# Set and Span Types

MobilityDB provides set, span, and span set types for representing set of values another type, which is called the base type. Set types are akin to array types in PostgreSQL restricted to one dimension, but enforce the constraint that sets do not have duplicates. Span and span set types in MobilityDB correspond to the range and multirange types in PostgreSQL but have additional constraints. In particular, span types in MobilityDB are of fixed length and do not allow empty spans and infinite bounds. While span types provide similar functionality to range types, they enable increasing performance. In particular, the overhead of processing variable-length types is removed and, in addition, pointer arithmetics and binary search can be used.

The base types used for constructing set, span, and span set types are the types `integer`, `bigint`, `float`, `text`, `date`, and `timestamptz` (timestamp with time zone) provided by PostgreSQL, the types `geometry` and `geography` provided by PostGIS, and the type `npoint` (network point) provided by MobilityDB (see temporal_network_points). MobilityDB provides the following set and span types:

- `set`: `intset`, `bigintset`, `floatset`, `textset`, `dateset`, `tstzset`, `geomset`, `geogset`, `npointset`.

- `span`: `intspan`, `bigintspan`, `floatspan`, `datespan`, `tstzspan`.

- `spanset`: `intspanset`, `bigintspanset`, `floatspanset`, `datespanset`, `tstzspanset`.

We present next the functions and operators for set and span types. These functions and operators are polymorphic, that is, their arguments may be of several types, and the result type may depend on the type of the arguments. To express this in the signature of the functions and operators, we use the following notation:

- `set` represents any set type, such as `intset` or `tstzset`.

- `span` represents any span type, such as `intspan` or `tstzspanset`.

- `spanset` represents any span set type, such as `intspanset` or `tstzspanset`.

- `spans` represents any span or span set type, such as `intspan` or `tstzspanset`.

- `base` represents any base type of a set or span type, such as `integer` or `timestamptz`

- `number` represents any base type of a number span type, such as `integer` or `float`,

- `numset` represents any number set type, such as `intset` or `floatset`.

- `numspans` represents any number span type, such as `intspan` or `floatspanset`.

- `numbers` represents any number set or range type, such as `integer`, `intset`, `intspan`, or `intspanset`,

- `dates` represents any time type with `date` granularity, that is, `date`, `dateset`, `datespan`, or `datespanset`,

- `times` represents any time type with `timestamptz` granularity, that is, `timestamptz`, `tstzset`, `tstzspan`, or `tstzspanset`,

- A set of types such as `{set,spans}` represents any of the types listed,

- A set of operators such as `{=, <>}` represents any of the operators listed,

- `type[]` represents an array of `type`.

As an example, the signature of the contains operator (`@>`) is as follows:

    {set,spans} @> {set,spans,base} → boolean

Notice that the signature above is an abridged version of the more precise signature below

    set @> {set,base} → boolean
    spans @> {spans,base} → boolean

since sets and spans cannot be mixed in operations and thus, for instance, we cannot ask wether a span contains a set. In the following, for conciseness, we use the abridged style of signatures above. Furthermore, the time part of the timestamps is omitted in most examples. Recall that in that case PostgreSQL assumes the time `00:00:00`.

In what follows, since span and span set types have similar functions and operators, when we speak about span types we mean both span and span set types, unless we explicitly refer to unit span types and span set types to distinguish them.

## Input and Output

MobilityDB generalizes Open Geospatial Consortium's (OGC) Well-Known Text (WKT) and Well-Known Binary (WKB) input and output format for all its types. In this way, applications can exchange data between them using a standardized exchange format. The WKT format is human-readable while the WKB format is more compact and more efficient than the WKT format. The WKB format can be output either as a binary string or as a character string encoded in hexadecimal ASCII.

The set types represent an ordered set of distinct values. A set must contain at least one element. Examples of set values are as follows:

    SELECT tstzset '{2001-01-01 08:00:00, 2001-01-03 09:30:00}';
    -- Singleton set
    SELECT textset '{"highway"}';
    -- Erroneous set: unordered elements
    SELECT floatset '{3.5, 1.2}';
    -- Erroneous set: duplicate elements
    SELECT geomset '{"Point(1 1)", "Point(1 1)"}';

Notice that the elements of the sets `textset`, `geomset`, `geogset`, and `npointset` must be enclosed between double quotes. Notice also that geometries and geographies follow the order defined in PostGIS.

A value of a unit span type has two bounds, the lower bound and the upper bound, which are values of the underlying base type. For example, a value of the `tstzspan` type has two bounds, which are `timestamptz` values. The bounds can be inclusive or exclusive. An inclusive bound means that the boundary instant is included in the span, while an exclusive bound means that the boundary instant is not included in the span. In the text form of a span value, inclusive and exclusive lower bounds are represented, respectively, by “`[`” and “`(`”. Likewise, inclusive and exclusive upper bounds are represented, respectively, by “`]`” and “`)`”. In a span value, the lower bound must be less than or equal to the upper bound. A span value with equal and inclusive bounds is called an instantaneous span and corresponds to a base type value. Examples of span values are as follows:

    SELECT intspan '[1, 3)';
    SELECT floatspan '[1.5, 3.5]';
    SELECT tstzspan '[2001-01-01 08:00:00, 2001-01-03 09:30:00)';
    -- Instant spans
    SELECT intspan '[1, 1]';
    SELECT floatspan '[1.5, 1.5]';
    SELECT tstzspan '[2001-01-01 08:00:00, 2001-01-01 08:00:00]';
    -- Erroneous span: invalid bounds
    SELECT tstzspan '[2001-01-01 08:10:00, 2001-01-01 08:00:00]';
    -- Erroneous span: empty span
    SELECT tstzspan '[2001-01-01 08:00:00, 2001-01-01 08:00:00)';

Values of `intspan`, `bigintspan`, and `datespan` are converted into normal form so that equivalent values have identical representations. In the canonical representation of these types, the lower bound is inclusive and the upper bound is exclusive as shown in the following examples:

    SELECT intspan '[1, 1]';
    -- [1, 2)
    SELECT bigintspan '(1, 3]';
    --[2, 4)
    SELECT datespan '[2001-01-01, 2001-01-03]';
    -- [2001-01-01, 2001-01-04)

A value of a span set type represents an ordered set of disjoint span values. A span set value must contain at least one element, in which case it corresponds to a single span value. Examples of span set values are as follows:

    SELECT floatspanset '{[8.1, 8.5],[9.2, 9.4]}';
    -- Singleton spanset
    SELECT tstzspanset '{[2001-01-01 08:00:00, 2001-01-01 08:10:00]}';
    -- Erroneous spanset: unordered elements
    SELECT intspanset '{[3,4],[1,2]}';
    -- Erroneous spanset: overlapping elements
    SELECT tstzspanset '{[2001-01-01 08:00:00, 2001-01-01 08:10:00],
      [2001-01-01 08:05:00, 2001-01-01 08:15:00]}';

