Skip to content
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

[v8.x backport] doc: Backport #19685 and #19949 to v8.x #21590

Closed
wants to merge 2 commits into from
Closed

[v8.x backport] doc: Backport #19685 and #19949 to v8.x #21590

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0410b5b
doc: remove ES6/ECMAScript 2015 from buffer.md
Trott Mar 29, 2018
aa9d4eb
doc: Uint8Array support in Buffer functions
SheetJSDev Apr 12, 2018
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
53 changes: 25 additions & 28 deletions doc/api/buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,13 @@

> Stability: 2 - Stable

Prior to the introduction of [`TypedArray`] in [`ECMAScript 2015`] (ES6), the
JavaScript language had no mechanism for reading or manipulating streams
of binary data. The `Buffer` class was introduced as part of the Node.js
API to make it possible to interact with octet streams in the context of things
like TCP streams and file system operations.
Prior to the introduction of [`TypedArray`], the JavaScript language had no
mechanism for reading or manipulating streams of binary data. The `Buffer` class
was introduced as part of the Node.js API to enable interaction with octet
streams in TCP streams, file system operations, and other contexts.

Now that [`TypedArray`] has been added in ES6, the `Buffer` class implements the
[`Uint8Array`] API in a manner that is more optimized and suitable for Node.js'
use cases.
With [`TypedArray`] now available, the `Buffer` class implements the
[`Uint8Array`] API in a manner that is more optimized and suitable for Node.js.

Instances of the `Buffer` class are similar to arrays of integers but
correspond to fixed-sized, raw memory allocations outside the V8 heap.
Expand Down Expand Up @@ -196,11 +194,11 @@ The character encodings currently supported by Node.js include:
* `'hex'` - Encode each byte as two hexadecimal characters.

*Note*: Today's browsers follow the [WHATWG Encoding Standard][] which aliases
both 'latin1' and ISO-8859-1 to win-1252. This means that while doing something
like `http.get()`, if the returned charset is one of those listed in the WHATWG
specification it is possible that the server actually returned
win-1252-encoded data, and using `'latin1'` encoding may incorrectly decode the
characters.
both `'latin1'` and `'ISO-8859-1'` to `'win-1252'`. This means that while doing
something like `http.get()`, if the returned charset is one of those listed in
the WHATWG specification it is possible that the server actually returned
`'win-1252'`-encoded data, and using `'latin1'` encoding may incorrectly decode
the characters.

## Buffers and TypedArray
<!-- YAML
Expand All @@ -211,11 +209,10 @@ changes:
-->

`Buffer` instances are also [`Uint8Array`] instances. However, there are subtle
incompatibilities with the TypedArray specification in [`ECMAScript 2015`].
For example, while [`ArrayBuffer#slice()`] creates a copy of the slice, the
implementation of [`Buffer#slice()`][`buf.slice()`] creates a view over the
existing `Buffer` without copying, making [`Buffer#slice()`][`buf.slice()`] far
more efficient.
incompatibilities with [`TypedArray`]. For example, while
[`ArrayBuffer#slice()`] creates a copy of the slice, the implementation of
[`Buffer#slice()`][`buf.slice()`] creates a view over the existing `Buffer`
without copying, making [`Buffer#slice()`][`buf.slice()`] far more efficient.

It is also possible to create new [`TypedArray`] instances from a `Buffer` with
the following caveats:
Expand Down Expand Up @@ -289,10 +286,9 @@ function:
* [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][`Buffer.from(arrayBuffer)`]
* [`Buffer.from(string[, encoding])`][`Buffer.from(string)`]

## Buffers and ES6 iteration
## Buffers and iteration

`Buffer` instances can be iterated over using the [`ECMAScript 2015`] (ES6) `for..of`
syntax.
`Buffer` instances can be iterated over using `for..of` syntax:

Example:

Expand Down Expand Up @@ -341,7 +337,7 @@ Example:
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
```

### new Buffer(arrayBuffer[, byteOffset [, length]])
### new Buffer(arrayBuffer[, byteOffset[, length]])
<!-- YAML
added: v3.0.0
deprecated: v6.0.0
Expand Down Expand Up @@ -410,7 +406,8 @@ changes:

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

* `buffer` {Buffer} An existing `Buffer` to copy data from.
* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`] from which
to copy data.

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

Expand Down Expand Up @@ -865,7 +862,8 @@ A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`] or a
added: v5.10.0
-->

* `buffer` {Buffer} An existing `Buffer` to copy data from.
* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`] from which
to copy data.

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

Expand Down Expand Up @@ -1986,7 +1984,7 @@ added: v5.10.0

* Returns: {Buffer} A reference to `buf`.

Interprets `buf` as an array of unsigned 16-bit integers and swaps the byte-order
Interprets `buf` as an array of unsigned 16-bit integers and swaps the byte order
*in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 2.

Examples:
Expand Down Expand Up @@ -2016,7 +2014,7 @@ added: v5.10.0

* Returns: {Buffer} A reference to `buf`.

Interprets `buf` as an array of unsigned 32-bit integers and swaps the byte-order
Interprets `buf` as an array of unsigned 32-bit integers and swaps the byte order
*in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 4.

Examples:
Expand Down Expand Up @@ -2046,7 +2044,7 @@ added: v6.3.0

* Returns: {Buffer} A reference to `buf`.

Interprets `buf` as an array of 64-bit numbers and swaps the byte-order *in-place*.
Interprets `buf` as an array of 64-bit numbers and swaps the byte order *in-place*.
Throws a `RangeError` if [`buf.length`] is not a multiple of 8.

Examples:
Expand Down Expand Up @@ -2757,5 +2755,4 @@ This value may depend on the JS engine that is being used.
[RFC1345]: https://tools.ietf.org/html/rfc1345
[RFC4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
[WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
[`ECMAScript 2015`]: https://www.ecma-international.org/ecma-262/6.0/index.html
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols