# View Source ExRoseTree.Util(ExRoseTree v0.1.3)

Various utility functions.

# Link to this section Summary

## Functions

A function that always returns true, regardless of what is passed to it.

Given a term and a list of potential functions to apply to the term, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

Given a term, a list of potential functions to apply to the term, and a list of arguments to apply to each function, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

Given a term, a list of potential functions to apply to the term, and a keyword list of options to apply to each function, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

A function that applies a predicate to a term. If the function application is true, returns the original term. If false, returns nil.

A function that always returns false, regardless of what is passed to it.

Similar to `Enum.split/2` but with specialized behavior. It is optimized to return the list of elements that come before the index in reverse order. This is ideal for the context-aware nature of Zippers. Also unlike `Enum.split/2`, if given an index that is greater than or equal to the total elements in the given list or if given a negative index, this function will not perform a split, and will return two empty lists.

Similar to `Enum.split/2`, `Enum.split_while/2`, and `Enum.split_with/2`, `split_when/2` instead takes a list of elements and a predicate to apply to each element. The first element that passes the predicate is where the list of elements will be split, with the target element as the head of the second list in the return value. Like with `split_at/2`, the first list of elements are returned in reverse order.

# result()

View Source
`@type result() :: {:ok, term()} | {:error, term()} | :error`

# result_fn()

View Source
`@type result_fn() :: (... -> result())`

# always(term)

View Source
`@spec always(term()) :: true`

A function that always returns true, regardless of what is passed to it.

## examples Examples

``````iex> ExRoseTree.Util.always(5)
true

iex> ExRoseTree.Util.always(false)
true``````

# first_of(term, funs)

View Source
`@spec first_of(term(), [result_fn()]) :: term() | nil`

Given a term and a list of potential functions to apply to the term, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

The list of functions should each be of type `ExRoseTree.Util.result_fn()`, in other words, they should return a `ExRoseTree.Util.result()` type.

## examples Examples

``````iex> funs = for n <- [4,3,2,1], do: &(if n == &1 do {:ok, n} else :error end)
...> ExRoseTree.Util.first_of(3, funs)
3

iex> funs = for n <- [4,3,2,1], do: &(if n == &1 do {:ok, n} else :error end)
...> ExRoseTree.Util.first_of(6, funs)
nil``````

# first_of_with_args(term, funs, args)

View Source
`@spec first_of_with_args(term(), [function()], [term()]) :: term() | nil`

Given a term, a list of potential functions to apply to the term, and a list of arguments to apply to each function, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

The list of functions should each be of type `ExRoseTree.Util.result_fn()`, in other words, they should return a `ExRoseTree.Util.result()` type.

## examples Examples

``````iex> fun = fn x, y, add_by, sub_by ->
...>   if x == y do {:ok, x + add_by - sub_by} else :error end
...> end
...> funs = for n <- [4,3,2,1], do: &fun.(n, &1, &2, &3)
...> ExRoseTree.Util.first_of_with_args(3, funs, [2, 1])
4``````

# first_of_with_opts(term, funs, opts)

View Source
```@spec first_of_with_opts(
term(),
[function()],
keyword()
) :: term() | nil```

Given a term, a list of potential functions to apply to the term, and a keyword list of options to apply to each function, will return with the result of the first one that succeeds when applied to the subject term. If no functions succeed, returns nil.

The list of functions should each be of type `ExRoseTree.Util.result_fn()`, in other words, they should return a `ExRoseTree.Util.result()` type.

## examples Examples

``````iex> fun = fn x, y, z ->
...>   mult_by = Keyword.get(z, :mult_by, 1)
...>   if x == y do {:ok, x * mult_by} else :error end
...> end
...> funs = for n <- [4,3,2,1], do: &fun.(n, &1, &2)
...> ExRoseTree.Util.first_of_with_opts(3, funs, [mult_by: 2])
6``````

# maybe(value, predicate)

View Source
`@spec maybe(term(), (term() -> boolean())) :: term() | nil`

A function that applies a predicate to a term. If the function application is true, returns the original term. If false, returns nil.

## examples Examples

``````iex> ExRoseTree.Util.maybe(5, &(&1 == 5))
5

iex> ExRoseTree.Util.maybe(5, &(&1 == 1))
nil``````

# never(term)

View Source
`@spec never(term()) :: false`

A function that always returns false, regardless of what is passed to it.

## examples Examples

``````iex> ExRoseTree.Util.never(5)
false

iex> ExRoseTree.Util.never(true)
false``````

# split_at(elements, index)

View Source
`@spec split_at(list(), non_neg_integer()) :: {[term()], [term()]}`

Similar to `Enum.split/2` but with specialized behavior. It is optimized to return the list of elements that come before the index in reverse order. This is ideal for the context-aware nature of Zippers. Also unlike `Enum.split/2`, if given an index that is greater than or equal to the total elements in the given list or if given a negative index, this function will not perform a split, and will return two empty lists.

## examples Examples

``````iex> ExRoseTree.Util.split_at([1,2,3,4,5], 2)
{[2, 1], [3, 4, 5]}

iex> ExRoseTree.Util.split_at([1,2,3,4,5], 10)
{[], []}``````
`@spec split_when(list(), predicate :: (term() -> boolean())) :: {[term()], [term()]}`
Similar to `Enum.split/2`, `Enum.split_while/2`, and `Enum.split_with/2`, `split_when/2` instead takes a list of elements and a predicate to apply to each element. The first element that passes the predicate is where the list of elements will be split, with the target element as the head of the second list in the return value. Like with `split_at/2`, the first list of elements are returned in reverse order.
``````iex> ExRoseTree.Util.split_when([1,2,3,4,5], fn x -> x == 3 end)