<?xml version="1.0" encoding="UTF-8"?>
<!--
   ****************************************************************************
    MobilityDB Manual
    Copyright(c) MobilityDB Contributors

    This documentation is licensed under a Creative Commons Attribution-Share
    Alike 3.0 License: https://creativecommons.org/licenses/by-sa/3.0/
   ****************************************************************************
-->
<chapter xml:id="box_types">
	<title>Bounding Box Types</title>
	<para>We present next the functions and operators for bounding box types. These functions and operators are polimorhic, that is, their argumentos can be of various types and their result type may depend on the type of the arguments. To express this in the signature of the operators, we use the following notation:</para>

	<itemizedlist>
		<listitem>
			<para><varname>box</varname> represents any bounding box type, that is, <varname>tbox</varname> or <varname>stbox</varname>.</para>
		</listitem>
	</itemizedlist>

	<sect1 xml:id="box_input_output">
		<title>Input and Output</title>
			<para>
				MobilityDB generalizes Open Geospatial Consortium's Well-Known Text (WKT) and Well-Known Binary (WKB) input and output format for all temporal types. We present next the functions for input and output box types.
			</para>

		<para>A <varname>tbox</varname> is composed of a numeric and/or time dimensions. For each dimension, a span given, that is, either an <varname>intspan</varname> or a <varname>floatspan</varname> for the value dimension and a <varname>tstzspan</varname> for the time dimension. Examples of input of <varname>tbox</varname> values are as follows:
			<programlisting language="sql" xml:space="preserve" format="linespecific">
-- Both value and time dimensions
SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-02])';
SELECT tbox 'TBOXFLOAT XT([1.5,2.5],[2001-01-01,2001-01-02])';
-- Only value dimension
SELECT tbox 'TBOXINT X([1,3))';
SELECT tbox 'TBOXFLOAT X((1.5,2.5))';
-- Only time dimension
SELECT tbox 'TBOX T((2001-01-01,2001-01-02))';
</programlisting>
		</para>

		<para>An <varname>stbox</varname> is composed of a spatial and/or time dimensions, where the coordinates of the spatial dimension may be 2D or 3D. For the time dimension a <varname>tstzspan</varname> is given and for the spatial dimension minimum and maximum coordinate values are given, where the latter may be Cartesian (planar) or geodetic (spherical). The SRID of the coordinates may be specified; if it is not the case, a value of 0 (unknown) and 4326 (corresponding to WGS84) is assumed, respectively, for planar and geodetic boxes. Geodetic boxes always have a Z dimension to account for the curvature of the underlying sphere or spheroid. Examples of input of <varname>stbox</varname> values are as follows:
			<programlisting language="sql" xml:space="preserve" format="linespecific">
-- Only value dimension with X and Y coordinates
SELECT stbox 'STBOX X((1.0,2.0),(1.0,2.0))';
-- Only value dimension with X, Y, and Z coordinates
SELECT stbox 'STBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';
-- Both value (with X and Y coordinates) and time dimensions
SELECT stbox 'STBOX XT(((1.0,2.0),(1.0,2.0)),[2001-01-03,2001-01-03])';
-- Both value (with X, Y, and Z coordinates) and time dimensions
SELECT stbox 'STBOX ZT(((1.0,2.0,3.0),(1.0,2.0,3.0)),[2001-01-01,2001-01-03])';
-- Only time dimension
SELECT stbox 'STBOX T([2001-01-03,2001-01-03])';
-- Only value dimension with X, Y, and Z geodetic coordinates
SELECT stbox 'GEODSTBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';
-- Both value (with X, Y and Z geodetic coordinates) and time dimension
SELECT stbox 'GEODSTBOX ZT(((1.0,2.0,3.0),(1.0,2.0,3.0)),[2001-01-04,2001-01-04])';
-- Only time dimension for geodetic box
SELECT stbox 'GEODSTBOX T([2001-01-03,2001-01-03])';
-- SRID is given
SELECT stbox 'SRID=5676;STBOX XT(((1.0,2.0),(1.0,2.0)),[2001-01-04,2001-01-04])';
SELECT stbox 'SRID=4326;GEODSTBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';
</programlisting>
		</para>

			<para>
				We give next the functions for input and output of box types in Well-Known Text and Well-Known Binary format.
			</para>

			<itemizedlist>
				<listitem xml:id="box_asText">
					<indexterm significance="normal"><primary><varname>asText</varname></primary></indexterm>
					<para>Return the Well-Known Text (WKT) representation</para>
					<para><varname>asText(box,maxdecdigits=15) → text</varname></para>
					<para>The <varname>maxdecdigits</varname> argument can be used to set the maximum number of decimal places in the output of floating point values (default 15).</para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT asText(tbox 'TBOXFLOAT XT([1.123456789,2.123456789),[2001-01-01,2001-01-02))', 3);
-- TBOXFLOAT XT([1.123, 2.123),[2001-01-01 00:00:00+01, 2001-01-02 00:00:00+01))
SELECT asText(stbox 'STBOX Z((1.55,1.55,1.55),(2.55,2.55,2.55))', 0);
-- STBOX Z((2,2,2),(3,3,3))
</programlisting>
				</listitem>

				<listitem xml:id="box_asBinary">
					<indexterm significance="normal"><primary><varname>asBinary</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>asHexWKB</varname></primary></indexterm>
					<para>Return the Well-Known Binary (WKB) or the Hexadecimal Well-Known Binary (HexWKB) representation</para>
					<para><varname>asBinary(box,endian text='') → bytea</varname></para>
					<para><varname>asHexWKB(box,endian text='') → text</varname></para>
					<para>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.</para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT asBinary(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))');