Values of the span set types are converted into normal form so that equivalent values have identical representations. For this, consecutive adjacent span values are merged when possible. Examples of transformation into normal form are as follows:

    SELECT intspanset '{[1,2],[3,4]}';
    -- {[1, 5)}
    SELECT floatspanset '{[1.5,2.5],(2.5,4.5]}';
    -- {[1.5, 4.5]}
    SELECT tstzspanset '{[2001-01-01 08:00:00, 2001-01-01 08:10:00),
      [2001-01-01 08:10:00, 2001-01-01 08:10:00], (2001-01-01 08:10:00, 2001-01-01 08:20:00]}';
    -- {[2001-01-01 08:00:00+00,2001-01-01 08:20:00+00]}

We give next the functions for input and output of set and span types in Well-Known Text and Well-Known Binary format. The default output format of all set and span types is the Well-Known Text format. The function `asText` given next enables to determine the output of floating point values.

- Return the Well-Known Text (WKT) representation

  `asText({floatset,floatspans},maxdecdigits=15) → text`

  The `maxdecdigits` argument can be used to set the maximum number of decimal places in the output of floating point values (default 15).

      SELECT asText(floatset '{1.123456789,2.123456789}', 3);
      -- {1.123, 2.123}
      SELECT asText(floatspanset '{[1.55,2.55],[4,5]}',0);
      -- {[2, 3], [4, 5]}

- Return the Well-Known Binary (WKB) or the Hexadecimal Well-Known Binary (HexWKB) representation

  `asBinary({set,spans},endian text='') → bytea`

  `asHexWKB({set,spans},endian text='') → text`

  The result is encoded using either the little-endian (NDR) or the big-endian (XDR) encoding. If no encoding is specified, then the encoding of the machine is used.

      SELECT asBinary(dateset '{2001-01-01, 2001-01-03}');
      -- \x01050001020000006e01000070010000
      SELECT asBinary(intspan '[1, 3)');
      -- \x011300010100000003000000
      SELECT asBinary(floatspanset '{[1, 2], [4, 5]}', 'XDR');
      -- \x00000e00000002033ff000000000000040000000000000000340100000000000004014000000000000
      SELECT asHexWKB(dateset '{2001-01-01, 2001-01-03}');
      -- 01050001020000006E01000070010000
      SELECT asHexWKB(intspan '[1, 3)');
      -- 011300010100000003000000
      SELECT asHexWKB(floatspanset '{[1, 2], [4, 5]}', 'XDR');
      -- 00000E00000002033FF000000000000040000000000000000340100000000000004014000000000000

- Input from the Well-Known Binary (WKB) representation

  `settypeFromBinary(bytea) → set`

  `spantypeFromBinary(bytea) → span`

  `spansettypeFromBinary(bytea) → spanset`

  There is one function per set or span (set) type, the name of the function has as prefix the name of the type

      SELECT datesetFromBinary('\x01050001020000006e01000070010000');
      -- {2001-01-01, 2001-01-03}
      SELECT intspanFromBinary('\x011300010100000003000000');
      -- [1, 3)
      SELECT floatspansetFromBinary(
        '\x00000e00000002033ff000000000000040000000000000000340100000000000004014000000000000');
      -- {[1, 2], [4, 5]}

- Input from the Hexadecimal Well-Known Binary (HexWKB) representation

  `settypeFromHexWKB(text) → set`

  `spantypeFromHexWKB(text) → span`

  `spansettypeFromHexWKB(text) → spanset`

  There is one function per set or span (set) type, the name of the function has as prefix the name of the type.

      SELECT datesetFromHexWKB('01050001020000006E01000070010000');
      -- {2001-01-01, 2001-01-03}
      SELECT intspanFromHexWKB('011300010100000003000000');
      -- [1, 3)
      SELECT floatspanFromHexWKB('01060001000000000000F83F0000000000000440');
      -- [1.5, 2.5)
      SELECT floatspansetFromHexWKB(
        '00000E00000002033FF000000000000040000000000000000340100000000000004014000000000000');
      -- {[1, 2], [4, 5]}

## Constructors

The constructor function for the set types has a single argument that is an array of values of the corresponding base type. The values must be ordered and cannot have nulls or duplicates.

- Constructor for set types

  `set(base[]) → set`

      SELECT set(ARRAY['highway', 'primary', 'secondary']);
      -- {"highway", "primary", "secondary"}
      SELECT set(ARRAY[timestamptz '2001-01-01 08:00:00', '2001-01-03 09:30:00']);
      -- {2001-01-01 08:00:00+00, 2001-01-03 09:30:00+00}

The unit span types have a constructor function that accepts four arguments. The first two arguments specify, respectively, the lower and upper bound, and the last two arguments are Boolean values stating, respectively, whether the lower and upper bounds are inclusive or not. The last two arguments are assumed to be, respectively, true and false if not specified. Notice that integer spans are transformed into normal form, that is, with inclusive lower bound and exclusive upper bound.

- Constructor for span types

  `span(lower base,upper base,leftInc bool=true,rightInc bool=false) → span`

      SELECT span(20.5, 25);
      -- [20.5, 25)
      SELECT span(20, 25, false, true);
      -- [21, 26)
      SELECT span(timestamptz '2001-01-01 08:00:00', '2001-01-03 09:30:00', false, true);
      -- (2001-01-01 08:00:00, 2001-01-03 09:30:00]

The constructor function for span set types have a single argument that is an array of span values of the same subtype.

- Constructor for span set types

  `spanset(span[]) → spanset`

      SELECT spanset(ARRAY[intspan '[10,12]', '[13,15]']);
      -- {[10, 16)}
      SELECT spanset(ARRAY[floatspan '[10.5,12.5]', '[13.5,15.5]']);
      -- {[10.5, 12.5], [13.5, 15.5]}
      SELECT spanset(ARRAY[tstzspan '[2001-01-01 08:00, 2001-01-01 08:10]',
        '[2001-01-01 08:20, 2001-01-01 08:40]']);
      -- {[2001-01-01 08:00, 2001-01-01 08:10], [2001-01-01 08:20, 2001-01-01 08:40]};

## Conversions

Values of set and span types can be converted to one another or converted to and from PostgreSQL range types using the function `CAST` or using the `::` notation.

- Convert a base value to a set, span, or span set value

  `base::{set,span,spanset}`

  `set(base) → set`

  `span(base) → span`

  `spanset(base) → spanset`

      SELECT CAST(timestamptz '2001-01-01 08:00:00' AS tstzset);
      -- {2001-01-01 08:00:00}
      SELECT timestamptz '2001-01-01 08:00:00'::tstzspan;
      -- [2001-01-01 08:00:00, 2001-01-01 08:00:00]
      SELECT spanset(timestamptz '2001-01-01 08:00:00');
      -- {[2001-01-01 08:00:00, 2001-01-01 08:00:00]}

