1# String decoder 2 3<!--introduced_in=v0.10.0--> 4 5> Stability: 2 - Stable 6 7<!-- source_link=lib/string_decoder.js --> 8 9The `node:string_decoder` module provides an API for decoding `Buffer` objects 10into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 11characters. It can be accessed using: 12 13```js 14const { StringDecoder } = require('node:string_decoder'); 15``` 16 17The following example shows the basic use of the `StringDecoder` class. 18 19```js 20const { StringDecoder } = require('node:string_decoder'); 21const decoder = new StringDecoder('utf8'); 22 23const cent = Buffer.from([0xC2, 0xA2]); 24console.log(decoder.write(cent)); // Prints: ¢ 25 26const euro = Buffer.from([0xE2, 0x82, 0xAC]); 27console.log(decoder.write(euro)); // Prints: € 28``` 29 30When a `Buffer` instance is written to the `StringDecoder` instance, an 31internal buffer is used to ensure that the decoded string does not contain 32any incomplete multibyte characters. These are held in the buffer until the 33next call to `stringDecoder.write()` or until `stringDecoder.end()` is called. 34 35In the following example, the three UTF-8 encoded bytes of the European Euro 36symbol (`€`) are written over three separate operations: 37 38```js 39const { StringDecoder } = require('node:string_decoder'); 40const decoder = new StringDecoder('utf8'); 41 42decoder.write(Buffer.from([0xE2])); 43decoder.write(Buffer.from([0x82])); 44console.log(decoder.end(Buffer.from([0xAC]))); // Prints: € 45``` 46 47## Class: `StringDecoder` 48 49### `new StringDecoder([encoding])` 50 51<!-- YAML 52added: v0.1.99 53--> 54 55* `encoding` {string} The character [encoding][] the `StringDecoder` will use. 56 **Default:** `'utf8'`. 57 58Creates a new `StringDecoder` instance. 59 60### `stringDecoder.end([buffer])` 61 62<!-- YAML 63added: v0.9.3 64--> 65 66* `buffer` {string|Buffer|TypedArray|DataView} The bytes to decode. 67* Returns: {string} 68 69Returns any remaining input stored in the internal buffer as a string. Bytes 70representing incomplete UTF-8 and UTF-16 characters will be replaced with 71substitution characters appropriate for the character encoding. 72 73If the `buffer` argument is provided, one final call to `stringDecoder.write()` 74is performed before returning the remaining input. 75After `end()` is called, the `stringDecoder` object can be reused for new input. 76 77### `stringDecoder.write(buffer)` 78 79<!-- YAML 80added: v0.1.99 81changes: 82 - version: v8.0.0 83 pr-url: https://github.com/nodejs/node/pull/9618 84 description: Each invalid character is now replaced by a single replacement 85 character instead of one for each individual byte. 86--> 87 88* `buffer` {string|Buffer|TypedArray|DataView} The bytes to decode. 89* Returns: {string} 90 91Returns a decoded string, ensuring that any incomplete multibyte characters at 92the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the 93returned string and stored in an internal buffer for the next call to 94`stringDecoder.write()` or `stringDecoder.end()`. 95 96[encoding]: buffer.md#buffers-and-character-encodings 97