stdlib 0.40: change the implementation of dict.update

CHANGELOG.md

@@ -5,6 +5,7 @@
 - The `function.curry*` and `function.apply*` functions have been deprecated.
 - The deprecated `dynamic.unsafe_coerce` function has been removed.
 - The deprecated `dict.update` function has been removed.
+- The dict module gains a new `update` function.
 - The deprecated `order.max` and `order.min` functions have been removed.
 - The `float` module gains the `modulo` function.
 - The `uri.origin` function no longer incorrectly has a trailing slash.

src/gleam/dict.gleam

@@ -1,4 +1,4 @@
-import gleam/option.{type Option}
+import gleam/option.{type Option, None, Some}
 
 /// A dictionary of keys and values.
 ///
@@ -60,7 +60,7 @@ pub fn is_empty(dict: Dict(k, v)) -> Bool {
 ///
 /// ## Examples
 ///
-/// Calling `to_list` on an empty `dict` returns an empty list.
+/// Calling `to_list` on an empty dict returns an empty list.
 ///
 /// ```gleam
 /// new() |> to_list
@@ -474,6 +474,65 @@ pub fn upsert(
   |> insert(dict, key, _)
 }
 
+/// Changes the value in a dict for a given key using a given function.
+///
+/// Returns a dict where the caller attempts to change a key-value pair in the
+/// dict bei either setting or updating or removing or ignoring a key-value
+/// pair; in case:
+///
+/// 1. the `update` key is present in the dict, then the value passed to
+///    function `with` is `Some(value)`; then:
+///    1. if `fun` returns `Ok(value)`, then the `update` key is newly
+///      associated with to the value of `value` of `Ok(value)`.
+///    2. else the `update` key and its associated value are removed from the
+///      dict.
+/// 2. the `update` key is not present in the dict, then the `value` passed to
+///    function `with` is `None`; then:
+///    1. if `fun` returns `Ok(value)`, then the `update key` is added to the
+///      dict associated with the `value` of `Ok(value)`.
+///    2. else the `update key` is not added to the map.
+///
+/// ## Example
+///
+/// ```gleam
+/// let dict = dict.from_list([#("a", 0), #("b", 1), #("c", 2)])
+///
+/// let inc_if_exists_or_discard = fn(x) {
+///   case x {
+///     Some(i) -> Ok(i + 1)
+///     None -> Error(Nil)
+///   }
+/// }
+///
+/// dict
+/// |> dict.update("a", inc_if_exists_or_discard)
+/// // -> from_list([#("a", 1), #("b", 1), #("c", 2)])
+///
+/// dict
+/// |> dict.update("e", inc_if_exists_or_discard)
+/// // -> from_list([#("a", 0), #("b", 1), #("c", 2)])
+/// ```
+///
+pub fn update(
+  in dict: Dict(k, v),
+  update key: k,
+  with fun: fn(Option(v)) -> Result(v, Nil),
+) -> Dict(k, v) {
+  case do_get(dict, key) {
+    Ok(existing_value) ->
+      case fun(Some(existing_value)) {
+        Ok(value) -> do_insert(key, value, dict)
+        Error(_) -> do_delete(key, dict)
+      }
+    Error(_) -> {
+      case fun(None) {
+        Ok(value) -> do_insert(key, value, dict)
+        Error(_) -> dict
+      }
+    }
+  }
+}
+
 fn do_fold(list: List(#(k, v)), initial: acc, fun: fn(acc, k, v) -> acc) -> acc {
   case list {
     [] -> initial

test/gleam/dict_test.gleam

@@ -199,6 +199,105 @@ pub fn upsert_test() {
   |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2), #("z", 0)]))
 }
 
+pub fn update_test() {
+  let dict = dict.from_list([#("a", 0), #("b", 1), #("c", 2)])
+
+  let inc_if_exists_or_set = fn(x) {
+    case x {
+      Some(i) -> Ok(i + 1)
+      None -> Ok(1)
+    }
+  }
+
+  dict
+  |> dict.update("a", inc_if_exists_or_set)
+  |> should.equal(dict.from_list([#("a", 1), #("b", 1), #("c", 2)]))
+
+  dict
+  |> dict.update("e", inc_if_exists_or_set)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2), #("e", 1)]))
+
+  let discard_if_exists_else_noop = fn(x) {
+    case x {
+      Some(_i) -> Error(Nil)
+      None -> Error(Nil)
+    }
+  }
+
+  dict
+  |> dict.update("a", discard_if_exists_else_noop)
+  |> should.equal(dict.from_list([#("b", 1), #("c", 2)]))
+
+  dict
+  |> dict.update("e", discard_if_exists_else_noop)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2)]))
+
+  let inc_if_exists_else_noop = fn(x) {
+    case x {
+      Some(i) -> Ok(i + 1)
+      None -> Error(Nil)
+    }
+  }
+
+  dict
+  |> dict.update("a", inc_if_exists_else_noop)
+  |> should.equal(dict.from_list([#("a", 1), #("b", 1), #("c", 2)]))
+
+  dict
+  |> dict.update("e", inc_if_exists_else_noop)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2)]))
+
+  let discard_if_exists_else_set_to_zero = fn(x) {
+    case x {
+      Some(_i) -> Error(Nil)
+      None -> Ok(0)
+    }
+  }
+
+  dict
+  |> dict.update("a", discard_if_exists_else_set_to_zero)
+  |> should.equal(dict.from_list([#("b", 1), #("c", 2)]))
+
+  dict
+  |> dict.update("e", discard_if_exists_else_set_to_zero)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2), #("e", 0)]))
+
+  let discard_if_exists_else_set_to_zero = fn(x) {
+    case x {
+      Some(_i) -> Error(Nil)
+      None -> Ok(0)
+    }
+  }
+
+  dict
+  |> dict.update("a", discard_if_exists_else_set_to_zero)
+  |> should.equal(dict.from_list([#("b", 1), #("c", 2)]))
+
+  dict
+  |> dict.update("e", discard_if_exists_else_set_to_zero)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2), #("e", 0)]))
+
+  // Utilize a function returning a `Result` in the change function.
+  let half_or_zero_else_noop = fn(x) {
+    case x {
+      Some(i) -> int.divide(i, 2)
+      None -> Error(Nil)
+    }
+  }
+
+  dict
+  |> dict.update("c", half_or_zero_else_noop)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 1)]))
+
+  dict
+  |> dict.update("b", half_or_zero_else_noop)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 0), #("c", 2)]))
+
+  dict
+  |> dict.update("e", half_or_zero_else_noop)
+  |> should.equal(dict.from_list([#("a", 0), #("b", 1), #("c", 2)]))
+}
+
 pub fn fold_test() {
   let dict = dict.from_list([#("a", 0), #("b", 1), #("c", 2), #("d", 3)])