Node.js v10.14.2 文档


目录

Buffer(缓冲器)#

中英对照

稳定性: 2 - 稳定的

在引入 TypedArray 之前,JavaScript 没有读取或操作二进制数据流的机制。 Buffer 类用于在 TCP 流或文件系统操作等场景中处理字节流。

现在有了 TypedArrayBuffer 类以一种更优化、更适合 Node.js 的方式实现了 Uint8Array

Buffer 类的实例类似于整数数组,但 Buffer 的大小是固定的、且在 V8 堆外分配物理内存。 Buffer 的大小在创建时确定,且无法改变。

Buffer 类是一个全局变量,使用时无需 require('buffer').Buffer

// 创建一个长度为 10、且用 0 填充的 Buffer。
const buf1 = Buffer.alloc(10);

// 创建一个长度为 10、且用 0x1 填充的 Buffer。 
const buf2 = Buffer.alloc(10, 1);

// 创建一个长度为 10、且未初始化的 Buffer。
// 这个方法比调用 Buffer.alloc() 更快,但返回的 Buffer 实例可能包含旧数据,因此需要使用 fill() 或 write() 重写。
const buf3 = Buffer.allocUnsafe(10);

// 创建一个包含 [0x1, 0x2, 0x3] 的 Buffer。
const buf4 = Buffer.from([1, 2, 3]);

// 创建一个包含 UTF-8 字节 [0x74, 0xc3, 0xa9, 0x73, 0x74] 的 Buffer。
const buf5 = Buffer.from('tést');

// 创建一个包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的 Buffer。
const buf6 = Buffer.from('tést', 'latin1');

Buffer.from()、Buffer.alloc() 与 Buffer.allocUnsafe()#

中英对照

在 Node.js v6.0.0 之前,Buffer 实例是通过 Buffer 构造函数创建的,它根据参数返回不同的 Buffer

  • 传入数值(如 new Buffer(10)),则分配一个指定大小的 Buffer 对象。 在 Node.js v8.0.0 之前,分配给这种 Buffer 实例的内存是未初始化的,可能包含旧数据。 这种 Buffer 实例随后必须被初始化,可以使用 buf.fill(0) 或写满这个 Buffer。 虽然这是为了提高性能而有意为之的,但开发经验表明,创建一个快速但未初始化的 Buffer 与创建一个慢点但更安全的 Buffer 之间需要有更明确的区分。 从 Node.js v8.0.0 开始, Buffer(num)new Buffer(num) 将返回已初始化的 Buffer
  • 传入字符串、数组、或 Buffer,则将传入的数据拷贝到 Buffer
  • 传入 ArrayBufferSharedArrayBuffer,则返回一个与传入的对象共享内存的 Buffer

因为 new Buffer() 会根据参数的类型而不同,所以如果没有正确地校验传给 new Buffer() 的参数、就可能引起安全性与可靠性问题。

为了使 Buffer 实例的创建更可靠,new Buffer() 构造函数已被废弃,建议使用 Buffer.from()Buffer.alloc()、和 Buffer.allocUnsafe()

--zero-fill-buffers 命令行选项#

中英对照

使用 --zero-fill-buffers 命令行选项时,new Buffer(size)Buffer.allocUnsafe()Buffer.allocUnsafeSlow()new SlowBuffer(size) 返回的 Buffer 在创建时会用 0 填充。

$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
<Buffer 00 00 00 00 00>

Buffer.allocUnsafe() 与 Buffer.allocUnsafeSlow() 不安全的原因#

中英对照

当调用 Buffer.allocUnsafe()Buffer.allocUnsafeSlow() 时,分配的内存是未初始化的(没有用 0 填充)。 虽然这样的设计使得内存的分配非常快,但分配的内存可能包含旧数据。 如果没有完全地重写内存,当读取 Buffer 时,旧数据就泄露了。

Buffer 与字符编码#

中英对照

Buffer 存入或取出字符串时,需要指定字符编码。

const buf = Buffer.from('hello world', 'ascii');

console.log(buf.toString('hex'));
// 输出: 68656c6c6f20776f726c64

console.log(buf.toString('base64'));
// 输出: aGVsbG8gd29ybGQ=

console.log(Buffer.from('fhqwhgads', 'ascii'));
// 输出: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// 输出: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>

Node.js 支持的字符编码有:

  • 'ascii' - 仅支持 7 位 ASCII 数据。

  • 'utf8' - 多字节编码的 Unicode 字符。

  • 'utf16le' - 2 或 4 个字节,小端序编码的 Unicode 字符。支持代理对(U+10000 至 U+10FFFF)。

  • 'ucs2' - 'utf16le' 的别名。

  • 'base64' - Base64 编码。

  • 'latin1' - 将 Buffer 编码成单字节编码的字符串。

  • 'binary' - 'latin1' 的别名。

  • 'hex' - 将每个字节编码成两个十六进制字符。

Buffer 与 TypedArray#

中英对照

Buffer 实例也是 Uint8Array 实例,但是与 TypedArray 有微小的不同。 例如,ArrayBuffer#slice() 会创建切片的拷贝,而 Buffer#slice() 是在现有的 Buffer 上创建而不拷贝。

使用 TypeArray.buffer 属性可以创建一个与其共享内存的 Buffer

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// 拷贝 `arr` 的内容。
const buf1 = Buffer.from(arr);
// 与 `arr` 共享内存。
const buf2 = Buffer.from(arr.buffer);

console.log(buf1);
// 输出: <Buffer 88 a0>
console.log(buf2);
// 输出: <Buffer 88 13 a0 0f>

arr[1] = 6000;

console.log(buf1);
// 输出: <Buffer 88 a0>
console.log(buf2);
// 输出: <Buffer 88 13 70 17>

当使用 TypedArray.buffer 创建 Buffer 时,也可以通过传入 byteOffsetlength 参数只使用 ArrayBuffer 的一部分。

const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);

console.log(buf.length);
// 输出: 16

Buffer.from()TypedArray.from() 有着不同的实现。 TypedArray 可以有映射函数,对类型数组的每个元素各调用一次:

  • TypedArray.from(source[, mapFn[, thisArg]])