- Convert a set value to a span set value

  `set::spanset`

  `spanset(set) → spanset`

      SELECT spanset(tstzset '{2001-01-01 08:00:00, 2001-01-01 08:15:00,
        2001-01-01 08:25:00}');
      /* {[2001-01-01 08:00:00, 2001-01-01 08:00:00],
         [2001-01-01 08:15:00, 2001-01-01 08:15:00],
         [2001-01-01 08:25:00, 2001-01-01 08:25:00]} */

- Convert a span value to a span set value

  `span::spanset`

  `spanset(span) → spanset`

      SELECT floatspan '[1.5,2.5]'::floatspanset;
      -- {[1.5, 2.5]}
      SELECT tstzspan '[2001-01-01 08:00:00, 2001-01-01 08:30:00)'::tstzspanset;
      -- {[2001-01-01 08:00:00, 2001-01-01 08:30:00)}

- Convert a set or a span set into a span, ignoring the potential time gaps

  `{set,spanset}::span`

  `span({set,spanset}) → span`

      SELECT span(dateset '{2001-01-01, 2001-01-03, 2001-01-05}');
      -- [2001-01-01, 2001-01-06)
      SELECT span(tstzspanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}');
      -- [2001-01-01, 2001-01-04)

- Convert a span value to and from a PostgreSQL range value

  `span::range`

  `range::span`

  `range(span) → range`

  `span(range) → span`

  Notice that PostgreSQL range values accept empty ranges and ranges with infinite values, which are not allowed as span values in MobilityDB

      SELECT intspan '[10, 20)'::int4range;
      -- [10,20)
      SELECT tstzspan '[2001-01-01 08:00:00, 2001-01-01 08:30:00)'::tstzrange;
      -- ["2001-01-01 08:00:00","2001-01-01 08:30:00")
      SELECT int4range '[10, 20)'::intspan;
      -- [10,20)
      SELECT int4range 'empty'::intspan;
      -- ERROR:  Range cannot be empty
      SELECT int4range '[10,)'::intspan;
      -- ERROR:  Range bounds cannot be infinite
      SELECT tstzrange '[2001-01-01 08:00:00, 2001-01-01 08:30:00)'::tstzspan;
      -- [2001-01-01 08:00:00, 2001-01-01 08:30:00)

- Convert a span set value to and from a PostgreSQL multirange value

  `spanset::multirange`

  `multirange::spanset`

  `multirange(spanset) → multirange`

  `spanset(multirange) → spanset`

      SELECT intspanset '{[1,2],[4,5]}'::int4multirange;
      -- {[1,3),[4,6)}
      SELECT tstzspanset '{[2001-01-01,2001-01-02],[2001-01-04,2001-01-05]}'::tstzmultirange;
      -- {[2001-01-01,2001-01-02],[2001-01-04,2001-01-05]}
      SELECT int4multirange '{[1,2],[4,5]}'::intspanset;
      -- {[1, 3), [4, 6)}
      SELECT tstzmultirange '{[2001-01-01,2001-01-02],[2001-01-04,2001-01-05]}'::tstzspanset;
      -- {[2001-01-01, 2001-01-02], [2001-01-04, 2001-01-05]}

## Accessors

- Return the memory size in bytes

  `memSize({set,spanset}) → integer`

      SELECT memSize(tstzset '{2001-01-01, 2001-01-02, 2001-01-03}');
      -- 48
      SELECT memSize(tstzspanset '{[2001-01-01, 2001-01-02], [2001-01-03, 2001-01-04],
        [2001-01-05, 2001-01-06]}');
      -- 112

- Return the lower or upper bound

  `lower(spans) → base`

  `upper(spans) → base`

      SELECT lower(tstzspan '[2001-01-01, 2001-01-05)');
      -- 2001-01-01
      SELECT lower(intspanset '{[1,2],[4,5]}');
      --  1

      SELECT lower(tstzspan '[2001-01-01, 2001-01-05)');
      -- 2001-01-01
      SELECT upper(intspanset '{[1,2],[4,5]}');
      --  6
      SELECT lower(tstzspan '[2001-01-01, 2001-01-05)');
      -- 2001-01-01
      SELECT lower(intspanset '{[1,2],[4,5]}');
      --  1

      SELECT upper(floatspan '[20.5, 25.3)');
      -- 25.3
      SELECT upper(tstzspan '[2001-01-01, 2001-01-05)');
      -- 2001-01-05

- Is the lower or upper bound inclusive?

  `lowerInc(spans) → boolean`

  `upperInc(spans) → boolean`

      SELECT lowerInc(datespan '[2001-01-01, 2001-01-05)');
      -- true
      SELECT lowerInc(intspanset '{[1,2],[4,5]}');
      -- true

      SELECT upper(floatspan '[20.5, 25.3]');
      -- true
      SELECT upperInc(tstzspan '[2001-01-01, 2001-01-05)');
      -- false

- Return the width of the span as a float

  `width(numspan) → float`

  `width(numspanset,boundspan=false) → float`

  An additional parameter can be set to true to compute the width of the bounding span, thus ignoring the potential value gaps

      SELECT width(floatspan '[1, 3)');
      -- 2
      SELECT width(intspanset '{[1,3),[5,7)}');
      -- 4
      SELECT width(intspanset '{[1,3),[5,7)}', true);
      -- 6

- Return the duration

  `duration({datespan,tstzspan}) → interval`

  `duration({datespanset,tstzspanset},boundspan bool=false) → interval`

  An additional parameter can be set to true to compute the duration of the bounding time span, thus ignoring the potential time gaps

      SELECT duration(datespan '[2001-01-01, 2001-01-03)');
      -- 2 days
      SELECT duration(tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-05)}');
      -- 3 days
      SELECT duration(tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-05)}', true);
      -- 4 days

- Return the (number of) values

  `numValues(set) → integer`

  `getValues(set) → base[]`

      SELECT numValues(intset '{1,3,5,7}');
      -- 4
      SELECT getValues(tstzset '{2001-01-01, 2001-01-03, 2001-01-05, 2001-01-07}');
      -- {"2001-01-01","2001-01-03","2001-01-05","2001-01-07"}

- Return the start, end, or n-th value

  `startValue(set) → base`

  `endValue(set) → base`

  `valueN(set,integer) → base`

      SELECT startValue(intset '{1,3,5,7}');
      -- 1
      SELECT endValue(dateset '{2001-01-01, 2001-01-03, 2001-01-05, 2001-01-07}');
      -- 2001-01-07
      SELECT valueN(floatset '{1,3,5,7}',2);
      -- 3

