## Ord overview

The `Ord` type class represents types which support comparisons with a total order.

Instances should satisfy the laws of total orderings:

1. Reflexivity: `S.compare(a, a) <= 0`
2. Antisymmetry: if `S.compare(a, b) <= 0` and `S.compare(b, a) <= 0` then `a <-> b`
3. Transitivity: if `S.compare(a, b) <= 0` and `S.compare(b, c) <= 0` then `S.compare(a, c) <= 0`

# constructors

## fromCompare

Signature

``````export declare const fromCompare: <A>(compare: (first: A, second: A) => Ordering) => Ord<A>
``````

# defaults

## equalsDefault

Signature

``````export declare const equalsDefault: <A>(compare: (first: A, second: A) => Ordering) => (x: A, y: A) => boolean
``````

# instances

## Contravariant

Signature

``````export declare const Contravariant: Contravariant1<'Ord'>
``````

## getMonoid

Returns a `Monoid` such that:

• its `concat(ord1, ord2)` operation will order first by `ord1`, and then by `ord2`
• its `empty` value is an `Ord` that always considers compared elements equal

Signature

``````export declare const getMonoid: <A = never>() => Monoid<Ord<A>>
``````

Example

``````import { sort } from 'fp-ts/Array'
import { contramap, reverse, getMonoid } from 'fp-ts/Ord'
import * as S from 'fp-ts/string'
import * as B from 'fp-ts/boolean'
import { pipe } from 'fp-ts/function'
import { concatAll } from 'fp-ts/Monoid'
import * as N from 'fp-ts/number'

interface User {
}

const byName = pipe(
S.Ord,
contramap((p: User) => p.name)
)

const byAge = pipe(
N.Ord,
contramap((p: User) => p.age)
)

const byRememberMe = pipe(
B.Ord,
contramap((p: User) => p.rememberMe)
)

const M = getMonoid<User>()

const users: Array<User> = [
{ id: 1, name: 'Guido', age: 47, rememberMe: false },
{ id: 2, name: 'Guido', age: 46, rememberMe: true },
{ id: 3, name: 'Giulio', age: 44, rememberMe: false },
{ id: 4, name: 'Giulio', age: 44, rememberMe: true },
]

// sort by name, then by age, then by `rememberMe`
const O1 = concatAll(M)([byName, byAge, byRememberMe])
assert.deepStrictEqual(sort(O1)(users), [
{ id: 3, name: 'Giulio', age: 44, rememberMe: false },
{ id: 4, name: 'Giulio', age: 44, rememberMe: true },
{ id: 2, name: 'Guido', age: 46, rememberMe: true },
{ id: 1, name: 'Guido', age: 47, rememberMe: false },
])

// now `rememberMe = true` first, then by name, then by age
const O2 = concatAll(M)([reverse(byRememberMe), byName, byAge])
assert.deepStrictEqual(sort(O2)(users), [
{ id: 4, name: 'Giulio', age: 44, rememberMe: true },
{ id: 2, name: 'Guido', age: 46, rememberMe: true },
{ id: 3, name: 'Giulio', age: 44, rememberMe: false },
{ id: 1, name: 'Guido', age: 47, rememberMe: false },
])
``````

## getSemigroup

A typical use case for the `Semigroup` instance of `Ord` is merging two or more orderings.

For example the following snippet builds an `Ord` for a type `User` which sorts by `created` date descending, and then `lastName`

Signature

``````export declare const getSemigroup: <A = never>() => Semigroup<Ord<A>>
``````

Example

``````import * as D from 'fp-ts/Date'
import { pipe } from 'fp-ts/function'
import { contramap, getSemigroup, Ord, reverse } from 'fp-ts/Ord'
import * as RA from 'fp-ts/ReadonlyArray'
import * as S from 'fp-ts/string'

interface User {
}

const ordByLastName: Ord<User> = pipe(
S.Ord,
contramap((user) => user.lastName)
)

const ordByCreated: Ord<User> = pipe(
D.Ord,
contramap((user) => user.created)
)

const ordUserByCreatedDescThenLastName = getSemigroup<User>().concat(reverse(ordByCreated), ordByLastName)

