<?xml version="1.0" encoding="UTF-8"?>
  <sect1 id="PostGIS_Types">
    <sect1info>
    <abstract>
    <para>This section lists the custom PostgreSQL
		data types installed by PostGIS to represent spatial data.
    </para>
    <para>Each data type describes its type casting behavior.
		A <ulink url="https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">type cast</ulink>
		converts values of one data type into another type.
		PostgreSQL allows defining casting behavior for custom types, along with the functions used to convert type values.
		Casts can have <emphasis role="bold">automatic</emphasis> behavior,
		which allows automatic conversion of a function argument to a type supported by the function.</para>
		<para>
		Some casts have <emphasis role="bold">explicit</emphasis> behavior,
		which means the cast must be specified using the syntax <varname>CAST(myval As sometype)</varname>
		or <varname>myval::sometype</varname>.
		Explicit casting avoids the issue of ambiguous casts,
		which can occur when using an overloaded function which does not support a given type.
		For example, a function may accept a box2d or a box3d, but not a geometry.
		Since geometry has an automatic cast to both box types, this produces an "ambiguous function" error.
	  To prevent the error use an explicit cast to the desired box type.</para>

    <para>All data types can be cast to <varname>text</varname>, so this does not need to be specified explicitly.</para>
    </abstract>
    </sect1info>
    <title>PostGIS Geometry/Geography/Box Data Types</title>

	<refentry id="box2d_type">
      <refnamediv>
        <refname>box2d</refname>
        <refpurpose>The type representing a 2-dimensional bounding box. </refpurpose>
      </refnamediv>

      <refsection>
        <title>Description</title>
        <para><varname>box2d</varname> is a spatial data type used to represent
            the two-dimensional bounding box enclosing a geometry or collection of geometries.
            For example, the <xref linkend="ST_Extent" /> aggregate function returns a <varname>box2d</varname> object.</para>

            <para>The representation contains the values <varname>xmin, ymin, xmax, ymax</varname>.
            These are the minimum and maximum values of the X and Y extents.
            </para>

            <para><varname>box2d</varname> objects have a text representation which looks like <code>BOX(1 2,5 6)</code>.
            </para>
      </refsection>

      <refsection>
		<title>Casting Behavior</title>
		<para>This table lists the automatic and explicit casts allowed for this data type:</para>
		<informaltable rowsep="1" frame="all">
		<tgroup cols="2">
			<tbody>
			  <row>
				<entry>Cast To</entry>  <entry>Behavior</entry>
			  </row>
			  <row>
				<entry>box3d</entry>	<entry>automatic</entry>
			  </row>
			  <row>
				<entry>geometry</entry>	<entry>automatic</entry>
			  </row>
			</tbody>
		</tgroup>
		</informaltable>
		</refsection>

		<refsection>
			<title>See Also</title>
			<para><xref linkend="PostGIS_BoxFunctions" /></para>
		</refsection>
    </refentry>

	<refentry id="box3d_type">
      <refnamediv>
        <refname>box3d</refname>
        <refpurpose>The type representing a 3-dimensional bounding box. </refpurpose>
      </refnamediv>

      <refsection>
        <title>Description</title>
        <para><varname>box3d</varname> is a PostGIS spatial data type used to represent
            the three-dimensional bounding box enclosing a geometry or collection of geometries.
            For example, the <xref linkend="ST_3DExtent" /> aggregate function returns a <varname>box3d</varname> object.
            </para>

            <para>The representation contains the values <varname>xmin, ymin, zmin, xmax, ymax, zmax</varname>.
            These are the minimum and maxium values of the X, Y and Z extents.
            </para>

            <para><varname>box3d</varname> objects have a text representation which looks like <code>BOX3D(1 2 3,5 6 5)</code>.
            </para>
        </refsection>

      <refsection>
		<title>Casting Behavior</title>
		<para>This table lists the automatic and explicit casts allowed for this data type:</para>
		<informaltable rowsep="1" frame="all">
		<tgroup cols="2">
			<tbody>
			  <row>
				<entry>Cast To</entry>
				<entry>Behavior</entry>
			  </row>
			  <row>
				<entry>box</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>box2d</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>geometry</entry>
				<entry>automatic</entry>
			  </row>
			</tbody>
		</tgroup>
		</informaltable>
		</refsection>

		<refsection>
			<title>See Also</title>
			<para><xref linkend="PostGIS_BoxFunctions" /></para>
		</refsection>

    </refentry>

	<refentry id="geometry">
		<refnamediv>
			<refname>geometry</refname>
			<refpurpose>The type representing spatial features with planar coordinate systems.</refpurpose>
		</refnamediv>

		<refsection>
			<title>Description</title>
			<para><varname>geometry</varname> is a fundamental PostGIS spatial data type used to represent a feature in planar (Euclidean) coordinate systems.</para>
			<para>All spatial operations on geometry use the units of the Spatial Reference System the geometry is in.</para>
		</refsection>

		<refsection>
		<title>Casting Behavior</title>
		<para>This table lists the automatic and explicit casts allowed for this data type:</para>
		<informaltable rowsep="1" frame="all">
		<tgroup cols="2">
			<tbody>
			  <row>
				<entry>Cast To</entry>
				<entry>Behavior</entry>
			  </row>
			  <row>
				<entry>box</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>box2d</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>box3d</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>bytea</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>geography</entry>
				<entry>automatic</entry>
			  </row>
			  <row>
				<entry>text</entry>
				<entry>automatic</entry>
			  </row>
			</tbody>
		</tgroup>
		</informaltable>
		</refsection>

		<refsection>
			<title>See Also</title>
			<para><xref linkend="RefObject" />, <xref linkend="PostGIS_SQLMM_Functions" /></para>
		</refsection>
	</refentry>

	<refentry id="geometry_dump">
		<refnamediv>
			<refname>geometry_dump</refname>
			<refpurpose>A composite type used to describe the parts of complex geometry.</refpurpose>
		</refnamediv>

		<refsection>
		<title>Description</title>
		<para><varname>geometry_dump</varname> is a
		<ulink url="https://www.postgresql.org/docs/current/rowtypes.html">composite data type</ulink>
		containing the fields:</para>
		<itemizedlist>
		<listitem>
			<para><varname>geom</varname> - a geometry representing a component of the dumped geometry.
                The geometry type depends on the originating function.</para>
			</listitem>
		<listitem>
			<para><varname>path[]</varname> - an integer array
			that defines the navigation path within the dumped geometry to the <varname>geom</varname> component.
			The path array is 1-based (i.e. <varname>path[1]</varname> is the first element.)</para>
			</listitem>
		</itemizedlist>
		<para>
		It is used by the <varname>ST_Dump*</varname> family of functions as an output type to explode a complex geometry into its
		constituent parts.</para>
		</refsection>
		<refsection>
			<title>See Also</title>
			<para><xref linkend="PostGIS_Geometry_DumpFunctions" /> </para>
		</refsection>
	</refentry>

	<refentry id="geography">
		<refnamediv>
			<refname>geography</refname>
			<refpurpose>The type representing spatial features with geodetic (ellipsoidal) coordinate systems.</refpurpose>
		</refnamediv>

		<refsection>
		<title>Description</title>
		<para><varname>geography</varname> is a spatial data type used to represent a feature in geodetic coordinate systems.
		Geodetic coordinate systems model the earth using an ellipsoid.
		</para>
		<para>
		Spatial operations on the geography type provide more accurate results
		by taking the ellipsoidal model into account.
		</para>
		</refsection>

		<refsection>
		<title>Casting Behavior</title>
		<para>This table lists the automatic and explicit casts allowed for this data type:</para>
		<informaltable rowsep="1" frame="all">
		<tgroup cols="2">
			<tbody>
			  <row>
				<entry>Cast To</entry>
				<entry>Behavior</entry>
			  </row>
			  <row>
				<entry>geometry</entry>
				<entry>explicit</entry>
			  </row>
			</tbody>
		</tgroup>
		</informaltable>
		</refsection>

		<refsection>
			<title>See Also</title>
			<para><xref linkend="PostGIS_Geography" />, <xref linkend="PostGIS_GeographyFunctions" /></para>
		</refsection>
	</refentry>
  </sect1>
