Tempo.Allen (Tempo v2.1.1)

Allen's thirteen relations between two spans, their inverses and their composition, and the everyday predicates as sets of them.

A span is [from, to). The relation of two spans is read from four comparisons, start against start, end against end, the first's end against the second's start and the first's start against the second's end (relation/2); every pair of spans stands in exactly one relation. The composition table is derived from the classifier when this module compiles, so the two cannot disagree. The everyday predicates (before?/2, within?/2, ...) are the sets of relations Tempo.before?/2 and its companions answer by for two single spans.

Summary

Types

predicate()

relation()

span()

A span as two positions on one frame, {from, to}, half-open.

Functions

compose(first, second)

The composition of two relations: the relations a first span may stand in to a third, given its relation to a second and the second's to the third.

contains?(a, b)

Whether the first span contains the second, under Allen's own name.

during?(a, b)

Whether the first span during the second, under Allen's own name.

equals?(a, b)

Whether the first span equals the second, under Allen's own name.

finished_by?(a, b)

Whether the first span finished by the second, under Allen's own name.

finishes?(a, b)

Whether the first span finishes the second, under Allen's own name.

holds?(name, a, b)

Whether a predicate or a relation holds between two spans.

inverse(relation)

The inverse of a relation: the relation of the second span to the first.

meets?(a, b)

Whether the first span meets the second, under Allen's own name.

met_by?(a, b)

Whether the first span met by the second, under Allen's own name.

overlapped_by?(a, b)

Whether the first span overlapped by the second, under Allen's own name.

overlaps?(a, b)

Whether the first span overlaps the second, under Allen's own name.

preceded_by?(a, b)

Whether the first span preceded by the second, under Allen's own name.

precedes?(a, b)

Whether the first span precedes the second, under Allen's own name.

predicate(name)

The relations an everyday predicate stands for.

predicates()

The everyday predicates: :before, :after, :adjacent, :within, :contains, :disjoint, :overlaps and :equal.

relation(a, b)

The relation of one span to another, from four comparisons.

relations()

The thirteen relations, in Allen's order.

started_by?(a, b)

Whether the first span started by the second, under Allen's own name.

starts?(a, b)

Whether the first span starts the second, under Allen's own name.

Types

predicate()

@type predicate() ::
  :before
  | :after
  | :adjacent
  | :within
  | :contains
  | :disjoint
  | :overlaps
  | :equal

relation()

@type relation() ::
  :precedes
  | :meets
  | :overlaps
  | :finished_by
  | :contains
  | :starts
  | :equals
  | :started_by
  | :during
  | :finishes
  | :overlapped_by
  | :met_by
  | :preceded_by

span()

@type span() :: {integer(), integer()}

A span as two positions on one frame, {from, to}, half-open.

Functions

compose(first, second)

@spec compose(relation(), relation()) :: [relation(), ...]

The composition of two relations: the relations a first span may stand in to a third, given its relation to a second and the second's to the third.

Arguments

first is the relation/0 of the first span to the second.
second is the relation/0 of the second span to the third.

Returns

The relation/0 atoms the first span may stand in to the third, in Allen's order.

Examples

iex> Tempo.Allen.compose(:precedes, :precedes)
[:precedes]

iex> Tempo.Allen.compose(:equals, :during)
[:during]

iex> Tempo.Allen.compose(:overlaps, :overlaps)
[:precedes, :meets, :overlaps]

contains?(a, b)

@spec contains?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span contains the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :contains, and false when it is not.

Examples

iex> Tempo.Allen.contains?({1, 5}, {2, 3})
true

during?(a, b)

@spec during?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span during the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :during, and false when it is not.

Examples

iex> Tempo.Allen.during?({2, 3}, {1, 5})
true

equals?(a, b)

@spec equals?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span equals the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :equals, and false when it is not.

Examples

iex> Tempo.Allen.equals?({1, 3}, {1, 3})
true

finished_by?(a, b)

@spec finished_by?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span finished by the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :finished_by, and false when it is not.

Examples

iex> Tempo.Allen.finished_by?({1, 5}, {3, 5})
true

finishes?(a, b)

@spec finishes?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span finishes the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :finishes, and false when it is not.

Examples

iex> Tempo.Allen.finishes?({3, 5}, {1, 5})
true

