diff options
author | dicearr <dcerearr@gmail.com> | 2017-10-23 09:28:52 +0200 |
---|---|---|
committer | Matteo Collina <hello@matteocollina.com> | 2017-10-31 19:43:04 +0100 |
commit | e509db8c564a660231cc09afef3d900f58201afc (patch) | |
tree | d2a5946f9ca0e43bb2d327287067c1b4ec086670 /doc/api/stream.md | |
parent | bb59d2bd19cd1e71cc3eeaa4918b36d0980b1c35 (diff) | |
download | android-node-v8-e509db8c564a660231cc09afef3d900f58201afc.tar.gz android-node-v8-e509db8c564a660231cc09afef3d900f58201afc.tar.bz2 android-node-v8-e509db8c564a660231cc09afef3d900f58201afc.zip |
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 <matteo.collina@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Diffstat (limited to 'doc/api/stream.md')
-rw-r--r-- | doc/api/stream.md | 41 |
1 files changed, 41 insertions, 0 deletions
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. |