View Source Bonfire.Common.Enums (Bonfire v0.9.10-classic-beta.156)

Extra functions to manipulate enumerables, basically an extension of Enum

Summary

Functions

Checks if all tuples in the enumerable are :ok.

Filters the given value or enumerable and if it contains any :error tuple, return an :error tuple with a list of error values, other return an :ok tuple with a list of values.

Gets the value of a key in a map and returns the ID of that value (i.e. either the :id field of that association, or the value itself).

Counts the number of items in an enumerable that satisfy the given function.

Recursively merges two data structures (left and right), which can be structs, maps or lists. If left and right are Ecto.Changesets, merge_changesets/2 is called on them. If left is a struct, a similar struct is returned with the merged values. If left and right are lists, they are concatenated unless :replace_lists option is set to true.

Deep merges a list of maps into a single map.

Attempt getting a value out of a map by atom key, or try with string key, or return a fallback

Takes a value and a fallback value. If the value is empty (e.g. an empty map, a non-loaded association, an empty list, an empty string, or nil), the fallback value is returned.

Takes a list and recursively flattens it by recursively flattening the head and tail of the list

Applies a function from one of Elixir's Map, Keyword, or List modules depending on the type of the given enumerable.

Like Enum.group_by/3, except children are required to be unique (will throw otherwise!) and the resulting map does not wrap each item in a list.

Groups an enumerable by a function that returns key-value pairs, ensuring that keys are unique.

Checks if the given list contains any duplicates. Takes an optional function that can be used to extract and/or compute the value to compare for each element in the list.

Checks if there are any :error tuples in the enumerable.

Checks if there are any :ok tuples in the enumerable.

Checks if there are any tuples with the given key in the enumerable.

Extracts a binary ID from various data structures, such as a map containing the key :id or "id", a changeset, or a tuple containing the atom :id.

Extracts the IDs from a list of maps, changesets, or other data structures and returns a list of these IDs.

Takes a data structure and converts any keys in maps to (previously defined) atoms, recursively. By default any unknown string keys will be discarded. It can optionally also convert string values to known atoms as well.

Converts input to value based on the provided options.

Recursively filters nil values from a map

Renames a key in a map. Optionally changes the value as well.

Renames a key in a map, only if the key exists in the map. Optionally changes the value as well.

Takes an enumerable object and converts it to a map. If it is not an enumerable, a map is created with the data under a fallback key (:data by default).

Checks a map for a value with provided key. If it already exists, the existing value is retained, but if not set or nil, then it is set to the provided default.

Updates a nested map using a list of keys and a value to set. It returns a new map with the updated value at the specified location.

Appends a value to a list, but only if the value is not nil or an empty list.

Takes any element, an index and a fallback value. If the element is a Tuple it returns either the tuple value at that index, otherwise it returns the fallback. If the tuple doesn't contain such an index, it raises ArgumentError.

Flattens the list if provided a list, otherwise just return the input

Attempts to retrieve a value from a map by its key, and otherwise returns the provided fallback value.

Updates a map with the given key and value, but only if the value is not nil, an empty list or an empty string.

Returns a keyword list representation of the input object. If the second argument is true, the function will recursively convert nested data structures to keyword lists as well. Note: make sure that all keys are atoms, i.e. using input_to_atoms first, otherwise the enumerable(s) containing a string key won't be converted.

Returns a map representation of the input object. If the second argument is true, the function will recursively convert nested data structures to maps as well.

Takes a data structure and tries to convert it to a struct, using some hints in the data (eg. __type or index_type fields) or a manually-provided type.

Takes a data structure and recursively converts any known keys to atoms and then tries to recursively convert any maps to structs, using some hints in the data (eg. __type or index_type fields).

Merges two maps or lists into a single map

Merges two Ecto changesets. If both changesets have a prepare field, the function concatenates the values of the prepare fields. Either way it also calls Ecto.Changeset.merge/2 operation.

Merges two maps while keeping only the keys that exist in the first map.

Recursively converts all nested structs to maps.

