Node.js Buffer(緩沖區)

JavaScript 語言自身隻有字元串資料類型，沒有二進制資料類型。

但在處理像TCP流或檔案流時，必須使用到二進制資料。是以在 Node.js中，定義了一個 Buffer 類，該類用來建立一個專門存放二進制資料的緩存區。

在 Node.js 中，Buffer 類是随 Node 核心一起釋出的核心庫。Buffer 庫為 Node.js 帶來了一種存儲原始資料的方法，可以讓 Node.js 處理二進制資料，每當需要在 Node.js 中處理I/O操作中移動的資料時，就有可能使用 Buffer 庫。原始資料存儲在 Buffer 類的執行個體中。一個 Buffer 類似于一個整數數組，但它對應于 V8 堆記憶體之外的一塊原始記憶體。

在v6.0之前建立Buffer對象直接使用new Buffer()構造函數來建立對象執行個體，但是Buffer對記憶體的權限操作相比很大，可以直接捕獲一些敏感資訊，是以在v6.0以後，官方文檔裡面建議使用 Buffer.from() 接口去建立Buffer對象。

Buffer 執行個體一般用于表示編碼字元的序列，比如 UTF-8 、 UCS2 、 Base64 、或十六進制編碼的資料。通過使用顯式的字元編碼，就可以在 Buffer 執行個體與普通的 JavaScript 字元串之間進行互相轉換。

Node.js 目前支援的字元編碼包括：

ascii - 僅支援 7 位 ASCII 資料。如果設定去掉高位的話，這種編碼是非常快的。

utf8 - 多位元組編碼的 Unicode 字元。許多網頁和其他文檔格式都使用 UTF-8 。

utf16le - 2 或 4 個位元組，小位元組序編碼的 Unicode 字元。支援代理對（U+10000 至 U+10FFFF）。

ucs2 - utf16le 的别名。

base64 - Base64 編碼。

latin1 - 一種把 Buffer 編碼成一位元組編碼的字元串的方式。

binary - latin1 的别名。

hex - 将每個位元組編碼為兩個十六進制字元。

Buffer 提供了以下 API 來建立 Buffer 類：

Buffer.alloc(size[, fill[, encoding]])： 傳回一個指定大小的 Buffer 執行個體，如果沒有設定 fill，則預設填滿 0

Buffer.allocUnsafe(size)： 傳回一個指定大小的 Buffer 執行個體，但是它不會被初始化，是以它可能包含敏感的資料

Buffer.allocUnsafeSlow(size)

Buffer.from(array)： 傳回一個被 array 的值初始化的新的 Buffer 執行個體（傳入的 array 的元素隻能是數字，不然就會自動被 0 覆寫）

Buffer.from(arrayBuffer[, byteOffset[, length]])： 傳回一個建立的與給定的 ArrayBuffer 共享同一記憶體的 Buffer。

Buffer.from(buffer)： 複制傳入的 Buffer 執行個體的資料，并傳回一個新的 Buffer 執行個體

Buffer.from(string[, encoding])： 傳回一個被 string 的值初始化的新的 Buffer 執行個體

寫入 Node 緩沖區的文法如下所示：

參數描述如下：

string - 寫入緩沖區的字元串。

offset - 緩沖區開始寫入的索引值，預設為 0 。

length - 寫入的位元組數，預設為 buffer.length

encoding - 使用的編碼。預設為 'utf8' 。

根據 encoding 的字元編碼寫入 string 到 buf 中的 offset 位置。 length 參數是寫入的位元組數。如果 buf 沒有足夠的空間儲存整個字元串，則隻會寫入 string 的一部分。隻部分解碼的字元不會被寫入。

傳回實際寫入的大小。如果 buffer 空間不足，則隻會寫入部分字元串。

執行以上代碼，輸出結果為：

讀取 Node 緩沖區資料的文法如下所示：

start - 指定開始讀取的索引位置，預設為 0。

end - 結束位置，預設為緩沖區的末尾。

解碼緩沖區資料并使用指定的編碼傳回字元串。

将 Node Buffer 轉換為 JSON 對象的函數文法格式如下：

當字元串化一個 Buffer 執行個體時，JSON.stringify() 會隐式地調用該 toJSON()。

傳回 JSON 對象。

Node 緩沖區合并的文法如下所示：

list - 用于合并的 Buffer 對象數組清單。

totalLength - 指定合并後Buffer對象的總長度。

傳回一個多個成員合并的新 Buffer 對象。

Node Buffer 比較的函數文法如下所示, 該方法在 Node.js v0.12.2 版本引入：

otherBuffer - 與 buf 對象比較的另外一個 Buffer 對象。

傳回一個數字，表示 buf 在 otherBuffer 之前，之後或相同。

Node 緩沖區拷貝文法如下所示：

targetBuffer - 要拷貝的 Buffer 對象。

targetStart - 數字, 可選, 預設: 0

