ByteArray  - AS3

バイト配列の現在の位置から最後までの読み取り可能なデータのバイト数です。

ByteArray オブジェクトにアクセスするたびに bytesAvailable プロパティと読み取りメソッドを組み合わせて使用すれば、有効なデータを確実に読み取ることができます。

新しい ByteArray インスタンスに使用する ByteArray クラス用のデフォルトオブジェクトのエンコードを表します。新しい ByteArray インスタンスを作成すると、そのインスタンスのエンコードが defaultObjectEncoding の値で開始します。defaultObjectEncoding プロパティは ObjectEncoding.AMF3 に初期化されます。

バイナリデータからオブジェクトの書き込みまたは読み取りをすると、objectEncoding 値を使用して、ActionScript 3.0、ActionScript 2.0、または ActionScript 1.0 の形式を使用する必要があるかどうかが特定されます。この値は、ObjectEncoding クラスの定数です。

関連する API エレメント

データのバイト順序（Endian.BIG_ENDIAN または Endian.LITTLE_ENDIAN）を変更するか、読み取ります。デフォルト値は BIG_ENDIAN です。

関連する API エレメント

ByteArray オブジェクトのバイト単位の長さです。

この長さに現在の長さよりも大きい値を設定すると、バイト配列の右側には 0 が詰められます。

この長さに現在の長さよりも小さい値を設定すると、バイト配列は切り詰められます。

ByteArray インスタンスへの書き込み、または ByteArray インスタンスからの読み取り時の、ActionScript 3.0、ActionScript 2.0、または ActionScript 1.0 の形式を使用する必要があるかどうかの特定に使用されます。この値は、ObjectEncoding クラスの定数です。

関連する API エレメント

ByteArray オブジェクト内でのファイルポインターの現在の位置をバイト単位で移動するか、または現在の位置をバイト単位で返します。これは、次に読み取りメソッドまたは書き込みメソッドを呼び出したときに読み取りまたは書き込みが開始されるポイントです。

バイト配列の基になるメモリを共有可能にするかどうかを指定します。共有可能バイト配列の場合、そのバイト配列を参照するすべてのワーカーのすべての ByteArray インスタンスで、基になる同じシステムメモリが使用されます。デフォルト値は false で、基になるメモリがワーカー間で共有されないことを示します。

このプロパティは、Worker.setSharedProperty() メソッドまたは MessageChannel.send() メソッドを使用してワーカーに渡された場合に、ランタイムがこのバイト配列で何を処理するかにも影響します。

• Not shareable：このプロパティが false の場合、バイト配列がワーカーに渡されると、ランタイムは、重複するバイト配列の内容を格納するメモリの新しいセグメントの割り当てを含む、バイト配列の完全なコピーを作成します。
• Shareable：このプロパティが true の場合、バイト配列がワーカーに渡されると、ランタイムは、元の ByteArray インスタンスおよび 2 番目のワーカー用に作成された新しい ByteArray インスタンスの両方の内容に使用する記憶領域のバッファーとして、同じ基になるメモリを使用します。つまり、両方の ByteArray インスタンスには同じ基になるバイト配列への参照が含まれます。

同時に複数のワーカーから共有バイト配列にアクセスする機能によって、両方のワーカーがバイト配列の基になるメモリを同時に操作するという好ましくない状況になる可能性があります。いくつかのメカニズムを使用して、共有メモリへのアクセスを制御できます。

• ByteArray クラスの atomicCompareAndSwapIntAt() および atomicCompareAndSwapLength() メソッドによって提供される比較および入れ替えメカニズム
• （flash.concurrent パッケージの）Mutex および Condition クラスによって提供される特別なメカニズム

このプロパティを true にする設定は、このバイト配列をワーカーに渡す後続のコードにのみ影響します。既にワーカーに渡されたこのバイト配列のすべてのコピーは、別のコピーとして存在し続けます。

以前 true だったこのプロパティを false に設定すると、バイト配列用の基になるメモリがシステムメモリの新しいセグメントに即座にコピーされます。その時点から、この ByteArray インスタンスは、新しい基になるメモリを使用するようになります。その結果、このバイト配列の基になるメモリは、たとえ以前に共有されていたとしても、他のワーカーと共有されなくなります。それ以降、このバイト配列をワーカーに渡すと、その基になるメモリは、shareable プロパティが false であるすべての ByteArray オブジェクトと同様にコピーされます。

