maps(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

🌸 maps(3) — Erlang Module Definition 🌸

okay bestie, welcome to maps(3) 💖 this is THE page for wrangling Erlang maps, and honestly? she ate. let's get into it 🫶

✨ NAME ✨

maps — maps processing functions 💅

🦋 DESCRIPTION 🦋

This module contains functions for maps processing, periodt. There's a chapter in the Efficiency Guide that describes how to use maps efficiently — so if you wanna be fast and not messy, go read that, iykyk 👑

🎀 DATA TYPES 🎀

iterator() :: iterator(term(), term()).

-opaque iterator(Key, Value)

An iterator representing the associations in a map with keys of type Key and values of type Value. It's like a little cursor that walks your map, no cap 🚶‍♀️✨

Created using maps:iterator/1 or maps:iterator/2.

Consumed by:

  • maps:next/1
  • maps:filter/2
  • maps:filtermap/2
  • maps:fold/3
  • maps:foreach/2
  • maps:map/2
  • maps:to_list/1

iterator_order() :: iterator_order(term()).

iterator_order(Key) ::
          undefined | ordered | reversed |
          fun((A :: Key, B :: Key) -> boolean()).

A key-based iterator order option, and she can be one of: undefined (the default for maps:iterator/1), ordered (sorted in map-key order), reversed (sorted in reverse map-key order), or a custom sorting function if you're feeling fancy 🌈

Used by maps:iterator/2.

The Expressions section contains descriptions of how terms are ordered — go peek if you need the deets 📖

👑 FUNCTIONS 👑

💖 filter(Pred, MapOrIter) -> Map

filter(Pred, MapOrIter) -> Map
                when
                    Pred :: fun((Key, Value) -> boolean()),
                    MapOrIter :: #{Key => Value} | iterator(Key, Value),
                    Map :: #{Key => Value}.

Returns a map Map where each key-value pair from MapOrIter satisfies the predicate Pred(Key, Value). Basically only the pairs that pass the vibe check get to stay 🎀

Unless MapOrIter is an ordered iterator returned by iterator/2, the order of the Pred(Key, Value) calls is not defined. so don't come at me about the order, it's giving chaos 🌪️

The call fails with a {badmap,Map} exception if MapOrIter is not a map or valid iterator, or with badarg if Pred is not a function of arity 2.

Examples

1> M = #{a => 2, b => 3, "a" => 1, "b" => 2}.
2> Pred = fun(K, V) -> is_atom(K) andalso V rem 2 =:= 0 end.
3> maps:filter(Pred, M).
#{a => 2}

🦋 filtermap(Fun, MapOrIter) -> Map

filtermap(Fun, MapOrIter) -> Map
                   when
                       Fun ::
                           fun((Key, Value1) ->
                                   boolean() | {true, Value2}),
                       MapOrIter ::
                           #{Key => Value1} | iterator(Key, Value1),
                       Map :: #{Key => Value1 | Value2}.

Calls Fun(Key, Value1) on each key-value pair of MapOrIter to update or remove associations from MapOrIter. It's literally filter plus a glow-up, obsessed 😭

  • If Fun(Key, Value1) returns true, the association is copied to the result map.
  • If it returns false, the association is not copied.
  • If it returns {true, NewValue}, the value for Key is replaced with NewValue in the result map.

Unless MapOrIter is an ordered iterator returned by iterator/2, the order of the Fun(Key, Value1) calls is not defined.

The call fails with a {badmap,Map} exception if MapOrIter is not a map or valid iterator, or with badarg if Fun is not a function of arity 2.

Examples

1> Fun = fun(K, V) when is_atom(K) -> {true, V*2};
           (_, V) -> V rem 2 =:= 0
  end.
2> Map = #{k1 => 1, "k2" => 2, "k3" => 3}.
3> maps:filtermap(Fun, Map).
#{k1 => 2,"k2" => 2}

🔥 find(Key, Map) -> {ok, Value} | error

find(Key, Map) -> {ok, Value} | error
              when Map :: #{Key => Value, _ => _}.

Returns a tuple {ok, Value}, where Value is the value associated with Key, or error if no value is associated with Key in Map. she's either serving or she's not, no in-between 💀

The call fails with a {badmap,Map} exception if Map is not a map.

Examples

1> Map = #{"hi" => 42}.
2> Key = "hi".
3> maps:find(Key, Map).
{ok,42}

🌟 fold(Fun, Init, MapOrIter) -> Acc

fold(Fun, Init, MapOrIter) -> Acc
              when
                  Fun :: fun((Key, Value, AccIn) -> AccOut),
                  Init :: term(),
                  Acc :: AccOut,
                  AccIn :: Init | AccOut,
                  MapOrIter :: #{Key => Value} | iterator(Key, Value).

Calls Fun(Key, Value, AccIn) for every Key to value Value association in MapOrIter, starting with AccIn bound to Acc0.

The Fun/3 fun must return a new accumulator, which is passed to the next call. The function returns the final value of the accumulator. The initial accumulator value Init is returned if the map is empty. carrying the acc through every single pair, main character energy fr fr 👑

Unless MapOrIter is an ordered iterator returned by iterator/2, the order of the Fun(Key, Value, AccIn) calls is not defined.

The call fails with a {badmap,Map} exception if MapOrIter is not a map or valid iterator, or with badarg if Fun is not a function of arity 3.

Examples

1> Fun = fun(K, V, AccIn) -> AccIn + V end.
2> Map = #{k1 => 1, k2 => 2, k3 => 3}.
3> maps:fold(Fun, 0, Map).
6

🍓 foreach(Fun, MapOrIter) -> ok

foreach(Fun, MapOrIter) -> ok
                 when
                     Fun :: fun((Key, Value) -> term()),
                     MapOrIter :: #{Key => Value} | iterator(Key,
Value).

