From e509db8c564a660231cc09afef3d900f58201afc Mon Sep 17 00:00:00 2001 From: dicearr Date: Mon, 23 Oct 2017 09:28:52 +0200 Subject: doc: howto decode buffers extending from Writable Improved stream documentation with an example of how to decode buffers to strings within a custom Writable. Fixes: https://github.com/nodejs/node/issues/15369 PR-URL: https://github.com/nodejs/node/pull/16403 Reviewed-By: Matteo Collina Reviewed-By: Benjamin Gruenbaum Reviewed-By: Gireesh Punathil --- doc/api/stream.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'doc/api/stream.md') diff --git a/doc/api/stream.md b/doc/api/stream.md index 96f67d75b3..e5515432b0 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1510,6 +1510,47 @@ class MyWritable extends Writable { } ``` +#### Decoding buffers in a Writable Stream + +Decoding buffers is a common task, for instance, when using transformers whose +input is a string. This is not a trivial process when using multi-byte +characters encoding, such as UTF-8. The following example shows how to decode +multi-byte strings using `StringDecoder` and [Writable][]. + +```js +const { Writable } = require('stream'); +const { StringDecoder } = require('string_decoder'); + +class StringWritable extends Writable { + constructor(options) { + super(options); + const state = this._writableState; + this._decoder = new StringDecoder(state.defaultEncoding); + this.data = ''; + } + _write(chunk, encoding, callback) { + if (encoding === 'buffer') { + chunk = this._decoder.write(chunk); + } + this.data += chunk; + callback(); + } + _final(callback) { + this.data += this._decoder.end(); + callback(); + } +} + +const euro = [[0xE2, 0x82], [0xAC]].map(Buffer.from); +const w = new StringWritable(); + +w.write('currency: '); +w.write(euro[0]); +w.end(euro[1]); + +console.log(w.data); // currency: € +``` + ### Implementing a Readable Stream The `stream.Readable` class is extended to implement a [Readable][] stream. -- cgit v1.2.3