ByteArray  - AS3

可从字节数组的当前位置到数组末尾读取的数据的字节数。

每次访问 ByteArray 对象时，将 bytesAvailable 属性与读取方法结合使用，以确保读取有效的数据。

表示用于新 ByteArray 实例的 ByteArray 类的默认对象编码。在创建新的 ByteArray 实例时，该实例上的编码以 defaultObjectEncoding 的值开头。defaultObjectEncoding 属性被初始化为 ObjectEncoding.AMF3。

将对象写入二进制数据或从中读取对象时，将使用 objectEncoding 值来确定应使用 ActionScript 3.0、ActionScript2.0 还是 ActionScript 1.0 格式。该值为 ObjectEncoding 类中的常数。

相关 API 元素

更改或读取数据的字节顺序；Endian.BIG_ENDIAN 或 Endian.LITTLE_ENDIAN。默认值为 BIG_ENDIAN。

相关 API 元素

ByteArray 对象的长度（以字节为单位）。

如果将长度设置为大于当前长度的值，则用零填充字节数组的右侧。

如果将长度设置为小于当前长度的值，将会截断该字节数组。

用于确定在写入或读取 ByteArray 实例时应使用 ActionScript 3.0、ActionScript 2.0 还是 ActionScript 1.0 格式。该值为 ObjectEncoding 类中的常数。

相关 API 元素

将文件指针的当前位置（以字节为单位）移动或返回到 ByteArray 对象中。下一次调用读取方法时将在此位置开始读取，或者下一次调用写入方法时将在此位置开始写入。

指定字节数组的底层内存是否可共享。对于可共享字节数组，引用该字节数组的所有 worker 中的所有 ByteArray 实例都使用相同的底层内存。默认值是 false，指示不在 worker 之间共享底层内存。

此属性还对当使用 Worker.setSharedProperty() 方法或 MessageChannel.send() 方法将此字节数组传递给某个 worker 时，运行时如何处理此字节数组产生影响：

• 不可共享：如果此属性为 false，则当字节数组传递给了某个 worker 时，运行时将创建该字节数组的一个完整副本，包括分配用来存储副本字节数组的内容的内存片段
• 可共享：如果此属性设置为 true，则当字节数组传递给了某个 worker 时，运行时将使用同一底层内存作为原始 ByteArray 实例和为第二个 worker 创建的新 ByteArray 实例的存储缓冲区。实际上，这两个 ByteArray 实例包含对同一底层字节数组的引用。

能够从多个 worker 同时访问共享字节数组的能力可能会导致我们不愿意看到的情况，即两个 worker 同时对字节数组的底层内存进行操控。您可以使用多种机制来控制对共享内存的访问：

• ByteArray 类的 atomicCompareAndSwapIntAt() 和 atomicCompareAndSwapLength() 方法提供的比较并交换机制
• Mutex 和 Condition 类（在 flash.concurrent 软件包中）提供的专用机制

将此属性设置为 true 仅会影响将此字节数组传递给 worker 的后续代码。已传递给 worker 的任何此字节数组的副本将仍然作为单独的副本存在。

如果在此属性以前为 true 时您将其设置为了 false，则字节数组的底层内存会被立即复制到系统内存的一个新片段中。然后，此 ByteArray 实例从该时间点开始将使用新的底层内存。因此，此字节数组的底层内存将不再与其他 worker 共享，即使它以前是共享的。如果您随后将此字节数组传递给一个 worker，则与使用其 shareable 属性为 false 的任何 ByteArray 对象时一样，将复制其底层内存。

默认值为 false。

相关 API 元素

创建一个表示填充的字节数组的 ByteArray 实例，以便使用此类中的方法和属性来优化数据存储和数据流。

在单一的原子操作中，将此字节数组中的一个整数值与另一个整数值进行比较，如果它们匹配，则将这些字节与另一个值进行交换。

此方法设计用来与其底层内存供多个 worker 共享（ByteArray 实例的 shareable 属性为 true）的字节数组一起使用。它执行以下步骤序列：

1. 从在 byteIndex 参数中指定的索引（以字节为度量单位）处开始从此字节数组中读取一个整数值
2. 将来自此字节数组的实际值与在 expectedValue 参数中传递的值进行比较
3. 如果两个值相等，则它会将 newValue 参数中的值写入到字节数组中由 byteIndex 参数指定的位置，并返回那些字节中之前包含的值（在步骤 1 中读取的值）
4. 否则，字节数组的内容不会更改并且该方法将返回从字节数组读取的实际值

所有这些步骤都是在一个原子性硬件事务中执行的。这保证了在比较并交换操作期间没有来自其他 worker 的操作会对字节数组的内容进行更改。

参数

相关 API 元素

在单一的原子操作中，将此字节数组的长度与所提供的一个值进行比较，如果它们匹配，则更改此字节数组的长度。

此方法设计用来与其底层内存供多个 worker 共享（ByteArray 实例的 shareable 属性为 true）的字节数组一起使用。它完成下列操作：

