ic-mops 0.8.4 → 0.8.5

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

@@ -0,0 +1,270 @@
+/// A module for obtaining randomness on the Internet Computer (IC).
+///
+/// This module provides the fundamentals for user abstractions to build on.
+///
+/// Dealing with randomness on a deterministic computing platform, such
+/// as the IC, is intricate. Some basic rules need to be followed by the
+/// user of this module to obtain (and maintain) the benefits of crypto-
+/// graphic randomness:
+///
+/// - cryptographic entropy (randomness source) is only obtainable
+///   asyncronously in discrete chunks of 256 bits (32-byte sized `Blob`s)
+/// - all bets must be closed *before* entropy is being asked for in
+///   order to decide them
+/// - this implies that the same entropy (i.e. `Blob`) - or surplus entropy
+///   not utilised yet - cannot be used for a new round of bets without
+///   losing the cryptographic guarantees.
+///
+/// Concretely, the below class `Finite`, as well as the
+/// `*From` methods risk the carrying-over of state from previous rounds.
+/// These are provided for performance (and convenience) reasons, and need
+/// special care when used. Similar caveats apply for user-defined (pseudo)
+/// random number generators.
+///
+/// Usage:
+/// ```motoko no-repl
+/// import Random "mo:base/Random";
+/// ```
+
+import I "Iter";
+import Option "Option";
+import Prim "mo:⛔";
+
+module {
+
+  let raw_rand = (actor "aaaaa-aa" : actor { raw_rand : () -> async Blob }).raw_rand;
+
+  /// Obtains a full blob (32 bytes) worth of fresh entropy.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// let random = Random.Finite(await Random.blob());
+  /// ```
+  public let blob : shared () -> async Blob = raw_rand;
+
+  /// Drawing from a finite supply of entropy, `Finite` provides
+  /// methods to obtain random values. When the entropy is used up,
+  /// `null` is returned. Otherwise the outcomes' distributions are
+  /// stated for each method. The uniformity of outcomes is
+  /// guaranteed only when the supplied entropy is originally obtained
+  /// by the `blob()` call, and is never reused.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// import Random "mo:base/Random";
+  ///
+  /// let random = Random.Finite(await Random.blob());
+  ///
+  /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+  /// let seedRandom = Random.Finite(seed);
+  /// ```
+  public class Finite(entropy : Blob) {
+    let it : I.Iter<Nat8> = entropy.vals();
+
+    /// Uniformly distributes outcomes in the numeric range [0 .. 255].
+    /// Consumes 1 byte of entropy.
+    ///
+    /// Example:
+    /// ```motoko no-repl
+    /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+    /// let random = Random.Finite(seed);
+    /// random.byte() // => ?20
+    /// ```
+    public func byte() : ?Nat8 {
+      it.next()
+    };
+
+    /// Bool iterator splitting up a byte of entropy into 8 bits
+    let bit : I.Iter<Bool> = object {
+      var mask = 0x00 : Nat8;
+      var byte = 0x00 : Nat8;
+      public func next() : ?Bool {
+        if (0 : Nat8 == mask) {
+          switch (it.next()) {
+            case null { null };
+            case (?w) {
+              byte := w;
+              mask := 0x40;
+              ?(0 : Nat8 != byte & (0x80 : Nat8))
+            }
+          }
+        } else {
+          let m = mask;
+          mask >>= (1 : Nat8);
+          ?(0 : Nat8 != byte & m)
+        }
+      }
+    };
+
+    /// Simulates a coin toss. Both outcomes have equal probability.
+    /// Consumes 1 bit of entropy (amortised).
+    ///
+    /// Example:
+    /// ```motoko no-repl
+    /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+    /// let random = Random.Finite(seed);
+    /// random.coin() // => ?false
+    /// ```
+    public func coin() : ?Bool {
+      bit.next()
+    };
+
+    /// Uniformly distributes outcomes in the numeric range [0 .. 2^p - 1].
+    /// Consumes ⌈p/8⌉ bytes of entropy.
+    ///
+    /// Example:
+    /// ```motoko no-repl
+    /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+    /// let random = Random.Finite(seed);
+    /// random.range(32) // => ?348746249
+    /// ```
+    public func range(p : Nat8) : ?Nat {
+      var pp = p;
+      var acc : Nat = 0;
+      for (i in it) {
+        if (8 : Nat8 <= pp) {
+          acc := acc * 256 + Prim.nat8ToNat(i)
+        }
+        else if (0 : Nat8 == pp) {
+          return ?acc
+        } else {
+          acc *= Prim.nat8ToNat(1 << pp);
+          let mask : Nat8 = 0xff >> (8 - pp);
+          return ?(acc + Prim.nat8ToNat(i & mask))
+        };
+        pp -= 8
+      };
+      if (0 : Nat8 == pp)
+        ?acc
+      else null
+    };
+
+    /// Counts the number of heads in `n` fair coin tosses.
+    /// Consumes ⌈n/8⌉ bytes of entropy.
+    ///
+    /// Example:
+    /// ```motoko no-repl
+    /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+    /// let random = Random.Finite(seed);
+    /// random.binomial(5) // => ?1
+    /// ```
+    public func binomial(n : Nat8) : ?Nat8 {
+      var nn = n;
+      var acc : Nat8 = 0;
+      for (i in it) {
+        if (8 : Nat8 <= nn) {
+          acc +%= Prim.popcntNat8(i)
+        } else if (0 : Nat8 == nn) {
+          return ?acc
+        } else {
+          let mask : Nat8 = 0xff << (8 - nn);
+          let residue = Prim.popcntNat8(i & mask);
+          return ?(acc +% residue)
+        };
+        nn -= 8
+      };
+      if (0 : Nat8 == nn)
+        ?acc
+      else null
+    }
+  };
+
+  /// Distributes outcomes in the numeric range [0 .. 255].
+  /// Seed blob must contain at least a byte.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+  /// Random.byteFrom(seed) // => 20
+  /// ```
+  public func byteFrom(seed : Blob) : Nat8 {
+    switch (seed.vals().next()) {
+      case (?w) { w };
+      case _ { Prim.trap "Random.byteFrom" }
+    }
+  };
+
+  /// Simulates a coin toss.
+  /// Seed blob must contain at least a byte.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+  /// Random.coinFrom(seed) // => false
+  /// ```
+  public func coinFrom(seed : Blob) : Bool {
+    switch (seed.vals().next()) {
+      case (?w) { w > (127 : Nat8) };
+      case _ { Prim.trap "Random.coinFrom" }
+    }
+  };
+
+  /// Distributes outcomes in the numeric range [0 .. 2^p - 1].
+  /// Seed blob must contain at least ((p+7) / 8) bytes.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+  /// Random.rangeFrom(32, seed) // => 348746249
+  /// ```
+  public func rangeFrom(p : Nat8, seed : Blob) : Nat {
+    rangeIter(p, seed.vals())
+  };
+
+  // internal worker method, expects iterator with sufficient supply
+  func rangeIter(p : Nat8, it : I.Iter<Nat8>) : Nat {
+    var pp = p;
+    var acc : Nat = 0;
+    for (i in it) {
+      if (8 : Nat8 <= pp) {
+        acc := acc * 256 + Prim.nat8ToNat(i)
+      } else if (0 : Nat8 == pp) {
+        return acc
+      } else {
+        acc *= Prim.nat8ToNat(1 << pp);
+        let mask : Nat8 = 0xff >> (8 - pp);
+        return acc + Prim.nat8ToNat(i & mask)
+      };
+      pp -= 8
+    };
+    if (0 : Nat8 == pp) {
+      return acc
+    }
+    else Prim.trap("Random.rangeFrom")
+  };
+
+  /// Counts the number of heads in `n` coin tosses.
+  /// Seed blob must contain at least ((n+7) / 8) bytes.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// let seed : Blob = "\14\C9\72\09\03\D4\D5\72\82\95\E5\43\AF\FA\A9\44\49\2F\25\56\13\F3\6E\C7\B0\87\DC\76\08\69\14\CF";
+  /// Random.binomialFrom(5, seed) // => 1
+  /// ```
+  public func binomialFrom(n : Nat8, seed : Blob) : Nat8 {
+    binomialIter(n, seed.vals())
+  };
+
+  // internal worker method, expects iterator with sufficient supply
+  func binomialIter(n : Nat8, it : I.Iter<Nat8>) : Nat8 {
+    var nn = n;
+    var acc : Nat8 = 0;
+    for (i in it) {
+      if (8 : Nat8 <= nn) {
+        acc +%= Prim.popcntNat8(i)
+      } else if (0 : Nat8 == nn) {
+        return acc
+      } else {
+        let mask : Nat8 = 0xff << (8 - nn);
+        let residue = Prim.popcntNat8(i & mask);
+        return (acc +% residue)
+      };
+      nn -= 8
+    };
+    if (0 : Nat8 == nn) {
+      return acc
+    }
+    else Prim.trap("Random.binomialFrom")
+  }
+
+}

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