デフォルト値： false。

関連する API エレメント

バイトの詰め込み配列を表す ByteArray インスタンスを作成します。これにより、このクラスのメソッドおよびプロパティを使用して、データストレージおよびデータストリームを最適化できます。

単一のアトミック操作では、このバイト配列の整数値を他の整数値と比較し、一致する場合は、これらのバイトを別の値と入れ替えます。

このメソッドは、基になるメモリが複数のワーカー間で共有されているバイト配列（ByteArray インスタンスの shareable プロパティが true）と共に使用されることを想定しています。次の一連の手順を実行します。

1. byteIndex 引数に指定されたインデックス（バイト単位）から始まるこのバイト配列から整数値を読み取ります。
2. このバイト配列からの実際の値と expectedValue 引数に渡された値を比較します。
3. 2 つの値が等しい場合は、newValue 引数の値を、byteIndex パラメーターで指定された場所のバイト配列に書き込み、それらのバイトに以前含まれていた値（手順 1 で読み取った値）を返します。
4. それ以外の場合は、バイト配列の内容は変更されず、メソッドはバイト配列から読み取られた実際の値を返します。

これらすべての手順は、1 つのアトミックハードウェアトランザクションで実行されます。これによって、比較および入れ換え操作中に、他のワーカーからの操作によるバイト配列の内容の変更が行われていないことが保証されます。

パラメーター

関連する API エレメント

単一のアトミック操作では、このバイト配列の長さを指定された値と比較し、一致する場合は、このバイト配列の長さを変更します

このメソッドは、基になるメモリが複数のワーカー間で共有されているバイト配列（ByteArray インスタンスの shareable プロパティが true）と共に使用されることを想定しています。以下を実行します。

1. ByteArray インスタンスの整数の length プロパティを読み取ります。
2. 長さを expectedLength 引数に渡された値と比較します。
3. 2 つの値が等しい場合は、バイト配列のサイズを増大または縮小するように、バイト配列の長さを newLength パラメーターとして渡した値に変更します。
4. それ以外の場合は、バイト配列は変更されません。

これらすべての手順は、1 つのアトミックハードウェアトランザクションで実行されます。これによって、比較およびサイズ変更操作中に、他のワーカーからの操作によるバイト配列の内容の変更が行われていないことが保証されます。

パラメーター

関連する API エレメント

バイト配列の内容を消去し、長さと位置のプロパティを 0 にリセットします。このメソッドを明示的に呼び出すと、ByteArray インスタンスによって使用されるメモリを解放します。

バイト配列を圧縮します。バイト配列全体が圧縮されます。呼び出し後、ByteArray の length プロパティが新しい長さに設定されます。position プロパティがバイト配列の末尾に設定されます。

圧縮アルゴリズムを指定するには、値（CompressionAlgorithm クラスに定義された値）を algorithm パラメーターに渡します。サポートされるアルゴリズムは次のとおりです。

zlib 圧縮データ形式の詳細については、http://www.ietf.org/rfc/rfc1950.txt の説明を参照してください。

deflate 圧縮アルゴリズムについては、http://www.ietf.org/rfc/rfc1951.txt の説明を参照してください。

lzma 圧縮アルゴリズムについては、http://sevenzip.sourceforge.jp/ の説明を参照してください。

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 形式を使用して ByteArray インスタンスのデータを gzip や zip などの特定の形式に圧縮する場合は、単に compress(CompressionAlgorithm.DEFLATE) を呼び出すだけでは不十分です。圧縮形式の仕様に従い、適切なメタデータと deflate 形式で圧縮されたデータで構成された ByteArray を作成する必要があります。同様に、gzip や zip などの形式で圧縮されたデータを解凍する場合、単にそのデータに対して uncompress(CompressionAlgorithm.DEFLATE) を呼び出すだけでは不十分です。まず、圧縮データからメタデータを分離してから、deflate 形式を使用して圧縮データを解凍する必要があります。

パラメーター

関連する API エレメント

deflate 圧縮アルゴリズムを使用してバイト配列を圧縮します。バイト配列全体が圧縮されます。

呼び出し後、ByteArray の length プロパティが新しい長さに設定されます。position プロパティがバイト配列の末尾に設定されます。