This function is used to insert a new value into a nested map data structure, where the path to the location of the value is specified as a list of keys.

Takes a map or keyword list, and returns a map with any atom keys converted to string keys. It can optionally do so recursively.

Converts a map to a struct (based on MIT licensed function by Kum Sackey)

If given a struct, returns a map representation of it

Takes a list of maps that have an id field and returns a list with only the unique maps. Uniqueness is determined based on the id field and not the full contents of the maps.

Unwraps tuples from a list of responses based on the specified key.

Functions

Link to this function

access_keys(keys, last_fallback \\ nil)

View Source

Checks if all tuples in the enumerable are :ok.

Examples

iex> Bonfire.Common.Enums.all_ok?([{:ok, 1}, {:ok, 2}])
true

iex> Bonfire.Common.Enums.all_ok?([{:ok, 1}, {:error, "failed"}])
false

Filters the given value or enumerable and if it contains any :error tuple, return an :error tuple with a list of error values, other return an :ok tuple with a list of values.

Examples

iex> Bonfire.Common.Enums.all_oks_or_error([{:ok, 1}, {:error, "failed"}])
{:error, ["failed"]}

iex> Bonfire.Common.Enums.all_oks_or_error([{:ok, 2}, {:ok, 3}])
{:ok, [2, 3]}

iex> Bonfire.Common.Enums.all_oks_or_error({:error, "failed"})
{:error, ["failed"]}

iex> Bonfire.Common.Enums.all_oks_or_error({:ok, 1})
{:ok, [1]}
Link to this function

attr_get_id(attrs, field_name)

View Source

Gets the value of a key in a map and returns the ID of that value (i.e. either the :id field of that association, or the value itself).

Link to this function

count_where(collection, function \\ &is_nil/1)

View Source

Counts the number of items in an enumerable that satisfy the given function.

Examples

iex> Bonfire.Common.Enums.count_where([1, 2, 3, 4, 5], fn x -> rem(x, 2) == 0 end)
2

iex> Bonfire.Common.Enums.count_where([:ok, :error, :ok], &(&1 == :ok))
2
Link to this function

deep_merge(left, right, opts \\ [])

View Source

Recursively merges two data structures (left and right), which can be structs, maps or lists. If left and right are Ecto.Changesets, merge_changesets/2 is called on them. If left is a struct, a similar struct is returned with the merged values. If left and right are lists, they are concatenated unless :replace_lists option is set to true.

Link to this function

deep_merge_reduce(list_or_map, opts \\ [])

View Source

Deep merges a list of maps into a single map.

Link to this function

enum_get(map, key, fallback \\ nil)

View Source

Attempt getting a value out of a map by atom key, or try with string key, or return a fallback

Link to this function

filter_empty(val, fallback)

View Source

Takes a value and a fallback value. If the value is empty (e.g. an empty map, a non-loaded association, an empty list, an empty string, or nil), the fallback value is returned.

Link to this function

filter_empty(enum, fallback, key)

View Source

Takes a list and recursively flattens it by recursively flattening the head and tail of the list

Link to this function

fun(map, fun, args \\ [])

View Source

Applies a function from one of Elixir's Map, Keyword, or List modules depending on the type of the given enumerable.

Examples

> Bonfire.Common.Enums.fun(%{a: 1, b: 2}, :values)
[2, 1]

iex> Bonfire.Common.Enums.fun([a: 1, b: 2], :values)
[1, 2]

iex> Bonfire.Common.Enums.fun([1, 2, 3], :first)
1
Link to this function

get_in_access_keys(map, keys, last_fallback)

View Source
Link to this function

get_in_access_keys!(map, keys, last_fallback)

View Source

Like Enum.group_by/3, except children are required to be unique (will throw otherwise!) and the resulting map does not wrap each item in a list.

Examples

iex> Bonfire.Common.Enums.group([1, 2, 3], fn x -> x end)
%{1 => 1, 2 => 2, 3 => 3}

