A bounded natural number (>= 0).

value / return types

-- >= 4
Nat (ValueMin Nat4)


-- 2 <= nat <= 12
Nat (ValueIn Nat2 Nat12)


-- = 3, & 3, described as a difference
Nat
    (ValueN Nat3
        (Nat3Plus more)
        (Is a To (Nat3Plus a))
        (Is b To (Nat3Plus b))
    )

function argument types

-- >= 4
Nat (In (Nat4Plus minMinus4) max maybeN)


-- 4 <= nat <= 15
Nat (In (Nat4Plus minMinus4) Nat15 maybeN)


-- An exact number nTo15 away from 15
Nat (N n (Is nTo15 To Nat15) x)


-- any, just >= 0
Nat range


-- Not constuctable
Nat Banana

The absolute value of an Int, which is at least Nat0.

Nat.abs 16 --> Nat 16


Nat.abs -4 --> Nat 4

Really only use this if you want the absolute value.

badLength list =
    List.length >> Nat.abs


goodLength =
    List.foldl
        (\_ ->
            MinNat.addN nat1
                >> Nat.lowerMin nat0
        )
        (nat0 |> Nat.toMin)

If something like this isn't possible, use MinNat.intAtLeast!

Nat (In ...)s from a first to a last value.

from3To10 : List (Nat (ValueIn Nat3 (Nat10Plus a)))
from3To10 =
    Nat.range nat3 nat10


from3ToAtLeast10 : List (Nat (ValueMin Nat3))
from3ToAtLeast10 =
    Nat.range nat3 atLeast10

The resulting List always has at least 1 element.

Generate a random Nat (ValueIn ...) in a range.

A Nat (Min ...) from an Int; if the Int < minimum, minimum is returned.

9 |> Nat.intAtLeast nat3
--> Nat 9


0 |> Nat.intAtLeast nat3
--> Nat 3

You can also use this if you know an Int must be at least minimum.

But avoid it if you can do better, like

goodLength =
    List.foldl
        (\_ ->
            MinNat.addN nat1
                >> Nat.lowerMin nat0
        )
        (nat0 |> Nat.toMin)

If you want to handle the case < minimum yourself, use Nat.isIntAtLeast.

A Nat (In ...) from an Int, clamped between a minimum & maximum.

• if the Int < minimum, minimum is returned
• if the Int > maximum, maximum is returned

clampBetween3And12 =
    Nat.intInRange nat3 nat12

9 |> clampBetween3And12 --> Nat 9

0 |> clampBetween3And12 --> Nat 3

99 |> clampBetween3And12 --> Nat 12

If you want to handle the cases < minimum & > maximum explicitly, use isIntInRange.

An Int compared to a range from first to last.

rejectOrAcceptUserInt =
    Nat.isIntInRange nat1 nat100
        { less = Err "must be >= 1"
        , greater = \_-> Err "must be <= 100"
        , inRange = Ok
        }


rejectOrAcceptUserInt 0
--> Err "must be >= 1"

If the Int >= a minimum, Just the Nat (Min minimum), else Nothing.

4 |> Nat.isIntAtLeast nat5 --> Nothing


1234 |> Nat.isIntAtLeast nat5 --> Just (Nat 1234)

The greater of 2 Nats.

Nat.theGreater between1And3 (nat4 |> Nat.lowerMin nat1)
--> Nat 4

The smaller of 2 Nats.

Nat.theSmaller nat3 (nat4 |> Nat.lowerMin nat3)
--> Nat 3

The Nat (ValueMin ...) ^ a Nat (ValueMin ...). We know that if a >= 1 → x ^ a >= x

atLeast5 |> Nat.toPower nat2
--> Nat 25 of type Nat (ValueMin Nat5)


atLeast2 |> Nat.toPower nat5
--> Nat 25 of type Nat (ValueMin Nat2)

The remainder after division.

• % 0 is impossible
• x % d is at most x

atMost7 |> Nat.remainderBy nat3
--> Nat 1 of type Nat (In Nat0 (Nat7Plus a))

Multiply by a Nat (In ...) >= 1. we know that if a >= 1, x * a >= x.

atLeast5  |> Nat.mul nat2
--> Nat 10 of type Nat (ValueMin Nat5)


atLeast2 |> Nat.mul nat5
--> Nat 10 of type Nat (ValueMin Nat2)

The maximum value of both factors can be Infinity.

Divide (//) by a Nat (In ...).

• / 0 is impossible

• x / d is at most x

atMost7
    |> Nat.div nat3
--> Nat 2 of type Nat (ValueIn Nat0 (Nat7Plus a))

Convert a Nat to an Int.

nat4 |> Nat.toInt --> 4
between4And10 |> Nat.toInt
atLeast4 |> Nat.toInt


compareNats : Nat range -> Nat range -> Order
compareNats a b =
    compare (Nat.toInt a) (Nat.toInt b)

Use the Int values of two Nats to return a result.

Nat.bi (>=) nat5 nat4 --> True


Nat.bi (>=) nat5 nat40 --> False

Note, that you must give the Nats in the same order you would give Ints.

Don't overuse this.

Set the minimum lower.

[ atLeast3, atLeast4 ]

Elm complains:

But all the previous elements in the list are: Nat (ValueMin Nat3)

[ atLeast3
, atLeast4 |> MNat.lowerMin nat3
]

Convert an exact Nat (In min ...) to a Nat (ValueMin min).

in4To10 |> Nat.toMin
--> is of type Nat (ValueMin Nat4)

There is only 1 situation you should use this.

To make these the same type.

[ atLeast1, in1To10 ]

Elm complains:

But all the previous elements in the list are: Nat (ValueMin Nat1)

[ atLeast1
, in1To10 |> Nat.toMin
]

Make it fit into functions with require a higher maximum.

You should design type annotations as general as possible.

onlyAtMost18 : Nat (In min Nat18 maybeN)


onlyAtMost18 between3And8 --fine

But once you implement onlyAtMost18, you might use the value in onlyAtMost19.

onlyAtMost18 value =
    -- onlyAtMost19 value --error :(
    onlyAtMost19
        (value |> Nat.maxIs nat18 {- works :) -})

lowerMin is also handy in those situations.