bfind
Runs a binary search on any sorted collection.
Installation
Requires Node.js 8.3.0 or above.
npm i bfind
API
The module exports a single function.
Parameters
- Object argument:
- Optional:
compare
(function, array, or any):
- If a function: When passed two arguments
a
and b
, expected to return -1
if a
is less than b
, 1
if a
is greater than b
, and 0
if they are equal. - If an array: An array of Map/object keys, the values of which can be used to compare two Maps/objects. The first key is checked first, and if the two values for that key are equal, the next key in the array is checked, and so on. If any given element is itself an array, it is interpreted as a nested keychain.
- Otherwise: A single Map/object key.
- If omitted: Only numbers and strings will be compared as-is. All others values will be coerced into strings before being compared.
get
(function): A callback that should return a value from the collection for a given index from 0
to length - 1
.length
(positive integer): The length of the collection.- Optional:
multiple
(string): Specifies behavior in the event that more than one existing collection item is sort-equivalent with value
. If set to first
or last
, the index of the first or last sort-equivalent item (respectively) will be returned. Otherwise, the index of whatever sort-equivalent item the algorithm comes across first will be returned. value
(any): The value to search for.
Return Value
Returns an object:
found
(boolean): true
if compare
reported that the collection contains another value with the same sort value as value
; false
otherwise.index
(positive integer): The index of value
or its sort-equivalent (if equal
is true
); or, the appropriate insertion index for value
(if equal
is false
).
Example
const bfind = require('bfind')
const arr = ['a', 'c', 'c']
const argsForArr = {get: i => arr[i], length: arr.length}
bfind({...argsForArr, value: 'a'})
bfind({...argsForArr, value: 'b'})
bfind({...argsForArr, value: 'c'})
bfind({...argsForArr, value: 'c', multiple: 'last'})
Related
This module is part of the “b” family of binary search modules.