// 说明
    Node API 版本为 v0.10.31。
    中文参考：http://nodeapi.ucdok.com/#/api/，http://blog.sina.com.cn/oleoneoy
    本段为博主注解。

目录

● 缓冲区
    ○ Class: Buffer
       ■ new Buffer(size)
       ■ new Buffer(array)
       ■ new Buffer(str, [encoding])
       ■ Class Method: Buffer.isEncoding(encoding)
       ■ buf.write(string, [offset], [length], [encoding])
       ■ buf.toString([encoding], [start], [end])
       ■ buf.toJSON()
       ■ buf[index]
       ■ Class Method: Buffer.isBuffer(obj)
       ■ Class Method: Buffer.byteLength(string, [encoding])
       ■ Class Method: Buffer.concat(list, [totalLength])
       ■ buf.length
       ■ buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
       ■ buf.slice([start], [end])
       ■ buf.readUInt8(offset, [noAssert])
       ■ buf.readUInt16LE(offset, [noAssert])
       ■ buf.readUInt16BE(offset, [noAssert])
       ■ buf.readUInt32LE(offset, [noAssert])
       ■ buf.readUInt32BE(offset, [noAssert])
       ■ buf.readInt8(offset, [noAssert])
       ■ buf.readInt16LE(offset, [noAssert])
       ■ buf.readInt16BE(offset, [noAssert])
       ■ buf.readInt32LE(offset, [noAssert])
       ■ buf.readInt32BE(offset, [noAssert])
       ■ buf.readFloatLE(offset, [noAssert])
       ■ buf.readFloatBE(offset, [noAssert])
       ■ buf.readDoubleLE(offset, [noAssert])
       ■ buf.readDoubleBE(offset, [noAssert])
       ■ buf.writeUInt8(value, offset, [noAssert])
       ■ buf.writeUInt16LE(value, offset, [noAssert])
       ■ buf.writeUInt16BE(value, offset, [noAssert])
       ■ buf.writeUInt32LE(value, offset, [noAssert])
       ■ buf.writeUInt32BE(value, offset, [noAssert])
       ■ buf.writeInt8(value, offset, [noAssert])
       ■ buf.writeInt16LE(value, offset, [noAssert])
       ■ buf.writeInt16BE(value, offset, [noAssert])
       ■ buf.writeInt32LE(value, offset, [noAssert])
       ■ buf.writeInt32BE(value, offset, [noAssert])
       ■ buf.writeFloatLE(value, offset, [noAssert])
       ■ buf.writeFloatBE(value, offset, [noAssert])
       ■ buf.writeDoubleLE(value, offset, [noAssert])
       ■ buf.writeDoubleBE(value, offset, [noAssert])
       ■ buf.fill(value, [offset], [end])
    ○ buffer.INSPECT_MAX_BYTES
    ○ Class: SlowBuffer
 

 缓冲区