1. 读取 ByteArray 实例的整数 length 属性
2. 将 length 与在 expectedLength 参数中传递的值进行比较
3. 如果两个值相等，它会将字节数组的长度更改为作为 newLength 参数传递的值，这将使字节数组的大小增大或缩小
4. 否则，不会更改字节数组

所有这些步骤都是在一个原子性硬件事务中执行的。这保证了在比较并调整大小操作期间没有来自其他 worker 的操作会对字节数组的内容进行更改。

参数

相关 API 元素

清除字节数组的内容，并将 length 和 position 属性重置为 0。明确调用此方法将释放 ByteArray 实例占用的内存。

压缩字节数组。将压缩整个字节数组。在调用后，ByteArray 的 length 属性将设置为新长度。position 属性将设置为字节数组末尾。

通过传递一个值（在 CompressionAlgorithm 类中定义）作为 algorithm 参数，可指定压缩算法。支持的算法有：

http://www.ietf.org/rfc/rfc1950.txt 中介绍了 zlib 压缩的数据格式。

http://www.ietf.org/rfc/rfc1951.txt 中介绍了 deflate 压缩算法。

lzma 压缩算法在 http://www.7-zip.org/7z.html 中有介绍。

这种 deflate 压缩算法用于多种压缩格式，如 zlib、gzip、一些 zip 实现等。在使用这些压缩格式之一压缩数据时，除了存储原始数据的压缩版本之外，压缩格式数据（例如 .zip 文件）还包括元数据信息。举例来说，各种文件格式中包括的元数据的类型有文件名、文件修改日期/时间、原始文件大小、可选的注释、校验和数据等。

例如，在使用 zlib 算法压缩 ByteArray 时，将以特定的格式构建生成的 ByteArray。一些字节包含有关所压缩数据的元数据，而另一些字节包含原始 ByteArray 数据的实际压缩版本。根据 zlib 压缩数据格式规范的定义，这些字节（即包含原始数据的压缩版本的部分）使用 deflate 算法进行压缩。因此，这些字节与对原始 ByteArray 调用 compress( air. CompressionAlgorithm.DEFLATE) 所得的结果相同。但是，compress( air.CompressionAlgorithm.ZLIB) 生成的结果包括额外的元数据，而 compress(CompressionAlgorithm.DEFLATE) 生成的结果只包括原始 ByteArray 数据的压缩版本，没有任何其他内容。

若要使用 deflate 格式以 gzip 或 zip 等特定格式压缩 ByteArray 实例的数据，不能只调用 compress(CompressionAlgorithm.DEFLATE)。必须创建一个按照压缩格式规范构建的 ByteArray，包括相应的元数据以及使用 deflate 格式获取的压缩数据。同样，若要对以 gzip 或 zip 这样的格式压缩的数据进行解码，不能对该数据简单地调用 uncompress(CompressionAlgorithm.DEFLATE)。首先，必须将元数据与压缩数据分离，然后才能使用 deflate 格式对压缩数据进行解压缩。

参数

相关 API 元素

使用 deflate 压缩算法压缩字节数组。将压缩整个字节数组。

在调用后，ByteArray 的 length 属性将设置为新长度。position 属性将设置为字节数组末尾。

http://www.ietf.org/rfc/rfc1951.txt 中介绍了 deflate 压缩算法。

为了使用 deflate 格式以 gzip 或 zip 等特定格式压缩 ByteArray 实例的数据，不能只调用 deflate()。必须创建一个按照压缩格式规范构建的 ByteArray，包括相应的元数据以及使用 deflate 格式获取的压缩数据。同样，为了对以 gzip 或 zip 等格式压缩的数据进行解码，对这些数据不能只调用 inflate()。首先，必须将元数据与压缩数据分离，然后才能使用 deflate 格式对压缩数据进行解压缩。

相关 API 元素

使用 deflate 压缩算法将字节数组解压缩。字节数组必须已经使用相同的算法进行压缩。

在调用后，ByteArray 的 length 属性将设置为新长度。position 属性将设置为 0。

http://www.ietf.org/rfc/rfc1951.txt 中介绍了 deflate 压缩算法。

为了对使用 deflate 压缩算法的格式压缩的数据（如 gzip 或 zip 格式的数据）进行解码，对包含压缩格式数据的 ByteArray 不能只调用 inflate()。首先，必须将作为压缩数据格式的一部分而包括的元数据与实际压缩数据分开。有关详细信息，请参阅 compress() 方法的描述。

相关 API 元素

从字节流中读取布尔值。读取单个字节，如果字节非零，则返回 true，否则返回 false。

从字节流中读取带符号的字节。

返回值的范围是从 -128 到 127。

从字节流中读取 length 参数指定的数据字节数。从 offset 指定的位置开始，将字节读入 bytes 参数指定的 ByteArray 对象中，并将字节写入目标 ByteArray 中。

参数

从字节流中读取一个 IEEE 754 双精度（64 位）浮点数。

从字节流中读取一个 IEEE 754 单精度（32 位）浮点数。

从字节流中读取一个带符号的 32 位整数。

