@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"}

@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 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}]}

@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.)

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}}

@spec merge(Enum.t(), Enum.t()) :: map()

Merges two enumerables into a single map.

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

@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}

@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"}

@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"}

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

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

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

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

@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"}

@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}

@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"}