Buffer.from() 不支持映射函数:

Buffer 与迭代器#

中英对照

Buffer 可以使用 for..of 进行迭代:

const buf = Buffer.from([1, 2, 3]);

// 输出:
//   1
//   2
//   3
for (const b of buf) {
  console.log(b);
}

还可以使用 buf.values()buf.keys()、与 buf.entries() 创建迭代器。

Buffer 类#

中英对照

Buffer 类是一个全局变量,用于直接处理二进制数据。

new Buffer(array)#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.from(array) 代替。

Allocates a new Buffer using an array of octets.

// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

new Buffer(arrayBuffer[, byteOffset[, length]])#

暂无中英对照

This creates a view of the ArrayBuffer or SharedArrayBuffer without copying the underlying memory. For example, when passed a reference to the .buffer property of a TypedArray instance, the newly created Buffer will share the same allocated memory as the TypedArray.

The optional byteOffset and length arguments specify a memory range within the arrayBuffer that will be shared by the Buffer.

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// Shares memory with `arr`
const buf = new Buffer(arr.buffer);

console.log(buf);
// Prints: <Buffer 88 13 a0 0f>

// Changing the original Uint16Array changes the Buffer also
arr[1] = 6000;

console.log(buf);
// Prints: <Buffer 88 13 70 17>

new Buffer(buffer)#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.from(buffer) 代替。

Copies the passed buffer data onto a new Buffer instance.

const buf1 = new Buffer('buffer');
const buf2 = new Buffer(buf1);

buf1[0] = 0x61;

console.log(buf1.toString());
// Prints: auffer
console.log(buf2.toString());
// Prints: buffer

new Buffer(size)#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.alloc() 代替 (或 Buffer.allocUnsafe())。

  • size <integer> The desired length of the new Buffer.

Allocates a new Buffer of size bytes. If size is larger than buffer.constants.MAX_LENGTH or smaller than 0, ERR_INVALID_OPT_VALUE is thrown. A zero-length Buffer is created if size is 0.

Prior to Node.js 8.0.0, the underlying memory for Buffer instances created in this way is not initialized. The contents of a newly created Buffer are unknown and may contain sensitive data. Use Buffer.alloc(size) instead to initialize a Buffer with zeroes.

const buf = new Buffer(10);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>

new Buffer(string[, encoding])#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.from(string[, encoding]) 代替。

  • string <string> String to encode.
  • encoding <string> The encoding of string. Default: 'utf8'.

Creates a new Buffer containing string. The encoding parameter identifies the character encoding of string.

const buf1 = new Buffer('this is a tést');
const buf2 = new Buffer('7468697320697320612074c3a97374', 'hex');

console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('ascii'));
// Prints: this is a tC)st

Buffer.alloc(size[, fill[, encoding]])#

中英对照

  • size <integer> 新建的 Buffer 的长度。
  • fill <string> | <Buffer> | <integer> 预填充 Buffer 的值。默认为 0
  • encoding <string> 如果 fill 是字符串,则指定 fill 的字符编码。默认为 'utf8'

创建一个大小为 size 字节的 Buffer。 如果 fillundefined,则用 0 填充 Buffer

const buf = Buffer.alloc(5);

console.log(buf);
// 输出: <Buffer 00 00 00 00 00>

如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0,则抛出 ERR_INVALID_OPT_VALUE。 如果 size 为 0,则创建一个长度为 0 的 Buffer

如果指定了 fill,则调用 buf.fill(fill) 初始化 Buffer

const buf = Buffer.alloc(5, 'a');

console.log(buf);
// 输出: <Buffer 61 61 61 61 61>

如果同时指定了 fillencoding,则调用 buf.fill(fill, encoding) 初始化 Buffer

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');

console.log(buf);
// 输出: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>

Buffer.alloc()Buffer.allocUnsafe() 慢,但能确保新建的 Buffer 不会包含旧数据。

Buffer.allocUnsafe(size)#

中英对照

  • size <integer> 新建的 Buffer 的长度。

创建一个大小为 size 字节的 Buffer。 如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0,则抛出 ERR_INVALID_OPT_VALUE。 如果 size 为 0,则创建一个长度为 0 的 Buffer

以这种方式创建的 Buffer 的内存是未初始化的。 Buffer 的内容是未知的,可能包含敏感数据。 使用 Buffer.alloc() 可以创建已初始化的 Buffer

const buf = Buffer.allocUnsafe(10);

console.log(buf);
// 输出: <Buffer a0 8b 28 3f 01 00 00 00 50 32>
// (输出的内容是内存的旧数据,每次都不同)

buf.fill(0);

console.log(buf);
// 输出: <Buffer 00 00 00 00 00 00 00 00 00 00>

Buffer.allocUnsafeSlow(size)#

中英对照

  • size <integer> 新建的 Buffer 的长度。

创建一个大小为 size 字节的 Buffer。 如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0,则抛出 ERR_INVALID_OPT_VALUE。 如果 size 为 0,则创建一个长度为 0 的 Buffer

以这种方式创建的 Buffer 的内存是未初始化的。 Buffer 的内容是未知的,可能包含敏感数据。 使用 buf.fill(0) 可以初始化 Buffer

当使用 Buffer.allocUnsafe() 创建 Buffer 时,如果要分配的内存小于 4KB,则会从一个预分配的 Buffer 切割出来。 这可以避免垃圾回收机制因创建太多独立的 Buffer 而过度使用。

当需要在内存池保留一小块内存时,可以使用 Buffer.allocUnsafeSlow() 创建一个非内存池的 Buffer 并拷贝出来。

// 保留一小块内存。
const store = [];

socket.on('readable', () => {
  const data = socket.read();

  // 分配内存。
  const sb = Buffer.allocUnsafeSlow(10);

  // 拷贝数据到内存。
  data.copy(sb, 0, 0, 10);

  store.push(sb);
});

Buffer.byteLength(string[, encoding])#

中英对照

返回字符串的实际字节长度。 与 String.prototype.length 不同,后者返回字符串的字符数。

const str = '\u00bd + \u00bc = \u00be';

