@ -21,18 +21,112 @@ The `Buffer` class is a global within Node.js, making it unlikely that one
would need to ever use `require('buffer')` .would need to ever use `require('buffer')` .
```js```js
const buf1 = new Buffer(10);const buf1 = Buffer.alloc (10);
// creates a buffer of length 10 // Creates a zero-filled Buffer of length 10.
const buf2 = new Buffer([1,2,3] );const buf2 = Buffer.alloc(10, 1 );
// creates a buffer containing [01, 02, 03] // Creates a Buffer of length 10, filled with 0x01.
const buf3 = new Buffer('test');const buf3 = Buffer.allocUnsafe(10);
// creates a buffer containing ASCII bytes [74, 65, 73, 74] // Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using either fill() or write().
const buf4 = Buffer.from([1,2,3]);
// Creates a Buffer containing [01, 02, 03].
const buf5 = Buffer.from('test');
// Creates a Buffer containing ASCII bytes [74, 65, 73, 74].
const buf6 = Buffer.from('tést', 'utf8');
// Creates a Buffer containing UTF8 bytes [74, c3, a9, 73, 74].
```
## `Buffer.from()` , `Buffer.alloc()` , and `Buffer.allocUnsafe()`
In versions of Node.js prior to v6, `Buffer` instances were created using the
`Buffer` constructor function, which allocates the returned `Buffer`
differently based on what arguments are provided:
* Passing a number as the first argument to `Buffer()` (e.g. `new Buffer(10)` ),
allocates a new `Buffer` object of the specified size. The memory allocated
for such `Buffer` instances is *not* initialized and *can contain sensitive
data*. Such `Buffer` objects *must* be initialized *manually* by using either
[`buf.fill(0)`][] or by writing to the `Buffer` completely. While this
behavior is *intentional* to improve performance, development experience has
demonstrated that a more explicit distinction is required between creating a
fast-but-uninitialized `Buffer` versus creating a slower-but-safer `Buffer` .
* Passing a string, array, or `Buffer` as the first argument copies the
passed object's data into the `Buffer` .
* Passing an `ArrayBuffer` returns a `Buffer` that shares allocated memory with
the given `ArrayBuffer` .
Because the behavior of `new Buffer()` changes significantly based on the type
of value passed as the first argument, applications that do not properly
validate the input arguments passed to `new Buffer()` , or that fail to
appropriately initialize newly allocated `Buffer` content, can inadvertently
introduce security and reliability issues into their code.
To make the creation of `Buffer` objects more reliable and less error prone,
the various forms of the `new Buffer()` constructor have been **deprecated**
and replaced by separate `Buffer.from()` , `Buffer.alloc()` , and
`Buffer.allocUnsafe()` methods.
*Developers should migrate all existing uses of the `new Buffer()` constructors
to one of these new APIs.*
* [`Buffer.from(array)`][buffer_from_array] returns a new `Buffer` containing
a *copy* of the provided octets.
* [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][buffer_from_arraybuf]
returns a new `Buffer` that *shares* the same allocated memory as the given
`ArrayBuffer` .
* [`Buffer.from(buffer)`][buffer_from_buffer] returns a new `Buffer`
containing a *copy* of the contents of the given `Buffer` .
* [`Buffer.from(str[, encoding])`][buffer_from_string] returns a new `Buffer`
containing a *copy* of the provided string.
* [`Buffer.alloc(size[, fill[, encoding]])`][buffer_alloc] returns a "filled"
`Buffer` instance of the specified size. This method can be significantly
slower than [`Buffer.allocUnsafe(size)`][buffer_allocunsafe] but ensures that
newly created `Buffer` instances never contain old and potentially sensitive
data.
* [`Buffer.allocUnsafe(size)`][buffer_allocunsafe] returns a new `Buffer` of
the specified `size` whose content *must* be initialized using either
[`buf.fill(0)`][] or written to completely.
`Buffer` instances returned by `Buffer.allocUnsafe(size)` *may* be allocated
off a shared internal memory pool if the `size` is less than or equal to half
`Buffer.poolSize` .
### The `--zero-fill-buffers` command line option
Node.js can be started using the `--zero-fill-buffers` command line option to
force all newly allocated `Buffer` and `SlowBuffer` instances created using
either `new Buffer(size)` , `Buffer.allocUnsafe(size)` , or
`new SlowBuffer(size)` to be *automatically zero-filled* upon creation. Use of
this flag *changes the default behavior* of these methods and *can have a
significant impact* on performance. Use of the `--zero-fill-buffers` option is
recommended only when absolutely necessary to enforce that newly allocated
`Buffer` instances cannot contain potentially sensitive data.
const buf4 = new Buffer('tést', 'utf8');
// creates a buffer containing UTF8 bytes [74, c3, a9, 73, 74]
``````
$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
< Buffer 00 00 00 00 00 >
```
### What makes `Buffer.allocUnsafe(size)` "unsafe"?
When calling `Buffer.allocUnsafe()` , the segment of allocated memory is
*uninitialized* (it is not zeroed-out). While this design makes the allocation
of memory quite fast, the allocated segment of memory might contain old data
that is potentially sensitive. Using a `Buffer` created by
`Buffer.allocUnsafe(size)` without *completely* overwriting the memory can
allow this old data to be leaked when the `Buffer` memory is read.
While there are clear performance advantages to using `Buffer.allocUnsafe()` ,
extra care *must* be taken in order to avoid introducing security
vulnerabilities into an application.
## Buffers and Character Encodings## Buffers and Character Encodings
@ -42,7 +136,7 @@ convert back and forth between Buffers and ordinary JavaScript string objects
by using an explicit encoding method.by using an explicit encoding method.
```js```js
const buf = new Buffer('hello world', 'ascii');const buf = Buffer.from ('hello world', 'ascii');
console.log(buf.toString('hex'));console.log(buf.toString('hex'));
// prints: 68656c6c6f20776f726c64 // prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));console.log(buf.toString('base64'));
@ -83,24 +177,24 @@ existing Buffer without copying, making `Buffer#slice()` far more efficient.
It is also possible to create new TypedArray instances from a `Buffer` with theIt is also possible to create new TypedArray instances from a `Buffer` with the
following caveats:following caveats:
1. The Buffer instances 's memory is copied to the TypedArray, not shared.1. The `Buffer` object
2. The Buffer's memory is interpreted as an array of distinct elements, and not 2. The ` Buffer` object
as a byte array of the target type. That is,elements, and not as a byte array of the target type. That is,
`new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array` `new Uint32Array(Buffer.from ([1,2,3,4]))` creates a 4-element `Uint32Array`
with elements `[1,2,3,4]` , not a `Uint32Array` with a single element with elements `[1,2,3,4]` , not a `Uint32Array` with a single element
`[0x1020304]` or `[0x4030201]` . `[0x1020304]` or `[0x4030201]` .
It is possible to create a new Buffer that shares the same allocated memory asIt is possible to create a new ` Buffer`
a TypedArray instance by using the TypeArray objects `.buffer` property:a TypedArray instance by using the TypeArray object' s `.buffer` property:
```js```js
const arr = new Uint16Array(2);const arr = new Uint16Array(2);
arr[0] = 5000;arr[0] = 5000;
arr[1] = 4000;arr[1] = 4000;
const buf1 = new Buffer(arr); // copies the bufferconst buf1 = Buffer.from (arr); // copies the buffer
const buf2 = new Buffer(arr.buffer); // shares the memory with arr;const buf2 = Buffer.from (arr.buffer); // shares the memory with arr;
console.log(buf1);console.log(buf1);
// Prints: < Buffer 88 a0 > , copied buffer has only two elements // Prints: < Buffer 88 a0 > , copied buffer has only two elements
@ -114,24 +208,38 @@ console.log(buf2);
// Prints: < Buffer 88 13 70 17 > // Prints: < Buffer 88 13 70 17 >
``````
Note that when creating a Buffer using the TypeArray's `.buffer` , it is notNote that when creating a `Buffer` using the TypedArray's `.buffer` , it is
currently possible to use only a portion of the underlying `ArrayBuffer` . Topossible to use only a portion of the underlying `ArrayBuffer` by passing in
create a Buffer that uses only a part of the `ArrayBuffer` , use the`byteOffset` and `length` parameters:
[`buf.slice()`][] function after the Buffer is created:
```js```js
const arr = new Uint16Array(20);const arr = new Uint16Array(20);
const buf = new Buffer(arr.buffer).slice( 0, 16);const buf = Buffer.from(arr.buffer, 0, 16);
console.log(buf.length);console.log(buf.length);
// Prints: 16 // Prints: 16
``````
The `Buffer.from()` and [`TypedArray.from()`][] (e.g.`Uint8Array.from()`) have
different signatures and implementations. Specifically, the TypedArray variants
accept a second argument that is a mapping function that is invoked on every
element of the typed array:
* `TypedArray.from(source[, mapFn[, thisArg]])`
The `Buffer.from()` method, however, does not support the use of a mapping
function:
* [`Buffer.from(array)`][buffer_from_array]
* [`Buffer.from(buffer)`][buffer_from_buffer]
* [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][buffer_from_arraybuf]
* [`Buffer.from(str[, encoding])`][buffer_from_string]
## Buffers and ES6 iteration## Buffers and ES6 iteration
Buffers can be iterated over using the ECMAScript 2015 (ES6) `for..of` syntax:Buffers can be iterated over using the ECMAScript 2015 (ES6) `for..of` syntax:
```js```js
const buf = new Buffer([1, 2, 3]);const buf = Buffer.from ([1, 2, 3]);
for (var b of buf)for (var b of buf)
console.log(b) console.log(b)
@ -152,6 +260,9 @@ It can be constructed in a variety of ways.
### new Buffer(array)### new Buffer(array)
Stability: 0 - Deprecated: Use [`Buffer.from(array)`][buffer_from_array]
instead.
* `array` {Array}* `array` {Array}
Allocates a new Buffer using an `array` of octets.Allocates a new Buffer using an `array` of octets.
@ -164,6 +275,9 @@ const buf = new Buffer([0x62,0x75,0x66,0x66,0x65,0x72]);
### new Buffer(buffer)### new Buffer(buffer)
Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`][buffer_from_buffer]
instead.
* `buffer` {Buffer}* `buffer` {Buffer}
Copies the passed `buffer` data onto a new `Buffer` instance.Copies the passed `buffer` data onto a new `Buffer` instance.
@ -179,15 +293,24 @@ console.log(buf2.toString());
// 'buffer' (copy is not changed) // 'buffer' (copy is not changed)
``````
### new Buffer(arrayBuffer)### new Buffer(arrayBuffer[, byteOffset [, length]] )
* `arrayBuffer` - The `.buffer` property of a `TypedArray` or a `new Stability: 0 - Deprecated: Use
ArrayBuffer()` [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][buffer_from_arraybuf]
instead.
* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a `TypedArray` or a
`new ArrayBuffer()`
* `byteOffset` {Number} Default: `0`
* `length` {Number} Default: `arrayBuffer.length - byteOffset`
When passed a reference to the `.buffer` property of a `TypedArray` instance,When passed a reference to the `.buffer` property of a `TypedArray` instance,
the newly created Buffer will share the same allocated memory as thethe newly created Buffer will share the same allocated memory as the
TypedArray.TypedArray.
The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer` .
```js```js
const arr = new Uint16Array(2);const arr = new Uint16Array(2);
arr[0] = 5000;arr[0] = 5000;
@ -207,18 +330,22 @@ console.log(buf);
### new Buffer(size)### new Buffer(size)
Stability: 0 - Deprecated: Use
[`Buffer.alloc(size[, fill[, encoding]])`][buffer_alloc] instead (also
see [`Buffer.allocUnsafe(size)`][buffer_allocunsafe]).
* `size` {Number}* `size` {Number}
Allocates a new Buffer of `size` bytes. The `size` must be less thanAllocates a new ` Buffer` `size` bytes. The `size` must be less than
or equal to the value of `require('buffer').kMaxLength` (on 64-bitor equal to the value of `require('buffer').kMaxLength` (on 64-bit
architectures, `kMaxLength` is `(2^31)-1` ). Otherwise, a [`RangeError`][] isarchitectures, `kMaxLength` is `(2^31)-1` ). Otherwise, a [`RangeError`][] is
thrown. If a `size` less than 0 is specified, a zero-length Buffer will bethrown. If a `size` less than 0 is specified, a zero-length Buffer will be
created.created.
Unlike `ArrayBuffers` , the underlying memory for Buffer instances created inUnlike `ArrayBuffers` , the underlying memory for ` Buffer`
this way is not initialized. The contents of a newly created `Buffer` arethis way is * not initialized* `Buffer` are
unknown and could contain sensitive data. Use [`buf.fill(0)`][] to initialize a unknown and * could contain sensitive data*
Buffer to zeroes.a ` Buffer` to zeroes.
```js```js
const buf = new Buffer(5);const buf = new Buffer(5);
@ -232,7 +359,10 @@ console.log(buf);
### new Buffer(str[, encoding])### new Buffer(str[, encoding])
* `str` {String} String to encode. Stability: 0 - Deprecated:
Use [`Buffer.from(str[, encoding])`][buffer_from_string] instead.
* `str` {String} string to encode.
* `encoding` {String} Default: `'utf8'` * `encoding` {String} Default: `'utf8'`
Creates a new Buffer containing the given JavaScript string `str` . IfCreates a new Buffer containing the given JavaScript string `str` . If
@ -250,6 +380,92 @@ console.log(buf2.toString());
// prints: this is a tést // prints: this is a tést
``````
### Class Method: Buffer.alloc(size[, fill[, encoding]])
* `size` {Number}
* `fill` {Value} Default: `undefined`
* `encoding` {String} Default: `utf8`
Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined` , the
`Buffer` will be *zero-filled* .
```js
const buf = Buffer.alloc(5);
console.log(buf);
// < Buffer 00 00 00 00 00 >
```
The `size` must be less than or equal to the value of
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
`(2^31)-1` ). Otherwise, a [`RangeError`][] is thrown. If a `size` less than 0
is specified, a zero-length `Buffer` will be created.
If `fill` is specified, the allocated `Buffer` will be initialized by calling
`buf.fill(fill)` . See [`buf.fill()`][] for more information.
```js
const buf = Buffer.alloc(5, 'a');
console.log(buf);
// < Buffer 61 61 61 61 61 >
```
If both `fill` and `encoding` are specified, the allocated `Buffer` will be
initialized by calling `buf.fill(fill, encoding)` . For example:
```js
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf);
// < Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64 >
```
Calling `Buffer.alloc(size)` can be significantly slower than the alternative
`Buffer.allocUnsafe(size)` but ensures that the newly created `Buffer` instance
contents will *never contain sensitive data* .
A `TypeError` will be thrown if `size` is not a number.
### Class Method: Buffer.allocUnsafe(size)
* `size` {Number}
Allocates a new *non-zero-filled* `Buffer` of `size` bytes. The `size` must
be less than or equal to the value of `require('buffer').kMaxLength` (on 64-bit
architectures, `kMaxLength` is `(2^31)-1` ). Otherwise, a [`RangeError`][] is
thrown. If a `size` less than 0 is specified, a zero-length `Buffer` will be
created.
The underlying memory for `Buffer` instances created in this way is *not
initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`buf.fill(0)`][] to initialize such
`Buffer` instances to zeroes.
```js
const buf = Buffer.allocUnsafe(5);
console.log(buf);
// < Buffer 78 e0 82 02 01 >
// (octets will be different, every time)
buf.fill(0);
console.log(buf);
// < Buffer 00 00 00 00 00 >
```
A `TypeError` will be thrown if `size` is not a number.
Note that the `Buffer` module pre-allocates an internal `Buffer` instance of
size `Buffer.poolSize` that is used as a pool for the fast allocation of new
`Buffer` instances created using `Buffer.allocUnsafe(size)` (and the deprecated
`new Buffer(size)` constructor) only when `size` is less than or equal to
`Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). The default
value of `Buffer.poolSize` is `8192` but can be modified.
Use of this pre-allocated internal memory pool is a key difference between
calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)` .
Specifically, `Buffer.alloc(size, fill)` will *never* use the internal Buffer
pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal
Buffer pool if `size` is less than or equal to half `Buffer.poolSize` . The
difference is subtle but can be important when an application requires the
additional performance that `Buffer.allocUnsafe(size)` provides.
### Class Method: Buffer.byteLength(string[, encoding])### Class Method: Buffer.byteLength(string[, encoding])
* `string` {String}* `string` {String}
@ -281,14 +497,15 @@ Compares `buf1` to `buf2` typically for the purpose of sorting arrays of
Buffers. This is equivalent is calling [`buf1.compare(buf2)`][].Buffers. This is equivalent is calling [`buf1.compare(buf2)`][].
```js```js
const arr = [Buffer('1234'), Buffer('0123')];const arr = [Buffer.from ('1234'), Buffer.from ('0123')];
arr.sort(Buffer.compare);arr.sort(Buffer.compare);
``````
### Class Method: Buffer.concat(list[, totalLength])### Class Method: Buffer.concat(list[, totalLength])
* `list` {Array} List of Buffer objects to concat* `list` {Array} List of Buffer objects to concat
* `totalLength` {Number} Total length of the Buffers in the list when concatenated* `totalLength` {Number} Total length of the Buffers in the list
when concatenated
* Return: {Buffer}* Return: {Buffer}
Returns a new Buffer which is the result of concatenating all the Buffers inReturns a new Buffer which is the result of concatenating all the Buffers in
@ -304,9 +521,9 @@ to provide the length explicitly.
Example: build a single Buffer from a list of three Buffers:Example: build a single Buffer from a list of three Buffers:
```js```js
const buf1 = new Buffer(10).fill( 0);const buf1 = Buffer.alloc(1 0);
const buf2 = new Buffer(14).fill(0 );const buf2 = Buffer.alloc(14 );
const buf3 = new Buffer(18).fill(0 );const buf3 = Buffer.alloc(18 );
const totalLength = buf1.length + buf2.length + buf3.length;const totalLength = buf1.length + buf2.length + buf3.length;
console.log(totalLength);console.log(totalLength);
@ -319,6 +536,102 @@ console.log(bufA.length);
// 42// 42
``````
### Class Method: Buffer.from(array)
* `array` {Array}
Allocates a new `Buffer` using an `array` of octets.
```js
const buf = Buffer.from([0x62,0x75,0x66,0x66,0x65,0x72]);
// creates a new Buffer containing ASCII bytes
// ['b','u','f','f','e','r']
```
A `TypeError` will be thrown if `array` is not an `Array` .
### Class Method: Buffer.from(arrayBuffer[, byteOffset[, length]])
* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a `TypedArray` or
a `new ArrayBuffer()`
* `byteOffset` {Number} Default: `0`
* `length` {Number} Default: `arrayBuffer.length - byteOffset`
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.
```js
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
const buf = Buffer.from(arr.buffer); // shares the memory with arr;
console.log(buf);
// Prints: < Buffer 88 13 a0 0f >
// changing the TypedArray changes the Buffer also
arr[1] = 6000;
console.log(buf);
// Prints: < Buffer 88 13 70 17 >
```
The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer` .
```js
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
console.log(buf.length);
// Prints: 2
```
A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer` .
### Class Method: Buffer.from(buffer)
* `buffer` {Buffer}
Copies the passed `buffer` data onto a new `Buffer` instance.
```js
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
buf1[0] = 0x61;
console.log(buf1.toString());
// 'auffer'
console.log(buf2.toString());
// 'buffer' (copy is not changed)
```
A `TypeError` will be thrown if `buffer` is not a `Buffer` .
### Class Method: Buffer.from(str[, encoding])
* `str` {String} String to encode.
* `encoding` {String} Encoding to use, Default: `'utf8'`
Creates a new `Buffer` containing the given JavaScript string `str` . If
provided, the `encoding` parameter identifies the character encoding.
If not provided, `encoding` defaults to `'utf8'` .
```js
const buf1 = Buffer.from('this is a tést');
console.log(buf1.toString());
// prints: this is a tést
console.log(buf1.toString('ascii'));
// prints: this is a tC)st
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf2.toString());
// prints: this is a tést
```
A `TypeError` will be thrown if `str` is not a string.
### Class Method: Buffer.isBuffer(obj)### Class Method: Buffer.isBuffer(obj)
* `obj` {Object}* `obj` {Object}
@ -347,9 +660,9 @@ Example: copy an ASCII string into a Buffer, one byte at a time:
```js```js
const str = "Node.js";const str = "Node.js";
const buf = new Buffer(str.length);const buf = Buffer.allocUnsafe (str.length);
for (var i = 0; i < str.length ; i + + ) { for (let i = 0; i < str.length ; i + + ) {
buf[i] = str.charCodeAt(i); buf[i] = str.charCodeAt(i);
}}
@ -371,9 +684,9 @@ Comparison is based on the actual sequence of bytes in each Buffer.
* `-1` is returned if `otherBuffer` should come *after* `buf` when sorted.* `-1` is returned if `otherBuffer` should come *after* `buf` when sorted.
```js```js
const buf1 = new Buffer('ABC');const buf1 = Buffer.from ('ABC');
const buf2 = new Buffer('BCD');const buf2 = Buffer.from ('BCD');
const buf3 = new Buffer('ABCD');const buf3 = Buffer.from ('ABCD');
console.log(buf1.compare(buf1));console.log(buf1.compare(buf1));
// Prints: 0 // Prints: 0
@ -405,10 +718,10 @@ Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
into `buf2` , starting at the 8th byte in `buf2` .into `buf2` , starting at the 8th byte in `buf2` .
```js```js
const buf1 = new Buffer(26);const buf1 = Buffer.allocUnsafe (26);
const buf2 = new Buffer(26).fill('!');const buf2 = Buffer.allocUnsafe (26).fill('!');
for (var i = 0 ; i < 26 ; i + + ) { for (let i = 0 ; i < 26 ; i + + ) {
buf1[i] = i + 97; // 97 is ASCII a buf1[i] = i + 97; // 97 is ASCII a
}}
@ -421,7 +734,7 @@ Example: Build a single Buffer, then copy data from one region to an overlapping
region in the same Bufferregion in the same Buffer
```js```js
const buf = new Buffer(26);const buf = Buffer.allocUnsafe (26);
for (var i = 0 ; i < 26 ; i + + ) { for (var i = 0 ; i < 26 ; i + + ) {
buf[i] = i + 97; // 97 is ASCII a buf[i] = i + 97; // 97 is ASCII a
@ -441,7 +754,7 @@ Creates and returns an [iterator][] of `[index, byte]` pairs from the Buffer
contents.contents.
```js```js
const buf = new Buffer('buffer');const buf = Buffer.from ('buffer');
for (var pair of buf.entries()) {for (var pair of buf.entries()) {
console.log(pair); console.log(pair);
}}
@ -463,9 +776,9 @@ Returns a boolean indicating whether `this` and `otherBuffer` have exactly the
same bytes.same bytes.
```js```js
const buf1 = new Buffer('ABC');const buf1 = Buffer.from ('ABC');
const buf2 = new Buffer('414243', 'hex');const buf2 = Buffer.from ('414243', 'hex');
const buf3 = new Buffer('ABCD');const buf3 = Buffer.from ('ABCD');
console.log(buf1.equals(buf2));console.log(buf1.equals(buf2));
// Prints: true // Prints: true
@ -488,7 +801,7 @@ This is meant as a small simplification to creating a Buffer. Allowing the
creation and fill of the Buffer to be done on a single line:creation and fill of the Buffer to be done on a single line:
```js```js
const b = new Buffer(50).fill('h');const b = Buffer.allocUnsafe (50).fill('h');
console.log(b.toString());console.log(b.toString());
// Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh // Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
``````
@ -519,22 +832,22 @@ default interpreted as UTF8. Buffers will use the entire Buffer (to compare a
partial Buffer use [`buf.slice()`][]). Numbers can range from 0 to 255.partial Buffer use [`buf.slice()`][]). Numbers can range from 0 to 255.
```js```js
const buf = new Buffer('this is a buffer');const buf = Buffer.from ('this is a buffer');
buf.indexOf('this');buf.indexOf('this');
// returns 0 // returns 0
buf.indexOf('is');buf.indexOf('is');
// returns 2 // returns 2
buf.indexOf(new Buffer('a buffer'));buf.indexOf(Buffer.from ('a buffer'));
// returns 8 // returns 8
buf.indexOf(97); // ascii for 'a'buf.indexOf(97); // ascii for 'a'
// returns 8 // returns 8
buf.indexOf(new Buffer('a buffer example'));buf.indexOf(Buffer.from ('a buffer example'));
// returns -1 // returns -1
buf.indexOf(new Buffer('a buffer example').slice(0,8));buf.indexOf(Buffer.from ('a buffer example').slice(0,8));
// returns 8 // returns 8
const utf16Buffer = new Buffer('\u039a\u0391\u03a3\u03a3\u0395', 'ucs2');const utf16Buffer = Buffer.from ('\u039a\u0391\u03a3\u03a3\u0395', 'ucs2');
utf16Buffer.indexOf('\u03a3', 0, 'ucs2');utf16Buffer.indexOf('\u03a3', 0, 'ucs2');
// returns 4 // returns 4
@ -557,19 +870,19 @@ Buffer use [`buf.slice()`][]). Numbers can range from 0 to 255.
The `byteOffset` indicates the index in `buf` where searching begins.The `byteOffset` indicates the index in `buf` where searching begins.
```js```js
const buf = new Buffer('this is a buffer');const buf = Buffer.from ('this is a buffer');
buf.includes('this');buf.includes('this');
// returns true // returns true
buf.includes('is');buf.includes('is');
// returns true // returns true
buf.includes(new Buffer('a buffer'));buf.includes(Buffer.from ('a buffer'));
// returns true // returns true
buf.includes(97); // ascii for 'a'buf.includes(97); // ascii for 'a'
// returns true // returns true
buf.includes(new Buffer('a buffer example'));buf.includes(Buffer.from ('a buffer example'));
// returns false // returns false
buf.includes(new Buffer('a buffer example').slice(0,8));buf.includes(Buffer.from ('a buffer example').slice(0,8));
// returns true // returns true
buf.includes('this', 4);buf.includes('this', 4);
// returns false // returns false
@ -582,7 +895,7 @@ buf.includes('this', 4);
Creates and returns an [iterator][] of Buffer keys (indices).Creates and returns an [iterator][] of Buffer keys (indices).
```js```js
const buf = new Buffer('buffer');const buf = Buffer.from ('buffer');
for (var key of buf.keys()) {for (var key of buf.keys()) {
console.log(key); console.log(key);
}}
@ -605,7 +918,7 @@ Buffer. For instance, in the example below, a Buffer with 1234 bytes is
allocated, but only 11 ASCII bytes are written.allocated, but only 11 ASCII bytes are written.
```js```js
const buf = new Buffer(1234);const buf = Buffer.alloc (1234);
console.log(buf.length);console.log(buf.length);
// Prints: 1234 // Prints: 1234
@ -621,7 +934,7 @@ modify the length of a Buffer should therefore treat `length` as read-only and
use [`buf.slice()`][] to create a new Buffer.use [`buf.slice()`][] to create a new Buffer.
```js```js
var buf = new Buffer(10);var buf = Buffer.allocUnsafe (10);
buf.write('abcdefghj', 0, 'ascii');buf.write('abcdefghj', 0, 'ascii');
console.log(buf.length);console.log(buf.length);
// Prints: 10 // Prints: 10
@ -645,7 +958,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
`offset` to be beyond the end of the Buffer.`offset` to be beyond the end of the Buffer.
```js```js
const buf = new Buffer([1,2,3,4,5,6,7,8]);const buf = Buffer.from ([1,2,3,4,5,6,7,8]);
buf.readDoubleBE();buf.readDoubleBE();
// Returns: 8.20788039913184e-304 // Returns: 8.20788039913184e-304
@ -673,7 +986,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
`offset` to be beyond the end of the Buffer.`offset` to be beyond the end of the Buffer.
```js```js
const buf = new Buffer([1,2,3,4]);const buf = Buffer.from ([1,2,3,4]);
buf.readFloatBE();buf.readFloatBE();
// Returns: 2.387939260590663e-38 // Returns: 2.387939260590663e-38
@ -700,7 +1013,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
Integers read from the Buffer are interpreted as two's complement signed values.Integers read from the Buffer are interpreted as two's complement signed values.
```js```js
const buf = new Buffer([1,-2,3,4]);const buf = Buffer.from ([1,-2,3,4]);
buf.readInt8(0);buf.readInt8(0);
// returns 1 // returns 1
@ -725,7 +1038,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
Integers read from the Buffer are interpreted as two's complement signed values.Integers read from the Buffer are interpreted as two's complement signed values.
```js```js
const buf = new Buffer([1,-2,3,4]);const buf = Buffer.from ([1,-2,3,4]);
buf.readInt16BE();buf.readInt16BE();
// returns 510 // returns 510
@ -750,7 +1063,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
Integers read from the Buffer are interpreted as two's complement signed values.Integers read from the Buffer are interpreted as two's complement signed values.
```js```js
const buf = new Buffer([1,-2,3,4]);const buf = Buffer.from ([1,-2,3,4]);
buf.readInt32BE();buf.readInt32BE();
// returns 33424132 // returns 33424132
@ -771,7 +1084,7 @@ and interprets the result as a two's complement signed value. Supports up to 48
bits of accuracy. For example:bits of accuracy. For example:
```js```js
const buf = new Buffer(6);const buf = Buffer.allocUnsafe (6);
buf.writeUInt16LE(0x90ab, 0);buf.writeUInt16LE(0x90ab, 0);
buf.writeUInt32LE(0x12345678, 2);buf.writeUInt32LE(0x12345678, 2);
buf.readIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)buf.readIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)
@ -796,7 +1109,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
`offset` to be beyond the end of the Buffer.`offset` to be beyond the end of the Buffer.
```js```js
const buf = new Buffer([1,-2,3,4]);const buf = Buffer.from ([1,-2,3,4]);
buf.readUInt8(0);buf.readUInt8(0);
// returns 1 // returns 1
@ -821,7 +1134,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
Example:Example:
```js```js
const buf = new Buffer([0x3, 0x4, 0x23, 0x42]);const buf = Buffer.from ([0x3, 0x4, 0x23, 0x42]);
buf.readUInt16BE(0);buf.readUInt16BE(0);
// Returns: 0x0304 // Returns: 0x0304
@ -854,7 +1167,7 @@ Setting `noAssert` to `true` skips validation of the `offset`. This allows the
Example:Example:
```js```js
const buf = new Buffer([0x3, 0x4, 0x23, 0x42]);const buf = Buffer.from ([0x3, 0x4, 0x23, 0x42]);
buf.readUInt32BE(0);buf.readUInt32BE(0);
// Returns: 0x03042342 // Returns: 0x03042342
@ -875,7 +1188,7 @@ and interprets the result as an unsigned integer. Supports up to 48
bits of accuracy. For example:bits of accuracy. For example:
```js```js
const buf = new Buffer(6);const buf = Buffer.allocUnsafe (6);
buf.writeUInt16LE(0x90ab, 0);buf.writeUInt16LE(0x90ab, 0);
buf.writeUInt32LE(0x12345678, 2);buf.writeUInt32LE(0x12345678, 2);
buf.readUIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)buf.readUIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)
@ -904,7 +1217,7 @@ Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
byte from the original Buffer.byte from the original Buffer.
```js```js
const buf1 = new Buffer(26);const buf1 = Buffer.allocUnsafe (26);
for (var i = 0 ; i < 26 ; i + + ) { for (var i = 0 ; i < 26 ; i + + ) {
buf1[i] = i + 97; // 97 is ASCII a buf1[i] = i + 97; // 97 is ASCII a
@ -922,7 +1235,7 @@ Specifying negative indexes causes the slice to be generated relative to the
end of the Buffer rather than the beginning.end of the Buffer rather than the beginning.
```js```js
const buf = new Buffer('buffer');const buf = Buffer.from ('buffer');
buf.slice(-6, -1).toString();buf.slice(-6, -1).toString();
// Returns 'buffe', equivalent to buf.slice(0, 5) // Returns 'buffe', equivalent to buf.slice(0, 5)
@ -943,7 +1256,7 @@ Decodes and returns a string from the Buffer data using the specified
character set `encoding` .character set `encoding` .
```js```js
const buf = new Buffer(26);const buf = Buffer.allocUnsafe (26);
for (var i = 0 ; i < 26 ; i + + ) { for (var i = 0 ; i < 26 ; i + + ) {
buf[i] = i + 97; // 97 is ASCII a buf[i] = i + 97; // 97 is ASCII a
}}
@ -967,7 +1280,7 @@ implicitly calls this function when stringifying a Buffer instance.
Example:Example:
```js```js
const buf = new Buffer('test');const buf = Buffer.from ('test');
const json = JSON.stringify(buf);const json = JSON.stringify(buf);
console.log(json);console.log(json);
@ -975,7 +1288,7 @@ console.log(json);
const copy = JSON.parse(json, (key, value) => {const copy = JSON.parse(json, (key, value) => {
return value & & value.type === 'Buffer' return value & & value.type === 'Buffer'
? new Buffer(value.data) ? Buffer.from (value.data)
: value; : value;
}); });
@ -991,7 +1304,7 @@ Creates and returns an [iterator][] for Buffer values (bytes). This function is
called automatically when the Buffer is used in a `for..of` statement.called automatically when the Buffer is used in a `for..of` statement.
```js```js
const buf = new Buffer('buffer');const buf = Buffer.from ('buffer');
for (var value of buf.values()) {for (var value of buf.values()) {
console.log(value); console.log(value);
}}
@ -1030,7 +1343,7 @@ string will be written however, it will not write only partially encoded
characters.characters.
```js```js
const buf = new Buffer(256);const buf = Buffer.allocUnsafe (256);
const len = buf.write('\u00bd + \u00bc = \u00be', 0);const len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾ // Prints: 12 bytes: ½ + ¼ = ¾
@ -1056,7 +1369,7 @@ should not be used unless you are certain of correctness.
Example:Example:
```js```js
const buf = new Buffer(8);const buf = Buffer.allocUnsafe (8);
buf.writeDoubleBE(0xdeadbeefcafebabe, 0);buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
console.log(buf);console.log(buf);
@ -1089,7 +1402,7 @@ should not be used unless you are certain of correctness.
Example:Example:
```js```js
const buf = new Buffer(4);const buf = Buffer.allocUnsafe (4);
buf.writeFloatBE(0xcafebabe, 0);buf.writeFloatBE(0xcafebabe, 0);
console.log(buf);console.log(buf);
@ -1119,7 +1432,7 @@ should not be used unless you are certain of correctness.
The `value` is interpreted and written as a two's complement signed integer.The `value` is interpreted and written as a two's complement signed integer.
```js```js
const buf = new Buffer(2);const buf = Buffer.allocUnsafe (2);
buf.writeInt8(2, 0);buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);buf.writeInt8(-2, 1);
console.log(buf);console.log(buf);
@ -1146,7 +1459,7 @@ should not be used unless you are certain of correctness.
The `value` is interpreted and written as a two's complement signed integer.The `value` is interpreted and written as a two's complement signed integer.
```js```js
const buf = new Buffer(4);const buf = Buffer.allocUnsafe (4);
buf.writeInt16BE(0x0102,0);buf.writeInt16BE(0x0102,0);
buf.writeInt16LE(0x0304,2);buf.writeInt16LE(0x0304,2);
console.log(buf);console.log(buf);
@ -1173,7 +1486,7 @@ should not be used unless you are certain of correctness.
The `value` is interpreted and written as a two's complement signed integer.The `value` is interpreted and written as a two's complement signed integer.
```js```js
const buf = new Buffer(8);const buf = Buffer.allocUnsafe (8);
buf.writeInt32BE(0x01020304,0);buf.writeInt32BE(0x01020304,0);
buf.writeInt32LE(0x05060708,4);buf.writeInt32LE(0x05060708,4);
console.log(buf);console.log(buf);
@ -1193,12 +1506,12 @@ Writes `value` to the Buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example:Supports up to 48 bits of accuracy. For example:
```js```js
const buf1 = new Buffer(6);const buf1 = Buffer.allocUnsafe (6);
buf1.writeUIntBE(0x1234567890ab, 0, 6);buf1.writeUIntBE(0x1234567890ab, 0, 6);
console.log(buf1);console.log(buf1);
// Prints: < Buffer 12 34 56 78 90 ab > // Prints: < Buffer 12 34 56 78 90 ab >
const buf2 = new Buffer(6);const buf2 = Buffer.allocUnsafe (6);
buf2.writeUIntLE(0x1234567890ab, 0, 6);buf2.writeUIntLE(0x1234567890ab, 0, 6);
console.log(buf2);console.log(buf2);
// Prints: < Buffer ab 90 78 56 34 12 > // Prints: < Buffer ab 90 78 56 34 12 >
@ -1227,7 +1540,7 @@ should not be used unless you are certain of correctness.
Example:Example:
```js```js
const buf = new Buffer(4);const buf = Buffer.allocUnsafe (4);
buf.writeUInt8(0x3, 0);buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);buf.writeUInt8(0x23, 2);
@ -1257,7 +1570,7 @@ should not be used unless you are certain of correctness.
Example:Example:
```js```js
const buf = new Buffer(4);const buf = Buffer.allocUnsafe (4);
buf.writeUInt16BE(0xdead, 0);buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);buf.writeUInt16BE(0xbeef, 2);
@ -1291,7 +1604,7 @@ should not be used unless you are certain of correctness.
Example:Example:
```js```js
const buf = new Buffer(4);const buf = Buffer.allocUnsafe (4);
buf.writeUInt32BE(0xfeedface, 0);buf.writeUInt32BE(0xfeedface, 0);
console.log(buf);console.log(buf);
@ -1316,7 +1629,7 @@ Writes `value` to the Buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example:Supports up to 48 bits of accuracy. For example:
```js```js
const buf = new Buffer(6);const buf = Buffer.allocUnsafe (6);
buf.writeUIntBE(0x1234567890ab, 0, 6);buf.writeUIntBE(0x1234567890ab, 0, 6);
console.log(buf);console.log(buf);
// Prints: < Buffer 12 34 56 78 90 ab > // Prints: < Buffer 12 34 56 78 90 ab >
@ -1358,7 +1671,7 @@ const store = [];
socket.on('readable', () => {socket.on('readable', () => {
var data = socket.read(); var data = socket.read();
// allocate for retained data // allocate for retained data
var sb = new SlowBuffer(10); var sb = SlowBuffer(10);
// copy the data into the new allocation // copy the data into the new allocation
data.copy(sb, 0, 0, 10); data.copy(sb, 0, 0, 10);
store.push(sb); store.push(sb);
@ -1368,8 +1681,34 @@ socket.on('readable', () => {
Use of `SlowBuffer` should be used only as a last resort *after* a developerUse of `SlowBuffer` should be used only as a last resort *after* a developer
has observed undue memory retention in their applications.has observed undue memory retention in their applications.
[`Array#includes()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes### new SlowBuffer(size)
* `size` Number
Allocates a new `SlowBuffer` of `size` bytes. The `size` must be less than
or equal to the value of `require('buffer').kMaxLength` (on 64-bit
architectures, `kMaxLength` is `(2^31)-1` ). Otherwise, a [`RangeError`][] is
thrown. If a `size` less than 0 is specified, a zero-length `SlowBuffer` will be
created.
The underlying memory for `SlowBuffer` instances is *not initialized* . The
contents of a newly created `SlowBuffer` are unknown and could contain
sensitive data. Use [`buf.fill(0)`][] to initialize a `SlowBuffer` to zeroes.
```js
const SlowBuffer = require('buffer').SlowBuffer;
const buf = new SlowBuffer(5);
console.log(buf);
// < Buffer 78 e0 82 02 01 >
// (octets will be different, every time)
buf.fill(0);
console.log(buf);
// < Buffer 00 00 00 00 00 >
```
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
[`Array#indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf[`Array#indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
[`Array#includes()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
[`buf.entries()`]: #buffer_buf_entries [`buf.entries()`]: #buffer_buf_entries
[`buf.fill(0)`]: #buffer_buf_fill_value_offset_end [`buf.fill(0)`]: #buffer_buf_fill_value_offset_end
[`buf.keys()`]: #buffer_buf_keys [`buf.keys()`]: #buffer_buf_keys
@ -1380,5 +1719,11 @@ has observed undue memory retention in their applications.
[`RangeError`]: errors.html#errors_class_rangeerror[`RangeError`]: errors.html#errors_class_rangeerror
[`String.prototype.length`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length[`String.prototype.length`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length
[`util.inspect()`]: util.html#util_util_inspect_object_options[`util.inspect()`]: util.html#util_util_inspect_object_options
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
[RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5[RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
[buffer_from_array]: #buffer_class_method_buffer_from_array
[buffer_from_buffer]: #buffer_class_method_buffer_from_buffer
[buffer_from_arraybuf]: #buffer_class_method_buffer_from_arraybuffer
[buffer_from_string]: #buffer_class_method_buffer_from_str_encoding
[buffer_allocunsafe]: #buffer_class_method_buffer_allocraw_size
[buffer_alloc]: #buffer_class_method_buffer_alloc_size_fill_encoding
[`TypedArray.from()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from
James M Snell
9 years ago