| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
The ByteArray class provides methods and properties to optimize reading, writing,
and working with binary data.
Note: The ByteArray class is for advanced ActionScript 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 ActionScript [] (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.
View the examples
bytesAvailable:uint [read-only]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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():uintdefaultObjectEncoding:uint [read-write]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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 function set defaultObjectEncoding(value:uint):voidSee also
endian:String [read-write]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Changes or reads the byte order for the data; either "bigEndian" or "littleEndian". The values are constants from the Endian class.
Implementation public function get endian():String public function set endian(value:String):voidSee also
length:uint [read-write]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
The length of the ByteArray object, in bytes.
If the length is set to a value that is larger than the
current length, Flash Player fills the right side with zeros.
If the length is set to a value that is smaller than the
current length, the array is truncated.
Implementation public function get length():uint public function set length(value:uint):voidobjectEncoding:uint [read-write]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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):voidSee also
position:uint [read-write]
| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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):voidpublic function ByteArray()| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
flash10 function clear():void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 10 |
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.
public function compress():void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Compresses the byte array using the zlib compressed data format.
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 zlib compressed data format is described at
http://www.ietf.org/rfc/rfc1950.txt.
See also
flash10 function deflate():void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 10 |
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.
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 compress()
method, the ByteArray is compressed using the zlib compressed data format.
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
deflate() on the original ByteArray. However,
the compress() result includes the extra metadata, while the
deflate() result includes only the compressed version of the original
ByteArray data and nothing else.
Consequently, in order to use deflate() to compress a ByteArray instance's
data in a specific format such as gzip or zip, you can't just call the
instance's deflate() method. 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() method. Likewise, in order to decode data compressed in a format such
as gzip or zip, you can't simply use the inflate() method on that data. First
you must separate the metadata from the compressed data, and you can then use the
inflate() method to decompress the compressed data.
See also
flash10 function inflate():void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 10 |
Decompresses the byte array. The byte array must have been previously
compressed with the DEFLATE compression algorithm, as is used by the
deflate() method.
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 call the inflate() method 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 deflate() method description.
Throws | IOError — The data is not valid compressed data; it was not compressed with the
DEFLATE compression algorithm.
|
See also
public function readBoolean():Boolean| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readByte():int| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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)bytes at which the read data should be written.
|
| |
| length:uint (default = 0) |
Throws | EOFError — There is not sufficient data available
to read.
|
public function readDouble():Number| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readFloat():Number| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readInt():int| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readMultiByte(length:uint, charSet:String):String| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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, then Flash Player 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 machine, but not on another machine. On the other machine, Flash Player will use the system's default code page.
|
Returns | String — UTF-8 encoded string.
|
Throws | EOFError — There is not sufficient data available
to read.
|
public function readObject():*| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readShort():int| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readUnsignedByte():uint| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readUnsignedInt():uint| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readUnsignedShort():uint| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function readUTF():String| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
See also
public function readUTFBytes(length:uint):String| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function toString():String| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Converts the byte array to a string.
If the data in the array begins with a Unicode byte order mark, Flash will honor that mark
when converting to a string. If System.useCodePage is set to true, the player 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.
|
public function uncompress():void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Decompresses the byte array. The byte array
must have been compressed using the
zlib compressed data format.
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.
See also
public function writeBoolean(value:Boolean):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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,
Flash Player writes a 1; if false, Flash Player writes a 0.
|
public function writeByte(value:int):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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; Flash Player 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) |
| |
| length:uint (default = 0) |
public function writeDouble(value:Number):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function writeFloat(value:Number):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function writeInt(value:int):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Writes a 32-bit signed integer to the byte stream.
Parameters
| value:int — An integer to write to the byte stream.
|
public function writeMultiByte(value:String, charSet:String):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function writeObject(object:*):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Writes an object into the byte array in AMF
serialized format.
Parameters
| object:* — The object to serialize.
|
public function writeShort(value:int):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
public function writeUnsignedInt(value:uint):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
Writes a 32-bit unsigned integer to the byte stream.
Parameters
| value:uint — An unsigned integer to write to the byte stream.
|
public function writeUTF(value:String):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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 public function writeUTFBytes(value:String):void| Language Version : | ActionScript 3.0 |
| Player Version : | Flash Player 9 |
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.
|
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:
- Declare a new ByteArray object instance
byteArr. - Write the byte-equivalent value of the Boolean
false and then check the length and
read it back. - Write the double-precision floating-point equivalent of the mathematical value of pi.
- 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.
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.
}
}
}
}
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00 
Object
Hide Inherited Public Properties
Show Inherited Public Properties