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.
const buf = Buffer.from("key=value;key2=value2"); buf.indexOf("="); // 3 buf.indexOf(0x3b); // 9 (the ";" byte) buf.includes("key2"); // true
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.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
valuethat is not a string, number,BufferorUint8ArraythrowsERR_INVALID_ARG_TYPE. - An unknown encoding throws
ERR_UNKNOWN_ENCODING. - An empty string or buffer matches at the offset:
indexOf("")is0, and an offset past the end returnsbuf.length. - Fractions in
byteOffsetare 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
Bufferhas nofind(); useindexOf()for bytes orsubarray()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.