From 0410b5b6493bcd3f8d78d41c6c5ed0a0801825f4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Thu, 29 Mar 2018 14:23:58 -0700 Subject: [PATCH 1/2] doc: remove ES6/ECMAScript 2015 from buffer.md As the introduction of ES6 features recedes further into the past, it is less and less relevant (and more and more distracting) to cite it in documentation text. Remove mention in buffer.md. PR-URL: https://github.com/nodejs/node/pull/19685 Reviewed-By: Tiancheng "Timothy" Gu Reviewed-By: Vse Mozhet Byt Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat Reviewed-By: Colin Ihrig --- doc/api/buffer.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 1c4930d5cb2f79..b1a2fb74bfc58d 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -4,15 +4,14 @@ > 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 make it possible to interact with +octet streams in the context of things like TCP streams and file system +operations. -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. @@ -211,11 +210,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: @@ -289,10 +287,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: @@ -2757,5 +2754,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 From aa9d4eb739a11cf4edc0c690756a751150a81533 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Thu, 12 Apr 2018 01:46:48 -0400 Subject: [PATCH 2/2] doc: Uint8Array support in Buffer functions Buffer.from / new Buffer accept Uint8Array Fixes: https://github.com/nodejs/node/issues/14118 PR-URL: https://github.com/nodejs/node/pull/19949 Reviewed-By: Anna Henningsen Reviewed-By: Vse Mozhet Byt Reviewed-By: Benjamin Gruenbaum Reviewed-By: James M Snell Reviewed-By: Gus Caplan --- doc/api/buffer.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index b1a2fb74bfc58d..6f31cbdc55cf3e 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -6,9 +6,8 @@ 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 make it possible to interact with -octet streams in the context of things like TCP streams and file system -operations. +was introduced as part of the Node.js API to enable interaction with octet +streams in TCP streams, file system operations, and other contexts. With [`TypedArray`] now available, the `Buffer` class implements the [`Uint8Array`] API in a manner that is more optimized and suitable for Node.js. @@ -195,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 -* `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. @@ -1983,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: @@ -2013,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: @@ -2043,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: