buffer: add end parameter

To limit how far into the buffer we search without allocating an
unnecessary subarray.

Author: ronag

doc/api/buffer.md

@@ -2069,11 +2069,14 @@ console.log(buf.fill('zz', 'hex'));
 // Throws an exception.
 ```
 
-### `buf.includes(value[, byteOffset][, encoding])`
+### `buf.includes(value[, byteOffset[, end]][, encoding])`
 
 <!-- YAML
 added: v5.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Added the `end` parameter.
   - version:
      - v25.5.0
      - v24.13.1
@@ -2084,6 +2087,8 @@ changes:
 * `value` {string|Buffer|Uint8Array|integer} What to search for.
 * `byteOffset` {integer} Where to begin searching in `buf`. If negative, then
   offset is calculated from the end of `buf`. **Default:** `0`.
+* `end` {integer} Where to stop searching in `buf` (exclusive). **Default:**
+  `buf.length`.
 * `encoding` {string} If `value` is a string, this is its encoding.
   **Default:** `'utf8'`.
 * Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise.
@@ -2132,11 +2137,14 @@ console.log(buf.includes('this', 4));
 // Prints: false
 ```
 
-### `buf.indexOf(value[, byteOffset][, encoding])`
+### `buf.indexOf(value[, start[, end]][, encoding])`
 
 <!-- YAML
 added: v1.5.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Added the `end` parameter.
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/10236
     description: The `value` can now be a `Uint8Array`.
@@ -2149,8 +2157,10 @@ changes:
 -->
 
 * `value` {string|Buffer|Uint8Array|integer} What to search for.
-* `byteOffset` {integer} Where to begin searching in `buf`. If negative, then
+* `start` {integer} Where to begin searching in `buf`. If negative, then
   offset is calculated from the end of `buf`. **Default:** `0`.
+* `end` {integer} Where to stop searching in `buf` (exclusive). **Default:**
+  `buf.length`.
 * `encoding` {string} If `value` is a string, this is the encoding used to
   determine the binary representation of the string that will be searched for in
   `buf`. **Default:** `'utf8'`.