-- \x0103270001009c57d3c11c000000fc2ef1d51c00000d0001000000000000f03f0000000000000040
SELECT asBinary(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))', 'XDR');
-- \x000300270100001cc1d3579c0000001cd5f12efc00000d013ff00000000000004000000000000000
SELECT asBinary(stbox 'STBOX X((1,1),(2,2))');
-- \x0101000000000000f03f0000000000000040000000000000f03f0000000000000040
SELECT asHexWKB(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))');
-- 0103270001009C57D3C11C000000FC2EF1D51C00000D0001000000000000F03F0000000000000040
SELECT asHexWKB(tbox 'TBOXFLOAT XT([1,2)[2001-01-01,2001-01-02))', 'XDR');
-- 000300270100001CC1D3579C0000001CD5F12EFC00000D013FF00000000000004000000000000000
SELECT asHexWKB(stbox 'STBOX X((1,1),(2,2))');
-- 0101000000000000F03F0000000000000040000000000000F03F0000000000000040
</programlisting>
				</listitem>

				<listitem xml:id="boxFromBinary">
					<indexterm significance="normal"><primary><varname>boxFromBinary</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>boxFromHexWKB</varname></primary></indexterm>
					<para>Input from the Well-Known Binary (WKB) or from the Hexadecimal Well-Known Binary (HexWKB) representation</para>
					<para><varname>boxFromBinary(bytea) → box</varname></para>
					<para><varname>boxFromHexWKB(text) → box</varname></para>
					<para>In the signatures above, <varname>box</varname> replaces any box type, that is, <varname>tbox</varname> or <varname>stbox</varname>.</para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tboxFromBinary(
  '\x0103270001009c57d3c11c000000fc2ef1d51c00000d0001000000000000f03f0000000000000040');
-- TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))
SELECT stboxFromBinary(
  '\x0101000000000000f03f0000000000000040000000000000f03f0000000000000040');
--  STBOX X((1,1),(2,2))
SELECT tboxFromHexWKB(
  '0103270001009C57D3C11C000000FC2EF1D51C00000D0001000000000000F03F0000000000000040');
-- TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02)))
SELECT stboxFromHexWKB(
  '0101000000000000F03F0000000000000040000000000000F03F0000000000000040');
-- STBOX X((1,1),(2,2))
</programlisting>
				</listitem>
			</itemizedlist>
	</sect1>

	<sect1 xml:id="box_constructors">
		<title>Constructors</title>

		<para>
			Type <varname>tbox</varname> has several constructor functions depending on whether the value and/or the time extent are given. The value extent can be specified by a number or a span, while the time extent can be specified by a time type.
		</para>

		<itemizedlist>
			<listitem xml:id="tbox">
				<indexterm significance="normal"><primary><varname>tbox</varname></primary></indexterm>
				<para>Constructor for <varname>tbox</varname></para>
				<para><varname>tbox({number,numspan}) → tbox</varname></para>
				<para><varname>tbox({timestamptz,tstzspan}) → tbox</varname></para>
				<para><varname>tbox({number,numspan},{timestamptz,tstzspan}) → tbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
-- Both value and time dimensions
SELECT tbox(1.0, timestamptz '2001-01-01');
SELECT tbox(floatspan '[1.0, 2.0)', tstzspan '[2001-01-01,2001-01-02)');
-- Only value dimension
SELECT tbox(floatspan '[1.0,2.0)');
-- Only time dimension
SELECT tbox(tstzspan '[2001-01-01,2001-01-02)');
</programlisting>
			</listitem>
		</itemizedlist>

		<para>
			Type <varname>stbox</varname> has several constructor functions depending on whether the space and/or the time extent are given. The coordinates for the spatial extent can be 2D or 3D and can be either Cartesian or geodetic. The spatial extent can be specified by the minimum and maximum coordinate values. The SRID can be specified in an optional last argument. If not given, a value 0 (respectively 4326) is assumed by default for planar (respectively geodetic) boxes. The spatial extent can also be specified by a geometry or a geography. The temporal extent can be specified by a time type.
		</para>

		<itemizedlist>
			<listitem xml:id="stbox">
				<indexterm significance="normal"><primary><varname>stboxX</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>stboxZ</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>stboxT</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>stboxXT</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>stboxZT</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>geodstboxZ</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>geodstboxT</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>geodstboxZT</varname></primary></indexterm>
				<para>Constructor for <varname>stbox</varname></para>
				<para><varname>stboxX(float,float,float,float,srid=0) → stbox</varname></para>
				<para><varname>stboxZ(float,float,float,float,float,float,srid=0) → stbox</varname></para>
				<para><varname>stboxT({timestamptz,tstzspan}) → stbox</varname></para>
				<para><varname>stboxXT(float,float,float,float,{timestamptz,tstzspan},srid=0) → stbox</varname></para>
				<para><varname>stboxZT(float,float,float,float,float,float,{timestamptz,tstzspan},srid=0) → stbox</varname></para>
				<para><varname>geodstboxZ(float,float,float,float,float,float,srid=4326) → stbox</varname></para>
				<para><varname>geodstboxT({timestamptz,tstzspan}) → stbox</varname></para>
				<para><varname>geodstboxZT(float,float,float,float,float,float,{timestamptz,tstzspan},srid=4326)</varname></para>
				<para><varname>  → stbox</varname></para>
				<para><varname>stbox(geo) → stbox</varname></para>
				<para><varname>stbox(geo,{timestamptz,tstzspan}) → stbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
