~3 years ago I needed a way to use Postgres’ tstzrange type from Ecto. I wanted a better way to interact with these types than fragment/1, and I also needed to perform small changes to the ranges in the application.

I created Interval to help me. It grew a bit generic, and I ended up building a library that could handle all of Postgres’ range types.

Lately I’ve needed to expand the functionality, and I took the opportunity to patch bugs, add docs, and expand the featureset a bit. I also figured I might as well write a blog post about it.

§What is an interval?

Interval is an Elixir library for working with range/intervals. Postgres uses the term “ranges” (e.g. numrange, daterange etc) but Elixir already has a Range concept, so to avoid confusion, I’ve used the other term for these: Intervals.

Intervals (or ranges) are sets of contiguous elements represented by the two endpoints of the set. It supports both discrete values (integers, Date) and continuous values (floats, DateTime).

The endpoint at either end can either be included or excluded from the interval. Included values are shown with square brackets, excluded values with parentheses. An interval of all integers between 1 and 20, including 1, excluding 20, can be written as [1,20).

An interval endpoint can be unbounded. In this case, it the endpoint includes all elements in it’s direction. We represent an unbounded endpoint by not writing anything in it’s place. [1, is the interval of all numbers from (and including) the integer 1.

An interval can be unbounded at both endpoints, which means the interval includes all elements of it’s type. , is the interval containing all elements.

Finally, an interval can be empty, which can be written as (1,1) (that is, the interval from 1 to 1, excluding 1). We use a special notation for empty intervals, fittingly empty.

These notation conventions reflect Postgres’ ranges when they are cast to strings.

§Notable Features

You should check out the docs if you are interested in using it, but here is a quick summary of what it provides.

§Builtins

Interval ships with support for the following value types

• integer
• float
• Date
• DateTime
• NaiveDateTime
• Decimal

It also contains a default implementation for the protocols

• Jason.Encoder
• String.Chars (to_string/1)

and comes with a parse/1 function to convert a formattet string (to_string/1) back into an interval.

E.g.

 1iex> alias Interval.DateTimeInterval
 2iex> my_interval = DateTimeInterval.new(~U[2023-01-01 00:00:00Z],
 3...>                                    ~U[2024-01-01 00:00:00Z], "[)")
 4iex> formattet = to_string(my_interval)
 5"[2023-01-01T00:00:00Z,2024-01-01T00:00:00Z)"
 6
 7iex> DateTimeInterval.parse(formattet)
 8{:ok,
 9 %Interval.DateTimeInterval{
10   left: {:inclusive, ~U[2023-01-01 00:00:00Z]},
11   right: {:exclusive, ~U[2024-01-01 00:00:00Z]}
12 }}

§Ecto Support

You can use the builtin intervals in your Ecto schemas:

1# ...
2schema "reservations" do
3  field :period, Interval.DateTimeInterval
4  # ...
5end
6# ...

The DateTimeInterval type specifically is backed by tstzrange, and implements Ecto.Type (like all the other builtins)

1iex> DateTimeInterval.type()
2:tstzrange

1iex> DateTimeInterval.cast("[2023-01-01T00:00:00Z,2024-01-01T00:00:00Z)")
2{:ok,
3 %Interval.DateTimeInterval{
4   left: {:inclusive, ~U[2023-01-01 00:00:00Z]},
5   right: {:exclusive, ~U[2024-01-01 00:00:00Z]}
6 }}

§Operations

Interval contains a few handfulls of operations to compare and mutate intervals.

 1iex> a = Interval.IntegerInterval.new(1, 3)
 2iex> b = Interval.IntegerInterval.new(2, 4)
 3# do they overlap?
 4iex> Interval.overlaps?(a, b)
 5true
 6# does a contain b?
 7iex> Interval.contains?(a, b)
 8false
 9# return the union of a and b (they must overlap or be adjacent):
10iex> Interval.union(a, b)
11%Interval.IntegerInterval{left: {:inclusive, 1}, right: {:exclusive, 4}}
12# return the intersection of a and b:
13iex> Interval.intersection(a, b)
14%Interval.IntegerInterval{left: {:inclusive, 2}, right: {:exclusive, 3}}

§Define your own

Interval ships with macros to help you define your own.

This is what Interval uses interally to define the built in types. Here is the full source code for the Interval.DateInterval module (with some typespecs removed for brevity)

 1defmodule Interval.DateInterval do
 2  use Interval, type: Date, discrete: true
 3
 4  if Interval.Support.EctoType.supported?() do
 5    use Interval.Support.EctoType, ecto_type: :daterange
 6  end
 7
 8  if Interval.Support.Jason.supported?() do
 9    use Interval.Support.Jason
10  end
11
12  # given any point value, return a normalized version of that point (or :error)
13  def point_normalize(a) when is_struct(a, Date), do: {:ok, a}
14  def point_normalize(_), do: :error
15
16  # compare two point values
17  defdelegate point_compare(a, b), to: Date, as: :compare
18
19  # step a point value `n` steps
20  def point_step(%Date{} = date, n) when is_integer(n), do: Date.add(date, n)
21
22  # format a point value
23  def point_format(point) do
24    Date.to_iso8601(point)
25  end
26
27  # parse a string into a point value
28  def point_parse(str) do
29    case Date.from_iso8601(str) do
30      {:ok, dt} -> {:ok, dt}
31      {:error, _} -> :error
32    end
33  end
34end

§Summary

Interval allows you to easily work with intervals.
There are other libraries that allows you to work with Postgres ranges, None of them (that I’ve found at least) implement functions to check and manipulate the ranges application-side.

Version 2 is at a point where I think it is fairly stable and is ready for use. It is currently being used in production.