diff options
author | FUJI Goro (gfx) <gfuji@cpan.org> | 2019-06-06 16:43:22 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2019-06-13 05:40:37 +0300 |
commit | ee167877ad55242c61f68b0c53e253584294801b (patch) | |
tree | 2c4695d141bf5c9974cd825a8e5f5379917315b0 | |
parent | 0a3885e8a7dc6c452202fdc1d232c26d173871f2 (diff) |
doc: add Buffer#subarray() and add note about Uint8Array#slice()
PR-URL: https://github.com/nodejs/node/pull/28101
Refs: https://github.com/nodejs/node/issues/28087
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
-rw-r--r-- | doc/api/buffer.md | 67 |
1 files changed, 49 insertions, 18 deletions
diff --git a/doc/api/buffer.md b/doc/api/buffer.md index dfb18eeb561..00dd366faef 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1896,18 +1896,9 @@ console.log(buf.readUIntBE(1, 6).toString(16)); // Throws ERR_OUT_OF_RANGE. ``` -### buf.slice([start[, end]]) +### buf.subarray([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. +added: v3.0.0 --> * `start` {integer} Where the new `Buffer` will start. **Default:** `0`. @@ -1935,7 +1926,7 @@ for (let i = 0; i < 26; i++) { buf1[i] = i + 97; } -const buf2 = buf1.slice(0, 3); +const buf2 = buf1.subarray(0, 3); console.log(buf2.toString('ascii', 0, buf2.length)); // Prints: abc @@ -1952,17 +1943,57 @@ end of `buf` rather than the beginning. ```js const buf = Buffer.from('buffer'); -console.log(buf.slice(-6, -1).toString()); +console.log(buf.subarray(-6, -1).toString()); // Prints: buffe -// (Equivalent to buf.slice(0, 5).) +// (Equivalent to buf.subarray(0, 5).) -console.log(buf.slice(-6, -2).toString()); +console.log(buf.subarray(-6, -2).toString()); // Prints: buff -// (Equivalent to buf.slice(0, 4).) +// (Equivalent to buf.subarray(0, 4).) -console.log(buf.slice(-5, -2).toString()); +console.log(buf.subarray(-5, -2).toString()); // Prints: uff -// (Equivalent to buf.slice(1, 4).) +// (Equivalent to buf.subarray(1, 4).) +``` + +### 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`. +* `end` {integer} Where the new `Buffer` will end (not inclusive). + **Default:** [`buf.length`][]. +* Returns: {Buffer} + +Returns a new `Buffer` that references the same memory as the original, but +offset and cropped by the `start` and `end` indices. + +This is the same behavior as `buf.subarray()`. + +This method is not compatible with the `Uint8Array.prototype.slice()`, +which is a superclass of `Buffer`. To copy the slice, use +`Uint8Array.prototype.slice()`. + +```js +const buf = Buffer.from('buffer'); + +const copiedBuf = Uint8Array.prototype.slice.call(buf); +copiedBuf[0]++; +console.log(copiedBuf.toString()); +// Prints: cuffer + +console.log(buf.toString()); +// Prints: buffer ``` ### buf.swap16() |