Skip to content
Tutorials Center
My learning

Topics

Node.js Reference · Buffers and Encoding

Node.js buf.indexOf() and buf.includes() methods

Reference for Node.js buf.indexOf(), lastIndexOf() and includes(): search a Buffer for a byte, string or buffer, with byte offsets, encodings and edge cases.

buf.indexOf(value[, byteOffset][, encoding]) returns the byte position of the first match of value in the buffer, or -1 when there is none. buf.lastIndexOf() searches from the end, and buf.includes() returns a boolean. The value can be a string, a number (one byte) or a Buffer or Uint8Array (a byte sequence).

All positions are byte offsets, not character counts. That matters as soon as the data contains characters that take more than one byte in UTF-8. Searching is the core of splitting framed data such as lines separated by \n or HTTP headers ended by a blank line.

NODE
const buf = Buffer.from("key=value;key2=value2");
buf.indexOf("=");      // 3
buf.indexOf(0x3b);     // 9 (the ";" byte)
buf.includes("key2");  // true

Try it

Node.js Finding bytes and strings

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 Byte offsets and encodings

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.indexOf(value, byteOffset = 0, encoding = "utf8")      // number
buf.lastIndexOf(value, byteOffset = buf.length - 1, encoding = "utf8") // number
buf.includes(value, byteOffset = 0, encoding = "utf8")     // boolean
Name Description
value A string, a number from 0 to 255 (other numbers are reduced with & 255), or a Buffer / Uint8Array.
byteOffset Where to start (for lastIndexOf(): where to start searching backwards). A negative value counts from the end. A value that is NaN or undefined means the default.
encoding Encoding of value when it is a string. The second argument may also be the encoding: buf.indexOf("6c", "hex").

Returns: the index of the match, or -1; includes() returns true or false.

Errors and edge cases:

  • A value that is not a string, number, Buffer or Uint8Array throws ERR_INVALID_ARG_TYPE.
  • An unknown encoding throws ERR_UNKNOWN_ENCODING.
  • An empty string or buffer matches at the offset: indexOf("") is 0, and an offset past the end returns buf.length.
  • Fractions in byteOffset are truncated.

Usage notes

  • UTF-8 caveat: the search is bytewise, so a match is found wherever the bytes agree. This is safe in UTF-8 because a valid character's bytes never appear inside another character, but be careful with other encodings.
  • Matching characters in text: convert a search character with Buffer.from() and the right encoding, or pass the string with the same encoding the buffer uses.
  • Cost: the search is native and fast, but each call scans from the offset, so in a loop always pass the next start offset rather than slicing.
  • Same method names as arrays and strings, but Buffer has no find(); use indexOf() for bytes or subarray() with a loop for predicates.
  • Delimiters across chunks: a delimiter may be split between two chunks of a stream. Keep the tail of the previous chunk and search the concatenation.
  • Sequences you search often can be created once as a buffer constant, saving an encoding step per call.