# Titanium.Codec
A module for translating between primitive types and raw byte streams.
# Overview
The Codec
module can be used for encoding strings and numbers into Titanium.Buffer
objects, and decoding primitive types from buffers.
# Byte Order
Multi-byte data can be stored in two different byte orders: big-endian or little-endian. In big-endian byte order, the most significant or highest-value byte is stored first. For example, the 4-byte integer 0xFEDCBA98 is made up of the bytes 0xFE, 0xDC, 0xBA and 0x98, from most-significant to least-significant.
If we represent a buffer as an array of byte values, a big-endian encoding of 0xFEDCBA98 would look like this:
[ 0xFE, 0xDC, 0xBA, 0x98 ]
In little-endian order, the bytes would be stored in this order:
[ 0x98, 0xBA, 0xDC, 0xFE ]
For 8-bit character encodings, including ASCII, Latin-1 and UTF-8, byte order is not significant: the text is a sequence of individual bytes.
For UTF-16, text is represented as a sequence of 16-bit values. For example, a capital T in UTF-16 is 0x0054, and lowercase i is 0x0069. If we encode the string "Ti" with UTF-16 in big-endian byte order, we get:
[ 0x00, 0x54, 0x00, 0x69 ]
In UTF-16 with little-endian byte order, "Ti" is encoded as:
[ 0x54, 0x00, 0x69, 0x00 ]
Note that the bytes for each character are stored least-significant byte first, but the order of the characters is unchanged.
# Methods
# decodeNumber
Decodes a number from the source
buffer using the specified data type.
Takes a set of named parameters in the options
argument.
Bytes are read from the source
buffer and decoded as the specified data type, type
.
Two optional parameters can also be specified in options
:
-
If
position
is included in theoptions
dictionary, reads data from the buffer starting atposition
. -
If
byteOrder
is included in theoptions
dictionary, the specified byte order is used -- otherwise, the native byte order is assumed.
Throws an exception if source
is null, or position
is greater than source.length
Parameters
Name | Type | Description |
---|---|---|
options | DecodeNumberDict | Named parameters. |
Returns
Number decoded from source
.
- Type
- Number
# decodeString
Decodes the source buffer into a String using the supplied character set.
Takes a set of named parameters in the options
argument.
Bytes are read from the source
buffer and decoded as a string.
Several optional parameters can also be specified in options
:
-
If
position
is specified, bytes are read fromsource
starting atposition
. -
If
length
is specified, no more thanlength
bytes are read. -
If
charset
is specified, it determines the character encoding used to decode the string. Otherwise, UTF-8 is assumed.
Throws an exception if charset
is not a valid character set, source
is null,
or either position
, length
, or position
+length
is greater than source.length
.
Parameters
Name | Type | Description |
---|---|---|
options | DecodeStringDict | Named parameters. |
Returns
The decoded string
- Type
- String
# encodeNumber
Encodes a number and writes it to a buffer.
Takes a set of named parameters passed in the options
argument.
Encodes the number source
into dest
using the passed in data type
.
Two optional parameters can also be specified in options
:
-
If
position
is included in theoptions
dictionary, writes the encoded number to the buffer starting atposition
. -
If
byteOrder
is included in theoptions
dictionary, the specified byte order is used -- otherwise, the native byte order is assumed.
Parameters
Name | Type | Description |
---|---|---|
options | EncodeNumberDict | Named parameters. |
Returns
Position after the encoded number in dest
.
- Type
- Number
# encodeString
Encodes a string into a series of bytes in a buffer using the specified character set.
Takes a set of named parameters in the options
argument.
The string is read from source
and written to the buffer dest
.
Several optional parameters can also be specified in options
:
-
If
charset
is included, the string is encoded using the specified character encoding. -
If
destPosition
is included, data is written into the buffer starting at the specified position. -
If
sourcePosition
is included, a substring of the source string starting at the specified position is encoded. -
If
sourceLength
is included, at most the specified numer of characters are encoded.
Throws an exception if charset
is not a valid character set,
source
is null, or either sourcePosition
, sourceLength
, or
sourcePosition
+sourceLength
is greater than source.length
.
Parameters
Name | Type | Description |
---|---|---|
options | Dictionary<EncodeStringDict> | Named parameters. |
Returns
An index indicating the first byte in the destination buffer after the encoded string.
- Type
- Number
# getNativeByteOrder
Get the OS native byte order (either BIG_ENDIAN or LITTLE_ENDIAN).
See "Byte Order" in the main discussion of Titanium.Codec for more information.
Returns
OS native byte order.
- Type
- Number
# Constants
# BIG_ENDIAN
Big endian (network) byte order -- that is, the most significant byte first.
See "Byte Order" in the main discussion of Titanium.Codec for more information.
# CHARSET_ISO_LATIN_1
ISO 8859-1 (Latin-1) character encoding.
See also: ISO/IEC 8859-1 on Wikipedia.
# CHARSET_UTF16
UTF-16 character encoding with default byte order.
See also: UTF-16/UCS2 on Wikipedia.
# CHARSET_UTF16BE
UTF-16 character encoding with big endian byte order.
See also: UTF-16/UCS2 on Wikipedia.
# CHARSET_UTF16LE
UTF-16 character encoding with little endian byte order.
See also: UTF-16/UCS2 on Wikipedia.
# LITTLE_ENDIAN
Little endian byte order -- that is, the least significant byte first.
See "Byte Order" in the main discussion of Titanium.Codec for more information.