Node.js Buffer(バッファ)

JavaScript 言語自体は文字列データ型のみを持ち、バイナリデータ型はありません。

Node.js の Buffer クラスはバイナリデータを処理するための中核的なツールであり、バイナリデータを効率的に操作する機能を提供します。

Buffer クラスは、ファイル操作、ネットワーク通信、画像処理などの場面で特に役立ちます。

特徴：

• バイナリデータ：：Bufferオブジェクトは、生のバイナリデータを含む固定サイズの配列です。各要素は1バイト（8ビット）を占めるため、Bufferファイル内容やネットワークパケットなどのバイナリデータの処理に適しています。
• 不変性：オブジェクトの内容は作成後に変更できますが、Bufferその長さは固定されており、動的に変更することはできません。

Buffer と文字エンコーディング

Buffer インスタンスは通常、UTF-8、UCS2、Base64、または16進数エンコードされたデータなどの文字エンコードされたシーケンスを表すために使用されます。明示的な文字エンコーディングを使用することで、Buffer インスタンスと通常の JavaScript 文字列の間で相互に変換できます。

Node.js で現在サポートされている文字エンコーディングは次のとおりです：

• ascii- 7ビットのASCIIデータのみをサポートします。上位ビットを除去する設定にすると、このエンコーディングは非常に高速です。

• utf8- マルチバイトエンコーディングのUnicode文字。多くのWebページやその他のドキュメント形式でUTF-8が使用されています。

• utf16le- 2バイトまたは4バイトのリトルエンディアンでエンコードされたUnicode文字。サロゲートペア（U+10000〜U+10FFFF）をサポートします。

• ucs2 - utf16leのエイリアス。

• base64- Base64エンコーディング。

• latin1- Buffer をBuffer1バイトエンコーディングの文字列にエンコードする方法。

• binary - latin1のエイリアス。

• hex各バイトを2つの16進文字としてエンコードします。

Buffer クラスの作成

Buffer は、Buffer クラスを作成するための以下の API を提供します：

• Buffer.alloc(size[, fill[, encoding]])：長さ size バイトの Buffer を作成します。これは size バイトのメモリ空間を確保することに相当し、各バイトの値は 0 です。
• Buffer.allocUnsafe(size)：長さ size バイトの Buffer を作成しますが、Buffer 内に古いデータが存在する可能性があり、実行結果に影響を与える可能性があるため、unsafe と呼ばれます。
• Buffer.allocUnsafeSlow(size)：指定されたサイズ size の新しい Buffer インスタンスを割り当てるために使用されますが、初期化は行われません。
• Buffer.from(array)：array の値で初期化された新しい Buffer インスタンスを返します（渡される array の要素は数字のみでなければならず、そうでない場合は自動的に 0 で上書きされます）。
• Buffer.from(arrayBuffer[, byteOffset[, length]])：指定された ArrayBuffer と同じメモリを共有する、新しく作成された Buffer を返します。
• Buffer.from(buffer)：渡された Buffer インスタンスのデータをコピーし、新しい Buffer インスタンスを返します。
• Buffer.from(string[, encoding])：文字列から Buffer を作成します。エンコーディングを指定でき、デフォルトは UTF-8 です。

バッファへの書き込み

構文

Node バッファに書き込む構文は次のとおりです：

buf.write(string[, offset[, length]][, encoding])

パラメータ

パラメータの説明は次のとおりです：

• string- バッファに書き込む文字列。

• offset- バッファの書き込み開始位置のインデックス値。デフォルトは 0 です。

• length- 書き込むバイト数。デフォルトは buffer.length です。

• encoding- 使用するエンコーディング。デフォルトは 'utf8' です。

encoding の文字エンコーディングに従って、string を buf の offset 位置に書き込みます。length パラメータは書き込むバイト数です。buf に文字列全体を保存するための十分な空きがない場合、string の一部のみが書き込まれます。部分的にデコードされた文字は書き込まれません。

戻り値

実際に書き込まれたサイズを返します。buffer のスペースが不足している場合は、文字列の一部のみが書き込まれます。

例

buf = Buffer.alloc(256);
len = buf.write("www.example.com");

console.log("写入字节数 : "+  len);

上記のコードを実行すると、出力結果は次のとおりです：

$node main.js
写入字节数 : 14

バッファからのデータの読み取り

構文

Node バッファのデータを読み取る構文は次のとおりです：

buf.toString([encoding[, start[, end]]])

パラメータ

パラメータの説明は次のとおりです：

• encoding- 使用するエンコーディング。デフォルトは 'utf8' です。

• start- 読み取りを開始するインデックス位置を指定します。デフォルトは 0 です。

• end- 終了位置。デフォルトはバッファの末尾です。

戻り値

バッファのデータをデコードし、指定されたエンコーディングを使用して文字列を返します。

例

buf = Buffer.alloc(26);
for (var i = 0 ; i < 26 ; i++) {
  buf[i] = i + 97;
}

console.log( buf.toString('ascii'));       // 输出: abcdefghijklmnopqrstuvwxyz
console.log( buf.toString('ascii',0,5));   //使用 'ascii' 编码, 并输出: abcde
console.log( buf.toString('utf8',0,5));    // 使用 'utf8' 编码, 并输出: abcde
console.log( buf.toString(undefined,0,5)); // 使用默认的 'utf8' 编码, 并输出: abcde

