OrderedMap/Set: fix docs

serokell · Nov 8, 2024 · 41a747e · 41a747e
1 parent a104c88
commit 41a747e
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 28 deletions.
diff --git a/src/OrderedMap.mo b/src/OrderedMap.mo
@@ -116,11 +116,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// 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.
-    ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    ///    
+    /// Note: The returned map shares with the `m` most of the tree nodes. 
+    /// Garbage collecting one of maps (e.g. after an assignment `m := natMap.put(m, k)`)
+    /// causes collecting `O(log(n))` nodes.
     public func put<V>(m : Map<K, V>, key : K, value : V) : Map<K, V>
       = replace(m, key, value).0;
 
@@ -153,11 +155,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// Space: `O(log(n))` retained memory plus garbage, see the note below.
     /// where `n` denotes the number of key-value entries stored in the map and
     /// assuming that the `compare` function implements an `O(1)` comparison.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: The returned map shares with the `m` most of the tree nodes. 
+    /// Garbage collecting one of maps (e.g. after an assignment `m := natMap.replace(m, k).0`)
+    /// causes collecting `O(log(n))` nodes.
     public func replace<V>(m : Map<K, V>, key : K, value : V) : (Map<K, V>, ?V) {
       switch (Internal.replace(m.root, compare, key, value)) {
         case (t, null) { ({root = t; size = m.size + 1}, null) };
@@ -192,12 +196,12 @@ module {
     /// // [(1, "Twenty One"), (2, "Twenty Two")]
     /// ```
     ///
-    /// Runtime: `O(n)`.
+    /// Runtime: `O(n * log(n))`.
     /// Space: `O(n)` retained memory plus garbage, see the note below.
     /// where `n` denotes the number of key-value entries stored in the map and
     /// assuming that the `compare` function implements an `O(1)` comparison.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
     public func mapFilter<V1, V2>(m : Map<K, V1>, f : (K, V1) -> ?V2) : Map<K, V2>
       = Internal.mapFilter(m, compare, f);
 
@@ -310,11 +314,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// 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.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: The returned map shares with the `m` most of the tree nodes. 
+    /// Garbage collecting one of maps (e.g. after an assignment `m := natMap.delete(m, k).0`)
+    /// causes collecting `O(log(n))` nodes.
     public func delete<V>(m : Map<K, V>, key : K) : Map<K, V>
       = remove(m, key).0;
 
@@ -347,11 +353,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// 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.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: The returned map shares with the `m` most of the tree nodes. 
+    /// Garbage collecting one of maps (e.g. after an assignment `m := natMap.remove(m, k)`)
+    /// causes collecting `O(log(n))` nodes.
     public func remove<V>(m : Map<K, V>, key : K) : (Map<K, V>, ?V) {
       switch (Internal.remove(m.root, compare, key)) {
         case (t, null) { ({root = t; size = m.size }, null) };

diff --git a/src/OrderedSet.mo b/src/OrderedSet.mo
@@ -118,11 +118,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// Space: `O(log(n))`.
     /// where `n` denotes the number of key-value entries stored in the set and
     /// assuming that the `compare` function implements an `O(1)` comparison.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: The returned set shares with the `s` most of the tree nodes. 
+    /// Garbage collecting one of sets (e.g. after an assignment `m := natSet.delete(m, k)`)
+    /// causes collecting `O(log(n))` nodes.
     public func put(s : Set<T>, value : T) : Set<T> 
       = Internal.put(s, compare, value);
 
@@ -145,11 +147,13 @@ module {
     /// ```
     ///
     /// Runtime: `O(log(n))`.
-    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// 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.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: The returned set shares with the `s` most of the tree nodes. 
+    /// Garbage collecting one of sets (e.g. after an assignment `m := natSet.delete(m, k)`)
+    /// causes collecting `O(log(n))` nodes.
     public func delete(s : Set<T>, value : T) : Set<T> 
       = Internal.delete(s, compare, value);
 
@@ -172,8 +176,6 @@ module {
     /// Space: `O(1)` retained memory plus garbage, see the note below.
     /// where `n` denotes the number of elements stored in the set and
     /// assuming that the `compare` function implements an `O(1)` comparison.
-    ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
     public func contains(s : Set<T>, value : T) : Bool 
       = Internal.contains(s.root, compare, value);
 
@@ -239,10 +241,10 @@ module {
     /// ```
     ///
     /// Runtime: `O(m * log(n))`.
-    /// Space: `O(1)`, retained memory plus garbage, see the note below.
+    /// Space: `O(m)`, retained memory plus garbage, see the note below.
     /// where `m` and `n` denote the number of elements in the sets, and `m <= n`.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: Creates `O(m * log(n))` temporary objects that will be collected as garbage.
     public func union(s1 : Set<T>, s2 : Set<T>) : Set<T> {
       if (size(s1) < size(s2)) {
         foldLeft(s1, s2, func(elem : T, acc : Set<T>) : Set<T> { Internal.put(acc, compare, elem) })
@@ -272,7 +274,7 @@ module {
     /// Space: `O(m)`, retained memory plus garbage, see the note below.
     /// where `m` and `n` denote the number of elements in the sets, and `m <= n`.
     ///
-    /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
+    /// Note: Creates `O(m)` temporary objects that will be collected as garbage.
     public func intersect(s1 : Set<T>, s2 : Set<T>) : Set<T> {
       let elems = Buffer.Buffer<T>(Nat.min(Nat.min(s1.size, s2.size), 100));
       if (s1.size < s2.size) {
@@ -357,9 +359,11 @@ module {
     /// ```
     ///
     /// Cost of mapping all the elements:
-    /// Runtime: `O(n)`.
+    /// Runtime: `O(n * log(n))`.
     /// Space: `O(n)` retained memory
     /// where `n` denotes the number of elements stored in the set.
+    ///
+    /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
     public func map<T1>(s : Set<T1>, f : T1 -> T) : Set<T>
       = Internal.foldLeft(s.root, empty(), func (elem : T1, acc : Set<T>) : Set<T> { Internal.put(acc, compare, f(elem)) });
 
@@ -389,12 +393,12 @@ module {
     /// // [2, 4, 6]
     /// ```
     ///
-    /// Runtime: `O(n)`.
+    /// Runtime: `O(n * log(n))`.
     /// Space: `O(n)` retained memory plus garbage, see the note below.
     /// where `n` denotes the number of elements stored in the set and
     /// assuming that the `compare` function implements an `O(1)` comparison.
     ///
-    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
     public func mapFilter<T1>(s : Set<T1>, f : T1 -> ?T) : Set<T> {
       func combine(elem : T1, acc : Set<T>) : Set<T> {
         switch (f(elem)) {
@@ -427,8 +431,6 @@ module {
     /// Space: `O(1)` retained memory plus garbage, see the note below.
     /// where `m` and `n` denote the number of elements stored in the sets set1 and set2, respectively,
     /// and assuming that the `compare` function implements an `O(1)` comparison.
-    ///
-    /// Note: Creates `O(m * log(n))` temporary objects that will be collected as garbage.
     public func isSubset(s1 : Set<T>, s2 : Set<T>) : Bool {
       if (s1.size > s2.size) { return false };
       isSubsetHelper(s1.root, s2.root)
@@ -455,8 +457,6 @@ module {
     /// Space: `O(1)` retained memory plus garbage, see the note below.
     /// where `m` and `n` denote the number of elements stored in the sets set1 and set2, respectively,
     /// and assuming that the `compare` function implements an `O(1)` comparison.
-    ///
-    /// Note: Creates `O(m * log(n))` temporary objects that will be collected as garbage.
     public func equals(s1 : Set<T>, s2 : Set<T>) : Bool {
       if (s1.size != s2.size) { return false };
       isSubsetHelper(s1.root, s2.root)
@@ -644,7 +644,7 @@ module {
     /// ```
     ///
     /// Runtime: `O(1)`.
-    /// Space: `O(1)`
+    /// Space: `O(1)`.
     public func isEmpty(s : Set<T>) : Bool {
       switch (s.root) {
         case (#leaf) { true };