# @bemoje/arr-sorted-index-of
Binary search -based indexOf for sorted arrays.
#### Version
#### Travis CI
#### Dependencies
#### Stats
#### Donate
## Installation
```sh
npm install @bemoje/arr-sorted-index-of
npm install --save @bemoje/arr-sorted-index-of
npm install --save-dev @bemoje/arr-sorted-index-of
```
## Usage
```javascript
import arrSortedIndexOf from '@bemoje/arr-sorted-index-of'
const alpha = ['a', 'b', 'c']
arrSortedIndexOf(alpha, 'b')
//=> 1
arrSortedIndexOf(alpha, 'e')
//=> -1
const numeric = [2, 13, 20]
arrSortedIndexOf(numeric, 20, {
numeric: true,
})
//=> 2
arrSortedIndexOf(numeric, 20, (a, b) => {
return a - b
})
//=> 2
const arrays = [
[192, 168, 0, 0],
[192, 168, 0, 1],
[192, 168, 1, 0],
]
arrSortedIndexOf(arrays, [192, 168, 0, 1], {
numeric: true,
arrays: true,
})
//=> 1
let elem
const objectsByName = [
{ name: 'bonzo', age: 9 },
{ name: 'john', age: 7 },
]
elem = { name: 'john', age: 7 }
arrSortedIndexOf(objectsByName, elem, {
by: 'name',
})
//=> 1
const objectsByAge = [
{ name: 'john', age: 7 },
{ name: 'bonzo', age: 9 },
]
elem = { name: 'john', age: 7 }
arrSortedIndexOf(objectsByAge, elem, {
by: 'age',
})
//=> 0
const valuesByAge = [
['john', 7],
['bonzo', 9],
]
elem = ['bonzo', 9]
arrSortedIndexOf(objectsByAge, elem, {
by: 1,
})
//=> 1
const valuesByFirstInt = [
['john', 'johnson', 7],
['tracy', 'chapman', 9],
]
elem = ['tracy', 'chapman', 9]
arrSortedIndexOf(valuesByFirstInt, elem, {
by: (arrElem) => {
for (let val of arrElem) {
if (Number.isInteger(val)) {
return val
}
}
},
})
//=> 1
```
## Tests
Uses *Jest* to test module functionality. Run tests to get coverage details.
```bash
npm run test
```
## API
#### Table of Contents
- [arrSortedIndexOf][1]
- [Parameters][2]
- [comparator][3]
- [Parameters][4]
- [getter][5]
- [Parameters][6]
## arrSortedIndexOf
Binary search -based indexOf for sorted arrays.
##### Parameters
- `arr` **[Array][7]** The array to search
- `element` **any** The element to find
- `compare` **([comparator][8] \| [object][9])?**
- `compare.numeric` **[boolean][10]** Sort numerically. Defaults to lexicographic/alphabetic sort. (optional, default `false`)
- `compare.descending` **[boolean][10]** Sort in descending order. Defaults to ascending order. (optional, default `false`)
- `compare.array` **[boolean][10]** Sort arrays. Nested arrays are also compared recursively. (optional, default `false`)
- `compare.by` **([number][11] \| [string][12] \| [getter][13])** Sort by either array index, a callback(element): any - or by object keys with dot-notation support. (optional, default `undefined`)
Returns **[number][11]** Returns -1 if not found, if found, returns the elements index position.
## comparator
Comparator function callback definition.
Type: [Function][14]
##### Parameters
- `a` **any** The first value to compare
- `b` **any** The second value to compare
Returns **[number][11]** A negative number if a > b, a positive number if a < b, 0 otherwise.
## getter
Callback type definition.
Type: [Function][14]
##### Parameters
- `a` **any** The value
Returns **any** The value to be compared
[1]: #arrsortedindexof
[2]: #parameters
[3]: #comparator
[4]: #parameters-1
[5]: #getter
[6]: #parameters-2
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[8]: #comparator
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[13]: #getter
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function