Streamline get_and_update specs for Access for Kernel (#10822)

In the same fashion of PRs #10228 and #10223

Replaces:
- `get_values` with `current_value`
- `update_value` with `new_value`
- `data` with `new_data` when suitable

Adds nil as an argument term in the function spec.

Author: eksperimental

lib/elixir/lib/access.ex

@@ -99,16 +99,16 @@ defmodule Access do
   @type key :: any
   @type value :: any
 
-  @type get_fun(data, get_value) ::
+  @type get_fun(data, current_value) ::
           (:get, data, (term -> term) ->
-             {get_value, new_data :: container})
+             {current_value, new_data :: container})
 
-  @type get_and_update_fun(data, get_value) ::
+  @type get_and_update_fun(data, current_value) ::
           (:get_and_update, data, (term -> term) ->
-             {get_value, new_data :: container} | :pop)
+             {current_value, new_data :: container} | :pop)
 
-  @type access_fun(data, get_value) ::
-          get_fun(data, get_value) | get_and_update_fun(data, get_value)
+  @type access_fun(data, current_value) ::
+          get_fun(data, current_value) | get_and_update_fun(data, current_value)
 
   @doc """
   Invoked in order to access the value stored under `key` in the given term `term`.
@@ -134,16 +134,16 @@ defmodule Access do
 
   The implementation of this callback should invoke `fun` with the value under
   `key` in the passed structure `data`, or with `nil` if `key` is not present in it.
-  This function must return either `{get_value, update_value}` or `:pop`.
+  This function must return either `{current_value, new_value}` or `:pop`.
 
-  If the passed function returns `{get_value, update_value}`,
-  the return value of this callback should be `{get_value, new_data}`, where:
+  If the passed function returns `{current_value, new_value}`,
+  the return value of this callback should be `{current_value, new_data}`, where:
 
-    * `get_value` is the retrieved value (which can be operated on before being returned)
+    * `current_value` is the retrieved value (which can be operated on before being returned)
 
-    * `update_value` is the new value to be stored under `key`
+    * `new_value` is the new value to be stored under `key`
 
-    * `new_data` is `data` after updating the value of `key` with `update_value`.
+    * `new_data` is `data` after updating the value of `key` with `new_value`.
 
   If the passed function returns `:pop`, the return value of this callback
   must be `{value, new_data}` where `value` is the value under `key`
@@ -152,8 +152,9 @@ defmodule Access do
   See the implementations of `Map.get_and_update/3` or `Keyword.get_and_update/3`
   for more examples.
   """
