# Buffer
~~~
穩(wěn)定度: 3 - 穩(wěn)定
~~~
純 JavaScript 對 Unicode 友好但是無法很好地處理二進制數據。當我們面對類似 TCP 流或文件系統(tǒng)時，是需要處理八位流的。Node 有幾種操作、創(chuàng)建以及消費八位流的策略。
原始數據保存在 `Buffer` 類的實例中。一個 `Buffer` 實例類似于一個整數數組，但對應者 V8 堆之外的一個原始內存分配區(qū)域。一個 `Buffer` 的大小不可變。
`Buffer` 類是一個全局的類，是一個比較罕見的不需要 `require('buffer')` 就可以使用的類。
在Buffers和JavaScript string轉換時，需要明確的一個編碼方法。下面是一些不同的string編碼。
- `'ascii'` - 僅適用 7 bit ASCII 格式數據。這個編碼方式非?？焖?，而且會剝離設置過高的bit。
- `'utf8'` - 多字節(jié)編碼 Unicode字符。很多網頁或者其他文檔的編碼格式都是使用 UTF-8的。
- `'utf16le'` - 2 或者 4 字節(jié), Little Endian (LE) 編碼Unicode字符。 代理對 (U+10000 to U+10FFFF) 是支持的.（BE和LE表示大端和小端，Little-Endian就是低位字節(jié)排放在內存的低地址端，高位字節(jié)排放在內存的高地址端；Big-Endian就是高位字節(jié)排放在內存的低地址端，低位字節(jié)排放在內存的高地址端；下同）
- `'ucs2'` - `'utf16le'`的別名.
- `'base64'` - Base64 字符串編碼。
- `'binary'` - 一個將原始2進制數據編碼為字符串的方法，僅使用每個字符的前8bits。 這個編碼方式已經被棄用而且應該被避免，盡可能的使用`Buffer`對象。這個編碼方式將會在未來的Node版本中移除。
- `'hex'` - 把每個byte編碼成2個十六進制字符
### 類: Buffer
Buffer 類是一個全局變量類型，用來直接處理2進制數據的。 它能夠使用多種方式構建。
### new Buffer(size)
- `size` Number
分配一個新的 buffer 大小是 `size` 的8位字節(jié).
### new Buffer(array)
- `array` Array
分配一個新的 buffer 使用一個8位字節(jié) `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實例將被創(chuàng)建。
如果 totalLength 參數沒有提供，雖然會從buffer數組中計算讀取，但是會增加一個額外的循環(huán)來計算它，所以提供一個明確的 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位字節(jié)流被寫入了。如果`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位字節(jié)。這個值是指單個字節(jié)，所以這個值必須在合法的范圍，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 超越邊界的，就將設置為他們的默認值。（譯者：這個默認值下面有的例子有說明）
例子: 創(chuàng)建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**
例子: 創(chuàng)建一個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字節(jié)序格式讀取一個 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字節(jié)序格式讀取一個 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字節(jié)序格式讀取一個 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字節(jié)序格式讀取一個 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字節(jié)序格式讀取一個 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字節(jié)序格式讀取一個 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字節(jié)序格式將`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字節(jié)序格式將`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字節(jié)序格式將`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字節(jié)序格式將`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字節(jié)序格式將`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字節(jié)序格式將`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`。
為了避免創(chuàng)建大量獨立分配的 Buffer 帶來的垃圾回收開銷，默認情況下小于 4KB 的空間都是切割自一個較大的獨立對象。這種策略既提高了性能也改善了內存使用，因為 V8 不需要跟蹤和清理很多 `Persistent` 對象。
當開發(fā)者需要將池中一小塊數據保留不確定的一段時間，較為妥當的辦法是用 SlowBuffer 創(chuàng)建一個不被池管理的 Buffer 實例并將相應數據拷貝出來。
~~~
socket.on('readable', function() {
var data = socket.read();
// 為需要保留的數據分配內存
var sb = new SlowBuffer(10);
// 將數據拷貝到新的空間中
data.copy(sb, 0, 0, 10);
store.push(sb);
});
~~~
請謹慎使用，僅作為開發(fā)者頻繁觀察到他們的應用中過度的內存保留時的*最后*手段。
