Node.js Reference · Buffers and Encoding
Node.js buf.toString() method
Reference for Node.js buf.toString(): decode a Buffer to a string with utf8, hex, base64 and other encodings, choose a byte range, and avoid split-character bugs.
buf.toString([encoding[, start[, end]]]) turns the bytes of a Buffer into a string. Without arguments it decodes the whole buffer as UTF-8. With an encoding name it can also produce hexadecimal, Base64, Latin-1 and other text forms, and with start and end it decodes only part of the buffer.
Decoding is the reverse of Buffer.from(string, encoding). Note that decoding is lenient: bytes that are not valid in the chosen encoding do not throw an error, they are replaced.
const buf = Buffer.from("héllo"); buf.toString(); // "héllo" buf.toString("hex"); // "68c3a96c6c6f" buf.toString("utf8", 0, 3); // "hé"
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
buf.toString(encoding = "utf8", start = 0, end = buf.length) // returns string
| Name | Description |
|---|---|
encoding |
Output encoding: "utf8" (default), "utf16le" (alias "ucs2"), "latin1" (alias "binary"), "ascii", "hex", "base64", "base64url". Case does not matter. |
start |
First byte offset to decode. Default 0. |
end |
Byte offset to stop at (not included). Default buf.length. |
Returns: a string.
Errors and edge cases:
- An unknown encoding name throws
TypeErrorwith codeERR_UNKNOWN_ENCODING. startbelow 0 is treated as 0, andendbeyond the length is clamped to the length. Ifendis not larger thanstart, the result is an empty string.- Invalid UTF-8 never throws. Each bad sequence becomes the replacement character U+FFFD.
- A string longer than the engine's maximum string length (about 512 MiB, see
buffer.constants.MAX_STRING_LENGTH) cannot be created and throwsERR_STRING_TOO_LONG.
Usage notes
- Offsets count bytes, not characters. In UTF-8, one character may take up to four bytes, so a byte range can land in the middle of a character and produce U+FFFD.
- Streaming text: never call
toString()on each chunk of a stream and join the results; a character split across two chunks is corrupted. Join the buffers first withBuffer.concat(), or useStringDecoderorsetEncoding(), which hold back incomplete characters. asciiis lossy: it clears the high bit of each byte, so it cannot show non-ASCII data.latin1maps each byte to the code point of the same value and is reversible.- Hex and Base64 are for binary data. Use
hexfor hashes and debugging, andbase64orbase64urlfor transport. See Buffer encodings. - Validate first with
buffer.isUtf8()if replacement characters would be a problem, or usenew TextDecoder("utf-8", { fatal: true })to get an error instead. - Also reachable through
String(buf)and template literals, which calltoString()with UTF-8.console.log(buf)does not: it prints the bytes in the form<Buffer 68 69>. - Copies data: the result is a new string; later changes to the buffer do not affect it.