experiment: conditionally deprecate types and values for caffeine using #M0235

src/Array.mo

@@ -397,6 +397,7 @@ module {
   /// Space: O(size)
   ///
   /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// @deprecated M0235
   public func mapResult<T, R, E>(self : [T], f : T -> Types.Result<R, E>) : Types.Result<[R], E> {
     let size = self.size();
 

src/Float.mo

@@ -462,6 +462,7 @@ module {
   /// ```motoko include=import
   /// assert Float.fromInt(-123) == -123.0;
   /// ```
+  /// @deprecated M0235
   public func fromInt(x : Int) : Float = Prim.intToFloat(x);
 
   /// Determines whether `x` is equal to `y` within the defined tolerance of `epsilon`.

src/List.mo

@@ -118,6 +118,7 @@ module {
   /// Runtime: `O(size)`
   ///
   /// Space: `O(size)`
+  /// @deprecated M0235
   public func toPure<T>(self : List<T>) : PureList.List<T> {
     var result : PureList.List<T> = null;
 
@@ -158,6 +159,7 @@ module {
   /// Runtime: `O(size)`
   ///
   /// Space: `O(size)`
+  /// @deprecated M0235
   public func fromPure<T>(pure : PureList.List<T>) : List<T> {
     var p = pure;
     var list = empty<T>();
@@ -978,6 +980,7 @@ module {
   /// Runtime: `O(1)`
   ///
   /// Space: `O(1)`
+  /// @deprecated M0235
   public func get<T>(self : List<T>, index : Nat) : ?T {
     // inlined version of locate
     let (a, b) = do {

src/Map.mo

@@ -76,6 +76,7 @@ module {
   /// assuming that the `compare` function implements an `O(1)` comparison.
   ///
   /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
+  /// @deprecated M0235
   public func toPure<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order)) : PureMap.Map<K, V> {
     PureMap.fromIter(entries(self), compare)
   };
@@ -101,6 +102,7 @@ module {
   /// Space: `O(n)`.
   /// where `n` denotes the number of key-value entries stored in the map and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func fromPure<K, V>(map : PureMap.Map<K, V>, compare : (implicit : (K, K) -> Order.Order)) : Map<K, V> {
     fromIter(PureMap.entries(map), compare)
   };
@@ -385,6 +387,7 @@ module {
   /// Space: `O(log(n))`.
   /// where `n` denotes the number of key-value entries stored in the map and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func insert<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order), key : K, value : V) : Bool {
     switch (swap(self, compare, key, value)) {
       case null true;
@@ -445,6 +448,7 @@ module {
   /// Space: `O(log(n))`.
   /// where `n` denotes the number of key-value entries stored in the map and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func swap<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order), key : K, value : V) : ?V {
     let insertResult = switch (self.root) {
       case (#leaf(leafNode)) {
@@ -510,6 +514,7 @@ module {
   /// Space: `O(log(n))`.
   /// where `n` denotes the number of key-value entries stored in the map and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func replace<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order), key : K, value : V) : ?V {
     // TODO: Could be optimized in future
     if (containsKey(self, compare, key)) {
@@ -576,6 +581,7 @@ module {
   /// assuming that the `compare` function implements an `O(1)` comparison.
   ///
   /// Note: Creates `O(log(n))` objects that will be collected as garbage.
+  /// @deprecated M0235
   public func delete<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order), key : K) : Bool {
     switch (take(self, compare, key)) {
       case null false;
@@ -610,6 +616,7 @@ module {
   /// assuming that the `compare` function implements an `O(1)` comparison.
   ///
   /// Note: Creates `O(log(n))` objects that will be collected as garbage.
+  /// @deprecated M0235
   public func take<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order), key : K) : ?V {
     let deletedValue = switch (self.root) {
       case (#leaf(leafNode)) {
@@ -1252,6 +1259,7 @@ module {
   /// Internal sanity check function.
   /// Can be used to check that key/value pairs have been inserted with a consistent key comparison function.
   /// Traps if the internal map structure is invalid.
+  /// @deprecated M0235
   public func assertValid<K, V>(self : Map<K, V>, compare : (implicit : (K, K) -> Order.Order)) {
     func checkIteration(iterator : Types.Iter<(K, V)>, order : Order.Order) {
       switch (iterator.next()) {

src/Nat.mo

@@ -75,6 +75,7 @@ module {
   /// ```motoko include=import
   /// assert Nat.fromInt(1234) == (1234 : Nat);
   /// ```
+  /// @deprecated M0235
   public func fromInt(int : Int) : Nat {
     if (int < 0) {
       Runtime.trap("Nat.fromInt(): negative input value")

src/Nat16.mo

@@ -48,6 +48,7 @@ module {
   /// ```motoko include=import
   /// assert Nat16.fromNat8(123) == (123 : Nat16);
   /// ```
+  /// @deprecated M0235
   public func fromNat8(x : Nat8) : Nat16 {
     Prim.nat8ToNat16(x)
   };
@@ -72,6 +73,7 @@ module {
   /// ```motoko include=import
   /// assert Nat16.fromNat32(123) == (123 : Nat16);
   /// ```
+  /// @deprecated M0235
   public func fromNat32(x : Nat32) : Nat16 {
     Prim.nat32ToNat16(x)
   };

src/Nat32.mo

@@ -48,6 +48,7 @@ module {
   /// ```motoko include=import
   /// assert Nat32.fromNat16(123) == (123 : Nat32);
   /// ```
+  /// @deprecated M0235
   public func fromNat16(x : Nat16) : Nat32 {
     Prim.nat16ToNat32(x)
   };
@@ -72,6 +73,7 @@ module {
   /// ```motoko include=import
   /// assert Nat32.fromNat64(123) == (123 : Nat32);
   /// ```
+  /// @deprecated M0235
   public func fromNat64(x : Nat64) : Nat32 {
     Prim.nat64ToNat32(x)
   };

src/Nat64.mo

@@ -48,6 +48,7 @@ module {
   /// ```motoko include=import
   /// assert Nat64.fromNat32(123) == (123 : Nat64);
   /// ```
+  /// @deprecated M0235
   public func fromNat32(x : Nat32) : Nat64 {
     Prim.nat32ToNat64(x)
   };

src/Queue.mo

@@ -56,6 +56,7 @@ module {
   /// Runtime: O(n)
   /// Space: O(n)
   /// `n` denotes the number of elements stored in the queue.
+  /// @deprecated M0235
   public func toPure<T>(self : Queue<T>) : PureQueue.Queue<T> {
     let pureQueue = PureQueue.empty<T>();
     let iter = values(self);
@@ -84,6 +85,7 @@ module {
   /// Runtime: O(n)
   /// Space: O(n)
   /// `n` denotes the number of elements stored in the queue.
+  /// @deprecated M0235
   public func fromPure<T>(pureQueue : PureQueue.Queue<T>) : Queue<T> {
     let queue = empty<T>();
     let iter = PureQueue.values(pureQueue);

src/Random.mo

@@ -30,6 +30,7 @@ module {
 
   let rawRand = (actor "aaaaa-aa" : actor { raw_rand : () -> async Blob }).raw_rand;
 
+  /// @deprecated M0235
   public let blob : shared () -> async Blob = rawRand;
 
   /// Initializes a random number generator state. This is used
@@ -49,6 +50,7 @@ module {
   ///   }
   /// }
   /// ```
+  /// @deprecated M0235
   public func emptyState() : State = {
     var bytes = [];
     var index = 0;
@@ -73,6 +75,7 @@ module {
   ///   }
   /// }
   /// ```
+  /// @deprecated M0235
   public func seedState(seed : Nat64) : SeedState = {
     random = emptyState();
     prng = PRNG.init(seed)
@@ -87,6 +90,7 @@ module {
   /// let random = Random.seed(123);
   /// let coin = random.bool(); // true or false
   /// ```
+  /// @deprecated M0235
   public func seed(seed : Nat64) : Random {
     seedFromState(seedState(seed))
   };
@@ -108,6 +112,7 @@ module {
   ///   }
   /// }
   /// ```
+  /// @deprecated M0235
   public func seedFromState(state : SeedState) : Random {
     Random(
       state.random,
@@ -191,6 +196,7 @@ module {
     /// let random = Random.seed(42);
     /// let coin = random.bool(); // true or false
     /// ```
+    /// @deprecated M0235
     public func bool() : Bool {
       nextBit()
     };
@@ -202,6 +208,7 @@ module {
     /// let random = Random.seed(42);
     /// let byte = random.nat8(); // 0 to 255
     /// ```
+    /// @deprecated M0235
     public func nat8() : Nat8 {
       if (state.index >= state.bytes.size()) {
         let newBytes = Blob.toArray(generator());
@@ -257,6 +264,7 @@ module {
     /// let random = Random.seed(42);
     /// let number = random.nat64(); // 0 to 18446744073709551615
     /// ```
+    /// @deprecated M0235
     public func nat64() : Nat64 {
       (Nat64.fromNat(Nat8.toNat(nat8())) << 56) | (Nat64.fromNat(Nat8.toNat(nat8())) << 48) | (Nat64.fromNat(Nat8.toNat(nat8())) << 40) | (Nat64.fromNat(Nat8.toNat(nat8())) << 32) | (Nat64.fromNat(Nat8.toNat(nat8())) << 24) | (Nat64.fromNat(Nat8.toNat(nat8())) << 16) | (Nat64.fromNat(Nat8.toNat(nat8())) << 8) | Nat64.fromNat(Nat8.toNat(nat8()))
     };
@@ -268,6 +276,7 @@ module {
     /// let random = Random.seed(42);
     /// let dice = random.nat64Range(1, 7); // 1 to 6
     /// ```
+    /// @deprecated M0235
     public func nat64Range(fromInclusive : Nat64, toExclusive : Nat64) : Nat64 {
       if (fromInclusive >= toExclusive) {
         Runtime.trap("Random.nat64Range(): fromInclusive >= toExclusive")
@@ -282,13 +291,15 @@ module {
     /// let random = Random.seed(42);
     /// let index = random.natRange(0, 10); // 0 to 9
     /// ```
+    /// @deprecated M0235
     public func natRange(fromInclusive : Nat, toExclusive : Nat) : Nat {
       if (fromInclusive >= toExclusive) {
         Runtime.trap("Random.natRange(): fromInclusive >= toExclusive")
       };
       Nat64.toNat(uniform64(Nat64.fromNat(toExclusive - fromInclusive - 1))) + fromInclusive
     };
 
+    /// @deprecated M0235
     public func intRange(fromInclusive : Int, toExclusive : Int) : Int {
       let range = Nat.fromInt(toExclusive - fromInclusive - 1);
       Nat64.toNat(uniform64(Nat64.fromNat(range))) + fromInclusive

src/Region.mo

@@ -55,6 +55,7 @@ module {
 
   /// A stateful handle to an isolated region of IC stable memory.
   /// `Region` is a stable type and regions can be stored in stable variables.
+  /// @deprecated M0235
   public type Region = Prim.Types.Region;
 
   /// Allocate a new, isolated Region of size 0.

src/Result.mo

@@ -43,6 +43,7 @@ module {
   /// assert validateEmail("@domain.com") == #err("Username cannot be empty");
   /// assert validateEmail("user@invalid") == #err("Invalid domain format");
   /// ```
+  /// @deprecated M0235
   public type Result<Ok, Err> = Types.Result<Ok, Err>;
 
   /// Compares two Results for equality.

src/Set.mo

@@ -71,6 +71,7 @@ module {
   /// assuming that the `compare` function implements an `O(1)` comparison.
   ///
   /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
+  /// @deprecated M0235
   public func toPure<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order)) : PureSet.Set<T> {
     PureSet.fromIter(values(self), compare)
   };
@@ -95,6 +96,7 @@ module {
   /// Space: `O(n)`.
   /// where `n` denotes the number of elements stored in the set and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func fromPure<T>(set : PureSet.Set<T>, compare : (implicit : (T, T) -> Order.Order)) : Set<T> {
     fromIter(PureSet.values(set), compare)
   };
@@ -375,6 +377,7 @@ module {
   /// Space: `O(log(n))`.
   /// where `n` denotes the number of elements stored in the set and
   /// assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func insert<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order), element : T) : Bool {
     let insertResult = switch (self.root) {
       case (#leaf(leafNode)) {
@@ -469,6 +472,7 @@ module {
   /// assuming that the `compare` function implements an `O(1)` comparison.
   ///
   /// Note: Creates `O(log(n))` objects that will be collected as garbage.
+  /// @deprecated M0235
   public func delete<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order), element : T) : Bool {
     let deleted = switch (self.root) {
       case (#leaf(leafNode)) {
@@ -923,6 +927,7 @@ module {
   /// Space: `O(1)` retained memory plus garbage, see the note below.
   /// where `m` and `n` denote the number of elements in `set` and `iter`, respectively,
   /// and assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func deleteAll<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order), iter : Types.Iter<T>) : Bool {
     var deleted = false;
     for (element in iter) {
@@ -953,6 +958,7 @@ module {
   /// Space: `O(1)` retained memory plus garbage, see the note below.
   /// where `m` and `n` denote the number of elements in `set` and `iter`, respectively,
   /// and assuming that the `compare` function implements an `O(1)` comparison.
+  /// @deprecated M0235
   public func insertAll<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order), iter : Types.Iter<T>) : Bool {
     var inserted = false;
     for (element in iter) {
@@ -1356,6 +1362,7 @@ module {
   /// Internal sanity check function.
   /// Can be used to check that elements have been inserted with a consistent comparison function.
   /// Traps if the internal set structure is invalid.
+  /// @deprecated M0235
   public func assertValid<T>(self : Set<T>, compare : (implicit : (T, T) -> Order.Order)) {
     func checkIteration(iterator : Types.Iter<T>, order : Order.Order) {
       switch (iterator.next()) {

src/Stack.mo

@@ -59,6 +59,7 @@ module {
   /// Runtime: `O(1)`.
   /// Space: `O(1)`.
   /// where `n` denotes the number of elements stored in the stack.
+  /// @deprecated M0235
   public func toPure<T>(self : Stack<T>) : PureList.List<T> {
     self.top
   };
@@ -90,6 +91,7 @@ module {
   /// Runtime: `O(n)`.
   /// Space: `O(n)`.
   /// where `n` denotes the number of elements stored in the queue.
+  /// @deprecated M0235
   public func fromPure<T>(list : PureList.List<T>) : Stack<T> {
     var size = 0;
     var cur = list;

src/VarArray.mo

@@ -528,6 +528,7 @@ module {
   /// Space: O(size)
   ///
   /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// @deprecated M0235
   public func mapResult<T, R, E>(self : [var T], f : T -> Result.Result<R, E>) : Result.Result<[var R], E> {
     let size = self.size();
 

src/WeakReference.mo

@@ -11,6 +11,7 @@
 import Prim "mo:⛔"
 
 module {
+  //TODO: @deprecated M0235
   public type WeakReference<T> = {
     ref : weak T
   };

src/pure/List.mo

@@ -20,6 +20,7 @@ import Runtime "../Runtime";
 
 module {
 
+  /// @deprecated M0235
   public type List<T> = Types.Pure.List<T>;
 
   /// Create an empty list.

src/pure/Map.mo

@@ -60,6 +60,7 @@ import Runtime "../Runtime";
 
 module {
 
+  /// @deprecated M0235
   public type Map<K, V> = Types.Pure.Map<K, V>;
 
   type Tree<K, V> = Types.Pure.Map.Tree<K, V>;

src/pure/Queue.mo

@@ -36,6 +36,7 @@ import Array "../Array";
 import Prim "mo:⛔";
 
 module {
+  /// @deprecated M0235
   type List<T> = Types.Pure.List<T>;
 
   /// Double-ended queue data type.

src/pure/Set.mo

@@ -46,6 +46,8 @@ module {
   /// If type `T` is stable then `Set<T>` is also stable.
   /// To ensure that property the `Set<T>` does not have any methods,
   /// instead they are gathered in the functor-like class `Operations` (see example there).
+
+  /// @deprecated M0235
   public type Set<T> = Types.Pure.Set<T>;
 
   /// Red-black tree of nodes with ordered set elements.