sourceStart - 數字, 可選, 預設: 0

sourceEnd - 數字, 可選, 預設: buffer.length

沒有傳回值。

Node 緩沖區裁剪文法如下所示：

start - 數字, 可選, 預設: 0

end - 數字, 可選, 預設: buffer.length

傳回一個新的緩沖區，它和舊緩沖區指向同一塊記憶體，但是從索引 start 到 end 的位置剪切。

Node 緩沖區長度計算文法如下所示：

傳回 Buffer 對象所占據的記憶體長度。

以下列出了 Node.js Buffer 子產品常用的方法（注意有些方法在舊版本是沒有的）：

序号

方法 & 描述

new Buffer(size)

配置設定一個新的 size 大小機關為8位位元組的 buffer。注意, size 必須小于 kMaxLength，否則，将會抛出異常 RangeError。廢棄的: 使用 Buffer.alloc() 代替（或 Buffer.allocUnsafe()）。

new Buffer(buffer)

拷貝參數 buffer 的資料到 Buffer 執行個體。廢棄的: 使用 Buffer.from(buffer) 代替。

new Buffer(str[, encoding])

配置設定一個新的 buffer ，其中包含着傳入的 str 字元串。 encoding 編碼方式預設為 'utf8'。

廢棄的: 使用 Buffer.from(string[, encoding]) 代替。

buf.length

傳回這個 buffer 的 bytes 數。注意這未必是 buffer 裡面内容的大小。length 是 buffer 對象所配置設定的記憶體數，它不會随着這個 buffer 對象内容的改變而改變。

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

根據參數 offset 偏移量和指定的 encoding 編碼方式，将參數 string 資料寫入buffer。 offset 偏移量預設值是 0, encoding 編碼方式預設是 utf8。 length 長度是将要寫入的字元串的 bytes 大小。傳回 number 類型，表示寫入了多少 8 位位元組流。如果 buffer 沒有足夠的空間來放整個 string，它将隻會隻寫入部分字元串。 length 預設是 buffer.length - offset。這個方法不會出現寫入部分字元。

buf.writeUIntLE(value, offset, byteLength[, noAssert])

将 value 寫入到 buffer 裡，它由 offset 和 byteLength 決定，最高支援 48 位無符号整數，小端對齊，例如：

noAssert 值為 true 時，不再驗證 value 和 offset 的有效性。預設是 false。

buf.writeUIntBE(value, offset, byteLength[, noAssert])

将 value 寫入到 buffer 裡，它由 offset 和 byteLength 決定，最高支援 48 位無符号整數，大端對齊。noAssert 值為 true 時，不再驗證 value 和 offset 的有效性。預設是 false。

buf.writeIntLE(value, offset, byteLength[, noAssert])

将value 寫入到 buffer 裡，它由offset 和 byteLength 決定，最高支援48位有符号整數，小端對齊。noAssert 值為 true 時，不再驗證 value 和 offset 的有效性。預設是 false。

buf.writeIntBE(value, offset, byteLength[, noAssert])

将value 寫入到 buffer 裡，它由offset 和 byteLength 決定，最高支援48位有符号整數，大端對齊。noAssert 值為 true 時，不再驗證 value 和 offset 的有效性。預設是 false。

buf.readUIntLE(offset, byteLength[, noAssert])

支援讀取 48 位以下的無符号數字，小端對齊。noAssert 值為 true 時， offset 不再驗證是否超過 buffer 的長度，預設為 false。

buf.readUIntBE(offset, byteLength[, noAssert])

支援讀取 48 位以下的無符号數字，大端對齊。noAssert 值為 true 時， offset 不再驗證是否超過 buffer 的長度，預設為 false。

buf.readIntLE(offset, byteLength[, noAssert])

支援讀取 48 位以下的有符号數字，小端對齊。noAssert 值為 true 時， offset 不再驗證是否超過 buffer 的長度，預設為 false。

buf.readIntBE(offset, byteLength[, noAssert])

支援讀取 48 位以下的有符号數字，大端對齊。noAssert 值為 true 時， offset 不再驗證是否超過 buffer 的長度，預設為 false。

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

根據 encoding 參數（預設是 'utf8'）傳回一個解碼過的 string 類型。還會根據傳入的參數 start (預設是 0) 和 end (預設是 buffer.length)作為取值範圍。

buf.toJSON()

将 Buffer 執行個體轉換為 JSON 對象。

buf[index]

擷取或設定指定的位元組。傳回值代表一個位元組，是以傳回值的合法範圍是十六進制0x00到0xFF 或者十進制0至 255。

buf.equals(otherBuffer)

比較兩個緩沖區是否相等，如果是傳回 true，否則傳回 false。

buf.compare(otherBuffer)

比較兩個 Buffer 對象，傳回一個數字，表示 buf 在 otherBuffer 之前，之後或相同。

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

