flash.utils

# ByteArray - AS3

Package | flash.utils
Class | public class ByteArray
Inheritance | ByteArray Object
Implements | IDataInput, IDataOutput
Subclasses | ByteArrayAsset

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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, deflate, and lzma compression and decompression are supported, as well as Action Message Format (AMF) object serialization.

A ByteArray object can share its backing memory among multiple worker instances by setting its `shareable` property to `true`.

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.

View the examples

More examples

Working with byte arrays
Reading and writing a ByteArray
ByteArray example: Reading a .zip file

Related API Elements

[] (array access)
Socket class
URLStream class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bytesAvailable : uint [read-only] The number of bytes of data available for reading from the current position in the byte array to the end of the array. | ByteArray
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | defaultObjectEncoding : uint [static] Denotes the default object encoding for the ByteArray class to use for a new ByteArray instance. | ByteArray
|  | endian : String Changes or reads the byte order for the data; either Endian.BIG_ENDIAN or Endian.LITTLE_ENDIAN. | ByteArray
|  | length : uint The length of the ByteArray object, in bytes. | ByteArray
|  | objectEncoding : uint Used to determine whether the ActionScript 3.0, ActionScript 2.0, or ActionScript 1.0 format should be used when writing to, or reading from, a ByteArray instance. | ByteArray
|  | position : uint Moves, or returns the current position, in bytes, of the file pointer into the ByteArray object. | ByteArray
|  | shareable : Boolean Specifies whether the underlying memory of the byte array is shareable. | ByteArray

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ByteArray() 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. | ByteArray
|  | atomicCompareAndSwapIntAt(byteIndex:int, expectedValue:int, newValue:int):int In a single atomic operation, compares an integer value in this byte array with another integer value and, if they match, swaps those bytes with another value. | ByteArray
|  | atomicCompareAndSwapLength(expectedLength:int, newLength:int):int In a single atomic operation, compares this byte array's length with a provided value and, if they match, changes the length of this byte array. | ByteArray
|  | clear():void Clears the contents of the byte array and resets the length and position properties to 0. | ByteArray
|  | compress(algorithm:String):void Compresses the byte array. | ByteArray
|  | deflate():void Compresses the byte array using the deflate compression algorithm. | ByteArray
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | inflate():void Decompresses the byte array using the deflate compression algorithm. | ByteArray
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | readBoolean():Boolean Reads a Boolean value from the byte stream. | ByteArray
|  | readByte():int Reads a signed byte from the byte stream. | ByteArray
|  | 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. | ByteArray
|  | readDouble():Number Reads an IEEE 754 double-precision (64-bit) floating-point number from the byte stream. | ByteArray
|  | readFloat():Number Reads an IEEE 754 single-precision (32-bit) floating-point number from the byte stream. | ByteArray
|  | readInt():int Reads a signed 32-bit integer from the byte stream. | ByteArray
|  | readMultiByte(length:uint, charSet:String):String Reads a multibyte string of specified length from the byte stream using the specified character set. | ByteArray
|  | readObject():* Reads an object from the byte array, encoded in AMF serialized format. | ByteArray
|  | readShort():int Reads a signed 16-bit integer from the byte stream. | ByteArray
|  | readUnsignedByte():uint Reads an unsigned byte from the byte stream. | ByteArray
|  | readUnsignedInt():uint Reads an unsigned 32-bit integer from the byte stream. | ByteArray
|  | readUnsignedShort():uint Reads an unsigned 16-bit integer from the byte stream. | ByteArray
|  | readUTF():String Reads a UTF-8 string from the byte stream. | ByteArray
|  | readUTFBytes(length:uint):String Reads a sequence of UTF-8 bytes specified by the length parameter from the byte stream and returns a string. | ByteArray
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toJSON(k:String):* Provides an overridable method for customizing the JSON encoding of values in an ByteArray object. | ByteArray
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Converts the byte array to a string. | ByteArray
|  | uncompress(algorithm:String):void Decompresses the byte array. | ByteArray
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | writeBoolean(value:Boolean):void Writes a Boolean value. | ByteArray
|  | writeByte(value:int):void Writes a byte to the byte stream. | ByteArray
|  | 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. | ByteArray
|  | writeDouble(value:Number):void Writes an IEEE 754 double-precision (64-bit) floating-point number to the byte stream. | ByteArray
|  | writeFloat(value:Number):void Writes an IEEE 754 single-precision (32-bit) floating-point number to the byte stream. | ByteArray
|  | writeInt(value:int):void Writes a 32-bit signed integer to the byte stream. | ByteArray
|  | writeMultiByte(value:String, charSet:String):void Writes a multibyte string to the byte stream using the specified character set. | ByteArray
|  | writeObject(object:*):void Writes an object into the byte array in AMF serialized format. | ByteArray
|  | writeShort(value:int):void Writes a 16-bit integer to the byte stream. | ByteArray
|  | writeUnsignedInt(value:uint):void Writes a 32-bit unsigned integer to the byte stream. | ByteArray
|  | writeUTF(value:String):void Writes a UTF-8 string to the byte stream. | ByteArray
|  | writeUTFBytes(value:String):void Writes a UTF-8 string to the byte stream. | ByteArray

