View Source Dx.Result (dx v0.3.0)
Result types and helpers to work with them.
A result is either:
{:error, e}
if an error occurred{:not_loaded, data_reqs}
if the result could not be determined without loading more data{:ok, boolean, binds}
otherwise, in contexts where a boolean is expected (typet:b()
){:ok, result, binds}
otherwise, whereresult
can be any value (typet:v()
)
data-loading
Data loading
In general, {:not_loaded, all_reqs}
only ever returns data requirements that are really needed.
example-using-all
Example using all
For example, using all?/1
with 3 conditions A, B and C, where
iex> [
...> {:ok, true, %{}}, # A
...> {:not_loaded, [1]}, # B
...> {:ok, false, %{}}, # C
...> ]
...> |> Dx.Result.all?()
{:ok, false, %{}}
The overall result is {:ok, false, %{}}
.
While B would need more data to be loaded, C can already determind and is false
,
so and any additional data loaded will not change that.
example-using-find
Example using find
Another example, using find/1
with 5 conditions A, B, C, D and E, where
iex> [
...> {:ok, false, %{}}, # A
...> {:not_loaded, [1]}, # B
...> {:not_loaded, [2]}, # C
...> {:ok, true, %{}}, # D
...> {:not_loaded, [3]}, # E
...> ]
...> |> Dx.Result.find()
{:not_loaded, [1, 2]}
The overall result is {:not_loaded, data_reqs1 + data_reqs2}
.
While D can already be determined and is {:ok, true, %{}}
, B and C come first and need more data
to be loaded, so they can be determined and returned if either is {:ok, true, %{}}
first.
All data requirements that might be needed are returned together in the result (those of B and C),
while those of E can be ruled out, as D already returns {:ok, true, %{}}
and comes first.
Link to this section Summary
Functions
Returns {:ok, true}
if fun
evaluates to {:ok, true}
for all elements in enum
.
Otherwise, returns {:not_loaded, data_reqs}
if any yield that.
Otherwise, returns {:ok, false}
.
Returns {:ok, true, binds}
if fun
evaluates to {:ok, true, binds}
for any element in enum
.
Otherwise, returns {:not_loaded, data_reqs}
if any yields that.
Otherwise, returns {:ok, false, %{}}
.
If ok, binds the result to the given key and returns the updated tuple. Otherwise, returns first argument as is.
Returns the number of elements for which fun
evaluates to {:ok, true}
.
If any elements return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
Returns the number of elements before fun
evaluates to {:ok, false}
or an element is nil
.
Elements are skipped (not counted) whenever fun
evaluates to {:ok, :skip}
.
If any elements before that return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
Returns {:ok, elem}
for the first elem
for which fun
evaluates to {:ok, true}
.
If any elements before that return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
Converts 2-tuples to the internal 3-tuple result format (type t:v()
or t:b()
).
Returns {:ok, mapped_results, binds}
if all elements map to {:ok, result, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
Returns {:ok, new_keyword_list, binds}
with new values if all values map to {:ok, new_value, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
Returns {:ok, new_map, binds}
with new values if all values map to {:ok, new_value, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
Wraps a value in an :ok
result.
When given {:ok, value, binds}
, runs fun
on value
and returns the result.
Otherwise, returns first argument as is.
Converts the internal 3-tuple result format (type t:v()
or t:b()
) to a 2-tuple format.
When given {:ok, value, binds}
, runs fun
on value
and returns {:ok, new_value, binds}
.
Otherwise, returns first argument as is.
When given {:ok, value, binds}
or {:ok, value}
, returns value
.
Otherwise, raises an exception.
Wraps a value in a compatible tuple for use with this module, if it's not wrapped already.
Link to this section Types
Possible return values from conditions.
Possible return values from resolving predicates.
Link to this section Functions
Returns {:ok, true}
if fun
evaluates to {:ok, true}
for all elements in enum
.
Otherwise, returns {:not_loaded, data_reqs}
if any yield that.
Otherwise, returns {:ok, false}
.
examples
Examples
iex> [
...> {:ok, true, %{}},
...> {:not_loaded, []},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.all?()
{:ok, false, %{}}
iex> [
...> {:ok, true, %{}},
...> {:not_loaded, []},
...> {:ok, true, %{}},
...> ]
...> |> Dx.Result.all?()
{:not_loaded, []}
iex> [
...> {:ok, true, %{}},
...> {:ok, true, %{}},
...> ]
...> |> Dx.Result.all?()
{:ok, true, %{}}
Returns {:ok, true, binds}
if fun
evaluates to {:ok, true, binds}
for any element in enum
.
Otherwise, returns {:not_loaded, data_reqs}
if any yields that.
Otherwise, returns {:ok, false, %{}}
.
examples
Examples
iex> [
...> {:ok, true, %{a: 1}},
...> {:not_loaded, []},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.any?()
{:ok, true, %{a: 1}}
iex> [
...> {:ok, false, %{}},
...> {:not_loaded, []},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.any?()
{:not_loaded, []}
iex> [
...> {:ok, false, %{}},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.any?()
{:ok, false, %{}}
If ok, binds the result to the given key and returns the updated tuple. Otherwise, returns first argument as is.
Returns the number of elements for which fun
evaluates to {:ok, true}
.
If any elements return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
examples
Examples
iex> [
...> {:ok, true, %{}},
...> {:ok, false, %{}},
...> {:ok, true, %{}},
...> ]
...> |> Dx.Result.count()
{:ok, 2, %{}}
iex> [
...> {:ok, false, %{}},
...> {:not_loaded, [1]},
...> {:not_loaded, [2]},
...> {:ok, true, %{}},
...> {:not_loaded, [3]},
...> ]
...> |> Dx.Result.count()
{:not_loaded, [1, 2, 3]}
iex> [
...> {:ok, true, %{}},
...> {:ok, :skip, %{}},
...> {:ok, false, %{}},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.count()
{:ok, 1, %{}}
iex> [
...> false,
...> false,
...> ]
...> |> Dx.Result.count(&{:ok, not &1, %{}})
{:ok, 2, %{}}
Returns the number of elements before fun
evaluates to {:ok, false}
or an element is nil
.
Elements are skipped (not counted) whenever fun
evaluates to {:ok, :skip}
.
If any elements before that return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
examples
Examples
iex> [
...> {:ok, true, %{}},
...> {:not_loaded, []},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.count_while()
{:not_loaded, []}
iex> [
...> {:ok, false, %{}},
...> {:not_loaded, [1]},
...> {:not_loaded, [2]},
...> {:ok, true, %{}},
...> {:not_loaded, [3]},
...> ]
...> |> Dx.Result.count_while()
{:ok, 0, %{}}
iex> [
...> {:ok, true, %{}},
...> {:ok, :skip, %{}},
...> {:ok, false, %{}},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.count_while()
{:ok, 1, %{}}
iex> [
...> false,
...> false,
...> ]
...> |> Dx.Result.count_while(&{:ok, not &1, %{}})
{:ok, 2, %{}}
find(enum, fun \\ &identity/1, result_mapper \\ &ok/2, default \\ ok(nil))
View SourceReturns {:ok, elem}
for the first elem
for which fun
evaluates to {:ok, true}
.
If any elements before that return {:not_loaded, data_reqs}
, returns all of them combined as {:not_loaded, ...}
.
Otherwise, returns {:ok, default}
.
examples
Examples
iex> [
...> {:ok, true, %{}},
...> {:not_loaded, []},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.find()
{:ok, {:ok, true, %{}}, %{}}
iex> [
...> {:ok, false, %{}},
...> {:not_loaded, [1]},
...> {:not_loaded, [2]},
...> {:ok, true, %{}},
...> {:not_loaded, [3]},
...> ]
...> |> Dx.Result.find()
{:not_loaded, [1, 2]}
iex> [
...> {:ok, false, %{}},
...> {:ok, false, %{}},
...> ]
...> |> Dx.Result.find()
{:ok, nil, %{}}
iex> [
...> false,
...> false,
...> ]
...> |> Dx.Result.find(&{:ok, not &1, %{}})
{:ok, false, %{}}
Converts 2-tuples to the internal 3-tuple result format (type t:v()
or t:b()
).
examples
Examples
iex> {:ok, 5}
...> |>Dx.Result.from_simple()
{:ok, 5, %{}}
iex> {:error, :err}
...> |>Dx.Result.from_simple()
{:error, :err}
Returns {:ok, mapped_results, binds}
if all elements map to {:ok, result, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
examples
Examples
iex> [
...> {:ok, 1, %{}},
...> {:ok, 2, %{}},
...> {:ok, 3, %{}},
...> ]
...> |> Dx.Result.map()
{:ok, [1, 2, 3], %{}}
iex> [
...> {:ok, 1, %{}},
...> {:not_loaded, [:x]},
...> {:ok, 3, %{}},
...> {:not_loaded, [:y]},
...> ]
...> |> Dx.Result.map()
{:not_loaded, [:x, :y]}
iex> [
...> {:ok, 1, %{}},
...> {:error, :x},
...> {:ok, 3, %{}},
...> {:not_loaded, [:y]},
...> ]
...> |> Dx.Result.map()
{:error, :x}
Returns {:ok, new_keyword_list, binds}
with new values if all values map to {:ok, new_value, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
examples
Examples
iex> [
...> a: {:ok, 1, %{}},
...> b: {:ok, 2, %{}},
...> c: {:ok, 3, %{}},
...> ]
...> |> Dx.Result.map_keyword_values()
{:ok, [a: 1, b: 2, c: 3], %{}}
iex> [
...> a: {:ok, 1, %{}},
...> b: {:not_loaded, MapSet.new([:x])},
...> c: {:ok, 3, %{}},
...> d: {:not_loaded, MapSet.new([:y])},
...> ]
...> |> Dx.Result.map_keyword_values()
{:not_loaded, MapSet.new([:x, :y])}
iex> [
...> a: {:ok, 1, %{}},
...> b: {:error, :x},
...> c: {:ok, 3, %{}},
...> d: {:not_loaded, [:y]},
...> ]
...> |> Dx.Result.map_keyword_values()
{:error, :x}
Returns {:ok, new_map, binds}
with new values if all values map to {:ok, new_value, binds}
.
Otherwise, returns {:error, e}
on error, or {:not_loaded, data_reqs}
with all data requirements.
examples
Examples
iex> %{
...> a: {:ok, 1, %{}},
...> b: {:ok, 2, %{}},
...> c: {:ok, 3, %{}},
...> }
...> |> Dx.Result.map_values()
{:ok, %{a: 1, b: 2, c: 3}, %{}}
iex> %{
...> a: {:ok, 1, %{}},
...> b: {:not_loaded, MapSet.new([:x])},
...> c: {:ok, 3, %{}},
...> d: {:not_loaded, MapSet.new([:y])},
...> }
...> |> Dx.Result.map_values()
{:not_loaded, MapSet.new([:x, :y])}
iex> %{
...> a: {:ok, 1, %{}},
...> b: {:error, :x},
...> c: {:ok, 3, %{}},
...> d: {:not_loaded, [:y]},
...> }
...> |> Dx.Result.map_values()
{:error, :x}
Wraps a value in an :ok
result.
When given {:ok, value, binds}
, runs fun
on value
and returns the result.
Otherwise, returns first argument as is.
Converts the internal 3-tuple result format (type t:v()
or t:b()
) to a 2-tuple format.
examples
Examples
iex> {:ok, 5, %{}}
...> |>Dx.Result.to_simple()
{:ok, 5}
iex> {:error, :err}
...> |>Dx.Result.to_simple()
{:error, :err}
When given {:ok, value, binds}
, runs fun
on value
and returns {:ok, new_value, binds}
.
Otherwise, returns first argument as is.
When given {:ok, value, binds}
or {:ok, value}
, returns value
.
Otherwise, raises an exception.
Wraps a value in a compatible tuple for use with this module, if it's not wrapped already.