- Return the (number of) spans

  `numSpans(spanset) → integer`

  `spans(spanset) → span[]`

      SELECT numSpans(intspanset '{[1,3),[4,5),[6,7)}');
      -- 3
      SELECT numSpans(datespanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-05),
        [2001-01-06, 2001-01-07)}');
      -- 3

      SELECT spans(floatspanset '{[1,3),[4,4],[6,7)}');
      -- {"[1,3)","[4,4]","[6,7)"}
      SELECT spans(tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-04],
        [2001-01-05, 2001-01-06)}');
      -- {"[2001-01-01,2001-01-03)", "[2001-01-04,2001-01-04]", "[2001-01-05,2001-01-06)"}

- Return the start, end, or n-th span

  `startSpan(spanset) → span`

  `endSpan(spanset) → span`

  `spanN(spanset,integer) → span`

      SELECT startSpan(intspanset '{[1,3),[4,5),[6,7)}');
      -- [1,3)
      SELECT startSpan(datespanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-05),
        [2001-01-06, 2001-01-07)}');
      -- [2001-01-01,2001-01-03)

      SELECT endSpan(floatspanset '{[1,3),[4,4],[6,7)}');
      -- [6,7)
      SELECT endSpan(tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-04],
        [2001-01-05, 2001-01-06)}');
      -- [2001-01-05,2001-01-06)

      SELECT spanN(floatspanset '{[1,3),[4,4],[6,7)}',2);
      -- [4,4]
      SELECT spanN(tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-04],
        [2001-01-05, 2001-01-06)}', 2);
      -- [2001-01-04,2001-01-04]

- Return the (number of) different dates

  `numDates(datespanset) → integer`

  `dates(datespanset) → dateset`

      SELECT numDates(datespanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}');
      -- 4
      SELECT dates(datespanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}');
      -- {2001-01-01, 2001-01-02, 2001-01-03, 2001-01-04}

- Return the start, end, or n-th date

  `startDate(datespanset) → date`

  `endDate(datespanset) → date`

  `dateN(datespanset,integer) → date`

  The functions do not take into account whether the bounds are inclusive or not.

      SELECT startDate(datespanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}');
      -- 2001-01-01
      SELECT endDate(datespanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}');
      -- 2001-01-05
      SELECT dateN(datespanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}', 3);
      -- 2001-01-05

- Return the (number of) different timestamps

  `numTimestamps(tstzspanset) → integer`

  `timestamps(tstzspanset) → tstzset`

      SELECT numTimestamps(tstzspanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}');
      -- 3
      SELECT timestamps(tstzspanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}');
      -- {"2001-01-01 00:00:00", "2001-01-03 00:00:00", "2001-01-05 00:00:00"}

- Return the start, end, or n-th timestamp

  `startTimestamp(tstzspanset) → timestamptz`

  `endTimestamp(tstzspanset) → timestamptz`

  `timestampN(tstzspanset,integer) → timestamptz`

  The functions do not take into account whether the bounds are inclusive or not.

      SELECT startTimestamp(tstzspanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}');
      -- 2001-01-01
      SELECT endTimestamp(tstzspanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}');
      -- 2001-01-05
      SELECT timestampN(tstzspanset '{[2001-01-01, 2001-01-03), (2001-01-03, 2001-01-05)}', 3);
      -- 2001-01-05

## Transformations

- Expand or shrink the bounds by a value or an interval

  `expand(numspan,base) → numspan`

  `expand(tstzspan,interval) → tstzspan`

  The function returns NULL if the value or interval given as second argument is negative and the span resulting from shifting the bounds with the argument is empty.

      SELECT expand(floatspan '[1, 3]', 1);
      -- [0, 4]
      SELECT expand(floatspan '[1, 3]', -1);
      -- [2, 2]
      SELECT expand(floatspan '[1, 3)', -1);
      -- NULL
      SELECT expand(tstzspan '[2001-01-01, 2001-01-03]', interval '1 day');
      -- [2000-12-31, 2001-01-04]
      SELECT expand(tstzspan '[2001-01-01, 2001-01-03]', interval '-1 day');
      -- [2001-01-02, 2001-01-02]
      SELECT expand(tstzspan '[2001-01-01, 2001-01-03]', interval '-2 day');
      -- NULL

- Shift by a value or interval

  `shift(numbers,base) → numbers`

  `shift(dates,integer) → dates`

  `shift(times,interval) → times`

      SELECT shift(dateset '{2001-01-01, 2001-01-03, 2001-01-05}', 1);
      -- {2001-01-02, 2001-01-04, 2001-01-06}
      SELECT shift(intspan '[1, 4)', -1);
      -- [0, 3)
      SELECT shift(tstzspan '[2001-01-01, 2001-01-03]', interval '1 day');
      -- [2001-01-02, 2001-01-04]
      SELECT shift(floatspanset '{[1, 2], [3, 4]}', -1);
      -- {[0, 1], [2, 3]}
      SELECT shift(tstzspanset '{[2001-01-01, 2001-01-03], [2001-01-04, 2001-01-05]}',
        interval '1 day');
      -- {[2001-01-02, 2001-01-04], [2001-01-05, 2001-01-06]}

- Scale by a value or interval

  `scale(numbers,base) → numbers`

  `scale(dates,integer) → dates`

  `scale(times,interval) → times`

  If the width or time span of the input value is zero (for example, for a singleton timestamp set), the result is the input value. The given value or interval must be strictly greater than zero.

      SELECT scale(tstzset '{2001-01-01}', '1 day');
      -- {2001-01-01}
      SELECT scale(tstzset '{2001-01-01, 2001-01-03, 2001-01-05}', '2 days');
      -- {2001-01-01, 2001-01-02, 2001-01-03}
      SELECT scale(intspan '[1, 4)', 4);
      -- [1, 6)
      SELECT scale(datespan '[2001-01-01, 2001-01-04)', 4);
      -- [2001-01-01, 2001-01-06)
      SELECT scale(tstzspan '[2001-01-01, 2001-01-03]', '1 day');
      -- [2001-01-01, 2001-01-02]
      SELECT scale(floatspanset '{[1, 2], [3, 4]}', 6);
      -- {[1, 3], [5, 7]}
      SELECT scale(tstzspanset '{[2001-01-01, 2001-01-03], [2001-01-04, 2001-01-05]}', '1 day');
      /* {[2001-01-01 00:00:00, 2001-01-01 12:00:00],
         [2001-01-01 18:00:00, 2001-01-02 00:00:00]} */
      SELECT scale(tstzset '{2001-01-01}', '-1 day');
      -- ERROR:  The duration must be a positive interval: -1 days

