ic-mops 0.8.5 → 0.8.7

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

@@ -1,270 +0,0 @@
-/// 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

@@ -1,209 +0,0 @@
-/// 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

@@ -1,93 +0,0 @@
-/// 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 }
-      }
-    }
-  }
-}