buffer 拷貝，源和目标可以相同。 targetStart 目标開始偏移和 sourceStart 源開始偏移預設都是 0。 sourceEnd 源結束位置偏移預設是源的長度 buffer.length 。

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

剪切 Buffer 對象，根據 start(預設是 0 ) 和 end (預設是 buffer.length ) 偏移和裁剪了索引。負的索引是從 buffer 尾部開始計算的。

buf.readUInt8(offset[, noAssert])

根據指定的偏移量，讀取一個無符号 8 位整數。若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。如果這樣 offset 可能會超出buffer 的末尾。預設是 false。

buf.readUInt16LE(offset[, noAssert])

根據指定的偏移量，使用特殊的 endian 位元組序格式讀取一個無符号 16 位整數。若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 offset 可能會超出 buffer 的末尾。預設是 false。

buf.readUInt16BE(offset[, noAssert])

根據指定的偏移量，使用特殊的 endian 位元組序格式讀取一個無符号 16 位整數，大端對齊。若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 offset 可能會超出 buffer 的末尾。預設是 false。

buf.readUInt32LE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個無符号 32 位整數，小端對齊。

若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 offset 可能會超出buffer 的末尾。預設是 false。

buf.readUInt32BE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個無符号 32 位整數，大端對齊。

buf.readInt8(offset[, noAssert])

根據指定的偏移量，讀取一個有符号 8 位整數。

若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 offset 可能會超出 buffer 的末尾。預設是 false。

buf.readInt16LE(offset[, noAssert])

根據指定的偏移量，使用特殊的 endian 格式讀取一個有符号 16 位整數，小端對齊。

buf.readInt16BE(offset[, noAssert])

根據指定的偏移量，使用特殊的 endian 格式讀取一個有符号 16 位整數，大端對齊。

buf.readInt32LE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個有符号 32 位整數，小端對齊。

buf.readInt32BE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個有符号 32 位整數，大端對齊。

buf.readFloatLE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個 32 位雙浮點數，小端對齊。

若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 offset 可能會超出buffer的末尾。預設是 false。

buf.readFloatBE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian 位元組序格式讀取一個 32 位雙浮點數，大端對齊。

buf.readDoubleLE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian位元組序格式讀取一個 64 位雙精度數，小端對齊。

buf.readDoubleBE(offset[, noAssert])

根據指定的偏移量，使用指定的 endian位元組序格式讀取一個 64 位雙精度數，大端對齊。

buf.writeUInt8(value, offset[, noAssert])

根據傳入的 offset 偏移量将 value 寫入 buffer。注意：value 必須是一個合法的無符号 8 位整數。

若參數 noAssert 為 true 将不會驗證 offset 偏移量參數。這意味着 value 可能過大，或者 offset 可能會超出 buffer 的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則不要使用。預設是 false。

buf.writeUInt16LE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer。注意：value 必須是一個合法的無符号 16 位整數，小端對齊。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value 可能過大，或者 offset 可能會超出buffer的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeUInt16BE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer。注意：value 必須是一個合法的無符号 16 位整數，大端對齊。

buf.writeUInt32LE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式(LITTLE-ENDIAN:小位元組序)将 value 寫入buffer。注意：value 必須是一個合法的無符号 32 位整數，小端對齊。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着value 可能過大，或者offset可能會超出buffer的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeUInt32BE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式(Big-Endian:大位元組序)将 value 寫入buffer。注意：value 必須是一個合法的有符号 32 位整數。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value 可能過大，或者offset可能會超出buffer的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeInt8(value, offset[, noAssert])

buf.writeInt16LE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer。注意：value 必須是一個合法的 signed 16 位整數。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value 可能過大，或者 offset 可能會超出 buffer 的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false 。

buf.writeInt16BE(value, offset[, noAssert])

buf.writeInt32LE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer。注意：value 必須是一個合法的 signed 32 位整數。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value 可能過大，或者 offset 可能會超出 buffer 的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeInt32BE(value, offset[, noAssert])

buf.writeFloatLE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer 。注意：當 value 不是一個 32 位浮點數類型的值時，結果将是不确定的。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value可能過大，或者 offset 可能會超出 buffer 的末尾進而造成 value 被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeFloatBE(value, offset[, noAssert])

buf.writeDoubleLE(value, offset[, noAssert])

根據傳入的 offset 偏移量和指定的 endian 格式将 value 寫入 buffer。注意：value 必須是一個有效的 64 位double 類型的值。

若參數 noAssert 為 true 将不會驗證 value 和 offset 偏移量參數。這意味着 value 可能過大，或者 offset 可能會超出 buffer 的末尾進而造成value被丢棄。除非你對這個參數非常有把握，否則盡量不要使用。預設是 false。

buf.writeDoubleBE(value, offset[, noAssert])

buf.fill(value[, offset][, end])

使用指定的 value 來填充這個 buffer。如果沒有指定 offset (預設是 0) 并且 end (預設是 buffer.length) ，将會填充整個buffer。