@@ -2310,20 +2320,25 @@ for (const key of buf.keys()) {
 //   5
 ```
 
-### `buf.lastIndexOf(value[, byteOffset][, encoding])`
+### `buf.lastIndexOf(value[, start[, end]][, encoding])`
 
 <!-- YAML
 added: v6.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Added the `end` parameter.
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/10236
     description: The `value` can now be a `Uint8Array`.
 -->
 
 * `value` {string|Buffer|Uint8Array|integer} What to search for.
-* `byteOffset` {integer} Where to begin searching in `buf`. If negative, then
+* `start` {integer} Where to begin searching in `buf`. If negative, then
   offset is calculated from the end of `buf`. **Default:**
   `buf.length - 1`.
+* `end` {integer} Where to stop searching in `buf` (exclusive). **Default:**
+  `buf.length`.
 * `encoding` {string} If `value` is a string, this is the encoding used to
   determine the binary representation of the string that will be searched for in
   `buf`. **Default:** `'utf8'`.

lib/buffer.js

@@ -731,51 +731,55 @@ const encodingOps = {
     byteLength: (string) => string.length,
     write: asciiWrite,
     slice: asciiSlice,
-    indexOf: (buf, val, byteOffset, dir) =>
+    indexOf: (buf, val, byteOffset, dir, byteLength = buf.byteLength - byteOffset) =>
       indexOfBuffer(buf,
                     fromStringFast(val, encodingOps.ascii),
                     byteOffset,
                     encodingsMap.ascii,
-                    dir),
+                    dir,
+                    byteLength),
   },
   base64: {
     encoding: 'base64',
     encodingVal: encodingsMap.base64,
     byteLength: (string) => base64ByteLength(string, string.length),
     write: base64Write,
     slice: base64Slice,
-    indexOf: (buf, val, byteOffset, dir) =>
+    indexOf: (buf, val, byteOffset, dir, byteLength = buf.byteLength - byteOffset) =>
       indexOfBuffer(buf,
                     fromStringFast(val, encodingOps.base64),
                     byteOffset,
                     encodingsMap.base64,
-                    dir),
+                    dir,
+                    byteLength),
   },
   base64url: {
     encoding: 'base64url',
     encodingVal: encodingsMap.base64url,
     byteLength: (string) => base64ByteLength(string, string.length),
     write: base64urlWrite,
     slice: base64urlSlice,
-    indexOf: (buf, val, byteOffset, dir) =>
+    indexOf: (buf, val, byteOffset, dir, byteLength = buf.byteLength - byteOffset) =>
       indexOfBuffer(buf,
                     fromStringFast(val, encodingOps.base64url),
                     byteOffset,
                     encodingsMap.base64url,
-                    dir),
+                    dir,
+                    byteLength),
   },
   hex: {
     encoding: 'hex',
     encodingVal: encodingsMap.hex,
     byteLength: (string) => string.length >>> 1,
     write: hexWrite,
     slice: hexSlice,
-    indexOf: (buf, val, byteOffset, dir) =>
+    indexOf: (buf, val, byteOffset, dir, byteLength = buf.byteLength - byteOffset) =>
       indexOfBuffer(buf,
                     fromStringFast(val, encodingOps.hex),
                     byteOffset,
                     encodingsMap.hex,
-                    dir),
+                    dir,
+                    byteLength),
   },
 };
 function getEncodingOps(encoding) {
@@ -1031,7 +1035,7 @@ Buffer.prototype.compare = function compare(target,
 // - byteOffset - an index into `buffer`; will be clamped to an int32
 // - encoding - an optional encoding, relevant if val is a string
 // - dir - true for indexOf, false for lastIndexOf
-function bidirectionalIndexOf(buffer, val, byteOffset, encoding, dir) {
+function bidirectionalIndexOf(buffer, val, byteOffset, byteLength, encoding, dir) {
   validateBuffer(buffer);
 
   if (typeof byteOffset === 'string') {
@@ -1051,7 +1055,7 @@ function bidirectionalIndexOf(buffer, val, byteOffset, encoding, dir) {
   dir = !!dir;  // Cast to bool.
 
   if (typeof val === 'number')
-    return indexOfNumber(buffer, val >>> 0, byteOffset, dir);
+    return indexOfNumber(buffer, val >>> 0, byteOffset, dir, byteLength);
 
   let ops;
   if (encoding === undefined)
@@ -1062,30 +1066,42 @@ function bidirectionalIndexOf(buffer, val, byteOffset, encoding, dir) {
   if (typeof val === 'string') {
     if (ops === undefined)
       throw new ERR_UNKNOWN_ENCODING(encoding);
-    return ops.indexOf(buffer, val, byteOffset, dir);
+    return ops.indexOf(buffer, val, byteOffset, dir, byteLength);
   }
 
   if (isUint8Array(val)) {
     const encodingVal =
       (ops === undefined ? encodingsMap.utf8 : ops.encodingVal);
-    return indexOfBuffer(buffer, val, byteOffset, encodingVal, dir);
+    return indexOfBuffer(buffer, val, byteOffset, encodingVal, dir, byteLength);
   }
 
   throw new ERR_INVALID_ARG_TYPE(
     'value', ['number', 'string', 'Buffer', 'Uint8Array'], val,
   );
 }
 
-Buffer.prototype.indexOf = function indexOf(val, byteOffset, encoding) {
-  return bidirectionalIndexOf(this, val, byteOffset, encoding, true);
+Buffer.prototype.indexOf = function indexOf(val, offset, end, encoding) {
+  if (typeof end === 'string') {
+    encoding = end;
+    end = val.byteLength;
+  }
+  return bidirectionalIndexOf(this, val, offset, end - offset, encoding, true);
 };
 
-Buffer.prototype.lastIndexOf = function lastIndexOf(val, byteOffset, encoding) {
-  return bidirectionalIndexOf(this, val, byteOffset, encoding, false);
+Buffer.prototype.lastIndexOf = function lastIndexOf(val, offset, byteLength, encoding) {
+  if (typeof end === 'string') {
+    encoding = end;
+    end = val.byteLength;
+  }
+  return bidirectionalIndexOf(this, val, offset, end - offset, encoding, false);
 };
 
-Buffer.prototype.includes = function includes(val, byteOffset, encoding) {
-  return bidirectionalIndexOf(this, val, byteOffset, encoding, true) !== -1;
+Buffer.prototype.includes = function includes(val, offset, end, encoding) {
+  if (typeof end === 'string') {
+    encoding = end;
+    end = val.byteLength;
+  }
+  return bidirectionalIndexOf(this, val, offset, end - offset, encoding, true) !== -1;
 };
 
 // Usage:

src/node_buffer.cc

@@ -1079,6 +1079,7 @@ void IndexOfBuffer(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[2]->IsNumber());
   CHECK(args[3]->IsInt32());
   CHECK(args[4]->IsBoolean());
+  CHECK(args[5]->IsNumber());
 
   enum encoding enc = static_cast<enum encoding>(args[3].As<Int32>()->Value());
 
@@ -1089,13 +1090,14 @@ void IndexOfBuffer(const FunctionCallbackInfo<Value>& args) {
   ArrayBufferViewContents<char> needle_contents(args[1]);
   int64_t offset_i64 = args[2].As<Integer>()->Value();
   bool is_forward = args[4]->IsTrue();
+  int64_t end_i64 = args[5].As<Integer>()->Value();
 
   const char* haystack = haystack_contents.data();
   const size_t haystack_length = haystack_contents.length();
   const char* needle = needle_contents.data();
   const size_t needle_length = needle_contents.length();
 
-  int64_t opt_offset = IndexOfOffset(haystack_length,
+  int64_t opt_offset = IndexOfOffset(std::min(end_i64 - offset_i64, haystack_length),
                                      offset_i64,
                                      needle_length,
                                      is_forward);
@@ -1149,6 +1151,7 @@ void IndexOfBuffer(const FunctionCallbackInfo<Value>& args) {
 int32_t IndexOfNumberImpl(Local<Value> buffer_obj,
                           const uint32_t needle,
                           const int64_t offset_i64,
+                          const int64_t end_i64,
                           const bool is_forward) {
   ArrayBufferViewContents<uint8_t> buffer(buffer_obj);
   const uint8_t* buffer_data = buffer.data();
@@ -1158,13 +1161,14 @@ int32_t IndexOfNumberImpl(Local<Value> buffer_obj,
     return -1;
   }
   size_t offset = static_cast<size_t>(opt_offset);
-  CHECK_LT(offset, buffer_length);
+  size_t length = std::min(static_cast<size_t>(end_i64), offset + buffer_length);
+  CHECK_LT(offset, length);
 
   const void* ptr;
   if (is_forward) {
-    ptr = memchr(buffer_data + offset, needle, buffer_length - offset);
+    ptr = memchr(buffer_data + offset, needle, length - offset);
   } else {
-    ptr = nbytes::stringsearch::MemrchrFill(buffer_data, needle, offset + 1);
+    ptr = nbytes::stringsearch::MemrchrFill(buffer_data, needle, length);
   }
   const uint8_t* ptr_uint8 = static_cast<const uint8_t*>(ptr);
   return ptr != nullptr ? static_cast<int32_t>(ptr_uint8 - buffer_data) : -1;
@@ -1174,27 +1178,30 @@ void SlowIndexOfNumber(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[1]->IsUint32());
   CHECK(args[2]->IsNumber());
   CHECK(args[3]->IsBoolean());
+  CHECK(args[4]->IsUint32());
 
   THROW_AND_RETURN_UNLESS_BUFFER(Environment::GetCurrent(args), args[0]);
 
   Local<Value> buffer_obj = args[0];
   uint32_t needle = args[1].As<Uint32>()->Value();
   int64_t offset_i64 = args[2].As<Integer>()->Value();
   bool is_forward = args[3]->IsTrue();
+  int64_t end_int64 = args[4].As<Integer>()->Value();
 
   args.GetReturnValue().Set(
-      IndexOfNumberImpl(buffer_obj, needle, offset_i64, is_forward));
+      IndexOfNumberImpl(buffer_obj, needle, offset_i64, end_int64, is_forward));
 }
 
 int32_t FastIndexOfNumber(Local<Value>,
                           Local<Value> buffer_obj,
                           uint32_t needle,
                           int64_t offset_i64,
+                          int64_t end_i64,
                           bool is_forward,
                           // NOLINTNEXTLINE(runtime/references)
                           FastApiCallbackOptions& options) {
   HandleScope scope(options.isolate);
-  return IndexOfNumberImpl(buffer_obj, needle, offset_i64, is_forward);
+  return IndexOfNumberImpl(buffer_obj, needle, offset_i64, end_i64, is_forward);
 }
 
 static CFunction fast_index_of_number(CFunction::Make(FastIndexOfNumber));

test/parallel/test-buffer-indexof.js

@@ -633,3 +633,43 @@ assert.strictEqual(reallyLong.lastIndexOf(pattern), 0);
              'Received an instance of lastIndexOf'
   });
 }
+
+// Test the new end parameter for indexOf, lastIndexOf, and includes
+{
+  const buf = Buffer.from('abcabc');
+
+  // indexOf with end parameter limits the search range
+  assert.strictEqual(buf.indexOf('c', 0, 3), 2);
+  assert.strictEqual(buf.indexOf('c', 0, 2), -1);  // 'c' is at index 2, excluded when end=2
+  assert.strictEqual(buf.indexOf('a', 1, 4), 3);
+  assert.strictEqual(buf.indexOf('a', 0, 1), 0);
+  assert.strictEqual(buf.indexOf('a', 0, 0), -1);  // empty range
+  assert.strictEqual(buf.indexOf('abc', 0, 3), 0);
+  assert.strictEqual(buf.indexOf('abc', 0, 2), -1);  // not enough bytes in range
+
+  // indexOf with end parameter and Buffer value
+  assert.strictEqual(buf.indexOf(Buffer.from('bc'), 0, 3), 1);
+  assert.strictEqual(buf.indexOf(Buffer.from('bc'), 0, 2), -1);
+
+  // indexOf with end parameter and encoding (end is a string → encoding)
+  assert.strictEqual(buf.indexOf('a', 0, 'utf8'), 0);
+  assert.strictEqual(buf.indexOf('abc', 0, 'utf8'), 0);
+
+  // lastIndexOf with end parameter limits the search range
+  assert.strictEqual(buf.lastIndexOf('a', 5, 4), 3);
+  assert.strictEqual(buf.lastIndexOf('a', 5, 3), 0);  // 'a' at index 3 excluded, finds index 0
+  assert.strictEqual(buf.lastIndexOf('c', 5, 3), 2);
+  assert.strictEqual(buf.lastIndexOf('c', 5, buf.length), 5);
+
+  // lastIndexOf with end as encoding string
+  assert.strictEqual(buf.lastIndexOf('a', 5, 'utf8'), 3);
+
+  // includes with end parameter
+  assert.strictEqual(buf.includes('c', 0, 3), true);
+  assert.strictEqual(buf.includes('c', 0, 2), false);
+  assert.strictEqual(buf.includes('abc', 0, 3), true);
+  assert.strictEqual(buf.includes('abc', 0, 2), false);
+
+  // includes with end as encoding string
+  assert.strictEqual(buf.includes('a', 0, 'utf8'), true);
+}