# integer-types

Integer, Natural, and Positive

https://github.com/typeclasses/integer-types

LTS Haskell 22.32: | 0.1.4.0 |

Stackage Nightly 2023-12-26: | 0.1.4.0 |

Latest on Hackage: | 0.1.4.0 |

**Chris Martin**

**Chris Martin, Julie Moronuki**

`integer-types-0.1.4.0@sha256:47d356d87ee96e38f98c6697ac1bcc903c0bb7c1cc99b17ee642cabc695d4e58,2198`

*(full list with versions)*:

## 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
```

## Changes

## 0.1.4.0

Added module `Integer.AbsoluteDifference`

Added to the `Integer`

module: `AbsoluteDifference (absoluteDifference)`

Date: 2023-07-15

## 0.1.3.0

Added modules `Integer.Increase`

, `Integer.StrictlyIncrease`

Added classes to the `Integer`

module:
`Increase (increase)`

, `StrictlyIncrease (strictlyIncrease)`

Added to the `Integer.Integer`

module: `increase`

, `strictlyIncrease`

Added to the `Integer.Natural`

module: `strictlyIncrease`

Added to the `Integer.Positive`

module: `increase`

Added to the `Integer.Signed`

module: `increase`

, `strictlyIncrease`

,
`one`

, `addOne`

, `subtractOne`

Date: 2023-07-14

## 0.1.2.0

Add `Read`

instance for `Positive`

Date: 2023-06-26

## 0.1.1.0

Add `Hashable`

instances for `Positive`

, `Sign`

, and `Signed`

Add `Enum`

and `Bounded`

instances for `Sign`

Date: 2023-04-22

## 0.1.0.0

Change type of `Integer.Natural.addOne`

from
`Integer -> Integer`

to `Natural -> Positive`

New functions:

```
Integer.Natural.length :: [a] -> Natural
Integer.Positive.length :: NonEmpty a -> Positive
```

Date: 2023-02-09

## 0.0.0.1

Consolidate all the test suites into one

Remove `Safe`

pragmas

Date: 2023-01-16

## 0.0.0.0

Initial release

Date: 2022-11-29