motoko/packages/latest/base.json

Compile and run Motoko smart contracts in Node.js or the browser.

{"name":"base","version":"moc-0.14.13","files":{"Nat.mo":{"content":"/// Natural numbers with infinite precision.\n///\n/// :::note\n/// Most operations on integer numbers (e.g. addition) are available as built-in operators (e.g. `1 + 1`).\n/// This module provides equivalent functions and `Text` conversion.\n/// :::\n///\n/// :::info Function form for higher-order use\n///\n/// Several arithmetic and comparison functions (e.g. `add`, `sub`, `equal`, `less`, `pow`) are defined in this module to enable their use as first-class function values, which is not possible with operators like `+`, `-`, `==`, etc., in Motoko. This allows you to pass these operations to higher-order functions such as `map`, `foldLeft`, or `sort`.\n/// :::\n///\n/// Import from the base library to use this module.\n///\n/// ```motoko name=import\n/// import Nat \"mo:base/Nat\";\n/// ```\n\nimport Int \"Int\";\nimport Order \"Order\";\nimport Prim \"mo:⛔\";\nimport Char \"Char\";\n\nmodule {\n\n  /// Infinite precision natural numbers.\n  public type Nat = Prim.Types.Nat;\n\n  /// Converts a natural number to its textual representation. Textual\n  /// representation _does not_ contain underscores to represent commas.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.toText 1234 // => \"1234\"\n  /// ```\n  public func toText(n : Nat) : Text = Int.toText n;\n\n  /// Creates a natural number from its textual representation. Returns `null`\n  /// if the input is not a valid natural number.\n  ///\n  /// :::note\n  /// The textual representation _must not_ contain underscores.\n  /// :::\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.fromText \"1234\" // => ?1234\n  /// ```\n  public func fromText(text : Text) : ?Nat {\n    if (text == \"\") {\n      return null\n    };\n    var n = 0;\n    for (c in text.chars()) {\n      if (Char.isDigit(c)) {\n        let charAsNat = Prim.nat32ToNat(Prim.charToNat32(c) -% Prim.charToNat32('0'));\n        n := n * 10 + charAsNat\n      } else {\n        return null\n      }\n    };\n    ?n\n  };\n\n  /// Returns the minimum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.min(1, 2) // => 1\n  /// ```\n  public func min(x : Nat, y : Nat) : Nat {\n    if (x < y) { x } else { y }\n  };\n\n  /// Returns the maximum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.max(1, 2) // => 2\n  /// ```\n  public func max(x : Nat, y : Nat) : Nat {\n    if (x < y) { y } else { x }\n  };\n\n  /// Equality function for Nat types.\n  /// This is equivalent to `x == y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.equal(1, 1); // => true\n  /// 1 == 1 // => true\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Buffer \"mo:base/Buffer\";\n  ///\n  /// let buffer1 = Buffer.Buffer<Nat>(3);\n  /// let buffer2 = Buffer.Buffer<Nat>(3);\n  /// Buffer.equal(buffer1, buffer2, Nat.equal) // => true\n  /// ```\n  public func equal(x : Nat, y : Nat) : Bool { x == y };\n\n  /// Inequality function for Nat types.\n  /// This is equivalent to `x != y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.notEqual(1, 2); // => true\n  /// 1 != 2 // => true\n  /// ```\n  ///\n\n  public func notEqual(x : Nat, y : Nat) : Bool { x != y };\n\n  /// \"Less than\" function for Nat types.\n  /// This is equivalent to `x < y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.less(1, 2); // => true\n  /// 1 < 2 // => true\n  /// ```\n  ///\n\n  public func less(x : Nat, y : Nat) : Bool { x < y };\n\n  /// \"Less than or equal\" function for Nat types.\n  /// This is equivalent to `x <= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.lessOrEqual(1, 2); // => true\n  /// 1 <= 2 // => true\n  /// ```\n  ///\n\n  public func lessOrEqual(x : Nat, y : Nat) : Bool { x <= y };\n\n  /// \"Greater than\" function for Nat types.\n  /// This is equivalent to `x > y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.greater(2, 1); // => true\n  /// 2 > 1 // => true\n  /// ```\n  ///\n\n  public func greater(x : Nat, y : Nat) : Bool { x > y };\n\n  /// \"Greater than or equal\" function for Nat types.\n  /// This is equivalent to `x >= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.greaterOrEqual(2, 1); // => true\n  /// 2 >= 1 // => true\n  /// ```\n  ///\n\n  public func greaterOrEqual(x : Nat, y : Nat) : Bool { x >= y };\n\n  /// General purpose comparison function for `Nat`. Returns the `Order` (\n  /// either `#less`, `#equal`, or `#greater`) of comparing `x` with `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.compare(2, 3) // => #less\n  /// ```\n  ///\n  /// This function can be used as value for a high order function, such as a sort function.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.sort([2, 3, 1], Nat.compare) // => [1, 2, 3]\n  /// ```\n  public func compare(x : Nat, y : Nat) : { #less; #equal; #greater } {\n    if (x < y) { #less } else if (x == y) { #equal } else { #greater }\n  };\n\n  /// Returns the sum of `x` and `y`, `x + y`. This operator will never overflow\n  /// because `Nat` is infinite precision.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.add(1, 2); // => 3\n  /// 1 + 2 // => 3\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft([2, 3, 1], 0, Nat.add) // => 6\n  /// ```\n  public func add(x : Nat, y : Nat) : Nat { x + y };\n\n  /// Returns the difference of `x` and `y`, `x - y`.\n  /// Traps on underflow below `0`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.sub(2, 1); // => 1\n  /// // Add a type annotation to avoid a warning about the subtraction\n  /// 2 - 1 : Nat // => 1\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft([2, 3, 1], 10, Nat.sub) // => 4\n  /// ```\n  public func sub(x : Nat, y : Nat) : Nat { x - y };\n\n  /// Returns the product of `x` and `y`, `x * y`. This operator will never\n  /// overflow because `Nat` is infinite precision.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.mul(2, 3); // => 6\n  /// 2 * 3 // => 6\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft([2, 3, 1], 1, Nat.mul) // => 6\n  /// ```\n  public func mul(x : Nat, y : Nat) : Nat { x * y };\n\n  /// Returns the unsigned integer division of `x` by `y`,  `x / y`.\n  /// Traps when `y` is zero.\n  ///\n  /// The quotient is rounded down, which is equivalent to truncating the\n  /// decimal places of the quotient.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.div(6, 2); // => 3\n  /// 6 / 2 // => 3\n  /// ```\n  ///\n\n  public func div(x : Nat, y : Nat) : Nat { x / y };\n\n  /// Returns the remainder of unsigned integer division of `x` by `y`,  `x % y`.\n  /// Traps when `y` is zero.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.rem(6, 4); // => 2\n  /// 6 % 4 // => 2\n  /// ```\n  ///\n\n  public func rem(x : Nat, y : Nat) : Nat { x % y };\n\n  /// Returns `x` to the power of `y`, `x ** y`. Traps when `y > 2^32`. This operator\n  /// will never overflow because `Nat` is infinite precision.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.pow(2, 3); // => 8\n  /// 2 ** 3 // => 8\n  /// ```\n  ///\n\n  public func pow(x : Nat, y : Nat) : Nat { x ** y };\n\n  /// Returns the (conceptual) bitwise shift left of `x` by `y`, `x * (2 ** y)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.bitshiftLeft(1, 3); // => 8\n  /// ```\n  ///\n\n  public func bitshiftLeft(x : Nat, y : Nat32) : Nat { Prim.shiftLeft(x, y) };\n\n  /// Returns the (conceptual) bitwise shift right of `x` by `y`, `x / (2 ** y)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat.bitshiftRight(8, 3); // => 1\n  /// ```\n  ///\n\n  public func bitshiftRight(x : Nat, y : Nat32) : Nat { Prim.shiftRight(x, y) };\n\n}\n"},"Nat8.mo":{"content":"/// Provides utility functions on 8-bit unsigned integers.\n///\n/// :::note\n/// Most operations on integer numbers (e.g. addition) are available as built-in operators (e.g. `1 + 1`).\n/// This module provides equivalent functions and `Text` conversion.\n/// :::\n///\n/// :::info Function form for higher-order use\n///\n/// Several arithmetic and comparison functions (e.g. `add`, `sub`, `equal`, `less`, `pow`) are defined in this module to enable their use as first-class function values, which is not possible with operators like `+`, `-`, `==`, etc., in Motoko. This allows you to pass these operations to higher-order functions such as `map`, `foldLeft`, or `sort`.\n/// :::\n///\n/// Import from the base library to use this module.\n///\n/// ```motoko name=import\n/// import Nat8 \"mo:base/Nat8\";\n/// ```\nimport Nat \"Nat\";\nimport Prim \"mo:⛔\";\n\nmodule {\n\n  /// 8-bit natural numbers.\n  public type Nat8 = Prim.Types.Nat8;\n\n  /// Maximum 8-bit natural number. `2 ** 8 - 1`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.maximumValue; // => 255 : Nat8\n  /// ```\n  public let maximumValue = 255 : Nat8;\n\n  /// Converts an 8-bit unsigned integer to an unsigned integer with infinite precision.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.toNat(123); // => 123 : Nat\n  /// ```\n  public let toNat : Nat8 -> Nat = Prim.nat8ToNat;\n\n  /// Converts an unsigned integer with infinite precision to an 8-bit unsigned integer.\n  ///\n  /// Traps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.fromNat(123); // => 123 : Nat8\n  /// ```\n  public let fromNat : Nat -> Nat8 = Prim.natToNat8;\n\n  /// Converts a 16-bit unsigned integer to a 8-bit unsigned integer.\n  ///\n  /// Traps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.fromNat16(123); // => 123 : Nat8\n  /// ```\n  public let fromNat16 : Nat16 -> Nat8 = Prim.nat16ToNat8;\n\n  /// Converts an 8-bit unsigned integer to a 16-bit unsigned integer.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.toNat16(123); // => 123 : Nat16\n  /// ```\n  public let toNat16 : Nat8 -> Nat16 = Prim.nat8ToNat16;\n\n  /// Converts a signed integer with infinite precision to an 8-bit unsigned integer.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.fromIntWrap(123); // => 123 : Nat8\n  /// ```\n  public let fromIntWrap : Int -> Nat8 = Prim.intToNat8Wrap;\n\n  /// Converts `x` to its textual representation.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.toText(123); // => \"123\" : Text\n  /// ```\n  public func toText(x : Nat8) : Text {\n    Nat.toText(toNat(x))\n  };\n\n  /// Returns the minimum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.min(123, 200); // => 123 : Nat8\n  /// ```\n  public func min(x : Nat8, y : Nat8) : Nat8 {\n    if (x < y) { x } else { y }\n  };\n\n  /// Returns the maximum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.max(123, 200); // => 200 : Nat8\n  /// ```\n  public func max(x : Nat8, y : Nat8) : Nat8 {\n    if (x < y) { y } else { x }\n  };\n\n  /// Equality function for Nat8 types.\n  /// This is equivalent to `x == y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.equal(1, 1); // => true\n  /// (1 : Nat8) == (1 : Nat8) // => true\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Buffer \"mo:base/Buffer\";\n  ///\n  /// let buffer1 = Buffer.Buffer<Nat8>(3);\n  /// let buffer2 = Buffer.Buffer<Nat8>(3);\n  /// Buffer.equal(buffer1, buffer2, Nat8.equal) // => true\n  /// ```\n  public func equal(x : Nat8, y : Nat8) : Bool { x == y };\n\n  /// Inequality function for Nat8 types.\n  /// This is equivalent to `x != y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.notEqual(1, 2); // => true\n  /// (1 : Nat8) != (2 : Nat8) // => true\n  /// ```\n  ///\n\n  public func notEqual(x : Nat8, y : Nat8) : Bool { x != y };\n\n  /// \"Less than\" function for Nat8 types.\n  /// This is equivalent to `x < y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.less(1, 2); // => true\n  /// (1 : Nat8) < (2 : Nat8) // => true\n  /// ```\n  ///\n\n  public func less(x : Nat8, y : Nat8) : Bool { x < y };\n\n  /// \"Less than or equal\" function for Nat8 types.\n  /// This is equivalent to `x <= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat.lessOrEqual(1, 2); // => true\n  /// 1 <= 2 // => true\n  /// ```\n  ///\n\n  public func lessOrEqual(x : Nat8, y : Nat8) : Bool { x <= y };\n\n  /// \"Greater than\" function for Nat8 types.\n  /// This is equivalent to `x > y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.greater(2, 1); // => true\n  /// (2 : Nat8) > (1 : Nat8) // => true\n  /// ```\n  ///\n\n  public func greater(x : Nat8, y : Nat8) : Bool { x > y };\n\n  /// \"Greater than or equal\" function for Nat8 types.\n  /// This is equivalent to `x >= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.greaterOrEqual(2, 1); // => true\n  /// (2 : Nat8) >= (1 : Nat8) // => true\n  /// ```\n  ///\n\n  public func greaterOrEqual(x : Nat8, y : Nat8) : Bool { x >= y };\n\n  /// General purpose comparison function for `Nat8`. Returns the `Order` (\n  /// either `#less`, `#equal`, or `#greater`) of comparing `x` with `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.compare(2, 3) // => #less\n  /// ```\n  ///\n  /// This function can be used as value for a high order function, such as a sort function.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.sort([2, 3, 1] : [Nat8], Nat8.compare) // => [1, 2, 3]\n  /// ```\n  public func compare(x : Nat8, y : Nat8) : { #less; #equal; #greater } {\n    if (x < y) { #less } else if (x == y) { #equal } else { #greater }\n  };\n\n  /// Returns the sum of `x` and `y`, `x + y`.\n  /// Traps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.add(1, 2); // => 3\n  /// (1 : Nat8) + (2 : Nat8) // => 3\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Nat8, Nat8>([2, 3, 1], 0, Nat8.add) // => 6\n  /// ```\n  public func add(x : Nat8, y : Nat8) : Nat8 { x + y };\n\n  /// Returns the difference of `x` and `y`, `x - y`.\n  /// Traps on underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.sub(2, 1); // => 1\n  /// (2 : Nat8) - (1 : Nat8) // => 1\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Nat8, Nat8>([2, 3, 1], 20, Nat8.sub) // => 14\n  /// ```\n  public func sub(x : Nat8, y : Nat8) : Nat8 { x - y };\n\n  /// Returns the product of `x` and `y`, `x * y`.\n  /// Traps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.mul(2, 3); // => 6\n  /// (2 : Nat8) * (3 : Nat8) // => 6\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Nat8, Nat8>([2, 3, 1], 1, Nat8.mul) // => 6\n  /// ```\n  public func mul(x : Nat8, y : Nat8) : Nat8 { x * y };\n\n  /// Returns the quotient of `x` divided by `y`, `x / y`.\n  /// Traps when `y` is zero.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.div(6, 2); // => 3\n  /// (6 : Nat8) / (2 : Nat8) // => 3\n  /// ```\n  ///\n\n  public func div(x : Nat8, y : Nat8) : Nat8 { x / y };\n\n  /// Returns the remainder of `x` divided by `y`, `x % y`.\n  /// Traps when `y` is zero.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.rem(6, 4); // => 2\n  /// (6 : Nat8) % (4 : Nat8) // => 2\n  /// ```\n  ///\n\n  public func rem(x : Nat8, y : Nat8) : Nat8 { x % y };\n\n  /// Returns `x` to the power of `y`, `x ** y`.\n  /// Traps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.pow(2, 3); // => 8\n  /// (2 : Nat8) ** (3 : Nat8) // => 8\n  /// ```\n  ///\n\n  public func pow(x : Nat8, y : Nat8) : Nat8 { x ** y };\n\n  /// Returns the bitwise negation of `x`, `^x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitnot(0); // => 255\n  /// ^(0 : Nat8) // => 255\n  /// ```\n  ///\n\n  public func bitnot(x : Nat8) : Nat8 { ^x };\n\n  /// Returns the bitwise and of `x` and `y`, `x & y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitand(3, 2); // => 2\n  /// (3 : Nat8) & (2 : Nat8) // => 2\n  /// ```\n  ///\n\n  public func bitand(x : Nat8, y : Nat8) : Nat8 { x & y };\n\n  /// Returns the bitwise or of `x` and `y`, `x | y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitor(3, 2); // => 3\n  /// (3 : Nat8) | (2 : Nat8) // => 3\n  /// ```\n  ///\n\n  public func bitor(x : Nat8, y : Nat8) : Nat8 { x | y };\n\n  /// Returns the bitwise exclusive or of `x` and `y`, `x ^ y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitxor(3, 2); // => 1\n  /// (3 : Nat8) ^ (2 : Nat8) // => 1\n  /// ```\n  ///\n\n  public func bitxor(x : Nat8, y : Nat8) : Nat8 { x ^ y };\n\n  /// Returns the bitwise shift left of `x` by `y`, `x << y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitshiftLeft(1, 2); // => 4\n  /// (1 : Nat8) << (2 : Nat8) // => 4\n  /// ```\n  ///\n\n  public func bitshiftLeft(x : Nat8, y : Nat8) : Nat8 { x << y };\n\n  /// Returns the bitwise shift right of `x` by `y`, `x >> y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitshiftRight(4, 2); // => 1\n  /// (4 : Nat8) >> (2 : Nat8) // => 1\n  /// ```\n  ///\n\n  public func bitshiftRight(x : Nat8, y : Nat8) : Nat8 { x >> y };\n\n  /// Returns the bitwise rotate left of `x` by `y`, `x <<> y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitrotLeft(128, 1); // => 1\n  /// (128 : Nat8) <<> (1 : Nat8) // => 1\n  /// ```\n  ///\n\n  public func bitrotLeft(x : Nat8, y : Nat8) : Nat8 { x <<> y };\n\n  /// Returns the bitwise rotate right of `x` by `y`, `x <>> y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.bitrotRight(1, 1); // => 128\n  /// (1 : Nat8) <>> (1 : Nat8) // => 128\n  /// ```\n  ///\n\n  public func bitrotRight(x : Nat8, y : Nat8) : Nat8 { x <>> y };\n\n  /// Returns the value of bit `p mod 8` in `x`, `(x & 2^(p mod 8)) == 2^(p mod 8)`.\n  /// This is equivalent to checking if the `p`-th bit is set in `x`, using 0 indexing.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bittest(5, 2); // => true\n  /// ```\n  public func bittest(x : Nat8, p : Nat) : Bool {\n    Prim.btstNat8(x, Prim.natToNat8(p))\n  };\n\n  /// Returns the value of setting bit `p mod 8` in `x` to `1`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitset(5, 1); // => 7\n  /// ```\n  public func bitset(x : Nat8, p : Nat) : Nat8 {\n    x | (1 << Prim.natToNat8(p))\n  };\n\n  /// Returns the value of clearing bit `p mod 8` in `x` to `0`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitclear(5, 2); // => 1\n  /// ```\n  public func bitclear(x : Nat8, p : Nat) : Nat8 {\n    x & ^(1 << Prim.natToNat8(p))\n  };\n\n  /// Returns the value of flipping bit `p mod 8` in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitflip(5, 2); // => 1\n  /// ```\n  public func bitflip(x : Nat8, p : Nat) : Nat8 {\n    x ^ (1 << Prim.natToNat8(p))\n  };\n\n  /// Returns the count of non-zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitcountNonZero(5); // => 2\n  /// ```\n  public let bitcountNonZero : (x : Nat8) -> Nat8 = Prim.popcntNat8;\n\n  /// Returns the count of leading zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitcountLeadingZero(5); // => 5\n  /// ```\n  public let bitcountLeadingZero : (x : Nat8) -> Nat8 = Prim.clzNat8;\n\n  /// Returns the count of trailing zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Nat8.bitcountTrailingZero(6); // => 1\n  /// ```\n  public let bitcountTrailingZero : (x : Nat8) -> Nat8 = Prim.ctzNat8;\n\n  /// Returns the sum of `x` and `y`, `x +% y`. Wraps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.addWrap(230, 26); // => 0\n  /// (230 : Nat8) +% (26 : Nat8) // => 0\n  /// ```\n  ///\n\n  public func addWrap(x : Nat8, y : Nat8) : Nat8 { x +% y };\n\n  /// Returns the difference of `x` and `y`, `x -% y`. Wraps on underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.subWrap(0, 1); // => 255\n  /// (0 : Nat8) -% (1 : Nat8) // => 255\n  /// ```\n\n  public func subWrap(x : Nat8, y : Nat8) : Nat8 { x -% y };\n\n  /// Returns the product of `x` and `y`, `x *% y`. Wraps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.mulWrap(230, 26); // => 92\n  /// (230 : Nat8) *% (26 : Nat8) // => 92\n  /// ```\n  ///\n\n  public func mulWrap(x : Nat8, y : Nat8) : Nat8 { x *% y };\n\n  /// Returns `x` to the power of `y`, `x **% y`. Wraps on overflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// ignore Nat8.powWrap(2, 8); // => 0\n  /// (2 : Nat8) **% (8 : Nat8) // => 0\n  /// ```\n  ///\n\n  public func powWrap(x : Nat8, y : Nat8) : Nat8 { x **% y };\n\n}\n"},"Prelude.mo":{"content":"/// This prelude file proposes standard library features that _may_\n/// belong in the _language_ (compiler-internal) prelude sometime, after\n/// some further experience and discussion.  Until then, they live here.\n\nimport Debug \"Debug\";\n\nmodule {\n\n  /// :::warning\n  /// Not yet implemented\n  /// :::\n  ///\n  /// Mark incomplete code with the `nyi` and `xxx` functions.\n  ///\n  /// Each have calls that are well-typed in all typing contexts, which\n  /// trap in all execution contexts.\n  public func nyi() : None {\n    Debug.trap(\"Prelude.nyi()\")\n  };\n\n  public func xxx() : None {\n    Debug.trap(\"Prelude.xxx()\")\n  };\n\n  /// Mark unreachable code with the `unreachable` function.\n  ///\n  /// Calls are well-typed in all typing contexts, and they\n  /// trap in all execution contexts.\n  public func unreachable() : None {\n    Debug.trap(\"Prelude.unreachable()\")\n  };\n\n}\n"},"Int8.mo":{"content":"/// Provides utility functions on 8-bit signed integers.\n///\n/// :::info Function form for higher-order use\n///\n/// Several arithmetic and comparison functions (e.g. `add`, `sub`, `bitor`, `bitand`, `pow`) are defined in this module to enable their use as first-class function values, which is not possible with operators like `+`, `-`, `==`, etc., in Motoko. This allows you to pass these operations to higher-order functions such as `map`, `foldLeft`, or `sort`.\n/// :::\n///\n/// :::note\n/// Most operations are available as built-in operators (e.g. `1 + 1`).\n/// :::\n/// Import from the base library to use this module.\n///\n/// ```motoko name=import\n/// import Int8 \"mo:base/Int8\";\n/// ```\nimport Int \"Int\";\nimport Prim \"mo:⛔\";\n\nmodule {\n\n  /// 8-bit signed integers.\n  public type Int8 = Prim.Types.Int8;\n\n  /// Minimum 8-bit integer value, `-2 ** 7`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.minimumValue // => -128\n  /// ```\n  public let minimumValue = -128 : Int8;\n\n  /// Maximum 8-bit integer value, `+2 ** 7 - 1`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.maximumValue // => +127\n  /// ```\n  public let maximumValue = 127 : Int8;\n\n  /// Converts an 8-bit signed integer to a signed integer with infinite precision.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.toInt(123) // => 123 : Int\n  /// ```\n  public let toInt : Int8 -> Int = Prim.int8ToInt;\n\n  /// Converts a signed integer with infinite precision to an 8-bit signed integer.\n  ///\n  /// Traps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.fromInt(123) // => +123 : Int8\n  /// ```\n  public let fromInt : Int -> Int8 = Prim.intToInt8;\n\n  /// Converts a signed integer with infinite precision to an 8-bit signed integer.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.fromIntWrap(-123) // => -123 : Int\n  /// ```\n  public let fromIntWrap : Int -> Int8 = Prim.intToInt8Wrap;\n\n  /// Converts a 16-bit signed integer to an 8-bit signed integer.\n  ///\n  /// Traps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.fromInt16(123) // => +123 : Int8\n  /// ```\n  public let fromInt16 : Int16 -> Int8 = Prim.int16ToInt8;\n\n  /// Converts an 8-bit signed integer to a 16-bit signed integer.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.toInt16(123) // => +123 : Int16\n  /// ```\n  public let toInt16 : Int8 -> Int16 = Prim.int8ToInt16;\n\n  /// Converts an unsigned 8-bit integer to a signed 8-bit integer.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.fromNat8(123) // => +123 : Int8\n  /// ```\n  public let fromNat8 : Nat8 -> Int8 = Prim.nat8ToInt8;\n\n  /// Converts a signed 8-bit integer to an unsigned 8-bit integer.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.toNat8(-1) // => 255 : Nat8 // underflow\n  /// ```\n  public let toNat8 : Int8 -> Nat8 = Prim.int8ToNat8;\n\n  /// Converts an integer number to its textual representation.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.toText(-123) // => \"-123\"\n  /// ```\n  public func toText(x : Int8) : Text {\n    Int.toText(toInt(x))\n  };\n\n  /// Returns the absolute value of `x`.\n  ///\n  /// Traps when `x == -2 ** 7` (the minimum `Int8` value).\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.abs(-123) // => +123\n  /// ```\n  public func abs(x : Int8) : Int8 {\n    fromInt(Int.abs(toInt(x)))\n  };\n\n  /// Returns the minimum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.min(+2, -3) // => -3\n  /// ```\n  public func min(x : Int8, y : Int8) : Int8 {\n    if (x < y) { x } else { y }\n  };\n\n  /// Returns the maximum of `x` and `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.max(+2, -3) // => +2\n  /// ```\n  public func max(x : Int8, y : Int8) : Int8 {\n    if (x < y) { y } else { x }\n  };\n\n  /// Equality function for Int8 types.\n  /// This is equivalent to `x == y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.equal(-1, -1); // => true\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Buffer \"mo:base/Buffer\";\n  ///\n  /// let buffer1 = Buffer.Buffer<Int8>(1);\n  /// buffer1.add(-3);\n  /// let buffer2 = Buffer.Buffer<Int8>(1);\n  /// buffer2.add(-3);\n  /// Buffer.equal(buffer1, buffer2, Int8.equal) // => true\n  /// ```\n  public func equal(x : Int8, y : Int8) : Bool { x == y };\n\n  /// Inequality function for Int8 types.\n  /// This is equivalent to `x != y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.notEqual(-1, -2); // => true\n  /// ```\n  ///\n\n  public func notEqual(x : Int8, y : Int8) : Bool { x != y };\n\n  /// \"Less than\" function for Int8 types.\n  /// This is equivalent to `x < y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.less(-2, 1); // => true\n  /// ```\n  ///\n\n  public func less(x : Int8, y : Int8) : Bool { x < y };\n\n  /// \"Less than or equal\" function for Int8 types.\n  /// This is equivalent to `x <= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.lessOrEqual(-2, -2); // => true\n  /// ```\n  ///\n\n  public func lessOrEqual(x : Int8, y : Int8) : Bool { x <= y };\n\n  /// \"Greater than\" function for Int8 types.\n  /// This is equivalent to `x > y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.greater(-2, -3); // => true\n  /// ```\n  ///\n\n  public func greater(x : Int8, y : Int8) : Bool { x > y };\n\n  /// \"Greater than or equal\" function for Int8 types.\n  /// This is equivalent to `x >= y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.greaterOrEqual(-2, -2); // => true\n  /// ```\n  ///\n\n  public func greaterOrEqual(x : Int8, y : Int8) : Bool { x >= y };\n\n  /// General-purpose comparison function for `Int8`. Returns the `Order` (\n  /// either `#less`, `#equal`, or `#greater`) of comparing `x` with `y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.compare(-3, 2) // => #less\n  /// ```\n  ///\n  /// This function can be used as value for a high order function, such as a sort function.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.sort([1, -2, -3] : [Int8], Int8.compare) // => [-3, -2, 1]\n  /// ```\n  public func compare(x : Int8, y : Int8) : { #less; #equal; #greater } {\n    if (x < y) { #less } else if (x == y) { #equal } else { #greater }\n  };\n\n  /// Returns the negation of `x`, `-x`.\n  ///\n  /// Traps on overflow, i.e. for `neg(-2 ** 7)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.neg(123) // => -123\n  /// ```\n  ///\n\n  public func neg(x : Int8) : Int8 { -x };\n\n  /// Returns the sum of `x` and `y`, `x + y`.\n  ///\n  /// Traps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.add(100, 23) // => +123\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Int8, Int8>([1, -2, -3], 0, Int8.add) // => -4\n  /// ```\n  public func add(x : Int8, y : Int8) : Int8 { x + y };\n\n  /// Returns the difference of `x` and `y`, `x - y`.\n  ///\n  /// Traps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.sub(123, 23) // => +100\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Int8, Int8>([1, -2, -3], 0, Int8.sub) // => 4\n  /// ```\n  public func sub(x : Int8, y : Int8) : Int8 { x - y };\n\n  /// Returns the product of `x` and `y`, `x * y`.\n  ///\n  /// Traps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.mul(12, 10) // => +120\n  /// ```\n  ///\n\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// import Array \"mo:base/Array\";\n  /// Array.foldLeft<Int8, Int8>([1, -2, -3], 1, Int8.mul) // => 6\n  /// ```\n  public func mul(x : Int8, y : Int8) : Int8 { x * y };\n\n  /// Returns the signed integer division of `x` by `y`, `x / y`.\n  /// Rounds the quotient towards zero, which is the same as truncating the decimal places of the quotient.\n  ///\n  /// Traps when `y` is zero.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.div(123, 10) // => +12\n  /// ```\n  ///\n\n  public func div(x : Int8, y : Int8) : Int8 { x / y };\n\n  /// Returns the remainder of the signed integer division of `x` by `y`, `x % y`,\n  /// which is defined as `x - x / y * y`.\n  ///\n  /// Traps when `y` is zero.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.rem(123, 10) // => +3\n  /// ```\n  ///\n\n  public func rem(x : Int8, y : Int8) : Int8 { x % y };\n\n  /// Returns `x` to the power of `y`, `x ** y`.\n  ///\n  /// Traps on overflow/underflow and when `y < 0 or y >= 8`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.pow(2, 6) // => +64\n  /// ```\n  ///\n\n  public func pow(x : Int8, y : Int8) : Int8 { x ** y };\n\n  /// Returns the bitwise negation of `x`, `^x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitnot(-16 /* 0xf0 */) // => +15 // 0x0f\n  /// ```\n  ///\n\n  public func bitnot(x : Int8) : Int8 { ^x };\n\n  /// Returns the bitwise \"and\" of `x` and `y`, `x & y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitand(0x1f, 0x70) // => +16 // 0x10\n  /// ```\n  ///\n\n  public func bitand(x : Int8, y : Int8) : Int8 { x & y };\n\n  /// Returns the bitwise \"or\" of `x` and `y`, `x | y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitor(0x0f, 0x70) // => +127 // 0x7f\n  /// ```\n  ///\n\n  public func bitor(x : Int8, y : Int8) : Int8 { x | y };\n\n  /// Returns the bitwise \"exclusive or\" of `x` and `y`, `x ^ y`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitxor(0x70, 0x7f) // => +15 // 0x0f\n  /// ```\n  ///\n\n  public func bitxor(x : Int8, y : Int8) : Int8 { x ^ y };\n\n  /// Returns the bitwise left shift of `x` by `y`, `x << y`.\n  /// The right bits of the shift filled with zeros.\n  /// Left-overflowing bits, including the sign bit, are discarded.\n  ///\n  /// For `y >= 8`, the semantics is the same as for `bitshiftLeft(x, y % 8)`.\n  /// For `y < 0`,  the semantics is the same as for `bitshiftLeft(x, y + y % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitshiftLeft(1, 4) // => +16 // 0x10 equivalent to `2 ** 4`.\n  /// ```\n  ///\n\n  public func bitshiftLeft(x : Int8, y : Int8) : Int8 { x << y };\n\n  /// Returns the signed bitwise right shift of `x` by `y`, `x >> y`.\n  /// The sign bit is retained and the left side is filled with the sign bit.\n  /// Right-underflowing bits are discarded, i.e. not rotated to the left side.\n  ///\n  /// For `y >= 8`, the semantics is the same as for `bitshiftRight(x, y % 8)`.\n  /// For `y < 0`,  the semantics is the same as for `bitshiftRight (x, y + y % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitshiftRight(64, 4) // => +4 // equivalent to `64 / (2 ** 4)`\n  /// ```\n  ///\n\n  public func bitshiftRight(x : Int8, y : Int8) : Int8 { x >> y };\n\n  /// Returns the bitwise left rotatation of `x` by `y`, `x <<> y`.\n  /// Each left-overflowing bit is inserted again on the right side.\n  /// The sign bit is rotated like other bits, i.e. the rotation interprets the number as unsigned.\n  ///\n  /// Changes the direction of rotation for negative `y`.\n  /// For `y >= 8`, the semantics is the same as for `bitrotLeft(x, y % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitrotLeft(0x11 /* 0b0001_0001 */, 2) // => +68 // 0b0100_0100 == 0x44.\n  /// ```\n  ///\n\n  public func bitrotLeft(x : Int8, y : Int8) : Int8 { x <<> y };\n\n  /// Returns the bitwise right rotation of `x` by `y`, `x <>> y`.\n  /// Each right-underflowing bit is inserted again on the right side.\n  /// The sign bit is rotated like other bits, i.e. the rotation interprets the number as unsigned.\n  ///\n  /// Changes the direction of rotation for negative `y`.\n  /// For `y >= 8`, the semantics is the same as for `bitrotRight(x, y % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitrotRight(0x11 /* 0b0001_0001 */, 1) // => -120 // 0b1000_1000 == 0x88.\n  /// ```\n  ///\n\n  public func bitrotRight(x : Int8, y : Int8) : Int8 { x <>> y };\n\n  /// Returns the value of bit `p` in `x`, `x & 2**p == 2**p`.\n  /// If `p >= 8`, the semantics is the same as for `bittest(x, p % 8)`.\n  /// This is equivalent to checking if the `p`-th bit is set in `x`, using 0 indexing.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bittest(64, 6) // => true\n  /// ```\n  public func bittest(x : Int8, p : Nat) : Bool {\n    Prim.btstInt8(x, Prim.intToInt8(p))\n  };\n\n  /// Returns the value of setting bit `p` in `x` to `1`.\n  /// If `p >= 8`, the semantics is the same as for `bitset(x, p % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitset(0, 6) // => +64\n  /// ```\n  public func bitset(x : Int8, p : Nat) : Int8 {\n    x | (1 << Prim.intToInt8(p))\n  };\n\n  /// Returns the value of clearing bit `p` in `x` to `0`.\n  /// If `p >= 8`, the semantics is the same as for `bitclear(x, p % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitclear(-1, 6) // => -65\n  /// ```\n  public func bitclear(x : Int8, p : Nat) : Int8 {\n    x & ^(1 << Prim.intToInt8(p))\n  };\n\n  /// Returns the value of flipping bit `p` in `x`.\n  /// If `p >= 8`, the semantics is the same as for `bitclear(x, p % 8)`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitflip(127, 6) // => +63\n  /// ```\n  public func bitflip(x : Int8, p : Nat) : Int8 {\n    x ^ (1 << Prim.intToInt8(p))\n  };\n\n  /// Returns the count of non-zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitcountNonZero(0x0f) // => +4\n  /// ```\n  public let bitcountNonZero : (x : Int8) -> Int8 = Prim.popcntInt8;\n\n  /// Returns the count of leading zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitcountLeadingZero(0x08) // => +4\n  /// ```\n  public let bitcountLeadingZero : (x : Int8) -> Int8 = Prim.clzInt8;\n\n  /// Returns the count of trailing zero bits in `x`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.bitcountTrailingZero(0x10) // => +4\n  /// ```\n  public let bitcountTrailingZero : (x : Int8) -> Int8 = Prim.ctzInt8;\n\n  /// Returns the sum of `x` and `y`, `x +% y`.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.addWrap(2 ** 6, 2 ** 6) // => -128 // overflow\n  /// ```\n  ///\n\n  public func addWrap(x : Int8, y : Int8) : Int8 { x +% y };\n\n  /// Returns the difference of `x` and `y`, `x -% y`.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.subWrap(-2 ** 7, 1) // => +127 // underflow\n  /// ```\n  ///\n\n  public func subWrap(x : Int8, y : Int8) : Int8 { x -% y };\n\n  /// Returns the product of `x` and `y`, `x *% y`. Wraps on overflow.\n  ///\n  /// Wraps on overflow/underflow.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.mulWrap(2 ** 4, 2 ** 4) // => 0 // overflow\n  /// ```\n  ///\n\n  public func mulWrap(x : Int8, y : Int8) : Int8 { x *% y };\n\n  /// Returns `x` to the power of `y`, `x **% y`.\n  ///\n  /// Wraps on overflow/underflow.\n  /// Traps if `y < 0 or y >= 8`.\n  ///\n  /// Example:\n  /// ```motoko include=import\n  /// Int8.powWrap(2, 7) // => -128 // overflow\n  /// ```\n  ///\n\n  public func powWrap(x : Int8, y : Int8) : Int8 { x **% y };\n\n}\n"},"Heap.mo":{"content":"/// Class `Heap<X>` provides a priority queue of elements of type `X`.\n///\n/// The class wraps a purely-functional implementation based on a leftist heap.\n///\n/// :::note Constructor details\n/// The constructor takes in a comparison function `compare` that defines the ordering between elements of type `X`. Most primitive types have a default version of this comparison function defined in their modules (e.g. `Nat.compare`). The runtime analysis in this documentation assumes that the `compare` function runs in `O(1)` time and space.\n/// :::\n///\n/// Example:\n///\n/// ```motoko name=initialize\n/// import Heap \"mo:base/Heap\";\n/// import Text \"mo:base/Text\";\n///\n/// let heap = Heap.Heap<Text>(Text.compare);\n/// ```\n///\n/// | Runtime   | Space     |\n/// |-----------|-----------|\n/// | `O(1)`    | `O(1)`    |\n\nimport O \"Order\";\nimport P \"Prelude\";\nimport L \"List\";\nimport I \"Iter\";\n\nmodule {\n\n  public type Tree<X> = ?(Int, X, Tree<X>, Tree<X>);\n\n  public class Heap<X>(compare : (X, X) -> O.Order) {\n    var heap : Tree<X> = null;\n\n    /// Inserts an element into the heap.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"apple\");\n    /// heap.peekMin() // => ?\"apple\"\n    /// ```\n    ///\n    /// | Runtime   | Space     |\n    /// |-----------|-----------|\n    /// | `O(1)`    | `O(1)`    |\n    public func put(x : X) {\n      heap := merge(heap, ?(1, x, null, null), compare)\n    };\n\n    /// Return the minimal element in the heap, or `null` if the heap is empty.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"apple\");\n    /// heap.put(\"banana\");\n    /// heap.put(\"cantaloupe\");\n    /// heap.peekMin() // => ?\"apple\"\n    /// ```\n    ///\n    /// | Runtime   | Space     |\n    /// |-----------|-----------|\n    /// | `O(1)`    | `O(1)`    |\n    public func peekMin() : ?X {\n      switch heap {\n        case (null) { null };\n        case (?(_, x, _, _)) { ?x }\n      }\n    };\n\n    /// Delete the minimal element in the heap, if it exists.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"apple\");\n    /// heap.put(\"banana\");\n    /// heap.put(\"cantaloupe\");\n    /// heap.deleteMin();\n    /// heap.peekMin(); // => ?\"banana\"\n    /// ```\n    ///\n    /// | Runtime      | Space       |\n    /// |--------------|-------------|\n    /// | `O(log(n))`  | `O(log(n))` |\n    public func deleteMin() {\n      switch heap {\n        case null {};\n        case (?(_, _, a, b)) { heap := merge(a, b, compare) }\n      }\n    };\n\n    /// Delete and return the minimal element in the heap, if it exists.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"apple\");\n    /// heap.put(\"banana\");\n    /// heap.put(\"cantaloupe\");\n    /// heap.removeMin(); // => ?\"apple\"\n    /// ```\n    ///\n    /// | Runtime      | Space       |\n    /// |--------------|-------------|\n    /// | `O(log(n))`  | `O(log(n))` |\n    public func removeMin() : (minElement : ?X) {\n      switch heap {\n        case null { null };\n        case (?(_, x, a, b)) {\n          heap := merge(a, b, compare);\n          ?x\n        }\n      }\n    };\n\n    /// Return a snapshot of the internal functional tree representation as sharable data.\n    /// The returned tree representation is not affected by subsequent changes of the `Heap` instance.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"banana\");\n    /// heap.share();\n    /// ```\n    ///\n    /// Useful for storing the heap as a stable variable, pretty-printing, and sharing it across async function calls,\n    /// i.e. passing it in async arguments or async results.\n    ///\n    /// | Runtime   | Space     |\n    /// |-----------|-----------|\n    /// | `O(1)`    | `O(1)`    |\n    public func share() : Tree<X> {\n      heap\n    };\n\n    /// Rewraps a snapshot of a heap (obtained by `share()`) in a `Heap` instance.\n    /// The wrapping instance must be initialized with the same `compare`\n    /// function that created the snapshot.\n    ///\n    /// Example:\n    /// ```motoko include=initialize\n    /// heap.put(\"apple\");\n    /// heap.put(\"banana\");\n    /// let snapshot = heap.share();\n    /// let heapCopy = Heap.Heap<Text>(Text.compare);\n    /// heapCopy.unsafeUnshare(snapshot);\n    /// heapCopy.peekMin() // => ?\"apple\"\n    /// ```\n    ///\n    /// Useful for loading a stored heap from a stable variable or accesing a heap\n    /// snapshot passed from an async function call.\n    ///\n    /// | Runtime   | Space     |\n    /// |-----------|-----------|\n    /// | `O(1)`    | `O(1)`    |\n    public func unsafeUnshare(tree : Tree<X>) {\n      heap := tree\n    };\n\n  };\n\n  func rank<X>(heap : Tree<X>) : Int {\n    switch heap {\n      case null { 0 };\n      case (?(r, _, _, _)) { r }\n    }\n  };\n\n  func makeT<X>(x : X, a : Tree<X>, b : Tree<X>) : Tree<X> {\n    if (rank(a) >= rank(b)) {\n      ?(rank(b) + 1, x, a, b)\n    } else {\n      ?(rank(a) + 1, x, b, a)\n    }\n  };\n\n  func merge<X>(h1 : Tree<X>, h2 : Tree<X>, compare : (X, X) -> O.Order) : Tree<X> {\n    switch (h1, h2) {\n      case (null, h) { h };\n      case (h, null) { h };\n      case (?(_, x, a, b), ?(_, y, c, d)) {\n        switch (compare(x, y)) {\n          case (#less) { makeT(x, a, merge(b, h2, compare)) };\n          case _ { makeT(y, c, merge(d, h1, compare)) }\n        }\n      }\n    }\n  };\n\n  /// Returns a new `Heap`, containing all entries given by the iterator `iter`.\n  /// The new map is initialized with the provided `compare` function.\n  ///\n  /// Example:\n  /// ```motoko include=initialize\n  /// let entries = [\"banana\", \"apple\", \"cantaloupe\"];\n  /// let iter = entries.vals();\n  ///\n  /// let newHeap = Heap.fromIter<Text>(iter, Text.compare);\n  /// newHeap.peekMin() // => ?\"apple\"\n  /// ```\n  ///\n  /// | Runtime   | Space     |\n  /// |-----------|-----------|\n  /// | `O(size)` | `O(size)` |\n  public func fromIter<X>(iter : I.Iter<X>, compare : (X, X) -> O.Order) : Heap<X> {\n    let heap = Heap<X>(compare);\n    func build(xs : L.List<Tree<X>>) : Tree<X> {\n      func join(xs : L.List<Tree<X>>) : L.List<Tree<X>> {\n        switch (xs) {\n          case (null) { null };\n          case (?(hd, null)) { ?(hd, null) };\n          case (?(h1, ?(h2, tl))) { ?(merge(h1, h2, compare), join(tl)) }\n        }\n      };\n      switch (xs) {\n        case null { P.unreachable() };\n        case (?(hd, null)) { hd };\n        case _ { build(join(xs)) }\n      }\n    };\n    let list = I.toList(I.map(iter, func(x : X) : Tree<X> { ?(1, x, null, null) }));\n    if (not L.isNil(list)) {\n      let t = build(list);\n      heap.unsafeUnshare(t)\n    };\n    heap\n  };\n\n}\n"},"Float.mo":{"content":"/// Double precision (64-bit) floating-point numbers in IEEE 754 representation.\n///\n/// This module contains common floating-point constants and utility functions.\n///\n/// Notation for special values in the documentation below:\n///\n/// `+inf`: Positive infinity\n///\n/// `-inf`: Negative infinity\n///\n/// `NaN`: \"not a number\" (can have different sign bit values, but `NaN != NaN` regardless of the sign).\n///\n/// :::note\n/// Floating point numbers have limited precision and operations may inherently result in numerical errors.\n/// :::\n///\n/// Examples of numerical errors:\n///   ```motoko\n///   0.1 + 0.1 + 0.1 == 0.3 // => false\n///   ```\n///\n///   ```motoko\n///  1e16 + 1.0 != 1e16 // => false\n///   ```\n///\n///\n/// Advice:\n/// * Floating point number comparisons by `==` or `!=` are discouraged. Instead, it is better to compare\n///   floating-point numbers with a numerical tolerance, called epsilon.\n///\n///   Example:\n///   ```motoko\n///   import Float \"mo:base/Float\";\n///   let x = 0.1 + 0.1 + 0.1;\n///   let y = 0.3;\n///\n///   let epsilon = 1e-6; // This depends on the application case (needs a numerical error analysis).\n///   Float.equalWithin(x, y, epsilon) // => true\n///   ```\n///\n/// * For absolute precision, it is recommend to encode the fraction number as a pair of a `Nat` for the base\n///   and a `Nat` for the exponent (decimal point).\n///\n/// `NaN` sign:\n/// * The `NaN` sign is only applied by `abs`, `neg`, and `copySign`. Other operations can have an arbitrary\n///   sign bit for `NaN` results.\n\nimport Prim \"mo:⛔\";\nimport Int \"Int\";\n\nmodule {\n\n  /// 64-bit floating point number type.\n  public type Float = Prim.Types.Float;\n\n  /// Ratio of the circumference of a circle to its diameter.\n  /// Note: Limited precision.\n  public let pi : Float = 3.14159265358979323846; // taken from musl math.h\n\n  /// Base of the natural logarithm.\n  /// Note: Limited precision.\n  public let e : Float = 2.7182818284590452354; // taken from musl math.h\n\n  /// Determines whether the `number` is a `NaN` (\"not a number\" in the floating point representation).\n  /// Notes:\n  /// * Equality test of `NaN` with itself or another number is always `false`.\n  /// * There exist many internal `NaN` value representations, such as positive and negative `NaN`,\n  ///   signalling and quiet `NaN`s, each with many different bit representations.\n  ///\n  /// Example:\n  /// ```motoko\n  /// import Float \"mo:base/Float\";\n  ///\n  /// Float.isNaN(0.0/0.0) // => true\n  /// ```\n  public func isNaN(number : Float) : Bool {\n    number != number\n  };\n\n  /// Returns the absolute value of `x`.\n  ///\n  /// Special cases:\n  /// ```\n  /// abs(+inf) => +inf\n  /// abs(-inf) => +inf\n  /// abs(-NaN)  => +NaN\n  /// abs(-0.0) => 0.0\n  /// ```\n  ///\n  /// Example:\n  /// ```motoko\n  /// import Float \"mo:base/Float\";\n  ///\n  /// Float.abs(-1.2) // => 1.2\n  /// ```\n  public let abs : (x : Float) -> Float = Prim.floatAbs;\n\n  /// Returns the square root of `x`.\n  ///\n  /// Special cases:\n  /// ```\n  /// sqrt(+inf) => +inf\n  /// sqrt(-0.0) => -0.0\n  /// sqrt(x)    => NaN if x < 0.0\n  /// sqrt(NaN)  => NaN\n  /// ```\n  ///\n  /// Example:\n  /// ```motoko\n  /// import Float \"mo:base/Float\";\n  ///\n  /// Float.sqrt(6.25) // => 2.5\n  /// ```\n  public let sqrt : (x : Float) -> Float = Prim.floatSqrt;\n\n  /// Returns the smallest integral float greater than or equal to `x`.\n  ///\n  /// Special cases:\n  /// ```\n  /// ceil(+inf) => +inf\n  /// ceil(-inf) => -inf\n  /// ceil(NaN)  => NaN\n  /// ceil(0.0)  => 0.0\n  /// ceil(-0.0) => -0.0\n  /// ```\n  ///\n  /// Example:\n  /// ```motoko\n  /// import Float \"mo:base/Float\";\n  ///\n  /// Float.ceil(1.2) // => 2.0\n  /// ```\n  public let ceil : (x : Float) -> Float = Prim.floatCeil;\n\n  /// Returns the largest integral float less than or equal to `x`.\n  ///\n  /// Special cases:\n  /// ```\n  /// floor(+inf) => +inf\n  /// floor(-inf) => -inf\n  /// floor(NaN)  => NaN\n  /// floor(0.0)  => 0.0\