## 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:
```haskell
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:
```haskell
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`.
```haskell
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`.
```haskell
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.
```haskell
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.
```haskell
(-) :: 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`.
```haskell
-- 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`.
```haskell
subtractSigned :: forall a. Subtraction a =>
a -> a -> Signed
```
`subtractInteger` does the same thing, but gives the result as `Integer` instead
of `Signed`.
```haskell
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`).
```haskell
subtract :: forall b a. (Subtraction' b, Subtraction a) =>
a -> a -> b
```