Skip to content

Commit

Permalink
doc: don't suggest setEncoding for binary streams
Browse files Browse the repository at this point in the history
Removed an incorrect reference to the use of setEncoding(null) as the
proper way to handling binary streams or to disable encoding, and
explained that the default encoding is "no encoding", and that this is
the correct approach for dealing with binary data via Buffers.

PR-URL: #11363
Fixes: #11352
Refs: #11316
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
  • Loading branch information
RickBullotta authored and MylesBorins committed Jul 17, 2017
1 parent 092bba5 commit e400ef9
Showing 1 changed file with 5 additions and 8 deletions.
13 changes: 5 additions & 8 deletions doc/api/stream.md
Expand Up @@ -926,24 +926,21 @@ added: v0.9.4
* `encoding` {string} The encoding to use.
* Returns: `this`

The `readable.setEncoding()` method sets the default character encoding for
The `readable.setEncoding()` method sets the character encoding for
data read from the Readable stream.

Setting an encoding causes the stream data
to be returned as string of the specified encoding rather than as `Buffer`
By default, no encoding is assigned and stream data will be returned as
`Buffer` objects. Setting an encoding causes the stream data
to be returned as strings of the specified encoding rather than as `Buffer`
objects. For instance, calling `readable.setEncoding('utf8')` will cause the
output data will be interpreted as UTF-8 data, and passed as strings. Calling
output data to be interpreted as UTF-8 data, and passed as strings. Calling
`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal
string format.

The Readable stream will properly handle multi-byte characters delivered through
the stream that would otherwise become improperly decoded if simply pulled from
the stream as `Buffer` objects.

Encoding can be disabled by calling `readable.setEncoding(null)`. This approach
is useful when working with binary data or with large multi-byte strings spread
out over multiple chunks.

```js
const readable = getReadableStreamSomehow();
readable.setEncoding('utf8');
Expand Down

0 comments on commit e400ef9

Please sign in to comment.