ic-mops 0.8.3 → 0.8.5

package/.mops/base@0.7.4/src/Option.mo

@@ -0,0 +1,160 @@
+/// Typesafe nulls
+///
+/// Optional values can be seen as a typesafe `null`. A value of type `?Int` can
+/// be constructed with either `null` or `?42`. The simplest way to get at the
+/// contents of an optional is to use pattern matching:
+///
+/// ```motoko
+/// let optionalInt1 : ?Int = ?42;
+/// let optionalInt2 : ?Int = null;
+///
+/// let int1orZero : Int = switch optionalInt1 {
+///   case null 0;
+///   case (?int) int;
+/// };
+/// assert int1orZero == 42;
+///
+/// let int2orZero : Int = switch optionalInt2 {
+///   case null 0;
+///   case (?int) int;
+/// };
+/// assert int2orZero == 0;
+/// ```
+///
+/// The functions in this module capture some common operations when working
+/// with optionals that can be more succinct than using pattern matching.
+
+import P "Prelude";
+
+module {
+
+  /// Unwraps an optional value, with a default value, i.e. `get(?x, d) = x` and
+  /// `get(null, d) = d`.
+  public func get<T>(x : ?T, default : T) : T =
+    switch x {
+      case null { default };
+      case (?x_) { x_ };
+    };
+
+  /// Unwraps an optional value using a function, or returns the default, i.e.
+  /// `option(?x, f, d) = f x` and `option(null, f, d) = d`.
+  public func getMapped<A, B>(x : ?A, f : A -> B, default : B) : B =
+    switch x {
+      case null { default };
+      case (?x_) { f(x_) };
+    };
+
+  /// Applies a function to the wrapped value. `null`'s are left untouched.
+  /// ```motoko
+  /// import Option "mo:base/Option";
+  /// assert Option.map<Nat, Nat>(?42, func x = x + 1) == ?43;
+  /// assert Option.map<Nat, Nat>(null, func x = x + 1) == null;
+  /// ```
+  public func map<A, B>(x : ?A, f : A -> B) : ?B =
+    switch x {
+      case null { null };
+      case (?x_) { ?f(x_) };
+    };
+
+  /// Applies a function to the wrapped value, but discards the result. Use
+  /// `iterate` if you're only interested in the side effect `f` produces.
+  ///
+  /// ```motoko
+  /// import Option "mo:base/Option";
+  /// var counter : Nat = 0;
+  /// Option.iterate(?5, func (x : Nat) { counter += x });
+  /// assert counter == 5;
+  /// Option.iterate(null, func (x : Nat) { counter += x });
+  /// assert counter == 5;
+  /// ```
+  public func iterate<A>(x : ?A, f : A -> ()) =
+    switch x {
+      case null {};
+      case (?x_) { f(x_) };
+    };
+
+  /// Applies an optional function to an optional value. Returns `null` if at
+  /// least one of the arguments is `null`.
+  public func apply<A, B>(x : ?A, f : ?(A -> B)) : ?B {
+    switch (f, x) {
+      case (?f_, ?x_) {
+        ?f_(x_);
+      };
+      case (_, _) {
+        null;
+      };
+    };
+  };
+
+  /// Applies a function to an optional value. Returns `null` if the argument is
+  /// `null`, or the function returns `null`.
+  public func chain<A, B>(x : ?A, f : A -> ?B) : ?B {
+    switch(x) {
+      case (?x_) {
+        f(x_);
+      };
+      case (null) {
+        null;
+      };
+    };
+  };
+
+  /// Given an optional optional value, removes one layer of optionality.
+  /// ```motoko
+  /// import Option "mo:base/Option";
+  /// assert Option.flatten(?(?(42))) == ?42;
+  /// assert Option.flatten(?(null)) == null;
+  /// assert Option.flatten(null) == null;
+  /// ```
+  public func flatten<A>(x : ??A) : ?A {
+    chain<?A, A>(x, func (x_ : ?A) : ?A {
+      x_;
+    });
+  };
+
+  /// Creates an optional value from a definite value.
+  /// ```motoko
+  /// import Option "mo:base/Option";
+  /// assert Option.make(42) == ?42;
+  /// ```
+  public func make<A>(x: A) : ?A = ?x;
+
+  /// Returns true if the argument is not `null`, otherwise returns false.
+  public func isSome(x : ?Any) : Bool =
+    switch x {
+      case null { false };
+      case _ { true };
+    };
+
+  /// Returns true if the argument is `null`, otherwise returns false.
+  public func isNull(x : ?Any) : Bool =
+    switch x {
+      case null { true };
+      case _ { false };
+    };
+
+  /// Asserts that the value is not `null`; fails otherwise.
+  /// @deprecated Option.assertSome will be removed soon; use an assert expression instead
+  public func assertSome(x : ?Any) =
+    switch x {
+      case null { P.unreachable() };
+      case _ {};
+    };
+
+  /// Asserts that the value _is_ `null`; fails otherwise.
+  /// @deprecated Option.assertNull will be removed soon; use an assert expression instead
+  public func assertNull(x : ?Any) =
+    switch x {
+      case null { };
+      case _ { P.unreachable() };
+    };
+
+  /// Unwraps an optional value, i.e. `unwrap(?x) = x`.
+  ///
+  /// @deprecated Option.unwrap is unsafe and fails if the argument is null; it will be removed soon; use a `switch` or `do?` expression instead
+  public func unwrap<T>(x : ?T) : T =
+    switch x {
+      case null { P.unreachable() };
+      case (?x_) { x_ };
+    };
+}

