// 说明
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 创建一个指定类型的数组有以下注意事项:
- buffer 的内存是复制的,不是共享的。
- 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。