上記のコードを実行すると、出力結果は次のとおりです：

$ node main.js
abcdefghijklmnopqrstuvwxyz
abcde
abcde
abcde

Buffer を JSON オブジェクトに変換

構文

Node Buffer を JSON オブジェクトに変換する関数の構文形式は次のとおりです：

buf.toJSON()

Buffer インスタンスを文字列化するとき、JSON.stringify()暗黙的にこのメソッドが呼び出されます。toJSON()。

戻り値

JSON オブジェクトを返します。

例

const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);

// 输出: {"type":"Buffer","data":[1,2,3,4,5]}
console.log(json);

const copy = JSON.parse(json, (key, value) => {
  return value && value.type === 'Buffer' ?
    Buffer.from(value.data) :
    value;
});

// 输出: <Buffer 01 02 03 04 05>
console.log(copy);

上記のコードを実行すると、出力結果は次のとおりです：

{"type":"Buffer","data":[1,2,3,4,5]}
<Buffer 01 02 03 04 05>

バッファの結合

構文

Node バッファを結合する構文は次のとおりです：

Buffer.concat(list[, totalLength])

パラメータ

パラメータの説明は次のとおりです：

• list- 結合に使用する Buffer オブジェクトの配列リスト。

• totalLength- 結合後の Buffer オブジェクトの合計長を指定します。

戻り値

複数のメンバーを結合した新しい Buffer オブジェクトを返します。

例

var buffer1 = Buffer.from(('サンプル'));
var buffer2 = Buffer.from(('www.example.com'));
var buffer3 = Buffer.concat([buffer1,buffer2]);
console.log("buffer3 内容: " + buffer3.toString());

上記のコードを実行すると、出力結果は次のとおりです：

buffer3 内容: サンプルwww.example.com

バッファの比較

構文

Node Buffer を比較する関数の構文は次のとおりです。このメソッドは Node.js v0.12.2 で導入されました：

buf.compare(otherBuffer);

パラメータ

パラメータの説明は次のとおりです：

• otherBuffer- 比較対象のbufbuf オブジェクトと比較するもう1つの Buffer オブジェクト。

戻り値

比較対象のbufにotherBuffer前、後、または同じであることを示す数字を返します。

例

var buffer1 = Buffer.from('ABC');
var buffer2 = Buffer.from('ABCD');
var result = buffer1.compare(buffer2);

if(result < 0) {
   console.log(buffer1 + " 在 " + buffer2 + "之前");
}else if(result == 0){
   console.log(buffer1 + " 与 " + buffer2 + "相同");
}else {
   console.log(buffer1 + " 在 " + buffer2 + "之后");
}

上記のコードを実行すると、出力結果は次のとおりです：

ABC在ABCD之前

バッファのコピー

構文

Node バッファのコピー構文は次のとおりです。

buf.copy(targetBuffer[, targetStart[, sourceStart[, sourceEnd]]])

パラメータ

パラメータの説明は次のとおりです。

• targetBuffer- コピーする Buffer オブジェクト。

• targetStart- 数値、オプション、デフォルト: 0

• sourceStart- 数値、オプション、デフォルト: 0

• sourceEnd- 数値、オプション、デフォルト: buffer.length

戻り値

戻り値はありません。

例

var buf1 = Buffer.from('abcdefghijkl');
var buf2 = Buffer.from('サンプル');

//将 buf2 插入到 buf1 指定位置上
buf2.copy(buf1, 2);

console.log(buf1.toString());

上記のコードを実行すると、出力結果は次のとおりです。

abサンプルijkl

バッファのスライス

Node バッファの切り出し構文は次のとおりです。

buf.slice([start[, end]])

パラメータ

パラメータの説明は次のとおりです。

• start- 数値、オプション、デフォルト: 0

• end- 数値、オプション、デフォルト: buffer.length

戻り値

新しいバッファを返します。これは古いバッファと同じメモリを指しますが、インデックス start から end の位置で切り出されます。

例

var buffer1 = Buffer.from('サンプル');
// 剪切缓冲区
var buffer2 = buffer1.slice(0,2);
console.log("buffer2 content: " + buffer2.toString());

上記のコードを実行すると、出力結果は次のとおりです。

buffer2 content: ru

バッファの長さ

構文

Node バッファの長さの計算構文は次のとおりです。

buf.length;

戻り値

Buffer オブジェクトが占めるメモリ長を返します。

例

var buffer = Buffer.from('www.example.com');
//  缓冲区长度
console.log("buffer length: " + buffer.length);

上記のコードを実行すると、出力結果は次のとおりです。

buffer length: 14

メソッドリファレンス

以下に、Node.js Buffer モジュールでよく使われるメソッドを示します（一部のメソッドは古いバージョンにはないことに注意してください）：

const buf = Buffer.allocUnsafe(6);

buf.writeUIntLE(0x1234567890ab, 0, 6);

// 输出: <Buffer ab 90 78 56 34 12>
console.log(buf);

const buf = Buffer.allocUnsafe(6);

buf.writeUIntBE(0x1234567890ab, 0, 6);

// 输出: <Buffer 12 34 56 78 90 ab>
console.log(buf);