1{ 2 "type": "module", 3 "source": "doc/api/string_decoder.md", 4 "modules": [ 5 { 6 "textRaw": "String decoder", 7 "name": "string_decoder", 8 "introduced_in": "v0.10.0", 9 "stability": 2, 10 "stabilityText": "Stable", 11 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v18.20.1/lib/string_decoder.js\">lib/string_decoder.js</a></p>\n<p>The <code>node:string_decoder</code> module provides an API for decoding <code>Buffer</code> objects\ninto strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16\ncharacters. It can be accessed using:</p>\n<pre><code class=\"language-js\">const { StringDecoder } = require('node:string_decoder');\n</code></pre>\n<p>The following example shows the basic use of the <code>StringDecoder</code> class.</p>\n<pre><code class=\"language-js\">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: €\n</code></pre>\n<p>When a <code>Buffer</code> instance is written to the <code>StringDecoder</code> 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 <code>stringDecoder.write()</code> or until <code>stringDecoder.end()</code> is called.</p>\n<p>In the following example, the three UTF-8 encoded bytes of the European Euro\nsymbol (<code>€</code>) are written over three separate operations:</p>\n<pre><code class=\"language-js\">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: €\n</code></pre>", 12 "classes": [ 13 { 14 "textRaw": "Class: `StringDecoder`", 15 "type": "class", 16 "name": "StringDecoder", 17 "methods": [ 18 { 19 "textRaw": "`stringDecoder.end([buffer])`", 20 "type": "method", 21 "name": "end", 22 "meta": { 23 "added": [ 24 "v0.9.3" 25 ], 26 "changes": [] 27 }, 28 "signatures": [ 29 { 30 "return": { 31 "textRaw": "Returns: {string}", 32 "name": "return", 33 "type": "string" 34 }, 35 "params": [ 36 { 37 "textRaw": "`buffer` {string|Buffer|TypedArray|DataView} The bytes to decode.", 38 "name": "buffer", 39 "type": "string|Buffer|TypedArray|DataView", 40 "desc": "The bytes to decode." 41 } 42 ] 43 } 44 ], 45 "desc": "<p>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.</p>\n<p>If the <code>buffer</code> argument is provided, one final call to <code>stringDecoder.write()</code>\nis performed before returning the remaining input.\nAfter <code>end()</code> is called, the <code>stringDecoder</code> object can be reused for new input.</p>" 46 }, 47 { 48 "textRaw": "`stringDecoder.write(buffer)`", 49 "type": "method", 50 "name": "write", 51 "meta": { 52 "added": [ 53 "v0.1.99" 54 ], 55 "changes": [ 56 { 57 "version": "v8.0.0", 58 "pr-url": "https://github.com/nodejs/node/pull/9618", 59 "description": "Each invalid character is now replaced by a single replacement character instead of one for each individual byte." 60 } 61 ] 62 }, 63 "signatures": [ 64 { 65 "return": { 66 "textRaw": "Returns: {string}", 67 "name": "return", 68 "type": "string" 69 }, 70 "params": [ 71 { 72 "textRaw": "`buffer` {string|Buffer|TypedArray|DataView} The bytes to decode.", 73 "name": "buffer", 74 "type": "string|Buffer|TypedArray|DataView", 75 "desc": "The bytes to decode." 76 } 77 ] 78 } 79 ], 80 "desc": "<p>Returns a decoded string, ensuring that any incomplete multibyte characters at\nthe end of the <code>Buffer</code>, or <code>TypedArray</code>, or <code>DataView</code> are omitted from the\nreturned string and stored in an internal buffer for the next call to\n<code>stringDecoder.write()</code> or <code>stringDecoder.end()</code>.</p>" 81 } 82 ], 83 "signatures": [ 84 { 85 "params": [ 86 { 87 "textRaw": "`encoding` {string} The character [encoding][] the `StringDecoder` will use. **Default:** `'utf8'`.", 88 "name": "encoding", 89 "type": "string", 90 "default": "`'utf8'`", 91 "desc": "The character [encoding][] the `StringDecoder` will use." 92 } 93 ], 94 "desc": "<p>Creates a new <code>StringDecoder</code> instance.</p>" 95 } 96 ] 97 } 98 ], 99 "type": "module", 100 "displayName": "String decoder" 101 } 102 ] 103}