-- Only value dimension with X and Y coordinates
SELECT stboxX(1.0,2.0,1.0,2.0);
-- Only value dimension with X, Y, and Z coordinates
SELECT stboxZ(1.0,2.0,3.0,1.0,2.0,3.0);
-- Only value dimension with X, Y, and Z coordinates and SRID
SELECT stboxZ(1.0,2.0,3.0,1.0,2.0,3.0,5676);
-- Only time dimension
SELECT stboxT(tstzspan '[2001-01-03,2001-01-03]');
-- Both value (with X and Y coordinates) and time dimensions
SELECT stboxXT(1.0,2.0, 1.0,2.0, tstzspan '[2001-01-03,2001-01-03]');
-- Both value (with X, Y, and Z coordinates) and time dimensions
SELECT stboxZT(1.0,2.0,3.0, 1.0,2.0,3.0, tstzspan '[2001-01-03,2001-01-03]');
-- Only value dimension with X, Y, and Z geodetic coordinates
SELECT geodstboxZ(1.0,2.0,3.0,1.0,2.0,3.0);
-- Only time dimension for geodetic box
SELECT geodstboxT(tstzspan '[2001-01-03,2001-01-03]');
--  Both value (with X, Y, and Z geodetic coordinates) and time dimensions
SELECT geodstboxZT(1.0,2.0,3.0, 1.0,2.0,3.0, tstzspan '[2001-01-03,2001-01-04]');
-- Geometry and time dimension
SELECT stbox(geometry 'Linestring(1 1 1,2 2 2)', tstzspan '[2001-01-03,2001-01-05]');
-- Geography and time dimension
SELECT stbox(geography 'Linestring(1 1 1,2 2 2)', tstzspan '[2001-01-03,2001-01-05]');
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_conversions">
		<title>Conversions</title>

		<itemizedlist>
			<listitem xml:id="tbox_convert_to">
				<indexterm significance="normal"><primary><varname>::</varname></primary></indexterm>
				<para>Convert a <varname>tbox</varname> to another type</para>
				<para><varname>tbox::{intspan,floatspan,tstzspan}</varname></para>
				<para><varname>intspan(tbox) → tbox</varname></para>
				<para><varname>floatspan(tbox) → tbox</varname></para>
				<para><varname>tstzspan(tbox) → tbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXINT XT([1,4),[2001-01-01,2001-01-02))'::intspan;
-- [1,4)
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02))'::floatspan;
-- (1, 2)
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02))'::tstzspan;
-- [2001-01-01, 2001-01-02)
</programlisting>
			</listitem>

			<listitem xml:id="tbox_convert_from">
				<indexterm significance="normal"><primary><varname>::</varname></primary></indexterm>
				<para>Convert another type to a <varname>tbox</varname></para>
				<para><varname>{numbers,times,tnumber}::tbox</varname></para>
				<para><varname>tbox({numbers,times,tnumber}) → tbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT intset '{1,2}'::tbox;
-- TBOXINT X([1, 3))
SELECT intspan '[1,3)'::tbox;
-- TBOXINT X([1, 3))
SELECT floatspan '(1.0,2.0)'::tbox;
-- TBOXFLOAT X((1, 2))
SELECT tstzspanset '{(2001-01-01,2001-01-02),(2001-01-03,2001-01-04)}'::tbox;
-- TBOX T((2001-01-01,2001-01-04))
</programlisting>
			</listitem>

			<listitem xml:id="stbox_convert_to">
				<indexterm significance="normal"><primary><varname>::</varname></primary></indexterm>
				<para>Convert an <varname>stbox</varname> to a another type</para>
				<para><varname>stbox::{box2d,box3d,geo,tstzspan}</varname></para>
				<para><varname>box2d(stbox) → box2d</varname></para>
				<para><varname>box3d(stbox) → box2d</varname></para>
				<para><varname>geometry(stbox) → geometry</varname></para>
				<para><varname>geography(stbox) → geography</varname></para>
				<para><varname>tstzspan(stbox) → tstzspan</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-03])'::box2d;
-- BOX(1 2,3 4)
SELECT ST_AsEWKT(stbox 'SRID=4326;STBOX XT(((1,1),(5,5)),[2001-01-01,2001-01-05])'::
  geometry);
-- SRID=4326;POLYGON((1 1,1 5,5 5,5 1,1 1))
SELECT ST_AsEWKT(stbox 'STBOX XT(((1,1),(1,5)),[2001-01-01,2001-01-05])'::geometry);
-- LINESTRING(1 1,1 5)
SELECT ST_AsEWKT(stbox 'GEODSTBOX XT(((1,1),(1,1)),[2001-01-01,2001-01-05])'::geography);
-- SRID=4326;POINT(1 1)
SELECT ST_AsEWKT(stbox 'STBOX ZT(((1,1,1),(5,5,5)),[2001-01-01,2001-01-05])'::
  geometry);
/* POLYHEDRALSURFACE(((1 1 1,1 5 1,5 5 1,5 1 1,1 1 1)),
   ((1 1 5,5 1 5,5 5 5,1 5 5,1 1 5)),((1 1 1,1 1 5,1 5 5,1 5 1,1 1 1)),
   ((5 1 1,5 5 1,5 5 5,5 1 5,5 1 1)),((1 1 1,5 1 1,5 1 5,1 1 5,1 1 1)),
   ((1 5 1,1 5 5,5 5 5,5 5 1,1 5 1))) */
SELECT stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-03])'::tstzspan;
-- [2001-01-01, 2001-01-03]
</programlisting>
			</listitem>

			<listitem xml:id="stbox_convert_from">
				<indexterm significance="normal"><primary><varname>::</varname></primary></indexterm>
				<para>Convert another type to an <varname>stbox</varname></para>
				<para><varname>{box2d,box3d,geo,time,tgeo}::stbox</varname></para>
				<para><varname>stbox({box2d,box3d,geo,time,tgeo}) → stbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT geometry 'Linestring(1 1 1,2 2 2)'::box3d::stbox;
-- STBOX Z((1,1,1),(2,2,2))
SELECT geography 'Linestring(1 1,2 2)'::stbox;
-- SRID=4326;GEODSTBOX X((1,1),(2,2))
SELECT tstzspanset '{(2001-01-01,2001-01-02),(2001-01-03,2001-01-04)}'::stbox;
-- STBOX T((2001-01-01,2001-01-04))
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_accessors">
		<title>Accessors</title>

		<itemizedlist>
			<listitem xml:id="hasX">
				<indexterm significance="normal"><primary><varname>hasX</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>hasZ</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>hasT</varname></primary></indexterm>
				<para>Has X/Z/T dimension?</para>
				<para><varname>hasX(box) → boolean</varname></para>
				<para><varname>hasZ(stbox) → boolean</varname></para>
				<para><varname>hasT(box) → boolean</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT hasX(tbox 'TBOX T([2001-01-01,2001-01-03))');