- Shift and scale by the values or intervals

  `shiftScale(numbers,base,base) → numbers`

  `shiftScale(dates,integer,integer) → dates`

  `shiftScale(times,interval,interval) → times`

  This function combines the functions `shift` and `scale`.

      SELECT shiftScale(tstzset '{2001-01-01}', '1 day', '1 day');
      -- {2001-01-02}
      SELECT shiftScale(tstzset '{2001-01-01, 2001-01-03, 2001-01-05}', '1 day','2 days');
      -- {2001-01-02, 2001-01-03, 2001-01-04}
      SELECT shiftScale(intspan '[1, 4)', -1, 4);
      -- [0, 5)
      SELECT shiftScale(datespan '[2001-01-01, 2001-01-04)', -1, 4);
      -- [2001-12-31, 2001-01-05)
      SELECT shiftScale(tstzspan '[2001-01-01, 2001-01-03]', '1 day', '1 day');
      -- [2001-01-02, 2001-01-03]
      SELECT shiftScale(floatspanset '{[1, 2], [3, 4]}', -1, 6);
      -- {[0, 2], [4, 6]}
      SELECT shiftScale(tstzspanset '{[2001-01-01, 2001-01-03], [2001-01-04, 2001-01-05]}',
        '1 day', '1 day');
      /* {[2001-01-02 00:00:00, 2001-01-02 12:00:00],
         [2001-01-02 18:00:00, 2001-01-03 00:00:00]} */

- Round down or up to the nearest integer

  `floor({floatset,floatspans}) → {floatset,floatspans}`

  `ceil({floatset,floatspans}) → {floatset,floatspans}`

      SELECT floor(floatset '{1.5,2.5}');
      -- {1, 2}
      SELECT ceil(floatspan '[1.5,2.5)');
      -- [2, 3)
      SELECT floor(floatspan '(1.5, 1.6)');
      -- [1, 1]
      SELECT ceil(floatspanset '{[1.5, 2.5],[3.5,4.5]}');
      -- {[2, 3], [4, 5]}

- Round to a number of decimal places

  `round({floatset,floatspans},integer=0) → {floatset,floatspans}`

      SELECT round(floatset '{1.123456789,2.123456789}', 3);
      -- {1.123, 2.123}
      SELECT round(floatspan '[1.123456789,2.123456789)', 3);
      -- [1.123,2.123)
      SELECT round(floatspan '[1.123456789, inf)', 3);
      -- [1.123,Infinity)
      SELECT round(floatspanset '{[1.123456789, 2.123456789],[3.123456789,4.123456789]}', 3);
      -- {[1.123, 2.123], [3.123, 4.123]}

- Convert to degrees or radians

  `degrees({floatset,floatspans}, normalize=false) → {floatset,floatspans}`

  `radians({floatset,floatspans}) → {floatset,floatspans}`

  The additional parameter in the `degrees` function can be used to normalize the values between 0 and 360 degrees.

      SELECT round(degrees(floatset '{0, 0.5, 0.7, 1.0}', true), 3);
      -- {0, 28.648, 40.107, 57.296}
      SELECT round(radians(floatspanset '{[0, 45], [90, 135]}'), 3);
      -- {[0, 0.785], [1.571, 2.356]}

- Transform to lowercase, uppercase, or initcap

  `lower(textset) → textset`

  `upper(textset) → textset`

  `initcap(textset) → textset`

      SELECT lower(textset '{"AAA", "BBB", "CCC"}');
      -- {"aaa", "bbb", "ccc"}
      SELECT upper(textset '{"aaa", "bbb", "ccc"}');
      -- {"AAA", "BBB", "CCC"}
      SELECT initcap(textset '{"aaa", "bbb", "ccc"}');
      -- {"Aaa", "Bbb", "Ccc"}

- Text concatenation

  `{text,textset} || {text,textset} → textset`

      SELECT textset '{aaa, bbb}' || text 'XX';
      -- {"aaaXX", "bbbXX"}
      SELECT text 'XX' || textset '{aaa, bbb}';
      -- {"XXaaa", "XXbbb"}

- Set the temporal precision of the time value to the interval with respect to the origin

  `tprecision(times,interval,origin timestamptz=’2000-01-03’) → times`

  If the origin is not specified, it is set by default to Monday, January 3, 2000

      SELECT tprecision(timestamptz '2001-12-03', '30 days');
      -- 2001-11-23
      SELECT tprecision(timestamptz '2001-12-03', '30 days', '2001-12-01');
      -- 2001-12-01
      SELECT tprecision(tstzset '{2001-01-01 08:00, 2001-01-01 08:10, 2001-01-01 09:00,
        2001-01-01 09:10}', '1 hour');
      -- {"2001-01-01 08:00:00+01", "2001-01-01 09:00:00+01"}
      SELECT tprecision(tstzspan '[2001-12-01 08:00, 2001-12-01 09:00]', '1 day');
      -- [2001-12-01, 2001-12-02)
      SELECT tprecision(tstzspan '[2001-12-01 08:00, 2001-12-15 09:00]', '1 day');
      -- [2001-12-01, 2001-12-16)
      SELECT tprecision(tstzspanset '{[2001-12-01 08:00, 2001-12-01 09:00],
        [2001-12-01 10:00, 2001-12-01 11:00]}', '1 day');
      -- {[2001-12-01, 2001-12-02)}
      SELECT tprecision(tstzspanset '{[2001-12-01 08:00, 2001-12-01 09:00],
        [2001-12-01 10:00, 2001-12-01 11:00]}', '1 day');
      -- {[2001-12-01, 2001-12-02)}

## Spatial Reference System

- Return or set the spatial reference identifier

  `SRID(spatialset) → integer`

  `setSRID(spatialset) → spatialset`

      SELECT SRID(geomset '{"Point(1 1)", "Point(2 2)"}');
      -- 0
      SELECT SRID(geogset '{"Linestring(1 1,2 2)","Polygon((1 1,1 2,2 2,2 1,1 1))"}');
      -- 4326
      SELECT SRID(geomset 'SRID=5676;{"Linestring(1 1,2 2)","Polygon((1 1,1 2,2 2,2 1,1 1))"}');
      -- 5676
      SELECT asEWKT(setSRID(geomset '{Point(1 1), Point(2 2)}', 5676));
      -- SRID=5676;{"POINT(1 1)", "POINT(2 2)"}
      SELECT asEWKT(setSRID(poseset '{"Pose(Point(1 1),1)", "Pose(Point(2 2),3)"}', 5676));
      -- SRID=5676;{"Pose(POINT(2 2),3)", "Pose(POINT(1 1),1)"}