Property Detail

### bytesAvailable

property

`bytesAvailable:uint` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Implementation
`public function get bytesAvailable():uint`

### defaultObjectEncoding

property

`defaultObjectEncoding:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Implementation
`public static function get defaultObjectEncoding():uint`
`public static function set defaultObjectEncoding(value:uint):void`

Related API Elements

ObjectEncoding class
flash.utils.ByteArray.objectEncoding

### endian

property

`endian:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Changes or reads the byte order for the data; either `Endian.BIG_ENDIAN` or `Endian.LITTLE_ENDIAN`. The default value is `BIG_ENDIAN`.

Implementation
`public function get endian():String`
`public function set endian(value:String):void`

Related API Elements

Endian class

### length

property

`length:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Implementation
`public function get length():uint`
`public function set length(value:uint):void`

### objectEncoding

property

`objectEncoding:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Used to determine whether the ActionScript 3.0, ActionScript 2.0, or ActionScript 1.0 format should be used when writing to, or reading from, a ByteArray instance. The value is a constant from the ObjectEncoding class.

Implementation
`public function get objectEncoding():uint`
`public function set objectEncoding(value:uint):void`

Related API Elements

ObjectEncoding class
flash.utils.ByteArray.defaultObjectEncoding

### position

property

`position:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Implementation
`public function get position():uint`
`public function set position(value:uint):void`

### shareable

property

`shareable:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Specifies whether the underlying memory of the byte array is shareable. For a shareable byte array, all ByteArray instances in all workers that reference the byte array use the same underlying system memory. The default value is `false`, indicating that the underlying memory is not shared among workers.

This property also affects what the runtime does with this byte array if it is passed to a worker using the `Worker.setSharedProperty()` method or the `MessageChannel.send()` method:

- Not shareable: If this property is `false`, when the byte array is passed to a worker the runtime creates a complete copy of the byte array, including allocating a new segment of memory in which to store the duplicate byte array's contents
- Shareable: If this property is `true`, when the byte array is passed to a worker the runtime uses the same underlying memory as the storage buffer for the contents of both the original ByteArray instance and the new ByteArray instance created for the second worker. In essence, both ByteArray instances contain a reference to the same underlying byte array.

The ability to access a shared byte array from multiple workers simultaneously can result in an undesirable situation where both workers are manipulating the byte array's underlying memory at the same time. You can use several mechanisms to control access to shared memory:

- the compare-and-swap mechanisms provided by the ByteArray class's `atomicCompareAndSwapIntAt()` and `atomicCompareAndSwapLength()` methods
- the specialized mechanisms provided by the Mutex and Condition classes (in the flash.concurrent package)

Setting this property to `true` only affects subsequent code that passes this byte array to a worker. Any copy of this byte array that has already been passed to a worker continues to exist as a separate copy.

If you set this property to `false` when it is previously `true`, the underlying memory for the byte array is immediately copied into a new segment of system memory. This ByteArray instance then uses the new underlying memory from that point on. Consequently, this byte array's underlying memory is no longer shared with other workers even if it was previously shared. If you subsequently pass this byte array to a worker, its underlying memory is copied as with any ByteArray object whose `shareable` property is `false`.

The default value is `false.`

Implementation
`public function get shareable():Boolean`
`public function set shareable(value:Boolean):void`

Related API Elements

Worker class
Worker.setSharedProperty() method
MessageChannel.send() method
atomicCompareAndSwapIntAt() method
atomicCompareAndSwapLength() method
Mutex class
Condition class
Constructor Detail