assert.deepStrictEqual(
RA.sort(ordUserByCreatedDescThenLastName)([
{ id: 'c', lastName: 'd', created: new Date(1973, 10, 30) },
{ id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
{ id: 'e', lastName: 'f', created: new Date(1980, 10, 30) },
]),
[
{ id: 'e', lastName: 'f', created: new Date(1980, 10, 30) },
{ id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
{ id: 'c', lastName: 'd', created: new Date(1973, 10, 30) },
]
)
``````

# model

## Ord (interface)

Signature

``````export interface Ord<A> extends Eq<A> {
readonly compare: (first: A, second: A) => Ordering
}
``````

# type lambdas

## URI

Signature

``````export declare const URI: 'Ord'
``````

## URI (type alias)

Signature

``````export type URI = typeof URI
``````

# utils

## between

Test whether a value is between a minimum and a maximum (inclusive)

Signature

``````export declare const between: <A>(O: Ord<A>) => (low: A, hi: A) => (a: A) => boolean
``````

## clamp

Clamp a value between a minimum and a maximum

Signature

``````export declare const clamp: <A>(O: Ord<A>) => (low: A, hi: A) => (a: A) => A
``````

## contramap

A typical use case for `contramap` would be like, given some `User` type, to construct an `Ord<User>`.

We can do so with a function from `User -> X` where `X` is some value that we know how to compare for ordering (meaning we have an `Ord<X>`)

For example, given the following `User` type, there are lots of possible choices for `X`, but letâ€™s say we want to sort a list of users by `lastName`.

If we have a way of comparing `lastName`s for ordering (`ordLastName: Ord<string>`) and we know how to go from `User -> string`, using `contramap` we can do this

Signature

``````export declare const contramap: <A, B>(f: (b: B) => A) => (fa: Ord<A>) => Ord<B>
``````

Example

``````import { pipe } from 'fp-ts/function'
import { contramap, Ord } from 'fp-ts/Ord'
import * as RA from 'fp-ts/ReadonlyArray'
import * as S from 'fp-ts/string'

interface User {
}

const ordLastName: Ord<string> = S.Ord

const ordByLastName: Ord<User> = pipe(
ordLastName,
contramap((user) => user.lastName)
)

assert.deepStrictEqual(
RA.sort(ordByLastName)([
{ firstName: 'a', lastName: 'd' },
{ firstName: 'c', lastName: 'b' },
]),
[
{ firstName: 'c', lastName: 'b' },
{ firstName: 'a', lastName: 'd' },
]
)
``````

## equals

Signature

``````export declare const equals: <A>(O: Ord<A>) => (second: A) => (first: A) => boolean
``````

## geq

Test whether one value is non-strictly greater than another

Signature

``````export declare const geq: <A>(O: Ord<A>) => (first: A, second: A) => boolean
``````

## gt

Test whether one value is strictly greater than another

Signature

``````export declare const gt: <A>(O: Ord<A>) => (first: A, second: A) => boolean
``````

## leq

Test whether one value is non-strictly less than another

Signature

``````export declare const leq: <A>(O: Ord<A>) => (first: A, second: A) => boolean
``````

## lt

Test whether one value is strictly less than another

Signature

``````export declare const lt: <A>(O: Ord<A>) => (first: A, second: A) => boolean
``````

## max

Take the maximum of two values. If they are considered equal, the first argument is chosen

Signature

``````export declare const max: <A>(O: Ord<A>) => (first: A, second: A) => A
``````

## min

Take the minimum of two values. If they are considered equal, the first argument is chosen

Signature

``````export declare const min: <A>(O: Ord<A>) => (first: A, second: A) => A
``````

## reverse

Signature

``````export declare const reverse: <A>(O: Ord<A>) => Ord<A>
``````

## trivial

Signature

``````export declare const trivial: Ord<unknown>
``````

## tuple

Given a tuple of `Ord`s returns an `Ord` for the tuple.

Signature

``````export declare const tuple: <A extends readonly unknown[]>(...ords: { [K in keyof A]: Ord<A[K]> }) => Ord<Readonly<A>>
``````

Example

``````import { tuple } from 'fp-ts/Ord'
import * as B from 'fp-ts/boolean'
import * as S from 'fp-ts/string'
import * as N from 'fp-ts/number'

const O = tuple(S.Ord, N.Ord, B.Ord)
assert.strictEqual(O.compare(['a', 1, true], ['b', 2, true]), -1)
assert.strictEqual(O.compare(['a', 1, true], ['a', 2, true]), -1)
assert.strictEqual(O.compare(['a', 1, true], ['a', 1, false]), 1)
``````

# zone of death

## getDualOrd

Use `reverse` instead.

Signature

``````export declare const getDualOrd: <A>(O: Ord<A>) => Ord<A>
``````

## getTupleOrd

Use `tuple` instead.

Signature

``````export declare const getTupleOrd: <T extends readonly Ord<any>[]>(
...ords: T
) => Ord<{ [K in keyof T]: T[K] extends Ord<infer A> ? A : never }>
``````

## ordBoolean

Use `Ord` instead.

Signature

``````export declare const ordBoolean: Ord<boolean>
``````

## ordDate

Use `Ord` instead.

Signature

``````export declare const ordDate: Ord<Date>
``````

## ordNumber

Use `Ord` instead.

Signature

``````export declare const ordNumber: Ord<number>
``````

## ordString

Use `Ord` instead.

Signature

``````export declare const ordString: Ord<string>
``````

## ord

Use `Contravariant` instead.

Signature

``````export declare const ord: Contravariant1<'Ord'>
``````