Miscellaneous

src/Array.mo

@@ -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"
                 }
               }
             }
@@ -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])
   };
 

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/Hash.mo

@@ -22,29 +22,4 @@ module {
     ha == hb
   };
 
-  /// Computes a hash from the least significant 32-bits of `n`, ignoring other bits.
-  /// @deprecated For large `Nat` values consider using a bespoke hash function that considers all of the argument's bits.
-  public func hash(n : Nat) : Hash {
-    let j = Prim.intToNat32Wrap(n);
-    hashNat8([
-      j & (255 << 0),
-      j & (255 << 8),
-      j & (255 << 16),
-      j & (255 << 24)
-    ])
-  };
-
-  func hashNat8(key : [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
-  };
-
 }

src/Int.mo

@@ -147,33 +147,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

@@ -277,7 +277,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

src/Map.mo

@@ -408,7 +408,7 @@ module {
   public func add<K, V>(map : Map<K, V>, compare : (K, K) -> Order.Order, key : K, value : V) : () {
     switch (put(map, compare, key, value)) {
       case null {};
-      case (?value) Runtime.trap("Key is already present")
+      case (?value) Runtime.trap("Map.add(): key is already present")
     }
   };
 

src/Text.mo

@@ -96,7 +96,7 @@ module {
       func _ {
         switch (cs.next()) {
           case (?c) { c };
-          case null { Prim.trap("Text.toArray") }
+          case null { Prim.trap("Text.toArray()") }
         }
       }
     )

src/Timer.mo

@@ -1,20 +1,35 @@
-/// Timers for one-off or periodic tasks.
+/// Timers for one-off or periodic tasks. Applicable as part of the default mechanism.
+/// If `moc` is invoked with `-no-timer`, the importing will fail. Furthermore, if passed `--trap-on-call-error`, a congested canister send queue may prevent timer expirations to execute at runtime. It may also deactivate the global timer.
 ///
-/// Note: If `moc` is invoked with `-no-timer`, the importing will fail.
-/// Note: The resolution of the timers is in the order of the block rate,
-///       so durations should be chosen well above that. For frequent
-///       canister wake-ups the heatbeat mechanism should be considered.
-
+/// The resolution of the timers is similar to the block rate,
+/// so durations should be chosen well above that. For frequent
+/// canister wake-ups, consider using the [heartbeat](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/heartbeats) mechanism; however, when possible, canisters should prefer timers.
+///
+/// The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`.
+///
+/// Timers are _not_ persisted across upgrades. One possible strategy
+/// to re-establish timers after an upgrade is to use stable variables
+/// in the `post_upgrade` hook and distill necessary timer information
+/// from there.
+///
+/// Using timers for security (e.g., access control) is strongly discouraged.
+/// Make sure to inform yourself about state-of-the-art dapp security.
+/// If you must use timers for security controls, be sure
+/// to consider reentrancy issues as well as the vanishing of timers on upgrades
+/// and reinstalls.
+///
+/// For further usage information for timers on the IC, please consult
+/// [the documentation](https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations).
 import { setTimer = setTimerNano; cancelTimer = cancel } = "mo:⛔";
+import Nat64 = "Nat64";
 import Time "Time";
-import Nat64 "Nat64";
 
 module {
 
-  public type Duration = { #seconds : Nat; #nanoseconds : Nat };
   public type TimerId = Nat;
 
-  /// Installs a one-off timer that upon expiration after given `duration` executes the future `job()`.
+  /// Installs a one-off timer that upon expiration after given duration `d`
+  /// executes the future `job()`.
   ///
   /// ```motoko no-repl
   /// let now = Time.now();
@@ -28,7 +43,7 @@ module {
     setTimerNano<system>(Nat64.fromNat(Time.toNanoseconds duration), false, job)
   };
 
-  /// Installs a recurring timer that upon expiration after given `duration`
+  /// Installs a recurring timer that upon expiration after given duration `d`
   /// executes the future `job()` and reinserts itself for another expiration.
   ///
   /// Note: A duration of 0 will only expire once.
@@ -47,8 +62,8 @@ module {
   /// and not recognised `id`s nothing happens.
   ///
   /// ```motoko no-repl
-  /// func deleteAppt(appt : Appointment) {
-  ///   cancelTimer (appt.reminder);
+  /// func deleteAppointment(appointment : Appointment) {
+  ///   cancelTimer (appointment.reminder);
   ///   // ...
   /// };
   /// ```

src/VarArray.mo

@@ -421,7 +421,7 @@ module {
         switch (options[nextSome - 1]) {
           case (?element) element;
           case null {
-            Prim.trap "Malformed array in filterMap"
+            Prim.trap "VarArray.filterMap(): malformed array"
           }
         }
       }
@@ -486,7 +486,7 @@ module {
                   element
                 };
                 case null {
-                  Prim.trap "Malformed array in mapResults"
+                  Prim.trap "VarArray.mapResults(): malformed array"
                 }
               }
             }