deflate 圧縮アルゴリズムについては、http://www.ietf.org/rfc/rfc1951.txt の説明を参照してください。

deflate 形式を使用して ByteArray インスタンスのデータを gzip や zip などの特定の形式に圧縮する場合は、単に deflate() を呼び出すだけでは目的を達することはできません。圧縮形式の仕様に従い、適切なメタデータと deflate 形式で圧縮されたデータで構成された ByteArray を作成する必要があります。同様に、gzip や zip などの形式で圧縮されたデータを解凍する場合、単にそのデータに対して inflate() を呼び出すだけでは不十分です。まず、圧縮データからメタデータを分離してから、deflate 形式を使用して圧縮データを解凍する必要があります。

関連する API エレメント

deflate 圧縮アルゴリズムを使用してバイト配列を圧縮します。同じアルゴリズムを使用してバイト配列が圧縮されている必要があります。

呼び出し後、ByteArray の length プロパティが新しい長さに設定されます。position プロパティが 0 に設定されます。

deflate 圧縮アルゴリズムについては、http://www.ietf.org/rfc/rfc1951.txt の説明を参照してください。

deflate 圧縮アルゴリズムを使用する形式で圧縮されたデータ（gzip 形式や zip 形式のデータ）を解凍する場合、圧縮形式データを含む ByteArray に対して単に inflate() を呼び出してもデータは解凍されません。まず、圧縮データ形式の構成要素であるメタデータを実際の圧縮データから分離する必要があります。詳細については、compress() メソッドの説明を参照してください。

関連する API エレメント

バイトストリームからブール値を読み取ります。1 バイトが読み取られ、バイトがゼロ以外の場合は true、それ以外の場合は false が返されます。

バイトストリームから符号付きバイトを読み取ります。

戻り値は -128 ～ 127 の範囲です。

バイトストリームから、length パラメーターで指定したデータバイト数を読み取ります。バイトは、bytes パラメーターによって指定された ByteArray オブジェクトに読み取られ、offset によって指定された位置から始まるターゲット ByteArray に書き込まれます。

パラメーター

バイトストリームから IEEE 754 倍精度（64 bit）浮動小数点数を読み取ります。

バイトストリームから IEEE 754 単精度（32 bit）浮動小数点数を読み取ります。

バイトストリームから符号付き 32 bit 整数を読み取ります。

戻り値は -2147483648 ～ 2147483647 の範囲です。

指定した文字セットを使用して、バイトストリームから指定した長さのマルチバイトストリングを読み取ります。

パラメーター

バイト配列から AMF 直列化形式でエンコードされたオブジェクトを読み取ります。

関連する API エレメント

バイトストリームから符号付き 16 bit 整数を読み取ります。

戻り値は -32768 ～ 32767 の範囲です。

バイトストリームから符号なしバイトを読み取ります。

戻り値は 0 ～ 255 の範囲です。

バイトストリームから符号なし 32 bit 整数を読み取ります。

戻り値は 0 ～ 4294967295 の範囲です。

バイトストリームから符号なし 16 bit 整数を読み取ります。

戻り値は 0 ～ 65535 の範囲です。

バイトストリームから UTF-8 ストリングを読み取ります。このストリングには、バイト単位の長さを示す符号なし short が前に付いているものと見なされます。

関連する API エレメント

バイトストリームまたはバイト配列から、length パラメーターで指定した UTF-8 バイトのシーケンスを読み取り、ストリングを返します。

パラメーター

ByteArray オブジェクトの値の JSON エンコーディングをカスタマイズするためのオーバーライド可能なメソッドです。

JSON.stringify() メソッドは、スキャンする各オブジェクトの toJSON() メソッドを検索します。toJSON() が見つかれば、JSON.stringify() で検出された値ごとに toJSON() メソッドが呼び出され、値のペアとなっているキーが渡されます。

ByteArray には、単純にクラス名を返すデフォルトの toJSON() 実装が含まれています。ByteArray では内容を解釈する必要があるので、ByteArray オブジェクトを JSON に書き出す場合は、独自の実装を行う必要があります。このためには、クラスのプロトタイプの toJSON() メソッドを再定義します。

toJSON() メソッドは、あらゆるタイプの値を返すことができます。オブジェクトを返す場合は、stringify() でそのオブジェクトが再帰的に処理されます。toJSON() が文字列を返す場合は、stringify() で再帰的な処理は行われず、オブジェクトをスキャンする処理が続行されます。