### ByteArray

()
Constructor

`public function ByteArray()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Method Detail

### atomicCompareAndSwapIntAt

()
method

`public function atomicCompareAndSwapIntAt(byteIndex:int, expectedValue:int, newValue:int):int`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

In a single atomic operation, compares an integer value in this byte array with another integer value and, if they match, swaps those bytes with another value.

This method is intended to be used with a byte array whose underlying memory is shared between multiple workers (the ByteArray instance's `shareable` property is `true`). It performs the following sequence of steps:

1. Reads an integer value from this byte array starting at the index (measured in bytes) specified in the `byteIndex` argument
2. Compares the actual value from this byte array to the value passed in the `expectedValue` argument
3. If the two values are equal, it writes the value in the `newValue` argument into the byte array at the location specified by the `byteIndex` parameter and returns the value that was previously contained in those bytes (the value read in step 1)
4. Otherwise, the contents of the byte array are not changed and the method returns the actual value read from the byte array

All these steps are performed in one atomic hardware transaction. This guarantees that no operations from other workers make changes to the contents of the byte array during the compare-and-swap operation.

Parameters

| `byteIndex:int` — the index position (in bytes) from which the integer to compare is read, and to which the `newValue` value is written if the comparison results in a match. This value must be a multiple of 4.
| `expectedValue:int` — the value that is expected to match the contents of the byte array at the specified index
| `newValue:int` — the new value that replaces the contents of the byte array at the specified index if the comparison results in a match

Returns

| `int` — the previous value at the specified location if the comparison results in a match, or the actual value from the byte array if the actual value and expected value don't match

Throws

| `ArgumentError` — if the `byteIndex` value is not a multiple of 4 or if it's negative

Related API Elements

ByteArray.shareable property
Worker class

### atomicCompareAndSwapLength

()
method

`public function atomicCompareAndSwapLength(expectedLength:int, newLength:int):int`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

In a single atomic operation, compares this byte array's length with a provided value and, if they match, changes the length of this byte array.

This method is intended to be used with a byte array whose underlying memory is shared between multiple workers (the ByteArray instance's `shareable` property is `true`). It does the following:

1. Reads the integer `length` property of the ByteArray instance
2. Compares the length to the value passed in the `expectedLength` argument
3. If the two values are equal, it changes the byte array's length to the value passed as the `newLength` parameter, either growing or shrinking the size of the byte array
4. Otherwise, the byte array is not changed

All these steps are performed in one atomic hardware transaction. This guarantees that no operations from other workers make changes to the contents of the byte array during the compare-and-resize operation.

Parameters

| `expectedLength:int` — the expected value of the ByteArray's `length` property. If the specified value and the actual value match, the byte array's length is changed.
| `newLength:int` — the new length value for the byte array if the comparison succeeds

Returns

| `int` — the previous `length` value of the ByteArray, regardless of whether or not it changed

Related API Elements

ByteArray.shareable property
Worker class

### clear

()
method

`public function clear():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4

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

()
method

`public function compress(algorithm:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Compresses the byte array. 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.

You specify a compression algorithm by passing a value (defined in the CompressionAlgorithm class) as the `algorithm` parameter. The supported algorithms include the following:

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

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

The lzma compression algorithm is described at http://www.7-zip.org/7z.html.

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(air.CompressionAlgorithm.DEFLATE)` on the original ByteArray. However, the result from `compress(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.

Parameters

| `algorithm:String` (default = `NaN`)`` — The compression algorithm to use when compressing. Valid values are defined as constants in the CompressionAlgorithm class. The default is to use zlib format. Calling `compress(CompressionAlgorithm.DEFLATE)` has the same effect as calling the `deflate()` method. Support for the lzma algorithm was added for Flash Player 11.3 and AIR 3.3. You must have those player versions, or later, to use lzma compression.

Related API Elements

uncompress()
flash.utils.CompressionAlgorithm

### deflate

()
method

`public function deflate():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4

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.

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.

Related API Elements

inflate()

### inflate

()
method

`public function inflate():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 10

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.

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.

Related API Elements

deflate()

### readBoolean

()
method

`public function readBoolean():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

| `Boolean` — Returns `true` if the byte is nonzero, `false` otherwise.

Throws

| `EOFError` — There is not sufficient data available to read.

### readByte

()
method