> Bonfire.Common.Enums.group([:a, :b, :b, :c], fn x -> x end)
** (throw) "Expected a unique value"

Groups an enumerable by a function that returns key-value pairs, ensuring that keys are unique.

Examples

iex> Bonfire.Common.Enums.group_map([:a, :b, :c], fn x -> {x, to_string(x)} end)
%{a: "a", b: "b", c: "c"}

> Bonfire.Common.Enums.group_map([1, 2, 2, 3], fn x -> {x, x * 2} end)
** (throw) "Expected a unique value"
Link to this function

has_duplicates?(list, fun \\ nil)

View Source

Checks if the given list contains any duplicates. Takes an optional function that can be used to extract and/or compute the value to compare for each element in the list.

Checks if there are any :error tuples in the enumerable.

Examples

iex> Bonfire.Common.Enums.has_error?([{:ok, 1}, {:error, "failed"}])
true

iex> Bonfire.Common.Enums.has_error?([{:ok, 1}])
false

Checks if there are any :ok tuples in the enumerable.

Examples

iex> Bonfire.Common.Enums.has_ok?([{:ok, 1}, {:error, "failed"}])
true

iex> Bonfire.Common.Enums.has_ok?([{:error, "failed"}])
false
Link to this function

has_tuple_key?(enum, key)

View Source

Checks if there are any tuples with the given key in the enumerable.

Examples

iex> Bonfire.Common.Enums.has_tuple_key?([{:ok, 1}, {:error, "failed"}], :ok)
true

iex> Bonfire.Common.Enums.has_tuple_key?([{:ok, 1}], :error)
false

Extracts a binary ID from various data structures, such as a map containing the key :id or "id", a changeset, or a tuple containing the atom :id.

Extracts the IDs from a list of maps, changesets, or other data structures and returns a list of these IDs.

  iex> ids([%{id: 1, name: "Alice"}, %{id: 2, name: "Bob"}])
  [1, 2]

  iex> ids(%{id: 3})
  [3]
Link to this function

input_to_atoms(data, opts \\ [])

View Source

Takes a data structure and converts any keys in maps to (previously defined) atoms, recursively. By default any unknown string keys will be discarded. It can optionally also convert string values to known atoms as well.

Link to this function

input_to_value(v, _, including_values, _, force, arg6, values_to_integers)

View Source

Converts input to value based on the provided options.

Examples

iex> input_to_value("42", false, true, nil, true, nil, true)
42

iex> input_to_value("Bonfire.Common", false, true, nil, true, nil, false)
Bonfire.Common

iex> input_to_value("bonfire_common", false, true, nil, true, nil, false)
:bonfire_common

iex> input_to_value("unknown_example_string", false, true, nil, true, nil, false)
"unknown_example_string"

Recursively filters nil values from a map

Link to this function

map_key_replace(map, key, new_key, new_value \\ nil)

View Source

Renames a key in a map. Optionally changes the value as well.

Link to this function

map_key_replace_existing(map, key, new_key, new_value \\ nil)

View Source

Renames a key in a map, only if the key exists in the map. Optionally changes the value as well.

Link to this function

map_new(data, fallback_key \\ :data)

View Source

Takes an enumerable object and converts it to a map. If it is not an enumerable, a map is created with the data under a fallback key (:data by default).

Link to this function

map_put_default(map, key, default)

View Source

Checks a map for a value with provided key. If it already exists, the existing value is retained, but if not set or nil, then it is set to the provided default.

Link to this function

map_put_in(root \\ %{}, keys, value)

View Source

Updates a nested map using a list of keys and a value to set. It returns a new map with the updated value at the specified location.

Examples

iex> map_put_in(%{}, [:a, :b, :c], 3)
%{a: %{b: %{c: 3}}}

Parameters

  • root - The initial map (can be an empty map or a populated one).
  • keys - A list of keys specifying the path to the value.
  • value - The value to set at the specified location.
Link to this function

maybe_append(list, value)

View Source
@spec maybe_append([any()], any()) :: [any()]

