doc: clarify Buffer.indexOf() and lastIndexOf() #10162

dcposch · 2016-12-07T09:20:50Z

Checklist

make -j8 test (UNIX), or vcbuild test nosign (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Clarifies the buffer documentation to explain how type coercion works for indexOf() and lastIndexOf().

Fixes #9801

@vsemozhetbyt @silverwind

jasnell

Almost there!

jasnell · 2016-12-07T15:37:35Z

doc/api/buffer.md

@@ -1150,6 +1150,33 @@ console.log(utf16Buffer.indexOf('\u03a3', 0, 'ucs2'));
 console.log(utf16Buffer.indexOf('\u03a3', -4, 'ucs2'));
 ```

+Edge cases:
+
+If `value` is not a string, number, or Buffer, this method will throw a `TypeError`.


Long lines. Please wrap at <= 80 chars :-)

Sounds good, done. FYI though, that file has lots of lines over 80 chars

jasnell · 2016-12-07T15:38:06Z

doc/api/buffer.md

+
+Edge case examples:
+
+```


jasnell · 2016-12-07T15:38:28Z

doc/api/buffer.md

+Edge case examples:
+
+```
+var b = new Buffer('abcdef')


const b = Buffer.from('abcdef');

Fixed, my b.

jasnell · 2016-12-07T15:39:00Z

doc/api/buffer.md

+Edge case examples:
+
+```
+var b = new Buffer('abcdef')


```js const b = Buffer.from('abcdef');

mscdex · 2016-12-07T15:58:42Z

I don't think we need to explicitly be testing string.indexOf()/string.lastIndexOf(), V8 has such tests already. Having just the Buffer tests is enough IMHO.

silverwind · 2016-12-07T17:47:18Z

Why not make the tests in this style so we test equal behaviour with string functions?

 assert.equal(b.lastIndexOf('b', 0), s.lastIndexOf('b', 0)) // -1

Trott

General direction is great 💯 Thanks! 🎆 I have several nits for the documentation changes and a suggestion for the tests.

Trott · 2016-12-07T21:21:29Z

doc/api/buffer.md

@@ -1150,6 +1150,34 @@ console.log(utf16Buffer.indexOf('\u03a3', 0, 'ucs2'));
 console.log(utf16Buffer.indexOf('\u03a3', -4, 'ucs2'));
 ```

+Edge cases:


No reason to say "Edge cases." Just start right in with "If `value is not a string..."

Yeah, "edge case" terminology often has somewhat negative interpretations.

Good call, fixed

Trott · 2016-12-07T21:21:42Z

doc/api/buffer.md

+that coerce to `NaN` or 0, like `{}`, `[]`, `null` or `undefined`, will search
+the whole buffer. This behavior matches [`String.indexOf()`].
+
+Edge case examples:


Similarly, remove "Edge case examples:".

Trott · 2016-12-07T21:23:33Z

doc/api/buffer.md

+const b = Buffer.from('abcdef')
+
+// Passing a value that's a number, but not a valid byte
+// Prints: 2, equivalent to searching for 99 or 'c'


"Prints" is not accurate. These don't print anything except in the REPL. I believe the way we handle this in other contexts is like this:

b.indexOf(99.9); // 2

Also, note that we use semi-colons in the example code throughout the docs. Please do the same here. Thanks!

Sounds good. I've added semicolons and console.log to be consistent with the other Buffer examples

Trott · 2016-12-07T21:23:55Z

doc/api/buffer.md

@@ -1270,6 +1298,37 @@ console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'ucs2'));
 console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'ucs2'));
 ```

+Edge cases:


Same: Don't specify "Edge cases".

Trott · 2016-12-07T21:24:03Z

doc/api/buffer.md

+that coerce to `NaN`, like `{}` or `undefined`, will search the whole buffer.
+This behavior matches [`String.lastIndexOf()`].
+
+Edge case examples:


And remove this too, please. Thanks.

Trott · 2016-12-07T21:24:27Z

doc/api/buffer.md

+const b = Buffer.from('abcdef')
+
+// Passing a value that's a number, but not a valid byte
+// Prints: 2, equivalent to searching for 99 or 'c'


Same comment as above regarding "Prints" etc. and semi-colons too.

Trott · 2016-12-07T21:26:29Z

test/parallel/test-buffer-indexof.js

 assert.equal(b.lastIndexOf('b', undefined), 1);
-assert.equal(b.lastIndexOf('b', null), -1);
+assert.equal(s.lastIndexOf('b', undefined), 1);


I realize there's a lot of assert.equal() in this test file, but if you could at least use assert.strictEqual() for the stuff you're adding, that would probably be better. If you want to change surrounding instances in the file too, awesome.

Trott · 2016-12-07T21:28:08Z

/cc @nodejs/documentation

Qard · 2016-12-07T21:39:53Z

Agreed on all the suggestions from @Trott and the direct buffer to string test suggestion by @silverwind. Once those changes are in, it should be good to me.

dcposch · 2016-12-08T02:43:08Z

@Qard @silverwind done

Trott · 2016-12-08T05:11:38Z

doc/api/buffer.md

@@ -1150,6 +1150,30 @@ console.log(utf16Buffer.indexOf('\u03a3', 0, 'ucs2'));
 console.log(utf16Buffer.indexOf('\u03a3', -4, 'ucs2'));
 ```