-  @callback get_and_update(data, key, (value -> {get_value, value} | :pop)) :: {get_value, data}
-            when get_value: var, data: container | any_container
+  @callback get_and_update(data, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
+              {current_value, new_data :: data}
+            when current_value: value, data: container | any_container
 
   @doc """
   Invoked to "pop" the value under `key` out of the given data structure.
@@ -320,9 +321,9 @@ defmodule Access do
   a struct that implements the `Access` behaviour).
 
   The `fun` argument receives the value of `key` (or `nil` if `key` is not
-  present in `container`) and must return a two-element tuple `{get_value, update_value}`:
-  the "get" value `get_value` (the retrieved value, which can be operated on before
-  being returned) and the new value to be stored under `key` (`update_value`).
+  present in `container`) and must return a two-element tuple `{current_value, new_value}`:
+  the "get" value `current_value` (the retrieved value, which can be operated on before
+  being returned) and the new value to be stored under `key` (`new_value`).
   `fun` may also return `:pop`, which means the current value
   should be removed from the container and returned.
 
@@ -337,8 +338,9 @@ defmodule Access do
       {1, [a: 2]}
 
   """
-  @spec get_and_update(data, key, (value -> {get_value, value} | :pop)) :: {get_value, data}
-        when get_value: var, data: container
+  @spec get_and_update(data, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
+          {current_value, new_data :: data}
+        when current_value: var, data: container
   def get_and_update(container, key, fun)
 
   def get_and_update(%module{} = container, key, fun) do
@@ -451,7 +453,7 @@ defmodule Access do
       ** (BadMapError) expected a map, got: []
 
   """
-  @spec key(key, term) :: access_fun(data :: struct | map, get_value :: term)
+  @spec key(key, term) :: access_fun(data :: struct | map, current_value :: term)
   def key(key, default \\ nil) do
     fn
       :get, data, next ->
@@ -495,7 +497,7 @@ defmodule Access do
       ** (RuntimeError) Access.key!/1 expected a map/struct, got: []
 
   """
-  @spec key!(key) :: access_fun(data :: struct | map, get_value :: term)
+  @spec key!(key) :: access_fun(data :: struct | map, current_value :: term)
   def key!(key) do
     fn
       :get, %{} = data, next ->
@@ -543,7 +545,7 @@ defmodule Access do
       ** (RuntimeError) Access.elem/1 expected a tuple, got: %{}
 
   """
-  @spec elem(non_neg_integer) :: access_fun(data :: tuple, get_value :: term)
+  @spec elem(non_neg_integer) :: access_fun(data :: tuple, current_value :: term)
   def elem(index) when is_integer(index) and index >= 0 do
     pos = index + 1
 
@@ -597,7 +599,7 @@ defmodule Access do
       ** (RuntimeError) Access.all/0 expected a list, got: %{}
 
   """
-  @spec all() :: access_fun(data :: list, get_value :: list)
+  @spec all() :: access_fun(data :: list, current_value :: list)
   def all() do
     &all/3
   end
@@ -672,7 +674,7 @@ defmodule Access do
       ** (RuntimeError) Access.at/1 expected a list, got: %{}
 
   """
-  @spec at(integer) :: access_fun(data :: list, get_value :: term)
+  @spec at(integer) :: access_fun(data :: list, current_value :: term)
   def at(index) when is_integer(index) do
     fn op, data, next -> at(op, data, index, next) end
   end
@@ -727,7 +729,7 @@ defmodule Access do
 
   """
   @doc since: "1.11.0"
-  @spec at!(integer) :: access_fun(data :: list, get_value :: term)
+  @spec at!(integer) :: access_fun(data :: list, current_value :: term)
   def at!(index) when is_integer(index) do
     fn op, data, next -> at!(op, data, index, next) end
   end
@@ -794,7 +796,7 @@ defmodule Access do
 
   """
   @doc since: "1.6.0"
-  @spec filter((term -> boolean)) :: access_fun(data :: list, get_value :: list)
+  @spec filter((term -> boolean)) :: access_fun(data :: list, current_value :: list)
   def filter(func) when is_function(func) do
     fn op, data, next -> filter(op, data, func, next) end
   end

lib/elixir/lib/kernel.ex

@@ -2661,8 +2661,8 @@ defmodule Kernel do
   The `fun` argument receives the value of `key` (or `nil` if `key`
   is not present) and must return one of the following values:
 
-    * a two-element tuple `{get_value, new_value}`. In this case,
-      `get_value` is the retrieved value which can possibly be operated on before
+    * a two-element tuple `{current_value, new_value}`. In this case,
+      `current_value` is the retrieved value which can possibly be operated on before
       being returned. `new_value` is the new value to be stored under `key`.
 
     * `:pop`, which implies that the current value under `key`
@@ -2716,13 +2716,14 @@ defmodule Kernel do
   `Access.key/2`, and others as examples.
   """
   @spec get_and_update_in(
-          structure :: Access.t(),
+          structure,
           keys,
-          (term -> {get_value, update_value} | :pop)
-        ) :: {get_value, structure :: Access.t()}
-        when keys: nonempty_list(any),
-             get_value: var,
-             update_value: term
+          (term | nil -> {current_value, new_value} | :pop)
+        ) :: {current_value, new_structure :: structure}
+        when structure: Access.t(),
+             keys: nonempty_list(any),
+             current_value: Access.value(),
+             new_value: Access.value()
   def get_and_update_in(data, keys, fun)
 
   def get_and_update_in(data, [head], fun) when is_function(head, 3),

lib/elixir/lib/keyword.ex

@@ -287,8 +287,8 @@ defmodule Keyword do
       {nil, [a: 1]}
 
   """
-  @spec get_and_update(t, key, (value -> {current_value, new_value :: value} | :pop)) ::
-          {current_value, value}
+  @spec get_and_update(t, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
+          {current_value, new_keywords :: t}
         when current_value: value
   def get_and_update(keywords, key, fun)
       when is_list(keywords) and is_atom(key),
@@ -351,8 +351,8 @@ defmodule Keyword do
       {1, []}
 
   """
-  @spec get_and_update!(t, key, (value -> {current_value, new_value :: value} | :pop)) ::
-          {current_value, t}
+  @spec get_and_update!(t, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
+          {current_value, new_keywords :: t}
         when current_value: value
   def get_and_update!(keywords, key, fun) do
     get_and_update!(keywords, key, fun, [])
@@ -929,7 +929,7 @@ defmodule Keyword do
       [a: 1, b: 11]
 
   """
-  @spec update(t, key, default :: value, (existing_value :: value -> updated_value :: value)) :: t
+  @spec update(t, key, default :: value, (existing_value :: value -> new_value :: value)) :: t
   def update(keywords, key, default, fun)
       when is_list(keywords) and is_atom(key) and is_function(fun, 1) do
     update_guarded(keywords, key, default, fun)

lib/elixir/lib/map.ex

@@ -619,7 +619,7 @@ defmodule Map do
       %{a: 1, b: 11}
 
   """
-  @spec update(map, key, default :: value, (existing_value :: value -> updated_value :: value)) ::
+  @spec update(map, key, default :: value, (existing_value :: value -> new_value :: value)) ::
           map
   def update(map, key, default, fun) when is_function(fun, 1) do
     case map do
@@ -817,7 +817,7 @@ defmodule Map do
       ** (KeyError) key :b not found in: %{a: 1}
 
   """
-  @spec update!(map, key, (existing_value :: value -> updated_value :: value)) :: map
+  @spec update!(map, key, (existing_value :: value -> new_value :: value)) :: map
   def update!(map, key, fun) when is_function(fun, 1) do
     value = fetch!(map, key)
     put(map, key, fun.(value))
@@ -855,8 +855,8 @@ defmodule Map do
       {nil, %{a: 1}}
 
   """
-  @spec get_and_update(map, key, (value -> {current_value, new_value :: value} | :pop)) ::
-          {current_value, map}
+  @spec get_and_update(map, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
+          {current_value, new_map :: map}
         when current_value: value
   def get_and_update(map, key, fun) when is_function(fun, 1) do
     current = get(map, key)
@@ -897,7 +897,7 @@ defmodule Map do
       {1, %{}}
 
   """
-  @spec get_and_update!(map, key, (value -> {current_value, new_value :: value} | :pop)) ::
+  @spec get_and_update!(map, key, (value | nil -> {current_value, new_value :: value} | :pop)) ::
           {current_value, map}
         when current_value: value
   def get_and_update!(map, key, fun) when is_function(fun, 1) do