Calls Fun(Key, Value) for every Key to Value association in MapOrIter. side effects only, she returns ok and minds her own business 💅

Unless MapOrIter is an ordered iterator returned by iterator/2, the order of the Fun(Key, Value) calls is not defined.

The call fails with a {badmap,Map} exception if MapOrIter is not a map or valid iterator, or with badarg if Fun is not a function of arity 2.

Examples

1> Fun = fun(K, V) -> self() ! {K,V} end.
2> Map = #{p => 1, q => 2,x => 10, y => 20, z => 30}.
3> maps:foreach(Fun, maps:iterator(Map, ordered)).
ok
4> [receive X -> X end || _ <- [1,2,3,4,5]].
[{p,1},{q,2},{x,10},{y,20},{z,30}]

🧚 from_keys(Keys, Value) -> Map

from_keys(Keys, Value) -> Map
                   when Keys :: list(), Value :: term(), Map :: map().

Takes a list of keys and a value and builds a map where all keys are associated with the same value. one value, many keys, they all share, iconic 🌈

Examples

1> Keys = ["a", "b", "c"].
2> maps:from_keys(Keys, ok).
#{"a" => ok,"b" => ok,"c" => ok}

💜 from_list(List) -> Map

from_list(List) -> Map
                   when
                       List :: [{Key, Value}],
                       Key :: term(),
                       Value :: term(),
                       Map :: map().

Takes a list of key-value tuples and builds a map. glow-up complete ✨

If the same key appears more than once, the last (rightmost) value is used, and previous values are ignored. so the later ones ate, the earlier ones are just gone, sorry bestie 😭

Examples

1> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}].
2> maps:from_list(List).
#{42 => value_three,1337 => "value two","a" => 1}

🫶 get(Key, Map) -> Value

get(Key, Map) -> Value
             when Key :: term(), Map :: map(), Value :: term().

Returns value Value associated with Key if Map contains Key.

The call fails with a {badmap,Map} exception if Map is not a map, or with a {badkey,Key} exception if no value is associated with Key. so if she's not there, she's gonna let you know 💀

Examples

1> Key = 1337.
2> Map = #{42 => value_two,1337 => "value one","a" => 1}.
3> maps:get(Key, Map).
"value one"

🌸 get(Key, Map, Default) -> Value | Default