稳定性：3 - 稳定
    纯粹的 JavaScript 是 Unicode 友好的，但对二进制数据并非这样。当处理 TCP 流和文件流的时候，需要处理字节流。Node 有若干种方法来操作，创建和消费字节流。
    原始数据保存在 Buffer 类的实例中。一个 Buffer 和一个整数数组类似，但对应 V8 堆内存之外的原始内存分配区域。一个 Buffer 不能重置大小。
    Buffer 类是全局变量，令其非常罕见地不需要 require('buffer')。
    在 Buffer 和 JavaScript 字符串对象间转换需要明确的编码方法。下面是不同的字符串编码。
  • 'ascii'——只有7位 ASCII 数据。这种编码方法非常快，且会忽略最高位如果设置了的话。注意如果从字符串转换成缓冲区，这种编码将空字符（'\0' 或 '\u0000'）转换成 0x20（空格的字符编码）。如果你想讲空字符转换成 0x00，你应该使用 'utf8'。
  • 'utf8'——多字节编码的 Unicode 字符。很多 web 页面和其他文档格式使用 UTF-8。
  • 'utf16le'——2或4字节，小端编码的 Unicode 字符。代理对（U+10000 至 U+10FFF）是被支持的。
  • 'ucs2'——'utf16le' 的别名。
  • 'base64'——Base64 字符串编码。
  • 'binary'——只使用每个字符的前8位来将原始二进制数据编码成字符串的一种方式。这种编码方法是被反对的，且若如可能应避免使用并用 Buffer 对象取代。这种编码将在 Node 的未来版本移除。
  • 'hex'——将每个字节编码成两个十六进制字符。
    从一个 Buffer 创建一个指定类型的数组有以下注意事项：
  1. buffer 的内存是复制的，不是共享的。
  2. buffer 的内存当作成一个数组，而不是字节数组。亦即，new Uint32Array(new Buffer([1, 2, 3, 4]) 创建一个带有元素 [1, 2, 3, 4] 的4元素 Uint32Array，而不是只有一个元素 [0x1020304] 或 [0x4030201] 的 Uint32Array。
    注意：Node.js v0.8 简单地记住 array.buffer 中的缓冲区引用而不是复制它。
    当更高效地，它对指定类型的数组规格引入了微妙的不兼容。ArrayBuffer #slice() 从切片复制一份拷贝，而 Buffer #slice() 创建一个视图。

Class: Buffer

    Buffer 类是一个用来直接处理二进制数据的全局类型。它可以用多种方式构造。

new Buffer(size)

  • size 数值类型

    分配一个 size 字节的新缓冲区。

new Buffer(array)

  • array 数组类型

    使用 array 作为字节数组分配新的缓冲区。

new Buffer(str, [encoding])

  • str 字符串类型 —— 需编码的字符串。
  • encoding 字符串类型 —— 使用的编码，可选。

    分配一个包含给出的 str 的新缓冲区。encoding 默认为 'utf8'。

Class Method: Buffer.isEncoding(encoding)

  • encoding 字符串类型 —— 要测试的编码的字符串

    如果 encoding 是有效的编码参数返回 true，否则返回 false。

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

  • string 字符串类型 —— 要写入缓冲区的数据
  • offset 数值类型，可选，默认值：0
  • length 数值类型，可循环，默认值：buffer.length - offset
  • encoding 字符串类型，可选，默认值：'utf8'

    使用给出的编码将 string 写入缓冲区的 offset 位置。offset 默认为0，encoding 默认为 'utf8'。length 是要写入的字节数量。返回写入的字节数量。如果 buffer 没有足够的空间来容纳整个字符串，它将写入字符串的一部分。length 默认为 buffer.length - offset。本方法不会写入字符的一部分。

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

    写入的字符数量（可能与写入的字节数量不相同）在 Buffer._charWritten 中设置，并会在下一次 buf.write() 调用时重写。

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

  • encoding 字符串类型，可选，默认值：'utf8'
  • start 数值类型，可选，默认值：0
  • end 数值类型，可选，默认值：buffer.length

    从使用 encoding（默认为 'utf8'）编码以 start（默认为0）开始到 end（默认为 buffer.length）结束的缓冲区数据解码并返回一个字符串。
    参看以上 buffer.write() 的例子。

buf.toJSON()

    返回 Buffer 实例的 JSON 表示，这与 JSON 的数组的输出是一致的。当序列化一个 Buffer 实例时 JSON.stringify 会隐含地调用这个函数。
    例子：

1 var buf = new Buffer('test');
2 var json = JSON.stringify(buf);
3 
4 console.log(json);
5 // '[116,101,115,116]'
6 
7 var copy = new Buffer(JSON.parse(json));
8 console.log(copy);
9 // <Buffer 74 65 73 74>

buf[index]

    获取和设置 index 处的字节。这个值指定为单个字节的值，所以合法的范围是在十六进制的 0x00 和 0xFF 或 0 和 255 之间。
    例子：复制一个 ASCII 字符串至缓冲区中，一次一个字节：

 1 str = "node.js";
 2 buf = new Buffer(str.length);
 3 
 4 for (var i = 0; i < str.length; i++) {
 5   buf[i] = str.charCodeAt(i);
 6 }
 7 
 8 console.log(buf);
 9 
10 // node.js

Class Method: Buffer.isBuffer(obj)

  • obj 对象类型
  • 返回值：布尔类型

    测试 obj 是否是一个 Buffer。

Class Method: Buffer.byteLength(string, [encoding])

  • string 字符串类型
  • encoding 字符串类型，可选，默认值：'utf8'
  • 返回值：数值类型

    给出字符串的实际字节数。encoding 默认为 'utf8'。这与 String.prototype.length 不一样，因为那返回字符串的字符数量。
    例子：

1 str = '\u00bd + \u00bc = \u00be';
2 
3 console.log(str + ": " + str.length + " characters, " +
4     Buffer.byteLength(str, 'utf8') + " bytes");
5 
6 // ½ + ¼ = ¾: 9 characters, 12 bytes

Class Method: Buffer.concat(list, [totalLength])

  • list 数组类型 待连接的 Buffer 对象数组
  • totalLength 数值类型 连接后的总长度

    返回把 list 中的所有 buffer 连接到一起的 buffer。
    如果 list 中没有元素，或 totalLength 为 0，那么将返回一个 0 长的 buffer。
    如果 list 只有一个元素，那么 list 中的第一个元素将被返回。
    如果 list 有多于一个元素，那么返回一个新的 Buffer。
    如果 totalLength 没有提供，将从 list 中读取。不过，这将在这个函数的执行中添加一个额外的循环，所以明确提供一个长度将更快些。

buf.length

  • 数值类型

    buffer 的字节大小。注意这并非必定是内容的大小。length 表示为 buffer 对象分配的内存大小。当缓冲区内容改变时它是不会改变的。

1 buf = new Buffer(1234);
2 
3 console.log(buf.length);
4 buf.write("some string", 0, "ascii");
5 console.log(buf.length);
6 
7 // 1234
8 // 1234

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

  • targetBuffer Buffer 对象 - 复制到的 Buffer
  • targetStart 数值类型，可选，默认值：0
  • sourceStart 数值类型，可选，默认值：0
  • sourceEnd 数值类型，可选，默认值：buffer.length

    在两个 buffer 之间复制。源区域与目的区域可以重叠。targetStart 和 sourceStart 默认为 0。sourceEnd 默认为 buffer.length。
    所有传递的为 undefined/NaN 或越界的值均设置为它们各自的默认值。
    例子：创建两个 Buffer，然后将 buf1 从 16 字节到 19 字节复制到 buf2，buf2 开始于第 8 字节。

 1 buf1 = new Buffer(26);
 2 buf2 = new Buffer(26);
 3 
 4 for (var i = 0; i < 26; i++)｛
 5     buf1[i] = i + 97; // 97 is ASCII a
 6     buf[i] = 33; // ASCII !
 7 }
 8 
 9 buf1.copy(buf2, 8, 16, 20);
