The ByteArray class provides methods and properties to optimize reading, writing, and working with binary data.

Note: The ByteArray class is for advanced developers who need to access data on the byte level.

In-memory data is a packed array (the most compact representation for the data type) of bytes, but an instance of the ByteArray class can be manipulated with the standard [](array access) operators. It also can be read and written to as an in-memory file, using methods similar to those in the URLStream and Socket classes.

On the Flash and AIR targets, the ByteArray type is a real class, but on other platforms, ByteArray is a Haxe abstract over a hidden ByteArrayData type. To check if an object is a ByteArray at runtime, import the ByteArray type, then compare with ByteArrayData, such as Std.is (ba, ByteArrayData).

In addition, all platforms support zlib compression and decompression, as well as additional formats for object serialization.

Possible uses of the ByteArray class include the following:

  • Creating a custom protocol to connect to a server.
  • Writing your own URLEncoder/URLDecoder.
  • Writing your own AMF/Remoting packet.
  • Optimizing the size of your data by using data types.
  • Working with binary data loaded from a local file.
  • Supporting new binary file formats.

Static variables

staticread onlybytesAvailable:UInt

The number of bytes of data available for reading from the current position in the byte array to the end of the array.

Use the bytesAvailable property in conjunction with the read methods each time you access a ByteArray object to ensure that you are reading valid data.

staticdefaultEndian:Endian

Denotes the default endianness for the ByteArray class to use for a new ByteArray instance. When you create a new ByteArray instance, the endian value on that instance starts with the value of defaultEndian. The defaultEndian property is initialized to the default system endianness. This will most likely be Endian.LITTLE_ENDIAN on the majority platforms except for the Flash runtime.

On Flash and AIR targets, this property cannot be changed and will always be set to Endian.BIG_ENDIAN.

staticdefaultObjectEncoding:ObjectEncoding

Denotes the default object encoding for the ByteArray class to use for a new ByteArray instance. When you create a new ByteArray instance, the encoding on that instance starts with the value of defaultObjectEncoding. The defaultObjectEncoding property is initialized to ObjectEncoding.DEFAULT. This value varies between platforms.

When an object is written to or read from binary data, the objectEncoding value is used to determine whether the Haxe, JavaScript, ActionScript 3.0, ActionScript 2.0 or ActionScript 1.0 format should be used. The value is a constant from the ObjectEncoding class.

staticlength:UInt

The length of the ByteArray object, in bytes.

If the length is set to a value that is larger than the current length, the right side of the byte array is filled with zeros.

If the length is set to a value that is smaller than the current length, the byte array is truncated.

staticposition:UInt

Moves, or returns the current position, in bytes, of the file pointer into the ByteArray object. This is the point at which the next call to a read method starts reading or a write method starts writing.

Static methods

staticinlineclear(this:ByteArrayData):Void

Clears the contents of the byte array and resets the length and position properties to 0. Calling this method explicitly frees up the memory used by the ByteArray instance.

@:value({ algorithm : null })staticinlinecompress(this:ByteArrayData, ?algorithm:Null<CompressionAlgorithm>):Void

Compresses the byte array. The entire byte array is compressed. For content running in Adobe AIR, you can specify a compression algorithm by passing a value(defined in the CompressionAlgorithm class) as the algorithm parameter. Flash Player supports only the default algorithm, zlib.

After the call, the length property of the ByteArray is set to the new length. The position property is set to the end of the byte array.