- Transform to a spatial reference identifier

  `transform(spatialset,to_srid integer) → spatialset`

  `transformPipeline(spatialset,pipeline text,to_srid integer,is_forward bool=true) →`

  `spatialset`

  The `transform` function specifies the transformation with a target SRID. An error is raised when the input set has an unknown SRID (represented by 0). The `transformPipeline` function specifies the transformation with a coordinate transformation pipeline in the following format:

  `urn:ogc:def:coordinateOperation:AUTHORITY::CODE`

  The SRID of the input set is ignored, and the SRID of the output set will be set to zero unless a value is provided via the optional `to_srid` parameter. As stated by the last parameter, the pipeline is executed by default in a forward direction; by setting the parameter to false, the pipeline is executed in the inverse direction.

      SELECT asEWKT(transform(geomset 'SRID=4326;{Point(2.340088 49.400250),
        Point(6.575317 51.553167)}', 3812), 6);
      -- SRID=3812;{"POINT(502773.429981 511805.120402)", "POINT(803028.908265 751590.742629)"}
      WITH test(geoset, pipeline) AS (
        SELECT geogset 'SRID=4326;{"Point(4.3525 50.846667 100.0)",
          "Point(-0.1275 51.507222 100.0)"}',
          text 'urn:ogc:def:coordinateOperation:EPSG::16031' )
      SELECT asEWKT(transformPipeline(transformPipeline(geoset, pipeline, 4326), pipeline,
        4326, false), 6)
      FROM test;
      -- SRID=4326;{"POINT Z (4.3525 50.846667 100)", "POINT Z (-0.1275 51.507222 100)"}

## Set Operations

The set and span types have associated set operators, namely union, difference, and intersection, which are represented, respectively by `+`, `-`, and `*`. The set operators for the set and span types are given next.

- Union, difference, or intersection of sets or spans

  `set {+, -, *} set → set`

  `spans {+, -, *} spans → spans`

      SELECT dateset '{2001-01-01, 2001-01-03, 2001-01-05}' +
        dateset '{2001-01-03, 2001-01-06}';
      -- {2001-01-01, 2001-01-03, 2001-01-05, 2001-01-06}
      SELECT intspan '[1, 3)' + intspan '[3, 5)';
      -- [1, 5)
      SELECT floatspan '[1, 3)' + floatspan '[4, 5)';
      -- {[1, 3), [4, 5)}
      SELECT tstzspanset '{[2001-01-01, 2001-01-03), [2001-01-04, 2001-01-05)}' +
        tstzspan '[2001-01-03, 2001-01-04)';
      -- {[2001-01-01, 2001-01-05)}

      SELECT intset '{1, 3, 5}' - intset '{3, 6}';
      -- {1, 5}
      SELECT datespan '[2001-01-01, 2001-01-05)' - datespan '[2001-01-03, 2001-01-07)';
      -- {[2001-01-01, 2001-01-03)}
      SELECT floatspan '[1, 5]' - floatspan '[3, 4]';
      -- {[1, 3), (4, 5]}
      SELECT tstzspanset '{[2001-01-01, 2001-01-06], [2001-01-07, 2001-01-10]}' -
        tstzspanset '{[2001-01-02, 2001-01-03], [2001-01-04, 2001-01-05],
        [2001-01-08, 2001-01-09]}';
      /* {[2001-01-01,2001-01-02), (2001-01-03,2001-01-04), (2001-01-05,2001-01-06],
         [2001-01-07,2001-01-08), (2001-01-09,2001-01-10]} */

      SELECT tstzset '{2001-01-01, 2001-01-03}' * tstzset '{2001-01-03, 2001-01-05}';
      -- {2001-01-03}
      SELECT intspan '[1, 5)' * intspan '[3, 6)';
      -- [3, 5)
      SELECT floatspanset '{[1, 5),[6, 8)}' * floatspan '[1, 6)';
      -- {[1, 5)}
      SELECT tstzspan '[2001-01-01, 2001-01-05)' * tstzspan '[2001-01-03, 2001-01-07)';
      -- [2001-01-03, 2001-01-05)

## Bounding Box Operations

### Topological Operations

The topological operations available for the set and span types are given next.

- Do the values overlap (have values in common)?

  `{set,spans} && {set,spans} → boolean`

      SELECT intset '{1, 3}' && intset '{2, 3, 4}';
      -- true
      SELECT floatspan '[1, 3)' && floatspan '[3, 4)';
      -- false
      SELECT tstzspan '[2001-01-01, 2001-01-05)' && tstzspan '[2001-01-02, 2001-01-07)';
      -- true
      SELECT floatspanset '{[1, 5),[6, 8)}' && floatspan '[1, 6)';
      -- true

- Does the first value contain the second one?

  `{set,spans} @> {base,set,spans} → boolean`

      SELECT floatset '{1.5, 2.5}' @> 2.5;
      -- true
      SELECT tstzspan '[2001-01-01, 2001-05-01)' @> timestamptz '2001-02-01';
      -- true
      SELECT floatspanset '{[1, 2),(2, 3)}' @> 2.0;
      -- false

- Is the first value contained by the second one?

  `{base,set,spans} <@ {set,spans} → boolean`

      SELECT timestamptz '2001-01-10' <@ tstzspan '[2001-01-01, 2001-05-01)';
      -- true
      SELECT floatspan '[2, 5]' <@ floatspan '[1, 5)';
      -- false
      SELECT tstzspan '[2001-02-01, 2001-03-01)' <@ tstzspan '[2001-01-01, 2001-05-01)';
      -- true
      SELECT floatspanset '{[1,2],[3,4]}' <@ floatspan '[1, 6]';
      -- true

- Is the first value adjacent to the second one?

  `spans -|- spans → boolean`

      SELECT intspan '[2, 6)' -|- intspan '[6, 7)';
      -- true
      SELECT floatspan '[2, 5)' -|- floatspan '(5, 6)';
      -- false
      SELECT floatspanset '{[2, 3],[4, 5)}' -|- floatspan '(5, 6)';
      -- true
      SELECT tstzspanset '{[2001-01-01, 2001-01-02]}' -|- tstzspan '[2001-01-02, 2001-01-03)';
      -- false

### Position Operations

The position operations available for set and span types are given next. Notice that the operators for time types have an additional `#` to distinguish them from the operators for number types.

- Is the first value strictly left of the second one?

  `numbers << numbers → boolean`

  `times <<# times → boolean`

      SELECT intspan '[15, 20)' << 20;
      -- true
      SELECT intspanset '{[15, 17],[18, 20)}' << 20;
      -- true
      SELECT floatspan '[15, 20)' << floatspan '(15, 20)';
      -- false
      SELECT dateset '{2001-01-01, 2001-01-02}' <<# dateset '{2001-01-03, 2001-01-05}';
      -- true

- Is the first value strictly to the right of the second one?

  `numbers >> numbers → boolean`

  `times #>> times → boolean`

      SELECT intspan '[15, 20)' >> 10;
      -- true
      SELECT floatspan '[15, 20)' >> floatspan '[5, 10]';
      -- true
      SELECT floatspanset '{[15, 17], [18, 20)}' >> floatspan '[5, 10]';
      -- true
      SELECT tstzspan '[2001-01-04, 2001-01-05)' #>>
        tstzspanset '{[2001-01-01, 2001-01-04), [2001-01-05, 2001-01-06)}';
      -- true

