Node.js v0.4.12 Manual & Documentation


Table Of Contents


Buffers

純粋な JavaScript は Unicode と相性がいいものの、バイナリデータの扱いはうまくありません。 TCP ストリームやファイルシステムを扱う場合は、オクテットストリームを処理する必要があります。 Node にはオクテットストリームを操作、作成、消費するためにいくつかの戦略があります。

生のデータは Buffer クラスのインスタンスに保存されます。 Buffer は整数の配列と似ていますが、 V8 ヒープの外部に割り当てられた生のメモリに対応します。 Buffer のサイズを変更することはできません。

Buffer オブジェクトはグローバルです。

バッファを JavaScript 文字列オブジェクトとの間で変換するにはエンコーディング方式を明示する必要があります。 いくつかのエンコーディング方式があります。

new Buffer(size)

size オクテットの新しいバッファを割り当てます。

new Buffer(array)

オクテットの array を使用する新しいバッファを割り当てます。

new Buffer(str, encoding='utf8')

与えられた str を内容とする新しいバッファを割り当てます。

buffer.write(string, offset=0, encoding='utf8')

与えられたエンコーディングを使用して、string をバッファの offset から書き込みます。 書き込まれたオクテット数を返します。 もし buffer が文字列全体を挿入するのに十分なスペースを含んでいなければ、文字列の一部だけを書き込みます。 このメソッドは文字の一部だけを書き込むことはありません。

例: utf8 の文字列をバッファに書き込み、それをプリントします

buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));

書き込まれた文字数 (書き込まれたバイト数とは異なる場合があります) は、 次に buf.write() が呼び出されて上書きされるまで Buffer._charsWritten に設定されています。

buffer.toString(encoding, start=0, end=buffer.length)

encoding でエンコードされたバッファデータの start から end までをデコードした文字列を返します。

上の buffer.write() の例を参照してください。

buffer[index]

index の位置のオクテットを取得および設定します。 その値は個々のバイトを参照するので、妥当な範囲は 16 進の 0x00 から 0xFF または 0 から255までの間です。

例: ASCII 文字列を 1 バイトずつバッファにコピーします

str = "node.js";
buf = new Buffer(str.length);

for (var i = 0; i < str.length ; i++) {
  buf[i] = str.charCodeAt(i);
}

console.log(buf);

// node.js

Buffer.isBuffer(obj)

Tests if obj is a Buffer.

Buffer.byteLength(string, encoding='utf8')

文字列の実際のバイト数を返します。 これは文字列の文字数を返す String.prototype.length と同じではありません。

例:

str = '\u00bd + \u00bc = \u00be';

console.log(str + ": " + str.length + " characters, " +
  Buffer.byteLength(str, 'utf8') + " bytes");

// ½ + ¼ = ¾: 9 characters, 12 bytes

buffer.length

バイト数によるバッファのサイズ。 これは実際の内容のサイズではないことに注意してください。 length はバッファオブジェクトに割り当てられたメモリ全体を参照します。

buf = new Buffer(1234);

console.log(buf.length);
buf.write("some string", "ascii", 0);
console.log(buf.length);

// 1234
// 1234

buffer.copy(targetBuffer, targetStart=0, sourceStart=0, sourceEnd=buffer.length)

バッファ間でコピーします。 ソースとターゲットの領域は重なっていても構いません。

例: バッファを2個作成し、buf1 の 16 バイト目から 19 バイト目を、 buf2 の 8 バイト目から始まる位置へコピーします。

buf1 = new Buffer(26);
buf2 = new Buffer(26);

for (var i = 0 ; i < 26 ; i++) {
  buf1[i] = i + 97; // 97 is ASCII a
  buf2[i] = 33; // ASCII !
}

buf1.copy(buf2, 8, 16, 20);
console.log(buf2.toString('ascii', 0, 25));

// !!!!!!!!qrst!!!!!!!!!!!!!

buffer.slice(start, end=buffer.length)

元のバッファと同じメモリを参照しますが、startend で示されるオフセットで始まり短くされた新しいバッファを返します。

新しいバッファスライスの変更は、オリジナルバッファのメモリを変更することになります!

例: ASCII のアルファベットでバッファを構築してスライスし、元のバッファで 1 バイトを変更します。

var buf1 = new Buffer(26);

for (var i = 0 ; i < 26 ; i++) {
  buf1[i] = i + 97; // 97 is ASCII a
}

var buf2 = buf1.slice(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));

// abc
// !bc