12.91 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-points 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 (make-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 (see relation? above for the valid symbols). This procedure returns its inverse relation; that is, (relate _ x y) ≡ (inverse (relate _ y x)), where _ is an interval protocol.

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