Buffer · Node.js 中文API文檔 0.10.18

# Buffer ~~~ 穩定度: 3 - 穩定 ~~~ 純 JavaScript 對 Unicode 友好但是無法很好地處理二進制數據。當我們面對類似 TCP 流或文件系統時，是需要處理八位流的。Node 有幾種操作、創建以及消費八位流的策略。原始數據保存在 `Buffer` 類的實例中。一個 `Buffer` 實例類似于一個整數數組，但對應者 V8 堆之外的一個原始內存分配區域。一個 `Buffer` 的大小不可變。 `Buffer` 類是一個全局的類，是一個比較罕見的不需要 `require('buffer')` 就可以使用的類。在Buffers和JavaScript string轉換時，需要明確的一個編碼方法。下面是一些不同的string編碼。 - `'ascii'` - 僅適用 7 bit ASCII 格式數據。這個編碼方式非常快速，而且會剝離設置過高的bit。 - `'utf8'` - 多字節編碼 Unicode字符。很多網頁或者其他文檔的編碼格式都是使用 UTF-8的。 - `'utf16le'` - 2 或者 4 字節, Little Endian (LE) 編碼Unicode字符。代理對 (U+10000 to U+10FFFF) 是支持的.（BE和LE表示大端和小端，Little-Endian就是低位字節排放在內存的低地址端，高位字節排放在內存的高地址端；Big-Endian就是高位字節排放在內存的低地址端，低位字節排放在內存的高地址端；下同） - `'ucs2'` - `'utf16le'`的別名. - `'base64'` - Base64 字符串編碼。 - `'binary'` - 一個將原始2進制數據編碼為字符串的方法，僅使用每個字符的前8bits。這個編碼方式已經被棄用而且應該被避免，盡可能的使用`Buffer`對象。這個編碼方式將會在未來的Node版本中移除。 - `'hex'` - 把每個byte編碼成2個十六進制字符 ### 類: Buffer Buffer 類是一個全局變量類型，用來直接處理2進制數據的。它能夠使用多種方式構建。 ### new Buffer(size) - `size` Number 分配一個新的 buffer 大小是 `size` 的8位字節. ### new Buffer(array) - `array` Array 分配一個新的 buffer 使用一個8位字節 `array` 數組. ### new Buffer(str, [encoding]) - `str` String類型 - 需要存入buffer的string字符串. - `encoding` String類型 - 使用什么編碼方式，參數可選. 分配一個新的 buffer ，其中包含著給定的 `str`字符串. `encoding` 編碼方式默認是：`'utf8'`. ### 類方法: Buffer.isEncoding(encoding) - `encoding` {String} 用來測試給定的編碼字符串如果給定的編碼 `encoding` 是有效的，返回 true，否則返回 false。 ### 類方法: Buffer.isBuffer(obj) - `obj` Object - 返回: Boolean 測試這個 `obj` 是否是一個 `Buffer`. ### 類方法: Buffer.byteLength(string, [encoding]) - `string` String類型 - `encoding` String類型, 可選參數, 默認是: 'utf8' - Return: Number類型將會返回這個字符串真實byte長度。 `encoding` 編碼默認是： `'utf8'`. 這個和 `String.prototype.length` 是不一樣的，因為那個方法返回這個字符串中有幾個字符的數量。（譯者：當用戶在寫http響應頭Cotent-Length的時候，千萬記得一定要用 `Buffer.byteLength` 方法，不要使用 `String.prototype.length` ）實例： ~~~ // ? + ? = ?: 9 characters, 12 bytes ~~~ ### 類方法: Buffer.concat(list, [totalLength]) - `list` {Array}數組類型，Buffer數組，用于被連接。 - `totalLength` {Number}類型上述Buffer數組的所有Buffer的總大小。（譯者：注意這里的totalLength不是數組長度是數組里Buffer實例的大小總和）返回一個保存著將傳入buffer數組中所有buffer對象拼接在一起的buffer對象。（譯者：有點拗口，其實就是將數組中所有的buffer實例通過復制拼接在一起）如果傳入的數組沒有內容，或者 totalLength 參數是0，那將返回一個zero-length的buffer。如果數組中只有一項，那么這第一項就會被返回。如果數組中的項多于一個，那么一個新的Buffer實例將被創建。如果 totalLength 參數沒有提供，雖然會從buffer數組中計算讀取，但是會增加一個額外的循環來計算它，所以提供一個明確的 totalLength 參數將會更快。 ### buf.length - Number類型這個buffer的bytes大小。注意這未必是這buffer里面內容的大小。`length` 的依據是buffer對象所分配的內存數值，它不會隨著這個buffer對象內容的改變而改變。 ~~~ // 1234 // 1234 ~~~ ### buf.write(string, [offset], [length], [encoding]) - `string` String類型 - 將要被寫入 buffer 的數據 - `offset` Number類型, 可選參數, 默認: 0 - `length` Number類型, 可選參數, 默認: `buffer.length - offset` - `encoding` String類型, 可選參數, 默認: 'utf8' 根據參數 `offset` 偏移量和指定的`encoding`編碼方式，將參數 `string` 數據寫入buffer。 `offset`偏移量默認是 `0`, `encoding`編碼方式默認是 `'utf8'`。 `length`長度是將要寫入的字符串的bytes大小。返回number類型，表示多少8位字節流被寫入了。如果`buffer` 沒有足夠的空間來放入整個string，它將只會寫入部分的字符串。 `length` 默認是 `buffer.length - offset`。這個方法不會出現寫入部分字符。 ~~~ buf = new Buffer(256); len = buf.write('\u00bd + \u00bc = \u00be', 0); console.log(len + " bytes: " + buf.toString('utf8', 0, len)); ~~~ ### buf.toString([encoding], [start], [end]) - `encoding` String類型, 可選參數, 默認: 'utf8' - `start` Number類型, 可選參數, 默認: 0 - `end` Number類型, 可選參數, 默認: `buffer.length` 根據 `encoding`參數（默認是 `'utf8'`）返回一個解碼的 string 類型。還會根據傳入的參數 `start` (默認是`0`) 和 `end` (默認是 `buffer.length`)作為取值范圍。查看上面`buffer.write()` 的例子. ### buf.toJSON() 返回一個 JSON表示的Buffer實例。`JSON.stringify`將會默認調用來字符串序列化這個Buffer實例。實例： ~~~ console.log(copy); // <Buffer 74 65 73 74> ~~~ ### buf[index] 獲取或者設置在指定`index`索引位置的8位字節。這個值是指單個字節，所以這個值必須在合法的范圍，16進制的`0x00` 到`0xFF`，或者`0` 到`255`。例子: 拷貝一個 ASCII 編碼的 string 字符串到一個 buffer, 一次一個 byte 進行拷貝: ~~~ // node.js ~~~ ### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd]) - `targetBuffer` Buffer 類型對象 - 將要進行拷貝的Buffer - `targetStart` Number類型, 可選參數, 默認: 0 - `sourceStart` Number類型, 可選參數, 默認: 0 - `sourceEnd` Number類型, 可選參數, 默認: `buffer.length` 進行buffer的拷貝，源和目標可以是重疊的。 `targetStart` 目標開始偏移和`sourceStart`源開始偏移默認都是 `0`. `sourceEnd` 源結束位置偏移默認是源的長度 `buffer.length`. 如果傳遞的值是`undefined`/`NaN` 或者是 out of bounds 超越邊界的，就將設置為他們的默認值。（譯者：這個默認值下面有的例子有說明）例子: 創建2個Buffer，然后把將`buf1`的16位到19位拷貝到 `buf2`中，并且從`buf2`的第8位開始拷貝。 ~~~ // !!!!!!!!qrst!!!!!!!!!!!!! ~~~ ### buf.slice([start], [end]) - `start` Number類型, 可選參數, 默認: 0 - `end` Number類型, 可選參數, 默認: `buffer.length` 返回一個新的buffer，這個buffer將會和老的buffer引用相同的內存地址，只是根據 `start` (默認是 `0`) 和`end` (默認是`buffer.length`) 偏移和裁剪了索引。負的索引是從buffer尾部開始計算的。 **修改這個新的buffer實例slice切片，也會改變原來的buffer** 例子: 創建一個ASCII 字母的 Buffer，對它slice切片，然后修改源Buffer上的一個byte。 ~~~ // abc // !bc ~~~ ### buf.readUInt8(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，讀取一個 unsigned 8 bit integer整形。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。實例： ~~~ // 0x3 // 0x4 // 0x23 // 0x42 ~~~ ### buf.readUInt16LE(offset, [noAssert]) ### buf.readUInt16BE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用特殊的 endian字節序格式讀取一個 unsigned 16 bit integer。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。實例： ~~~ // 0x0304 // 0x0403 // 0x0423 // 0x2304 // 0x2342 // 0x4223 ~~~ ### buf.readUInt32LE(offset, [noAssert]) ### buf.readUInt32BE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用指定的 endian字節序格式讀取一個 unsigned 32 bit integer。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。實例： ~~~ // 0x03042342 // 0x42230403 ~~~ ### buf.readInt8(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，讀取一個 signed 8 bit integer。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。和 `buffer.readUInt8`一樣的返回，除非buffer中包含了有作為2的補碼的有符號值。 ### buf.readInt16LE(offset, [noAssert]) ### buf.readInt16BE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用特殊的 endian字節序格式讀取一個 signed 16 bit integer。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。和 buffer.readUInt16一樣返回，除非buffer中包含了有作為2的補碼的有符號值。 ### buf.readInt32LE(offset, [noAssert]) ### buf.readInt32BE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用指定的 endian字節序格式讀取一個 signed 32 bit integer。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。和 buffer.readUInt32一樣返回，除非buffer中包含了有作為2的補碼的有符號值。 ### buf.readFloatLE(offset, [noAssert]) ### buf.readFloatBE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用指定的 endian字節序格式讀取一個 32 bit float。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。實例： ~~~ // 0x01 ~~~ ### buf.readDoubleLE(offset, [noAssert]) ### buf.readDoubleBE(offset, [noAssert]) - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false - Return: Number類型從這個buffer對象里，根據指定的偏移量，使用指定的 endian字節序格式讀取一個 64 bit double。設置參數 `noAssert`為true表示忽略驗證`offset`偏移量參數。這意味著 `offset`可能會超出buffer的末尾。默認是 `false`。實例： ~~~ // 0.3333333333333333 ~~~ ### buf.writeUInt8(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量將`value`寫入buffer。注意：`value` 必須是一個合法的unsigned 8 bit integer. 設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 實例： ~~~ // <Buffer 03 04 23 42> ~~~ ### buf.writeUInt16LE(value, offset, [noAssert]) ### buf.writeUInt16BE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：`value` 必須是一個合法的unsigned 16 bit integer. 設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 實例： ~~~ // <Buffer de ad be ef> // <Buffer ad de ef be> ~~~ ### buf.writeUInt32LE(value, offset, [noAssert]) ### buf.writeUInt32BE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：`value` 必須是一個合法的unsigned 32 bit integer。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 實例： ~~~ // <Buffer fe ed fa ce> // <Buffer ce fa ed fe> ~~~ ### buf.writeInt8(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量將`value`寫入buffer。注意：`value` 必須是一個合法的 signed 8 bit integer。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 和 `buffer.writeUInt8` 一樣工作，除非是把有2的補碼的 signed integer 有符號整形寫入`buffer`。 ### buf.writeInt16LE(value, offset, [noAssert]) ### buf.writeInt16BE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：`value` 必須是一個合法的 signed 16 bit integer。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 和 `buffer.writeUInt16*` 一樣工作，除非是把有2的補碼的 signed integer 有符號整形寫入`buffer`。 ### buf.writeInt32LE(value, offset, [noAssert]) ### buf.writeInt32BE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：`value` 必須是一個合法的 signed 32 bit integer。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 和 `buffer.writeUInt32*` 一樣工作，除非是把有2的補碼的 signed integer 有符號整形寫入`buffer`。 ### buf.writeFloatLE(value, offset, [noAssert]) ### buf.writeFloatBE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：當`value` 不是一個 32 bit float 類型的值時，結果將是不確定的。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 實例： ~~~ // <Buffer 4f 4a fe bb> // <Buffer bb fe 4a 4f> ~~~ ### buf.writeDoubleLE(value, offset, [noAssert]) ### buf.writeDoubleBE(value, offset, [noAssert]) - `value` Number類型 - `offset` Number類型 - `noAssert` Boolean類型, 可選參數, 默認: false 根據指定的offset偏移量和指定的 endian字節序格式將`value`寫入buffer。注意：`value` 必須是一個有效的 64 bit double 類型的值。設置參數 `noAssert`為true表示忽略驗證`value`和`offset`參數。這意味著 `value`可能過大，或者`offset`可能會超出buffer的末尾造成`value`被丟棄。這個參數除了你非常有把握，否則不應該使用它。默認是 `false`。`. 實例： ~~~ // <Buffer 43 eb d5 b7 dd f9 5f d7> // <Buffer d7 5f f9 dd b7 d5 eb 43> ~~~ ### buf.fill(value, [offset], [end]) - `value` - `offset` Number類型, 可選參數 - `end` Number類型, 可選參數使用指定的value來填充這個buffer。如果 `offset` (默認是 `0`) 并且 `end` (默認是 `buffer.length`) 沒有明確給出，就會填充整個buffer。（譯者：buf.fill調用的是C語言的memset函數非常高效） ~~~ var b = new Buffer(50); b.fill("h"); ~~~ ### buffer.INSPECT_MAX_BYTES - Number類型, 默認: 50 設置當調用`buffer.inspect()`方法后，多少bytes將會返回。這個值可以被用戶模塊重寫。（譯者：這個值主要用在當我們打印console.log(buf)時，設置返回多少長度內容）注意這個屬性是`require('buffer')`模塊返回的。這個屬性不是在全局變量Buffer中，也不再buffer的實例里。 ### 類: SlowBuffer 返回一個不被池管理的 `Buffer`。為了避免創建大量獨立分配的 Buffer 帶來的垃圾回收開銷，默認情況下小于 4KB 的空間都是切割自一個較大的獨立對象。這種策略既提高了性能也改善了內存使用，因為 V8 不需要跟蹤和清理很多 `Persistent` 對象。當開發者需要將池中一小塊數據保留不確定的一段時間，較為妥當的辦法是用 SlowBuffer 創建一個不被池管理的 Buffer 實例并將相應數據拷貝出來。 ~~~ socket.on('readable', function() { var data = socket.read(); // 為需要保留的數據分配內存 var sb = new SlowBuffer(10); // 將數據拷貝到新的空間中 data.copy(sb, 0, 0, 10); store.push(sb); }); ~~~ 請謹慎使用，僅作為開發者頻繁觀察到他們的應用中過度的內存保留時的*最后*手段。