Skip to content

(v7.x) doc: backport “fix sorting in API references”, “add changelogs for {v8,buffer}” #11529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

(v7.x) doc: backport “fix sorting in API references”, “add changelogs for {v8,buffer}” #11529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a6d5cc
doc: fix sorting in API references
vsemozhetbyt Feb 13, 2017
bddebc4
doc: add changelogs for v8
addaleax Feb 21, 2017
bcb1299
doc: add changelogs for buffer
addaleax Feb 21, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 184 additions & 96 deletions doc/api/buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,15 @@ extra care *must* be taken in order to avoid introducing security
vulnerabilities into an application.

## Buffers and Character Encodings
<!-- YAML
changes:
- version: v6.4.0
pr-url: https://github.com/nodejs/node/pull/7111
description: Introduced `latin1` as an alias for `binary`.
- version: v5.0.0
pr-url: https://github.com/nodejs/node/pull/2859
description: Removed the deprecated `raw` and `raws` encodings.
-->

`Buffer` instances are commonly used to represent sequences of encoded characters
such as UTF-8, UCS2, Base64 or even Hex-encoded data. It is possible to
Expand Down Expand Up @@ -188,6 +197,12 @@ that the server actually returned win-1252-encoded data, and using `'latin1'`
encoding may incorrectly decode the characters.

## Buffers and TypedArray
<!-- YAML
changes:
- version: v3.0.0
pr-url: https://github.com/nodejs/node/pull/2002
description: The `Buffer`s class now inherits from `Uint8Array`.
-->

`Buffer` instances are also [`Uint8Array`] instances. However, there are subtle
incompatibilities with the TypedArray specification in ECMAScript 2015.
Expand Down Expand Up @@ -298,6 +313,13 @@ It can be constructed in a variety of ways.
### new Buffer(array)
<!-- YAML
deprecated: v6.0.0
changes:
- version: v7.2.1
pr-url: https://github.com/nodejs/node/pull/9529
description: Calling this constructor no longer emits a deprecation warning.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8169
description: Calling this constructor emits a deprecation warning now.
-->

> Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead.
Expand All @@ -313,35 +335,20 @@ Example:
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
```

### new Buffer(buffer)
<!-- YAML
deprecated: v6.0.0
-->

> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.

* `buffer` {Buffer} An existing `Buffer` to copy data from

Copies the passed `buffer` data onto a new `Buffer` instance.

Example:

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

buf1[0] = 0x61;

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

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

### new Buffer(arrayBuffer[, byteOffset [, length]])
<!-- YAML
added: v3.0.0
deprecated: v6.0.0
changes:
- version: v7.2.1
pr-url: https://github.com/nodejs/node/pull/9529
description: Calling this constructor no longer emits a deprecation warning.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8169
description: Calling this constructor emits a deprecation warning now.
- version: v6.0.0
pr-url: https://github.com/nodejs/node/pull/4682
description: The `byteOffset` and `length` parameters are supported now.
-->

> Stability: 0 - Deprecated: Use
Expand Down Expand Up @@ -383,9 +390,49 @@ arr[1] = 6000;
console.log(buf);
```

### new Buffer(buffer)
<!-- YAML
deprecated: v6.0.0
changes:
- version: v7.2.1
pr-url: https://github.com/nodejs/node/pull/9529
description: Calling this constructor no longer emits a deprecation warning.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8169
description: Calling this constructor emits a deprecation warning now.
-->

> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.

* `buffer` {Buffer} An existing `Buffer` to copy data from

Copies the passed `buffer` data onto a new `Buffer` instance.

Example:

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

buf1[0] = 0x61;

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

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

### new Buffer(size)
<!-- YAML
deprecated: v6.0.0
changes:
- version: v7.2.1
pr-url: https://github.com/nodejs/node/pull/9529
description: Calling this constructor no longer emits a deprecation warning.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8169
description: Calling this constructor emits a deprecation warning now.
-->

> Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see
Expand Down Expand Up @@ -419,6 +466,13 @@ console.log(buf);
### new Buffer(string[, encoding])
<!-- YAML
deprecated: v6.0.0
changes:
- version: v7.2.1
pr-url: https://github.com/nodejs/node/pull/9529
description: Calling this constructor no longer emits a deprecation warning.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8169
description: Calling this constructor emits a deprecation warning now.
-->

> Stability: 0 - Deprecated:
Expand Down Expand Up @@ -508,6 +562,10 @@ A `TypeError` will be thrown if `size` is not a number.
### Class Method: Buffer.allocUnsafe(size)
<!-- YAML
added: v5.10.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/7079
description: Passing a negative `size` will now throw an error.
-->

