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

<sect1 id="seg" xreflabel="seg">
 <title>seg &mdash; a datatype for line segments or floating point intervals</title>

 <indexterm zone="seg">
  <primary>seg</primary>
 </indexterm>

 <para>
  This module implements a data type <type>seg</type> for
  representing line segments, or floating point intervals.
  <type>seg</type> can represent uncertainty in the interval endpoints,
  making it especially useful for representing laboratory measurements.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="seg-rationale">
  <title>Rationale</title>

  <para>
   The geometry of measurements is usually more complex than that of a
   point in a numeric continuum. A measurement is usually a segment of
   that continuum with somewhat fuzzy limits. The measurements come out
   as intervals because of uncertainty and randomness, as well as because
   the value being measured may naturally be an interval indicating some
   condition, such as the temperature range of stability of a protein.
  </para>

  <para>
   Using just common sense, it appears more convenient to store such data
   as intervals, rather than pairs of numbers. In practice, it even turns
   out more efficient in most applications.
  </para>

  <para>
   Further along the line of common sense, the fuzziness of the limits
   suggests that the use of traditional numeric data types leads to a
   certain loss of information. Consider this: your instrument reads
   6.50, and you input this reading into the database. What do you get
   when you fetch it? Watch:

<screen>
test=&gt; select 6.50 :: float8 as "pH";
 pH
---
6.5
(1 row)
</screen>

   In the world of measurements, 6.50 is not the same as 6.5. It may
   sometimes be critically different. The experimenters usually write
   down (and publish) the digits they trust. 6.50 is actually a fuzzy
   interval contained within a bigger and even fuzzier interval, 6.5,
   with their center points being (probably) the only common feature they
   share. We definitely do not want such different data items to appear the
   same.
  </para>

  <para>
   Conclusion? It is nice to have a special data type that can record the
   limits of an interval with arbitrarily variable precision. Variable in
   the sense that each data element records its own precision.
  </para>

  <para>
   Check this out:

<screen>
test=&gt; select '6.25 .. 6.50'::seg as "pH";
          pH
------------
6.25 .. 6.50
(1 row)
</screen>
  </para>
 </sect2>

 <sect2 id="seg-syntax">
  <title>Syntax</title>

  <para>
   The external representation of an interval is formed using one or two
   floating-point numbers joined by the range operator (<literal>..</literal>
   or <literal>...</literal>).  Alternatively, it can be specified as a
   center point plus or minus a deviation.
   Optional certainty indicators (<literal>&lt;</literal>,
   <literal>&gt;</literal> or <literal>~</literal>) can be stored as well.
   (Certainty indicators are ignored by all the built-in operators, however.)
   <xref linkend="seg-repr-table"/> gives an overview of allowed
   representations; <xref linkend="seg-input-examples"/> shows some
   examples.
  </para>

  <para>
   In <xref linkend="seg-repr-table"/>, <replaceable>x</replaceable>, <replaceable>y</replaceable>, and
   <replaceable>delta</replaceable> denote
   floating-point numbers.  <replaceable>x</replaceable> and <replaceable>y</replaceable>, but
   not <replaceable>delta</replaceable>, can be preceded by a certainty indicator.
  </para>

  <table id="seg-repr-table">
   <title><type>seg</type> External Representations</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><literal><replaceable>x</replaceable></literal></entry>
      <entry>Single value (zero-length interval)
      </entry>
     </row>
     <row>
      <entry><literal><replaceable>x</replaceable>