get(Key, Map, Default) -> Value | Default
             when Map :: #{Key => Value, _ => _}.

Returns the value associated with key Key in Map, or Default if Key is not present in the map. the backup plan came through, we love a safety net 🥺

The call fails with a {badmap,Map} exception if Map is not a map.

Examples

1> Map = #{key1 => val1, key2 => val2}.
#{key1 => val1,key2 => val2}
2> maps:get(key1, Map, "Default value").
val1
3> maps:get(key3, Map, "Default value").
"Default value"

🎀 groups_from_list(KeyFun, List) -> GroupsMap

groups_from_list(KeyFun, List) -> GroupsMap
                          when
                              KeyFun :: fun((Elem) -> Key),
                              GroupsMap :: #{Key => Group},
                              Key :: term(),
                              List :: [Elem],
                              Group :: [Elem],
                              Elem :: term().

Partitions the given List into a map of groups. sorting the friend group, one clique at a time 💅

The result is a map where each key is given by KeyFun and each value is a list of elements from the given List for which KeyFun returned the same key.

The order of elements within each group list is preserved from the original list. no shuffle, promise 🙈

Examples

1> EvenOdd = fun(X) when X rem 2 =:= 0 -> even;
                     (_) -> odd
  end.
2> maps:groups_from_list(EvenOdd, [1, 2, 3]).
#{even => [2], odd => [1, 3]}
3> maps:groups_from_list(fun length/1, ["ant", "buffalo", "cat", "dingo"]).
#{3 => ["ant", "cat"], 5 => ["dingo"], 7 => ["buffalo"]}

🦄 groups_from_list(KeyFun, ValueFun, List) -> GroupsMap

groups_from_list(KeyFun, ValueFun, List) -> GroupsMap
                          when
                              KeyFun :: fun((Elem) -> Key),
                              ValueFun :: fun((Elem) -> Value),
                              GroupsMap :: #{Key := Group},
                              Key :: term(),
                              Value :: term(),
                              List :: [Elem],
                              Group :: [Value],
                              Elem :: term().

Partitions the given List into a map of groups. same energy as the last one but now she's also transforming the values on the way in 😌

The result is a map where each key is given by KeyFun and each value is a list of elements from the given List, mapped via ValueFun, for which KeyFun returned the same key.

The order of elements within each group list is preserved from the original list.

Examples

1> EvenOdd = fun(X) -> case X rem 2 of 0 -> even; 1 -> odd end end.
2> Square = fun(X) -> X * X end.
3> maps:groups_from_list(EvenOdd, Square, [1, 2, 3]).
#{even => [4], odd => [1, 9]}
4> maps:groups_from_list(
    fun length/1,
    fun lists:reverse/1,
    ["ant", "buffalo", "cat", "dingo"]).
#{3 => ["tna", "tac"],5 => ["ognid"],7 => ["olaffub"]}

🌈 intersect(Map1, Map2) -> Map3

intersect(Map1, Map2) -> Map3
                   when
                       Map1 :: #{Key => term()},
                       Map2 :: #{term() => Value2},
                       Map3 :: #{Key => Value2}.

Computes the intersection of maps Map1 and Map2, producing a single map Map3. only the shared keys survive the vibe check ✂️

If a key exists in both maps, the value in Map1 is superseded by the value in Map2. Map2 ate, periodt. Keys existing in only one of the maps are discarded along with their values, rip to them 🪦

...and if Map1 or Map2 isn't a map, the call just fails with a {badmap,Map} exception. no vibes, only consequences 💀

Examples ✨

1> Map1 = #{a => "one", b => "two"}.
2> Map2 = #{a => 1, c => 3}.
3> maps:intersect(Map1, Map2).
#{a => 1}

intersect_with(Combiner, Map1, Map2) -> Map3

intersect_with(Combiner, Map1, Map2) -> Map3
                        when
                            Map1 :: #{Key => Value1},
                            Map2 :: #{term() => Value2},
                            Combiner ::
                                fun((Key, Value1, Value2) ->
                                        CombineResult),
                            Map3 :: #{Key => CombineResult}.

