Merge branch 'main' into range-with-step

.github/workflows/gh-pages.yml

@@ -8,6 +8,7 @@ on:
 
 jobs:
   deploy:
+    if: github.event.pull_request.head.repo.owner.login == 'dfinity'
     strategy:
       matrix:
         node: [20]
@@ -16,16 +17,6 @@ jobs:
     env:
       PR_PATH: pull/${{github.event.number}}
     steps:
-      - name: Comment on PR
-        uses: hasura/[email protected]
-        if: github.ref != 'refs/heads/main'
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          repository: ${{ github.repository }}
-          number: ${{ github.event.number }}
-          id: deploy-preview
-          message: "⏳ Loading documentation preview..."
-
       - name: Checkout website repo
         uses: actions/checkout@v4
 

mops.toml

@@ -8,6 +8,7 @@ license = "Apache-2.0"
 
 [dev-dependencies]
 matchers = "https://github.com/kritzcreek/motoko-matchers#v1.3.0@3dac8a071b69e4e651b25a7d9683fe831eb7cffd"
+testing = "https://github.com/internet-computer/testing.mo#v0.1.3@2968b359cf69d7bbef5005d8fbfbc60d56df8a88"
 
 [toolchain]
 moc = "0.13.3"

src/Array.mo

@@ -11,11 +11,11 @@
 /// import Array "mo:base/Array";
 /// ```
 
-import Iter "type/Iter";
 import Order "Order";
 import Result "Result";
 import VarArray "VarArray";
 import Option "Option";
+import Types "Types";
 import Prim "mo:⛔";
 import { todo } "Debug";
 
@@ -332,7 +332,7 @@ module {
         switch (options[nextSome - 1]) {
           case (?element) element;
           case null {
-            Prim.trap "Malformed array in filterMap"
+            Prim.trap "Array.filterMap(): malformed array"
           }
         }
       }
@@ -397,7 +397,7 @@ module {
                   element
                 };
                 case null {
-                  Prim.trap "Malformed array in mapResults"
+                  Prim.trap "Array.mapResult(): malformed array"
                 }
               }
             }