+If `value` is not a string, number, or Buffer, this method will throw a


@nodejs/documentation: Should "Buffer" be surrounded in back-ticks in this line?

Based on how it's used in other parts of this file, yes. Fixed

Trott

LGTM if CI is ✅ and other revewer's nits are addressed. Thanks for doing this!

thefourtheye · 2016-12-08T06:29:10Z

doc/api/buffer.md

+
+If `byteOffset` is not a number, it will be coerced to a number. Any arguments
+that coerce to `NaN` or 0, like `{}`, `[]`, `null` or `undefined`, will search
+the whole buffer. This behavior matches [`String.indexOf()`].


String.indexOf() should have corresponding link.

Good call. I figured out how to build the docs and verified that the link works now.

I also changed it to String#indexOf() for consistency.

thefourtheye · 2016-12-08T06:29:21Z

doc/api/buffer.md

+
+If `byteOffset` is not a number, it will be coerced to a number. Any arguments
+that coerce to `NaN`, like `{}` or `undefined`, will search the whole buffer.
+This behavior matches [`String.lastIndexOf()`].


String.lastIndexOf() should have corresponding link.

trevnorris

Excellent stuff. Just one change suggestion, but not critical.

trevnorris · 2016-12-09T22:29:07Z

lib/buffer.js