-- false
SELECT hasX(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
-- true
SELECT hasZ(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
-- false
SELECT hasT(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03])');
-- true
SELECT hasT(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
-- false
</programlisting>
			</listitem>

			<listitem xml:id="isGeodetic">
				<indexterm significance="normal"><primary><varname>isGeodetic</varname></primary></indexterm>
				<para>Is geodetic?</para>
				<para><varname>isGeodetic(stbox) → boolean</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT isGeodetic(stbox 'GEODSTBOX Z((1.0,1.0,0.0),(3.0,3.0,1.0))');
-- true
SELECT isGeodetic(stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-02])');
-- false
</programlisting>
			</listitem>

			<listitem xml:id="xMin">
				<indexterm significance="normal"><primary><varname>xMin</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>yMin</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>zMin</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>tMin</varname></primary></indexterm>
				<para>Return the minimum X/Y/Z/T value</para>
				<para><varname>xMin(box) → float</varname></para>
				<para><varname>yMin(stbox) → float</varname></para>
				<para><varname>zMin(stbox) → float</varname></para>
				<para><varname>tMin(box) → timestamptz</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT xMin(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
-- 1
SELECT yMin(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
-- 2
SELECT zMin(stbox 'STBOX Z((1.0,2.0,3.0),(4.0,5.0,6.0))');
-- 3
SELECT tMin(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
-- 2001-01-01
</programlisting>
				<para>Notice that for <varname>tbox</varname> the result value for <varname>xMin</varname> and <varname>xMin</varname> is converted to a <varname>float</varname> for the temporal boxes with an integer span.</para>
			</listitem>

			<listitem xml:id="xMax">
				<indexterm significance="normal"><primary><varname>xMax</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>yMax</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>zMax</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>tMax</varname></primary></indexterm>
				<para>Return the maximum X/Y/Z/T value</para>
				<para><varname>xMax(box) → float</varname></para>
				<para><varname>yMax(stbox) → float</varname></para>
				<para><varname>zMax(stbox) → float</varname></para>
				<para><varname>tMax(box) → timestamptz</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT xMax(tbox 'TBOXINT X([1,4))');
-- 3
SELECT yMax(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
-- 4
SELECT zMax(stbox 'STBOX Z((1.0,2.0,3.0),(4.0,5.0,6.0))');
-- 6
SELECT tMax(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
-- 2001-01-03
</programlisting>
				<para>Notice that for <varname>tbox</varname> the result value for <varname>xMin</varname> and <varname>xMin</varname> is converted to a <varname>float</varname> for the temporal boxes with an integer span.</para>
			</listitem>

			<listitem xml:id="xMinInc">
				<indexterm significance="normal"><primary><varname>xMinInc</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>tMinInc</varname></primary></indexterm>
				<para>Is the minimum X/T value inclusive?</para>
				<para><varname>xMinInc(tbox) → bool</varname></para>
				<para><varname>tMinInc(box) → bool</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT xMinInc(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
-- false
SELECT tMinInc(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
-- true
</programlisting>
			</listitem>

			<listitem xml:id="xMaxInc">
				<indexterm significance="normal"><primary><varname>xMaxInc</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>tMaxInc</varname></primary></indexterm>
				<para>Is the maximum X/T value inclusive?</para>
				<para><varname>xMaxInc(tbox) → bool</varname></para>
				<para><varname>tMaxInc(box) → bool</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT xMaxInc(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
-- false
SELECT tMaxInc(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
-- true
</programlisting>
			</listitem>

			<listitem xml:id="area">
				<indexterm significance="normal"><primary><varname>area</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>perimeter</varname></primary></indexterm>
				<para>Area, volume, perimeter</para>
				<para><varname>area(stbox, spheroid bool=true) → float</varname></para>
				<para><varname>volume(stbox) → float</varname></para>
				<para><varname>perimeter(stbox, spheroid bool=true) → float</varname></para>
				<para>For geodetic boxes, the computation is done on the WGS 84 spheroid by default. If the last argument is false, a faster spherical calculation is used. The <varname>volume</varname> function do not accept geodetic boxes.</para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT area(stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
-- 4
SELECT volume(stbox 'STBOX ZT(((1,1,1),(3,3,3)),[2001-01-01,2001-01-03))');
-- 8
SELECT perimeter(stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
-- 8
SELECT area(stbox 'GEODSTBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
-- 49209676328.36632
SELECT perimeter(stbox 'GEODSTBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))', false);
-- 889221.9544681838
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_transformations">
		<title>Transformations</title>

		<itemizedlist>
			<listitem xml:id="box_shiftValue">
				<indexterm significance="normal"><primary><varname>shiftValue</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>scaleValue</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>shiftScaleValue</varname></primary></indexterm>
				<para>Shift and/or scale the span of a bounding box by one or two values</para>
				<para><varname>shiftValue(box,{integer,float}) → box</varname></para>
				<para><varname>scaleValue(box,{integer,float}) → box</varname></para>
				<para><varname>shiftScaleValue(tbox,{integer,float},{integer,float}) → box</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT shiftValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 1.0);
-- TBOXFLOAT XT([2.5, 3.5],[2001-01-01, 2001-01-02])
SELECT scaleValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 2.0);
-- TBOXFLOAT XT([1.5, 3.5],[2001-01-01, 2001-01-02])
SELECT shiftScaleValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 2.0, 3.0);
-- TBOXFLOAT XT([3.5, 6.5],[2001-01-01, 2001-01-02])
</programlisting>
			</listitem>

			<listitem xml:id="box_shiftTime">
				<indexterm significance="normal"><primary><varname>shiftTime</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>scaleTime</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>shiftScaleTime</varname></primary></indexterm>
				<para>Shift and/or scale the span or the period of the bounding box to a value or interval</para>
				<para><varname>shiftTime(box,interval) → box</varname></para>
				<para><varname>scaleTime(box,interval) → box</varname></para>
				<para><varname>shiftScaleTime(box,interval,interval) → box</varname></para>
				<para>For scaling, if the width or the time span of the period is zero (that is, the lower and upper bound are equal), the result is the box. The given value or interval must be strictly greater than zero.</para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT shiftTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
  interval '1 day');
-- TBOXFLOAT XT([1.5, 2.5],[2001-01-02, 2001-01-03])
SELECT shiftTime(stbox 'STBOX T([2001-01-01,2001-01-02])', interval '-1 day');
-- STBOX T([2001-12-31, 2001-01-01])
SELECT shiftTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
  interval '1 day');
-- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-02, 2001-01-03])
SELECT scaleTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
  interval '2 days');
-- TBOXFLOAT XT([1.5, 2.5],[2001-01-01, 2001-01-03])
SELECT scaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
  interval '1 hour');
-- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01 00:00:00, 2001-01-01 01:00:00])
SELECT scaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
  interval '-1 day');
-- ERROR:  The interval must be positive: -1 days
SELECT shiftScaleTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
  interval '1 day', interval '3 days');