console.log(`${str}: ${str.length} 个字符, ` +
            `${Buffer.byteLength(str, 'utf8')} 个字节`);
// 输出: ½ + ¼ = ¾: 9 个字符, 12 个字节

Buffer.compare(buf1, buf2)#

中英对照

比较 buf1buf2,主要用于 Buffer 数组的排序。 相当于调用 buf1.compare(buf2)

const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
const arr = [buf1, buf2];

console.log(arr.sort(Buffer.compare));
// 输出: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (相当于: [buf2, buf1])

Buffer.concat(list[, totalLength])#

中英对照

返回一个合并了 list 中所有 Buffer 的新 Buffer

如果 list 中没有元素、或 totalLength 为 0,则返回一个长度为 0 的 Buffer

如果没有指定 totalLength,则计算 list 中的 Buffer 的总长度。

如果 list 中的 Buffer 的总长度大于 totalLength,则合并后的 Buffer 会被截断到 totalLength 的长度。

// 用含有三个 `Buffer` 的数组创建一个单一的 `Buffer`。
const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;

console.log(totalLength);
// 输出: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);

console.log(bufA);
// 输出: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// 输出: 42

Buffer.from(array)#

中英对照

使用字节数组 array 创建 Buffer

// 创建一个包含字符串 'buffer' 的 UTF-8 字节的 Buffer。
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

Buffer.from(arrayBuffer[, byteOffset[, length]])#

中英对照

创建 ArrayBuffer 的视图,但不会拷贝底层内存。 例如,当传入 TypedArray.buffer 属性的引用时,新建的 Buffer 会与 TypedArray 共享同一内存。

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// 与 `arr` 共享内存。
const buf = Buffer.from(arr.buffer);

console.log(buf);
// 输出: <Buffer 88 13 a0 0f>

// 改变原先的 Uint16Array 也会改变 Buffer。
arr[1] = 6000;

console.log(buf);
// 输出: <Buffer 88 13 70 17>

byteOffsetlength 指定 arrayBuffer 中与 Buffer 共享的内存范围。

const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);

console.log(buf.length);
// 输出: 2

Buffer.from(buffer)#

中英对照

拷贝 buffer 的数据到新建的 Buffer

const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);

buf1[0] = 0x61;

console.log(buf1.toString());
// 输出: auffer
console.log(buf2.toString());
// 输出: buffer

Buffer.from(string[, encoding])#

中英对照

  • string <string> 要编码的字符串。
  • encoding <string> string 的字符编码。默认为 'utf8'

创建一个包含 stringBuffer

const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');

console.log(buf1.toString());
// 输出: this is a tést
console.log(buf2.toString());
// 输出: this is a tést
console.log(buf1.toString('ascii'));
// 输出: this is a tC)st

Buffer.from(object[, offsetOrEncoding[, length]])#

中英对照

  • object <Object> 支持 Symbol.toPrimitivevalueOf() 的对象。
  • offsetOrEncoding <number> | <string> 字节偏移量或字符编码,取决于 object.valueOf()object[Symbol.toPrimitive]() 返回的值。
  • length <number> 长度,取决于 object.valueOf()object[Symbol.toPrimitive]() 的返回值。

对于 valueOf() 返回值不严格等于 object 的对象,返回 Buffer.from(object.valueOf(), offsetOrEncoding, length)

const buf = Buffer.from(new String('this is a test'));
// 输出: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

对于支持 Symbol.toPrimitive 的对象,会返回 Buffer.from(object[Symbol.toPrimitive](), offsetOrEncoding, length)

class Foo {
  [Symbol.toPrimitive]() {
    return 'this is a test';
  }
}

const buf = Buffer.from(new Foo(), 'utf8');
// 输出: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

Buffer.isBuffer(obj)#

中英对照

如果 obj 是一个 Buffer,则返回 true,否则返回 false

Buffer.isEncoding(encoding)#

中英对照

如果 encoding 是支持的字符编码,则返回 true,否则返回 false

Buffer.poolSize#

中英对照

指定预分配的 Buffer 池的大小(以字节为单位)。 该值可以修改。

buf[index]#

中英对照

索引操作符 [index] 可用于获取或设置 buf 中指定位置的字节。 该值指向单个字节,所以有效的值的范围是 0x000xFF(十六进制),或 0255(十进制)。

该操作符继承自 Uint8Array,所以对越界访问的处理与 UInt8Array 相同(取值时返回 undefined,赋值时不作为)。

// 拷贝 ASCII 字符串到 `Buffer`,每次拷贝一个字节。

const str = 'http://nodejs.cn/';
const buf = Buffer.allocUnsafe(str.length);

for (let i = 0; i < str.length; i++) {
  buf[i] = str.charCodeAt(i);
}

console.log(buf.toString('ascii'));
// 输出: http://nodejs.cn/

buf.buffer#

中英对照

const arrayBuffer = new ArrayBuffer(16);
const buffer = Buffer.from(arrayBuffer);

console.log(buffer.buffer === arrayBuffer);
// 输出: true

buf.byteOffset#

中英对照

  • <integer> Buffer 底层的 ArrayBuffer 对象的 byteOffset

Buffer.from(ArrayBuffer, byteOffset, length) 设置了 byteOffset 或创建一个小于 Buffer.poolSizeBuffer 时,底层的 ArrayBuffer 的偏移量并不是从 0 开始。

当直接使用 buf.buffer 访问底层的 ArrayBuffer 时,ArrayBuffer 的第一个字节可能并不指向 buf 对象。

所有使用 Buffer 创建 TypedArray 时,需要正确地指定 byteOffset

// 创建一个小于 `Buffer.poolSize` 的 `Buffer`。
const nodeBuffer = new Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

// 将 `Buffer` 赋值给一个 `Int8Array`。
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);

buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])#

中英对照

  • target <Buffer> | <Uint8Array> 要与 buf 对比的 BufferUint8Array
  • targetStart <integer> target 中开始对比的偏移量。默认为 0
  • targetEnd <integer> target 中结束对比的偏移量(不包含)。默认为 target.length
  • sourceStart <integer> buf 中开始对比的偏移量。默认为 0
  • sourceEnd <integer> buf 中结束对比的偏移量(不包含)。默认为 buf.length
  • 返回: <integer>

