### 12.87 `util.temporal-relation` - Temporal relation

Module: util.temporal-relation

Procedures to find relation between two temporal intervals, or a temporal interval and a point in time.

A temporal interval is represented by two points in time, lesser bound and greater bound. This module does not define a concrete structure for temporal intervals. Instead, the user provides a interval protocol, which specifies how to access start/end time and how to compare them.

Given two temporal intervals x and y, there are 13 possible relations (the terms are taken from Haskell Rampart library https://hackage.haskell.org/package/rampart-2.0.0.0/docs/Rampart.html):

```|<-- x -->|
|<-- y -->|             x before y

|<-- x -->|
|<-- y -->|                x meets y

|<--- x ---->|
|<-- y -->|                 x overlaps y

|<------ x ------->|
|<-- y -->|                 x finished-by y

|<------- x -------->|
|<---- y ---->|                  x contains y

|<-- x -->|
|<------ y ---->|                 x starts y

|<---- x ---->|
|<---- y ---->|                    x equal y

|<----- x ----->|
|<-- y -->|                        x started-by y

|<---- x ---->|
|<--------y -------->|               x during y

|<-- x -->|
|<------ y ------->|                 x finishes y

|<-- x -->|
|<----- y ---->|                     x overlapped-by y

|<-- x -->|
|<-- y -->|                          x met-by y

|<-- x -->|
|<-- y -->|                          x after y
```
Function: make-interval-protocol lesser greater :optional compare-points

{util.temporal-relation} Creates and returns an interval protocol. The lesser and greater arguments are procedures taking an user-defined interval object, and returns its lesser bound and greater bound, respectively. The compare-points argument is a procedure that takes two points of time, and must return either a negative real value (if the first point is before the second), zero (if two points are the same), or a positive real value (if the first point is after the second).

The actual representation of time points are up to the caller.

If the compare argument is omitted, the built-in `compare` procedure is used (see Comparison). It is suffice for most scalar values; e.g. you may use real numbers, `<time>`, or `<date>` objects.

Variable: pair-interval-protocol

{util.temporal-relation} Bound to `(amke-interval-protocol car cdr)`; that is, an interval represented by cons of lesser bound and greater bound.

Function: relation? obj

{util.temporal-relation} Returns `#t` iff obj is a symbol representing a temporal relation. Valid symbols are one of `before`, `meets`, `overlaps`, `finished-by`, `contains`, `starts`, `equal`, `started-by`, `during`, `finishes`, `overlapped-by`, `met-by` and `after`.

Function: inverse rel

{util.temporal-relation} The argument must be a symbol representing a temporal relation. This procedure returns its inverse relation; that is, `(relate _ x y)``(inverse (relate _ y x))`.

An error is thrown if rel is not a valid relation.

Function: relate proto x y

{util.temporal-relation} The proto argument is an interval protocol, and both x and y must be temporal intervals that is compatible to the protocol proto.

The procedure returns a temporal relation, represented as one of the following symbols: `before`, `meets`, `overlaps`, `finished-by`, `contains`, `starts`, `equal`, `started-by`, `during`, `finishes`, `overlapped-by`, `met-by` and `after`.

Function: relate-point proto x point

{util.temporal-relation} The proto argument is an interval protocol, and x must be a temporal interval that implements the protocol. The point is a point of time, comparable by the compare-points procedure of the protocol.

The possible relations are a subset of interval-interval relations:

```|<-- x -->|
p                 x before p

|<--- x --->|
p                    x finished-by p

|<--- x --->|
p                      x contains p

|<--- x --->|
p                           x started-by p

|<-- x -->|
p                             x after p
```