closed_intervals v0.5.0 ClosedIntervals View Source
A ClosedIntervals datastructure.
ClosedIntervals
represents a set of closed intervals and provides functions to
retrieve the interval to which a given value belongs to. ClosedIntervals
can
handle arbitrary data, as long as it can be ordered in a sensible way. Users
can either use the default term order &<=/2
if that suits their needs, or
provide an explicit order function.
Link to this section Summary
Functions
Create a new ClosedIntervals
from points.
Reconstruct a ClosedInterval
from the output of leaf_intervals/1
.
Retrieve all intervals which cover value
.
Get the interval to which a value belongs to.
Retrieve a list of all leaf intervals.
Retrieve the left bound of a ClosedIntervals
.
Map a function over all intervals.
Retrieve the right bound of a ClosedIntervals
.
Serialize ClosedIntervals
into a list.
Link to this section Types
interval(data)
View Sourceinterval(data) :: {data, data} | {:"-inf", data} | {data, :"+inf"}
t(data)
View Sourcet(data) :: %ClosedIntervals{ eq: (data, data -> boolean()) | nil, order: (data, data -> boolean()), tree: ClosedIntervals.Tree.t(data) }
Link to this section Functions
Create a new ClosedIntervals
from points.
This function creates a new ClosedIntervals
from an Enum
of points. The points
can be of any form, as long as they can be ordered sensibly. For types where the
term order does not order them in a way such that the resulting order represents
a linear ordering along the interval range, a custom order can be applied using the
order
parameter. order
defaults to &<=/2
. Note that a custom order should return
true for equal points, if the resulting order has to be stable.
Additionally, an explicit equality function can be provided which is used in
ClosedIntervals.get_interval/2
and ClosedIntervals.get_all_intervals/2
.
Errors
The function expects that the enum
contains at least two points. If that is not the case,
an ArgumentError
is raised.
iex> from([1])
** (ArgumentError) Need at least two points to construct a ClosedIntervals
Examples
from/1,2
can handle plain types:
iex> from([1, 2, 3]) |> leaf_intervals()
[{1, 2}, {2, 3}]
It can also handle nested types, if a suitable order
is defined:
iex> points = [%{idx: 3}, %{idx: 7}, %{idx: 1}]
iex> points |> from(order: &(&1.idx <= &2.idx)) |> leaf_intervals()
[{%{idx: 1}, %{idx: 3}}, {%{idx: 3}, %{idx: 7}}]
Arguments
:order
: A custom order defined on the points used to construct theClosedIntervals
:eq
: A custom equality defined on the points used to construct theClosedIntervals
Reconstruct a ClosedInterval
from the output of leaf_intervals/1
.
Note that the args
must match the arguments used when originally constructing the
ClosedInterval
with from/1,2
.
Errors
If the least of leaf intervals is not the result of leaf_intervals/1
, this can result
in an ArgumentError
.
Example
iex> closed_intervals = from([1, 2, 3])
iex> leaf_intervals = leaf_intervals(closed_intervals)
iex> from_leaf_intervals(leaf_intervals)
iex> closed_intervals == from_leaf_intervals(leaf_intervals)
true
Retrieve all intervals which cover value
.
This function is useful if the index points used to define the ClosedIntervals
are not
unique. For example, when defining a step-function, it might make sense to use the same
point multiple times but with different data in order to represent a sharp step. Values
which are placed right at the interval bounds can then belong to multiple closed intervals.
Get the interval to which a value belongs to.
Example
iex> closed_intervals = from([1, 2, 5])
iex> get_interval(closed_intervals, 3)
{2, 5}
leaf_intervals(closed_intervals)
View Sourceleaf_intervals(t(data)) :: [{data, data}] when data: var
Retrieve a list of all leaf intervals.
A leaf interval is an interval which has been constructed from two adjacent
points. It does not expand to :"-inf"
or :"+inf"
.
See from_leaf_intervals/1,2
. We can reconstruct the original ClosedInterval
from a list of leaf intervals.
Example
iex> from([1, 2, 3]) |> leaf_intervals()
[{1, 2}, {2, 3}]
Retrieve the left bound of a ClosedIntervals
.
Example
iex> [1, 2, 3] |> from() |> left_bound()
1
Map a function over all intervals.
Example
iex> closed_intervals = from([1, 2, 3])
iex> map(closed_intervals, & &1 + 1) |> to_list()
[2, 3, 4]
Retrieve the right bound of a ClosedIntervals
.
Example
iex> [1, 2, 3] |> from() |> right_bound()
3
to_list(closed_intervals)
View Sourceto_list(t(data)) :: [data] when data: var
Serialize ClosedIntervals
into a list.
Example
iex> closed_intervals = from([1, 2, 3])
iex> to_list(closed_intervals)
[1, 2, 3]
We can construct the original ClosedInterval
from a list
generated by to_list/1
:
iex> closed_intervals = from([1, 2, 3])
iex> to_list(closed_intervals)
iex> closed_intervals == closed_intervals |> to_list() |> from()
true