The zlib compressed data format is described at [http://www.ietf.org/rfc/rfc1950.txt](http://www.ietf.org/rfc/rfc1950.txt).

The deflate compression algorithm is described at [http://www.ietf.org/rfc/rfc1951.txt](http://www.ietf.org/rfc/rfc1951.txt).

The deflate compression algorithm is used in several compression formats, such as zlib, gzip, some zip implementations, and others. When data is compressed using one of those compression formats, in addition to storing the compressed version of the original data, the compression format data(for example, the .zip file) includes metadata information. Some examples of the types of metadata included in various file formats are file name, file modification date/time, original file size, optional comments, checksum data, and more.

For example, when a ByteArray is compressed using the zlib algorithm, the resulting ByteArray is structured in a specific format. Certain bytes contain metadata about the compressed data, while other bytes contain the actual compressed version of the original ByteArray data. As defined by the zlib compressed data format specification, those bytes(that is, the portion containing the compressed version of the original data) are compressed using the deflate algorithm. Consequently those bytes are identical to the result of calling compress(<ph outputclass="javascript">air.CompressionAlgorithm.DEFLATE) on the original ByteArray. However, the result from compress(<ph outputclass="javascript">air.CompressionAlgorithm.ZLIB) includes the extra metadata, while the compress(CompressionAlgorithm.DEFLATE) result includes only the compressed version of the original ByteArray data and nothing else.

In order to use the deflate format to compress a ByteArray instance's data in a specific format such as gzip or zip, you cannot simply call compress(CompressionAlgorithm.DEFLATE). You must create a ByteArray structured according to the compression format's specification, including the appropriate metadata as well as the compressed data obtained using the deflate format. Likewise, in order to decode data compressed in a format such as gzip or zip, you can't simply call uncompress(CompressionAlgorithm.DEFLATE) on that data. First, you must separate the metadata from the compressed data, and you can then use the deflate format to decompress the compressed data.

staticinlinedeflate(this:ByteArrayData):Void

Compresses the byte array using the deflate compression algorithm. The entire byte array is compressed.

After the call, the length property of the ByteArray is set to the new length. The position property is set to the end of the byte array.

The deflate compression algorithm is described at [http://www.ietf.org/rfc/rfc1951.txt](http://www.ietf.org/rfc/rfc1951.txt).

In order to use the deflate format to compress a ByteArray instance's data in a specific format such as gzip or zip, you cannot simply call deflate(). You must create a ByteArray structured according to the compression format's specification, including the appropriate metadata as well as the compressed data obtained using the deflate format. Likewise, in order to decode data compressed in a format such as gzip or zip, you can't simply call inflate() on that data. First, you must separate the metadata from the compressed data, and you can then use the deflate format to decompress the compressed data.

@:fromstaticfromArrayBuffer(buffer:ArrayBuffer):ByteArray

Converts an ArrayBuffer into a ByteArray.

Parameters:

buffer

An ArrayBuffer instance

Returns:

A new ByteArray

@:fromstaticfromBytes(bytes:Bytes):ByteArray

Converts a Bytes object into a ByteArray.

Parameters:

buffer

A Bytes instance

Returns:

A new ByteArray

staticfromFile(path:String):ByteArray

Creates a new ByteArray from a file path synchronously. This means that the ByteArray will be returned immediately (if supported).

HTML5 and Flash do not support loading files synchronously, so these targets always return null.

In order to load files from a remote web address, use the loadFromFile method, which supports asynchronous loading.

Parameters:

path

A local file path

Returns:

A new ByteArray if successful, or null if unsuccessful

staticinlineinflate(this:ByteArrayData):Void

Decompresses the byte array using the deflate compression algorithm. The byte array must have been compressed using the same algorithm.

After the call, the length property of the ByteArray is set to the new length. The position property is set to 0.

The deflate compression algorithm is described at [http://www.ietf.org/rfc/rfc1951.txt](http://www.ietf.org/rfc/rfc1951.txt).

In order to decode data compressed in a format that uses the deflate compression algorithm, such as data in gzip or zip format, it will not work to simply call inflate() on a ByteArray containing the compression formation data. First, you must separate the metadata that is included as part of the compressed data format from the actual compressed data. For more information, see the compress() method description.

Throws:

IOError

The data is not valid compressed data; it was not compressed with the same compression algorithm used to compress.

staticloadFromBytes(bytes:Bytes):Future<ByteArray>

Creates a new ByteArray from haxe.io.Bytes. Progress, completion and error callbacks will be dispatched using callbacks attached to a returned Future object.

Parameters:

bytes

A haxe.io.Bytes instance

Returns:

A Future ByteArray

staticloadFromFile(path:String):Future<ByteArray>

Creates a new ByteArray from a file path or web address asynchronously. The file load will occur in the background. Progress, completion and error callbacks will be dispatched in the current thread using callbacks attached to a returned Future object.

Parameters:

path

A local file path or web address

Returns:

A Future ByteArray

staticinlinereadBoolean(this:ByteArrayData):Bool

Reads a Boolean value from the byte stream. A single byte is read, and true is returned if the byte is nonzero, false otherwise.

Returns:

Returns true if the byte is nonzero, false otherwise.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadByte(this:ByteArrayData):Int

Reads a signed byte from the byte stream.

The returned value is in the range -128 to 127.

Returns:

An integer between -128 and 127.

Throws:

EOFError

There is not sufficient data available to read.

@:value({ length : 0, offset : 0 })staticinlinereadBytes(this:ByteArrayData, bytes:ByteArray, offset:UInt = 0, length:UInt = 0):Void

Reads the number of data bytes, specified by the length parameter, from the byte stream. The bytes are read into the ByteArray object specified by the bytes parameter, and the bytes are written into the destination ByteArray starting at the position specified by offset.

Parameters:

bytes

The ByteArray object to read data into.

offset

The offset(position) in bytes at which the read data should be written.

length

The number of bytes to read. The default value of 0 causes all available data to be read.

Throws:

EOFError

There is not sufficient data available to read.

RangeError

The value of the supplied offset and length, combined, is greater than the maximum for a uint.

staticinlinereadDouble(this:ByteArrayData):Float

Reads an IEEE 754 double-precision(64-bit) floating-point number from the byte stream.

Returns:

A double-precision(64-bit) floating-point number.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadFloat(this:ByteArrayData):Float

Reads an IEEE 754 single-precision(32-bit) floating-point number from the byte stream.

Returns:

A single-precision(32-bit) floating-point number.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadInt(this:ByteArrayData):Int

Reads a signed 32-bit integer from the byte stream.

The returned value is in the range -2147483648 to 2147483647.

Returns:

A 32-bit signed integer between -2147483648 and 2147483647.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadMultiByte(this:ByteArrayData, length:UInt, charSet:String):String

Reads a multibyte string of specified length from the byte stream using the specified character set.

Parameters:

length

The number of bytes from the byte stream to read.

charSet

The string denoting the character set to use to interpret the bytes. Possible character set strings include "shift-jis", "cn-gb", "iso-8859-1", and others. For a complete list, see Supported Character Sets.

Note: If the value for the charSet parameter is not recognized by the current system, the application uses the system's default code page as the character set. For example, a value for the charSet parameter, as in myTest.readMultiByte(22, "iso-8859-01") that uses 01 instead of 1 might work on your development system, but not on another system. On the other system, the application will use the system's default code page.

Returns:

UTF-8 encoded string.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadObject(this:ByteArrayData):Dynamic

Reads an object from the byte array, encoded in AMF serialized format.

Returns:

The deserialized object.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadShort(this:ByteArrayData):Int

Reads a signed 16-bit integer from the byte stream.

The returned value is in the range -32768 to 32767.

Returns:

A 16-bit signed integer between -32768 and 32767.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadUTF(this:ByteArrayData):String

Reads a UTF-8 string from the byte stream. The string is assumed to be prefixed with an unsigned short indicating the length in bytes.

Returns:

UTF-8 encoded string.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadUTFBytes(this:ByteArrayData, length:UInt):String

Reads a sequence of UTF-8 bytes specified by the length parameter from the byte stream and returns a string.

Parameters:

length

An unsigned short indicating the length of the UTF-8 bytes.

Returns:

A string composed of the UTF-8 bytes of the specified length.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadUnsignedByte(this:ByteArrayData):UInt

Reads an unsigned byte from the byte stream.

The returned value is in the range 0 to 255.

Returns:

A 32-bit unsigned integer between 0 and 255.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadUnsignedInt(this:ByteArrayData):UInt

Reads an unsigned 32-bit integer from the byte stream.

The returned value is in the range 0 to 4294967295.

Returns:

A 32-bit unsigned integer between 0 and 4294967295.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinereadUnsignedShort(this:ByteArrayData):UInt

Reads an unsigned 16-bit integer from the byte stream.

The returned value is in the range 0 to 65535.

Returns:

A 16-bit unsigned integer between 0 and 65535.

Throws:

EOFError

There is not sufficient data available to read.

staticinlinetoString(this:ByteArrayData):String

Converts the byte array to a string. If the data in the array begins with a Unicode byte order mark, the application will honor that mark when converting to a string. If System.useCodePage is set to true, the application will treat the data in the array as being in the current system code page when converting.

Returns:

The string representation of the byte array.

@:value({ algorithm : null })staticinlineuncompress(this:ByteArrayData, ?algorithm:Null<CompressionAlgorithm>):Void

Decompresses the byte array. For content running in Adobe AIR, you can specify a compression algorithm by passing a value(defined in the CompressionAlgorithm class) as the algorithm parameter. The byte array must have been compressed using the same algorithm. Flash Player supports only the default algorithm, zlib.

After the call, the length property of the ByteArray is set to the new length. The position property is set to 0.

The zlib compressed data format is described at [http://www.ietf.org/rfc/rfc1950.txt](http://www.ietf.org/rfc/rfc1950.txt).

The deflate compression algorithm is described at [http://www.ietf.org/rfc/rfc1951.txt](http://www.ietf.org/rfc/rfc1951.txt).

In order to decode data compressed in a format that uses the deflate compression algorithm, such as data in gzip or zip format, it will not work to call uncompress(CompressionAlgorithm.DEFLATE) on a ByteArray containing the compression formation data. First, you must separate the metadata that is included as part of the compressed data format from the actual compressed data. For more information, see the compress() method description.

Throws:

IOError

The data is not valid compressed data; it was not compressed with the same compression algorithm used to compress.

staticinlinewriteBoolean(this:ByteArrayData, value:Bool):Void

Writes a Boolean value. A single byte is written according to the value parameter, either 1 if true or 0 if false.

Parameters:

value

A Boolean value determining which byte is written. If the parameter is true, the method writes a 1; if false, the method writes a 0.

staticinlinewriteByte(this:ByteArrayData, value:Int):Void

Writes a byte to the byte stream.

The low 8 bits of the parameter are used. The high 24 bits are ignored.

Parameters:

value

A 32-bit integer. The low 8 bits are written to the byte stream.

@:value({ length : 0, offset : 0 })staticinlinewriteBytes(this:ByteArrayData, bytes:ByteArray, offset:UInt = 0, length:UInt = 0):Void

Writes a sequence of length bytes from the specified byte array, bytes, starting offset(zero-based index) bytes into the byte stream.

If the length parameter is omitted, the default length of 0 is used; the method writes the entire buffer starting at offset. If the offset parameter is also omitted, the entire buffer is written.

If offset or length is out of range, they are clamped to the beginning and end of the bytes array.

Parameters:

bytes

The ByteArray object.

offset

A zero-based index indicating the position into the array to begin writing.

length

An unsigned integer indicating how far into the buffer to write.

staticinlinewriteDouble(this:ByteArrayData, value:Float):Void

Writes an IEEE 754 double-precision(64-bit) floating-point number to the byte stream.

Parameters:

value

A double-precision(64-bit) floating-point number.

staticinlinewriteFloat(this:ByteArrayData, value:Float):Void

Writes an IEEE 754 single-precision(32-bit) floating-point number to the byte stream.

Parameters:

value

A single-precision(32-bit) floating-point number.

staticinlinewriteInt(this:ByteArrayData, value:Int):Void

Writes a 32-bit signed integer to the byte stream.

Parameters:

value

An integer to write to the byte stream.

staticinlinewriteMultiByte(this:ByteArrayData, value:String, charSet:String):Void

Writes a multibyte string to the byte stream using the specified character set.

Parameters:

value

The string value to be written.

charSet

The string denoting the character set to use. Possible character set strings include "shift-jis", "cn-gb", "iso-8859-1", and others. For a complete list, see <a href="../../charset-codes.html">Supported Character Sets.

staticinlinewriteObject(this:ByteArrayData, object:Dynamic):Void

Writes an object into the byte array in AMF serialized format.

Parameters:

object

The object to serialize.

staticinlinewriteShort(this:ByteArrayData, value:Int):Void

Writes a 16-bit integer to the byte stream. The low 16 bits of the parameter are used. The high 16 bits are ignored.

Parameters:

value

32-bit integer, whose low 16 bits are written to the byte stream.

staticinlinewriteUTF(this:ByteArrayData, value:String):Void

Writes a UTF-8 string to the byte stream. The length of the UTF-8 string in bytes is written first, as a 16-bit integer, followed by the bytes representing the characters of the string.

Parameters:

value

The string value to be written.

Throws:

RangeError

If the length is larger than 65535.

staticinlinewriteUTFBytes(this:ByteArrayData, value:String):Void

Writes a UTF-8 string to the byte stream. Similar to the writeUTF() method, but writeUTFBytes() does not prefix the string with a 16-bit length word.

Parameters:

value

The string value to be written.

staticinlinewriteUnsignedInt(this:ByteArrayData, value:UInt):Void

Writes a 32-bit unsigned integer to the byte stream.

Parameters:

value

An unsigned integer to write to the byte stream.