@bemoje/arr-sorted-index-of/readme.md

Binary search -based indexOf for sorted arrays.

# @bemoje/arr-sorted-index-of

Binary search  -based indexOf for sorted arrays.

#### Version

<span><a href="https://npmjs.org/@bemoje/arr-sorted-index-of" title="View this project on NPM"><img src="https://img.shields.io/npm/v/@bemoje/arr-sorted-index-of" alt="NPM version" /></a></span>

#### Travis CI

<span><a href="https://npmjs.org/@bemoje/arr-sorted-index-of" title="View this project on NPM"><img src="https://travis-ci.org/bemoje/bemoje-arr-sorted-index-of.svg?branch=master" alt="dependencies" /></a></span>

#### Dependencies

<span><a href="https://npmjs.org/@bemoje/arr-sorted-index-of" title="View this project on NPM"><img src="https://david-dm.org/bemoje/bemoje-arr-sorted-index-of.svg" alt="dependencies" /></a></span>

#### Stats

<span><a href="https://npmjs.org/@bemoje/arr-sorted-index-of" title="View this project on NPM"><img src="https://img.shields.io/npm/dt/@bemoje/arr-sorted-index-of" alt="NPM downloads" /></a></span>
<span><a href="https://github.com/bemoje/bemoje-arr-sorted-index-of/fork" title="Fork this project"><img src="https://img.shields.io/github/forks/bemoje/bemoje-arr-sorted-index-of" alt="Forks" /></a></span>

#### Donate

<span><a href="https://www.buymeacoffee.com/bemoje" title="Donate to this project using Buy Me A Beer"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?label=Buy me a beer!" alt="Buy Me A Beer donate button" /></a></span>
<span><a href="https://paypal.me/forstaaloen" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg?label=PayPal" alt="PayPal donate button" /></a></span>

## 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
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### 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 &lt; 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