@@ -440,7 +440,7 @@ module {
   ///
   /// Space: O(size)
   /// *Runtime and space assumes that `k` runs in O(1) time and space.
-  public func flatMap<T, R>(array : [T], k : T -> Iter.Iter<R>) : [R] {
+  public func flatMap<T, R>(array : [T], k : T -> Types.Iter<R>) : [R] {
     var flatSize = 0;
     let arrays = Prim.Array_tabulate<[R]>(
       array.size(),
@@ -539,7 +539,7 @@ module {
   /// Runtime: O(number of elements in array)
   ///
   /// Space: O(number of elements in array)
-  public func join<T>(arrays : Iter.Iter<[T]>) : [T] {
+  public func join<T>(arrays : Types.Iter<[T]>) : [T] {
     flatten(fromIter(arrays))
   };
 
@@ -598,7 +598,7 @@ module {
   public func isEmpty<T>(array : [T]) : Bool = array.size() == 0;
 
   /// Converts an iterator to an array.
-  public func fromIter<T>(iter : Iter.Iter<T>) : [T] {
+  public func fromIter<T>(iter : Types.Iter<T>) : [T] {
     todo() // Pending `List` data structure
   };
 
@@ -622,7 +622,7 @@ module {
   /// Runtime: O(1)
   ///
   /// Space: O(1)
-  public func keys<T>(array : [T]) : Iter.Iter<Nat> = array.keys();
+  public func keys<T>(array : [T]) : Types.Iter<Nat> = array.keys();
 
   /// Iterator provides a single method `next()`, which returns
   /// elements in order, or `null` when out of elements to iterate over.
@@ -643,7 +643,7 @@ module {
   /// Runtime: O(1)
   ///
   /// Space: O(1)
-  public func values<T>(array : [T]) : Iter.Iter<T> = array.vals();
+  public func values<T>(array : [T]) : Types.Iter<T> = array.vals();
 
   /// Iterator provides a single method `next()`, which returns
   /// pairs of (index, element) in order, or `null` when out of elements to iterate over.
@@ -661,7 +661,7 @@ module {
   /// Runtime: O(1)
   ///
   /// Space: O(1)
-  public func enumerate<T>(array : [var T]) : Iter.Iter<(Nat, T)> = object {
+  public func enumerate<T>(array : [var T]) : Types.Iter<(Nat, T)> = object {
     let size = array.size();
     var index = 0;
     public func next() : ?(Nat, T) {
@@ -729,7 +729,7 @@ module {
   ///
   /// Space: O(length)
   public func subArray<T>(array : [T], start : Nat, length : Nat) : [T] {
-    if (start + length > array.size()) { Prim.trap("Array.subArray()") };
+    if (start + length > array.size()) { Prim.trap("Array.subArray(): 'start + length' is greater than 'array.size()'") };
     Prim.Array_tabulate<T>(length, func i = array[start + i])
   };
 
@@ -832,7 +832,7 @@ module {
   /// Runtime: O(1)
   ///
   /// Space: O(1)
-  public func range<T>(array : [T], fromInclusive : Int, toExclusive : Int) : Iter.Iter<T> {
+  public func range<T>(array : [T], fromInclusive : Int, toExclusive : Int) : Types.Iter<T> {
     let size = array.size();
     // Convert negative indices to positive and handle bounds
     let startInt = if (fromInclusive < 0) {

src/Blob.mo

@@ -30,6 +30,7 @@
 /// }
 /// ```
 
+import Types "Types";
 import Prim "mo:⛔";
 
 module {
@@ -84,7 +85,7 @@ module {
   /// let blob = "\00\FF\00" : Blob;
   /// Blob.hash(blob) // => 1_818_567_776
   /// ```
-  public func hash(blob : Blob) : Nat32 = Prim.hashBlob blob;
+  public func hash(blob : Blob) : Types.Hash = Prim.hashBlob blob;
 
   /// General purpose comparison function for `Blob` by comparing the value of
   /// the bytes. Returns the `Order` (either `#less`, `#equal`, or `#greater`)

src/Error.mo

@@ -17,6 +17,8 @@ module {
   ///   #system_fatal;
   ///   // Transient error.
   ///   #system_transient;
+  ///   // Response unknown due to missed deadline.
+  ///   #system_unknown;
   ///   // Destination invalid.
   ///   #destination_invalid;
   ///   // Explicit reject by canister code.

src/Float.mo

@@ -32,7 +32,7 @@
 ///   let y = 0.3;
 ///
 ///   let epsilon = 1e-6; // This depends on the application case (needs a numerical error analysis).
-///   Float.equalWithin(x, y, epsilon) // => true
+///   Float.equal(x, y, epsilon) // => true
 ///   ```
 ///
 /// * For absolute precision, it is recommened to encode the fraction number as a pair of a Nat for the base
@@ -491,14 +491,6 @@ module {
   /// ```
   public let fromInt : Int -> Float = Prim.intToFloat;
 
-  /// Returns `x == y`.
-  /// @deprecated Use `Float.equalWithin()` as this function does not consider numerical errors.
-  public func equal(x : Float, y : Float) : Bool { x == y };
-
-  /// Returns `x != y`.
-  /// @deprecated Use `Float.notEqualWithin()` as this function does not consider numerical errors.
-  public func notEqual(x : Float, y : Float) : Bool { x != y };
-
   /// Determines whether `x` is equal to `y` within the defined tolerance of `epsilon`.
   /// The `epsilon` considers numerical erros, see comment above.
   /// Equivalent to `Float.abs(x - y) <= epsilon` for a non-negative epsilon.
@@ -507,25 +499,25 @@ module {
   ///
   /// Special cases:
   /// ```
-  /// equalWithin(+0.0, -0.0, epsilon) => true for any `epsilon >= 0.0`
-  /// equalWithin(-0.0, +0.0, epsilon) => true for any `epsilon >= 0.0`
-  /// equalWithin(+inf, +inf, epsilon) => true for any `epsilon >= 0.0`
-  /// equalWithin(-inf, -inf, epsilon) => true for any `epsilon >= 0.0`
-  /// equalWithin(x, NaN, epsilon)     => false for any x and `epsilon >= 0.0`
-  /// equalWithin(NaN, y, epsilon)     => false for any y and `epsilon >= 0.0`
+  /// equal(+0.0, -0.0, epsilon) => true for any `epsilon >= 0.0`
+  /// equal(-0.0, +0.0, epsilon) => true for any `epsilon >= 0.0`
+  /// equal(+inf, +inf, epsilon) => true for any `epsilon >= 0.0`
+  /// equal(-inf, -inf, epsilon) => true for any `epsilon >= 0.0`
+  /// equal(x, NaN, epsilon)     => false for any x and `epsilon >= 0.0`
+  /// equal(NaN, y, epsilon)     => false for any y and `epsilon >= 0.0`
   /// ```
   ///
   /// Example:
   /// ```motoko
   /// import Float "mo:base/Float";
   ///
   /// let epsilon = 1e-6;
-  /// Float.equalWithin(-12.3, -1.23e1, epsilon) // => true
+  /// Float.equal(-12.3, -1.23e1, epsilon) // => true
   /// ```
-  public func equalWithin(x : Float, y : Float, epsilon : Float) : Bool {
+  public func equal(x : Float, y : Float, epsilon : Float) : Bool {
     if (not (epsilon >= 0.0)) {
       // also considers NaN, not identical to `epsilon < 0.0`
-      Prim.trap("epsilon must be greater or equal 0.0")
+      Prim.trap("Float.equal(): epsilon must be greater or equal 0.0")
     };
     x == y or abs(x - y) <= epsilon // `x == y` to also consider infinity equal
   };
@@ -538,23 +530,27 @@ module {
   ///
   /// Special cases:
   /// ```
-  /// notEqualWithin(+0.0, -0.0, epsilon) => false for any `epsilon >= 0.0`
-  /// notEqualWithin(-0.0, +0.0, epsilon) => false for any `epsilon >= 0.0`
-  /// notEqualWithin(+inf, +inf, epsilon) => false for any `epsilon >= 0.0`
-  /// notEqualWithin(-inf, -inf, epsilon) => false for any `epsilon >= 0.0`
-  /// notEqualWithin(x, NaN, epsilon)     => true for any x and `epsilon >= 0.0`
-  /// notEqualWithin(NaN, y, epsilon)     => true for any y and `epsilon >= 0.0`
+  /// notEqual(+0.0, -0.0, epsilon) => false for any `epsilon >= 0.0`
+  /// notEqual(-0.0, +0.0, epsilon) => false for any `epsilon >= 0.0`
+  /// notEqual(+inf, +inf, epsilon) => false for any `epsilon >= 0.0`
+  /// notEqual(-inf, -inf, epsilon) => false for any `epsilon >= 0.0`
+  /// notEqual(x, NaN, epsilon)     => true for any x and `epsilon >= 0.0`
+  /// notEqual(NaN, y, epsilon)     => true for any y and `epsilon >= 0.0`
   /// ```
   ///
   /// Example:
   /// ```motoko
   /// import Float "mo:base/Float";
   ///
   /// let epsilon = 1e-6;
-  /// Float.notEqualWithin(-12.3, -1.23e1, epsilon) // => false
+  /// Float.notEqual(-12.3, -1.23e1, epsilon) // => false
   /// ```
-  public func notEqualWithin(x : Float, y : Float, epsilon : Float) : Bool {
-    not equalWithin(x, y, epsilon)
+  public func notEqual(x : Float, y : Float, epsilon : Float) : Bool {
+    if (not (epsilon >= 0.0)) {
+      // also considers NaN, not identical to `epsilon < 0.0`
+      Prim.trap("Float.notEqual(): epsilon must be greater or equal 0.0")
+    };
+    not (x == y or abs(x - y) <= epsilon)
   };
 
   /// Returns `x < y`.
@@ -632,8 +628,8 @@ module {
   /// Defines a total order of `x` and `y` for use in sorting.
   ///
   /// Note: Using this operation to determine equality or inequality is discouraged for two reasons:
-  /// * It does not consider numerical errors, see comment above. Use `equalWithin(x, y, espilon)` or
-  ///   `notEqualWithin(x, y, epsilon)` to test for equality or inequality, respectively.
+  /// * It does not consider numerical errors, see comment above. Use `equal(x, y, espilon)` or
+  ///   `notEqual(x, y, epsilon)` to test for equality or inequality, respectively.
   /// * `NaN` are here considered equal if their sign matches, which is different to the standard equality
   ///    by `==` or when using `equal()` or `notEqual()`.
   ///

src/Int.mo

@@ -10,10 +10,8 @@
 
 import Prim "mo:⛔";
 import Char "Char";
-import Hash "Hash";
 import Runtime "Runtime";
 import Iter "Iter";
-import { todo } "Debug";
 
 module {
 
@@ -147,33 +145,6 @@ module {
     if (x < y) { y } else { x }
   };
 
-  // this is a local copy of deprecated Hash.hashNat8 (redefined to suppress the warning)
-  private func hashNat8(key : [Nat32]) : Hash.Hash {
-    var hash : Nat32 = 0;
-    for (natOfKey in key.vals()) {
-      hash := hash +% natOfKey;
-      hash := hash +% hash << 10;
-      hash := hash ^ (hash >> 6)
-    };
-    hash := hash +% hash << 3;
-    hash := hash ^ (hash >> 11);
-    hash := hash +% hash << 15;
-    return hash
-  };
-
-  /// Computes a hash from the least significant 32-bits of `i`, ignoring other bits.
-  /// @deprecated For large `Int` values consider using a bespoke hash function that considers all of the argument's bits.
-  public func hash(i : Int) : Hash.Hash {
-    // CAUTION: This removes the high bits!
-    let j = Prim.int32ToNat32(Prim.intToInt32Wrap(i));
-    hashNat8([
-      j & (255 << 0),
-      j & (255 << 8),
-      j & (255 << 16),
-      j & (255 << 24)
-    ])
-  };
-
   /// Equality function for Int types.
   /// This is equivalent to `x == y`.
   ///

src/Iter.mo

@@ -5,6 +5,7 @@ import Array "Array";
 import VarArray "VarArray";
 import Prim "mo:prim";
 import Runtime "Runtime";
+import Types "Types";
 
 module {
 
@@ -21,7 +22,7 @@ module {
   ///   …do something with x…
   /// }
   /// ```
-  public type Iter<T> = { next : () -> ?T };
+  public type Iter<T> = Types.Iter<T>;
 
   public func empty<T>() : Iter<T> {
     object {
@@ -321,7 +322,7 @@ module {
       count,
       func(_) {
         switch (current) {
-          case null Runtime.trap("Node must not be null");
+          case null Runtime.trap("Iter.toArray(): node must not be null");
           case (?node) {
             current := node.next;
             node.value