返回值的范围是从 -2147483648 到 2147483647。

使用指定的字符集从字节流中读取指定长度的多字节字符串。

参数

从字节数组中读取一个以 AMF 序列化格式进行编码的对象。

相关 API 元素

从字节流中读取一个带符号的 16 位整数。

返回值的范围是从 -32768 到 32767。

从字节流中读取无符号的字节。

返回值的范围是从 0 到 255。

从字节流中读取一个无符号的 32 位整数。

返回值的范围是从 0 到 4294967295。

从字节流中读取一个无符号的 16 位整数。

返回值的范围是从 0 到 65535。

从字节流中读取一个 UTF-8 字符串。假定字符串的前缀是无符号的短整型（以字节表示长度）。

相关 API 元素

从字节流中读取一个由 length 参数指定的 UTF-8 字节序列，并返回一个字符串。

参数

提供一种可覆盖的方法，用于在 ByteArray 对象中自定义值的 JSON 编码。

JSON.stringify() 方法在其遍历的每个对象上寻找 toJSON() 方法。如果找到 toJSON() 方法，JSON.stringify() 会为其遇到的每个值调用该方法，传入与值配对的密钥。

ByteArray 提供 toJSON() 的默认实现，该实现只返回类名称。因为任何 ByteArray 的内容都需要解释，因此希望将 ByteArray 对象导出到 JSON 的客户端必须提供其自己的实现。通过重新定义类原型中的 toJSON() 方法可执行此操作。

toJSON() 方法可返回任何类型的值。如果返回一个对象，则 stringify() 会递归到该对象中。如果 toJSON() 返回一个字符串，则 stringify() 不会递归并继续其遍历。

参数

相关 API 元素

将字节数组转换为字符串。如果数组中的数据以 Unicode 字节顺序标记开头，应用程序在将其转换为字符串时将保持该标记。如果 System.useCodePage 设置为 true，应用程序在转换时会将数组中的数据视为处于当前系统代码页中。

解压缩字节数组。在调用后，ByteArray 的 length 属性将设置为新长度。position 属性将设置为 0。

字节数组必须已经使用与解压相同的算法进行压缩。通过传递一个值（在 CompressionAlgorithm 类中定义）作为 algorithm 参数，可指定解压算法。支持的算法有：

http://www.ietf.org/rfc/rfc1950.txt 中介绍了 zlib 压缩的数据格式。

http://www.ietf.org/rfc/rfc1951.txt 中介绍了 deflate 压缩算法。

lzma 压缩算法在 http://www.7-zip.org/7z.html 中有介绍。

在对使用 deflate 压缩算法的格式压缩的数据（如采用 gzip 或 zip 格式的数据）进行解码时，对包含压缩格式数据的 ByteArray 调用 uncompress(CompressionAlgorithm.DEFLATE) 将不起作用。首先，必须将作为压缩数据格式的一部分而包括的元数据与实际压缩数据分开。有关详细信息，请参阅 compress() 方法的描述。

参数

相关 API 元素

写入布尔值。根据 value 参数写入单个字节。如果为 true，则写入 1，如果为 false，则写入 0。

参数

在字节流中写入一个字节。

使用参数的低 8 位。忽略高 24 位。

参数

将指定字节数组 bytes（起始偏移量为 offset，从零开始的索引）中包含 length 个字节的字节序列写入字节流。

如果省略 length 参数，则使用默认长度 0；该方法将从 offset 开始写入整个缓冲区。如果还省略了 offset 参数，则写入整个缓冲区。

如果 offset 或 length 超出范围，它们将被锁定到 bytes 数组的开头和结尾。

参数

在字节流中写入一个 IEEE 754 双精度（64 位）浮点数。

参数

在字节流中写入一个 IEEE 754 单精度（32 位）浮点数。

参数

在字节流中写入一个带符号的 32 位整数。

参数

使用指定的字符集将多字节字符串写入字节流。

参数

将对象以 AMF 序列化格式写入字节数组。

参数

相关 API 元素

在字节流中写入一个 16 位整数。使用参数的低 16 位。忽略高 16 位。

参数

在字节流中写入一个无符号的 32 位整数。

参数

将 UTF-8 字符串写入字节流。先写入以字节表示的 UTF-8 字符串长度（作为 16 位整数），然后写入表示字符串字符的字节。

参数

将 UTF-8 字符串写入字节流。类似于 writeUTF() 方法，但 writeUTFBytes() 不使用 16 位长度的词为字符串添加前缀。

参数

1. 声明新的 ByteArray 对象实例 byteArr。
2. 写入布尔值 false 的字节等效值，然后检查长度并重新读取。
3. 写入数学值 pi 的双精度浮点等效值。
4. 重新读取写入字节数组的九个字节中的每一个字节。

注意：在字节上调用 trace() 时，它将输出存储于字节数组中的字节的十进制等效值。

注意如何在末尾添加一段代码以检查文件结尾错误，确保读取的字节流没有超出文件结尾。

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.
            }
        }
    }
}