-  byteOffset = +byteOffset;  // Coerce to Number.
+  // Coerce to Number. Values like null and [] become 0.
+  byteOffset = +byteOffset;
+  // If the offset is undefined, "foo", {}, coerces to NaN, search whole buffer.
  if (isNaN(byteOffset)) {


If we're going to explicitly coerce the value first, then let's go ahead and use Number.isNaN() instead. Which explicitly checks for NaN, w/o first coercing the argument.

good call, fixed

thefourtheye · 2016-12-10T00:58:03Z

test/parallel/test-buffer-indexof.js

+assert.strictEqual(b.lastIndexOf('b', [2]), 1);
+
+// Behavior should match String.lastIndexOf()
+var s = 'abcdef';


Nit: This could be a const

Lots of var in this file (mixed with some let and const). Might be cool to ban var in the future and convert all of our variables to let or const.

Changed s to be const in any case

thefourtheye · 2016-12-10T00:59:25Z

test/parallel/test-buffer-indexof.js

+assert.strictEqual(b.lastIndexOf('b', undefined), 1);
+assert.strictEqual(b.lastIndexOf('b', {}), 1);
+
+// The following offsets coerce to 0


Nit: Strictly speaking, zero is not being coerced to zero :D

thefourtheye · 2016-12-10T01:02:36Z

test/parallel/test-buffer-indexof.js

+// The following offset coerces to 2, in other words +[2] === 2
+assert.strictEqual(b.lastIndexOf('b', [2]), 1);
+
+// Behavior should match String.lastIndexOf()


Can we have similar tests, like the following, for indexOf as well?

Sure, but indexOf is less interesting. Args coercing to 0 and NaN both have the same behavior, searching the whole buffer. Only lastIndexOf has this weirdness where, for example, passing an offset of null vs undefined does different things.

Fixed. Added tests for indexOf

silverwind · 2016-12-16T21:13:58Z

ping @dcposch

dcposch · 2017-01-23T03:33:10Z

@silverwind @italoacasas @jasnell done

silverwind · 2017-01-24T18:37:46Z

One more CI: https://ci.nodejs.org/job/node-test-pull-request/6030/

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

silverwind · 2017-01-24T23:39:26Z

Thanks! Landed in dd50cd9 .. 39f65e6.

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: nodejs#10162 Fixes: nodejs#9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: nodejs#10162 Fixes: nodejs#9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: nodejs#10162 Fixes: nodejs#9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: nodejs#10162 Fixes: nodejs#9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

jasnell · 2017-03-08T22:30:18Z

This would need a backport PR if it should land on v4

dcposch · 2017-03-08T23:01:24Z

Do you want me to make one?

Test type coercion for non-number offset arguments. Verify that Buffer and String behave the same way. PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

PR-URL: #10162 Fixes: #9801 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

nodejs-github-bot added the buffer Issues and PRs related to the buffer subsystem. label Dec 7, 2016

dcposch force-pushed the master branch from d868e56 to 37deda3 Compare December 7, 2016 09:26

italoacasas added doc Issues and PRs related to the documentations. test Issues and PRs related to the tests. labels Dec 7, 2016

jasnell requested changes Dec 7, 2016

View reviewed changes

dcposch force-pushed the master branch 2 times, most recently from 62882e1 to b7e3c3f Compare December 7, 2016 17:34

Trott requested changes Dec 7, 2016

View reviewed changes

dcposch force-pushed the master branch from b7e3c3f to a3da2bc Compare December 8, 2016 02:42

Trott reviewed Dec 8, 2016

View reviewed changes

Trott approved these changes Dec 8, 2016

View reviewed changes

Qard approved these changes Dec 8, 2016

View reviewed changes

thefourtheye reviewed Dec 8, 2016

View reviewed changes

dcposch force-pushed the master branch 2 times, most recently from 8836e63 to 409b4b6 Compare December 8, 2016 09:57

silverwind approved these changes Dec 8, 2016

View reviewed changes

trevnorris previously requested changes Dec 9, 2016

View reviewed changes

thefourtheye reviewed Dec 10, 2016

View reviewed changes

dcposch force-pushed the master branch from 409b4b6 to ac29ecb Compare December 18, 2016 19:18

nodejs-github-bot added the lts-watch-v6.x label Dec 18, 2016

nodejs-github-bot added dont-land-on-v7.x and removed lts-watch-v6.x labels Jan 21, 2017

silverwind closed this Jan 24, 2017

targos removed the dont-land-on-v7.x label Jan 28, 2017

italoacasas mentioned this pull request Jan 29, 2017

v7.5.0 proposal #11062

Merged

jasnell added the dont-land-on-v4.x label Mar 8, 2017

MylesBorins mentioned this pull request Mar 9, 2017

v6.10.1 proposal #11759

Merged

doc: clarify Buffer.indexOf() and lastIndexOf() #10162

doc: clarify Buffer.indexOf() and lastIndexOf() #10162

Conversation

dcposch commented Dec 7, 2016

Checklist

Affected core subsystem(s)

Description of change

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch Dec 7, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mscdex commented Dec 7, 2016

silverwind commented Dec 7, 2016

Trott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott commented Dec 7, 2016

Qard commented Dec 7, 2016

dcposch commented Dec 8, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevnorris left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch Dec 18, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch Dec 18, 2016 • edited Loading

Choose a reason for hiding this comment

silverwind commented Dec 16, 2016

dcposch commented Jan 23, 2017 • edited Loading

silverwind commented Jan 24, 2017

silverwind commented Jan 24, 2017

jasnell commented Mar 8, 2017

dcposch commented Mar 8, 2017 via email

dcposch Dec 7, 2016 •

edited

Loading

dcposch Dec 18, 2016 •

edited

Loading

dcposch Dec 18, 2016 •

edited

Loading

dcposch commented Jan 23, 2017 •

edited

Loading