`public function readByte():int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Reads a signed byte from the byte stream.

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

Returns

| `int` — An integer between -128 and 127.

Throws

| `EOFError` — There is not sufficient data available to read.

### readBytes

()
method

`public function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:ByteArray` — The ByteArray object to read data into.
| `offset:uint` (default = `0`)`` — The offset (position) in `bytes` at which the read data should be written.
| `length:uint` (default = `0`)`` — 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.

More examples

Reading and writing a ByteArray

### readDouble

()
method

`public function readDouble():Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Returns

| `Number` — A double-precision (64-bit) floating-point number.

Throws

| `EOFError` — There is not sufficient data available to read.

### readFloat

()
method

`public function readFloat():Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Returns

| `Number` — A single-precision (32-bit) floating-point number.

Throws

| `EOFError` — There is not sufficient data available to read.

### readInt

()
method

`public function readInt():int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

Returns

| `int` — A 32-bit signed integer between -2147483648 and 2147483647.

Throws

| `EOFError` — There is not sufficient data available to read.

### readMultiByte

()
method

`public function readMultiByte(length:uint, charSet:String):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `length:uint` — The number of bytes from the byte stream to read.
| `charSet:String` — 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

| `String` — UTF-8 encoded string.

Throws

| `EOFError` — There is not sufficient data available to read.

### readObject

()
method

`public function readObject():*`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

flash.net.registerClassAlias()

### readShort

()
method

`public function readShort():int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

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

Returns

| `int` — A 16-bit signed integer between -32768 and 32767.

Throws

| `EOFError` — There is not sufficient data available to read.

### readUnsignedByte

()
method

`public function readUnsignedByte():uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Reads an unsigned byte from the byte stream.

The returned value is in the range 0 to 255.

Returns

| `uint` — A 32-bit unsigned integer between 0 and 255.

Throws

| `EOFError` — There is not sufficient data available to read.

### readUnsignedInt

()
method

`public function readUnsignedInt():uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

The returned value is in the range 0 to 4294967295.

Returns

| `uint` — A 32-bit unsigned integer between 0 and 4294967295.

Throws

| `EOFError` — There is not sufficient data available to read.

### readUnsignedShort

()
method

`public function readUnsignedShort():uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

The returned value is in the range 0 to 65535.

Returns

| `uint` — A 16-bit unsigned integer between 0 and 65535.

Throws

| `EOFError` — There is not sufficient data available to read.

### readUTF

()
method

`public function readUTF():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

| `String` — UTF-8 encoded string.

Throws

| `EOFError` — There is not sufficient data available to read.

Related API Elements

flash.utils.IDataInput.readUTF()

### readUTFBytes

()
method

`public function readUTFBytes(length:uint):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `length:uint` — An unsigned short indicating the length of the UTF-8 bytes.

Returns

| `String` — A string composed of the UTF-8 bytes of the specified length.

Throws

| `EOFError` — There is not sufficient data available to read.

### toJSON

()
method

`public function toJSON(k:String):*`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11, AIR 3, Flash Lite 4

Provides an overridable method for customizing the JSON encoding of values in an ByteArray object.

The `JSON.stringify()` method looks for a `toJSON()` method on each object that it traverses. If the `toJSON()` method is found, `JSON.stringify()` calls it for each value it encounters, passing in the key that is paired with the value.

ByteArray provides a default implementation of `toJSON()` that simply returns the name of the class. Because the content of any ByteArray requires interpretation, clients that wish to export ByteArray objects to JSON must provide their own implementation. You can do so by redefining the `toJSON()` method on the class prototype.

The `toJSON()` method can return a value of any type. If it returns an object, `stringify()` recurses into that object. If `toJSON()` returns a string, `stringify()` does not recurse and continues its traversal.

Parameters

| `k:String` — The key of a key/value pair that `JSON.stringify()` has encountered in its traversal of this object

Returns

| `*` — The class name string.

Learn more

Overview of the JSON API

Related API Elements

Object
Object.prototype

### toString

()
method

`public function toString():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

| `String` — The string representation of the byte array.

### uncompress

()
method