- Is the first value not to the right of the second one?

  `numbers &< numbers → boolean`

  `times &<# times → boolean`

      SELECT intspan '[15, 20)' &< 18;
      -- false
      SELECT intspanset '{[15, 16],[17, 18)}' &< 18;
      -- true
      SELECT floatspan '[15, 20)' &< floatspan '[10, 20]';
      -- true
      SELECT dateset '{2001-01-02, 2001-01-05}' &<# dateset '{2001-01-01, 2001-01-04}';
      -- false

- Is the first value not to the left of the second one?

  `numbers &> numbers → boolean`

  `times #&> times → boolean`

      SELECT intspan '[15, 20)' &> 30;
      -- true
      SELECT floatspan '[1, 6]' &> floatspan '(1, 3)';
      -- false
      SELECT floatspanset '{[1, 2],[3, 4]}' &> floatspan '(1, 3)';
      -- false
      SELECT timestamp '2001-01-01' #&> tstzspan '[2001-01-01, 2001-01-05)';
      -- true

### Splitting Operations

When creating indexes for set or span set types, what is stored in the index is not the actual value but instead, a bounding box that represents the value. In this case, the index will provide a list of candidate values that may satisfy the query predicate, and a second step is needed to filter out candidate values by computing the query predicate on the actual values.

However, when the bounding boxes have a large empty space not covered by the actual values, the index will generate many candidate values that do not satisfy the query predicate, which reduces the efficiency of the index. In these situations, it may be better to represent a value not with a single bounding box, but instead with multiple bounding boxes. This increases considerably the efficiency of the index, provided that the index is able to manage multiple bounding boxes per value. The following functions are used for generating multiple spans from a single set or span set value.

- Return an array of N spans obtained by merging the elements of a set or the spans of a spanset

  `splitNSpans(set, integer) → span[]`

  `splitNSpans(spanset, integer) → span[]`

  The last argument specifies the number of output spans. If the number of input elements or spans is less than the given number, the resulting array will have one span per input element or span. Otherwise, the given number of output spans will be obtained by merging several consecutive input elements or spans.

      SELECT splitNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 1);
      /* {"[1, 11)"} */
      SELECT splitNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 3);
      -- {"[1, 5)","[5, 8)","[8, 11)"}
      SELECT splitNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 6);
      -- {"[1, 3)","[3, 5)","[5, 7)","[7, 9)","[9, 10)","[10, 11)"}
      SELECT splitNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 12);
      /* {"[1, 2)","[2, 3)","[3, 4)","[4, 5)","[5, 6)","[6, 7)","[7, 8)","[8, 9)",
          "[9, 10)","[10, 11)"} */

      SELECT splitNSpans(intspanset '{[1, 2), [3, 4), [5, 6), [7, 8), [9, 10)}');
      -- {"[1, 2)","[3, 4)","[5, 6)","[7, 8)","[9, 10)"}
      SELECT splitNSpans(floatspanset '{[1, 2), [3, 4), [5, 6), [7, 8), [9, 10)}', 3);
      -- {"[1, 4)","[5, 8)","[9, 10)"}
      SELECT splitNSpans(datespanset '{[2000-01-01, 2000-01-04), [2000-01-05, 2000-01-10)}', 3);
      -- {"[2000-01-01, 2000-01-04)","[2000-01-05, 2000-01-10)"}

- Return an array of spans obtained by merging N consecutive elements of a set or N consecutive spans of a spanset

  `splitEachNSpans(set, integer) → span[]`

  `splitEachNSpans(spanset, integer) → span[]`

  The last argument specifies the number of input elements that are merged to produce an output span. If the number of input elements is less than the given number, the resulting array will have one output span per element. Otherwise, the given number of consecutive input elements will be merged into a single output span in the answer. Notice that, contrary to the `splitNSpans` function, the number of spans in the result depends on the number of input elements or spans.

      SELECT splitEachNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 1);
      /* {"[1, 2)","[2, 3)","[3, 4)","[4, 5)","[5, 6)","[6, 7)","[7, 8)","[8, 9)",
          "[9, 10)","[10, 11)"} */
      SELECT splitEachNSpans(intspanset '{[1, 2), [3, 4), [5, 6), [7, 8), [9, 10)}', 3);
      -- {"[1, 6)","[7, 10)"}
      SELECT splitEachNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 6);
      -- {"[1, 7)","[7, 11)"}
      SELECT splitEachNSpans(intset '{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}', 12);
      -- {"[1, 11)"}

## Distance Operations

The distance operator `<->` for set and span types consider the bounding span and returns a the smallest distance between the two values. In the case of time values, the operator returns the number of days or the number of seconds between the two time values. The distance operator can also be used for nearest neighbor searches using a GiST or an SP-GiST index (see setspan_indexing).

- Return the smallest distance ever

  `numbers <-> numbers → base`

  `dates <-> dates → integer`

  `times <-> times → float`

      SELECT 3 <-> intspan '[6, 8)';
      -- 3
      SELECT floatspan '[1, 3]' <-> floatspan '(5.5, 7]';
      -- 2.5
      SELECT floatspan '[1, 3]' <-> floatspanset '{(5.5, 7],[8, 9]}';
      -- 2.5
      SELECT tstzspan '[2001-01-02, 2001-01-06)' <-> timestamptz '2001-01-07';
      -- 86400
      SELECT dateset '{2001-01-01, 2001-01-03, 2001-01-05}' <->
        dateset '{2001-01-02, 2001-01-04}';
      --  0

## Comparisons

The comparison operators (`=`, `<`, and so on) require that the left and right arguments be of the same type. Excepted equality and inequality, the other comparison operators are not useful in the real world but allow B-tree indexes to be constructed on set and span types. For span values, the operators compare first the lower bound, then the upper bound. For set and span set values, the operators compare first the bounding spans, and if those are equal, they compare the first N values or spans, where N is the minimum of the number of composing values or spans of both values.

The comparison operators available for the set and span types are given next. Recall that integer spans are always represented by their canonical form.