10 console.log(buf2.toString('ascii', 0, 25));
11 
12 // !!!!!!!!qrst!!!!!!!!!!!!!!

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

  • start 数值类型，可选，默认值：0
  • end 数值类型，可选，默认值：buffer.length

    返回和原来的 buffer 引用同一段内存的新 buffer，只是偏移并用 start（默认为0）和 end（默认为 buffer.length）索引裁剪了。负索引从 buffer 的结束开始。
    修改 slice 出来的新 buffer 将修改原始 buffer 的内存！
    例子：使用 ASCII 字母表创建一个 Buffer，创建一个切片，然后从原始 Buffer 中修改一个字节。

var buf1 = new Buffer(26);

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

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

// abc
// !bc

buf.readUInt8(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移 offset 读取无符号八位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    示例：

var buf = new Buffer(4);

buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;

for (ii = 0; ii < buf.length; ii++)｛
    console.log(buf.readUInt8(ii));
}

// 0x3
// 0x4
// 0x23
// 0x42

buf.readUInt16LE(offset, [noAssert])
buf.readUInt16BE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个无符号16位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    示例：

var buf = new Buffer(4);

buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;

console.log(buf.readUInt16BE(0));
console.log(buf.readUInt16LE(0));
console.log(buf.readUInt16BE(1));
console.log(buf.readUInt16LE(1));
console.log(buf.readUInt16BE(2));
console.log(buf.readUInt16LE(2));

// 0x0304
// 0x0403
// 0x0423
// 0x2304
// 0x2342
// 0x4223

buf.readUInt32LE(offset, [noAssert])
buf.readUInt32BE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个无符号32位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    示例：

 

var buf = new Buffer(4);

buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;

console.log(buf.readUInt32BE(0));
cosnole.log(buf.readUInt32LE(0));

// 0x03042342
// 0x42230403

