document union_with, insert_with and flatten_with changes.

Author: KtorZ

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v3.0.0 - UNRELEASED
+
+### Added
+
+- [`aiken/collection/list.{foldl2}`](https://aiken-lang.github.io/stdlib/aiken/collection/list.html#foldl2): to left-fold over lists while accumulating two separate results. This is reasonably faster than constructing a list of pairs.
+
+- [`aiken/collection/list.{foldr2}`](https://aiken-lang.github.io/stdlib/aiken/collection/list.html#foldr2): to right-fold over lists while accumulating two separate results. This is reasonably faster than constructing a list of pairs.
+
+### Changed
+
+- <sup>⚠️ BREAKING-CHANGE ⚠️</sup> [`aiken/collection/dict.{insert_with}`](https://aiken-lang.github.io/stdlib/aiken/collection/dict.html#insert_with), [`aiken/collection/dict.{union_with}`](https://aiken-lang.github.io/stdlib/aiken/collection/dict.html#union_with) and [`cardano/assets.{flatten_with}`](https://aiken-lang.github.io/stdlib/cardano/assets.html#flatten_with) have a reworked API using two callbacks instead of a single callback returning `Option`. These gives them better performances, alongside a few other functions using them internally. To ease the construction of the callbacks, new modules with callback strategies have been created:
+    - [`aiken/collection/dict/strategy`](https://aiken-lang.github.io/stdlib/aiken/collection/dict/strategy.html)
+    - [`cardano/assets/strategy`](https://aiken-lang.github.io/stdlib/cardano/assets/strategy.html)
+
+
+
 ## v2.2.0 - 2024-12-13
 
 ### Added

lib/aiken/collection/dict.ak

@@ -13,7 +13,7 @@
 //// > [`dict.from_ascending_list`](#from_ascending_list).
 
 use aiken/builtin
-use aiken/collection/dict/union.{UnionStrategy}
+use aiken/collection/dict/strategy.{UnionStrategy}
 
 /// An opaque `Dict`. The type is opaque because the module maintains some
 /// invariant, namely: there's only one occurrence of a given key in the dictionary.
@@ -162,7 +162,7 @@ fn do_from_pairs(xs: Pairs<ByteArray, value>) -> Pairs<ByteArray, value> {
   when xs is {
     [] -> []
     [Pair(k, v), ..rest] ->
-      do_insert_with(do_from_pairs(rest), k, v, union.keep_left())
+      do_insert_with(do_from_pairs(rest), k, v, strategy.keep_left())
   }
 }
 
@@ -734,9 +734,9 @@ test insert_2() {
 ///
 /// let result =
 ///   dict.empty
-///     |> dict.insert_with(key: "a", value: 1, with: union.sum())
-///     |> dict.insert_with(key: "b", value: 2, with: union.sum())
-///     |> dict.insert_with(key: "a", value: 3, with: union.sum())
+///     |> dict.insert_with(key: "a", value: 1, with: strategy.sum())
+///     |> dict.insert_with(key: "b", value: 2, with: strategy.sum())
+///     |> dict.insert_with(key: "a", value: 3, with: strategy.sum())
 ///     |> dict.to_pairs()
 ///
 /// result == [Pair("a", 4), Pair("b", 2)]
@@ -760,8 +760,8 @@ pub fn insert_with(
 test insert_with_1() {
   let result =
     empty
-      |> insert_with(key: "foo", value: 1, with: union.sum())
-      |> insert_with(key: "bar", value: 2, with: union.sum())
+      |> insert_with(key: "foo", value: 1, with: strategy.sum())
+      |> insert_with(key: "bar", value: 2, with: strategy.sum())
       |> to_pairs()
 
   result == [Pair("bar", 2), Pair("foo", 1)]
@@ -770,9 +770,9 @@ test insert_with_1() {
 test insert_with_2() {
   let result =
     empty
-      |> insert_with(key: "foo", value: 1, with: union.sum())
-      |> insert_with(key: "bar", value: 2, with: union.sum())
-      |> insert_with(key: "foo", value: 3, with: union.sum())
+      |> insert_with(key: "foo", value: 1, with: strategy.sum())
+      |> insert_with(key: "bar", value: 2, with: strategy.sum())
+      |> insert_with(key: "foo", value: 3, with: strategy.sum())
       |> to_pairs()
 
   result == [Pair("bar", 2), Pair("foo", 4)]
@@ -1065,7 +1065,7 @@ test union_with_1() {
       |> insert(bar, 42)
       |> insert(foo, 1337)
 
-  let result = union_with(left, right, with: union.sum())
+  let result = union_with(left, right, with: strategy.sum())
 
   result == from_pairs([Pair(foo, 1351), Pair(bar, 42)])
 }

lib/aiken/collection/dict/union.ak lib/aiken/collection/dict/strategy.ak

@@ -11,30 +11,61 @@ pub type KeepValue<key, value> =
 pub type DiscardValue<key, value> =
   fn() -> Pairs<key, value>
 
+// ### Union Strategies
+
 /// A strategy which always fail, enforcing the dict contains no duplicate.
+///
+/// ```aiken
+/// fn(_, _, _, _, _) {
+///   fail @"unexpected duplicate key found in dict."
+/// }
+/// ```
 pub fn expect_no_duplicate() -> UnionStrategy<key, value> {
   fn(_, _, _, _, _) {
     fail @"unexpected duplicate key found in dict."
   }
 }
 
 /// Combine values by keeping the values present in the left-most dict.
+///
+/// ```aiken
+/// fn(_key, left, _right, keep, _discard) { keep(left) }
+/// ```
 pub fn keep_left() -> UnionStrategy<key, value> {
   fn(_key, left, _right, keep, _discard) { keep(left) }
 }
 
-/// Combine values by keeping the values present in the left-most dict.
+/// Combine values by keeping the values present in the right-most dict.
+///
+/// ```aiken
+/// fn(_key, _left, right, keep, _discard) { keep(right) }
+/// ```
 pub fn keep_right() -> UnionStrategy<key, value> {
   fn(_key, _left, right, keep, _discard) { keep(right) }
 }
 
 /// Combine values by taking their sum.
+///
+/// ```aiken
+/// fn(_key, left, right, keep, _discard) { keep(left + right) }
+/// ```
 pub fn sum() -> UnionStrategy<key, Int> {
   fn(_key, left, right, keep, _discard) { keep(left + right) }
 }
 
-/// Combine values by taking their sum, only if it is non-null. Otherwise,
-/// discard the key/value entirely.
+/// Combine values by taking their sum, only if it is non-null. If the
+/// resulting sum is 0, discard the key/value entirely.
+///
+/// ```aiken
+/// fn(_key, left, right, keep, discard) {
+///   let value = left + right
+///   if value == 0 {
+///     discard()
+///   } else {
+///     keep(value)
+///   }
+/// }
+/// ```
 pub fn sum_if_non_zero() -> UnionStrategy<key, Int> {
   fn(_key, left, right, keep, discard) {
     let value = left + right

lib/cardano/assets.ak

@@ -1,10 +1,10 @@
 use aiken/builtin
 use aiken/collection/dict.{Dict, from_ascending_pairs_with}
-use aiken/collection/dict/union as dict_union
+use aiken/collection/dict/strategy as dict_strategy
 use aiken/collection/list
 use aiken/crypto.{Blake2b_224, Hash, Script}
 use aiken/option
-use cardano/assets/union
+use cardano/assets/strategy.{FlattenStrategy}
 
 /// Lovelace is now a type wrapper for Int.
 pub type Lovelace =
@@ -79,7 +79,7 @@ pub fn from_asset_list(xs: Pairs<PolicyId, Pairs<AssetName, Int>>) -> Value {
           expect Pair(p, [_, ..] as x) = inner
           x
             |> from_ascending_pairs_with(fn(v) { v != 0 })
-            |> dict.insert_with(acc, p, _, dict_union.expect_no_duplicate())
+            |> dict.insert_with(acc, p, _, dict_strategy.expect_no_duplicate())
         },
       )
     |> Value
@@ -556,7 +556,7 @@ pub fn add(
             left,
             asset_name,
             quantity,
-            dict_union.sum_if_non_zero(),
+            dict_strategy.sum_if_non_zero(),
           )
 
         if dict.is_empty(inner_result) {
@@ -623,7 +623,7 @@ pub fn merge(left v0: Value, right v1: Value) -> Value {
       v0.inner,
       v1.inner,
       fn(_, a0, a1, keep, discard) {
-        let result = dict.union_with(a0, a1, dict_union.sum_if_non_zero())
+        let result = dict.union_with(a0, a1, dict_strategy.sum_if_non_zero())
         if dict.is_empty(result) {
           discard()
         } else {
@@ -793,10 +793,7 @@ pub fn flatten(self: Value) -> List<(PolicyId, AssetName, Int)> {
 /// Flatten a `Value` as a list of results, possibly discarding some along the way.
 ///
 /// When the transform function returns `None`, the result is discarded altogether.
-pub fn flatten_with(
-  self: Value,
-  with: union.UnionStrategy<result>,
-) -> List<result> {
+pub fn flatten_with(self: Value, with: FlattenStrategy<result>) -> List<result> {
   dict.foldr(
     self.inner,
     [],
@@ -819,7 +816,7 @@ pub fn flatten_with(
 }
 
 test flatten_with_1() {
-  flatten_with(zero, union.triple()) == []
+  flatten_with(zero, strategy.triple()) == []
 }
 
 test flatten_with_2() {

lib/cardano/assets/union.ak lib/cardano/assets/strategy.ak

@@ -1,7 +1,7 @@
 use aiken/crypto.{Blake2b_224, Hash, Script}
 
-/// A strategy for combining two values in a dictionnary that belong to the same key.
-pub type UnionStrategy<result> =
+/// A strategy for flattening an asset list.
+pub type FlattenStrategy<result> =
   fn(
     Hash<Blake2b_224, Script>,
     ByteArray,
@@ -19,8 +19,16 @@ pub type KeepResult<result> =
 pub type DiscardResult<result> =
   fn() -> List<result>
 
-/// Combine values by keeping them in a 3-tuple.
-pub fn triple() -> UnionStrategy<(Hash<Blake2b_224, Script>, ByteArray, Int)> {
+// ### Flatten strategies
+
+/// Keep all assets, combining them as a 3-tuple.
+///
+/// ```aiken
+/// fn(policy_id, asset_name, quantity, keep, _discard) {
+///   keep((policy_id, asset_name, quantity))
+/// }
+/// ```
+pub fn triple() -> FlattenStrategy<(Hash<Blake2b_224, Script>, ByteArray, Int)> {
   fn(policy_id, asset_name, quantity, keep, _discard) {
     keep((policy_id, asset_name, quantity))
   }