Accessbehaviour(Elixir v1.18.3)
View SourceKey-based access to data structures.
TheAccess module defines a behaviour for dynamically accessingkeys of any type in a data structure via thedata[key] syntax.
Access supports keyword lists (Keyword) and maps (Map) outof the box. Keywords supports only atoms keys, keys for maps canbe of any type. Both returnnil if the key does not exist:
iex>keywords=[a:1,b:2]iex>keywords[:a]1iex>keywords[:c]niliex>map=%{a:1,b:2}iex>map[:a]1iex>star_ratings=%{1.0=>"★",1.5=>"★☆",2.0=>"★★"}iex>star_ratings[1.5]"★☆"This syntax is very convenient as it can be nested arbitrarily:
iex>keywords=[a:1,b:2]iex>keywords[:c][:unknown]nilThis works because accessing anything on anil value, returnsnil itself:
iex>nil[:a]nilMaps and structs
While the access syntax is allowed in maps viamap[key],if your map is made of predefined atom keys, you should preferto access those atom keys withmap.key instead ofmap[key],asmap.key will raise if the key is missing (which is notsupposed to happen if the keys are predefined) or ifmap isnil.
Similarly, since structs are maps and structs have predefinedkeys, they only allow thestruct.key syntax and they do notallow thestruct[key] access syntax.
In other words, themap[key] syntax is loose, returningnilfor missing keys, while themap.key syntax is strict, raisingfor both nil values and missing keys.
To bridge this gap, Elixir provides theget_in/1 andget_in/2functions, which are capable of traversing nested data structures,even in the presence ofnils:
iex>users=%{"john"=>%{age:27},"meg"=>%{age:23}}iex>get_in(users["john"].age)27iex>get_in(users["unknown"].age)nilNotice how, even if no user was found,get_in/1 returnednil.Outside ofget_in/1, trying to access the field.age onnilwould raise.
Theget_in/2 function takes one step further by allowingdifferent accessors to be mixed in. For example, given a usermap with the:name and:languages keys, here is how toaccess the name of all programming languages:
iex>languages=[...>%{name:"elixir",type::functional},...>%{name:"c",type::procedural}...>]iex>user=%{name:"john",languages:languages}iex>get_in(user,[:languages,Access.all(),:name])["elixir","c"]This module provides convenience functions for traversing otherstructures, like tuples and lists. As we will see next, they caneven be used to update nested data structures.
If you want to learn more about the dual nature of maps in Elixir,as they can be either for structured data or as a key-value store,see theMap module.
Updating nested data structures
The access syntax can also be used with theKernel.put_in/2,Kernel.update_in/2,Kernel.get_and_update_in/2, andKernel.pop_in/1macros to further manipulate values in nested data structures:
iex>users=%{"john"=>%{age:27},"meg"=>%{age:23}}iex>put_in(users["john"].age,28)%{"john"=>%{age:28},"meg"=>%{age:23}}As shown in the previous section, you can also use theKernel.put_in/3,Kernel.update_in/3,Kernel.pop_in/2, andKernel.get_and_update_in/3 functions to provide nestedcustom accessors. For instance, given a user map with the:name and:languages keys, here is how to deeply traversethe map and convert all language names to uppercase:
iex>languages=[...>%{name:"elixir",type::functional},...>%{name:"c",type::procedural}...>]iex>user=%{name:"john",languages:languages}iex>update_in(user,[:languages,Access.all(),:name],&String.upcase/1)%{name:"john",languages:[%{name:"ELIXIR",type::functional},%{name:"C",type::procedural}]}See the functionskey/1,key!/1,elem/1, andall/0 forsome of the available accessors.
Summary
Callbacks
Invoked in order to access the value stored underkey in the given termterm.
Invoked in order to access the value underkey and update it at the same time.
Invoked to "pop" the value underkey out of the given data structure.
Functions
Returns a function that accesses all the elements in a list.
Returns a function that accesses the element atindex (zero based) of a list.
Same asat/1 except that it raisesEnum.OutOfBoundsErrorif the given index is out of bounds.
Returns a function that accesses the element at the given index in a tuple.
Fetches the value for the given key in a container (a map, keywordlist, or struct that implements theAccess behaviour).
Returns a function that accesses all elements of a list that match the provided predicate.
Returns a function that accesses the first element of a list that matches the provided predicate.
Gets the value for the given key in a container (a map, keywordlist, or struct that implements theAccess behaviour).
Gets and updates the given key in acontainer (a map, a keyword list,a struct that implements theAccess behaviour).
Returns a function that accesses the given key in a map/struct.
Returns a function that accesses the given key in a map/struct.
Removes the entry with a given key from a container (a map, keywordlist, or struct that implements theAccess behaviour).
Returns a function that accesses all items of a list that are within the provided range.
Types
@type access_fun(data, current_value) ::get_fun(data) |get_and_update_fun(data, current_value)
@type key() ::any()
@type nil_container() :: nil@type t() ::container() |nil_container() |any()
@type value() ::any()
Callbacks
Invoked in order to access the value stored underkey in the given termterm.
This function should return{:ok, value} wherevalue is the value underkey if the key exists in the term, or:error if the key does not exist inthe term.
Many of the functions defined in theAccess module internally call thisfunction. This function is also used when the square-brackets access syntax(structure[key]) is used: thefetch/2 callback implemented by the modulethat defines thestructure struct is invoked and if it returns{:ok, value} thenvalue is returned, or if it returns:error thennil isreturned.
See theMap.fetch/2 andKeyword.fetch/2 implementations for examples ofhow to implement this callback.
@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()
Invoked in order to access the value underkey and update it at the same time.
The implementation of this callback should invokefun with the value underkey in the passed structuredata, or withnil ifkey is not present in it.This function must return either{current_value, new_value} or:pop.
If the passed function returns{current_value, new_value},the return value of this callback should be{current_value, new_data}, where:
current_valueis the retrieved value (which can be operated on before being returned)new_valueis the new value to be stored underkeynew_dataisdataafter updating the value ofkeywithnew_value.
If the passed function returns:pop, the return value of this callbackmust be{value, new_data} wherevalue is the value underkey(ornil if not present) andnew_data isdata withoutkey.
See the implementations ofMap.get_and_update/3 orKeyword.get_and_update/3for more examples.
Invoked to "pop" the value underkey out of the given data structure.
Whenkey exists in the given structuredata, the implementation shouldreturn a{value, new_data} tuple wherevalue is the value that was underkey andnew_data isterm withoutkey.
Whenkey is not present in the given structure, a tuple{value, data}should be returned, wherevalue is implementation-defined.
See the implementations forMap.pop/3 orKeyword.pop/3 for more examples.
Functions
@spec all() ::access_fun(data ::list(), current_value ::list())
Returns a function that accesses all the elements in a list.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Examples
iex>list=[%{name:"john"},%{name:"mary"}]iex>get_in(list,[Access.all(),:name])["john","mary"]iex>get_and_update_in(list,[Access.all(),:name],fnprev->...>{prev,String.upcase(prev)}...>end){["john","mary"],[%{name:"JOHN"},%{name:"MARY"}]}iex>pop_in(list,[Access.all(),:name]){["john","mary"],[%{},%{}]}Here is an example that traverses the list dropping evennumbers and multiplying odd numbers by 2:
iex>requireIntegeriex>get_and_update_in([1,2,3,4,5],[Access.all()],fnnum->...>ifInteger.is_even(num),do::pop,else:{num,num*2}...>end){[1,2,3,4,5],[2,6,10]}An error is raised if the accessed structure is not a list:
iex>get_in(%{},[Access.all()])** (RuntimeError) Access.all/0 expected a list, got: %{}@spec at(integer()) ::access_fun(data ::list(), current_value ::term())
Returns a function that accesses the element atindex (zero based) of a list.
Keep in mind that index lookups in lists take linear time: the larger the list,the longer it will take to access its index. Therefore index-based operationsare generally avoided in favor of other functions in theEnum module.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Examples
iex>list=[%{name:"john"},%{name:"mary"}]iex>get_in(list,[Access.at(1),:name])"mary"iex>get_in(list,[Access.at(-1),:name])"mary"iex>get_and_update_in(list,[Access.at(0),:name],fnprev->...>{prev,String.upcase(prev)}...>end){"john",[%{name:"JOHN"},%{name:"mary"}]}iex>get_and_update_in(list,[Access.at(-1),:name],fnprev->...>{prev,String.upcase(prev)}...>end){"mary",[%{name:"john"},%{name:"MARY"}]}at/1 can also be used to pop elements out of a list ora key inside of a list:
iex>list=[%{name:"john"},%{name:"mary"}]iex>pop_in(list,[Access.at(0)]){%{name:"john"},[%{name:"mary"}]}iex>pop_in(list,[Access.at(0),:name]){"john",[%{},%{name:"mary"}]}When the index is out of bounds,nil is returned and the update function is never called:
iex>list=[%{name:"john"},%{name:"mary"}]iex>get_in(list,[Access.at(10),:name])niliex>get_and_update_in(list,[Access.at(10),:name],fnprev->...>{prev,String.upcase(prev)}...>end){nil,[%{name:"john"},%{name:"mary"}]}An error is raised if the accessed structure is not a list:
iex>get_in(%{},[Access.at(1)])** (RuntimeError) Access.at/1 expected a list, got: %{}@spec at!(integer()) ::access_fun(data ::list(), current_value ::term())
Same asat/1 except that it raisesEnum.OutOfBoundsErrorif the given index is out of bounds.
Examples
iex>get_in([:a,:b,:c],[Access.at!(2)]):ciex>get_in([:a,:b,:c],[Access.at!(3)])** (Enum.OutOfBoundsError) out of bounds error@spec elem(non_neg_integer()) ::access_fun(data ::tuple(), current_value ::term())
Returns a function that accesses the element at the given index in a tuple.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
The returned function raises ifindex is out of bounds.
Note that popping elements out of tuples is not possible and raises anerror.
Examples
iex>map=%{user:{"john",27}}iex>get_in(map,[:user,Access.elem(0)])"john"iex>get_and_update_in(map,[:user,Access.elem(0)],fnprev->...>{prev,String.upcase(prev)}...>end){"john",%{user:{"JOHN",27}}}iex>pop_in(map,[:user,Access.elem(0)])** (RuntimeError) cannot pop data from a tupleAn error is raised if the accessed structure is not a tuple:
iex>get_in(%{},[Access.elem(0)])** (RuntimeError) Access.elem/1 expected a tuple, got: %{}@spec fetch(container(),term()) :: {:ok,term()} | :error
@spec fetch(nil_container(),any()) :: :error
Fetches the value for the given key in a container (a map, keywordlist, or struct that implements theAccess behaviour).
Returns{:ok, value} wherevalue is the value underkey if there is sucha key, or:error ifkey is not found.
Examples
iex>Access.fetch(%{name:"meg",age:26},:name){:ok,"meg"}iex>Access.fetch([ordered:true,on_timeout::exit],:timeout):errorSame asfetch/2 but returns the value directly,or raises aKeyError exception ifkey is not found.
Examples
iex>Access.fetch!(%{name:"meg",age:26},:name)"meg"@spec filter((term() ->boolean())) ::access_fun(data ::list(), current_value ::list())
Returns a function that accesses all elements of a list that match the provided predicate.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Examples
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>get_in(list,[Access.filter(&(&1.salary>20)),:name])["francine"]iex>get_and_update_in(list,[Access.filter(&(&1.salary<=20)),:name],fnprev->...>{prev,String.upcase(prev)}...>end){["john"],[%{name:"JOHN",salary:10},%{name:"francine",salary:30}]}filter/1 can also be used to pop elements out of a list ora key inside of a list:
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>pop_in(list,[Access.filter(&(&1.salary>=20))]){[%{name:"francine",salary:30}],[%{name:"john",salary:10}]}iex>pop_in(list,[Access.filter(&(&1.salary>=20)),:name]){["francine"],[%{name:"john",salary:10},%{salary:30}]}When no match is found, an empty list is returned and the update function is never called
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>get_in(list,[Access.filter(&(&1.salary>=50)),:name])[]iex>get_and_update_in(list,[Access.filter(&(&1.salary>=50)),:name],fnprev->...>{prev,String.upcase(prev)}...>end){[],[%{name:"john",salary:10},%{name:"francine",salary:30}]}An error is raised if the predicate is not a function or is of the incorrect arity:
iex>get_in([],[Access.filter(5)])** (FunctionClauseError) no function clause matching in Access.filter/1An error is raised if the accessed structure is not a list:
iex>get_in(%{},[Access.filter(fna->a==10end)])** (RuntimeError) Access.filter/1 expected a list, got: %{}@spec find((term() ->as_boolean(term()))) ::access_fun(data ::list(), current_value ::term())
Returns a function that accesses the first element of a list that matches the provided predicate.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Examples
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>get_in(list,[Access.find(&(&1.salary>20)),:name])"francine"iex>get_and_update_in(list,[Access.find(&(&1.salary<=40)),:name],fnprev->...>{prev,String.upcase(prev)}...>end){"john",[%{name:"JOHN",salary:10},%{name:"francine",salary:30}]}find/1 can also be used to pop the first found element out of a list ora key inside of a list:
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>pop_in(list,[Access.find(&(&1.salary<=40))]){%{name:"john",salary:10},[%{name:"francine",salary:30}]}When no match is found, nil is returned and the update function is never called
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30}]iex>get_in(list,[Access.find(&(&1.salary>=50)),:name])niliex>get_and_update_in(list,[Access.find(&(&1.salary>=50)),:name],fnprev->...>{prev,String.upcase(prev)}...>end){nil,[%{name:"john",salary:10},%{name:"francine",salary:30}]}An error is raised if the predicate is not a function or is of the incorrect arity:
iex>get_in([],[Access.find(5)])** (FunctionClauseError) no function clause matching in Access.find/1An error is raised if the accessed structure is not a list:
iex>get_in(%{},[Access.find(fna->a==10end)])** (RuntimeError) Access.find/1 expected a list, got: %{}@spec get(container(),term(),term()) ::term()
@spec get(nil_container(),any(), default) :: default when default: var
Gets the value for the given key in a container (a map, keywordlist, or struct that implements theAccess behaviour).
Returns the value underkey if there is such a key, ordefault ifkey isnot found.
Examples
iex>Access.get(%{name:"john"},:name,"default name")"john"iex>Access.get(%{name:"john"},:age,25)25iex>Access.get([ordered:true],:timeout)nil@spec get_and_update(data,key(), (value() | nil -> {current_value, new_value ::value()} | :pop)) :: {current_value, new_data :: data}when data:container(), current_value: var
Gets and updates the given key in acontainer (a map, a keyword list,a struct that implements theAccess behaviour).
Thefun argument receives the value ofkey (ornil ifkey is notpresent incontainer) and must return a two-element tuple{current_value, new_value}:the "get" valuecurrent_value (the retrieved value, which can be operated on beforebeing returned) and the new value to be stored underkey (new_value).fun may also return:pop, which means the current valueshould be removed from the container and returned.
The returned value is a two-element tuple with the "get" value returned byfun and a new container with the updated value underkey.
Examples
iex>Access.get_and_update([a:1],:a,fncurrent_value->...>{current_value,current_value+1}...>end){1,[a:2]}Returns a function that accesses the given key in a map/struct.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
The returned function uses the default value if the key does not exist.This can be used to specify defaults and safely traverse missing keys:
iex>get_in(%{},[Access.key(:user,%{}),Access.key(:name,"meg")])"meg"Such is also useful when using update functions, allowing us to introducevalues as we traverse the data structure for updates:
iex>put_in(%{},[Access.key(:user,%{}),Access.key(:name)],"Mary")%{user:%{name:"Mary"}}Examples
iex>map=%{user:%{name:"john"}}iex>get_in(map,[Access.key(:unknown,%{}),Access.key(:name,"john")])"john"iex>get_and_update_in(map,[Access.key(:user),Access.key(:name)],fnprev->...>{prev,String.upcase(prev)}...>end){"john",%{user:%{name:"JOHN"}}}iex>pop_in(map,[Access.key(:user),Access.key(:name)]){"john",%{user:%{}}}An error is raised if the accessed structure is not a map or a struct:
iex>get_in([],[Access.key(:foo)])** (BadMapError) expected a map, got: []@spec key!(key()) ::access_fun(data ::struct() |map(), current_value ::term())
Returns a function that accesses the given key in a map/struct.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Similar tokey/2, but the returned function raises if the key does not exist.
Examples
iex>map=%{user:%{name:"john"}}iex>get_in(map,[Access.key!(:user),Access.key!(:name)])"john"iex>get_and_update_in(map,[Access.key!(:user),Access.key!(:name)],fnprev->...>{prev,String.upcase(prev)}...>end){"john",%{user:%{name:"JOHN"}}}iex>pop_in(map,[Access.key!(:user),Access.key!(:name)]){"john",%{user:%{}}}iex>get_in(map,[Access.key!(:user),Access.key!(:unknown)])** (KeyError) key :unknown not found in: %{name: "john"}The examples above could be partially written as:
iex>map=%{user:%{name:"john"}}iex>map.user.name"john"iex>get_and_update_in(map.user.name,fnprev->...>{prev,String.upcase(prev)}...>end){"john",%{user:%{name:"JOHN"}}}However, it is not possible to remove fields using the dot notation,as it is implied those fields must also be present. In any case,Access.key!/1 is useful when the key is not known in advanceand must be accessed dynamically.
An error is raised if the accessed structure is not a map/struct:
iex>get_in([],[Access.key!(:foo)])** (RuntimeError) Access.key!/1 expected a map/struct, got: []Removes the entry with a given key from a container (a map, keywordlist, or struct that implements theAccess behaviour).
Returns a tuple containing the value associated with the key and theupdated container.nil is returned for the value if the key isn'tin the container.
Examples
With a map:
iex>Access.pop(%{name:"Elixir",creator:"Valim"},:name){"Elixir",%{creator:"Valim"}}A keyword list:
iex>Access.pop([name:"Elixir",creator:"Valim"],:name){"Elixir",[creator:"Valim"]}An unknown key:
iex>Access.pop(%{name:"Elixir",creator:"Valim"},:year){nil,%{creator:"Valim",name:"Elixir"}}@spec slice(Range.t()) ::access_fun(data ::list(), current_value ::list())
Returns a function that accesses all items of a list that are within the provided range.
The range will be normalized following the same rules fromEnum.slice/2.
The returned function is typically passed as an accessor toKernel.get_in/2,Kernel.get_and_update_in/3, and friends.
Examples
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30},%{name:"vitor",salary:25}]iex>get_in(list,[Access.slice(1..2),:name])["francine","vitor"]iex>get_and_update_in(list,[Access.slice(1..3//2),:name],fnprev->...>{prev,String.upcase(prev)}...>end){["francine"],[%{name:"john",salary:10},%{name:"FRANCINE",salary:30},%{name:"vitor",salary:25}]}slice/1 can also be used to pop elements out of a list ora key inside of a list:
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30},%{name:"vitor",salary:25}]iex>pop_in(list,[Access.slice(-2..-1)]){[%{name:"francine",salary:30},%{name:"vitor",salary:25}],[%{name:"john",salary:10}]}iex>pop_in(list,[Access.slice(-2..-1),:name]){["francine","vitor"],[%{name:"john",salary:10},%{salary:30},%{salary:25}]}When no match is found, an empty list is returned and the update function is never called
iex>list=[%{name:"john",salary:10},%{name:"francine",salary:30},%{name:"vitor",salary:25}]iex>get_in(list,[Access.slice(5..10//2),:name])[]iex>get_and_update_in(list,[Access.slice(5..10//2),:name],fnprev->...>{prev,String.upcase(prev)}...>end){[],[%{name:"john",salary:10},%{name:"francine",salary:30},%{name:"vitor",salary:25}]}An error is raised if the accessed structure is not a list:
iex>get_in(%{},[Access.slice(2..10//3)])** (ArgumentError) Access.slice/1 expected a list, got: %{}An error is raised if the step of the range is negative:
iex>get_in([],[Access.slice(2..10//-1)])** (ArgumentError) Access.slice/1 does not accept ranges with negative steps, got: 2..10//-1