Apache-2.0 licensed by Chris Martin
Maintained by Chris Martin, Julie Moronuki
This version can be pinned in stack with:integer-types-,2198

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


Added module Integer.AbsoluteDifference

Added to the Integer module: AbsoluteDifference (absoluteDifference)

Date: 2023-07-15

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

Add Read instance for Positive

Date: 2023-06-26

Add Hashable instances for Positive, Sign, and Signed

Add Enum and Bounded instances for Sign

Date: 2023-04-22

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

Consolidate all the test suites into one

Remove Safe pragmas

Date: 2023-01-16

Initial release

Date: 2022-11-29