Buffer -nodejs

纯 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'的别名.
'ucs2' - 'utf16le'的别名.
'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 ）

类方法: 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对象内容的改变而改变。

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)作为取值范围。

buf.toJSON()

返回一个 JSON表示的Buffer实例。JSON.stringify将会默认调用来字符串序列化这个Buffer实例

buf[index]

获取或者设置在指定index索引位置的8位字节。这个值是指单个字节，所以这个值必须在合法的范围，16进制的0x00 到0xFF，或者0 到255。

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 超越边界的，就将设置为他们的默认值。（译者：这个默认值下面有的例子有说明）

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

start Number类型, 可选参数, 默认: 0
end Number类型, 可选参数, 默认: buffer.length

返回一个新的buffer，这个buffer将会和老的buffer引用相同的内存地址，只是根据 start (默认是 0) 和end (默认是buffer.length) 偏移和裁剪了索引。负的索引是从buffer尾部开始计算的。

修改这个新的buffer实例slice切片，也会改变原来的buffer