对比 buftarget,并返回一个数值,表明 buf 在排序上是否排在 target 前面、或后面、或相同。 对比是基于各自 Buffer 实际的字节序列。

  • 如果 targetbuf 相同,则返回 0
  • 如果 target 排在 buf 前面,则返回 1
  • 如果 target 排在 buf 后面,则返回 -1
const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('BCD');
const buf3 = Buffer.from('ABCD');

console.log(buf1.compare(buf1));
// 输出: 0
console.log(buf1.compare(buf2));
// 输出: -1
console.log(buf1.compare(buf3));
// 输出: -1
console.log(buf2.compare(buf1));
// 输出: 1
console.log(buf2.compare(buf3));
// 输出: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare));
// 输出: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (相当于: [buf1, buf3, buf2])

targetStarttargetEndsourceStartsourceEnd 可用于指定 targetbuf 中对比的范围。

const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);

console.log(buf1.compare(buf2, 5, 9, 0, 4));
// 输出: 0
console.log(buf1.compare(buf2, 0, 6, 4));
// 输出: -1
console.log(buf1.compare(buf2, 5, 6, 5));
// 输出: 1

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])#

中英对照

  • target <Buffer> | <Uint8Array> 要拷贝进的 BufferUint8Array
  • targetStart <integer> target 中开始写入的偏移量。默认为 0
  • sourceStart <integer> buf 中开始拷贝的偏移量。默认为 0
  • sourceEnd <integer> buf 中结束拷贝的偏移量(不包含)。默认为 buf.length
  • 返回: <integer> 拷贝的字节数。

拷贝 buf 中某个区域的数据到 target 中的某个区域,即使 target 的内存区域与 buf 的重叠。

// 创建两个 `Buffer`。
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');

for (let i = 0; i < 26; i++) {
  // 97 是 'a' 的十进制 ASCII 值。
  buf1[i] = i + 97;
}

// 拷贝 `buf1` 中第 16 至 19 字节偏移量的数据到 `buf2` 第 8 字节偏移量开始。
buf1.copy(buf2, 8, 16, 20);

console.log(buf2.toString('ascii', 0, 25));
// 输出: !!!!!!!!qrst!!!!!!!!!!!!!
// 创建一个 `Buffer`,并拷贝同一 `Buffer` 中一个区域的数据到另一个重叠的区域。

const buf = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 是 'a' 的十进制 ASCII 值。
  buf[i] = i + 97;
}

buf.copy(buf, 0, 4, 10);

console.log(buf.toString());
// 输出: efghijghijklmnopqrstuvwxyz

buf.entries()#

中英对照

buf 的内容创建并返回一个 [index, byte] 形式的迭代器

// 输出 `Buffer` 的全部内容。

const buf = Buffer.from('buffer');

for (const pair of buf.entries()) {
  console.log(pair);
}
// 输出:
//   [0, 98]
//   [1, 117]
//   [2, 102]
//   [3, 102]
//   [4, 101]
//   [5, 114]

buf.equals(otherBuffer)#

中英对照

如果 bufotherBuffer 具有完全相同的字节,则返回 true,否则返回 false

const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('414243', 'hex');
const buf3 = Buffer.from('ABCD');

console.log(buf1.equals(buf2));
// 输出: true
console.log(buf1.equals(buf3));
// 输出: false

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

中英对照

  • value <string> | <Buffer> | <integer> 用来填充 buf 的值。
  • offset <integer> 开始填充 buf 的偏移量。默认为 0
  • end <integer> 结束填充 buf 的偏移量(不包含)。默认为 buf.length
  • encoding <string> 如果 value 是字符串,则指定 value 的字符编码。默认为 'utf8'
  • 返回: <Buffer> buf 的引用。

用指定的 value 填充 buf。 如果没有指定 offsetend,则填充整个 buf

// 用 ASCII 字符 'h' 填充 `Buffer`。

const b = Buffer.allocUnsafe(50).fill('h');

console.log(b.toString());
// 输出: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

如果 value 不是字符串或整数,则会被转换为 uint32 值。

如果 fill() 最后写入的是一个多字节字符,则只写入适合 buf 的字节:

// 用一个双字节字符填充 `Buffer`。

console.log(Buffer.allocUnsafe(3).fill('\u0222'));
// 输出: <Buffer c8 a2 c8>

如果 value 包含无效的字符,则截掉无效的字符。 如果截掉后没有数据,则不填充:

const buf = Buffer.allocUnsafe(5);

console.log(buf.fill('a'));
// 输出: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'));
// 输出: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'));
// 抛出异常。

buf.includes(value[, byteOffset][, encoding])#

中英对照

  • value <string> | <Buffer> | <integer> 要查找的值。
  • byteOffset <integer> buf 中开始查找的偏移量。默认为 0
  • encoding <string> 如果 value 是字符串,则指定 value 的字符编码。默认为 'utf8'
  • 返回: <boolean> 如果 buf 查找到 value,则返回 true,否则返回 false

相当于 buf.indexOf() !== -1

const buf = Buffer.from('this is a buffer');

console.log(buf.includes('this'));
// 输出: true
console.log(buf.includes('is'));
// 输出: true
console.log(buf.includes(Buffer.from('a buffer')));
// 输出: true
console.log(buf.includes(97));
// 输出: true(97 是 'a' 的十进制 ASCII 值)
console.log(buf.includes(Buffer.from('a buffer example')));
// 输出: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// 输出: true
console.log(buf.includes('this', 4));
// 输出: false

buf.indexOf(value[, byteOffset][, encoding])#

中英对照

  • value <string> | <Buffer> | <Uint8Array> | <integer> 要查找的值。
  • byteOffset <integer> buf 中开始查找的偏移量。默认为 0
  • encoding <string> 如果 value 是字符串,则指定 value 的字符编码。默认为 'utf8'
  • 返回: <integer> buf 中首次出现 value 的索引,如果 buf 没包含 value 则返回 -1

