[{"name":"Natural","comment":" Compute with the [natural numbers](https://en.wikipedia.org/wiki/Natural_number), ℕ = { 0, 1, 2, ... }.\n\n\n# Representation\n\n@docs Natural\n\n\n# Constants\n\nThe natural numbers from [`0`](#zero) to [`10`](#ten) inclusive are named.\n\n@docs zero, one, two, three, four, five, six, seven, eight, nine, ten\n\n\n# Limits\n\nLet `n : Int`. If `0 <= n <= maxSafeInt` then `n` is called a **safe `Int`**.\n\n@docs maxSafeInt\n\n\n# Constructors\n\n@docs fromSafeInt, fromInt, fromSafeString, fromString, fromBinaryString, fromOctalString, fromDecimalString, fromHexString, fromBaseBString\n\n\n# Comparison\n\nTo test for equality between two natural numbers you can use `==` and `/=`.\n\n    add two two == four\n\n    mul three three /= six\n\nFor all other comparisons you will have to use the functions below.\n\n@docs compare, isLessThan, isLessThanOrEqual, isGreaterThan, isGreaterThanOrEqual, max, min\n\n\n# Predicates\n\n@docs isZero, isOne, isPositive, isEven, isOdd\n\n\n# Arithmetic\n\n@docs add, sub, mul, divModBy, divBy, modBy, exp\n\n\n# Conversion\n\n@docs toInt, toString, toBinaryString, toOctalString, toDecimalString, toHexString, toBaseBString\n\n","unions":[{"name":"Natural","comment":" A representation of the natural numbers.\n\n**N.B.** _The size of the numbers you can compute with is only limited by the\navailable memory._\n\n","args":[],"cases":[]}],"aliases":[],"values":[{"name":"add","comment":" Add two natural numbers.\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"compare","comment":" Compare any two natural numbers.\n\n    compare three four == LT\n\n    compare four four == EQ\n\n    compare five four == GT\n\n","type":"Natural.Natural -> Natural.Natural -> Basics.Order"},{"name":"divBy","comment":" Find the quotient when the second natural number is divided by the first.\n\n**N.B.** _Please see [`divModBy`](#divModBy) to understand how the quotient is computed._\n\n","type":"Natural.Natural -> Natural.Natural -> Maybe.Maybe Natural.Natural"},{"name":"divModBy","comment":" Find the quotient and remainder when the second natural number (the **dividend**) is divided by\nthe first (the **divisor**).\n\nThis operation performs [Euclidean division](https://en.wikipedia.org/wiki/Euclidean_division)\nor **division with remainder**.\n\n`divModBy d D` of two natural numbers `D` and `d ≠ 0`,\nis defined as producing two unique natural numbers `q` (the **quotient**) and `r` (the **remainder**)\nsuch that\n\n  - `d * q` is the greatest multiple of `d` less than or equal to `D`, and\n  - `r = D - d * q` such that `0 <= r < d`.\n\nFor e.g.\n\n    (ten |> divModBy two) == Just (five, zero)\n    -- Because 2 * 5 = 10 is the greatest multiple of 2 less than or equal to 10, and\n    -- 0 = 10 - 2 * 5 such that 0 <= 0 < 10.\n\n    (ten |> divModBy three) == Just (three, one)\n    -- Because 3 * 3 = 9 is the greatest multiple of 3 less than or equal to 10, and\n    -- 1 = 10 - 3 *3 such that 0 <= 1 < 10.\n\nDivision by [`0`](#zero) is not allowed. So, for all `n : Natural`,\n\n    (n |> divModBy zero) == Nothing\n\n","type":"Natural.Natural -> Natural.Natural -> Maybe.Maybe ( Natural.Natural, Natural.Natural )"},{"name":"eight","comment":" The natural number [`8`](https://en.wikipedia.org/wiki/8).\n","type":"Natural.Natural"},{"name":"exp","comment":" Find the power of the first natural number (the **base**) to the second\nnatural number (the **exponent**).\n\n    exp two three == eight\n\nFor all `n : Natural`,\n\n    exp n zero == one\n\nIn particular,\n\n    exp zero zero == one\n\n**N.B.** _You can read \"[What is `0^0`?](https://maa.org/book/export/html/116806)\" to learn more_.\n\nFor all `n : Natural`, where `n` is positive,\n\n    exp zero n == zero\n\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"five","comment":" The natural number [`5`](https://en.wikipedia.org/wiki/5).\n","type":"Natural.Natural"},{"name":"four","comment":" The natural number [`4`](https://en.wikipedia.org/wiki/4).\n","type":"Natural.Natural"},{"name":"fromBaseBString","comment":" Create the natural number represented by the given base-`b` string.\n\n`b` must be between 2 and 36 inclusive and each character in the string must be\na valid base-`b` digit.\n\n\n### About base-`b` digits\n\nA valid base-`b` digit is any digit `d` such that `0 <= d <= b - 1`.\n\nFor bases larger than 10, we use case-insensitive letters from the [Latin alphabet](https://en.wikipedia.org/wiki/Latin_alphabet)\nto represent the base-`b` digits that are 10 or larger. So,\n\n```txt\nA or a represents 10\nB or b represents 11\nC or c represents 12\n...\nZ or z represents 35\n```\n\nFor e.g.\n\nIf `b = 16` then the valid base-16 digits are `[0-9a-fA-F]`.\n\nIf `b = 36` then the valid base-36 digits are `[0-9a-zA-Z]`.\n\n\n### Syntax for `fromBaseBString` input\n\n```txt\ninput ::= [digit]+\ndigit ::= [0-9a-zA-Z]\n```\n\nValid strings when `b = 16`:\n\n`\"0\"`, `\"123\"`, and `\"Ff\"`.\n\nInvalid strings when `b = 16`:\n\n  - `\"+2\"`, because `'+'` is not part of the allowed syntax,\n  - `\"5g\"`, because `'g'` is not a hexdecimal digit.\n\nFor e.g.\n\n    fromBaseBString 2 \"1010\" == Just ten\n\n    fromBaseBString 16 \"aD\" == fromInt 173\n\n    fromBaseBString 36 \"z\" == fromInt 35\n\n    fromBaseBString 2 \"\" == Nothing\n    -- Because the string is empty.\n\n    fromBaseBString 10 \"A\" == Nothing\n    -- Because 'A' is not a decimal digit.\n\n","type":"Basics.Int -> String.String -> Maybe.Maybe Natural.Natural"},{"name":"fromBinaryString","comment":" Create the natural number represented by the given binary string.\n\n```txt\nbinary ::= [0-1]+\n```\n\nFor e.g.\n\n    fromBinaryString \"0\" == Just zero\n\n    fromBinaryString \"1010\" == Just ten\n\n    fromBinaryString \"\" == Nothing\n    -- Because the string is empty.\n\n    fromBinaryString \"2\" == Nothing\n    -- Because '2' is not a binary digit.\n\n","type":"String.String -> Maybe.Maybe Natural.Natural"},{"name":"fromDecimalString","comment":" Create the natural number represented by the given decimal string.\n\n```txt\ndecimal ::= [0-9]+\n```\n\nFor e.g.\n\n    fromDecimalString \"0\" == Just zero\n\n    fromDecimalString \"10\" == Just ten\n\n    fromDecimalString \"\" == Nothing\n    -- Because the string is empty.\n\n    fromDecimalString \"A\" == Nothing\n    -- Because 'A' is not a decimal digit.\n\n","type":"String.String -> Maybe.Maybe Natural.Natural"},{"name":"fromHexString","comment":" Create the natural number represented by the given hexadecimal string.\n\n```txt\nhex ::= [0-9a-fA-F]+\n```\n\nFor e.g.\n\n    fromHexString \"0\" == Just zero\n\n    fromHexString \"a\" == Just ten\n\n    fromHexString \"A\" == Just ten\n\n    fromHexString \"FE\" == fromInt 254\n\n    fromHexString \"\" == Nothing\n    -- Because the string is empty.\n\n    fromHexString \"5g\" == Nothing\n    -- Because 'g' is not a hexadecimal digit.\n\n","type":"String.String -> Maybe.Maybe Natural.Natural"},{"name":"fromInt","comment":" Create the natural number that represents the given `Int`.\n\n    fromInt 0 == Just zero\n\n    fromInt 1 == Just one\n\n    fromInt maxSafeInt == fromString \"9007199254740991\"\n\nUnless the given `Int` is negative or greater than [`maxSafeInt`](#maxSafeInt).\n\n    fromInt -1 == Nothing\n\n    fromInt (maxSafeInt + 1) == Nothing\n\n","type":"Basics.Int -> Maybe.Maybe Natural.Natural"},{"name":"fromOctalString","comment":" Create the natural number represented by the given octal string.\n\n```txt\noctal ::= [0-7]+\n```\n\nFor e.g.\n\n    fromOctalString \"0\" == Just zero\n\n    fromOctalString \"12\" == Just ten\n\n    fromOctalString \"\" == Nothing\n    -- Because the string is empty.\n\n    fromOctalString \"8\" == Nothing\n    -- Because '8' is not an octal digit.\n\n","type":"String.String -> Maybe.Maybe Natural.Natural"},{"name":"fromSafeInt","comment":" Use this function when you know the given `Int` is a [safe `Int`](#limits).\n\n    fromSafeInt 0 == zero\n\n    fromSafeInt 1 == one\n\n    fromSafeInt maxSafeInt == fromSafeString \"9007199254740991\"\n\nIf the given `Int` isn't safe then [zero](#zero) is returned.\n\n    fromSafeInt -1 == zero\n\n    fromSafeInt (maxSafeInt + 1) == zero\n\nThis function is useful for establising **small constants** in a calculation.\nFor e.g. to [compute the first 100 digits of π using John Machin's formula](https://en.wikipedia.org/wiki/Machin-like_formula)\nthe natural number 239 is needed.\n\n    twoThirtyNine : Natural\n    twoThirtyNine =\n        fromSafeInt 239\n\n","type":"Basics.Int -> Natural.Natural"},{"name":"fromSafeString","comment":" It's best to use this function when you can guarantee that the string you're\ndealing with is a valid input to the [`fromString`](#fromString) function.\n\nIf the input is invalid then [`zero`](#zero) is returned.\n\n**N.B.** _Read the documentation of [`fromString`](#fromString) to learn what's considered\nto be valid or invalid input to this function._\n\nThis function is useful for establishing **large constants** in a calculation.\n\n    oneGoogol : Natural\n    oneGoogol =\n        -- 10 ^ 100\n        fromSafeString \"10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\"\n\nLearn more about a [googol](https://en.wikipedia.org/wiki/Googol).\n\n\n### What's considered a large constant?\n\nLet `n : Int`, since `fromSafeInt n` can be used for `0 <= n <= maxSafeInt` then it makes sense\nto consider any natural number larger than [`maxSafeInt`](#maxSafeInt), a large constant.\n\n","type":"String.String -> Natural.Natural"},{"name":"fromString","comment":" Create the natural number represented by the given string.\n\n\n### Syntax for `fromString` input\n\n```txt\ninput    ::= unsigned\nunsigned ::= ('0b' | '0B') binary\n           | ('0o' | '0O') octal\n           | ('0x' | '0X') hex\n           | decimal\nbinary   ::= [0-1]+\noctal    ::= [0-7]+\nhex      ::= [0-9a-fA-F]+\ndecimal  ::= [0-9]+\n```\n\nFor e.g.\n\n    fromString \"0b10101101\" == fromInt 173\n\n    fromString \"0o255\" == fromInt 173\n\n    fromString \"0XaD\" == fromInt 173\n\n    fromString \"173\" == fromInt 173\n\n    fromString \"b10101101\" == Nothing\n    -- Because the leading '0' is missing.\n\n    fromString \"aD\" == Nothing\n    -- Because 'a' is not a decimal digit.\n\n    fromString \"0x\" == Nothing\n    -- Because there must be at least one hexadecimal digit.\n\n","type":"String.String -> Maybe.Maybe Natural.Natural"},{"name":"isEven","comment":" Determine if the natural number is even (i.e. divisible by [`2`](#two)).\n\n    isEven zero == True\n\n    isEven one == False\n\n    isEven two == True\n\n    isEven three == False\n\n","type":"Natural.Natural -> Basics.Bool"},{"name":"isGreaterThan","comment":" Determine if the second natural number is greater than the first.\n\n    (two |> isGreaterThan eight) == False\n\n    (two |> isGreaterThan two) == False\n\n    (eight |> isGreaterThan two) == True\n\n","type":"Natural.Natural -> Natural.Natural -> Basics.Bool"},{"name":"isGreaterThanOrEqual","comment":" Determine if the second natural number is greater than or equal to\nthe first.\n\n    (two |> isGreaterThanOrEqual eight) == False\n\n    (two |> isGreaterThanOrEqual two) == True\n\n    (eight |> isGreaterThanOrEqual two) == True\n\n","type":"Natural.Natural -> Natural.Natural -> Basics.Bool"},{"name":"isLessThan","comment":" Determine if the second natural number is less than the first.\n\n    (two |> isLessThan eight) == True\n\n    (two |> isLessThan two) == False\n\n    (eight |> isLessThan two) == False\n\n","type":"Natural.Natural -> Natural.Natural -> Basics.Bool"},{"name":"isLessThanOrEqual","comment":" Determine if the second natural number is less than or equal to the\nfirst.\n\n    (two |> isLessThanOrEqual eight) == True\n\n    (two |> isLessThanOrEqual two) == True\n\n    (eight |> isLessThanOrEqual two) == False\n\n","type":"Natural.Natural -> Natural.Natural -> Basics.Bool"},{"name":"isOdd","comment":" Determine if the natural number is odd (i.e. not even, so not divisible by [`2`](#two)).\n\n    isOdd zero == False\n\n    isOdd one == True\n\n    isOdd two == False\n\n    isOdd three == True\n\n","type":"Natural.Natural -> Basics.Bool"},{"name":"isOne","comment":" Determine if the natural number is [`1`](#one).\n\n    isOne zero == False\n\n    isOne one == True\n\n","type":"Natural.Natural -> Basics.Bool"},{"name":"isPositive","comment":" Determine if the natural number is positive (i.e. greater than [`0`](#zero)).\n\n    isPositive five == True\n\n    isPositive zero == False\n\n","type":"Natural.Natural -> Basics.Bool"},{"name":"isZero","comment":" Determine if the natural number is [`0`](#zero).\n\n    isZero zero == True\n\n    isZero one == False\n\n","type":"Natural.Natural -> Basics.Bool"},{"name":"max","comment":" Find the larger of two natural numbers.\n\n    max five ten == ten\n\n    max ten five == ten\n\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"maxSafeInt","comment":" The largest `Int`, currently `2^53 - 1 = 9007199254740991`, which can be given as input to\n[`fromSafeInt`](#fromSafeInt) and [`fromInt`](#fromInt) without causing problems.\n","type":"Basics.Int"},{"name":"min","comment":" Find the smaller of two natural numbers.\n\n    min five ten == five\n\n    min ten five == five\n\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"modBy","comment":" Find the remainder when the second natural number is divided by the first.\n\n**N.B.** _Please see [`divModBy`](#divModBy) to understand how the remainder is computed._\n\n","type":"Natural.Natural -> Natural.Natural -> Maybe.Maybe Natural.Natural"},{"name":"mul","comment":" Multiply two natural numbers.\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"nine","comment":" The natural number [`9`](https://en.wikipedia.org/wiki/9).\n","type":"Natural.Natural"},{"name":"one","comment":" The natural number [`1`](https://en.wikipedia.org/wiki/1).\n","type":"Natural.Natural"},{"name":"seven","comment":" The natural number [`7`](https://en.wikipedia.org/wiki/7).\n","type":"Natural.Natural"},{"name":"six","comment":" The natural number [`6`](https://en.wikipedia.org/wiki/6).\n","type":"Natural.Natural"},{"name":"sub","comment":" Subtract the second natural number from the first.\n\n    sub ten four == six\n    -- 10 - 4 = 6\n\nIt uses [saturating subtraction](https://en.wikipedia.org/wiki/Saturation_arithmetic).\nThus, if the second natural number is larger than the first, 0 is returned.\n\n    sub four ten == zero\n    -- 4 - 10 = 0\n\n","type":"Natural.Natural -> Natural.Natural -> Natural.Natural"},{"name":"ten","comment":" The natural number [`10`](https://en.wikipedia.org/wiki/10).\n","type":"Natural.Natural"},{"name":"three","comment":" The natural number [`3`](https://en.wikipedia.org/wiki/3).\n","type":"Natural.Natural"},{"name":"toBaseBString","comment":" Convert any natural number to its base-`b` representation.\n\n`b` must be between 2 and 36 inclusive and each character in the resulting\nstring will be a valid base-`b` digit.\n\nAll [Latin letters](https://en.wikipedia.org/wiki/Latin_alphabet) in the\nbase-`b` representation will be in uppercase.\n\nFor e.g.\n\n    toBaseBString 2 (fromSafeInt 1729) == Just \"11011000001\"\n\n    toBaseBString 8 (fromSafeInt 1729) == Just \"3301\"\n\n    toBaseBString 10 (fromSafeInt 1729) == Just \"1729\"\n\n    toBaseBString 16 (fromSafeInt 1729) == Just \"6C1\"\n\n    toBaseBString 36 (fromSafeInt 1729) == Just \"1C1\"\n\nFor any `k : Int` where `k < 2` or `k > 36`, and any `n : Natural`,\n\n    toBaseBString k n == Nothing\n\n**N.B.** _Please refer to [`fromBaseBString`](#fromBaseBString) to learn more about\nbase-`b` digits._\n\n","type":"Basics.Int -> Natural.Natural -> Maybe.Maybe String.String"},{"name":"toBinaryString","comment":" Convert any natural number to its binary (base-2) representation.\n\n    toBinaryString zero == \"0\"\n\n    toBinaryString one == \"1\"\n\n    toBinaryString ten == \"1010\"\n\n    toBinaryString (fromSafeInt 1729) == \"11011000001\"\n\n    toBinaryString (add (fromSafeInt maxSafeInt) one) == \"100000000000000000000000000000000000000000000000000000\"\n\n","type":"Natural.Natural -> String.String"},{"name":"toDecimalString","comment":" Convert any natural number to its decimal (base-10) representation.\n\n    toDecimalString zero == \"0\"\n\n    toDecimalString one == \"1\"\n\n    toDecimalString ten == \"10\"\n\n    toDecimalString (fromSafeInt 1729) == \"1729\"\n\n    toDecimalString (add (fromSafeInt maxSafeInt) one) == \"9007199254740992\"\n\n","type":"Natural.Natural -> String.String"},{"name":"toHexString","comment":" Convert any natural number to its hexadecimal (base-16) representation.\n\n    toHexString zero == \"0\"\n\n    toHexString one == \"1\"\n\n    toHexString ten == \"A\"\n\n    toHexString (fromSafeInt 1729) == \"6C1\"\n\n    toHexString (add (fromSafeInt maxSafeInt) one) == \"20000000000000\"\n\n","type":"Natural.Natural -> String.String"},{"name":"toInt","comment":" Convert any natural number, `n`, to `n mod (maxSafeInt + 1)`.\n\n    toInt zero == 0\n\n    toInt ten == 10\n\n    toInt (fromSafeInt maxSafeInt) == maxSafeInt\n\n    toInt (add (fromSafeInt maxSafeInt) one) == 0\n\n    toInt (add (fromSafeInt maxSafeInt) ten) == 9\n\n","type":"Natural.Natural -> Basics.Int"},{"name":"toOctalString","comment":" Convert any natural number to its octal (base-8) representation.\n\n    toOctalString zero == \"0\"\n\n    toOctalString one == \"1\"\n\n    toOctalString ten == \"12\"\n\n    toOctalString (fromSafeInt 1729) == \"3301\"\n\n    toOctalString (add (fromSafeInt maxSafeInt) one) == \"400000000000000000\"\n\n","type":"Natural.Natural -> String.String"},{"name":"toString","comment":" An alias for [`toDecimalString`](#toDecimalString).\n","type":"Natural.Natural -> String.String"},{"name":"two","comment":" The natural number [`2`](https://en.wikipedia.org/wiki/2).\n","type":"Natural.Natural"},{"name":"zero","comment":" The natural number [`0`](https://en.wikipedia.org/wiki/0).\n\nTo be more precise, it is a representation of the natural number `0`. However, I\nwill not have any cause to make that distinction. A similar remark can be made\nabout the other constants.\n\n","type":"Natural.Natural"}],"binops":[]}]