integer-types: Integer, Natural, and Positive

[ apache, library, numeric ] [ Propose Tags ]

The base package contains two unbounded integral types: Integer (-∞, ∞) and Natural (0, ∞). This package expands that integral repertoire with the addition of Positive (1, ∞).

[Skip to Readme]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,
Change log
Dependencies base (>=4.16 && <4.18), deepseq (>=1.4.6 && <1.5), quaalude (>=0.0 && <0.1) [details]
License Apache-2.0
Author Chris Martin
Maintainer Chris Martin, Julie Moronuki
Category Numeric
Home page
Bug tracker
Uploaded by chris_martin at 2023-02-10T07:04:54Z
Distributions NixOS:, Stackage:
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 83 total (14 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-02-10 [all 1 reports]

Readme for integer-types-

[back to package description]

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