Add various util functions to the stdlib.

Author: KtorZ

CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## v2.0.0 - UNRELEASED
+## v2.1.0 - 2024-09-14
+
+### Added
+
+- [`aiken/collection/list.{for_each}`](https://aiken-lang.github.io/stdlib/aiken/collection/list.html#for_each): for performing many side-effects.
+- [`aiken/collection/dict.{pop}`](https://aiken-lang.github.io/stdlib/aiken/collection/dict.html#pop): for accessing and removing a value from a dictionnary in a single op.
+- [`aiken/primitive/bytearray.{starts_with}`](https://aiken-lang.github.io/stdlib/aiken/primitive/bytearray.html#starts_with): for matching bytearray prefixes.
+- [`aiken/primitive/math/rational.{pow}`](https://aiken-lang.github.io/stdlib/aiken/primitive/math/rational.html#pow): for computing (int) powers of rational numbers.
+- [`cardano/assets.{match}`](https://aiken-lang.github.io/stdlib/cardano/assets.html#match): efficiently compare two value-like.
+- [`cardano/assets.{restricted_to}`](https://aiken-lang.github.io/stdlib/cardano/assets.html#restricted_to): extracting value subsets from parent value.
+- [`cardano/address/credential.{compare}`](https://aiken-lang.github.io/stdlib/cardano/address/credential.html#compare): for ordering credentials.
+- [`cardano/governance/voter.{compare}`](https://aiken-lang.github.io/stdlib/cardano/governacen/voter.html#compare): for ordering voters.
+- [`cardano/transaction/output_reference.{compare}`](https://aiken-lang.github.io/stdlib/cardano/transaction/output_reference.html#compare): for ordering output references.
+- [`cardano/transaction/script_purpose.{compare}`](https://aiken-lang.github.io/stdlib/cardano/transaction/script_purpose.html#compare): for ordering script purpose.
+
+### Changed
+
+- N/A
+
+### Removed
+
+- N/A
+
+## v2.0.0 - 2024-09-01
 
 > [!NOTE]
 > Significant performance improvements (mostly on CPU) across all boards mostly due to the integration of Plutus V3.

README.md

@@ -18,7 +18,7 @@ aiken add aiken-lang/stdlib --version v2
 
 aiken's version | stdlib's version(s)
 ---             | ---
-`v1.1.0`        | `>= 2.0.0`
+`v1.1.*`        | `>= 2.0.0`
 `v1.0.29-alpha` | `>= 1.9.0` && `< 2.0.0`
 `v1.0.28-alpha` | `>= 1.9.0` && `< 2.0.0`
 `v1.0.26-alpha` | `<= 1.8.0` && `< 1.9.0`

aiken.toml

@@ -1,6 +1,6 @@
 name = "aiken-lang/stdlib"
 version = "main"
-compiler = "v1.1.0"
+compiler = "v1.1.2"
 plutus = "v3"
 description = "The Aiken Standard Library"
 

lib/aiken/collection/dict.ak

@@ -850,6 +850,91 @@ test map_2() {
   get(result, foo) == Some(43) && size(result) == size(fixture_1)
 }
 
+/// Remove a key-value pair from the dictionary and return its value. If the key is not found, no changes are made.
+///
+/// ```aiken
+/// let (value, _) =
+///   dict.empty
+///     |> dict.insert(key: "a", value: 100)
+///     |> dict.insert(key: "b", value: 200)
+///     |> dict.pop(key: "a")
+///
+/// result == 100
+/// ```
+pub fn pop(
+  self: Dict<key, value>,
+  key: ByteArray,
+) -> (Option<value>, Dict<key, value>) {
+  do_pop(self.inner, key, fn(value, inner) { (value, Dict { inner }) })
+}
+
+fn do_pop(
+  self: Pairs<ByteArray, value>,
+  key k: ByteArray,
+  return: fn(Option<value>, Pairs<ByteArray, value>) -> result,
+) -> result {
+  when self is {
+    [] -> return(None, [])
+    [Pair(k2, v2), ..rest] ->
+      if builtin.less_than_equals_bytearray(k, k2) {
+        if k == k2 {
+          return(Some(v2), rest)
+        } else {
+          return(None, self)
+        }
+      } else {
+        do_pop(
+          rest,
+          k,
+          fn(value, inner) { return(value, [Pair(k2, v2), ..inner]) },
+        )
+      }
+  }
+}
+
+test pop_1() {
+  pop(empty, foo) == (None, empty)
+}
+
+test pop_2() {
+  let m =
+    empty
+      |> insert(foo, 14)
+  pop(m, foo) == (Some(14), empty)
+}
+
+test pop_3() {
+  let m =
+    empty
+      |> insert(foo, 14)
+  pop(m, bar) == (None, m)
+}
+
+test pop_4() {
+  let m =
+    empty
+      |> insert(foo, 14)
+      |> insert(bar, 14)
+  pop(m, foo) == (Some(14), empty |> insert(bar, 14))
+}
+
+test pop_6() {
+  let m =
+    empty
+      |> insert("aaa", 1)
+      |> insert("bbb", 2)
+      |> insert("ccc", 3)
+      |> insert("ddd", 4)
+      |> insert("eee", 5)
+      |> insert("fff", 6)
+      |> insert("ggg", 7)
+      |> insert("hhh", 8)
+      |> insert("iii", 9)
+      |> insert("jjj", 10)
+
+  pop(m, "bcd") == (None, m)
+}
+
 // ## Combining
 
 /// Combine two dictionaries. If the same key exist in both the left and

lib/aiken/collection/list.ak

@@ -893,6 +893,25 @@ test flat_map_2() {
   flat_map([1, 2, 3], fn(a) { [a, a] }) == [1, 1, 2, 2, 3, 3]
 }
 
+/// Perform an action for each element of a list.
+///
+/// ```aiken
+/// list.for_each(labels, do: fn(lbl) { trace lbl Void })
+/// ```
+fn for_each(self: List<a>, do: fn(a) -> Void) -> Void {
+  foldr(self, Void, fn(x, _) { do(x) })
+}
+
+test for_each_1() {
+  for_each(
+    [@"hello", @"world"],
+    do: fn(lbl) {
+      trace lbl
+      Void
+    },
+  )
+}
+
 /// List [`map`](#map) but provides the position (0-based) of the elements while iterating.
 ///
 /// ```aiken

lib/cardano/address/credential.ak

@@ -0,0 +1,30 @@
+use aiken/primitive/bytearray
+use cardano/address.{Credential, Script, VerificationKey}
+
+pub fn compare(left: Credential, right: Credential) -> Ordering {
+  when left is {
+    Script(left) ->
+      when right is {
+        Script(right) -> bytearray.compare(left, right)
+        _ -> Less
+      }
+    VerificationKey(left) ->
+      when right is {
+        Script(_) -> Greater
+        VerificationKey(right) -> bytearray.compare(left, right)
+      }
+  }
+}
+
+test compare_matrix() {
+  and {
+    (compare(Script(""), Script("")) == Equal)?,
+    (compare(VerificationKey(""), VerificationKey("")) == Equal)?,
+    (compare(Script(""), VerificationKey("")) == Less)?,
+    (compare(VerificationKey(""), Script("")) == Greater)?,
+    (compare(Script("01"), Script("02")) == Less)?,
+    (compare(Script("02"), Script("01")) == Greater)?,
+    (compare(VerificationKey("01"), VerificationKey("02")) == Less)?,
+    (compare(VerificationKey("02"), VerificationKey("01")) == Greater)?,
+  }
+}