-- TBOXFLOAT XT([1.5, 2.5],[2001-01-02, 2001-01-05])
SELECT shiftScaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
  interval '1 hour', interval '3 hours');
-- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01 01:00:00, 2001-01-01 04:00:00])
</programlisting>
			</listitem>

			<listitem xml:id="box_getSpace">
				<indexterm significance="normal"><primary><varname>getSpace</varname></primary></indexterm>
				<para>Return the spatial dimension of the bounding box, removing the temporal dimension if any</para>
				<para><varname>getSpace(stbox) → stbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT getSpace(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])');
-- STBOX Z((1,1,1),(2,2,2))
</programlisting>
			</listitem>
		</itemizedlist>

		<para>
			The functions given next expand the bounding boxes on the value and the time dimension or set the precision of the value dimension. These functions raise an error if the corresponding dimension is not present.
		</para>
		<itemizedlist>
			<listitem xml:id="box_expand">
				<indexterm significance="normal"><primary><varname>expandValue</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>expandSpace</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>expandTime</varname></primary></indexterm>
				<para>Expand the numeric, spatial, or temporal dimension of a bounding box by a value or an interval</para>
				<para><varname>expandValue(tbox,{integer,float}) → tbox</varname></para>
				<para><varname>expandSpace(stbox,float) → stbox</varname></para>
				<para><varname>expandTime(box,interval) → box</varname></para>
				<para>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.</para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT expandValue(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', 1.0);
-- TBOXFLOAT XT((0,3),[2001-01-01,2001-01-03])
SELECT expandValue(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', -1.0);
-- NULL
SELECT expandValue(tbox 'TBOX T([2001-01-01,2001-01-03))', 1);
-- The box must have value dimension
</programlisting>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT expandSpace(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])', 1);
-- STBOX ZT(((0,0,0),(3,3,3)),[2001-01-01,2001-01-03])
SELECT expandSpace(stbox 'STBOX T([2001-01-01,2001-01-03))', 1);
-- The box must have space dimension
</programlisting>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT expandTime(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', interval '1 day');
-- TBOXFLOAT XT((1,2),[2000-12-31,2001-01-04])
SELECT expandTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])',
  interval '-1 day');
-- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-02,2001-01-02])
SELECT expandTime(tbox 'TBOX XT((1,2),[2001-01-01,2001-01-03])', interval '-2 days');
-- NULL
</programlisting>
			</listitem>

			<listitem xml:id="box_round">
				<indexterm significance="normal"><primary><varname>round</varname></primary></indexterm>
				<para>Round the value or the coordinates of the bounding box to a number of decimal places</para>
				<para><varname>round(box,integer=0) → box</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT round(tbox 'TBOXFLOAT XT((1.12345,2.12345),[2001-01-01,2001-01-02])', 2);
-- TBOXFLOAT XT((1.12,2.12),[2001-01-01, 2001-01-02])
SELECT round(stbox 'STBOX XT(((1.12345, 1.12345),(2.12345, 2.12345)),
  [2001-01-01,2001-01-02])', 2);
-- STBOX XT(((1.12,1.12),(2.12,2.12)),[2001-01-01, 2001-01-02])
SELECT round(tstzspan '[2000-01-01, 2001-01-02]'::tbox);
-- The tbox must have X dimension
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_srid">
		<title>Spatial Reference System</title>

		<itemizedlist>
			<listitem xml:id="stbox_SRID">
				<indexterm significance="normal"><primary><varname>SRID</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>setSRID</varname></primary></indexterm>
				<para>Return or set the spatial reference identifier</para>
				<para><varname>SRID(stbox) → integer</varname></para>
				<para><varname>setSRID(stbox) → stbox</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT SRID(stbox 'STBOX ZT(((1.0,2.0,3.0),(4.0,5.0,6.0)),[2001-01-01,2001-01-02])');
-- 0
SELECT SRID(stbox 'SRID=5676;STBOX XT(((1.0,2.0),(4.0,5.0)),[2001-01-01,2001-01-02])');
-- 5676
SELECT SRID(stbox 'GEODSTBOX T([2001-01-01,2001-01-02))');
-- ERROR:  The box must have space dimension
</programlisting>

				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT setSRID(stbox 'STBOX ZT(((1.0,2.0,3.0),(4.0,5.0,6.0)),
  [2001-01-01,2001-01-02])', 5676);
-- SRID=5676;STBOX ZT(((1,2,3),(4,5,6)),[2001-01-01,2001-01-02])
</programlisting>
				</listitem>

			<listitem xml:id="stbox_transform">
				<indexterm significance="normal"><primary><varname>transform</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>transformPipeline</varname></primary></indexterm>
				<para>Transform to a spatial reference identifier</para>
				<para><varname>transform(stbox,to_srid integer) → stbox</varname></para>
				<para><varname>transformPipeline(stbox,pipeline text,to_srid integer,is_forward bool=true) → stbox</varname></para>
				<para>The <varname>transform</varname> function specifies the transformation with a target SRID. An error is raised when the input box has an unknown SRID (represented by 0). The <varname>transformPipeline</varname> function specifies the transformation with a defined coordinate transformation pipeline represented with the following string format:</para>
				<para><varname>urn:ogc:def:coordinateOperation:AUTHORITY::CODE</varname></para>
				<para>The SRID of the input box is ignored, and the SRID of the output box will be set to zero unless a value is provided via the optional <varname>to_srid</varname> 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.</para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT round(transform(stbox 'SRID=4326;STBOX XT(((2.340088, 49.400250),
  (6.575317, 51.553167)),[2001-01-01,2001-01-02])', 3812), 6);
/* SRID=3812;STBOX XT(((502773.429981,511805.120402),(803028.908265,751590.742629)),
  [2001-01-01, 2001-01-02]) */
