View Source Moar.Map (Moar v1.58.0)

Map-related functions.

Summary

Functions

Converts key in map to an atom, optionally transforming the value with value_transformer.

Converts keys in map to atoms.

Removes keys from a map where the value is nil.

Converts keys to atoms, traversing through descendant lists and maps.

Deeply merges two maps into a single map. (It will also accept keyword lists and convert them to maps, as long as they are not empty lists.)

Takes keys from nested maps.

Converts a list of maps into a map of maps indexed by the values of one of the map keys. It's a map-specific version of the more generic Moar.Enum.index_by/2.

Merges two enumerables into a single map. Supports nil values for either enumerable.

Merges two maps, retaining any existing non-blank values.

Puts a key/value pair into the given map if the key is not alredy in the map, or if the value in the map is blank as defined by Moar.Term.blank?/1.

Like Map.put_new/3 but raises if key already exists in map.

Returns a copy of map with old_key_name changed to new_key_name.

Returns a copy of map with old_key_name changed to new_key_name.

Like rename_key/2 but raises if key is not in map

Like rename_key/3 but raises if key is not in map

Returns a copy of map after changing key names supplied by keys_map.

Like rename_keys/2 but raises if any key in keys_map is not in map.

Converts keys in map to strings.

Transforms values of map using transformer function.

Validates that the keys of map are equal to or a subset of valid_keys. In addition to being a list, valid_keys can be a map or struct, in which case the keys of the map or struct are used as the list of valid keys.

Functions

Link to this function

atomize_key(map, key, value_transformer \\ &Function.identity/1)

View Source
@spec atomize_key(map(), binary() | atom(), (any() -> any()) | nil) :: map()

Converts key in map to an atom, optionally transforming the value with value_transformer.

Raises if key is a string and map already has an atomized version of that key.

iex> Moar.Map.atomize_key(%{"number-one" => "one", "number-two" => "two"}, "number-one")
%{:number_one => "one", "number-two" => "two"}

iex> Moar.Map.atomize_key(%{"number-one" => "one", "number-two" => "two"}, "number-one", &String.upcase/1)
%{:number_one => "ONE", "number-two" => "two"}
Link to this function

atomize_key!(map, key, value_fn \\ &Function.identity/1)

View Source
@spec atomize_key!(map(), binary() | atom(), (any() -> any()) | nil) :: map()

Like atomize_key/3 but raises if key is not in map.

@spec atomize_keys(map()) :: map()

Converts keys in map to atoms.

Raises if converting a key from a string to an atom would result in a key conflict.

iex> Moar.Map.atomize_keys(%{"a" => 1, "b" => 2})
%{a: 1, b: 2}
@spec compact(map()) :: map()

Removes keys from a map where the value is nil.

iex> Moar.Map.compact(%{a: 1, b: nil, c: ""})
%{a: 1, c: ""}
@spec deep_atomize_keys(list() | map()) :: map()

Converts keys to atoms, traversing through descendant lists and maps.

Raises if converting a key from a string to an atom would result in a key conflict.

iex> Moar.Map.deep_atomize_keys(%{"a" => %{"aa" => 1}, "b" => [%{"bb" => 2}, %{"bbb" => 3}]})
%{a: %{aa: 1}, b: [%{bb: 2}, %{bbb: 3}]}
Link to this function

deep_merge(a, b, conflict_fn \\ fn _val1, val2 -> val2 end)

View Source
@spec deep_merge(map() | keyword(), map() | keyword(), (any(), any() -> any())) ::
  map()

Deeply merges two maps into a single map. (It will also accept keyword lists and convert them to maps, as long as they are not empty lists.)

Optionally accepts conflict_fn which gets called when both enumerables have values at the same keypath. It receives the conflicting values from each map and is expected to return the winning value.

iex> Moar.Map.deep_merge(%{fruit: %{apples: 3, bananas: 5}, veggies: %{carrots: 10}}, [fruit: [cherries: 20]])
%{fruit: %{apples: 3, bananas: 5, cherries: 20}, veggies: %{carrots: 10}}

iex> Moar.Map.deep_merge(%{a: %{b: 1}}, %{a: %{b: 2}})
%{a: %{b: 2}}

iex> Moar.Map.deep_merge(%{a: %{b: 1}}, %{a: %{b: 2}}, fn x, _y -> x end)
%{a: %{b: 1}}

iex> Moar.Map.deep_merge(%{a: %{b: 1}}, %{a: %{b: 2}}, fn x, y -> [x, y] end)
%{a: %{b: [1, 2]}}
@spec deep_take(
  map(),
  [atom() | binary() | {atom() | binary(), list() | map()}] | map()
) :: map()

Takes keys from nested maps.

iex> Moar.Map.deep_take(%{a: 1, b: %{c: 2, d: 3}, z: 9}, [:a, b: [:c]])
%{a: 1, b: %{c: 2}}
Link to this function

index_by(list_of_maps, key)

View Source
@spec index_by([map()], any()) :: map()

Converts a list of maps into a map of maps indexed by the values of one of the map keys. It's a map-specific version of the more generic Moar.Enum.index_by/2.

iex> Moar.Map.index_by([%{name: "Alice", tid: "alice"}, %{name: "Billy", tid: "billy"}], :tid)
%{"alice" => %{name: "Alice", tid: "alice"}, "billy" => %{name: "Billy", tid: "billy"}}
@spec merge(Enum.t() | nil, Enum.t() | nil) :: map()

