class ByteArrayData
package openfl.utils
implements IDataInput, IDataOutput
import openfl.utils.ByteArray
Available on all platforms
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.
In addition, zlib compression and decompression are supported, as well as Action Message Format(AMF) 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 file in Adobe® AIR®.
Constructor
new ()
Creates a ByteArray instance representing a packed array of bytes, so that you can use the methods and properties in this class to optimize your data storage and stream.
Variables
read 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.
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.
Methods
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.
compress (?algorithm: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.
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.
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. |
|---|
readBoolean ():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.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
Returns true if the byte is nonzero,
false otherwise.
Reads a signed byte from the byte stream.
The returned value is in the range -128 to 127.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
An integer between -128 and 127.
readBytes (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 |
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. |
readDouble ():Float
Reads an IEEE 754 double-precision(64-bit) floating-point number from the byte stream.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A double-precision(64-bit) floating-point number.
Reads an IEEE 754 single-precision(32-bit) floating-point number from the byte stream.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A single-precision(32-bit) floating-point number.
Reads a signed 32-bit integer from the byte stream.
The returned value is in the range -2147483648 to 2147483647.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A 32-bit signed integer between -2147483648 and 2147483647.
readMultiByte (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
Note: If the value for the |
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
UTF-8 encoded string.
Available on Neko, Android, iOS, macOS, Linux, HTML5, Windows
Reads an object from the byte array, encoded in AMF serialized format.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
The deserialized object.
Available on Flash
Reads a signed 16-bit integer from the byte stream.
The returned value is in the range -32768 to 32767.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A 16-bit signed integer between -32768 and 32767.
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.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
UTF-8 encoded string.
readUTFBytes (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. |
|---|
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A string composed of the UTF-8 bytes of the specified length.
Reads an unsigned byte from the byte stream.
The returned value is in the range 0 to 255.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A 32-bit unsigned integer between 0 and 255.
Reads an unsigned 32-bit integer from the byte stream.
The returned value is in the range 0 to 4294967295.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A 32-bit unsigned integer between 0 and 4294967295.
Reads an unsigned 16-bit integer from the byte stream.
The returned value is in the range 0 to 65535.
Throws:
EOFError | There is not sufficient data available to read. |
|---|
Returns:
A 16-bit unsigned integer between 0 and 65535.
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.
uncompress (?algorithm: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. |
|---|
writeBoolean (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 |
|---|
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. |
|---|
writeBytes (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. |
writeDouble (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. |
|---|
writeFloat (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. |
|---|
Writes a 32-bit signed integer to the byte stream.
Parameters:
value | An integer to write to the byte stream. |
|---|
writeMultiByte (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 |
writeShort (value:Int):Void
Available on Neko, Android, iOS, macOS, Linux, HTML5, Windows
Writes an object into the byte array in AMF serialized format.
Parameters:
object | The object to serialize. |
|---|
writeShort (value:Int):Void
Available on Flash
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. |
|---|
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. |
|---|
writeUTFBytes (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. |
|---|
writeUnsignedInt (value:UInt):Void
Writes a 32-bit unsigned integer to the byte stream.
Parameters:
value | An unsigned integer to write to the byte stream. |
|---|
Static variables
staticdefaultObjectEncoding:UInt
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.AMF3.
When an object is written to or read from binary data, the
objectEncoding value is used to determine whether the
ActionScript 3.0, ActionScript2.0, or ActionScript 1.0 format should be
used. The value is a constant from the ObjectEncoding class.