ic-mops 0.8.3 → 0.8.5

package/.mops/base@0.8.3/src/Nat.mo

@@ -0,0 +1,305 @@
+/// Natural numbers with infinite precision.
+///
+/// Most operations on natural numbers (e.g. addition) are available as built-in operators (e.g. `1 + 1`).
+/// This module provides equivalent functions and `Text` conversion.
+///
+/// Import from the base library to use this module.
+/// ```motoko name=import
+/// import Nat "mo:base/Nat";
+/// ```
+
+import Int "Int";
+import Order "Order";
+import Prim "mo:⛔";
+import Char "Char";
+
+module {
+
+  /// Infinite precision natural numbers.
+  public type Nat = Prim.Types.Nat;
+
+  /// Converts a natural number to its textual representation. Textual
+  /// representation _do not_ contain underscores to represent commas.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// Nat.toText 1234 // => "1234"
+  /// ```
+  public func toText(n : Nat) : Text = Int.toText n;
+
+  /// Creates a natural number from its textual representation. Returns `null`
+  /// if the input is not a valid natural number.
+  ///
+  /// Note: The textual representation _must not_ contain underscores.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// Nat.fromText "1234" // => ?1234
+  /// ```
+  public func fromText(text : Text) : ?Nat {
+    if (text == "") {
+      return null
+    };
+    var n = 0;
+    for (c in text.chars()) {
+      if (Char.isDigit(c)) {
+        let charAsNat = Prim.nat32ToNat(Prim.charToNat32(c) -% Prim.charToNat32('0'));
+        n := n * 10 + charAsNat
+      } else {
+        return null
+      }
+    };
+    ?n
+  };
+
+  /// Returns the minimum of `x` and `y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// Nat.min(1, 2) // => 1
+  /// ```
+  public func min(x : Nat, y : Nat) : Nat {
+    if (x < y) { x } else { y }
+  };
+
+  /// Returns the maximum of `x` and `y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// Nat.max(1, 2) // => 2
+  /// ```
+  public func max(x : Nat, y : Nat) : Nat {
+    if (x < y) { y } else { x }
+  };
+
+  /// Equality function for Nat types.
+  /// This is equivalent to `x == y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.equal(1, 1); // => true
+  /// 1 == 1 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `==` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `==`
+  /// as a function value at the moment.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Buffer "mo:base/Buffer";
+  ///
+  /// let buffer1 = Buffer.Buffer<Nat>(3);
+  /// let buffer2 = Buffer.Buffer<Nat>(3);
+  /// Buffer.equal(buffer1, buffer2, Nat.equal) // => true
+  /// ```
+  public func equal(x : Nat, y : Nat) : Bool { x == y };
+
+  /// Inequality function for Nat types.
+  /// This is equivalent to `x != y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.notEqual(1, 2); // => true
+  /// 1 != 2 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `!=` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `!=`
+  /// as a function value at the moment.
+  public func notEqual(x : Nat, y : Nat) : Bool { x != y };
+
+  /// "Less than" function for Nat types.
+  /// This is equivalent to `x < y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.less(1, 2); // => true
+  /// 1 < 2 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `<` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `<`
+  /// as a function value at the moment.
+  public func less(x : Nat, y : Nat) : Bool { x < y };
+
+  /// "Less than or equal" function for Nat types.
+  /// This is equivalent to `x <= y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.lessOrEqual(1, 2); // => true
+  /// 1 <= 2 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `<=` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `<=`
+  /// as a function value at the moment.
+  public func lessOrEqual(x : Nat, y : Nat) : Bool { x <= y };
+
+  /// "Greater than" function for Nat types.
+  /// This is equivalent to `x > y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.greater(2, 1); // => true
+  /// 2 > 1 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `>` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `>`
+  /// as a function value at the moment.
+  public func greater(x : Nat, y : Nat) : Bool { x > y };
+
+  /// "Greater than or equal" function for Nat types.
+  /// This is equivalent to `x >= y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.greaterOrEqual(2, 1); // => true
+  /// 2 >= 1 // => true
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `>=` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `>=`
+  /// as a function value at the moment.
+  public func greaterOrEqual(x : Nat, y : Nat) : Bool { x >= y };
+
+  /// General purpose comparison function for `Nat`. Returns the `Order` (
+  /// either `#less`, `#equal`, or `#greater`) of comparing `x` with `y`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// Nat.compare(2, 3) // => #less
+  /// ```
+  ///
+  /// This function can be used as value for a high order function, such as a sort function.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Array "mo:base/Array";
+  /// Array.sort([2, 3, 1], Nat.compare) // => [1, 2, 3]
+  /// ```
+  public func compare(x : Nat, y : Nat) : { #less; #equal; #greater } {
+    if (x < y) { #less } else if (x == y) { #equal } else { #greater }
+  };
+
+  /// Returns the sum of `x` and `y`, `x + y`. This operator will never overflow
+  /// because `Nat` is infinite precision.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.add(1, 2); // => 3
+  /// 1 + 2 // => 3
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `+` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `+`
+  /// as a function value at the moment.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Array "mo:base/Array";
+  /// Array.foldLeft([2, 3, 1], 0, Nat.add) // => 6
+  /// ```
+  public func add(x : Nat, y : Nat) : Nat { x + y };
+
+  /// Returns the difference of `x` and `y`, `x - y`.
+  /// Traps on underflow below `0`.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.sub(2, 1); // => 1
+  /// // Add a type annotation to avoid a warning about the subtraction
+  /// 2 - 1 : Nat // => 1
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `-` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `-`
+  /// as a function value at the moment.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Array "mo:base/Array";
+  /// Array.foldLeft([2, 3, 1], 10, Nat.sub) // => 4
+  /// ```
+  public func sub(x : Nat, y : Nat) : Nat { x - y };
+
+  /// Returns the product of `x` and `y`, `x * y`. This operator will never
+  /// overflow because `Nat` is infinite precision.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.mul(2, 3); // => 6
+  /// 2 * 3 // => 6
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `*` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `*`
+  /// as a function value at the moment.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// import Array "mo:base/Array";
+  /// Array.foldLeft([2, 3, 1], 1, Nat.mul) // => 6
+  /// ```
+  public func mul(x : Nat, y : Nat) : Nat { x * y };
+
+  /// Returns the unsigned integer division of `x` by `y`,  `x / y`.
+  /// Traps when `y` is zero.
+  ///
+  /// The quotient is rounded down, which is equivalent to truncating the
+  /// decimal places of the quotient.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.div(6, 2); // => 3
+  /// 6 / 2 // => 3
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `/` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `/`
+  /// as a function value at the moment.
+  public func div(x : Nat, y : Nat) : Nat { x / y };
+
+  /// Returns the remainder of unsigned integer division of `x` by `y`,  `x % y`.
+  /// Traps when `y` is zero.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.rem(6, 4); // => 2
+  /// 6 % 4 // => 2
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `%` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `%`
+  /// as a function value at the moment.
+  public func rem(x : Nat, y : Nat) : Nat { x % y };
+
+  /// Returns `x` to the power of `y`, `x ** y`. Traps when `y > 2^32`. This operator
+  /// will never overflow because `Nat` is infinite precision.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// ignore Nat.pow(2, 3); // => 8
+  /// 2 ** 3 // => 8
+  /// ```
+  ///
+  /// Note: The reason why this function is defined in this library (in addition
+  /// to the existing `**` operator) is so that you can use it as a function
+  /// value to pass to a higher order function. It is not possible to use `**`
+  /// as a function value at the moment.
+  public func pow(x : Nat, y : Nat) : Nat { x ** y };
+
+}

package/.mops/base@0.8.3/src/Nat16.mo

@@ -0,0 +1,144 @@
+/// 16-bit unsigned integers with checked arithmetic
+///
+/// Most operations are available as built-in operators (e.g. `1 + 1`).
+import Nat "Nat";
+import Prim "mo:⛔";
+
+module {
+
+  /// 16-bit natural numbers.
+  public type Nat16 = Prim.Types.Nat16;
+
+  /// Conversion.
+  public let toNat : Nat16 -> Nat = Prim.nat16ToNat;
+
+  /// Conversion. Traps on overflow/underflow.
+  public let fromNat : Nat -> Nat16 = Prim.natToNat16;
+
+  /// Conversion. Wraps on overflow/underflow.
+  public let fromIntWrap : Int -> Nat16 = Prim.intToNat16Wrap;
+
+  /// Returns the Text representation of `x`.
+  public func toText(x : Nat16) : Text {
+    Nat.toText(toNat(x))
+  };
+
+  /// Returns the minimum of `x` and `y`.
+  public func min(x : Nat16, y : Nat16) : Nat16 {
+    if (x < y) { x } else { y }
+  };
+
+  /// Returns the maximum of `x` and `y`.
+  public func max(x : Nat16, y : Nat16) : Nat16 {
+    if (x < y) { y } else { x }
+  };
+
+  /// Returns `x == y`.
+  public func equal(x : Nat16, y : Nat16) : Bool { x == y };
+
+  /// Returns `x != y`.
+  public func notEqual(x : Nat16, y : Nat16) : Bool { x != y };
+
+  /// Returns `x < y`.
+  public func less(x : Nat16, y : Nat16) : Bool { x < y };
+
+  /// Returns `x <= y`.
+  public func lessOrEqual(x : Nat16, y : Nat16) : Bool { x <= y };
+
+  /// Returns `x > y`.
+  public func greater(x : Nat16, y : Nat16) : Bool { x > y };
+
+  /// Returns `x >= y`.
+  public func greaterOrEqual(x : Nat16, y : Nat16) : Bool { x >= y };
+
+  /// Returns the order of `x` and `y`.
+  public func compare(x : Nat16, y : Nat16) : { #less; #equal; #greater } {
+    if (x < y) { #less } else if (x == y) { #equal } else { #greater }
+  };
+
+  /// Returns the sum of `x` and `y`, `x + y`. Traps on overflow.
+  public func add(x : Nat16, y : Nat16) : Nat16 { x + y };
+
+  /// Returns the difference of `x` and `y`, `x - y`. Traps on underflow.
+  public func sub(x : Nat16, y : Nat16) : Nat16 { x - y };
+
+  /// Returns the product of `x` and `y`, `x * y`. Traps on overflow.
+  public func mul(x : Nat16, y : Nat16) : Nat16 { x * y };
+
+  /// Returns the division of `x by y`, `x / y`.
+  /// Traps when `y` is zero.
+  public func div(x : Nat16, y : Nat16) : Nat16 { x / y };
+
+  /// Returns the remainder of `x` divided by `y`, `x % y`.
+  /// Traps when `y` is zero.
+  public func rem(x : Nat16, y : Nat16) : Nat16 { x % y };
+
+  /// Returns `x` to the power of `y`, `x ** y`. Traps on overflow.
+  public func pow(x : Nat16, y : Nat16) : Nat16 { x ** y };
+
+  /// Returns the bitwise negation of `x`, `^x`.
+  public func bitnot(x : Nat16) : Nat16 { ^x };
+
+  /// Returns the bitwise and of `x` and `y`, `x & y`.
+  public func bitand(x : Nat16, y : Nat16) : Nat16 { x & y };
+
+  /// Returns the bitwise or of `x` and `y`, `x \| y`.
+  public func bitor(x : Nat16, y : Nat16) : Nat16 { x | y };
+
+  /// Returns the bitwise exclusive or of `x` and `y`, `x ^ y`.
+  public func bitxor(x : Nat16, y : Nat16) : Nat16 { x ^ y };
+
+  /// Returns the bitwise shift left of `x` by `y`, `x << y`.
+  public func bitshiftLeft(x : Nat16, y : Nat16) : Nat16 { x << y };
+
+  /// Returns the bitwise shift right of `x` by `y`, `x >> y`.
+  public func bitshiftRight(x : Nat16, y : Nat16) : Nat16 { x >> y };
+
+  /// Returns the bitwise rotate left of `x` by `y`, `x <<> y`.
+  public func bitrotLeft(x : Nat16, y : Nat16) : Nat16 { x <<> y };
+
+  /// Returns the bitwise rotate right of `x` by `y`, `x <>> y`.
+  public func bitrotRight(x : Nat16, y : Nat16) : Nat16 { x <>> y };
+
+  /// Returns the value of bit `p mod 16` in `x`, `(x & 2^(p mod 16)) == 2^(p mod 16)`.
+  public func bittest(x : Nat16, p : Nat) : Bool {
+    Prim.btstNat16(x, Prim.natToNat16(p))
+  };
+
+  /// Returns the value of setting bit `p mod 16` in `x` to `1`.
+  public func bitset(x : Nat16, p : Nat) : Nat16 {
+    x | (1 << Prim.natToNat16(p))
+  };
+
+  /// Returns the value of clearing bit `p mod 16` in `x` to `0`.
+  public func bitclear(x : Nat16, p : Nat) : Nat16 {
+    x & ^(1 << Prim.natToNat16(p))
+  };
+
+  /// Returns the value of flipping bit `p mod 16` in `x`.
+  public func bitflip(x : Nat16, p : Nat) : Nat16 {
+    x ^ (1 << Prim.natToNat16(p))
+  };
+
+  /// Returns the count of non-zero bits in `x`.
+  public let bitcountNonZero : (x : Nat16) -> Nat16 = Prim.popcntNat16;
+
+  /// Returns the count of leading zero bits in `x`.
+  public let bitcountLeadingZero : (x : Nat16) -> Nat16 = Prim.clzNat16;
+
+  /// Returns the count of trailing zero bits in `x`.
+  public let bitcountTrailingZero : (x : Nat16) -> Nat16 = Prim.ctzNat16;
+
+  /// Returns the sum of `x` and `y`, `x +% y`. Wraps on overflow.
+  public func addWrap(x : Nat16, y : Nat16) : Nat16 { x +% y };
+
+  /// Returns the difference of `x` and `y`, `x -% y`. Wraps on underflow.
+  public func subWrap(x : Nat16, y : Nat16) : Nat16 { x -% y };
+
+  /// Returns the product of `x` and `y`, `x *% y`. Wraps on overflow.
+  public func mulWrap(x : Nat16, y : Nat16) : Nat16 { x *% y };
+
+  /// Returns `x` to the power of `y`, `x **% y`. Wraps on overflow.
+  public func powWrap(x : Nat16, y : Nat16) : Nat16 { x **% y };
+
+}

package/.mops/base@0.8.3/src/Nat32.mo

@@ -0,0 +1,144 @@
+/// 32-bit unsigned integers with checked arithmetic
+///
+/// Most operations are available as built-in operators (e.g. `1 + 1`).
+import Nat "Nat";
+import Prim "mo:⛔";
+
+module {
+
+  /// 32-bit natural numbers.
+  public type Nat32 = Prim.Types.Nat32;
+
+  /// Conversion.
+  public let toNat : Nat32 -> Nat = Prim.nat32ToNat;
+
+  /// Conversion. Traps on overflow/underflow.
+  public let fromNat : Nat -> Nat32 = Prim.natToNat32;
+
+  /// Conversion. Wraps on overflow/underflow.
+  public let fromIntWrap : Int -> Nat32 = Prim.intToNat32Wrap;
+
+  /// Returns the Text representation of `x`.
+  public func toText(x : Nat32) : Text {
+    Nat.toText(toNat(x))
+  };
+
+  /// Returns the minimum of `x` and `y`.
+  public func min(x : Nat32, y : Nat32) : Nat32 {
+    if (x < y) { x } else { y }
+  };
+
+  /// Returns the maximum of `x` and `y`.
+  public func max(x : Nat32, y : Nat32) : Nat32 {
+    if (x < y) { y } else { x }
+  };
+
+  /// Returns `x == y`.
+  public func equal(x : Nat32, y : Nat32) : Bool { x == y };
+
+  /// Returns `x != y`.
+  public func notEqual(x : Nat32, y : Nat32) : Bool { x != y };
+
+  /// Returns `x < y`.
+  public func less(x : Nat32, y : Nat32) : Bool { x < y };
+
+  /// Returns `x <= y`.
+  public func lessOrEqual(x : Nat32, y : Nat32) : Bool { x <= y };
+
+  /// Returns `x > y`.
+  public func greater(x : Nat32, y : Nat32) : Bool { x > y };
+
+  /// Returns `x >= y`.
+  public func greaterOrEqual(x : Nat32, y : Nat32) : Bool { x >= y };
+
+  /// Returns the order of `x` and `y`.
+  public func compare(x : Nat32, y : Nat32) : { #less; #equal; #greater } {
+    if (x < y) { #less } else if (x == y) { #equal } else { #greater }
+  };
+
+  /// Returns the sum of `x` and `y`, `x + y`. Traps on overflow.
+  public func add(x : Nat32, y : Nat32) : Nat32 { x + y };
+
+  /// Returns the difference of `x` and `y`, `x - y`. Traps on underflow.
+  public func sub(x : Nat32, y : Nat32) : Nat32 { x - y };
+
+  /// Returns the product of `x` and `y`, `x * y`. Traps on overflow.
+  public func mul(x : Nat32, y : Nat32) : Nat32 { x * y };
+
+  /// Returns the division of `x by y`, `x / y`.
+  /// Traps when `y` is zero.
+  public func div(x : Nat32, y : Nat32) : Nat32 { x / y };
+
+  /// Returns the remainder of `x` divided by `y`, `x % y`.
+  /// Traps when `y` is zero.
+  public func rem(x : Nat32, y : Nat32) : Nat32 { x % y };
+
+  /// Returns `x` to the power of `y`, `x ** y`. Traps on overflow.
+  public func pow(x : Nat32, y : Nat32) : Nat32 { x ** y };
+
+  /// Returns the bitwise negation of `x`, `^x`.
+  public func bitnot(x : Nat32) : Nat32 { ^x };
+
+  /// Returns the bitwise and of `x` and `y`, `x & y`.
+  public func bitand(x : Nat32, y : Nat32) : Nat32 { x & y };
+
+  /// Returns the bitwise or of `x` and `y`, `x \| y`.
+  public func bitor(x : Nat32, y : Nat32) : Nat32 { x | y };
+
+  /// Returns the bitwise exclusive or of `x` and `y`, `x ^ y`.
+  public func bitxor(x : Nat32, y : Nat32) : Nat32 { x ^ y };
+
+  /// Returns the bitwise shift left of `x` by `y`, `x << y`.
+  public func bitshiftLeft(x : Nat32, y : Nat32) : Nat32 { x << y };
+
+  /// Returns the bitwise shift right of `x` by `y`, `x >> y`.
+  public func bitshiftRight(x : Nat32, y : Nat32) : Nat32 { x >> y };
+
+  /// Returns the bitwise rotate left of `x` by `y`, `x <<> y`.
+  public func bitrotLeft(x : Nat32, y : Nat32) : Nat32 { x <<> y };
+
+  /// Returns the bitwise rotate right of `x` by `y`, `x <>> y`.
+  public func bitrotRight(x : Nat32, y : Nat32) : Nat32 { x <>> y };
+
+  /// Returns the value of bit `p mod 32` in `x`, `(x & 2^(p mod 32)) == 2^(p mod 32)`.
+  public func bittest(x : Nat32, p : Nat) : Bool {
+    Prim.btstNat32(x, Prim.natToNat32(p))
+  };
+
+  /// Returns the value of setting bit `p mod 32` in `x` to `1`.
+  public func bitset(x : Nat32, p : Nat) : Nat32 {
+    x | (1 << Prim.natToNat32(p))
+  };
+
+  /// Returns the value of clearing bit `p mod 32` in `x` to `0`.
+  public func bitclear(x : Nat32, p : Nat) : Nat32 {
+    x & ^(1 << Prim.natToNat32(p))
+  };
+
+  /// Returns the value of flipping bit `p mod 32` in `x`.
+  public func bitflip(x : Nat32, p : Nat) : Nat32 {
+    x ^ (1 << Prim.natToNat32(p))
+  };
+
+  /// Returns the count of non-zero bits in `x`.
+  public let bitcountNonZero : (x : Nat32) -> Nat32 = Prim.popcntNat32;
+
+  /// Returns the count of leading zero bits in `x`.
+  public let bitcountLeadingZero : (x : Nat32) -> Nat32 = Prim.clzNat32;
+
+  /// Returns the count of trailing zero bits in `x`.
+  public let bitcountTrailingZero : (x : Nat32) -> Nat32 = Prim.ctzNat32;
+
+  /// Returns the sum of `x` and `y`, `x +% y`. Wraps on overflow.
+  public func addWrap(x : Nat32, y : Nat32) : Nat32 { x +% y };
+
+  /// Returns the difference of `x` and `y`, `x -% y`. Wraps on underflow.
+  public func subWrap(x : Nat32, y : Nat32) : Nat32 { x -% y };
+
+  /// Returns the product of `x` and `y`, `x *% y`. Wraps on overflow.
+  public func mulWrap(x : Nat32, y : Nat32) : Nat32 { x *% y };
+
+  /// Returns `x` to the power of `y`, `x **% y`. Wraps on overflow.
+  public func powWrap(x : Nat32, y : Nat32) : Nat32 { x **% y };
+
+}