# Titanium.Codec

> A module for translating between primitive types and raw byte streams.

- Source: https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.Codec
- Titanium SDK version: 13.0.1
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 1.7
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy

The `Codec` module can be used for encoding strings and numbers into [Buffer](https://titaniumsdk.com/docs/sdk/Titanium.Buffer.md)
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:

``` js
[ 0xFE, 0xDC, 0xBA, 0x98 ]
```

In little-endian order, the bytes would be stored in this order:

``` js
[ 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:

``` js
[ 0x00, 0x54, 0x00, 0x69 ]
```

In UTF-16 with little-endian byte order, "Ti" is encoded as:

``` js
[ 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.

## Properties

### BIG_ENDIAN

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Big endian (network) byte order -- that is, the most significant byte first.

See "Byte Order" in the main discussion of [Titanium.Codec](https://titaniumsdk.com/docs/sdk/Titanium.Codec.md) for more information.

### CHARSET_ASCII

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"ascii"`

ASCII character encoding..

See also: [ASCII](http://en.wikipedia.org/wiki/ASCII) on Wikipedia.

### CHARSET_ISO_LATIN_1

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"latin1"`

ISO 8859-1 (Latin-1) character encoding.

See also: [ISO/IEC 8859-1](http://en.wikipedia.org/wiki/ISO/IEC_8859-1) on Wikipedia.

### CHARSET_UTF16

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"utf16"`

UTF-16 character encoding with default byte order.

See also: [UTF-16/UCS2](http://en.wikipedia.org/wiki/UTF-16/UCS-2) on Wikipedia.

### CHARSET_UTF16BE

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"utf16be"`

UTF-16 character encoding with big endian byte order.

See also: [UTF-16/UCS2](http://en.wikipedia.org/wiki/UTF-16/UCS-2) on Wikipedia.

### CHARSET_UTF16LE

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"utf16le"`

UTF-16 character encoding with little endian byte order.

See also: [UTF-16/UCS2](http://en.wikipedia.org/wiki/UTF-16/UCS-2) on Wikipedia.

### CHARSET_UTF8

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"utf8"`

UTF-8 character encoding.

See also: [UTF-8](http://en.wikipedia.org/wiki/UTF-8) on Wikipedia.

### LITTLE_ENDIAN

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Little endian byte order -- that is, the least significant byte first.

See "Byte Order" in the main discussion of [Titanium.Codec](https://titaniumsdk.com/docs/sdk/Titanium.Codec.md) for more information.

### TYPE_BYTE

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"byte"`

8-bit integer encoding type.

### TYPE_DOUBLE

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"double"`

64-bit double precision floating-point type.

### TYPE_FLOAT

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"float"`

32-bit single precision floating-point type.

### TYPE_INT

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"int"`

32-bit integer encoding type.

### TYPE_LONG

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"long"`

64-bit integer encoding type.

### TYPE_SHORT

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
- Value: `"short"`

16-bit integer encoding type.

## Methods

### decodeNumber

- Platforms: Android, iPhone, iPad, macOS

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 the `options` dictionary, reads data from the
    buffer starting at `position`.

*   If `byteOrder` is included in the `options` 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:

- `options` (DecodeNumberDict): Named parameters.

Returns: Number - Number decoded from `source`.

Example: Decode a Double-Precision Floating Point Number

This sample decodes an 8-byte double-precision floating point number using the
OS byte order.

``` js
var buffer = // a buffer containing (at least) one 8-byte floating-point number
var value = Ti.Codec.decodeNumber({
    source: buffer,
    type: Ti.Codec.TYPE_DOUBLE
});
```

Example: Decode an Integer Specifying Start Position and Byte Order

This sample decodes a 4-byte integer starting at index position 10 in the
buffer, using big endian encoding.

``` js
var buffer = // a buffer containing a 4-byte integer at position 10.
var value = Ti.Codec.decodeNumber({
      source: buffer,
      position: 10,
      type: Ti.Codec.TYPE_INT,
      byteOrder: Ti.Codec.BIG_ENDIAN
});
```

### decodeString

- Platforms: Android, iPhone, iPad, macOS

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 from `source` starting at `position`.

*   If `length` is specified, no more than `length` 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:

- `options` (DecodeStringDict): Named parameters.

Returns: String - The decoded string

Example: Decode a String

This sample decodes a string using the default character encoding.

``` js
var buffer = // a buffer containing an encoded string
var string = Ti.Codec.decodeString({ source: buffer });
```

Example: Decode a String with a Specified Character Encoding

This sample decodes a string using the UTF-16 character encoding.

``` js
var buffer = // a buffer containing a UTF-16 encoded string
var string = Ti.Codec.decodeString({
  source: buffer,
  charset: Ti.Codec.CHARSET_UTF16
});
```

### encodeNumber

- Platforms: Android, iPhone, iPad, macOS

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 the `options` dictionary, writes the encoded number
    to the buffer starting at `position`.

*   If `byteOrder` is included in the `options` dictionary, the specified byte order
    is used -- otherwise, the native byte order is assumed.

Parameters:

- `options` (EncodeNumberDict): Named parameters.

Returns: Number - Position _after_ the encoded number in `dest`.

Example: Encode a Double-Precision Floating Point Value

This example encodes a double-precision floating point value in 8 bytes using the OS byte
order.

``` js
var buffer = Ti.createBuffer({ length: 8 });
Ti.Codec.encodeNumber({
  source: 1.23456789,
  dest: buffer,
  type: Ti.Codec.TYPE_DOUBLE
});
```

Example: Encode an Integer Specifying Start Position and Byte Order

This example encodes a 4-byte integer using big endian encoding, and
writes it to the supplied buffer starting at index position 10.

``` js
var buffer = Ti.createBuffer({ length: 100 });
Ti.Codec.encodeNumber({
    source: 0x3456789a,
    dest: buffer,
    position: 10,
    type: Ti.Codec.TYPE_INT,
    byteOrder: Ti.Codec.BIG_ENDIAN
});
```

### encodeString

- Platforms: Android, iPhone, iPad, macOS

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:

- `options` (Dictionary<EncodeStringDict>): Named parameters.

Returns: Number - An index indicating the first byte in the destination buffer _after_ the
encoded string.

Example: Encode String with Default Character Encoding

This sample encodes a string using the default character encoding (UTF-8), then trims the
buffer to the length of the encoded string.

``` js
var buffer = Ti.createBuffer({ length: 1024 });
var length = Ti.Codec.encodeString({
    source: "hello world",
    dest: buffer
});
buffer.length = length;
```

Example: Encode Substring with Specified Character Encoding

This sample encodes the first 10 characters of a string using UTF-16 character encoding.

``` js
// (10 * 2) + BOM = 22
var buffer = Ti.createBuffer({ length: 22 });
Ti.Codec.encodeString({
    source: "jack jumped over the candle stick",
    sourceLength: 10,
    dest: buffer,
    charset: Ti.Codec.CHARSET_UTF16
});
```

### getNativeByteOrder

- Platforms: Android, iPhone, iPad, macOS

Get the OS native byte order (either [Titanium.Codec.BIG_ENDIAN](https://titaniumsdk.com/docs/sdk/Titanium.Codec.md#BIG_ENDIAN) or
[Titanium.Codec.LITTLE_ENDIAN](https://titaniumsdk.com/docs/sdk/Titanium.Codec.md#LITTLE_ENDIAN)).

See "Byte Order" in the main discussion of [Titanium.Codec](https://titaniumsdk.com/docs/sdk/Titanium.Codec.md) for more information.

Returns: Number - OS native byte order.

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.