improve module comments around dict and assets strategies.

Author: KtorZ

CHANGELOG.md

@@ -25,6 +25,7 @@
 ### Added
 
 - [`aiken/cbor.{deserialise}`](https://aiken-lang.github.io/stdlib/aiken/cbor.html#deserialise): to recover `Data` from CBOR bytes.
+
 - [`aiken/collection/pairs.{insert_with_by_ascending_key}`](https://aiken-lang.github.io/stdlib/aiken/collection/pairs.html#insert_with_by_ascending_key): for inserting in pairs while specifying how to combine values on key conflict.
 
 ## v2.1.0 - 2024-09-14

lib/aiken/collection/dict/strategy.ak

@@ -1,3 +1,5 @@
+//// This module contains strategies used to transform [`Dict`](../dict.html#Dict). You can safely ignore this module if you aren't using [`union_with`](../dict.html#union_with) nor [`insert_with`](../dict.html#insert_with).
+
 /// A strategy for combining two values in a dictionnary that belong to the same key.
 pub type UnionStrategy<key, value> =
   fn(key, value, value, KeepValue<key, value>, DiscardValue<key, value>) ->

lib/cardano/assets.ak

@@ -790,9 +790,11 @@ pub fn flatten(self: Value) -> List<(PolicyId, AssetName, Int)> {
   )
 }
 
-/// Flatten a `Value` as a list of results, possibly discarding some along the way.
+/// Flatten a `Value` as a list of results, possibly discarding some along the way. In particular, we have:
 ///
-/// When the transform function returns `None`, the result is discarded altogether.
+/// ```aiken
+/// flatten(value) === flatten_with(value, strategy.triple())
+/// ```
 pub fn flatten_with(self: Value, with: FlattenStrategy<result>) -> List<result> {
   dict.foldr(
     self.inner,

lib/cardano/assets/strategy.ak

@@ -1,3 +1,5 @@
+//// This module contains strategies used to transform [`Value`](../assets.html#Value). You can safely ignore this module if you aren't using [`flatten_with`](../assets.html#flatten_with).
+
 use aiken/crypto.{Blake2b_224, Hash, Script}
 
 /// A strategy for flattening an asset list.

lib/cardano/transaction.ak

@@ -128,8 +128,7 @@ pub type Redeemer =
 /// validator {
 ///   spend(datum, redeemer, my_output_reference, self) {
 ///     expect Some(input) =
-///       self.inputs
-///         |> transaction.find_input(my_output_reference)
+///       self.inputs |> transaction.find_input(my_output_reference)
 ///   }
 /// }
 /// ```
@@ -141,6 +140,29 @@ pub fn find_input(
     |> list.find(fn(input) { input.output_reference == output_reference })
 }
 
+/// Find the output corresponding to an output reference in a list of inputs.
+/// **Fails** when no matching output is found.
+///
+/// ```aiken
+/// validator {
+///   spend(datum, redeemer, my_output_reference, self) {
+///     let output =
+///       self.inputs |> transaction.resolve_input(my_output_reference)
+///   }
+/// }
+/// ```
+pub fn resolve_input(inputs: List<Input>, output_reference: OutputReference) -> Output {
+  when inputs is {
+    [] -> fail
+    [head, ..tail] ->
+      if head.output_reference == output_reference {
+        head.output
+      } else {
+        resolve_input(tail, output_reference)
+      }
+  }
+}
+
 /// Find a [`Datum`](#Datum) by its hash, if present. The function looks first for
 /// datums in the witness set, and then for inline datums if it doesn't find any in
 /// witnesses.