Buffer (缓冲)

buffer可以在 TCP 流或文件系统操作等场景中处理二进制数据流。

 

开发者们应当把所有正在使用的 new Buffer() 构造函数迁移到这些新的 API 上。

• Buffer.from(array) 返回一个新建的包含所提供的字节数组的副本的 Buffer。
• Buffer.from(arrayBuffer[, byteOffset [, length]]) 返回一个新建的与给定的 ArrayBuffer 共享同一内存的 Buffer。
• Buffer.from(buffer) 返回一个新建的包含所提供的 Buffer 的内容的副本的 Buffer。
• Buffer.from(string[, encoding]) 返回一个新建的包含所提供的字符串的副本的 Buffer。
• Buffer.alloc(size[, fill[, encoding]]) 返回一个指定大小的被填满的 Buffer 实例。 这个方法会明显地比 Buffer.allocUnsafe(size) 慢，但可确保新创建的 Buffer 实例绝不会包含旧的和潜在的敏感数据。
• Buffer.allocUnsafe(size) 与 Buffer.allocUnsafeSlow(size) 返回一个新建的指定 size 的 Buffer，但它的内容必须被初始化，可以使用 buf.fill(0) 或完全写满。

 

创建：

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

分配一个大小为 size 字节的新建的 Buffer 。 如果 fill 为 undefined ，则该 Buffer 会用 0 填充。

如果指定了 fill ，则会调用 buf.fill(fill) 初始化分配的 Buffer 。

如果同时指定了 fill和encoding，则会调用 buf.fill(fill, encoding) 初始化分配的Buffer


 

Buffer.allocUnsafe(size)

以这种方式创建的 Buffer 实例的底层内存是未初始化的。 新创建的 Buffer 的内容是未知的，且可能包含敏感数据。 可以使用 buf.fill(0) 初始化 Buffer 实例为0。

const buf = Buffer.allocUnsafe(10);
// 输出: (内容可能不同): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
console.log(buf);

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

 

Buffer.from(array)

通过一个八位字节的 array 创建一个新的 Buffer 。

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

 

Buffer.from(buffer)

将传入的 buffer 数据拷贝到一个新建的 Buffer 实例。

const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
buf1[0] = 0x61;
// 输出: auffer
console.log(buf1.toString());
// 输出: buffer
console.log(buf2.toString());

 

Buffer.from(string[, encoding])

新建一个包含所给的 JavaScript 字符串 string 的 Buffer 。 encoding 参数指定 string 的字符编码

const buf1 = Buffer.from('this is a tést');
// 输出: this is a tést
console.log(buf1.toString());
// 输出: this is a tC)st
console.log(buf1.toString('ascii'));
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
// 输出: this is a tést
console.log(buf2.toString());

 

填充：

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

 

读取：

 

写入：

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

根据 encoding 的字符编码写入 string 到 buf 中的 offset 位置。 length 参数是写入的字节数。

如果 buf 没有足够的空间保存整个字符串，则只会写入 string 的一部分。 只部分解码的字符不会被写入。

 

搜索：

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

如果 buf 找到 value，则返回 true，否则返回 false

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

// 输出: true
console.log(buf.includes('this'));

// 输出: true
console.log(buf.includes('is'));

// 输出: true
console.log(buf.includes(Buffer.from('a buffer')));

// 输出: true
// (97 是 'a' 的十进制 ASCII 值)
console.log(buf.includes(97));

// 输出: false
console.log(buf.includes(Buffer.from('a buffer example')));

// 输出: true
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));

// 输出: false
console.log(buf.includes('this', 4));

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

buf 中 value 首次出现的索引，如果 buf 没包含 value 则返回 -1

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

// 输出: 0
console.log(buf.indexOf('this'));

// 输出: 2
console.log(buf.indexOf('is'));

// 输出: 8
console.log(buf.indexOf(Buffer.from('a buffer')));

// 输出: 8
// (97 是 'a' 的十进制 ASCII 值)
console.log(buf.indexOf(97));

// 输出: -1
console.log(buf.indexOf(Buffer.from('a buffer example')));

// 输出: 8
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));


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

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

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

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

buf 中 value 最后一次出现的索引，如果 buf 没包含 value 则返回 -1

与 buf.indexOf() 类似，除了 buf 是从后往前搜索而不是从前往后。

 

buf.length

返回 buf 在字节数上分配的内存量。 注意，这并不一定反映 buf 内可用的数据量。

const buf = Buffer.alloc(1234);

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

buf.write('some string', 0, 'ascii');

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

 

Buffer.byteLength(string[, encoding])

返回一个字符串的实际字节长度。如果 string 是字符串，则encoding是它的字符编码。 默认: 'utf8'

 

Buffer.compare(buf1, buf2)

比较 buf1 和 buf2 ，通常用于 Buffer 实例数组的排序。 相当于调用 buf1.compare(buf2) 。

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

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

 

Buffer.concat(list[, totalLength])

返回一个合并了 list 中所有 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;

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

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

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

// 输出: 42
console.log(bufA.length);

 

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

拷贝 buf 的一个区域的数据到 target 的一个区域

例子：创建两个 Buffer 实例 buf1 与 buf2 ，并拷贝 buf1 中第 16 个至第 19 个字节到 buf2 第 8 个字节起。

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.copy(buf2, 8, 16, 20);

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

 

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

返回一个指向相同原始内存的新建的 Buffer，但做了偏移且通过 start 和 end 索引进行裁剪。

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

 

buf.toJSON()

返回 buf 的 JSON 格式。

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

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

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

根据 encoding 指定的字符编码解码 buf 成一个字符串。 start 和 end 可传入用于只解码 buf 的一部分。

 

buffer.transcode(source, fromEnc, toEnc)

将给定的 Buffer 或 Uint8Array 实例从一个字符编码重新编码到另一个字符。 返回一个新的Buffer实例。

 

Buffer.isBuffer(obj)

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

 

buf.equals(otherBuffer)

如果 buf 与 otherBuffer 具有完全相同的字节，则返回 true，否则返回 false。