パラメーター

関連する API エレメント

バイト配列をストリングに変換します。配列のデータが Unicode バイト順マークで開始する場合、アプリケーションではストリングの変換時に、そのマークが使用されます。System.useCodePage を true に設定すると、アプリケーションでは、変換時の配列のデータは現在のシステムコードページにあると見なされます。

バイト配列を解凍します。呼び出し後、ByteArray の length プロパティが新しい長さに設定されます。position プロパティが 0 に設定されます。

uncompress と同じアルゴリズムを使用してバイト配列が圧縮されている必要があります。非圧縮アルゴリズムを指定するには、値（CompressionAlgorithm クラスに定義された値）を algorithm パラメーターに渡します。サポートされるアルゴリズムは次のとおりです。

zlib 圧縮データ形式の詳細については、http://www.ietf.org/rfc/rfc1950.txt の説明を参照してください。

deflate 圧縮アルゴリズムについては、http://www.ietf.org/rfc/rfc1951.txt の説明を参照してください。

lzma 圧縮アルゴリズムについては、http://sevenzip.sourceforge.jp/ の説明を参照してください。

deflate 圧縮アルゴリズムを使用する形式で圧縮されたデータ（gzip 形式や zip 形式のデータ）を解凍する場合、圧縮形式データを含む ByteArray に対して uncompress(CompressionAlgorithm.DEFLATE) を呼び出してもデータは解凍されません。まず、圧縮データ形式の構成要素であるメタデータを実際の圧縮データから分離する必要があります。詳細については、compress() メソッドの説明を参照してください。

パラメーター

関連する API エレメント

ブール値を書き込みます。value パラメーターに従って、1 バイトが書き込まれます。true の場合は 1、false の場合は 0 のいずれかが書き込まれます。

パラメーター

バイトストリームにバイトを書き込みます。

パラメーターの下位 8 bit が使用されます。上位 24 bit は無視されます。

パラメーター

指定したバイト配列の offset（0 から始まるインデックス値）バイトから開始される length バイトのシーケンス bytes をバイトストリームに書き込みます。

length パラメーターを省略すると、デフォルトの長さの 0 が使用され、メソッドによって offset から開始されるバッファー全体が書き込まれます。 offset パラメーターも省略した場合は、バッファー全体が書き込まれます。

offset または length が範囲外の場合、これらは bytes 配列の最初と最後に固定されます。

パラメーター

バイトストリームに IEEE 754 倍精度（64 bit）浮動小数点数を書き込みます。

パラメーター

バイトストリームに IEEE 754 単精度（32 bit）浮動小数点数を書き込みます。

パラメーター

バイトストリームに 32 bit 符号付き整数を書き込みます。

パラメーター

指定した文字セットを使用して、バイトストリームにマルチバイトストリングを書き込みます。

パラメーター

バイト配列に AMF 直列化形式でオブジェクトを書き込みます。

パラメーター

関連する API エレメント

バイトストリームに 16 bit 整数を書き込みます。パラメーターの下位 16 bit が使用されます。上位 16 bit は無視されます。

パラメーター

バイトストリームに 32 bit 符号なし整数を書き込みます。

パラメーター

バイトストリームに UTF-8 ストリングを書き込みます。最初に UTF-8 ストリングの長さがバイト単位で 16 bit 整数として書き込まれ、その後にストリングの文字を表すバイトが続きます。

パラメーター

バイトストリームに UTF-8 ストリングを書き込みます。writeUTF() メソッドと似ていますが、writeUTFBytes() では、ストリングに 16 bit 長の接頭辞が付きません。

パラメーター

1. 新しい ByteArray オブジェクトインスタンス byteArr を宣言します。
2. バイトと等価のブール値 false を書き込み、長さをチェックしてその値を戻します。
3. pi の数値と等価の倍精度の浮動小数を書き込みます。
4. バイト配列に書き込まれた 9 バイトを 1 つずつ読み出します。

注意：trace() がバイトに対して呼び出されると、バイト配列に保存された 10 進表現のバイトが出力されます。

コードセグメントが最後に追加され、ファイルの終端エラーをチェックして、バイトストリームが最後まで読み取られないことを確認します。

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