Merges two enumerables into a single map. Supports nil values for either enumerable.

iex> Moar.Map.merge(%{a: 1}, [b: 2])
%{a: 1, b: 2}

iex> Moar.Map.merge(nil, [a: 1])
%{a: 1}
@spec merge_if_blank(map(), map()) :: map()

Merges two maps, retaining any existing non-blank values.

iex> Moar.Map.merge_if_blank(%{a: 1, b: nil, c: ""}, %{a: 100, b: 2, c: 3, d: 4})
%{a: 1, b: 2, c: 3, d: 4}
Link to this function

put_if_blank(map, key, value)

View Source
@spec put_if_blank(map() | keyword(), any(), any()) :: map()

Puts a key/value pair into the given map if the key is not alredy in the map, or if the value in the map is blank as defined by Moar.Term.blank?/1.

Also, the map parameter can be any enumerable that can be turned into a map via Enum.into/2.

iex> %{a: 1} |> Moar.Map.put_if_blank(:b, 2)
%{a: 1, b: 2}

iex> %{a: 1, b: nil} |> Moar.Map.put_if_blank(:b, 2)
%{a: 1, b: 2}

iex> %{a: 1, b: 3} |> Moar.Map.put_if_blank(:b, 2)
%{a: 1, b: 3}
Link to this function

put_new!(map, key, value)

View Source
@spec put_new!(map(), any(), any()) :: map()

Like Map.put_new/3 but raises if key already exists in map.

iex> Moar.Map.put_new!(%{a: 1}, :b, 2)
%{a: 1, b: 2}

iex> Moar.Map.put_new!(%{a: 1, b: 2}, :b, 3)
** (RuntimeError) Map already contains key: :b
Link to this function

rename_key(map, old_and_new_key)

View Source
@spec rename_key(
  map(),
  {binary(), binary()}
) :: map()

Returns a copy of map with old_key_name changed to new_key_name.

old_key_name and new_key_name are passed in as a {old_key_name, new_key_name} tuple.

iex> %{"color" => "red", "size" => "medium"} |> Moar.Map.rename_key({"color", "colour"})
%{"colour" => "red", "size" => "medium"}
Link to this function

rename_key(map, old_key_name, new_key_name)

View Source
@spec rename_key(map(), binary() | atom(), binary() | atom()) :: map()

Returns a copy of map with old_key_name changed to new_key_name.

iex> %{"color" => "red", "size" => "medium"} |> Moar.Map.rename_key("color", "colour")
%{"colour" => "red", "size" => "medium"}
Link to this function

rename_key!(map, old_and_new_key)

View Source
@spec rename_key!(
  map(),
  {binary(), binary()}
) :: map()

Like rename_key/2 but raises if key is not in map

Link to this function

rename_key!(map, old_key_name, new_key_name)

View Source
@spec rename_key!(map(), binary() | atom(), binary() | atom()) :: map()

Like rename_key/3 but raises if key is not in map

Link to this function

rename_keys(map, keys_map)

View Source
@spec rename_keys(map(), map()) :: map()

Returns a copy of map after changing key names supplied by keys_map.

%{"behavior" => "chill", "color" => "red"} |> Moar.Map.rename_keys(%{"behavior" => "behaviour", "color" => "colour"})
%{"behaviour" => "chill", "colour" => "red"}
Link to this function

rename_keys!(map, keys_map)

View Source
@spec rename_keys!(map(), map()) :: map()

Like rename_keys/2 but raises if any key in keys_map is not in map.

@spec stringify_keys(map()) :: map()

Converts keys in map to strings.

iex> Moar.Map.stringify_keys(%{a: 1, b: 2} )
%{"a" => 1, "b" => 2}
Link to this function

transform(map, keys, transformer)

View Source
@spec transform(map(), atom() | binary() | list(), (any() -> any())) :: map()

Transforms values of map using transformer function.

iex> %{"foo" => "chicken", "bar" => "cow", "baz" => "pig"} |> Moar.Map.transform("foo", &String.upcase/1)
%{"foo" => "CHICKEN", "bar" => "cow", "baz" => "pig"}

iex> %{"foo" => "chicken", "bar" => "cow", "baz" => "pig"} |> Moar.Map.transform(["foo", "bar"], &String.upcase/1)
%{"foo" => "CHICKEN", "bar" => "COW", "baz" => "pig"}
Link to this function

validate_keys!(map, valid_keys)

View Source
@spec validate_keys!(map(), list() | map() | struct()) :: map()

Validates that the keys of map are equal to or a subset of valid_keys. In addition to being a list, valid_keys can be a map or struct, in which case the keys of the map or struct are used as the list of valid keys.

It returns the input map, or raises an exception if there are non-allowed keys.

iex> Moar.Map.validate_keys!(%{a: 1, b: 2}, [:a, :b, :c])
%{a: 1, b: 2}

iex> Moar.Map.validate_keys!(%{a: 1, b: 2}, %{a: nil, b: 2, c: :foo})
%{a: 1, b: 2}

iex> Moar.Map.validate_keys!(%{a: 1, b: 2}, [:a, :c])
** (ArgumentError) Non-allowed keys found in map: [:b]