okay so this one is intersect but make it fancy 🎀 It computes the intersection of the maps Map1 and Map2, giving you back a single map Map3, and wherever the same key shows up, the values get combined by your Combiner fun. it's giving collaborative.

when Combiner gets called, the key that lives in both maps is the first parameter, the value from Map1 is the second parameter, and the value from Map2 is the third parameter. order matters bestie, don't mix them up 💅

this call fails with a {badmap,Map} exception if Map1 or Map2 isn't a map. and it fails with a badarg exception if Combiner isn't a fun that takes three arguments. three. not two, not four. three. 👑

Examples ✨

1> Map1 = #{a => "one", b => "two"}.
2> Map2 = #{a => 1, c => 3}.
3> maps:intersect_with(fun(_Key, Val1, Val2) -> {Val1, Val2} end, Map1, Map2).
#{a => {"one",1}}

is_key(Key, Map) -> boolean()

is_key(Key, Map) -> boolean() when Key :: term(), Map :: map().

returns true if the map Map contains Key; otherwise, returns false. that's it, that's the whole function. simple. iconic. 🦋

the call fails with a {badmap,Map} exception if Map is not a map.

Examples ✨

1> Map = #{"42" => value}.
#{"42" => value}
2> maps:is_key("42", Map).
true
3> maps:is_key(value, Map).
false

iterator(Map) -> Iterator

iterator(Map) -> Iterator
                  when
                      Map :: #{Key => Value},
                      Iterator :: iterator(Key, Value).

returns a map iterator Iterator that you can hand to maps:next/1 to traverse the key-value associations in a map. it's like a lil cursor that walks the map for you 🚶‍♀️

⚠️ the order of iteration is undefined, so don't you dare assume anything about it. but here's the good news: when iterating over a map, the memory usage is guaranteed to be bounded no matter the size of the map. tiny memory footprint, big map energy 🌈

the call fails with a {badmap,Map} exception if Map is not a map.

Examples ✨

1> M = #{ "foo" => 1, "bar" => 2 }.
#{"foo" => 1,"bar" => 2}
2> I = maps:iterator(M).
3> {K1, V1, I2} = maps:next(I), {K1, V1}.
{"bar",2}
4> {K2, V2, I3} = maps:next(I2),{K2, V2}.
{"foo",1}
5> maps:next(I3).
none

iterator(Map, Order) -> Iterator

iterator(Map, Order) -> Iterator
                  when
                      Map :: #{Key => Value},
                      Order :: iterator_order(Key),
                      Iterator :: iterator(Key, Value).

same idea but now you get to pick the Order ✨ returns a map iterator Iterator that can be used by maps:next/1 to traverse the key-value associations in a map sorted by key using the given Order. now that's what I call a glow-up 💅

the call fails with a {badmap,Map} exception if Map is not a map, or with a badarg exception if Order is invalid. invalid order = instant rejection, no cap 🙅‍♀️

Examples 🌸

ordered iterator:

1> M = #{a => 1, b => 2}.
2> OrdI = maps:iterator(M, ordered).
3> {K1, V1, OrdI2} = maps:next(OrdI), {K1, V1}.
{a,1}
4> {K2, V2, OrdI3} = maps:next(OrdI2),{K2, V2}.
{b,2}
5> maps:next(OrdI3).
none

iterator ordered in reverse 🔄:

1> M = #{a => 1, b => 2}.
2> RevI = maps:iterator(M, reversed).
3> {K2, V2, RevI2} = maps:next(RevI), {K2, V2}.
{b,2}
4> {K1, V1, RevI3} = maps:next(RevI2),{K1, V1}.
{a,1}
5> maps:next(RevI3).
none
6> maps:to_list(RevI).
[{b,2},{a,1}]

and if you're feeling extra, using a custom ordering function that orders binaries by size 🫶:

1> M = #{<<"abcde">> => d, <<"y">> => b, <<"x">> => a, <<"pqr">> => c}.
2> SizeI = fun(A, B) when byte_size(A) < byte_size(B) -> true;
             (A, B) when byte_size(A) > byte_size(B) -> false;
             (A, B) -> A =< B
          end.
