doc: document bytes to chars after setEncoding · nodejs/node@feb6863

@@ -66,8 +66,8 @@ buffer that can be retrieved using `writable._writableState.getBuffer()` or

66666767

The amount of data potentially buffered depends on the `highWaterMark` option

6868

passed into the streams constructor. For normal streams, the `highWaterMark`

69-

option specifies a total number of bytes. For streams operating in object mode,

70-

the `highWaterMark` specifies a total number of objects.

69+

option specifies a [total number of bytes][hwm-gotcha]. For streams operating

70+

in object mode, the `highWaterMark` specifies a total number of objects.

71717272

Data is buffered in Readable streams when the implementation calls

7373

[`stream.push(chunk)`][stream-push]. If the consumer of the Stream does not

@@ -1415,9 +1415,9 @@ constructor and implement the `readable._read()` method.

14151415

#### new stream.Readable([options])

1416141614171417

* `options` {Object}

1418-

* `highWaterMark` {number} The maximum number of bytes to store in

1419-

the internal buffer before ceasing to read from the underlying

1420-

resource. Defaults to `16384` (16kb), or `16` for `objectMode` streams

1418+

* `highWaterMark` {number} The maximum [number of bytes][hwm-gotcha] to store

1419+

in the internal buffer before ceasing to read from the underlying resource.

1420+

Defaults to `16384` (16kb), or `16` for `objectMode` streams

14211421

* `encoding` {string} If specified, then buffers will be decoded to

14221422

strings using the specified encoding. Defaults to `null`

14231423

* `objectMode` {boolean} Whether this stream should behave

@@ -2031,6 +2031,19 @@ has an interesting side effect. Because it *is* a call to

20312031

However, because the argument is an empty string, no data is added to the

20322032

readable buffer so there is nothing for a user to consume.

203320332034+

### `highWaterMark` discrepency after calling `readable.setEncoding()`

2035+2036+

The use of `readable.setEncoding()` will change the behavior of how the

2037+

`highWaterMark` operates in non-object mode.

2038+2039+

Typically, the size of the current buffer is measured against the

2040+

`highWaterMark` in _bytes_. However, after `setEncoding()` is called, the

2041+

comparison function will begin to measure the buffer's size in _characters_.

2042+2043+

This is not a problem in common cases with `latin1` or `ascii`. But it is

2044+

advised to be mindful about this behavior when working with strings that could

2045+

contain multi-byte characters.

2046+20342047

[`'data'`]: #stream_event_data

20352048

[`'drain'`]: #stream_event_drain

20362049

[`'end'`]: #stream_event_end

@@ -2065,6 +2078,8 @@ readable buffer so there is nothing for a user to consume.

20652078

[http-incoming-message]: http.html#http_class_http_incomingmessage

20662079

[Readable]: #stream_class_stream_readable

20672080

[zlib]: zlib.html

2081+

[hwm-gotcha]: #stream_highWaterMark_discrepency_after_calling_readable_setencoding

2082+

[Readable]: #stream_class_stream_readable

20682083

[stream-_flush]: #stream_transform_flush_callback

20692084

[stream-_read]: #stream_readable_read_size_1

20702085

[stream-_transform]: #stream_transform_transform_chunk_encoding_callback