## Core types: Integer, Natural, Positive

The primary module of the `integer-types`

package is `Integer`

, which exports
the following integer-like types:

Type |
Range |

`Integer` |
(-∞, ∞) |

`Natural` |
(0, ∞) |

`Positive` |
(1, ∞) |

## The Signed type

In addition to `Integer`

, there is also an equivalent type called `Signed`

that
is represented as:

```
data Signed = Zero | NonZero Sign Positive
data Sign = MinusSign | PlusSign
```

`Signed`

also comes with bundled pattern synonyms that allow it to be used as if
it had the following definition:

```
data Signed = Minus Positive | Zero | Plus Positive
```

## Monomorphic conversions

The following modules contain monomorphic conversion functions:

`Integer.Integer`

`Integer.Natural`

`Integer.Positive`

`Integer.Signed`

For example, you can convert from `Positive`

to `Integer`

using either
`Integer.Positive.toInteger`

or `Integer.Integer.fromPositive`

, which are two
names for the same function of type `Positive -> Integer`

.

Since not all integers are positive, the corresponding function in the reverse
direction has a `Maybe`

codomain. `Integer.Integer.toPositive`

and
`Integer.Positive.fromInteger`

have the type `Integer -> Maybe Positive`

.

## Polymorphic conversions

The `Integer`

module exports two polymorphic conversion functions. The first is
for conversions that always succeed, such as `Positive -> Integer`

.

```
convert :: IntegerConvert a b => a -> b
```

The second is for conversions that may fail because they convert to a subset of
the domain, such as `Integer -> Maybe Positive`

.

```
narrow :: IntegerNarrow a b => a -> Maybe b
```

## Finite integer subsets

In addition to the conversion utilities discussed above, this library also
provides some minimal support for converting to/from the `Word`

and `Int`

types.
These are system-dependent finite subsets of `Integer`

that are sometimes used
for performance reasons.

```
toFinite :: (ConvertWithFinite a, Finite b) => a -> Maybe b
fromFinite :: (ConvertWithFinite a, Finite b) => b -> Maybe a
```

For example, `toFinite`

may specialize as `Positive -> Maybe Int`

, and
`fromFinite`

may specialize as `Int -> Maybe Positive`

.

## Monomorphic subtraction

For the `Integer`

and `Signed`

types that represent the full range of integers,
the standard arithmetic operations in the `Num`

and `Integral`

classes are
suitable.

For `Natural`

and `Positive`

, which are subsets of the integers, the standard
classes are not entirely appropriate. Consider, for example, subtraction.

```
(-) :: Num a => a -> a -> a
```

`Natural`

and `Positive`

do belong to the `Num`

class, but subtraction and some
other operations are partial; the expression `1 - 2`

throws instead of returning
a value, because the integer result `-1`

is negative and not representable by
either `Natural`

or `Positive`

.

For this reason, `Natural`

and `Positive`

have their own subtraction functions
that return `Signed`

.

```
-- from Integer.Positive
subtract :: Positive -> Positive -> Signed
-- from Integer.Natural
subtract :: Natural -> Natural -> Signed
```

## Polymorphic subtraction

In addition to the `(-)`

method from the `Num`

class and the `subtract`

functions for `Natural`

and `Positive`

, there are some polymorphic subtraction
functions in the `Integer`

module. `subtractSigned`

generalizes the two
monomorphic functions discussed in the previous section. Its codomain is
`Signed`

.

```
subtractSigned :: forall a. Subtraction a =>
a -> a -> Signed
```

`subtractInteger`

does the same thing, but gives the result as `Integer`

instead
of `Signed`

.

```
subtractInteger :: forall a. Subtraction a =>
a -> a -> Integer
```

The `subtract`

function generalizes further. Its domain is any subtractable type
(`Natural`

, `Positive`

, `Integer`

, or `Signed`

) and its codomain is any type
that can represent the full range of integers (`Integer`

or `Signed`

).

```
subtract :: forall b a. (Subtraction' b, Subtraction a) =>
a -> a -> b
```