如果 value 是:

  • 一个字符串,则 value 根据 encoding 的字符编码进行解析。
  • 一个 BufferUint8Array,则 value 会整个进行对比。如果要对比部分 Buffer,可使用 buf.slice()
  • 一个数值, 则 value 会被解析成 0255 之间的无符号八位整数值。
const buf = Buffer.from('this is a buffer');

console.log(buf.indexOf('this'));
// 输出: 0
console.log(buf.indexOf('is'));
// 输出: 2
console.log(buf.indexOf(Buffer.from('a buffer')));
// 输出: 8
console.log(buf.indexOf(97));
// 输出: 8(97 是 'a' 的十进制 ASCII 值)
console.log(buf.indexOf(Buffer.from('a buffer example')));
// 输出: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));
// 输出: 8

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');

console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'));
// 输出: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'));
// 输出: 6

如果 value 是一个数值,则会被转换成介于 0 到 255 之间的整数值。

如果 byteOffset 不是一个数值,则会被转换成数值。 如果转换后的值为 NaN 或 0, 则会查找整个 buffer。 这与 String#indexOf() 是一致的。

const b = Buffer.from('abcdef');

// 传入一个非法的数值。
// 输出:2(相当于查找 99 或 'c')
console.log(b.indexOf(99.9));
console.log(b.indexOf(256 + 99));

// 传入被转换成 NaN 或 0 的 byteOffset。
// 输出:1(查找整个 buffer)
console.log(b.indexOf('b', undefined));
console.log(b.indexOf('b', {}));
console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));

如果 value 是一个空字符串或空 Buffer,且 byteOffset 小于 buf.length,则返回 byteOffset。 如果 value 是一个空字符串,且 byteOffset 大于或等于 buf.length,则返回 buf.length

buf.keys()#

中英对照

创建并返回 buf 键名(索引)的迭代器

const buf = Buffer.from('buffer');

for (const key of buf.keys()) {
  console.log(key);
}
// 输出:
//   0
//   1
//   2
//   3
//   4
//   5

buf.lastIndexOf(value[, byteOffset][, encoding])#

中英对照

buf.indexOf() 的区别是,查找的是 'value' 最后一次出现的索引,而不是首次出现。

const buf = Buffer.from('this buffer is a buffer');

console.log(buf.lastIndexOf('this'));
// 输出: 0
console.log(buf.lastIndexOf('buffer'));
// 输出: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')));
// 输出: 17
console.log(buf.lastIndexOf(97));
// 输出: 15(97 是 'a' 的十进制 ASCII 值)
console.log(buf.lastIndexOf(Buffer.from('yolo')));
// 输出: -1
console.log(buf.lastIndexOf('buffer', 5));
// 输出: 5
console.log(buf.lastIndexOf('buffer', 4));
// 输出: -1

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');

console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'));
// 输出: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'));
// 输出: 4

如果 value 不是一个字符串, 数字, 或者 Buffer, 该方法会抛出一个 TypeError 异常, 如果 value 是一个数字, 它将会被强制转换成一个有效的 byte 值, 如果 value 是一个数值,则会被转换成介于 0 到 255 之间的整数值。

如果 byteOffset 不是一个数值,则会被转换成数值。 如果转换后的值为 NaN,比如 {}undefined,则会查找整个 buffer。 这与 String#lastIndexOf() 是一致的。

const b = Buffer.from('abcdef');

// 传入一个非法的数值。
// 输出:2(相当于查找 99 或 'c')
console.log(b.lastIndexOf(99.9));
console.log(b.lastIndexOf(256 + 99));

// 传入被转换成 NaN 的 byteOffset。
// 输出:1(查找整个 buffer)
console.log(b.lastIndexOf('b', undefined));
console.log(b.lastIndexOf('b', {}));

// 传入被转换成 0 的 byteOffset。
// 输出:-1(相当于传入 0)
console.log(b.lastIndexOf('b', null));
console.log(b.lastIndexOf('b', []));

如果 value 是一个空字符串或空 Buffer,则返回 byteOffset

buf.length#

中英对照

返回内存中分配给 buf 的字节数。 不一定反映 buf 中可用数据的字节量。

// 创建一个 `Buffer`,并写入一个 ASCII 字符串。

const buf = Buffer.alloc(1234);

console.log(buf.length);
// 输出: 1234

buf.write('http://nodejs.cn/', 0, 'ascii');

console.log(buf.length);
// 输出: 1234

虽然 length 属性不是不可变的,但改变 length 的值可能会造成不确定的结果。 如果想改变一个 Buffer 的长度,应该使用 buf.slice() 创建一个新的 Buffer

let buf = Buffer.allocUnsafe(10);

buf.write('abcdefghj', 0, 'ascii');

console.log(buf.length);
// 输出: 10

buf = buf.slice(0, 5);

console.log(buf.length);
// 输出: 5

buf.parent#

暂无中英对照

稳定性: 0 - 废弃的: 使用 buf.buffer 代替。

The buf.parent property is a deprecated alias for buf.buffer.

buf.readDoubleBE(offset)#

buf.readDoubleLE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 8
  • 返回: <number>

用指定的字节序格式(readDoubleBE() 返回大端序,readDoubleLE() 返回小端序)从 buf 中指定的 offset 读取一个 64 位双精度值。

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);

console.log(buf.readDoubleBE(0));
// 输出: 8.20788039913184e-304
console.log(buf.readDoubleLE(0));
// 输出: 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readFloatBE(offset)#

buf.readFloatLE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <number>

用指定的字节序格式(readFloatBE() 返回大端序,readFloatLE() 返回小端序)从 buf 中指定的 offset 读取一个 32 位浮点值。

const buf = Buffer.from([1, 2, 3, 4]);

console.log(buf.readFloatBE(0));
// 输出: 2.387939260590663e-38
console.log(buf.readFloatLE(0));
// 输出: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readInt8(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 1
  • 返回: <integer>

buf 中指定的 offset 读取一个有符号的 8 位整数值。

Buffer 中读取的整数值会被解析为二进制补码值。

const buf = Buffer.from([-1, 5]);

