closed_intervals v0.3.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

This is the internal tree representation. It is not intended to be used publicly.

Create a new ClosedIntervals from points.

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.

Link to this section Types

Link to this type

t(data)

View Source
t(data) :: %ClosedIntervals{
  eq: (data, data -> boolean()),
  order: (data, data -> boolean()),
  tree: tree(data)
}
Link to this type

tree(data)

View Source
tree(data) ::
  {:closed_intervals, left :: nil | tree(data), right :: nil | tree(data),
   left_bound :: data, right_bound :: data, cut :: nil | data}

Link to this section Functions

Link to this macro

closed_intervals(args \\ [])

View Source (macro)

This is the internal tree representation. It is not intended to be used publicly.

Link to this macro

closed_intervals(record, args)

View Source (macro)
Link to this function

from(enum, args \\ [])

View Source
from(Enum.t(), Keyword.t()) :: t(term())

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 an 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 the ClosedIntervals
  • :eq: A custom equality defined on the points used to construct the ClosedIntervals
Link to this function

get_all_intervals(closed_intervals, value)

View Source
get_all_intervals(t(data), data) ::
  [{data, data}] | [{:"-inf", data}] | [{data, :"+inf"}]
when data: var

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.

Link to this function

get_interval(closed_intervals, value)

View Source
get_interval(t(data), data) ::
  {data, data} | {:"-inf", data} | {data, :"+inf"}
when data: var

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}
Link to this function

leaf_intervals(closed_intervals)

View Source
leaf_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".

Example

iex> from([1, 2, 3]) |> leaf_intervals()
[{1, 2}, {2, 3}]
Link to this function

left_bound(closed_intervals)

View Source

Retrieve the left bound of a ClosedIntervals.

Example

iex> [1, 2, 3] |> from() |> left_bound()
1
Link to this function

map(closed_intervals, mapper)

View Source
map(t(data), (data -> data)) :: t(data) when data: var

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]
Link to this function

right_bound(closed_intervals)

View Source

Retrieve the right bound of a ClosedIntervals.

Example

iex> [1, 2, 3] |> from() |> right_bound()
3
Link to this function

to_list(closed_intervals)

View Source
to_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]
iex> closed_intervals == closed_intervals |> to_list() |> from()
true