3> SizeOrdI = maps:iterator(M, SizeI).
4> maps:to_list(SizeOrdI).
[{<<"x">>,a},{<<"y">>,b},{<<"pqr">>,c},{<<"abcde">>,d}]

keys(Map) -> Keys

keys(Map) -> Keys when Map :: #{Key => _}, Keys :: [Key].

returns a complete list of keys contained in Map, in any order. any order!! do not @ me about ordering, there is no ordering 🫠

the call fails with a {badmap,Map} exception if Map is not a map.

Examples ✨

1> Map = #{42 => three,1337 => "two","a" => 1}.
2> maps:keys(Map).
[42,1337,"a"]

map(Fun, MapOrIter) -> Map

map(Fun, MapOrIter) -> Map
               when
                   Fun :: fun((Key, Value1) -> Value2),
                   MapOrIter :: #{Key => Value1} | iterator(Key, Value1),
                   Map :: #{Key => Value2}.

produces a brand new map Map by calling the function Fun(Key, Value1) for every Key-to-value Value1 association in MapOrIter. it's the map equivalent of a makeover montage 💖

the Fun/2 fun must return value Value2 to be associated with key Key for the new map Map.

unless MapOrIter is an ordered iterator returned by iterator/2, the order of the Fun(Key, Value1) calls is not defined. so if order matters to you... it doesn't, unless you got that ordered iterator. periodt.

the call fails with a {badmap,Map} exception if MapOrIter is not a map or a valid iterator, or with badarg if Fun is not a function of arity 2.

Examples ✨

1> Fun = fun(K,V1) when is_list(K) -> V1*2 end.
2> Map = #{"k1" => 1, "k2" => 2, "k3" => 3}.
3> maps:map(Fun, Map).
#{"k1" => 2,"k2" => 4,"k3" => 6}

merge(Map1, Map2) -> Map3

merge(Map1, Map2) -> Map3
                 when Map1 :: map(), Map2 :: map(), Map3 :: map().

merges maps Map1 and Map2 into a single map Map3, where values from Map2 override those from Map1 for duplicate keys. Map2 wins the argument, every time, sorry Map1 😭

the call fails with a {badmap,Map} exception if Map1 or Map2 is not a map.

Examples ✨

1> Map1 = #{a => "one", b => "two"}.
2> Map2 = #{a => 1, c => 3}.
3> maps:merge(Map1, Map2).
#{a => 1,b => "two",c => 3}

merge_with(Combiner, Map1, Map2) -> Map3

merge_with(Combiner, Map1, Map2) -> Map3
                      when
                          Map1 :: #{Key1 => Value1},
                          Map2 :: #{Key2 => Value2},
                          Combiner ::
                              fun((Key1, Value1, Value2) ->
       CombineResult),
                          Map3 ::
                              #{Key1 => CombineResult,
                                Key1 => Value1,
                                Key2 => Value2}.

merges maps Map1 and Map2 into a single map Map3, combining values for duplicate keys using the Combiner fun. no silent overrides here, we're negotiating 🤝

when Combiner is applied, the key that exists in both maps is the first parameter, the value from Map1 is the second parameter, and the value from Map2 is the third parameter.

the call fails with a {badmap,Map} exception if Map1 or Map2 is not a map. the call fails with a badarg exception if Combiner is not a fun that takes three arguments. yes, again, THREE 🚨

Examples ✨

1> Map1 = #{a => 3, b => 5}.
2> Map2 = #{a => 4, c => 17}.
3> maps:merge_with(fun(_Key, Val1, Val2) -> Val1 + Val2 end, Map1, Map2).
#{a => 7,b => 5,c => 17}

new() -> Map

new() -> Map when Map :: #{}.

returns a new empty map. that's it. a lil blank canvas for your main character era 🎀

Examples ✨

1> maps:new().
#{}

next(Iterator) -> {Key, Value, NextIterator} | none

next(Iterator) -> {Key, Value, NextIterator} | none
                when
                    Iterator :: iterator(Key, Value),
                    NextIterator :: iterator(Key, Value).