package/.mops/base@0.7.4/src/Order.mo

@@ -0,0 +1,46 @@
+/// Order
+
+module {
+
+  /// A type to represent an order.
+  public type Order = {
+    #less;
+    #equal;
+    #greater;
+  };
+
+  /// Check if an order is #less.
+  public func isLess(order : Order) : Bool {
+    switch order {
+      case (#less) { true };
+      case _ { false };
+    };
+  };
+
+  /// Check if an order is #equal.
+  public func isEqual(order : Order) : Bool {
+    switch order {
+      case (#equal) { true };
+      case _ { false };
+    };
+  };
+
+  /// Check if an order is #greater.
+  public func isGreater(order : Order) : Bool {
+    switch order {
+      case (#greater) { true };
+      case _ { false };
+    };
+  };
+
+  /// Returns true if only if  `o1` and `o2` are the same ordering.
+  public func equal(o1 : Order, o2: Order) : Bool {
+    switch (o1, o2) {
+      case (#less, #less) { true };
+      case (#equal, #equal) { true };
+      case (#greater, #greater) { true };
+      case _ { false };
+    };
+  };
+
+};

package/.mops/base@0.7.4/src/Prelude.mo

@@ -0,0 +1,33 @@
+/// General utilities
+///
+/// This prelude file proposes standard library features that _may_
+/// belong in the _language_ (compiler-internal) prelude sometime, after
+/// some further experience and discussion.  Until then, they live here.
+
+import Debug "Debug";
+
+module {
+
+  /// Not yet implemented
+  ///
+  /// Mark incomplete code with the `nyi` and `xxx` functions.
+  ///
+  /// Each have calls are well-typed in all typing contexts, which
+  /// trap in all execution contexts.
+  public func nyi() : None {
+    Debug.trap("Prelude.nyi()");
+  };
+
+  public func xxx() : None {
+    Debug.trap("Prelude.xxx()");
+  };
+
+  /// Mark unreachable code with the `unreachable` function.
+  ///
+  /// Calls are well-typed in all typing contexts, and they
+  /// trap in all execution contexts.
+  public func unreachable() : None {
+    Debug.trap("Prelude.unreachable()")
+  };
+
+}

package/.mops/base@0.7.4/src/Principal.mo

@@ -0,0 +1,58 @@
+/// IC principals (user and canister smart contract IDs)
+
+import Prim "mo:⛔";
+import Blob "Blob";
+import Hash "Hash";
+module {
+
+  /// Internet Computer principal identifiers.
+  /// Convert to `Blob` for access to bytes.
+  public type Principal = Prim.Types.Principal;
+
+  /// Conversion.
+  public let fromActor : (a : actor {}) -> Principal = Prim.principalOfActor;
+
+  /// Conversion.
+  public let toBlob : (p : Principal) -> Blob = Prim.blobOfPrincipal;
+
+  /// Conversion.
+  public let fromBlob : (b : Blob) -> Principal = Prim.principalOfBlob;
+  
+  /// Conversion.
+  public func toText(p : Principal) : Text = debug_show(p);
+
+  private let anonymousPrincipal : Blob = "\04";
+
+  public func isAnonymous(p : Principal) : Bool =
+    Prim.blobOfPrincipal p == anonymousPrincipal;
+
+  public func hash(principal : Principal) : Hash.Hash =
+    Blob.hash (Prim.blobOfPrincipal(principal));
+
+  public func fromText(t : Text) : Principal = fromActor(actor(t));
+
+  /// Returns `x == y`.
+  public func equal(x : Principal, y : Principal) : Bool { x == y };
+
+  /// Returns `x != y`.
+  public func notEqual(x : Principal, y : Principal) : Bool { x != y };
+
+  /// Returns `x < y`.
+  public func less(x : Principal, y : Principal) : Bool { x < y };
+
+  /// Returns `x <= y`.
+  public func lessOrEqual(x : Principal, y : Principal) : Bool { x <= y };
+
+  /// Returns `x > y`.
+  public func greater(x : Principal, y : Principal) : Bool { x > y };
+
+  /// Returns `x >= y`.
+  public func greaterOrEqual(x : Principal, y : Principal) : Bool { x >= y };
+
+  /// Returns the order of `x` and `y`.
+  public func compare(x : Principal, y : Principal) : { #less; #equal; #greater } {
+    if (x < y) { #less }
+    else if (x == y) { #equal }
+    else { #greater }
+  };
+}

package/.mops/base@0.7.4/src/RBTree.mo

@@ -0,0 +1,218 @@
+/// Red-Black Trees
+
+import Debug "Debug";
+import I "Iter";
+import List "List";
+import Nat "Nat";
+import O "Order";
+
+module {
+
+  /// Node color: red or black.
+  public type Color = { #R; #B };
+
+  /// Ordered, (red-black) tree of entries.
+  public type Tree<X, Y> = {
+    #node : (Color, Tree<X, Y>, (X, ?Y), Tree<X, Y>);
+    #leaf;
+  };
+
+  /// Create an order map from an order function for its keys.
+  public class RBTree<X, Y>(compareTo : (X, X) -> O.Order) {
+
+    var tree : Tree<X, Y> = (#leaf : Tree<X, Y>);
+
+    /// Tree as sharable data.
+    ///
+    /// Get non-OO, purely-functional representation:
+    /// for drawing, pretty-printing and non-OO contexts
+    /// (e.g., async args and results):
+    public func share() : Tree<X, Y> {
+      tree
+    };
+
+    /// Get the value associated with a given key.
+    public func get(x : X) : ?Y {
+      getRec(x, compareTo, tree);
+    };
+
+    /// Replace the value associated with a given key.
+    public func replace(x : X, y : Y) : ?Y {
+      let (res, t) = insertRoot(x, compareTo, y, tree);
+      tree := t;
+      res
+    };
+
+    /// Put an entry: A value associated with a given key.
+    public func put(x : X, y : Y) {
+      let (res, t) = insertRoot(x, compareTo, y, tree);
+      tree := t;
+    };
+
+    /// Delete the entry associated with a given key.
+    public func delete(x : X) {
+      let (res, t) = removeRec(x, compareTo, tree);
+      tree := t
+    };
+
+    /// Remove the entry associated with a given key.
+    public func remove(x : X) : ?Y {
+      let (res, t) = removeRec(x, compareTo, tree);
+      tree := t;
+      res
+    };
+
+    /// An iterator for the key-value entries of the map, in ascending key order.
+    ///
+    /// iterator is persistent, like the tree itself
+    public func entries() : I.Iter<(X, Y)> { iter(tree, #fwd) };
+
+    /// An iterator for the key-value entries of the map, in descending key order.
+    ///
+    /// iterator is persistent, like the tree itself
+    public func entriesRev() : I.Iter<(X, Y)> { iter(tree, #bwd) };
+
+  };
+
+
+  type IterRep<X, Y> = List.List<{ #tr:Tree<X, Y>; #xy:(X, ?Y) }>;
+
+  /// An iterator for the entries of the map, in ascending (`#fwd`) or descending (`#bwd`) order.
+  public func iter<X, Y>(t : Tree<X, Y>, dir : { #fwd; #bwd }) : I.Iter<(X, Y)> {
+    object {
+      var trees : IterRep<X, Y> = ?(#tr(t), null);
+      public func next() : ?(X, Y) {
+        switch (dir, trees) {
+          case (_, null) { null };
+          case (_, ?(#tr(#leaf), ts)){
+            trees := ts;
+            next()
+          };
+          case (_, ?(#xy(xy), ts)) {
+            trees := ts;
+            switch (xy.1) {
+              case null { next() };
+              case (?y) { ?(xy.0, y) }
+            }
+          };
+          case (#fwd, ?(#tr(#node(_, l, xy, r)), ts)) {
+            trees := ?(#tr(l), ?(#xy(xy), ?(#tr(r), ts)));
+            next()
+          };
+          case (#bwd, ?(#tr(#node(_, l, xy, r)), ts)) {
+            trees := ?(#tr(r), ?(#xy(xy), ?(#tr(l), ts)));
+            next()
+          };
+        }
+      };
+    }
+  };
+
+  /// Remove the value associated with a given key.
+  func removeRec<X, Y>(x : X, compareTo : (X, X) -> O.Order, t : Tree<X, Y>)
+    : (?Y, Tree<X, Y>) {
+    switch t {
+      case (#leaf) { (null, #leaf) };
+      case (#node(c, l, xy, r)) {
+        switch (compareTo(x, xy.0)) {
+          case (#less) {
+            let (yo, l2) = removeRec(x, compareTo, l);
+            (yo, #node(c, l2, xy, r))
+          };
+          case (#equal) {
+            (xy.1, #node(c, l, (x, null), r))
+          };
+          case (#greater) {
+            let (yo, r2) = removeRec(x, compareTo, r);
+            (yo, #node(c, l, xy, r2))
+          };
+        }
+      }
+    }
+  };
+
+
+
+  func bal<X, Y>(color : Color, lt : Tree<X, Y>, kv : (X, ?Y), rt : Tree<X, Y>) : Tree<X, Y> {
+    // thank you, algebraic pattern matching!
+    // following notes from [Ravi Chugh](https://www.classes.cs.uchicago.edu/archive/2019/spring/22300-1/lectures/RedBlackTrees/index.html)
+    switch (color, lt, kv, rt) {
+      case (#B, #node(#R, #node(#R, a, x, b), y, c), z, d) {
+        #node(#R, #node(#B, a, x, b), y, #node(#B, c, z, d))
+      };
+      case (#B, #node(#R, a, x, #node(#R, b, y, c)), z, d) {
+        #node(#R, #node(#B, a, x, b), y, #node(#B, c, z, d))
+      };
+      case (#B, a, x, #node(#R, #node(#R, b, y, c), z, d)) {
+        #node(#R, #node(#B, a, x, b), y, #node(#B, c, z, d))
+      };
+      case (#B, a, x, #node(#R, b, y, #node(#R, c, z, d))) {
+        #node(#R, #node(#B, a, x, b), y, #node(#B, c, z, d))
+      };
+      case _ { #node(color, lt, kv, rt) };
+    }
+  };
+
+  func insertRoot<X, Y>(x : X, compareTo : (X, X) -> O.Order, y : Y, t : Tree<X, Y>)
+    : (?Y, Tree<X, Y>) {
+    switch (insertRec(x, compareTo, y, t)) {
+      case (_, #leaf) { assert false; loop { } };
+      case (yo, #node(_, l, xy, r)) { (yo, #node(#B, l, xy, r)) };
+    }
+  };
+
+  func insertRec<X, Y>(x : X, compareTo : (X, X) -> O.Order, y : Y, t : Tree<X, Y>)
+    : (?Y, Tree<X, Y>) {
+    switch t {
+      case (#leaf) { (null, #node(#R, #leaf, (x, ?y), #leaf)) };
+      case (#node(c, l, xy, r)) {
+        switch (compareTo(x, xy.0)) {
+          case (#less) {
+            let (yo, l2) = insertRec(x, compareTo, y, l);
+            (yo, bal(c, l2, xy, r))
+          };
+          case (#equal) {
+            (xy.1, #node(c, l, (x, ?y), r))
+          };
+          case (#greater) {
+            let (yo, r2) = insertRec(x, compareTo, y, r);
+            (yo, bal(c, l, xy, r2))
+          };
+        }
+      }
+    }
+  };
+
+  func getRec<X, Y>(x : X, compareTo : (X, X) -> O.Order, t : Tree<X, Y>) : ?Y {
+    switch t {
+      case (#leaf) { null };
+      case (#node(c, l, xy, r)) {
+        switch (compareTo(x, xy.0)) {
+          case (#less) { getRec(x, compareTo, l) };
+          case (#equal) { xy.1 };
+          case (#greater) { getRec(x, compareTo, r) };
+        }
+      };
+    }
+  };
+
+  func height<X, Y>(t : Tree<X, Y>) : Nat {
+    switch t {
+      case (#leaf) { 0 };
+      case (#node(_, l, _, r)) {
+        Nat.max(height(l), height(r)) + 1
+      }
+    }
+  };
+
+  /// The size of the tree as the number of key-value entries.
+  public func size<X, Y>(t : Tree<X, Y>) : Nat {
+    switch t {
+      case (#leaf) { 0 };
+      case (#node(_, l, xy, r)) {
+        size(l) + size(r) + (switch (xy.1) { case null 0; case _ 1 });
+      };
+    }
+  };
+
+}

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

@@ -0,0 +1,188 @@
+/// 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.
+
+import I "Iter";
+import Option "Option";
+import P "Prelude";
+import Prim "mo:⛔";
+
+module {
+
+  /// 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.
+  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.
+    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 = 0x80 : 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).
+    public func coin() : ?Bool {
+      bit.next()
+    };
+
+    /// Uniformly distributes outcomes in the numeric range [0 .. 2^p - 1].
+    /// Consumes ⌈p/8⌉ bytes of entropy.
+    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
+      };
+      null
+    };
+
+    /// Counts the number of heads in `n` fair coin tosses.
+    /// Consumes ⌈p/8⌉ bytes of entropy.
+    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
+      };
+      null
+    }
+  };
+
+  let raw_rand = (actor "aaaaa-aa" : actor { raw_rand : () -> async Blob }).raw_rand;
+
+  /// Distributes outcomes in the numeric range [0 .. 255].
+  /// Seed blob must contain at least a byte.
+  public func byteFrom(seed : Blob) : Nat8 {
+    switch (seed.vals().next()) {
+      case (?w) { w };
+      case _ { P.unreachable() };
+    }
+  };
+
+  /// Simulates a coin toss.
+  /// Seed blob must contain at least a byte.
+  public func coinFrom(seed : Blob) : Bool {
+    switch (seed.vals().next()) {
+      case (?w) { w > (127 : Nat8) };
+      case _ { P.unreachable() };
+    }
+  };
+
+  /// Obtains a full blob (32 bytes) worth of fresh entropy.
+  public let blob : shared () -> async Blob = raw_rand;
+
+  /// Distributes outcomes in the numeric range [0 .. 2^p - 1].
+  /// Seed blob must contain at least ((p+7) / 8) bytes.
+  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
+    };
+    P.unreachable()
+  };
+
+  /// Counts the number of heads in `n` coin tosses.
+  /// Seed blob must contain at least ((n+7) / 8) bytes.
+  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
+    };
+    P.unreachable()
+  }
+
+}