@@ -0,0 +1,209 @@
+/// Error handling with the Result type.
+
+import Prim "mo:⛔";
+import P "Prelude";
+import Order "Order";
+
+module {
+
+  /// `Result<Ok, Err>` is the type used for returning and propagating errors. It
+  /// is a type with the variants, `#ok(Ok)`, representing success and containing
+  /// a value, and `#err(Err)`, representing error and containing an error value.
+  ///
+  /// The simplest way of working with `Result`s is to pattern match on them:
+  ///
+  /// For example, given a function `createUser(user : User) : Result<Id, String>`
+  /// where `String` is an error message we could use it like so:
+  /// ```motoko no-repl
+  /// switch(createUser(myUser)) {
+  ///   case (#ok(id)) { Debug.print("Created new user with id: " # id) };
+  ///   case (#err(msg)) { Debug.print("Failed to create user with the error: " # msg) };
+  /// }
+  /// ```
+  public type Result<Ok, Err> = {
+    #ok : Ok;
+    #err : Err
+  };
+
+  // Compares two Result's for equality.
+  public func equal<Ok, Err>(
+    eqOk : (Ok, Ok) -> Bool,
+    eqErr : (Err, Err) -> Bool,
+    r1 : Result<Ok, Err>,
+    r2 : Result<Ok, Err>
+  ) : Bool {
+    switch (r1, r2) {
+      case (#ok(ok1), #ok(ok2)) {
+        eqOk(ok1, ok2)
+      };
+      case (#err(err1), #err(err2)) {
+        eqErr(err1, err2)
+      };
+      case _ { false }
+    }
+  };
+
+  // Compares two Results. `#ok` is larger than `#err`. This ordering is
+  // arbitrary, but it lets you for example use Results as keys in ordered maps.
+  public func compare<Ok, Err>(
+    compareOk : (Ok, Ok) -> Order.Order,
+    compareErr : (Err, Err) -> Order.Order,
+    r1 : Result<Ok, Err>,
+    r2 : Result<Ok, Err>
+  ) : Order.Order {
+    switch (r1, r2) {
+      case (#ok(ok1), #ok(ok2)) {
+        compareOk(ok1, ok2)
+      };
+      case (#err(err1), #err(err2)) {
+        compareErr(err1, err2)
+      };
+      case (#ok(_), _) { #greater };
+      case (#err(_), _) { #less }
+    }
+  };
+
+  /// Allows sequencing of `Result` values and functions that return
+  /// `Result`'s themselves.
+  /// ```motoko
+  /// import Result "mo:base/Result";
+  /// type Result<T,E> = Result.Result<T, E>;
+  /// func largerThan10(x : Nat) : Result<Nat, Text> =
+  ///   if (x > 10) { #ok(x) } else { #err("Not larger than 10.") };
+  ///
+  /// func smallerThan20(x : Nat) : Result<Nat, Text> =
+  ///   if (x < 20) { #ok(x) } else { #err("Not smaller than 20.") };
+  ///
+  /// func between10And20(x : Nat) : Result<Nat, Text> =
+  ///   Result.chain(largerThan10(x), smallerThan20);
+  ///
+  /// assert(between10And20(15) == #ok(15));
+  /// assert(between10And20(9) == #err("Not larger than 10."));
+  /// assert(between10And20(21) == #err("Not smaller than 20."));
+  /// ```
+  public func chain<R1, R2, Error>(
+    x : Result<R1, Error>,
+    y : R1 -> Result<R2, Error>
+  ) : Result<R2, Error> {
+    switch x {
+      case (#err(e)) { #err(e) };
+      case (#ok(r)) { y(r) }
+    }
+  };
+
+  /// Flattens a nested Result.
+  ///
+  /// ```motoko
+  /// import Result "mo:base/Result";
+  /// assert(Result.flatten<Nat, Text>(#ok(#ok(10))) == #ok(10));
+  /// assert(Result.flatten<Nat, Text>(#err("Wrong")) == #err("Wrong"));
+  /// assert(Result.flatten<Nat, Text>(#ok(#err("Wrong"))) == #err("Wrong"));
+  /// ```
+  public func flatten<Ok, Error>(
+    result : Result<Result<Ok, Error>, Error>
+  ) : Result<Ok, Error> {
+    switch result {
+      case (#ok(ok)) { ok };
+      case (#err(err)) { #err(err) }
+    }
+  };
+
+  /// Maps the `Ok` type/value, leaving any `Error` type/value unchanged.
+  public func mapOk<Ok1, Ok2, Error>(
+    x : Result<Ok1, Error>,
+    f : Ok1 -> Ok2
+  ) : Result<Ok2, Error> {
+    switch x {
+      case (#err(e)) { #err(e) };
+      case (#ok(r)) { #ok(f(r)) }
+    }
+  };
+
+  /// Maps the `Err` type/value, leaving any `Ok` type/value unchanged.
+  public func mapErr<Ok, Error1, Error2>(
+    x : Result<Ok, Error1>,
+    f : Error1 -> Error2
+  ) : Result<Ok, Error2> {
+    switch x {
+      case (#err(e)) { #err(f(e)) };
+      case (#ok(r)) { #ok(r) }
+    }
+  };
+
+  /// Create a result from an option, including an error value to handle the `null` case.
+  /// ```motoko
+  /// import Result "mo:base/Result";
+  /// assert(Result.fromOption(?42, "err") == #ok(42));
+  /// assert(Result.fromOption(null, "err") == #err("err"));
+  /// ```
+  public func fromOption<R, E>(x : ?R, err : E) : Result<R, E> {
+    switch x {
+      case (?x) { #ok(x) };
+      case null { #err(err) }
+    }
+  };
+
+  /// Create an option from a result, turning all #err into `null`.
+  /// ```motoko
+  /// import Result "mo:base/Result";
+  /// assert(Result.toOption(#ok(42)) == ?42);
+  /// assert(Result.toOption(#err("err")) == null);
+  /// ```
+  public func toOption<R, E>(r : Result<R, E>) : ?R {
+    switch r {
+      case (#ok(x)) { ?x };
+      case (#err(_)) { null }
+    }
+  };
+
+  /// Applies a function to a successful value, but discards the result. Use
+  /// `iterate` if you're only interested in the side effect `f` produces.
+  ///
+  /// ```motoko
+  /// import Result "mo:base/Result";
+  /// var counter : Nat = 0;
+  /// Result.iterate<Nat, Text>(#ok(5), func (x : Nat) { counter += x });
+  /// assert(counter == 5);
+  /// Result.iterate<Nat, Text>(#err("Wrong"), func (x : Nat) { counter += x });
+  /// assert(counter == 5);
+  /// ```
+  public func iterate<Ok, Err>(res : Result<Ok, Err>, f : Ok -> ()) {
+    switch res {
+      case (#ok(ok)) { f(ok) };
+      case _ {}
+    }
+  };
+
+  // Whether this Result is an `#ok`
+  public func isOk(r : Result<Any, Any>) : Bool {
+    switch r {
+      case (#ok(_)) { true };
+      case (#err(_)) { false }
+    }
+  };
+
+  // Whether this Result is an `#err`
+  public func isErr(r : Result<Any, Any>) : Bool {
+    switch r {
+      case (#ok(_)) { false };
+      case (#err(_)) { true }
+    }
+  };
+
+  /// Asserts that its argument is an `#ok` result, traps otherwise.
+  public func assertOk(r : Result<Any, Any>) {
+    switch (r) {
+      case (#err(_)) { assert false };
+      case (#ok(_)) {}
+    }
+  };
+
+  /// Asserts that its argument is an `#err` result, traps otherwise.
+  public func assertErr(r : Result<Any, Any>) {
+    switch (r) {
+      case (#err(_)) {};
+      case (#ok(_)) assert false
+    }
+  };
+
+}

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

@@ -0,0 +1,93 @@
+/// Class `Stack<X>` provides a Minimal LIFO stack of elements of type `X`.
+///
+/// See library `Deque` for mixed LIFO/FIFO behavior.
+///
+/// Example:
+/// ```motoko name=initialize
+/// import Stack "mo:base/Stack";
+///
+/// let stack = Stack.Stack<Nat>(); // create a stack
+/// ```
+/// Runtime: O(1)
+///
+/// Space: O(1)
+
+import List "List";
+
+module {
+
+  public class Stack<T>() {
+
+    var stack : List.List<T> = List.nil<T>();
+
+    /// Push an element on the top of the stack.
+    ///
+    /// Example:
+    /// ```motoko include=initialize
+    /// stack.push(1);
+    /// stack.push(2);
+    /// stack.push(3);
+    /// stack.peek(); // examine the top most element
+    /// ```
+    ///
+    /// Runtime: O(1)
+    ///
+    /// Space: O(1)
+    public func push(x : T) {
+      stack := ?(x, stack)
+    };
+
+    /// True when the stack is empty and false otherwise.
+    ///
+    /// Example:
+    /// ```motoko include=initialize
+    /// stack.isEmpty();
+    /// ```
+    ///
+    /// Runtime: O(1)
+    ///
+    /// Space: O(1)
+    public func isEmpty() : Bool {
+      List.isNil<T>(stack)
+    };
+
+    /// Return (without removing) the top element, or return null if the stack is empty.
+    ///
+    /// Example:
+    /// ```motoko include=initialize
+    /// stack.push(1);
+    /// stack.push(2);
+    /// stack.push(3);
+    /// stack.peek();
+    /// ```
+    ///
+    /// Runtime: O(1)
+    ///
+    /// Space: O(1)
+    public func peek() : ?T {
+      switch stack {
+        case null { null };
+        case (?(h, t)) { ?h }
+      }
+    };
+
+    /// Remove and return the top element, or return null if the stack is empty.
+    ///
+    /// Example:
+    /// ```motoko include=initialize
+    /// stack.push(1);
+    /// ignore stack.pop();
+    /// stack.isEmpty();
+    /// ```
+    ///
+    /// Runtime: O(1)
+    ///
+    /// Space: O(1)
+    public func pop() : ?T {
+      switch stack {
+        case null { null };
+        case (?(h, t)) { stack := t; ?h }
+      }
+    }
+  }
+}