returns the next key-value association in Iterator and a new iterator for the remaining associations in the iterator. two for one, slay 💅

if there are no more associations in the iterator, none is returned. that's the "we're done here" signal 🫡

Examples ✨

1> Map = #{a => 1, b => 2, c => 3}.
#{a => 1,b => 2,c => 3}
2> I = maps:iterator(Map, ordered).
3> {K1, V1, I1} = maps:next(I), {K1, V1}.
{a,1}
4> {K2, V2, I2} = maps:next(I1), {K2, V2}.
{b,2}
5> {K3, V3, I3} = maps:next(I2), {K3, V3}.
{c,3}
6> maps:next(I3).
none

put(Key, Value, Map1) -> Map2

put(Key, Value, Map1) -> Map2
               when
                   Key :: term(),
                   Value :: term(),
                   Map1 :: map(),
                   Map2 :: map().

associates Key with Value in Map1, replacing any existing value, and returns a new map Map2 with the updated association alongside the original entries from Map1. nothing gets lost, everything gets upgraded ✨

the call fails with a {badmap,Map} exception if Map1 is not a map.

Examples ✨

1> Map = #{"a" => 1}.
#{"a" => 1}
2> maps:put("a", 42, Map).
#{"a" => 42}
3> maps:put("b", 1337, Map).
#{"a" => 1,"b" => 1337}

remove(Key, Map1) -> Map2

remove(Key, Map1) -> Map2
                  when Key :: term(), Map1 :: map(), Map2 :: map().

removes Key and its associated value from Map1, if it exists, and returns a new map Map2 without Key. if it doesn't exist... it just doesn't, and you get your map back unbothered 🙈

the call fails with a {badmap,Map} exception if Map1 is not a map.

Examples ✨

1> Map = #{"a" => 1}.
#{"a" => 1}
2> maps:remove("a", Map).
#{}
3> maps:remove("b", Map).
#{"a" => 1}

size(Map) -> non_neg_integer()

size(Map) -> non_neg_integer() when Map :: map().

returns the number of key-value associations in Map.

this operation occurs in constant time. constant!! that's the flex 🔥 no matter how big your map is, size/1 is not the one struggling.

Examples ✨

1> Map = #{42 => value_two,1337 => "value one","a" => 1}.
2> maps:size(Map).
3

take(Key, Map1) -> {Value, Map2} | error

take(Key, Map1) -> {Value, Map2} | error
                when Map1 :: #{Key => Value, _ => _}, Map2 :: #{_ => _}.

removes Key and its associated value from Map1, if it exists, returning a tuple with the removed value Value and the new map Map2; otherwise, returns error. it's giving "take it and go" 💅

the call will fail with a {badmap,Map} exception if Map1 is not a map.

example:

1> Map = #{"a" => "hello", "b" => "world"}.
#{"a" => "hello", "b" => "world"}
2> maps:take("a", Map).
{"hello",#{"b" => "world"}}
3> maps:take("does not exist", Map).
error

to_list(MapOrIterator) -> [{Key, Value}]

to_list(MapOrIterator) -> [{Key, Value}]
                  when
                      MapOrIterator ::
                          #{Key => Value} | iterator(Key, Value).

returns a list of pairs representing the key-value associations of MapOrIterator.

unless MapOrIter is an ordered iterator returned by iterator/2, the order of the {Key, Value} tuples in the resulting list is not defined. like, it's giving chaos, bestie 💀 nothing is promised.

The call fails with a {badmap,Map} exception if MapOrIterator is not a map or an iterator obtained by a call to iterator/1 or iterator/2. so don't hand it a random thing, she WILL scream at you.

✨ Examples

1> Map = #{42 => value_three,1337 => "value two","a" => 1}.
2> maps:to_list(Map).
[{42,value_three},{1337,"value two"},{"a",1}]

Using an ordered iterator to return an ordered list 🎀:

1> Map = #{z => 1, y => 2, x => 3}.
2> maps:to_list(maps:iterator(Map, ordered)).
[{x,3},{y,2},{z,1}]

💖 update(Key, Value, Map1) -> Map2

when
    Map1 :: #{Key := _, _ => _},
    Map2 :: #{Key := Value, _ => _}.

If Key exists in Map1, its value is replaced with Value, and the function returns a new map Map2 with the updated association. it's a glow-up for one single key, no cap 💅

The call fails with a {badmap,Map} exception if Map1 is not a map, or with a {badkey,Key} exception if no value is associated with Key. so if the key isn't there? we do NOT invent it. she refuses. 🙈

✨ Examples

1> Map = #{"a" => 1}.
#{"a" => 1}
2> maps:update("a", 42, Map).
#{"a" => 42}

🌸 update_with(Key, Fun, Map1) -> Map2

when
    Map1 :: #{Key := Value1, _ => _},
    Map2 :: #{Key := Value2, _ => _},
    Fun :: fun((Value1) -> Value2).

Updates a value in Map1 associated with Key by calling Fun on the old value to produce a new value. it's the "take what's there and make it better" of it all ✨

The call fails with a {badkey,Key} exception if Key is not present in the map. no key, no vibes, no update. periodt.

✨ Examples

1> Map = #{counter => 1}.
2> Fun = fun(V) -> V + 1 end.
3> maps:update_with(counter, Fun, Map).
#{counter => 2}

🦋 update_with(Key, Fun, Init, Map1) -> Map2

when
    Map1 :: #{Key => Value1, _ => _},
    Map2 :: #{Key := Value2 | Init, _ => _},
    Fun :: fun((Value1) -> Value2).

Updates the value in Map1 for Key by applying Fun to the old value or using Init if Key is not present in the map. so this one is the extrovert version — she'll introduce herself with Init if nobody's home 🫶

✨ Examples

1> Map = #{"counter" => 1}.
2> Fun = fun(V) -> V + 1 end.
3> maps:update_with("counter", Fun, 42, Map).
#{"counter" => 2}
4> maps:update_with("new counter", Fun, 42, Map).
#{"counter" => 1,"new counter" => 42}

👑 values(Map) -> Values

when Map :: #{_ => Value}, Values :: [Value].

Returns a complete list of values contained in map Map, in any order. any order!! do not build your whole personality on that order, it is not defined 🫠

The call fails with a {badmap,Map} exception if Map is not a map.

✨ Examples

1> Map = #{42 => value_three,1337 => "value two","a" => 1}.
2> maps:values(Map).
[value_three,"value two",1]

🎀 with(Ks, Map1) -> Map2

when
    Ks :: [K],
    Map1 :: #{K => V, _ => _},
    Map2 :: #{K => V}.

Returns a new map Map2 with the keys K1 through Kn and their associated values from map Map1. it's a little curated playlist of keys and she only keeps the ones you asked for 💜

Any key in Ks that does not exist in Map1 is ignored. ghosted, honestly. still fine though, no error, just vibes.

✨ Examples

1> Map = #{42 => value_three,1337 => "value two","a" => 1}.
2> Keys = ["a",42,"other key"].
3> maps:with(Keys, Map).
#{42 => value_three,"a" => 1}

🌈 without(Ks, Map1) -> Map2

when
    Ks :: [K],
    Map1 :: map(),
    Map2 :: map(),
    K :: term().

Returns a new map Map2 without keys K1 through Kn and their associated values from map Map1. the block button. the unfollow. the "we don't do that here" 🌸

Any key in Ks that does not exist in Map1 is ignored. yelling at a key that was never there changes nothing, bestie.

✨ Examples

1> Map = #{42 => value_three, 1337 => "value two", "a" => 1}.
2> Keys = ["a",42,"other key"].
3> maps:without(Keys, Map).
#{1337 => "value two"}
lowkey a little sad to hit the end of the page but we made it 💖 every single function, every example, every exception — all accounted for. go forth and maps: responsibly, my love 🧚

and that's a wrap on this little document 🫶 she was brought to you by Ericsson AB, version stdlib 8.0.4, manual page maps(3) — the date wasn't printed on that footer line, so we're just hyping the source and version, periodt 👑⭐

📦 where this page comes from