console.log(buf.readInt8(0));
// 输出: -1
console.log(buf.readInt8(1));
// 输出: 5
console.log(buf.readInt8(2));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readInt16BE(offset)#

buf.readInt16LE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 2
  • 返回: <integer>

用指定的字节序格式(readInt16BE() 返回大端序,readInt16LE() 返回小端序)从 buf 中指定的 offset 读取一个有符号的 16 位整数值。

Buffer 中读取的整数值会被解析为二进制补码值。

const buf = Buffer.from([0, 5]);

console.log(buf.readInt16BE(0));
// 输出: 5
console.log(buf.readInt16LE(0));
// 输出: 1280
console.log(buf.readInt16LE(1));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readInt32BE(offset)#

buf.readInt32LE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <integer>

用指定的字节序格式(readInt32BE() 返回大端序,readInt32LE() 返回小端序)从 buf 中指定的 offset 读取一个有符号的 32 位整数值。

Buffer 中读取的整数值会被解析为二进制补码值。

const buf = Buffer.from([0, 0, 0, 5]);

console.log(buf.readInt32BE(0));
// 输出: 5
console.log(buf.readInt32LE(0));
// 输出: 83886080
console.log(buf.readInt32LE(1));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readIntBE(offset, byteLength)#

buf.readIntLE(offset, byteLength)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - byteLength
  • byteLength <integer> 要读取的字节数。必须满足0 < byteLength <= 6
  • 返回: <integer>

buf 中指定的 offset 读取 byteLength 个字节,并将读取的值解析为二进制补码值。 最高支持 48 位精度。

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readIntLE(0, 6).toString(16));
// 输出: -546f87a9cbee
console.log(buf.readIntBE(0, 6).toString(16));
// 输出: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16));
// 抛出异常 ERR_INDEX_OUT_OF_RANGE。
console.log(buf.readIntBE(1, 0).toString(16));
// 抛出异常 Throws ERR_OUT_OF_RANGE。

buf.readUInt8(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 1
  • 返回: <integer>

buf 中指定的 offset 读取一个无符号的 8 位整数值。

const buf = Buffer.from([1, -2]);

console.log(buf.readUInt8(0));
// 输出: 1
console.log(buf.readUInt8(1));
// 输出: 254
console.log(buf.readUInt8(2));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readUInt16BE(offset)#

buf.readUInt16LE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 2
  • 返回: <integer>

用指定的字节序格式(readUInt16BE() 返回大端序,readUInt16LE() 返回小端序)从 buf 中指定的 offset 读取一个无符号的 16 位整数值。

const buf = Buffer.from([0x12, 0x34, 0x56]);

console.log(buf.readUInt16BE(0).toString(16));
// 输出: 1234
console.log(buf.readUInt16LE(0).toString(16));
// 输出: 3412
console.log(buf.readUInt16BE(1).toString(16));
// 输出: 3456
console.log(buf.readUInt16LE(1).toString(16));
// 输出: 5634
console.log(buf.readUInt16LE(2).toString(16));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readUInt32BE(offset)#

buf.readUInt32LE(offset)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <integer>

用指定的字节序格式(readUInt32BE() 返回大端序,readUInt32LE() 返回小端序)从 buf 中指定的 offset 读取一个无符号的 32 位整数值。

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);

console.log(buf.readUInt32BE(0).toString(16));
// 输出: 12345678
console.log(buf.readUInt32LE(0).toString(16));
// 输出: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// 抛出异常 ERR_OUT_OF_RANGE。

buf.readUIntBE(offset, byteLength)#

buf.readUIntLE(offset, byteLength)#

中英对照

  • offset <integer> 开始读取的偏移量。必须满足0 <= offset <= buf.length - byteLength
  • byteLength <integer> 要读取的字节数。必须满足0 < byteLength <= 6
  • 返回: <integer>

buf 中指定的 offset 读取 byteLength 个字节,并将读取的值解析为无符号的整数。 最高支持 48 位精度。

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);

console.log(buf.readUIntBE(0, 6).toString(16));
// 输出: 1234567890ab
console.log(buf.readUIntLE(0, 6).toString(16));
// 输出: ab9078563412
console.log(buf.readUIntBE(1, 6).toString(16));
//抛出异常 ERR_OUT_OF_RANGE。

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

中英对照

创建一个指向与原始 Buffer 同一内存的新 Buffer,但使用 startend 进行了裁剪。

修改新建的 Buffer 切片,也会同时修改原始的 Buffer,因为两个对象所分配的内存是重叠的。

// 创建一个包含 ASCII 字母表的 `Buffer`,然后进行切片,再修改原始 `Buffer` 上的一个字节。

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 是 'a' 的十进制 ASCII 值。
  buf1[i] = i + 97;
}

const buf2 = buf1.slice(0, 3);

console.log(buf2.toString('ascii', 0, buf2.length));
// 输出: abc

buf1[0] = 33;

console.log(buf2.toString('ascii', 0, buf2.length));
// 输出: !bc

如果指定负的偏移量,则切片的生成是相对于 buf 的末尾而不是开头。

const buf = Buffer.from('buffer');

console.log(buf.slice(-6, -1).toString());
// 输出: buffe(相当于 buf.slice(0, 5))

console.log(buf.slice(-6, -2).toString());
// 输出: buff(相当于 buf.slice(0, 4))

console.log(buf.slice(-5, -2).toString());
// 输出: uff(相当于 buf.slice(1, 4))

buf.swap16()#

中英对照

buf 解析成无符号的 16 位整数的数组,并且以字节顺序原地进行交换。 如果 buf.length 不是 2 的倍数,则抛出 ERR_INVALID_BUFFER_SIZE

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// 输出: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap16();

console.log(buf1);
// 输出: <Buffer 02 01 04 03 06 05 08 07>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap16();
// 抛出异常 ERR_INVALID_BUFFER_SIZE。

buf.swap32()#

中英对照

buf 解析成无符号的 32 位整数的数组,并且以字节顺序原地进行交换。 如果 buf.length 不是 4 的倍数,则抛出 ERR_INVALID_BUFFER_SIZE

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// 输出: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap32();