Appends a value to a list, but only if the value is not nil or an empty list.

Link to this function

maybe_elem(tuple, index, fallback \\ nil)

View Source

Takes any element, an index and a fallback value. If the element is a Tuple it returns either the tuple value at that index, otherwise it returns the fallback. If the tuple doesn't contain such an index, it raises ArgumentError.

Flattens the list if provided a list, otherwise just return the input

Link to this function

maybe_get(map, key, fallback \\ nil)

View Source

Attempts to retrieve a value from a map by its key, and otherwise returns the provided fallback value.

Link to this function

maybe_list(val, change_fn)

View Source
Link to this function

maybe_merge_to_struct(first, precedence)

View Source
Link to this function

maybe_put(map, key, value)

View Source

Updates a map with the given key and value, but only if the value is not nil, an empty list or an empty string.

Link to this function

maybe_to_keyword_list(obj, recursive \\ false, force_top_level \\ true)

View Source

Returns a keyword list representation of the input object. If the second argument is true, the function will recursively convert nested data structures to keyword lists as well. Note: make sure that all keys are atoms, i.e. using input_to_atoms first, otherwise the enumerable(s) containing a string key won't be converted.

Link to this function

maybe_to_map(obj, recursive \\ false)

View Source

Returns a map representation of the input object. If the second argument is true, the function will recursively convert nested data structures to maps as well.

Link to this function

maybe_to_struct(obj, type \\ nil)

View Source

Takes a data structure and tries to convert it to a struct, using some hints in the data (eg. __type or index_type fields) or a manually-provided type.

Link to this function

maybe_to_structs(v, opts \\ [])

View Source

Takes a data structure and recursively converts any known keys to atoms and then tries to recursively convert any maps to structs, using some hints in the data (eg. __type or index_type fields).

Link to this function

merge_as_map(left, right, opts \\ [])

View Source

Merges two maps or lists into a single map

Link to this function

merge_changesets(cs1, cs2)

View Source

Merges two Ecto changesets. If both changesets have a prepare field, the function concatenates the values of the prepare fields. Either way it also calls Ecto.Changeset.merge/2 operation.

Link to this function

merge_keeping_only_first_keys(map_1, map_2)

View Source

Merges two maps while keeping only the keys that exist in the first map.

Link to this function

merge_structs_as_map(target, merge)

View Source
Link to this function

naughty_to_atoms!(data, opts \\ [])

View Source
Link to this function

nested_structs_to_maps(struct)

View Source

Recursively converts all nested structs to maps.

Link to this function

put_new_in(map, list, val)

View Source

This function is used to insert a new value into a nested map data structure, where the path to the location of the value is specified as a list of keys.

When the path is a single-element list, if the key already exists in the map, it returns the original map; otherwise, it inserts the key-value pair.

When the path is a list of more than one key, the first element of the list (key) represents the key for the current level of the nested map, and the remaining elements (path) represent the keys for the nested map at the next level. The function starts by retrieving the value at the current level of the map (if it exists) and updates the map with the new value.

Link to this function

stringify_keys(map, recursive \\ false)

View Source

Takes a map or keyword list, and returns a map with any atom keys converted to string keys. It can optionally do so recursively.

Link to this function

struct_from_map(a_map, list)

View Source

Converts a map to a struct (based on MIT licensed function by Kum Sackey)

Link to this function

struct_to_map(other, recursive \\ false)

View Source

If given a struct, returns a map representation of it

Takes a list of maps that have an id field and returns a list with only the unique maps. Uniqueness is determined based on the id field and not the full contents of the maps.

Link to this function

unwrap_tuples(enum, key)

View Source

Unwraps tuples from a list of responses based on the specified key.

Examples

iex> Bonfire.Common.Enums.unwrap_tuples([{:ok, 1}, {:error, "failed"}, {:ok, 2}], :ok)
[1, 2]

iex> Bonfire.Common.Enums.unwrap_tuples([{:ok, 1}, {:error, "failed"}], :error)
["failed"]