WITH test(box, pipeline) AS (
  SELECT stbox 'SRID=4326;GEODSTBOX Z((-0.1275,50.846667,100),(4.3525,51.507222,100))',
    text 'urn:ogc:def:coordinateOperation:EPSG::16031' )
SELECT asEWKT(transformPipeline(transformPipeline(box, pipeline, 4326),
  pipeline, 4326, false), 6)
FROM test;
-- SRID=4326;GEODSTBOX Z((-0.1275,50.846667,100),(4.3525,51.507222,100))
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_splitting">
		<title>Splitting Operations</title>

		<itemizedlist>
			<listitem xml:id="quadSplit">
				<indexterm significance="normal"><primary><varname>quadSplit</varname></primary></indexterm>
				<para>Split the bounding box in quadrants or octants &SRF;
</para>
				<para><varname>quadSplit(stbox) → {stbox}</varname></para>
				<para>As indicated by the &SRF;
 symbol, this function is a <emphasis>set-returning function</emphasis> (also known as a <emphasis>table function</emphasis>) since it typically return more than one value.</para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT quadSplit(stbox 'STBOX XT(((0,0),(4,4)),[2001-01-01,2001-01-05])');
/* {"STBOX XT(((0,0),(2,2)),[2001-01-01, 2001-01-05])",
   "STBOX XT(((2,0),(4,2)),[2001-01-01, 2001-01-05])",
   "STBOX XT(((0,2),(2,4)),[2001-01-01, 2001-01-05])",
   "STBOX XT(((2,2),(4,4)),[2001-01-01, 2001-01-05])"} */
SELECT quadSplit(stbox 'STBOX Z((0,0,0),(4,4,4))');
/* {"STBOX Z((0,0,0),(2,2,2))","STBOX Z((2,0,0),(4,2,2))","STBOX Z((0,2,0),(2,4,2))",
   "STBOX Z((2,2,0),(4,4,2))","STBOX Z((0,0,2),(2,2,4))","STBOX Z((2,0,2),(4,2,4))",
   "STBOX Z((0,2,2),(2,4,4))","STBOX Z((2,2,2),(4,4,4))"} */
</programlisting>
			</listitem>
		</itemizedlist>
		<para>This function is typically used for multiresolution grids, where the space is split in cells such that the cells have a maximum number of elements. <xref linkend="berlinmod_grid"/> shows an example of the result of using this function using synthetic trajectories in Brussels.</para>
		<figure xml:id="berlinmod_grid" float="start">
			<title>Multiresolution grid on Brussels data obtained using the <ulink url="https://github.com/MobilityDB/MobilityDB-BerlinMOD">BerlinMOD</ulink> generator. Each cell contains at most 10,000 (left) and 1,000 (right) instants across the entire simulation period (four days in this case). On the left, we can see the high density of the traffic in the ring around Brussels, while on the right we can see other main axes in the city.</title>
			<mediaobject>
				<imageobject><imagedata scale="65" fileref="images/berlinmod_grid10k.png"/></imageobject>
			</mediaobject>
			<mediaobject>
				<imageobject><imagedata scale="65" fileref="images/berlinmod_grid1k.png"/></imageobject>
			</mediaobject>
		</figure>
	</sect1>

	<sect1 xml:id="box_set_ops">
		<title>Set Operations</title>

		<para>The set operators for box types are union (<varname>+</varname>) and intersection (<varname>*</varname>). In the case of union, the operands must have exactly the same dimensions, otherwise an error is raised. Furthermore, if the operands do not overlap on all the dimensions and error is raised, since in this would result in a box with disjoint values, which cannot be represented.  The operator computes the union on all dimensions that are present in both arguments. In the case of intersection, the operands must have at least one common dimension, otherwise an error is raised. The operator computes the intersection on all dimensions that are present in both arguments.</para>

		<itemizedlist>
			<listitem xml:id="box_union">
				<indexterm significance="normal"><primary><varname>+</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>*</varname></primary></indexterm>
				<para>Union and intersection of two bounding boxes</para>
				<para><varname>box {+, *} box → box</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-03])' +
  tbox 'TBOXINT XT([2,4),[2001-01-02,2001-01-04])';
-- TBOXINT XT([1,4),[2001-01-01,2001-01-04])
SELECT stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])' +
  stbox 'STBOX XT(((2,2),(3,3))),[2001-01-01,2001-01-03]';
-- ERROR:  The arguments must be of the same dimensionality
SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-02])' +
  tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
-- ERROR:  Result of box union would not be contiguous
</programlisting>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-03])' *
  tbox 'TBOX T([2001-01-02,2001-01-04))';
-- TBOX T([2001-01-02,2001-01-03))
SELECT stbox 'STBOX ZT(((1,1,1),(3,3,3)),[2001-01-01,2001-01-02])' *
  stbox 'STBOX X((2,2),(4,4))';
-- STBOX X((2,2),(3,3))
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_topo_pos">
		<title>Bounding Box Operations</title>

		<sect2>
			<title>Topological Operations</title>
			<para>There are five topological operators: overlaps (<varname>&amp;&amp;</varname>), contains (<varname>@&gt;</varname>), contained (<varname>&lt;@</varname>), same (<varname>~=</varname>), and adjacent (<varname>-|-</varname>). The operators verify the topological relationship between the bounding boxes taking into account the value and/or the time dimension for as many dimensions that are present on both arguments.</para>

			<itemizedlist>
				<listitem xml:id="box_overlap">
					<indexterm significance="normal"><primary><varname>&amp;&amp;</varname></primary></indexterm>
					<para>Do the bounding boxes overlap?</para>
					<para><varname>box &amp;&amp; box → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-03])' &amp;&amp;
  tbox 'TBOXFLOAT XT((2,4),[2001-01-02,2001-01-04])';
-- true
SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' &amp;&amp;
  stbox 'STBOX T([2001-01-02,2001-01-02])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="box_contains">
					<indexterm significance="normal"><primary><varname>@&gt;</varname></primary></indexterm>
					<para>Does the first bounding box contain the second one?</para>
					<para><varname>box @&gt; box → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' @&gt;
  tbox 'TBOXFLOAT XT((2,3),[2001-01-01,2001-01-02])';
