Skip to content
This repository was archived by the owner on Apr 18, 2020. It is now read-only.

Make README more verbose #18

Open
RichardBarrell wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Make README more verbose #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 38 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,53 @@ Example
```js
var bs = require("binary-search");

bs([1, 2, 3, 4], 3, function(element, needle) { return element - needle; });
bs([1, 2, 4, 5], 4, function(element, needle) { return element - needle; });
// => 2

bs([1, 2, 4, 5], 3, function(element, needle) { return element - needle; });
// => -3

bs([1, 2, 4, 5], 8, function(element, needle) { return element - needle; });
// => -5

bs([1, 2, 4, 5], 0, function(element, needle) { return element - needle; });
// => -1
```

Be advised that passing in a comparator function is *required*. Since you're
probably using one for your sort function anyway, this isn't a big deal.
Parameters
----------

The comparator takes a 1st and 2nd argument of element and needle, respectively.
- `haystack` - an array. `haystack` must already be sorted.
- `needle` - the value you want to search for.
- `comparator(element, needle, [index, array])` - compare an element from
`haystack` with the `needle`.
- Must return a positive number if the `element` is larger than `needle`,
- Must return `0` if they are equal, and
- Must return a negative number if `element` is smaller than `needle`.
- The comparator function will often be the same function that was used to
sort `haystack`. If not, it must rank elements in the same order as the
comparator that was used to sort `haystack`.
- You shouldn't normally need the index or array to compare values, but they
are there if you do.
- `minimumIndex` - (optional) - the index of the smallest element in `haystack`
which should be included in the search. By default this is 0.
- `maximumIndex` - (optional) - the index of the largest element in `haystack`
which should be included in the search. By default this is `haystack.length - 1`
- `minimumIndex` and `maximumIndex` let you specify an input range, in case
you want to limit the search to a particular range of inputs.
- Be advised that this is generally a bad idea.
- (But sometimes bad ideas are necessary.)
- By default `bs()` will search the entire `haystack`.

The comparator also takes a 3rd and 4th argument, the current index and array,
respectively. You shouldn't normally need the index or array to compare values,
but it's there if you do.
Return values
-------------

You may also, optionally, specify an input range as the final two parameters,
in case you want to limit the search to a particular range of inputs. However,
be advised that this is generally a bad idea (but sometimes bad ideas are
necessary).
- If the needle is equal to an element in the haystack, `bs()` will return that element's index.
- If the needle is smaller than any element of the haystack, `bs()` returns `minimumIndex - 1`.
- If you didn't specify `minimumIndex` and `maximumIndex`, the return value will be `-1` in this case.
- If the needle is larger than any element of the haystack, `bs()` returns `-1 * (largestIndex + 2)`, where `largestIndex` is the index of the last element in the haystack.
- If you didn't specify `minimumIndex` and `maximumIndex`, the return value will be `-1 * (haystack.length + 1)`.
- If the needle is in between two elements of the haystack, `bs()` returns `-1 * (largerIndex + 1)`, where `largerIndex` is the index of the larger or the two elements which the `needle` sits between.
Copy link

@ghost ghost Aug 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an easier way to state the return values:

  • If the needle is equal to an element in the haystack, bs() will return that element's index.
  • If the needle is not equal to an element in the haystack, bs() will return -(x+1), where x is where the element would have been if it was in the haystack. (Therefore if the element is less than all elements in the array, this would be -1; if the element is greater than all elements in the array, this would be -(haystack.length+1).)
    • Note that this means a negative return value indicates that the needle was not in the haystack, while a zero or positive return value indicates that the needle was in the haystack.

Copy link
Author

@RichardBarrell RichardBarrell Aug 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, that's terser. I think I want to break the latter half of that paragraph into bullet points.

This terser explanation omits explaining what happens if minimumIndex and maximumIndex are supplied… which makes it clearer.

I think this would be better if I changed it so that the return value explains everything in the following order:

  • first the easy case (needle found in haystack)
  • second, stating the general rule for when needle isn't in haystack, as you have here
  • then a bullet point for each case (needle before, needle between, needle after)
  • lastly, a completely separate paragraph (maybe even a completely separate section) explaining what happens if one specifies non-default values of minimumIndex and maximumIndex.

I'll come back and have another go at writing later. Thank you for the feedback! :)

Copy link

@paulmelnikow paulmelnikow Nov 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the needle is not equal to an element in the haystack, bs() will return -(x+1) where x is where the element would have been if it was in the haystack

This is correct, though I found it a bit confusing. Since x is negative, it's easier for me to understand it this way:

If the needle is not equal to an element in the haystack, bs() will return -x, where x-1 is the position where the element would have been if it were in the haystack.


License
-------
Expand Down