<!-- doc/src/sgml/rangetypes.sgml -->

<sect1 id="rangetypes">
 <title>Range Types</title>

 <indexterm>
  <primary>range type</primary>
 </indexterm>

 <indexterm>
  <primary>multirange type</primary>
 </indexterm>

 <para>
  Range types are data types representing a range of values of some
  element type (called the range's <firstterm>subtype</firstterm>).
  For instance, ranges
  of <type>timestamp</type> might be used to represent the ranges of
  time that a meeting room is reserved. In this case the data type
  is <type>tsrange</type> (short for <quote>timestamp range</quote>),
  and <type>timestamp</type> is the subtype.  The subtype must have
  a total order so that it is well-defined whether element values are
  within, before, or after a range of values.
 </para>

 <para>
  Range types are useful because they represent many element values in a
  single range value, and because concepts such as overlapping ranges can
  be expressed clearly. The use of time and date ranges for scheduling
  purposes is the clearest example; but price ranges, measurement
  ranges from an instrument, and so forth can also be useful.
 </para>

 <para>
  Every range type has a corresponding multirange type. A multirange is
  an ordered list of non-contiguous, non-empty, non-null ranges. Most
  range operators also work on multiranges, and they have a few functions
  of their own.
 </para>

 <sect2 id="rangetypes-builtin">
  <title>Built-in Range and Multirange Types</title>

 <para>
  PostgreSQL comes with the following built-in range types:
  <itemizedlist>
    <listitem>
      <para>
       <type>int4range</type> &mdash; Range of <type>integer</type>,
       <type>int4multirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
    <listitem>
      <para>
       <type>int8range</type> &mdash; Range of <type>bigint</type>,
       <type>int8multirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
    <listitem>
      <para>
       <type>numrange</type> &mdash; Range of <type>numeric</type>,
       <type>nummultirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
    <listitem>
      <para>
       <type>tsrange</type> &mdash; Range of <type>timestamp without time zone</type>,
       <type>tsmultirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
    <listitem>
      <para>
       <type>tstzrange</type> &mdash; Range of <type>timestamp with time zone</type>,
       <type>tstzmultirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
    <listitem>
      <para>
       <type>daterange</type> &mdash; Range of <type>date</type>,
       <type>datemultirange</type> &mdash; corresponding Multirange
      </para>
    </listitem>
  </itemizedlist>
  In addition, you can define your own range types;
  see <xref linkend="sql-createtype"/> for more information.
 </para>
 </sect2>

 <sect2 id="rangetypes-examples">
  <title>Examples</title>

  <para>
<programlisting>
CREATE TABLE reservation (room int, during tsrange);
INSERT INTO reservation VALUES
    (1108, '[2010-01-01 14:30, 2010-01-01 15:30)');

-- Containment
SELECT int4range(10, 20) @&gt; 3;

-- Overlaps
SELECT numrange(11.1, 22.2) &amp;&amp; numrange(20.0, 30.0);

-- Extract the upper bound
SELECT upper(int8range(15, 25));

-- Compute the intersection
SELECT int4range(10, 20) * int4range(15, 25);

-- Is the range empty?
SELECT isempty(numrange(1, 5));
</programlisting>

   See <xref linkend="range-operators-table"/>
   and <xref linkend="range-functions-table"/> for complete lists of
   operators and functions on range types.
  </para>
 </sect2>

 <sect2 id="rangetypes-inclusivity">
  <title>Inclusive and Exclusive Bounds</title>

  <para>
   Every non-empty range has two bounds, the lower bound and the upper
   bound. All points between these values are included in the range. An
   inclusive bound means that the boundary point itself is included in
   the range as well, while an exclusive