console.log(buf1);
// 输出: <Buffer 04 03 02 01 08 07 06 05>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap32();
// 抛出异常 ERR_INVALID_BUFFER_SIZE。

buf.swap64()#

中英对照

buf 解析成 64 位数值的数组,并且以字节顺序原地进行交换。 如果 buf.length 不是 8 的倍数,则抛出 ERR_INVALID_BUFFER_SIZE

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);

console.log(buf1);
// 输出: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap64();

console.log(buf1);
// 输出: <Buffer 08 07 06 05 04 03 02 01>

const buf2 = Buffer.from([0x1, 0x2, 0x3]);

buf2.swap64();
// 抛出异常 ERR_INVALID_BUFFER_SIZE。

JavaScript 不能编码 64 位整数。 该方法是用来处理 64 位浮点数的。

buf.toJSON()#

中英对照

返回 buf 的 JSON 格式。 当字符串化 Buffer 时,JSON.stringify() 会调用该函数。

const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);

console.log(json);
// 输出: {"type":"Buffer","data":[1,2,3,4,5]}

const copy = JSON.parse(json, (key, value) => {
  return value && value.type === 'Buffer' ?
    Buffer.from(value.data) :
    value;
});

console.log(copy);
// 输出: <Buffer 01 02 03 04 05>

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

中英对照

  • encoding <string> 使用的字符编码。默认为 'utf8'
  • start <integer> 开始解码的字节偏移量。默认为 0
  • end <integer> 结束解码的字节偏移量(不包含)。默认为 buf.length
  • 返回: <string>

根据 encoding 指定的字符编码将 buf 解码成字符串。

字符串的最大长度(以 UTF-16 为单位)可查看 buffer.constants.MAX_STRING_LENGTH

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 是 'a' 的十进制 ASCII 值。
  buf1[i] = i + 97;
}

console.log(buf1.toString('ascii'));
// 输出: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('ascii', 0, 5));
// 输出: abcde

const buf2 = Buffer.from('tést');

console.log(buf2.toString('hex'));
// 输出: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// 输出: té
console.log(buf2.toString(undefined, 0, 3));
// 输出: té

buf.values()#

中英对照

创建并返回 buf 键值(字节)的迭代器。 当对 Buffer 使用 for..of 时会调用该函数。

const buf = Buffer.from('buffer');

for (const value of buf.values()) {
  console.log(value);
}
// 输出:
//   98
//   117
//   102
//   102
//   101
//   114

for (const value of buf) {
  console.log(value);
}
// 输出:
//   98
//   117
//   102
//   102
//   101
//   114

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

中英对照

  • string <string> 要写入 buf 的字符串。
  • offset <integer> 开始写入的偏移量。默认 0
  • length <integer> 要写入的字节数。默认为 buf.length - offset
  • encoding <string> string 的字符编码。默认为 'utf8'
  • 返回: <integer> 已写入的字节数。

根据 encoding 指定的字符编码将 string 写入到 buf 中的 offset 位置。 如果 buf 没有足够的空间保存整个字符串,则只会写入 string 的一部分。

const buf = Buffer.alloc(256);

const len = buf.write('\u00bd + \u00bc = \u00be', 0);

console.log(`${len} 个字节: ${buf.toString('utf8', 0, len)}`);
// 输出: 12 个字节: ½ + ¼ = ¾

buf.writeDoubleBE(value, offset)#

buf.writeDoubleLE(value, offset)#

中英对照

  • value <number> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 8
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeDoubleBE() 写入大端序,writeDoubleLE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是 64 位双精度值。

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleBE(123.456, 0);

console.log(buf);
// 输出: <Buffer 40 5e dd 2f 1a 9f be 77>

buf.writeDoubleLE(123.456, 0);

console.log(buf);
// 输出: <Buffer 77 be 9f 1a 2f dd 5e 40>

buf.writeFloatBE(value, offset)#

buf.writeFloatLE(value, offset)#

中英对照

  • value <number> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeFloatBE() 写入大端序,writeFloatLE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是 32 位浮点值。

const buf = Buffer.allocUnsafe(4);

buf.writeFloatBE(0xcafebabe, 0);

console.log(buf);
// 输出: <Buffer 4f 4a fe bb>

buf.writeFloatLE(0xcafebabe, 0);

console.log(buf);
// 输出: <Buffer bb fe 4a 4f>

buf.writeInt8(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 1
  • 返回: <integer> offset 加上已写入的字节数。

value 写入到 buf 中指定的 offset 位置。 value 必须是有符号的 8 位整数。

const buf = Buffer.allocUnsafe(2);

buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);

console.log(buf);
// 输出: <Buffer 02 fe>

buf.writeInt16BE(value, offset)#

