Map(Elixir v1.18.3)
View SourceMaps are the "go to" key-value data structure in Elixir.
Maps can be created with the%{} syntax, and key-value pairs can beexpressed askey => value:
iex>%{}%{}iex>%{"one"=>:two,3=>"four"}%{3=>"four","one"=>:two}Key-value pairs in a map do not follow any order (that's why the printed mapin the example above has a different order than the map that was created).
Maps do not impose any restriction on the key type: anything can be a key in amap. As a key-value structure, maps do not allow duplicate keys. Keys arecompared using the exact-equality operator (===/2). If colliding keys are definedin a map literal, the last one prevails.
When the key in a key-value pair is an atom, thekey: value shorthand syntaxcan be used (as in many other special forms):
iex>%{a:1,b:2}%{a:1,b:2}If you want to mix the shorthand syntax with=>, the shorthand syntax must comeat the end:
iex>%{"hello"=>"world",a:1,b:2}%{:a=>1,:b=>2,"hello"=>"world"}Keys in maps can be accessed through some of the functions in this module(such asMap.get/3 orMap.fetch/2) or through themap[] syntax providedby theAccess module:
iex>map=%{a:1,b:2}iex>Map.fetch(map,:a){:ok,1}iex>map[:b]2iex>map["non_existing_key"]nilTo access atom keys, one may also use themap.key notation. Note thatmap.keywill raise aKeyError if themap doesn't contain the key:key, compared tomap[:key], that would returnnil.
map=%{foo:"bar",baz:"bong"}map.foo#=> "bar"map.non_existing_key** (KeyError) key :non_existing_key not found in: %{baz: "bong", foo: "bar"}Avoid parentheses
Do not add parentheses when accessing fields, such as indata.key().If parentheses are used, Elixir will expectdata to be an atom representinga module and attempt to call thefunctionkey/0 in it.
The two syntaxes for accessing keys reveal the dual nature of maps. Themap[key]syntax is used for dynamically created maps that may have any key, of any type.map.key is used with maps that hold a predetermined set of atoms keys, which areexpected to always be present. Structs, defined viadefstruct/1, are one exampleof such "static maps", where the keys can also be checked during compile time.
Maps can be pattern matched on. When a map is on the left-hand side of apattern match, it will match if the map on the right-hand side contains thekeys on the left-hand side and their values match the ones on the left-handside. This means that an empty map matches every map.
iex>%{}=%{foo:"bar"}%{foo:"bar"}iex>%{a:a}=%{:a=>1,"b"=>2,[:c,:e,:e]=>3}iex>a1But this will raise aMatchError exception:
%{:c=>3}=%{:a=>1,2=>:b}Variables can be used as map keys both when writing map literals as well aswhen matching:
iex>n=11iex>%{n=>:one}%{1=>:one}iex>%{^n=>:one}=%{1=>:one,2=>:two,3=>:three}%{1=>:one,2=>:two,3=>:three}Maps also support a specific update syntax to update the value stored underexisting keys. You can update using the atom keys syntax:
iex>map=%{one:1,two:2}iex>%{map|one:"one"}%{one:"one",two:2}Or any other keys:
iex>other_map=%{"three"=>3,"four"=>4,"five"=>5}iex>%{other_map|"three"=>"three","four"=>"four"}%{"five"=>5,"four"=>"four","three"=>"three"}When a key that does not exist in the map is updated aKeyError exception will be raised:
%{map|three:3}The functions in this module that need to find a specific key work in logarithmic time.This means that the time it takes to find keys grows as the map grows, but it's notdirectly proportional to the map size. In comparison to finding an element in a list,it performs better because lists have a linear time complexity. Some functions,such askeys/1 andvalues/1, run in linear time because they need to get to everyelement in the map.
Maps also implement theEnumerable protocol, so many functions to work with mapsare found in theEnum module. Additionally, the following functions for maps arefound inKernel:
Summary
Functions
Deletes the entry inmap for a specifickey.
Drops the givenkeys frommap.
Checks if two maps are equal.
Fetches the value for a specifickey in the givenmap.
Fetches the value for a specifickey in the givenmap, erroring out ifmap doesn't containkey.
Returns a map containing only those pairs frommapfor whichfun returns a truthy value.
Builds a map from the givenkeys and the fixedvalue.
Converts astruct to map.
Gets the value for a specifickey inmap.
Gets the value fromkey and updates it, all in one pass.
Gets the value fromkey and updates it, all in one pass. Raises if there is nokey.
Gets the value for a specifickey inmap.
Returns whether the givenkey exists in the givenmap.
Intersects two maps, returning a map with the common keys.
Intersects two maps, returning a map with the common keys and resolving conflicts through a function.
Returns all keys frommap.
Merges two maps into one.
Merges two maps into one, resolving conflicts through the givenfun.
Returns a new empty map.
Creates a map from anenumerable.
Creates a map from anenumerable via the given transformation function.
Removes the value associated withkey inmap and returns the value and the updated map.
Removes and returns the value associated withkey inmap alongsidethe updated map, or raises ifkey is not present.
Lazily returns and removes the value associated withkey inmap.
Puts the givenvalue underkey inmap.
Puts the givenvalue underkey unless the entrykeyalready exists inmap.
Evaluatesfun and puts the result underkeyinmap unlesskey is already present.
Returns map excluding the pairs frommap for whichfun returnsa truthy value.
Puts a value underkey only if thekey already exists inmap.
Puts a value underkey only if thekey already exists inmap.
Replaces the value underkey using the given function only ifkey already exists inmap.
Takes all entries corresponding to the givenkeys inmap and extractsthem into a separate map.
Splits themap into two maps according to the given functionfun.
Returns a new map with all the key-value pairs inmap where the keyis inkeys.
Convertsmap to a list.
Updates thekey inmap with the given function.
Updateskey with the given function.
Returns all values frommap.
Types
Functions
Deletes the entry inmap for a specifickey.
If thekey does not exist, returnsmap unchanged.
Inlined by the compiler.
Examples
iex>Map.delete(%{a:1,b:2},:a)%{b:2}iex>Map.delete(%{b:2},:a)%{b:2}Drops the givenkeys frommap.
Ifkeys contains keys that are not inmap, they're simply ignored.
Examples
iex>Map.drop(%{a:1,b:2,c:3},[:b,:d])%{a:1,c:3}Checks if two maps are equal.
Two maps are considered to be equal if they containthe same keys and those keys contain the same values.
Note this function exists for completeness so theMapandKeyword modules provide similar APIs. In practice,developers often compare maps using==/2 or===/2directly.
Examples
iex>Map.equal?(%{a:1,b:2},%{b:2,a:1})trueiex>Map.equal?(%{a:1,b:2},%{b:1,a:2})falseComparison between keys and values is done with===/3,which means integers are not equivalent to floats:
iex>Map.equal?(%{a:1.0},%{a:1})falseFetches the value for a specifickey in the givenmap.
Ifmap contains the givenkey then its value is returned in the shape of{:ok, value}.Ifmap doesn't containkey,:error is returned.
Inlined by the compiler.
Examples
iex>Map.fetch(%{a:1},:a){:ok,1}iex>Map.fetch(%{a:1},:b):errorFetches the value for a specifickey in the givenmap, erroring out ifmap doesn't containkey.
Ifmap containskey, the corresponding value is returned. Ifmap doesn't containkey, aKeyError exception is raised.
Inlined by the compiler.
Examples
iex>Map.fetch!(%{a:1},:a)1Returns a map containing only those pairs frommapfor whichfun returns a truthy value.
fun receives the key and value of each of theelements in the map as a key-value pair.
See alsoreject/2 which discards all elements where thefunction returns a truthy value.
Performance considerations
If you find yourself doing multiple calls toMap.filter/2andMap.reject/2 in a pipeline, it is likely more efficientto useEnum.map/2 andEnum.filter/2 instead and convert toa map at the end usingMap.new/1.
Examples
iex>Map.filter(%{one:1,two:2,three:3},fn{_key,val}->rem(val,2)==1end)%{one:1,three:3}Builds a map from the givenkeys and the fixedvalue.
Inlined by the compiler.
Examples
iex>Map.from_keys([1,2,3],:number)%{1=>:number,2=>:number,3=>:number}Converts astruct to map.
It accepts a struct and simply removes the__struct__ fieldfrom the given struct.
Example
defmoduleUserdodefstruct[:name]endMap.from_struct(%User{name:"john"})#=> %{name: "john"}Gets the value for a specifickey inmap.
Ifkey is present inmap then its valuevalue isreturned. Otherwise,default is returned.
Ifdefault is not provided,nil is used.
Examples
iex>Map.get(%{},:a)niliex>Map.get(%{a:1},:a)1iex>Map.get(%{a:1},:b)niliex>Map.get(%{a:1},:b,3)3iex>Map.get(%{a:nil},:a,1)nil@spec get_and_update(map(),key(), (value() | nil -> {current_value, new_value ::value()} | :pop)) :: {current_value, new_map ::map()}when current_value:value()
Gets the value fromkey and updates it, all in one pass.
fun is called with the current value underkey inmap (ornil ifkeyis not present inmap) and must return a two-element tuple: the current value(the retrieved value, which can be operated on before being returned) and thenew value to be stored underkey in the resulting new map.fun may alsoreturn:pop, which means the current value shall be removed frommap andreturned (making this function behave likeMap.pop(map, key)).
The returned value is a two-element tuple with the current value returned byfun and a new map with the updated value underkey.
Examples
iex>Map.get_and_update(%{a:1},:a,fncurrent_value->...>{current_value,"new value!"}...>end){1,%{a:"new value!"}}iex>Map.get_and_update(%{a:1},:b,fncurrent_value->...>{current_value,"new value!"}...>end){nil,%{a:1,b:"new value!"}}iex>Map.get_and_update(%{a:1},:a,fn_->:popend){1,%{}}iex>Map.get_and_update(%{a:1},:b,fn_->:popend){nil,%{a:1}}@spec get_and_update!(map(),key(), (value() -> {current_value, new_value ::value()} | :pop)) :: {current_value,map()}when current_value:value()
Gets the value fromkey and updates it, all in one pass. Raises if there is nokey.
Behaves exactly likeget_and_update/3, but raises aKeyError exception ifkey is not present inmap.
Examples
iex>Map.get_and_update!(%{a:1},:a,fncurrent_value->...>{current_value,"new value!"}...>end){1,%{a:"new value!"}}iex>Map.get_and_update!(%{a:1},:b,fncurrent_value->...>{current_value,"new value!"}...>end)** (KeyError) key :b not found in: %{a: 1}iex>Map.get_and_update!(%{a:1},:a,fn_->...>:pop...>end){1,%{}}Gets the value for a specifickey inmap.
Ifkey is present inmap then its valuevalue isreturned. Otherwise,fun is evaluated and its result is returned.
This is useful if the default value is very expensive to calculate orgenerally difficult to setup and teardown again.
Examples
iex>map=%{a:1}iex>fun=fn->...># some expensive operation here...>13...>endiex>Map.get_lazy(map,:a,fun)1iex>Map.get_lazy(map,:b,fun)13Returns whether the givenkey exists in the givenmap.
Inlined by the compiler.
Examples
iex>Map.has_key?(%{a:1},:a)trueiex>Map.has_key?(%{a:1},:b)falseIntersects two maps, returning a map with the common keys.
The values in the returned map are the values of the intersected keys inmap2.
Inlined by the compiler.
Examples
iex>Map.intersect(%{a:1,b:2},%{b:"b",c:"c"})%{b:"b"}Intersects two maps, returning a map with the common keys and resolving conflicts through a function.
The given function will be invoked when there are duplicate keys; itsarguments arekey (the duplicate key),value1 (the value ofkey inmap1), andvalue2 (the value ofkey inmap2). The value returned byfun is used as the value underkey in the resulting map.
Examples
iex>Map.intersect(%{a:1,b:2},%{b:2,c:3},fn_k,v1,v2->...>v1+v2...>end)%{b:4}Returns all keys frommap.
Inlined by the compiler.
Examples
Map.keys(%{a:1,b:2})[:a,:b]Merges two maps into one.
All keys inmap2 will be added tomap1, overriding any existing one(i.e., the keys inmap2 "have precedence" over the ones inmap1).
If you have a struct and you would like to merge a set of keys into thestruct, do not use this function, as it would merge all keys on the rightside into the struct, even if the key is not part of the struct. Instead,usestruct/2.
Inlined by the compiler.
Examples
iex>Map.merge(%{a:1,b:2},%{a:3,d:4})%{a:3,b:2,d:4}Merges two maps into one, resolving conflicts through the givenfun.
All keys inmap2 will be added tomap1. The given function will be invokedwhen there are duplicate keys; its arguments arekey (the duplicate key),value1 (the value ofkey inmap1), andvalue2 (the value ofkey inmap2). The value returned byfun is used as the value underkey inthe resulting map.
Examples
iex>Map.merge(%{a:1,b:2},%{a:3,d:4},fn_k,v1,v2->...>v1+v2...>end)%{a:4,b:2,d:4}@spec new() ::map()
Returns a new empty map.
Examples
iex>Map.new()%{}@spec new(Enumerable.t()) ::map()
Creates a map from anenumerable.
Duplicated keys are removed; the latest one prevails.
Examples
iex>Map.new([{:b,1},{:a,2}])%{a:2,b:1}iex>Map.new(a:1,a:2,a:3)%{a:3}@spec new(Enumerable.t(), (term() -> {key(),value()})) ::map()
Creates a map from anenumerable via the given transformation function.
Duplicated keys are removed; the latest one prevails.
Examples
iex>Map.new([:a,:b],fnx->{x,x}end)%{a::a,b::b}iex>Map.new(%{a:2,b:3,c:4},fn{key,val}->{key,val*2}end)%{a:4,b:6,c:8}@spec pop(map(),key(), default) :: {value(), updated_map ::map()} | {default,map()}when default:value()
Removes the value associated withkey inmap and returns the value and the updated map.
Ifkey is present inmap, it returns{value, updated_map} wherevalue is the value ofthe key andupdated_map is the result of removingkey frommap. Ifkeyis not present inmap,{default, map} is returned.
Examples
iex>Map.pop(%{a:1},:a){1,%{}}iex>Map.pop(%{a:1},:b){nil,%{a:1}}iex>Map.pop(%{a:1},:b,3){3,%{a:1}}Removes and returns the value associated withkey inmap alongsidethe updated map, or raises ifkey is not present.
Behaves the same aspop/3 but raises aKeyError exception ifkey is not present inmap.
Examples
iex>Map.pop!(%{a:1},:a){1,%{}}iex>Map.pop!(%{a:1,b:2},:a){1,%{b:2}}iex>Map.pop!(%{a:1},:b)** (KeyError) key :b not found in: %{a: 1}Lazily returns and removes the value associated withkey inmap.
Ifkey is present inmap, it returns{value, new_map} wherevalue is the value ofthe key andnew_map is the result of removingkey frommap. Ifkeyis not present inmap,{fun_result, map} is returned, wherefun_resultis the result of applyingfun.
This is useful if the default value is very expensive to calculate orgenerally difficult to setup and teardown again.
Examples
iex>map=%{a:1}iex>fun=fn->...># some expensive operation here...>13...>endiex>Map.pop_lazy(map,:a,fun){1,%{}}iex>Map.pop_lazy(map,:b,fun){13,%{a:1}}Puts the givenvalue underkey inmap.
Inlined by the compiler.
Examples
iex>Map.put(%{a:1},:b,2)%{a:1,b:2}iex>Map.put(%{a:1,b:2},:a,3)%{a:3,b:2}Puts the givenvalue underkey unless the entrykeyalready exists inmap.
Examples
iex>Map.put_new(%{a:1},:b,2)%{a:1,b:2}iex>Map.put_new(%{a:1,b:2},:a,3)%{a:1,b:2}Evaluatesfun and puts the result underkeyinmap unlesskey is already present.
This function is useful in case you want to compute the value to put underkey only ifkey is not already present, as for example, when the value is expensive tocalculate or generally difficult to setup and teardown again.
Examples
iex>map=%{a:1}iex>fun=fn->...># some expensive operation here...>3...>endiex>Map.put_new_lazy(map,:a,fun)%{a:1}iex>Map.put_new_lazy(map,:b,fun)%{a:1,b:3}Returns map excluding the pairs frommap for whichfun returnsa truthy value.
See alsofilter/2.
Examples
iex>Map.reject(%{one:1,two:2,three:3},fn{_key,val}->rem(val,2)==1end)%{two:2}Puts a value underkey only if thekey already exists inmap.
Examples
iex>Map.replace(%{a:1,b:2},:a,3)%{a:3,b:2}iex>Map.replace(%{a:1},:b,2)%{a:1}Puts a value underkey only if thekey already exists inmap.
Ifkey is not present inmap, aKeyError exception is raised.
Inlined by the compiler.
Examples
iex>Map.replace!(%{a:1,b:2},:a,3)%{a:3,b:2}iex>Map.replace!(%{a:1},:b,2)** (KeyError) key :b not found in: %{a: 1}Replaces the value underkey using the given function only ifkey already exists inmap.
In comparison toreplace/3, this can be useful when it's expensive to calculate the value.
Ifkey does not exist, the original map is returned unchanged.
Examples
iex>Map.replace_lazy(%{a:1,b:2},:a,fnv->v*4end)%{a:4,b:2}iex>Map.replace_lazy(%{a:1,b:2},:c,fnv->v*4end)%{a:1,b:2}Takes all entries corresponding to the givenkeys inmap and extractsthem into a separate map.
Returns a tuple with the new map and the old map with removed keys.
Keys for which there are no entries inmap are ignored.
Examples
iex>Map.split(%{a:1,b:2,c:3},[:a,:c,:e]){%{a:1,c:3},%{b:2}}Splits themap into two maps according to the given functionfun.
fun receives each{key, value} pair in themap as its only argument. Returnsa tuple with the first map containing all the elements inmap for whichapplyingfun returned a truthy value, and a second map with all the elementsfor which applyingfun returned a falsy value (false ornil).
Examples
iex>Map.split_with(%{a:1,b:2,c:3,d:4},fn{_k,v}->rem(v,2)==0end){%{b:2,d:4},%{a:1,c:3}}iex>Map.split_with(%{a:1,b:-2,c:1,d:-3},fn{k,_v}->kin[:b,:d]end){%{b:-2,d:-3},%{a:1,c:1}}iex>Map.split_with(%{a:1,b:-2,c:1,d:-3},fn{_k,v}->v>50end){%{},%{a:1,b:-2,c:1,d:-3}}iex>Map.split_with(%{},fn{_k,v}->v>50end){%{},%{}}Returns a new map with all the key-value pairs inmap where the keyis inkeys.
Ifkeys contains keys that are not inmap, they're simply ignored.
Examples
iex>Map.take(%{a:1,b:2,c:3},[:a,:c,:e])%{a:1,c:3}Convertsmap to a list.
Each key-value pair in the map is converted to a two-element tuple{key, value} in the resulting list.
Inlined by the compiler.
Examples
iex>Map.to_list(%{a:1})[a:1]iex>Map.to_list(%{1=>2})[{1,2}]@spec update(map(),key(), default ::value(), (existing_value ::value() -> new_value ::value())) ::map()
Updates thekey inmap with the given function.
Ifkey is present inmap then the existing value is passed tofun and its result isused as the updated value ofkey. Ifkey isnot present inmap,default is inserted as the value ofkey. The defaultvalue will not be passed through the update function.
Examples
iex>Map.update(%{a:1},:a,13,fnexisting_value->existing_value*2end)%{a:2}iex>Map.update(%{a:1},:b,11,fnexisting_value->existing_value*2end)%{a:1,b:11}Updateskey with the given function.
Ifkey is present inmap then the existing value is passed tofun and its result isused as the updated value ofkey. Ifkey isnot present inmap, aKeyError exception is raised.
Examples
iex>Map.update!(%{a:1},:a,&(&1*2))%{a:2}iex>Map.update!(%{a:1},:b,&(&1*2))** (KeyError) key :b not found in: %{a: 1}Returns all values frommap.
Inlined by the compiler.
Examples
Map.values(%{a:1,b:2})[1,2]