-- true
SELECT stbox 'STBOX Z((1,1,1),(3,3,3))' @&gt;
  stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="box_containedby">
					<indexterm significance="normal"><primary><varname>&lt;@</varname></primary></indexterm>
					<para>Is the first bounding box contained in the second one?</para>
					<para><varname>box &lt;@ box → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &lt;@
  tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])';
-- true
SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' &lt;@
  stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="box_same">
					<indexterm significance="normal"><primary><varname>~=</varname></primary></indexterm>
					<para>Are the bounding boxes equal in their common dimensions?</para>
					<para><varname>box ~= box → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' ~=
  tbox 'TBOXFLOAT T([2001-01-01,2001-01-02])';
-- true
SELECT stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03])' ~=
  stbox 'STBOX Z((1,1,1),(3,3,3))';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="box_adjacent">
					<indexterm significance="normal"><primary><varname>-|-</varname></primary></indexterm>
					<para>Are the bounding boxes adjacent?</para>
					<para><varname>box -|- box → boolean</varname></para>
					<para>Two boxes are adjacent if they share <emphasis>n</emphasis> dimensions and their intersection is at most of <emphasis>n</emphasis>-1 dimensions.</para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXINT XT([1,2),[2001-01-01,2001-01-02])' -|-
  tbox 'TBOXINT XT([2,3),[2001-01-02,2001-01-03])';
-- true
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' -|-
  tbox 'TBOX T([2001-01-02,2001-01-03])';
-- true
SELECT stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03])' -|-
  stbox 'STBOX XT(((2,2),(4,4)),[2001-01-03,2001-01-04])';
-- true
</programlisting>
				</listitem>
			</itemizedlist>
		</sect2>

		<sect2>
			<title>Position Operations</title>
			<para>The position operators consider the relative position of the bounding boxes. The operators <varname>&lt;&lt;</varname>, <varname>&gt;&gt;</varname>, <varname>&amp;&lt;</varname>, and <varname>&amp;&gt;</varname> consider the X value for the <varname>tbox</varname> type and the X coordinates for the <varname>stbox</varname> type, the operators <varname>&lt;&lt;|</varname>, <varname>|&gt;&gt;</varname>, <varname>&amp;&lt;|</varname>, and <varname>|&amp;&gt;</varname> consider the Y coordinates for the <varname>stbox</varname> type, the operators <varname>&lt;&lt;/</varname>, <varname>/&gt;&gt;</varname>, <varname>&amp;&lt;/</varname>, and <varname>/&amp;&gt;</varname> consider the Z coordinates for the <varname>stbox</varname> type, and the operators <varname>&lt;&lt;#</varname>, <varname>#&gt;&gt;</varname>, <varname>#&amp;&lt;</varname>, and <varname>#&amp;&gt;</varname> consider the time dimension for the <varname>tbox</varname> and <varname>stbox</varname> types. The operators raise an error if both boxes do not have the required dimension.</para>

			<para>The operators for the numeric dimension of the <varname>tbox</varname> type are given next.</para>

			<itemizedlist>
				<listitem xml:id="tbox_left">
					<indexterm significance="normal"><primary><varname>&lt;&lt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&lt;&lt;|</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&lt;&lt;/</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&lt;&lt;#</varname></primary></indexterm>
					<para>Are the X/Y/Z/T values of the first bounding box strictly less than those of the second one?</para>
					<para><varname>tbox {&lt;&lt;, &lt;&lt;#} tbox → boolean</varname></para>
					<para><varname>stbox {&lt;&lt;, &lt;&lt;|, &lt;&lt;/, &lt;&lt;#} stbox → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &lt;&lt;
  tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
-- true
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &lt;&lt;
  tbox 'TBOXFLOAT T([2001-01-03,2001-01-04])';
-- ERROR:  The box must have value dimension
SELECT stbox 'STBOX Z((1,1,1),(2,2,2))' &lt;&lt;| stbox 'STBOX Z((3,3,3),(4,4,4))';
-- true
SELECT stbox 'STBOX Z((1,1,1),(2,2,2))' &lt;&lt;/ stbox 'STBOX Z((3,3,3),(4,4,4))';
-- true
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &lt;&lt;#
  tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="tbox_right">
					<indexterm significance="normal"><primary><varname>&gt;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>|&gt;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>/&gt;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>#&gt;&gt;</varname></primary></indexterm>
					<para>Are the X/Y/Z/T values of the first bounding box strictly greater than those of the second one?</para>
					<para><varname>tbox {&gt;&gt;, #&gt;&gt;} tbox → boolean</varname></para>
					<para><varname>stbox {&gt;&gt;, |&gt;&gt;, /&gt;&gt;, #&gt;&gt;} stbox → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])' &gt;&gt;
  tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])';
-- true
SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' |&gt;&gt; stbox 'STBOX Z((1,1,1),(2,2,2))';
-- true
SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' /&gt;&gt; stbox 'STBOX Z((1,1,1),(2,2,2))';
-- true
SELECT stbox 'STBOX XT(((3,3),(4,4)),[2001-01-03,2001-01-04])'  #&gt;&gt;
  stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="tbox_overleft">
					<indexterm significance="normal"><primary><varname>&amp;&lt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&amp;&lt;|</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&amp;&lt;/</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>&amp;&lt;#</varname></primary></indexterm>
					<para>Are the X/Y/Z/T values of the first bounding box not greater than those of the second one?</para>
					<para><varname>tbox {&amp;&lt;, &amp;&lt;#} {tbox,stbox} → boolean</varname></para>
					<para><varname>stbox {&amp;&lt;, &amp;&lt;|, &amp;&lt;/, &amp;&lt;#} stbox → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' &amp;&lt;
  tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
-- true
SELECT stbox 'STBOX Z((1,1,1),(4,4,4))' &amp;&lt;| stbox 'STBOX Z((3,3,3),(4,4,4))';
-- true
SELECT stbox 'STBOX Z((1,1,1),(4,4,4))' &amp;&lt;/ stbox 'STBOX Z((3,3,3),(4,4,4))';
-- true
SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' &amp;&lt;#
  tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
-- true
</programlisting>
				</listitem>

				<listitem xml:id="tbox_overright">
					<indexterm significance="normal"><primary><varname>&amp;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>|&amp;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>/&amp;&gt;</varname></primary></indexterm>
					<indexterm significance="normal"><primary><varname>#&amp;&gt;</varname></primary></indexterm>
					<para>Are the X/Y/Z/T values of the first bounding box not less than those of the second one?</para>
					<para><varname>tbox {&amp;&gt;, #&amp;&gt;} tbox → boolean</varname></para>
					<para><varname>stbox {&amp;&gt;, |&amp;&gt;, /&amp;&gt;, #&amp;&gt;} stbox} → boolean</varname></para>
					<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &amp;&gt;
  tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])';
-- true
SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' |&amp;&gt; stbox 'STBOX Z((1,1,1),(2,2,2))';
-- false
SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' /&amp;&gt; stbox 'STBOX Z((1,1,1),(2,2,2))';
-- true
SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' #&amp;&gt;
  stbox 'STBOX XT(((1,1),(4,4)),[2001-01-01,2001-01-04])';
-- true
</programlisting>
				</listitem>
			</itemizedlist>
		</sect2>
	</sect1>

	<sect1 xml:id="box_comparisons">
		<title>Comparisons</title>

		<para>The traditional comparison operators (<varname>=</varname>, <varname>&lt;</varname>, and so on) can be applied to box types. Excepted equality  and inequality, the other comparison operators are not useful in the real world but allow B-tree indexes to be constructed on box types. These operators compare first the timestamps and if those are equal, compare the values.</para>

		<itemizedlist>
			<listitem xml:id="box_eq">
				<indexterm significance="normal"><primary><varname>=</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>&lt;&gt;</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>&lt;</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>&gt;</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>&lt;=</varname></primary></indexterm>
				<indexterm significance="normal"><primary><varname>&gt;=</varname></primary></indexterm>
				<para>Traditional comparisons</para>
				<para><varname>box {=, &lt;&gt;, &lt;, &lt;=, &gt;=} box → boolean</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' =
  tbox 'TBOXINT XT([2,2],[2001-01-03,2001-01-05])';
-- false
SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-01,2001-01-04])' &lt;&gt;
  tbox 'TBOXFLOAT XT([2,2],[2001-01-03,2001-01-05])';
-- true
SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' &lt;
  tbox 'TBOXINT XT([1,2],[2001-01-03,2001-01-05])';
-- true
SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-03,2001-01-04])' &gt;
  tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-05])';
