{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.json","id":"string_decoder","path":"/string_decoder","type":"module","module":"string_decoder","title":"String decoder","introducedIn":"v0.10.0","sourceLink":{"path":"lib/string_decoder.js","url":"https://github.com/nodejs/node/blob/HEAD/lib/string_decoder.js"},"stability":{"index":"2","description":"Stable"},"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `node:string_decoder` module provides an API for decoding `Buffer` objects\ninto strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16\ncharacters. It can be accessed using:\n\n```mjs\nimport { StringDecoder } from 'node:string_decoder';\n```\n\n```cjs\nconst { StringDecoder } = require('node:string_decoder');\n```\n\nThe following example shows the basic use of the `StringDecoder` class.\n\n```mjs\nimport { StringDecoder } from 'node:string_decoder';\nimport { Buffer } from 'node:buffer';\nconst decoder = new StringDecoder('utf8');\n\nconst cent = Buffer.from([0xC2, 0xA2]);\nconsole.log(decoder.write(cent)); // Prints: ¢\n\nconst euro = Buffer.from([0xE2, 0x82, 0xAC]);\nconsole.log(decoder.write(euro)); // Prints: €\n```\n\n```cjs\nconst { StringDecoder } = require('node:string_decoder');\nconst decoder = new StringDecoder('utf8');\n\nconst cent = Buffer.from([0xC2, 0xA2]);\nconsole.log(decoder.write(cent)); // Prints: ¢\n\nconst euro = Buffer.from([0xE2, 0x82, 0xAC]);\nconsole.log(decoder.write(euro)); // Prints: €\n```\n\nWhen a `Buffer` instance is written to the `StringDecoder` instance, an\ninternal buffer is used to ensure that the decoded string does not contain\nany incomplete multibyte characters. These are held in the buffer until the\nnext call to `stringDecoder.write()` or until `stringDecoder.end()` is called.\n\nIn the following example, the three UTF-8 encoded bytes of the European Euro\nsymbol (`€`) are written over three separate operations:\n\n```mjs\nimport { StringDecoder } from 'node:string_decoder';\nimport { Buffer } from 'node:buffer';\nconst decoder = new StringDecoder('utf8');\n\ndecoder.write(Buffer.from([0xE2]));\ndecoder.write(Buffer.from([0x82]));\nconsole.log(decoder.end(Buffer.from([0xAC]))); // Prints: €\n```\n\n```cjs\nconst { StringDecoder } = require('node:string_decoder');\nconst decoder = new StringDecoder('utf8');\n\ndecoder.write(Buffer.from([0xE2]));\ndecoder.write(Buffer.from([0x82]));\nconsole.log(decoder.end(Buffer.from([0xAC]))); // Prints: €\n```","summary":"The `node:string_decoder` module provides an API for decoding `Buffer` objects into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 characters. It can be accessed using:","examples":[{"language":"mjs","displayName":null,"code":"import { StringDecoder } from 'node:string_decoder';"},{"language":"cjs","displayName":null,"code":"const { StringDecoder } = require('node:string_decoder');"},{"language":"mjs","displayName":null,"code":"import { StringDecoder } from 'node:string_decoder';\nimport { Buffer } from 'node:buffer';\nconst decoder = new StringDecoder('utf8');\n\nconst cent = Buffer.from([0xC2, 0xA2]);\nconsole.log(decoder.write(cent)); // Prints: ¢\n\nconst euro = Buffer.from([0xE2, 0x82, 0xAC]);\nconsole.log(decoder.write(euro)); // Prints: €"},{"language":"cjs","displayName":null,"code":"const { StringDecoder } = require('node:string_decoder');\nconst decoder = new StringDecoder('utf8');\n\nconst cent = Buffer.from([0xC2, 0xA2]);\nconsole.log(decoder.write(cent)); // Prints: ¢\n\nconst euro = Buffer.from([0xE2, 0x82, 0xAC]);\nconsole.log(decoder.write(euro)); // Prints: €"},{"language":"mjs","displayName":null,"code":"import { StringDecoder } from 'node:string_decoder';\nimport { Buffer } from 'node:buffer';\nconst decoder = new StringDecoder('utf8');\n\ndecoder.write(Buffer.from([0xE2]));\ndecoder.write(Buffer.from([0x82]));\nconsole.log(decoder.end(Buffer.from([0xAC]))); // Prints: €"},{"language":"cjs","displayName":null,"code":"const { StringDecoder } = require('node:string_decoder');\nconst decoder = new StringDecoder('utf8');\n\ndecoder.write(Buffer.from([0xE2]));\ndecoder.write(Buffer.from([0x82]));\nconsole.log(decoder.end(Buffer.from([0xAC]))); // Prints: €"}],"children":[{"kind":"class","id":"class-stringdecoder","name":"StringDecoder","title":"Class: `StringDecoder`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"","summary":"","examples":[],"children":[{"kind":"constructor","id":"new-stringdecoderencoding","name":"StringDecoder","title":"`new StringDecoder([encoding])`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.99"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"encoding","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The character [encoding](buffer.html#buffers-and-character-encodings) the `StringDecoder` will use.","default":"'utf8'","optional":true,"rest":false,"properties":[]}],"returns":null},"description":"Creates a new `StringDecoder` instance.","summary":"Creates a new `StringDecoder` instance.","examples":[],"children":[]},{"kind":"method","id":"stringdecoderendbuffer","name":"end","title":"`stringDecoder.end([buffer])`","scope":"module","overloadOf":null,"stability":null,"added":["v0.9.3"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"buffer","type":{"text":"string | Buffer | TypedArray | DataView","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"TypedArray","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypedArray","start":18,"end":28},{"name":"DataView","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView","start":31,"end":39}]},"description":"The bytes to decode.","default":null,"optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":""}},"description":"Returns any remaining input stored in the internal buffer as a string. Bytes\nrepresenting incomplete UTF-8 and UTF-16 characters will be replaced with\nsubstitution characters appropriate for the character encoding.\n\nIf the `buffer` argument is provided, one final call to `stringDecoder.write()`\nis performed before returning the remaining input.\nAfter `end()` is called, the `stringDecoder` object can be reused for new input.","summary":"Returns any remaining input stored in the internal buffer as a string. Bytes representing incomplete UTF-8 and UTF-16 characters will be replaced with substitution characters appropriate for the character encoding.","examples":[],"children":[]},{"kind":"method","id":"stringdecoderwritebuffer","name":"write","title":"`stringDecoder.write(buffer)`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.99"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[{"versions":["v8.0.0"],"prUrl":"https://github.com/nodejs/node/pull/9618","commit":null,"description":"Each invalid character is now replaced by a single replacement character instead of one for each individual byte."}],"signature":{"parameters":[{"name":"buffer","type":{"text":"string | Buffer | TypedArray | DataView","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"TypedArray","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypedArray","start":18,"end":28},{"name":"DataView","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView","start":31,"end":39}]},"description":"The bytes to decode.","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":""}},"description":"Returns a decoded string, ensuring that any incomplete multibyte characters at\nthe end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the\nreturned string and stored in an internal buffer for the next call to\n`stringDecoder.write()` or `stringDecoder.end()`.","summary":"Returns a decoded string, ensuring that any incomplete multibyte characters at the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the returned string and stored in an internal buffer for the next call to `stringDecoder.write()` or `stringDecoder.end()`.","examples":[],"children":[]}]}]}