# precise-bs

[![CircleCI](https://circleci.com/gh/jcoreio/precise-bs.svg?style=svg)](https://circleci.com/gh/jcoreio/precise-bs)
[![Coverage Status](https://codecov.io/gh/jcoreio/precise-bs/branch/master/graph/badge.svg)](https://codecov.io/gh/jcoreio/precise-bs)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![npm version](https://badge.fury.io/js/precise-bs.svg)](https://badge.fury.io/js/precise-bs)

binary search and related utility functions

# `lowerIndex`/`lowerValue`/`lowerEntry`

```ts
export function lowerIndex<Arr extends AnyArray>(
  array: Arr,
  find: Arr[number]
): number
export function lowerValue<Arr extends AnyArray, Find>(
  array: Arr,
  find: Find,
  comparator: Comparator<Arr[number] | Find>,
  low?: number,
  high?: number
): number

export function lowerValue<...>(...): Arr[number]
export function lowerEntry<...>(...): [number, Arr[number]]
```

Finds the index/value/entry of the least element less than the
given search value in a sorted array using a binary search. If the
search value is less than or equal to all elements in the array,
returns the index `-1` or value `undefined` or entry `[-1, undefined]`.

# `floorIndex`/`floorValue`/`floorEntry`

```ts
export function floorIndex<Arr extends AnyArray>(
  array: Arr,
  find: Arr[number]
): number
export function floorValue<Arr extends AnyArray, Find>(
  array: Arr,
  find: Find,
  comparator: Comparator<Arr[number] | Find>,
  low?: number,
  high?: number
): number

export function floorValue<...>(...): Arr[number]
export function floorEntry<...>(...): [number, Arr[number]]
```

Finds the index/value/entry of the least element less than or equal to the
given search value in a sorted array using a binary search. If the
search value is less than all elements in the array,
returns the index `-1` or value `undefined` or entry `[-1, undefined]`.

# `ceilingIndex`/`ceilingValue`/`ceilingEntry`

```ts
export function ceilingIndex<Arr extends AnyArray>(
  array: Arr,
  find: Arr[number]
): number
export function ceilingValue<Arr extends AnyArray, Find>(
  array: Arr,
  find: Find,
  comparator: Comparator<Arr[number] | Find>,
  low?: number,
  high?: number
): number

export function ceilingValue<...>(...): Arr[number]
export function ceilingEntry<...>(...): [number, Arr[number]]
```

Finds the index/value/entry of the least element greater than or equal to the
given search value in a sorted array using a binary search. If the
search value is greater than all elements in the array,
returns the index `array.length` or value `undefined` or entry `[array.length, undefined]`.

# `higherIndex`/`floorValue`/`floorEntry`

```ts
export function higherIndex<Arr extends AnyArray>(
  array: Arr,
  find: Arr[number]
): number
export function higherValue<Arr extends AnyArray, Find>(
  array: Arr,
  find: Find,
  comparator: Comparator<Arr[number] | Find>,
  low?: number,
  high?: number
): number

export function higherValue<...>(...): Arr[number]
export function higherEntry<...>(...): [number, Arr[number]]
```

Finds the index/value/entry of the least element greater than the
given search value in a sorted array using a binary search. If the
search value is greater than or equal all elements in the array,
returns the index `array.length` or value `undefined` or entry `[array.length, undefined]`.

# `type Comparator<T>`

The generic comparator type used by the above binary search functions.

```ts
export type Comparator<T> = (a: T, b: T) => number
```

# `DEFAULT_COMPARATOR`

The default comparator used by the above binary search functions. This differs from
the default `Array.prototype.sort` comparator, which stringifies values before comparing,
and is one of the biggest pitfalls in JS!

```ts
export const DEFAULT_COMPARATOR: Comparator<any> = (a: any, b: any): number =>
  a < b ? -1 : a > b ? 1 : 0
```