buf.readInt8(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移 offset 读取有符号八位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    工作过程和 buffer.readUInt8 一样，除了 buffer 的内容当作成2的补码的有符号值。

buf.readInt16LE(offset, [noAssert])
buf.readInt16BE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个有符号16位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    工作过程和 buffer.readUInt16* 一样，除了 buffer 的内容当作成2的补码的有符号值。

buf.readInt32LE(offset, [noAssert])
buf.readInt32BE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个有符号32位整数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    工作过程和 buffer.readUInt32* 一样，除了 buffer 的内容当作成2的补码的有符号值。

buf.readFloatLE(offset, [noAssert])
buf.readFloatBE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个32位浮点数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    示例：

var buf = new Buffer(4);

buf[0] = 0x00;
buf[1] = 0x00;
buf[2] = 0x80;
buf[3] = 0x3f;

console.log(buf.readFloatLE(0));

// 0x01

buf.readDoubleLE(offset, [noAssert])
buf.readDoubleBE(offset, [noAssert])

  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false
  • 返回值：数值类型

    从 buffer 的指定偏移以指定的端序读取一个64为双精度浮点数。
    将 noAssert 设置为 true 可跳过 offset 的验证。这意味着 offset 可能越过 buffer 的尾部。默认为 false。
    示例：

var buf = new Buffer(8);

buf[0] = 0x55;
buf[1] = 0x55;
buf[2] = 0x55;
buf[3] = 0x55;
buf[4] = 0x55;
buf[5] = 0x55;
buf[6] = 0xd5;
buf[7] = 0x3f;

console.log(buf.readDoubleLE(0));

// 0.3333333333333333

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移写入值 value。注意，value 必须是一个有效的无符号8位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    示例：

var buf = new Buffer(4);
buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);

console.log(buf);

// <Buffer 03 04 23 42>

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定的端序写入值 value。注意，value 必须是一个有效的无符号16位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    示例：

var buf = new Buffer(4);
buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);

console.log(buf);

buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);

console.log(buf);

// <Buffer de ad be ef>
// <Buffer ad de ef be>

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定的端序写入值 value。注意，value 必须是一个有效的无符号32位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    示例：

var buf = new Buffer(4);
buf.writeUInt32BE(0xfeedface, 0);

console.log(buf);

buf.writeUInt23LE(0xfeedface, 0);

console.log(buf);

// <Buffer fe ed fa ce>
// <Buffer ce fa ed fe>

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移写入值 value。注意，value 必须是一个有效的有符号8位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    工作过程和 buffer.writeUInt8 一样，除了 value 被当作成2的补码的有符号值写进 buffer。

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定端序写入值 value。注意，value 必须是一个有效的有符号16位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    工作过程和 buffer.writeUInt16* 一样，除了 value 被当作成2的补码的有符号值写进 buffer。

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定端序写入值 value。注意，value 必须是一个有效的有符号32位整数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    工作过程和 buffer.writeUInt32* 一样，除了 value 被当作成2的补码的有符号值写进 buffer。

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定端序写入值 value。注意，如果 value 不是一个32位浮点数，其行为是不确定的。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    示例：

var buf = new Buffer(4);
buf.writeFloatBE(0xcafebabe, 0);

console.log(buf);

buf.writeFloatLE(0xcafebabe, 0);

// <Buffer 4f 4a fe bb>
// <Buffer bb fe 4a 4f>

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

  • value 数值类型
  • offset 数值类型
  • noAssert 布尔值类型，可选，默认值：false

    向 buffer 的指定偏移以指定端序写入值 value。注意，value 必须是一个64位浮点数。
    将 noAssert 设置为 true 可跳过 value 和 offset 的验证。这意味着 value 可能对该函数来说太大或 offset 可能越过 buffer 的尾部，导致值被悄悄地截断。这不应该被使用除非你能确保正确性。默认为 false。
    示例：

var buf = new Buffer(8);
buf.writeDoubleBE(0xdeadbeefcafebabe, 0);

console.log(buf);

buf.writeDoubleLE(0xdeadbeefcafebabe, 0);

console.log(buf);

// <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 数值类型，可选
  • end 数值类型，可选

    以指定的值填充 buffer。如果 offset（默认为 0 ）和 end（默认为 buffer.length ）没有给出，将填充整个 buffer。

var b = new Buffer(50);
b.fill("h");

buffer.INSPECT_MAX_BYTES

  • 数值类型，默认值：50

    当调用 buffer.inspect() 时多少字节将被返回。这可以被用户模块重写。
    注意这是 require('buffer') 返回的 buffer 模块的属性，不是在 Buffer 全局对象上，也不是在 buffer 实例上。

Class: SlowBuffer

    这个类主要是作为内部使用。JavaScript 程序应该使用 Buffer 而不是 SlowBuffer。
    为了避免在服务器的生存期内经常为小块的内存分配很多 C++ Buffer 对象，Node 以 8Kb（8192 字节）为一块分配内存。如果 buffer 比这个大小还要小，那么它将依附于一个 SlowBuffer 父对象。如果它这个大小要大，那么 Node 将直接为它创建一个 SlowBuffer slab。