From 1576730ef38fba5ffa91b412c6c6da52bbeac1a4 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Fri, 8 Jul 2016 12:59:26 +0200
Subject: [PATCH] test,doc: clarify `buf.indexOf(num)` input range

Hopefully clarify the behaviour of `buffer.indexOf()` and
`buffer.includes()` for numbers in that they will be
truncated to uint8s.

Add tests for that behaviour.

Fixes: https://github.com/nodejs/node/issues/7591
PR-URL: https://github.com/nodejs/node/pull/7611
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/buffer.md                     |  6 ++++--
 test/parallel/test-buffer-includes.js | 16 ++++++++++++++++
 test/parallel/test-buffer-indexof.js  | 16 ++++++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index fd527a02d1..fb8065a645 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -973,7 +973,8 @@ Operates similar to [`Array#indexOf()`][] in that it returns either the
 starting index position of `value` in Buffer or `-1` if the Buffer does not
 contain `value`. The `value` can be a String, Buffer or Number. Strings are by
 default interpreted as UTF8. Buffers will use the entire Buffer (to compare a
-partial Buffer use [`buf.slice()`][]).  Numbers can range from 0 to 255.
+partial Buffer use [`buf.slice()`][]). Numbers will be interpreted as unsigned 8-bit
+integer values between `0` and `255`.
 
 ```js
 const buf = Buffer.from('this is a buffer');
@@ -1012,7 +1013,8 @@ added: v5.3.0
 Operates similar to [`Array#includes()`][]. The `value` can be a String, Buffer
 or Number. Strings are interpreted as UTF8 unless overridden with the
 `encoding` argument. Buffers will use the entire Buffer (to compare a partial
-Buffer use [`buf.slice()`][]). Numbers can range from 0 to 255.
+Buffer use [`buf.slice()`][]). Numbers will be interpreted as unsigned 8-bit
+integer values between `0` and `255`.
 
 The `byteOffset` indicates the index in `buf` where searching begins.
 
diff --git a/test/parallel/test-buffer-includes.js b/test/parallel/test-buffer-includes.js
index 7962d1cef8..5859399b50 100644
--- a/test/parallel/test-buffer-includes.js
+++ b/test/parallel/test-buffer-includes.js
@@ -256,3 +256,19 @@ assert.throws(function() {
 assert.throws(function() {
   b.includes([]);
 });
+
+// test truncation of Number arguments to uint8
+{
+  const buf = Buffer.from('this is a test');
+  assert.ok(buf.includes(0x6973));
+  assert.ok(buf.includes(0x697320));
+  assert.ok(buf.includes(0x69732069));
+  assert.ok(buf.includes(0x697374657374));
+  assert.ok(buf.includes(0x69737374));
+  assert.ok(buf.includes(0x69737465));
+  assert.ok(buf.includes(0x69737465));
+  assert.ok(buf.includes(-140));
+  assert.ok(buf.includes(-152));
+  assert.ok(!buf.includes(0xff));
+  assert.ok(!buf.includes(0xffff));
+}
diff --git a/test/parallel/test-buffer-indexof.js b/test/parallel/test-buffer-indexof.js
index 647f1e9a62..d699e1cd59 100644
--- a/test/parallel/test-buffer-indexof.js
+++ b/test/parallel/test-buffer-indexof.js
@@ -448,3 +448,19 @@ pattern = reallyLong.slice(0, 1000000);  // First 1/5th.
 assert.equal(3932160, reallyLong.lastIndexOf(pattern));
 pattern = reallyLong.slice(0, 2000000);  // first 2/5ths.
 assert.equal(0, reallyLong.lastIndexOf(pattern));
+
+// test truncation of Number arguments to uint8
+{
+  const buf = Buffer.from('this is a test');
+  assert.strictEqual(buf.indexOf(0x6973), 3);
+  assert.strictEqual(buf.indexOf(0x697320), 4);
+  assert.strictEqual(buf.indexOf(0x69732069), 2);
+  assert.strictEqual(buf.indexOf(0x697374657374), 0);
+  assert.strictEqual(buf.indexOf(0x69737374), 0);
+  assert.strictEqual(buf.indexOf(0x69737465), 11);
+  assert.strictEqual(buf.indexOf(0x69737465), 11);
+  assert.strictEqual(buf.indexOf(-140), 0);
+  assert.strictEqual(buf.indexOf(-152), 1);
+  assert.strictEqual(buf.indexOf(0xff), -1);
+  assert.strictEqual(buf.indexOf(0xffff), -1);
+}