Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const buf = Buffer.from("héllo");
buf.toString();          // "héllo"
buf.toString("hex");     // "68c3a96c6c6f"
buf.toString("utf8", 0, 3); // "hé"

Try it

Node.js Encodings and ranges

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.

Node.js Invalid and split sequences

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

NODE
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 TypeError with code ERR_UNKNOWN_ENCODING.
  • start below 0 is treated as 0, and end beyond the length is clamped to the length. If end is not larger than start, 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 throws ERR_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 with Buffer.concat(), or use StringDecoder or setEncoding(), which hold back incomplete characters.
  • ascii is lossy: it clears the high bit of each byte, so it cannot show non-ASCII data. latin1 maps each byte to the code point of the same value and is reversible.
  • Hex and Base64 are for binary data. Use hex for hashes and debugging, and base64 or base64url for transport. See Buffer encodings.
  • Validate first with buffer.isUtf8() if replacement characters would be a problem, or use new TextDecoder("utf-8", { fatal: true }) to get an error instead.
  • Also reachable through String(buf) and template literals, which call toString() 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.