@@ -51,6 +51,14 @@ const kNativeDecoder = Symbol('kNativeDecoder'); |
51 | 51 |
|
52 | 52 | // Do not cache `Buffer.isEncoding` when checking encoding names as some |
53 | 53 | // modules monkey-patch it to support additional encodings |
| 54 | +/** |
| 55 | + * Normalize encoding notation |
| 56 | + * |
| 57 | + * @param {string} enc |
| 58 | + * @returns {"utf8" | "utf16le" | "hex" | "ascii" |
| 59 | + * | "base64" | "latin1" | "base64url"} |
| 60 | + * @throws {TypeError} Throws an error when encoding is invalid |
| 61 | + */ |
54 | 62 | function normalizeEncoding(enc) { |
55 | 63 | const nenc = internalUtil.normalizeEncoding(enc); |
56 | 64 | if (nenc === undefined) { |
@@ -65,15 +73,27 @@ const encodingsMap = {}; |
65 | 73 | for (let i = 0; i < encodings.length; ++i) |
66 | 74 | encodingsMap[encodings[i]] = i; |
67 | 75 |
|
68 | | -// StringDecoder provides an interface for efficiently splitting a series of |
69 | | -// buffers into a series of JS strings without breaking apart multi-byte |
70 | | -// characters. |
| 76 | +/** |
| 77 | + * StringDecoder provides an interface for efficiently splitting a series of |
| 78 | + * buffers into a series of JS strings without breaking apart multi-byte |
| 79 | + * characters. |
| 80 | + * |
| 81 | + * @param {string} [encoding=utf-8] |
| 82 | + */ |
71 | 83 | function StringDecoder(encoding) { |
72 | 84 | this.encoding = normalizeEncoding(encoding); |
73 | 85 | this[kNativeDecoder] = Buffer.alloc(kSize); |
74 | 86 | this[kNativeDecoder][kEncodingField] = encodingsMap[this.encoding]; |
75 | 87 | } |
76 | 88 |
|
| 89 | +/** |
| 90 | + * Returns a decoded string, omitting any incomplete multi-bytes |
| 91 | + * characters at the end of the Buffer, or TypedArray, or DataView |
| 92 | + * |
| 93 | + * @param {string | Buffer | TypedArray | DataView} buf |
| 94 | + * @returns {string} |
| 95 | + * @throws {TypeError} Throws when buf is not in one of supported types |
| 96 | + */ |
77 | 97 | StringDecoder.prototype.write = function write(buf) { |
78 | 98 | if (typeof buf === 'string') |
79 | 99 | return buf; |
@@ -84,6 +104,14 @@ StringDecoder.prototype.write = function write(buf) { |
84 | 104 | return decode(this[kNativeDecoder], buf); |
85 | 105 | }; |
86 | 106 |
|
| 107 | +/** |
| 108 | + * Returns any remaining input stored in the internal buffer as a string. |
| 109 | + * After end() is called, the stringDecoder object can be reused for new |
| 110 | + * input. |
| 111 | + * |
| 112 | + * @param {string | Buffer | TypedArray | DataView} [buf] |
| 113 | + * @returns {string} |
| 114 | + */ |
87 | 115 | StringDecoder.prototype.end = function end(buf) { |
88 | 116 | let ret = ''; |
89 | 117 | if (buf !== undefined) |
@@ -94,6 +122,12 @@ StringDecoder.prototype.end = function end(buf) { |
94 | 122 | }; |
95 | 123 |
|
96 | 124 | /* Everything below this line is undocumented legacy stuff. */ |
| 125 | +/** |
| 126 | + * |
| 127 | + * @param {string | Buffer | TypedArray | DataView} buf |
| 128 | + * @param {number} offset |
| 129 | + * @returns {string} |
| 130 | + */ |
97 | 131 | StringDecoder.prototype.text = function text(buf, offset) { |
98 | 132 | this[kNativeDecoder][kMissingBytes] = 0; |
99 | 133 | this[kNativeDecoder][kBufferedBytes] = 0; |
|