* `size` {Integer} The desired length of the new `Buffer`
Expand Down Expand Up @@ -606,6 +664,14 @@ A `TypeError` will be thrown if `size` is not a number.
### Class Method: Buffer.byteLength(string[, encoding])
<!-- YAML
added: v0.1.90
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/8946
description: Passing invalid input will now throw an error.
- version: v5.10.0
pr-url: https://github.com/nodejs/node/pull/5255
description: The `string` parameter can now be any `TypedArray`, `DataView`
or `ArrayBuffer`.
-->

* `string` {String | Buffer | TypedArray | DataView | ArrayBuffer} A value to
Expand Down Expand Up @@ -886,6 +952,10 @@ console.log(buf.toString('ascii'));
### buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
<!-- YAML
added: v0.11.13
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5880
description: Additional parameters for specifying offsets are supported now.
-->

* `target` {Buffer} A `Buffer` to compare to
Expand Down Expand Up @@ -1066,6 +1136,10 @@ console.log(buf1.equals(buf3));
### buf.fill(value[, offset[, end]][, encoding])
<!-- YAML
added: v0.5.0
changes:
- version: v5.7.0
pr-url: https://github.com/nodejs/node/pull/4935
description: The `encoding` parameter is supported now.
-->

* `value` {String | Buffer | Integer} The value to fill `buf` with
Expand Down Expand Up @@ -1100,9 +1174,55 @@ Example: Fill a `Buffer` with a two-byte character
console.log(Buffer.allocUnsafe(3).fill('\u0222'));
```

### buf.includes(value[, byteOffset][, encoding])
<!-- YAML
added: v5.3.0
-->

* `value` {String | Buffer | Integer} What to search for
* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0`
* `encoding` {String} If `value` is a string, this is its encoding.
**Default:** `'utf8'`
* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise

Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].

Examples:

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

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

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

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

// Prints: true
// (97 is the decimal ASCII value for 'a')
console.log(buf.includes(97));

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

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

// Prints: false
console.log(buf.includes('this', 4));
```

### buf.indexOf(value[, byteOffset][, encoding])
<!-- YAML
added: v1.5.0
changes:
- version: v5.7.0, v4.4.0
pr-url: https://github.com/nodejs/node/pull/4803
description: When `encoding` is being passed, the `byteOffset` parameter
is no longer required.
-->

* `value` {String | Buffer | Integer} What to search for
Expand Down Expand Up @@ -1179,47 +1299,6 @@ console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));
```

### buf.includes(value[, byteOffset][, encoding])
<!-- YAML
added: v5.3.0
-->

* `value` {String | Buffer | Integer} What to search for
* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0`
* `encoding` {String} If `value` is a string, this is its encoding.
**Default:** `'utf8'`
* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise

Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].

Examples:

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

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

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

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

// Prints: true
// (97 is the decimal ASCII value for 'a')
console.log(buf.includes(97));

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

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

// Prints: false
console.log(buf.includes('this', 4));
```

### buf.keys()
<!-- YAML
added: v1.1.0
Expand Down Expand Up @@ -1710,6 +1789,15 @@ console.log(buf.readUIntBE(1, 6).toString(16));
### buf.slice([start[, end]])
<!-- YAML
added: v0.3.0
changes:
- version: v7.1.0, v6.9.2
pr-url: https://github.com/nodejs/node/pull/9341
description: Coercing the offsets to integers now handles values outside
the 32-bit integer range properly.
- version: v7.0.0
pr-url: https://github.com/nodejs/node/pull/9101
description: All offsets are now coerced to integers before doing any
calculations with them.
-->

* `start` {Integer} Where the new `Buffer` will start. **Default:** `0`
Expand Down Expand Up @@ -1859,6 +1947,35 @@ buf2.swap64();
Note that JavaScript cannot encode 64-bit integers. This method is intended
for working with 64-bit floats.

### buf.toJSON()
<!-- YAML
added: v0.9.2
-->

* Returns: {Object}

Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls
this function when stringifying a `Buffer` instance.

Example:

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

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

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

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

### buf.toString([encoding[, start[, end]]])
<!-- YAML
added: v0.1.90
Expand Down Expand Up @@ -1902,35 +2019,6 @@ console.log(buf2.toString('utf8', 0, 3));
console.log(buf2.toString(undefined, 0, 3));
```

### buf.toJSON()
<!-- YAML
added: v0.9.2
-->

* Returns: {Object}

Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls
this function when stringifying a `Buffer` instance.

Example:

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

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

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

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

### buf.values()
<!-- YAML
added: v1.1.0
Expand Down
Loading