`public function uncompress(algorithm:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

The byte array must have been compressed using the same algorithm as the uncompress. You specify an uncompression algorithm by passing a value (defined in the CompressionAlgorithm class) as the `algorithm` parameter. The supported algorithms include the following:

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

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

The lzma compression algorithm is described at http://www.7-zip.org/7z.html.

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.

Parameters

| `algorithm:String` (default = `NaN`)`` — The compression algorithm to use when decompressing. This must be the same compression algorithm used to compress the data. Valid values are defined as constants in the CompressionAlgorithm class. The default is to use zlib format. Support for the lzma algorithm was added for Flash Player 11.3 and AIR 3.3. You must have those player versions, or later, to use lzma.

Throws

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

Related API Elements

compress()
flash.utils.CompressionAlgorithm

### writeBoolean

()
method

`public function writeBoolean(value:Boolean):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:Boolean` — 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.

### writeByte

()
method

`public function writeByte(value:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Writes a byte to the byte stream.

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

Parameters

| `value:int` — A 32-bit integer. The low 8 bits are written to the byte stream.

### writeBytes

()
method

`public function writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:ByteArray` — The ByteArray object.
| `offset:uint` (default = `0`)`` — A zero-based index indicating the position into the array to begin writing.
| `length:uint` (default = `0`)`` — An unsigned integer indicating how far into the buffer to write.

More examples

Reading and writing a ByteArray

### writeDouble

()
method

`public function writeDouble(value:Number):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:Number` — A double-precision (64-bit) floating-point number.

### writeFloat

()
method

`public function writeFloat(value:Number):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:Number` — A single-precision (32-bit) floating-point number.

### writeInt

()
method

`public function writeInt(value:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:int` — An integer to write to the byte stream.

### writeMultiByte

()
method

`public function writeMultiByte(value:String, charSet:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:String` — The string value to be written.
| `charSet:String` — 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 Supported Character Sets.

### writeObject

()
method

`public function writeObject(object:*):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `object:*` — The object to serialize.

Related API Elements

flash.net.registerClassAlias()

### writeShort

()
method

`public function writeShort(value:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:int` — 32-bit integer, whose low 16 bits are written to the byte stream.

### writeUnsignedInt

()
method

`public function writeUnsignedInt(value:uint):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Parameters

| `value:uint` — An unsigned integer to write to the byte stream.

### writeUTF

()
method

`public function writeUTF(value:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:String` — The string value to be written.

Throws

| `RangeError` — If the length is larger than 65535.

### writeUTFBytes

()
method

`public function writeUTFBytes(value:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:String` — The string value to be written.

Examples How to use this example
ByteArrayExample.as
The following example uses the class `ByteArrayExample` to write a Boolean and the double-precision floating-point representation of pi to a byte array. This is accomplished using the following steps:

1. Declare a new ByteArray object instance `byteArr`.
2. Write the byte-equivalent value of the Boolean `false` and then check the length and read it back.
3. Write the double-precision floating-point equivalent of the mathematical value of pi.
4. Read back each of the nine bytes written into the byte array.

Note: when `trace()` is called on a byte, it prints the decimal equivalent of the bytes stored in the byte array.

Notice how a code segment is added at the end to check for end of file errors to ensure that the byte stream is not read past its end.

Copy

    package {
        import flash.display.Sprite;
        import flash.utils.ByteArray;
        import flash.errors.EOFError;

        public class ByteArrayExample extends Sprite {
            public function ByteArrayExample() {
                var byteArr:ByteArray = new ByteArray();

                byteArr.writeBoolean(false);
                trace(byteArr.length);            // 1
                trace(byteArr[0]);            // 0

                byteArr.writeDouble(Math.PI);
                trace(byteArr.length);            // 9
                trace(byteArr[0]);            // 0
                trace(byteArr[1]);            // 64
                trace(byteArr[2]);            // 9
                trace(byteArr[3]);            // 33
                trace(byteArr[4]);            // 251
                trace(byteArr[5]);            // 84
                trace(byteArr[6]);            // 68
                trace(byteArr[7]);            // 45
                trace(byteArr[8]);            // 24

                byteArr.position = 0;

                try {
                    trace(byteArr.readBoolean() == false); // true
                }
                catch(e:EOFError) {
                    trace(e);           // EOFError: Error #2030: End of file was encountered.
                }

                try {
                    trace(byteArr.readDouble());        // 3.141592653589793
                }
                catch(e:EOFError) {
                    trace(e);           // EOFError: Error #2030: End of file was encountered.
                }

                try {
                    trace(byteArr.readDouble());
                }
                catch(e:EOFError) {
                    trace(e);            // EOFError: Error #2030: End of file was encountered.
                }
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00