Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
doc: deprecate buffer.slice
PR-URL: #41596
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
  • Loading branch information
benjamingr authored and danielleadams committed Apr 21, 2022
1 parent 0be2321 commit e46c7d6
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 4 deletions.
12 changes: 8 additions & 4 deletions doc/api/buffer.md
Expand Up @@ -252,7 +252,7 @@ In particular:
without copying. This behavior can be surprising, and only exists for legacy
compatibility. [`TypedArray.prototype.subarray()`][] can be used to achieve
the behavior of [`Buffer.prototype.slice()`][`buf.slice()`] on both `Buffer`s
and other `TypedArray`s.
and other `TypedArray`s and should be preferred.
* [`buf.toString()`][] is incompatible with its `TypedArray` equivalent.
* A number of methods, e.g. [`buf.indexOf()`][], support additional arguments.

Expand Down Expand Up @@ -2038,7 +2038,7 @@ If `value` is:
* a string, `value` is interpreted according to the character encoding in
`encoding`.
* a `Buffer` or [`Uint8Array`][], `value` will be used in its entirety.
To compare a partial `Buffer`, use [`buf.slice()`][].
To compare a partial `Buffer`, use [`buf.subarray`][].
* a number, `value` will be interpreted as an unsigned 8-bit integer
value between `0` and `255`.

Expand Down Expand Up @@ -3371,6 +3371,9 @@ console.log(buf.subarray(-5, -2).toString());
<!-- YAML
added: v0.3.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/41596
description: The buf.slice() method has been deprecated.
- version:
- v7.1.0
- v6.9.2
Expand All @@ -3388,11 +3391,11 @@ changes:
**Default:** [`buf.length`][].
* Returns: {Buffer}

> Stability: 0 - Deprecated: Use [`buf.subarray`][] instead.
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()`.
Expand Down Expand Up @@ -5349,6 +5352,7 @@ introducing security vulnerabilities into an application.
[`buf.keys()`]: #bufkeys
[`buf.length`]: #buflength
[`buf.slice()`]: #bufslicestart-end
[`buf.subarray`]: #bufsubarraystart-end
[`buf.toString()`]: #buftostringencoding-start-end
[`buf.values()`]: #bufvalues
[`buffer.constants.MAX_LENGTH`]: #bufferconstantsmax_length
Expand Down
17 changes: 17 additions & 0 deletions doc/api/deprecations.md
Expand Up @@ -3032,6 +3032,22 @@ const w = new Writable({
});
```

### DEP0158: `buffer.slice(start, end)`

<!-- YAML
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/41596
description: Documentation-only deprecation.
-->

Type: Documentation-only

This method was deprecated because it is not compatible with
`Uint8Array.prototype.slice()`, which is a superclass of `Buffer`.

Use [`buffer.subarray`][] which does the same thing instead.

[Legacy URL API]: url.md#legacy-url-api
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
[RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
Expand All @@ -3054,6 +3070,7 @@ const w = new Writable({
[`WriteStream.open()`]: fs.md#class-fswritestream
[`assert`]: assert.md
[`asyncResource.runInAsyncScope()`]: async_context.md#asyncresourceruninasyncscopefn-thisarg-args
[`buffer.subarray`]: buffer.md#bufsubarraystart-end
[`child_process`]: child_process.md
[`clearInterval()`]: timers.md#clearintervaltimeout
[`clearTimeout()`]: timers.md#cleartimeouttimeout
Expand Down

0 comments on commit e46c7d6

Please sign in to comment.