{
  "$schema": "https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.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": []
        }
      ]
    }
  ]
}