- Traditional comparisons

  `set {=, <>, <, >, <=, >=} set → boolean`

  `spans {=, <>, <, >, <=, >=} spans → boolean`

  `set_cmp(set,set) → int`

  `span_cmp(span,span) → int`

  `spanset_cmp(spanset,spanset) → int`

  Functions `set_cmp`, `span_cmp`, and `spanset_cmp` return -1, 0, or 1 depending on whether the first argument is, respectively, less than, equal to, or greater than the second one.

      SELECT intspan '[1,3]' = intspan '[1,4)';
      -- true
      SELECT floatspanset '{[1, 2),[2,3)}' = floatspanset '{[1,3)}';
      -- true
      SELECT tstzset '{2001-01-01, 2001-01-04}' <> tstzset '{2001-01-01, 2001-01-05}';
      -- false
      SELECT tstzspan '[2001-01-01, 2001-01-04)' <> tstzspan '[2001-01-03, 2001-01-05)';
      -- true
      SELECT floatspan '[3, 4]' < floatspan '(3, 4]';
      -- true
      SELECT intspanset '{[1,2],[3,4]}' < intspanset '{[3, 4]}';
      -- true
      SELECT floatspan '[3, 4]' > floatspan '[3, 4)';
      -- true
      SELECT tstzspan '[2001-01-03, 2001-01-04)' > tstzspan '[2001-01-02, 2001-01-05)';
      -- true
      SELECT floatspanset '{[1, 4)}' <= floatspanset '{[1, 5), [6, 7)}';
      -- true
      SELECT tstzspanset '{[2001-01-01, 2001-01-04)}' <=
        tstzspanset '{[2001-01-01, 2001-01-05), [2001-01-06, 2001-01-07)}';
      -- true
      SELECT tstzspan '[2001-01-03, 2001-01-05)' >= tstzspan '[2001-01-03, 2001-01-04)';
      -- true
      SELECT intspanset '{[1, 4)}' >= intspanset '{[1, 5), [6, 7)}';
      -- false
      SELECT spanset_cmp(intspanset '{[1, 4)}', intspanset '{[1, 5), [6, 7)}');
      -- -1

## Aggregations

There are several aggregate functions defined for set and span types. They are described next.

- Function `extent` returns a bounding span that encloses a set of set or span values.

- Union is a very useful operation for set and span types. As we have seen in setspan_set_ops, we can compute the union of two set or span values using the `+` operator. However, it is also very useful to have an aggregate version of the union operator for combining an arbitrary number of values. Functions `setUnion` and `spanUnion` can be used for this purpose.

- Function `tCount` generalizes the traditional aggregate function `count`. The temporal count can be used to compute at each point in time the number of available objects (for example, number of spans). Function `tCount` returns a temporal integer (see ttype_p1). The function has two optional parameters that specify the granularity (an `interval`) and the origin of time (a `timestamptz`). When these parameters are given, the temporal count is computed at time bins of the given granularity (see ttype_tiling).

- Bounding span

  `extent({set,spans}) → span`

      WITH spans(r) AS (
        SELECT floatspan '[1, 4)' UNION SELECT floatspan '(5, 8)' UNION
        SELECT floatspan '(7, 9)' )
      SELECT extent(r) FROM spans;
      -- [1,9)
      WITH times(ts) AS (
        SELECT tstzset '{2001-01-01, 2001-01-03, 2001-01-05}' UNION
        SELECT tstzset '{2001-01-02, 2001-01-04, 2001-01-06}' UNION
        SELECT tstzset '{2001-01-01, 2001-01-02}' )
      SELECT extent(ts) FROM times;
      -- [2001-01-01, 2001-01-06]
      WITH periods(ps) AS (
        SELECT tstzspanset '{[2001-01-01, 2001-01-02], [2001-01-03, 2001-01-04]}' UNION
        SELECT tstzspanset '{[2001-01-01, 2001-01-04], [2001-01-05, 2001-01-06]}' UNION
        SELECT tstzspanset '{[2001-01-02, 2001-01-06]}' )
      SELECT extent(ps) FROM periods;
      -- [2001-01-01, 2001-01-06]

- Aggregate union

  `setUnion({value,set}) → set`

  `spanUnion(spans) → spanset`

      WITH times(ts) AS (
        SELECT tstzset '{2001-01-01, 2001-01-03, 2001-01-05}' UNION
        SELECT tstzset '{2001-01-02, 2001-01-04, 2001-01-06}' UNION
        SELECT tstzset '{2001-01-01, 2001-01-02}' )
      SELECT setUnion(ts) FROM times;
      -- {2001-01-01, 2001-01-02, 2001-01-03, 2001-01-04, 2001-01-05, 2001-01-06}
      WITH periods(ps) AS (
        SELECT tstzspanset '{[2001-01-01, 2001-01-02], [2001-01-03, 2001-01-04]}' UNION
        SELECT tstzspanset '{[2001-01-02, 2001-01-03], [2001-01-05, 2001-01-06]}' UNION
        SELECT tstzspanset '{[2001-01-07, 2001-01-08]}' )
      SELECT spanUnion(ps) FROM periods;
      -- {[2001-01-01, 2001-01-04], [2001-01-05, 2001-01-06], [2001-01-07, 2001-01-08]}

- Temporal count

  `tCount(times) → {tintSeq,tintSeqSet}`

      WITH times(ts) AS (
        SELECT tstzset '{2001-01-01, 2001-01-03, 2001-01-05}' UNION
        SELECT tstzset '{2001-01-02, 2001-01-04, 2001-01-06}' UNION
        SELECT tstzset '{2001-01-01, 2001-01-02}' )
      SELECT tCount(ts) FROM times;
      -- {2@2001-01-01, 2@2001-01-02, 1@2001-01-03, 1@2001-01-04, 1@2001-01-05, 1@2001-01-06}
      WITH periods(ps) AS (
        SELECT tstzspanset '{[2001-01-01, 2001-01-02), [2001-01-03, 2001-01-04)}' UNION
        SELECT tstzspanset '{[2001-01-01, 2001-01-04), [2001-01-05, 2001-01-06)}' UNION
        SELECT tstzspanset '{[2001-01-02, 2001-01-06)}' )
      SELECT tCount(ps) FROM periods;
      -- {[2@2001-01-01, 3@2001-01-03, 1@2001-01-04, 2@2001-01-05, 2@2001-01-06)}

## Indexing

GiST and SP-GiST indexes can be created for table columns of the set and span types. The GiST index implements an R-tree while the SP-GiST index implements a quad-tree. An example of creation of a GiST index in a column `During` of type `tstzspan` in a table `Reservation` is as follows:

    CREATE TABLE Reservation (ReservationID integer PRIMARY KEY, RoomID integer,
      During tstzspan);
    CREATE INDEX Reservation_During_Idx ON Reservation USING GIST(During);

A GiST or an SP-GiST index can accelerate queries involving the following operators: `=`, `&&`, `<@`, `@>`, `-|-`, `<<`, `>>`, `&<`, `&>`, `<<#`, `#>>`, `&<#`, `#&>`, and `<->`.

In addition, B-tree indexes can be created for table columns of a set or span types. For these index types, basically the only useful operation is equality. There is a B-tree sort ordering defined for values of span time types with corresponding `<`, `<=`, `>`, and `>=` operators, but the ordering is rather arbitrary and not usually useful in the real world. The B-tree support is primarily meant to allow sorting internally in queries, rather than creation of actual indexes.

Finally, hash indexes can be created for table columns of a set or span types. For these types of indexes, the only operation defined is equality.