holds?(name, a, b)

@spec holds?(predicate() | relation(), span() | Tempo.t(), span() | Tempo.t()) ::
  boolean()

Whether a predicate or a relation holds between two spans.

Arguments

name is a predicate/0 or a relation/0.
a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is one the name stands for, and false when it is not.

Examples

iex> Tempo.Allen.holds?(:before, {1, 3}, {3, 5})
true

iex> Tempo.Allen.holds?(:precedes, {1, 3}, {3, 5})
false

inverse(relation)

@spec inverse(relation()) :: relation()

The inverse of a relation: the relation of the second span to the first.

Arguments

relation is a relation/0.

Returns

The relation/0 the second span stands in to the first.

Examples

iex> Tempo.Allen.inverse(:precedes)
:preceded_by

iex> Tempo.Allen.inverse(:equals)
:equals

meets?(a, b)

@spec meets?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span meets the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :meets, and false when it is not.

Examples

iex> Tempo.Allen.meets?({1, 3}, {3, 5})
true

met_by?(a, b)

@spec met_by?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span met by the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :met_by, and false when it is not.

Examples

iex> Tempo.Allen.met_by?({3, 5}, {1, 3})
true

overlapped_by?(a, b)

@spec overlapped_by?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span overlapped by the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :overlapped_by, and false when it is not.

Examples

iex> Tempo.Allen.overlapped_by?({3, 6}, {1, 4})
true

overlaps?(a, b)

@spec overlaps?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span overlaps the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :overlaps, and false when it is not.

Examples

iex> Tempo.Allen.overlaps?({1, 4}, {3, 6})
true

preceded_by?(a, b)

@spec preceded_by?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span preceded by the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :preceded_by, and false when it is not.

Examples

iex> Tempo.Allen.preceded_by?({3, 4}, {1, 2})
true

precedes?(a, b)

@spec precedes?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span precedes the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :precedes, and false when it is not.

Examples

iex> Tempo.Allen.precedes?({1, 2}, {3, 4})
true

predicate(name)

@spec predicate(predicate() | relation()) :: [relation(), ...]

The relations an everyday predicate stands for.

Arguments

name is a predicate/0, or a relation/0, which stands for itself.

Returns

The relation/0 atoms the predicate holds for.

Examples

iex> Tempo.Allen.predicate(:within)
[:equals, :starts, :during, :finishes]

iex> Tempo.Allen.predicate(:meets)
[:meets]

predicates()

@spec predicates() :: [predicate(), ...]

The everyday predicates: :before, :after, :adjacent, :within, :contains, :disjoint, :overlaps and :equal.

Returns

A list of the predicate/0 atoms.

Examples

iex> :within in Tempo.Allen.predicates()
true

relation(a, b)

@spec relation(span() | Tempo.t(), span() | Tempo.t()) :: relation()

The relation of one span to another, from four comparisons.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0 of two positions on one frame.

Returns

One of the thirteen relation/0 atoms. For two expressions it is what Tempo.relation/2 answers, and the error that would return is raised; a value that is neither an expression nor a span raises a Tempo.ConversionError.

Examples

iex> Tempo.Allen.relation(~o"2026-01", ~o"2026-02")
:meets

iex> Tempo.Allen.relation({1, 3}, {3, 5})
:meets

iex> Tempo.Allen.relation({1, 5}, {2, 3})
:contains

iex> Tempo.Allen.relation({2, 3}, {1, 5})
:during

relations()

@spec relations() :: [relation(), ...]

The thirteen relations, in Allen's order.

Returns

A list of the thirteen relation/0 atoms.

Examples

iex> length(Tempo.Allen.relations())
13

iex> hd(Tempo.Allen.relations())
:precedes

started_by?(a, b)

@spec started_by?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span started by the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :started_by, and false when it is not.

Examples

iex> Tempo.Allen.started_by?({1, 5}, {1, 3})
true

starts?(a, b)

@spec starts?(span() | Tempo.t(), span() | Tempo.t()) :: boolean()

Whether the first span starts the second, under Allen's own name.

Arguments

a and b are each a Tempo.t/0 that names one span, or each a span/0, as for relation/2.

Returns

true when the relation of a to b is :starts, and false when it is not.

Examples

iex> Tempo.Allen.starts?({1, 3}, {1, 5})
true