-- true
SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' &lt;=
  tbox 'TBOXINT XT([2,2],[2001-01-03,2001-01-05])';
-- true
SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-01,2001-01-04])' &gt;=
  tbox 'TBOXFLOAT XT([2,2],[2001-01-03,2001-01-05])';
-- false
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_aggregations">
		<title>Aggregations</title>

		<itemizedlist>
			<listitem xml:id="box_extent">
				<indexterm significance="normal"><primary><varname>extent</varname></primary></indexterm>
				<para>Bounding box extent</para>
				<para><varname>extent(box) → box</varname></para>
				<programlisting language="sql" xml:space="preserve" format="linespecific">
WITH boxes(b) AS (
  SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-03])' UNION
  SELECT tbox 'TBOXFLOAT XT((5,7),[2001-01-05,2001-01-07])' UNION
  SELECT tbox 'TBOXFLOAT XT((6,8),[2001-01-06,2001-01-08])' )
SELECT extent(b) FROM boxes;
-- TBOXFLOAT XT((1,8),[2001-01-01,2001-01-08])
WITH boxes(b) AS (
  SELECT stbox 'STBOX Z((1,1,1),(3,3,3))' UNION
  SELECT stbox 'STBOX Z((5,5,5),(7,7,7))' UNION
  SELECT stbox 'STBOX Z((6,6,6),(8,8,8))' )
SELECT extent(b) FROM boxes;
-- STBOX Z((1,1,1),(8,8,8))
</programlisting>
			</listitem>
		</itemizedlist>
	</sect1>

	<sect1 xml:id="box_indexing">
		<title>Indexing</title>
		<para>GiST and SP-GiST indexes can be created for table columns of the <varname>tbox</varname> and <varname>stbox</varname> types. The GiST index implements an R-tree and the SP-GiST index implements an n-dimensional quad-tree. An example of creation of a GiST index in a column <varname>Box</varname> of type <varname>stbox</varname> in a table <varname>Trips</varname> is as follows:
			<programlisting language="sql" xml:space="preserve" format="linespecific">
CREATE TABLE Trips(TripID integer PRIMARY KEY, Trip tgeompoint, Box stbox);
CREATE INDEX Trips_Box_Idx ON Trips USING GIST(bbox);
</programlisting>
		</para>
		<para>A GiST or SP-GiST index can accelerate queries involving the following operators: <varname>&amp;&amp;</varname>, <varname>&lt;@</varname>, <varname>@&gt;</varname>, <varname>~=</varname>, <varname>-|-</varname>, <varname>&lt;&lt;</varname>, <varname>&gt;&gt;</varname>, <varname>&amp;&lt;</varname>, <varname>&amp;&gt;</varname>, <varname>&lt;&lt;|</varname>, <varname>|&gt;&gt;</varname>, <varname>&amp;&lt;|</varname>, <varname>|&amp;&gt;</varname>,  <varname>&lt;&lt;/</varname>, <varname>/&gt;&gt;</varname>, <varname>&amp;&lt;/</varname>, <varname>/&amp;&gt;</varname>, <varname>&lt;&lt;#</varname>, <varname>#&gt;&gt;</varname>, <varname>&amp;&lt;#</varname>, and <varname>#&amp;&gt;</varname>.</para>

		<para>In addition, B-tree indexes can be created for table columns of a bounding box type. For these index types, basically the only useful operation is equality. There is a B-tree sort ordering defined for values of bounding box types, with corresponding <varname>&lt;</varname> and <varname>&gt;</varname> 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.</para>
	</sect1>
</chapter>