# 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

See all snapshots `integer-types` appears in

Apache-2.0 licensed by
Maintained by
This version can be pinned in stack with:`integer-types-0.1.4.0@sha256:47d356d87ee96e38f98c6697ac1bcc903c0bb7c1cc99b17ee642cabc695d4e58,2198`

#### Module documentation for 0.1.4.0

Depends on 4 packages(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
``````

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

Initial release

Date: 2022-11-29