buf.writeInt16LE(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 2
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeInt16BE() 写入大端序,writeInt16LE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是有符号的 16 位整数。

const buf = Buffer.allocUnsafe(4);

buf.writeInt16BE(0x0102, 0);
buf.writeInt16LE(0x0304, 2);

console.log(buf);
// 输出: <Buffer 01 02 04 03>

buf.writeInt32BE(value, offset)#

buf.writeInt32LE(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeInt32BE() 写入大端序,writeInt32LE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是有符号的 32 位整数。

const buf = Buffer.allocUnsafe(8);

buf.writeInt32BE(0x01020304, 0);
buf.writeInt32LE(0x05060708, 4);

console.log(buf);
// 输出: <Buffer 01 02 03 04 08 07 06 05>

buf.writeIntBE(value, offset, byteLength)#

buf.writeIntLE(value, offset, byteLength)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - byteLength
  • byteLength <integer> 要写入的字节数。必须满足0 < byteLength <= 6
  • 返回: <integer> offset 加上已写入的字节数。

value 中的 byteLength 个字节写入到 buf 中指定的 offset 位置。 最高支持 48 位精度。

const buf = Buffer.allocUnsafe(6);

buf.writeIntBE(0x1234567890ab, 0, 6);

console.log(buf);
// 输出: <Buffer 12 34 56 78 90 ab>

buf.writeIntLE(0x1234567890ab, 0, 6);

console.log(buf);
// 输出: <Buffer ab 90 78 56 34 12>

buf.writeUInt8(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 1
  • 返回: <integer> offset 加上已写入的字节数。

value 写入到 buf 中指定的 offset 位置。 value 必须是无符号的 8 位整数。

const buf = Buffer.allocUnsafe(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.writeUInt16BE(value, offset)#

buf.writeUInt16LE(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 2
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeUInt16BE() 写入大端序,writeUInt16LE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是无符号的 16 位整数。

const buf = Buffer.allocUnsafe(4);

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

console.log(buf);
// 输出: <Buffer de ad be ef>

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

console.log(buf);
// 输出: <Buffer ad de ef be>

buf.writeUInt32BE(value, offset)#

buf.writeUInt32LE(value, offset)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - 4
  • 返回: <integer> offset 加上已写入的字节数。

用指定的字节序格式(writeUInt32BE() 写入大端序,writeUInt32LE() 写入小端序)将 value 写入到 buf 中指定的 offset 位置。 value 必须是无符号的 32 位整数。

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

console.log(buf);
// 输出: <Buffer fe ed fa ce>

buf.writeUInt32LE(0xfeedface, 0);

console.log(buf);
// 输出: <Buffer ce fa ed fe>

buf.writeUIntBE(value, offset, byteLength)#

buf.writeUIntLE(value, offset, byteLength)#

中英对照

  • value <integer> 要写入 buf 的数值。
  • offset <integer> 开始写入的偏移量。必须满足0 <= offset <= buf.length - byteLength
  • byteLength <integer> 要写入的字节数。必须满足0 < byteLength <= 6
  • 返回: <integer> offset 加上已写入的字节数。

value 中的 byteLength 个字节写入到 buf 中指定的 offset 位置。 最高支持 48 位精度。

const buf = Buffer.allocUnsafe(6);

buf.writeUIntBE(0x1234567890ab, 0, 6);

console.log(buf);
// 输出: <Buffer 12 34 56 78 90 ab>

buf.writeUIntLE(0x1234567890ab, 0, 6);

console.log(buf);
// 输出: <Buffer ab 90 78 56 34 12>

buffer.INSPECT_MAX_BYTES#

中英对照

当调用 buf.inspect() 时返回的最大字节数。 该属性可以重写。 详见 util.inspect()

该属性是在 require('buffer') 返回的 buffer 模块上,而不是在 Buffer 全局变量或 Buffer 实例上。

buffer.kMaxLength#

中英对照

  • <integer> 分配给单个 Buffer 实例的最大内存。

buffer.constants.MAX_LENGTH 的别名。

该属性是在 require('buffer') 返回的 buffer 模块上,而不是在 Buffer 全局变量或 Buffer 实例上。

buffer.transcode(source, fromEnc, toEnc)#

中英对照

将指定的 BufferUint8Array 从一个字符编码重新编码到另一个字符,并返回新的 Buffer。

如果 fromEnctoEnc 指定了无效的字符编码,或者无法从 fromEnc 转换为 toEnc,则抛出异常。

buffer.transcode() 支持的字符编码有 'ascii''utf8''utf16le''ucs2''latin1''binary'

如果指定的字节序列无法用目标字符编码表示,则转码过程会使用替代的字符。例如:

const buffer = require('buffer');

const newBuf = buffer.transcode(Buffer.from('€'), 'utf8', 'ascii');
console.log(newBuf.toString('ascii'));
// 输出: '?'

因为欧元符号()无法在 US-ASCII 中表示,所以在转码 Buffer 时使用 ? 代替。

该属性是在 require('buffer') 返回的 buffer 模块上,而不是在 Buffer 全局变量或 Buffer 实例上。

SlowBuffer 类#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.allocUnsafeSlow() 代替。

Returns an un-pooled Buffer.

In order to avoid the garbage collection overhead of creating many individually allocated Buffer instances, by default allocations under 4KB are sliced from a single larger allocated object.

In the case where a developer may need to retain a small chunk of memory from a pool for an indeterminate amount of time, it may be appropriate to create an un-pooled Buffer instance using SlowBuffer then copy out the relevant bits.

// Need to keep around a few small chunks of memory
const store = [];

socket.on('readable', () => {
  const data = socket.read();

  // Allocate for retained data
  const sb = SlowBuffer(10);

  // Copy the data into the new allocation
  data.copy(sb, 0, 0, 10);

  store.push(sb);
});

Use of SlowBuffer should be used only as a last resort after a developer has observed undue memory retention in their applications.

new SlowBuffer(size)#

暂无中英对照

稳定性: 0 - 废弃的: 使用 Buffer.allocUnsafeSlow() 代替。

  • size <integer> The desired length of the new SlowBuffer.

Allocates a new Buffer of size bytes. If size is larger than buffer.constants.MAX_LENGTH or smaller than 0, ERR_INVALID_OPT_VALUE is thrown. A zero-length Buffer is created if size is 0.

The underlying memory for SlowBuffer instances is not initialized. The contents of a newly created SlowBuffer are unknown and may contain sensitive data. Use buf.fill(0) to initialize a SlowBuffer with zeroes.

const { SlowBuffer } = require('buffer');

const buf = new SlowBuffer(5);

console.log(buf);
// Prints: (contents may vary): <Buffer 78 e0 82 02 01>

buf.fill(0);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00>

Buffer 常量#

中英对照

buffer.constants 是在 require('buffer') 返回的 buffer 模块上,而不是在 Buffer 全局变量或 Buffer 实例上。

buffer.constants.MAX_LENGTH#

中英对照

  • <integer> 单个 Buffer 实例允许的最大内存。

在 32 位的架构上,该值是 (2^30)-1(1 GB)。 在 64 位的架构上,该值是 (2^31)-1(2 GB)。

也可使用 buffer.kMaxLength

buffer.constants.MAX_STRING_LENGTH#

中英对照

  • <integer> 单个 string 实例允许的最大长度。

表示 string 原始数据类型能有的最大 length,以 UTF-16 代码为单位。

该值取决于使用的 JS 引擎。