head	1.9;
access;
symbols
	REL9_0_0:1.6.8.3
	REL9_1_ALPHA1:1.9
	REL9_0_RC1:1.6.8.3
	REL9_0_BETA4:1.6.8.1
	REL9_0_STABLE:1.6.0.8
	REL9_0_BETA3:1.6
	REL9_0_BETA2:1.6
	REL8_3_11:1.4
	REL8_4_4:1.5.2.1
	REL9_0_BETA1:1.6
	REL9_0_ALPHA5_BRANCH:1.6.0.6
	REL9_0_ALPHA5:1.6
	REL8_3_10:1.4
	REL8_4_3:1.5.2.1
	REL9_0_ALPHA4:1.6
	REL9_0_ALPHA4_BRANCH:1.6.0.4
	REL8_5_ALPHA3:1.6
	REL8_5_ALPHA3_BRANCH:1.6.0.2
	REL8_3_9:1.4
	REL8_4_2:1.5.2.1
	REL8_5_ALPHA2:1.5
	REL8_5_ALPHA2_BRANCH:1.5.0.6
	REL8_3_8:1.4
	REL8_4_1:1.5
	REL8_5_ALPHA1:1.5
	REL8_5_ALPHA1_BRANCH:1.5.0.4
	REL8_4_STABLE:1.5.0.2
	REL8_4_0:1.5
	REL8_4_RC2:1.5
	REL8_4_RC1:1.5
	REL8_4_BETA2:1.4
	REL8_4_BETA1:1.4
	REL8_3_7:1.4
	REL8_3_6:1.4
	REL8_3_5:1.4
	REL8_3_4:1.4
	REL8_3_3:1.4
	REL8_3_2:1.4
	REL8_3_1:1.4
	REL8_3_STABLE:1.4.0.2
	REL8_3_0:1.4
	REL8_3_RC2:1.4
	REL8_3_RC1:1.4
	REL8_3_BETA4:1.2
	REL8_3_BETA3:1.2;
locks; strict;
comment	@# @;


1.9
date	2010.08.17.04.37.21;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2010.08.10.20.42.01;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.6;

1.6
date	2009.12.08.20.08.30;	author mha;	state Exp;
branches
	1.6.8.1;
next	1.5;

1.5
date	2009.05.18.11.08.24;	author petere;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	2007.12.06.04.12.10;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2007.12.03.23.49.51;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2007.11.11.14.23.18;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.5.2.1
date	2009.12.08.20.08.37;	author mha;	state Exp;
branches;
next	;

1.6.8.1
date	2010.07.29.19.34.37;	author petere;	state Exp;
branches;
next	1.6.8.2;

1.6.8.2
date	2010.08.10.20.42.02;	author petere;	state Exp;
branches;
next	1.6.8.3;

1.6.8.3
date	2010.08.17.04.37.18;	author petere;	state Exp;
branches;
next	;


desc
@@


1.9
log
@Spell and markup checking
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.8 2010/08/10 20:42:01 petere Exp $ -->

<sect1 id="seg">
 <title>seg</title>

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

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

 <sect2>
  <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=> 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=> select '6.25 .. 6.50'::seg as "pH";
          pH
------------
6.25 .. 6.50
(1 row)
</screen>
  </para>
 </sect2>

 <sect2>
  <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> and <literal>~</literal>) can be stored as well.
   (Certainty indicators are ignored by all the built-in operators, however.)
   <xref linkend="seg-repr-table"> gives on overview over the allowed
   representations; <xref linkend="seg-input-examples"> shows some
   examples.
  </para>

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

  <table id="seg-repr-table">
   <title><type>seg</> external representations</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><literal><replaceable>x</></literal></entry>
      <entry>Single value (zero-length interval)
      </entry>
     </row>
     <row>
      <entry><literal><replaceable>x</> .. <replaceable>y</></literal></entry>
      <entry>Interval from <replaceable>x</> to <replaceable>y</>
      </entry>
     </row>
     <row>
      <entry><literal><replaceable>x</> (+-) <replaceable>delta</></literal></entry>
      <entry>Interval from <replaceable>x</> - <replaceable>delta</> to
      <replaceable>x</> + <replaceable>delta</>
      </entry>
     </row>
     <row>
      <entry><literal><replaceable>x</> ..</literal></entry>
      <entry>Open interval with lower bound <replaceable>x</>
      </entry>
     </row>
     <row>
      <entry><literal>.. <replaceable>x</></literal></entry>
      <entry>Open interval with upper bound <replaceable>x</>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <table id="seg-input-examples">
   <title>Examples of valid <type>seg</> input</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><literal>5.0</literal></entry>
      <entry>
       Creates a zero-length segment (a point, if you will)
      </entry>
     </row>
     <row>
      <entry><literal>~5.0</literal></entry>
      <entry>
       Creates a zero-length segment and records
       <literal>~</> in the data.  <literal>~</literal> is ignored
       by <type>seg</> operations, but
       is preserved as a comment.
      </entry>
     </row>
     <row>
      <entry><literal>&lt;5.0</literal></entry>
      <entry>
       Creates a point at 5.0.  <literal>&lt;</literal> is ignored but
       is preserved as a comment.
      </entry>
     </row>
     <row>
      <entry><literal>&gt;5.0</literal></entry>
      <entry>
       Creates a point at 5.0.  <literal>&gt;</literal> is ignored but
       is preserved as a comment.
      </entry>
     </row>
     <row>
      <entry><literal>5(+-)0.3</literal></entry>
      <entry>
        Creates an interval <literal>4.7 .. 5.3</literal>.
        Note that the <literal>(+-)</> notation isn't preserved.
      </entry>
     </row>
     <row>
      <entry><literal>50 .. </literal></entry>
      <entry>Everything that is greater than or equal to 50</entry>
     </row>
     <row>
      <entry><literal>.. 0</literal></entry>
      <entry>Everything that is less than or equal to 0</entry>
     </row>
     <row>
      <entry><literal>1.5e-2 .. 2E-2 </literal></entry>
      <entry>Creates an interval <literal>0.015 .. 0.02</literal></entry>
     </row>
     <row>
      <entry><literal>1 ... 2</literal></entry>
      <entry>
       The same as <literal>1...2</literal>, or <literal>1 .. 2</literal>,
       or <literal>1..2</literal>
       (spaces around the range operator are ignored)
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   Because <literal>...</> is widely used in data sources, it is allowed
   as an alternative spelling of <literal>..</>.  Unfortunately, this
   creates a parsing ambiguity: it is not clear whether the upper bound
   in <literal>0...23</> is meant to be <literal>23</> or <literal>0.23</>.
   This is resolved by requiring at least one digit before the decimal
   point in all numbers in <type>seg</> input.
  </para>

  <para>
   As a sanity check, <type>seg</> rejects intervals with the lower bound
   greater than the upper, for example <literal>5 .. 2</>.
  </para>

 </sect2>

 <sect2>
  <title>Precision</title>

  <para>
   <type>seg</> values are stored internally as pairs of 32-bit floating point
   numbers. This means that numbers with more than 7 significant digits
   will be truncated.
  </para>

  <para>
   Numbers with 7 or fewer significant digits retain their
   original precision. That is, if your query returns 0.00, you will be
   sure that the trailing zeroes are not the artifacts of formatting: they
   reflect the precision of the original data. The number of leading
   zeroes does not affect precision: the value 0.0067 is considered to
   have just 2 significant digits.
  </para>
 </sect2>

 <sect2>
  <title>Usage</title>

  <para>
   The <filename>seg</> module includes a GiST index operator class for
   <type>seg</> values.
   The operators supported by the GiST operator class are shown in <xref linkend="seg-gist-operators">.
  </para>

  <table id="seg-gist-operators">
   <title>Seg GiST operators</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Operator</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>[a, b] &lt;&lt; [c, d]</literal></entry>
      <entry>[a, b] is entirely to the left of [c, d].  That is, [a,
       b] &lt;&lt; [c, d] is true if b &lt; c and false otherwise.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &gt;&gt; [c, d]</literal></entry>
      <entry>[a, b] is entirely to the right of [c, d].  That is, [a,
       b] &gt;&gt; [c, d] is true if a &gt; d and false otherwise.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&lt; [c, d]</literal></entry>
      <entry>Overlaps or is left of &mdash; This might be better read
       as <quote>does not extend to right of</quote>.  It is true when
       b &lt;= d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&gt; [c, d]</literal></entry>
      <entry>Overlaps or is right of &mdash; This might be better read
       as <quote>does not extend to left of</quote>.  It is true when
       a &gt;= c.</entry>
     </row>

     <row>
      <entry><literal>[a, b] = [c, d]</literal></entry>
      <entry>Same as &mdash; The segments [a, b] and [c, d] are
       identical, that is, a = c and b = d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&amp; [c, d]</literal></entry>
      <entry>The segments [a, b] and [c, d] overlap.</entry>
     </row>

     <row>
      <entry><literal>[a, b] @@&gt; [c, d]</literal></entry>
      <entry>The segment [a, b] contains the segment [c, d], that is,
       a &lt;= c and b &gt;= d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &lt;@@ [c, d]</literal></entry>
      <entry>The segment [a, b] is contained in [c, d], that is, a
       &gt;= c and b &lt;= d.</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   (Before PostgreSQL 8.2, the containment operators <literal>@@&gt;</> and <literal>&lt;@@</> were
   respectively called <literal>@@</> and <literal>~</>.  These names are still available, but are
   deprecated and will eventually be retired.  Notice that the old names
   are reversed from the convention formerly followed by the core geometric
   data types!)
  </para>

  <para>
   The standard B-tree operators are also provided, for example

  <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Operator</entry>
       <entry>Description</entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry><literal>[a, b] &lt; [c, d]</literal></entry>
       <entry>Less than</entry>
      </row>

      <row>
       <entry><literal>[a, b] &gt; [c, d]</literal></entry>
       <entry>Greater than</entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>

   These operators do not make a lot of sense for any practical
   purpose but sorting. These operators first compare (a) to (c),
   and if these are equal, compare (b) to (d). That results in
   reasonably good sorting in most cases, which is useful if
   you want to use ORDER BY with this type.
  </para>
 </sect2>

 <sect2>
  <title>Notes</title>

  <para>
   For examples of usage, see the regression test <filename>sql/seg.sql</>.
  </para>

  <para>
   The mechanism that converts <literal>(+-)</> to regular ranges
   isn't completely accurate in determining the number of significant digits
   for the boundaries.  For example, it adds an extra digit to the lower
   boundary if the resulting interval includes a power of ten:

<screen>
postgres=> select '10(+-)1'::seg as seg;
      seg
---------
9.0 .. 11             -- should be: 9 .. 11
</screen>
  </para>

  <para>
   The performance of an R-tree index can largely depend on the initial
   order of input values. It may be very helpful to sort the input table
   on the <type>seg</> column; see the script <filename>sort-segments.pl</>
   for an example.
  </para>
 </sect2>

 <sect2>
  <title>Credits</title>

  <para>
   Original author: Gene Selkov, Jr. <email>selkovjr@@mcs.anl.gov</email>,
   Mathematics and Computer Science Division, Argonne National Laboratory.
  </para>

  <para>
   My thanks are primarily to Prof. Joe Hellerstein
   (<ulink url="http://db.cs.berkeley.edu/jmh/"></ulink>) for elucidating the
   gist of the GiST (<ulink url="http://gist.cs.berkeley.edu/"></ulink>). I am
   also grateful to all Postgres developers, present and past, for enabling
   myself to create my own world and live undisturbed in it. And I would like
   to acknowledge my gratitude to Argonne Lab and to the U.S. Department of
   Energy for the years of faithful support of my database research.
  </para>

 </sect2>

</sect1>
@


1.8
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.7 2010/07/29 19:34:40 petere Exp $ -->
d240 1
a240 1
   The operators supported by the GiST opclass are shown in <xref linkend="seg-gist-operators">.
d311 1
a311 1
   datatypes!)
@


1.7
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.6 2009/12/08 20:08:30 mha Exp $ -->
d89 3
d135 1
a135 1
  <table>
@


1.6
log
@Fix a couple of broken links to third-party sites.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.5 2009/05/18 11:08:24 petere Exp $ -->
d42 1
a42 1
  <programlisting>
d48 1
a48 1
  </programlisting>
d68 1
a68 1
   <programlisting>
d74 1
a74 1
   </programlisting>
d237 1
a237 1
   The operators supported by the GiST opclass include:
d240 62
a301 72
  <itemizedlist>
   <listitem>
    <programlisting>
[a, b] &lt;&lt; [c, d]        Is left of
    </programlisting>
    <para>
     [a, b] is entirely to the left of [c, d].  That is,
     [a, b] &lt;&lt; [c, d] is true if b &lt; c and false otherwise
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] &gt;&gt; [c, d]        Is right of
    </programlisting>
    <para>
     [a, b] is entirely to the right of [c, d].  That is,
     [a, b] &gt;&gt; [c, d] is true if a &gt; d and false otherwise
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] &amp;&lt; [c, d]        Overlaps or is left of
    </programlisting>
    <para>
     This might be better read as <quote>does not extend to right of</quote>.
     It is true when b &lt;= d.
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] &amp;&gt; [c, d]        Overlaps or is right of
    </programlisting>
    <para>
     This might be better read as <quote>does not extend to left of</quote>.
     It is true when a &gt;= c.
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] = [c, d]         Same as
    </programlisting>
    <para>
     The segments [a, b] and [c, d] are identical, that is, a = c and b = d
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] &amp;&amp; [c, d]        Overlaps
    </programlisting>
    <para>
     The segments [a, b] and [c, d] overlap.
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] @@&gt; [c, d]        Contains
    </programlisting>
    <para>
     The segment [a, b] contains the segment [c, d], that is,
     a &lt;= c and b &gt;= d
    </para>
   </listitem>
   <listitem>
    <programlisting>
[a, b] &lt;@@ [c, d]        Contained in
    </programlisting>
    <para>
     The segment [a, b] is contained in [c, d], that is,
     a &gt;= c and b &lt;= d
    </para>
   </listitem>
  </itemizedlist>
d304 2
a305 2
   (Before PostgreSQL 8.2, the containment operators @@&gt; and &lt;@@ were
   respectively called @@ and ~.  These names are still available, but are
d314 22
a335 4
  <programlisting>
[a, b] &lt; [c, d]                Less than
[a, b] &gt; [c, d]                Greater than
  </programlisting>
d358 1
a358 1
   <programlisting>
d363 1
a363 1
   </programlisting>
@


1.6.8.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.6 2009/12/08 20:08:30 mha Exp $ -->
d42 1
a42 1
<screen>
d48 1
a48 1
</screen>
d68 1
a68 1
<screen>
d74 1
a74 1
</screen>
d237 1
a237 1
   The operators supported by the GiST opclass are shown in <xref linkend="seg-gist-operators">.
d240 72
a311 62
  <table id="seg-gist-operators">
   <title>Seg GiST operators</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Operator</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>[a, b] &lt;&lt; [c, d]</literal></entry>
      <entry>[a, b] is entirely to the left of [c, d].  That is, [a,
       b] &lt;&lt; [c, d] is true if b &lt; c and false otherwise.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &gt;&gt; [c, d]</literal></entry>
      <entry>[a, b] is entirely to the right of [c, d].  That is, [a,
       b] &gt;&gt; [c, d] is true if a &gt; d and false otherwise.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&lt; [c, d]</literal></entry>
      <entry>Overlaps or is left of &mdash; This might be better read
       as <quote>does not extend to right of</quote>.  It is true when
       b &lt;= d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&gt; [c, d]</literal></entry>
      <entry>Overlaps or is right of &mdash; This might be better read
       as <quote>does not extend to left of</quote>.  It is true when
       a &gt;= c.</entry>
     </row>

     <row>
      <entry><literal>[a, b] = [c, d]</literal></entry>
      <entry>Same as &mdash; The segments [a, b] and [c, d] are
       identical, that is, a = c and b = d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &amp;&amp; [c, d]</literal></entry>
      <entry>The segments [a, b] and [c, d] overlap.</entry>
     </row>

     <row>
      <entry><literal>[a, b] @@&gt; [c, d]</literal></entry>
      <entry>The segment [a, b] contains the segment [c, d], that is,
       a &lt;= c and b &gt;= d.</entry>
     </row>

     <row>
      <entry><literal>[a, b] &lt;@@ [c, d]</literal></entry>
      <entry>The segment [a, b] is contained in [c, d], that is, a
       &gt;= c and b &lt;= d.</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
d314 2
a315 2
   (Before PostgreSQL 8.2, the containment operators <literal>@@&gt;</> and <literal>&lt;@@</> were
   respectively called <literal>@@</> and <literal>~</>.  These names are still available, but are
d324 4
a327 22
  <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Operator</entry>
       <entry>Description</entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry><literal>[a, b] &lt; [c, d]</literal></entry>
       <entry>Less than</entry>
      </row>

      <row>
       <entry><literal>[a, b] &gt; [c, d]</literal></entry>
       <entry>Greater than</entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
d350 1
a350 1
<screen>
d355 1
a355 1
</screen>
@


1.6.8.2
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.6.8.1 2010/07/29 19:34:37 petere Exp $ -->
a88 3
   <xref linkend="seg-repr-table"> gives on overview over the allowed
   representations; <xref linkend="seg-input-examples"> shows some
   examples.
d132 1
a132 1
  <table id="seg-input-examples">
@


1.6.8.3
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.6.8.2 2010/08/10 20:42:02 petere Exp $ -->
d240 1
a240 1
   The operators supported by the GiST operator class are shown in <xref linkend="seg-gist-operators">.
d311 1
a311 1
   data types!)
@


1.5
log
@Refer to tables by id, not by "the following table", because tables are in
theory floating elements.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.4 2007/12/06 04:12:10 tgl Exp $ -->
d376 1
a376 1
   (<ulink url="http://db.cs.berkeley.edu/~jmh/"></ulink>) for elucidating the
@


1.5.2.1
log
@Fix a couple of broken links to third-party sites.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/seg.sgml,v 1.5 2009/05/18 11:08:24 petere Exp $ -->
d376 1
a376 1
   (<ulink url="http://db.cs.berkeley.edu/jmh/"></ulink>) for elucidating the
@


1.4
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d92 1
a92 1
   In the following table, <replaceable>x</>, <replaceable>y</>, and
d95 1
a95 1
   not <replaceable>delta</>, can be preceded by a certainty indicator:
d98 1
a98 1
  <table>
@


1.3
log
@Entity-ify a passel of & < > characters.  Per gripe from Devrim.
@
text
@d1 1
d5 1
a5 1
 
d11 4
a14 3
  The <literal>seg</literal> module contains the code for the user-defined 
  type, <literal>SEG</literal>, representing laboratory measurements as 
  floating point intervals. 
d16 1
a16 1
 
d19 1
d28 1
d34 1
d41 1
a41 1
  </para>
d43 1
a43 1
test=> select 6.50 as "pH";
d49 1
a49 1
  <para>
d58 1
d62 1
a62 1
   a sense that each data element records its own precision.
d64 1
d67 2
a68 2
  </para>
  <programlisting>
d74 2
a75 1
  </programlisting>
d80 1
d83 6
a88 3
   floating point numbers joined by the range operator ('..' or '...'). 
   Optional certainty indicators (&lt;, &gt; and ~) are ignored by the internal 
   logics, but are retained in the data.
d90 8
a97 1
  
d99 1
a99 1
   <title>Rules</title>
d103 3
a105 2
      <entry>rule 1</entry>
      <entry>seg -&gt; boundary PLUMIN deviation</entry>
d108 3
a110 2
      <entry>rule 2</entry>
      <entry>seg -&gt; boundary RANGE boundary</entry>
d113 4
a116 2
      <entry>rule 3</entry>
      <entry>seg -&gt; boundary RANGE</entry>
d119 3
a121 2
      <entry>rule 4</entry>
      <entry>seg -&gt; RANGE boundary</entry>
d124 3
a126 14
      <entry>rule 5</entry>
      <entry>seg -&gt; boundary</entry>
     </row>
     <row>
      <entry>rule 6</entry>
      <entry>boundary -&gt; FLOAT</entry>
     </row>
     <row>
      <entry>rule 7</entry>
      <entry>boundary -&gt; EXTENSION FLOAT</entry>
     </row>
     <row>
      <entry>rule 8</entry>
      <entry>deviation -&gt; FLOAT</entry>
d133 1
a133 1
   <title>Tokens</title>
d137 1
a137 33
      <entry>RANGE</entry>
      <entry>(\.\.)(\.)?</entry>
     </row>
     <row>
      <entry>PLUMIN</entry>
      <entry>\'\+\-\'</entry>
     </row>
     <row>
      <entry>integer</entry>
      <entry>[+-]?[0-9]+</entry>
     </row>
     <row>
      <entry>real</entry>
      <entry>[+-]?[0-9]+\.[0-9]+</entry>
     </row>
     <row>
      <entry>FLOAT</entry>
      <entry>({integer}|{real})([eE]{integer})?</entry>
     </row>
     <row>
      <entry>EXTENSION</entry>
      <entry>[&lt;&gt;~]</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 
  <table>
   <title>Examples of valid <literal>SEG</literal> representations</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>Any number</entry>
d139 1
a139 2
       (rules 5,6) -- creates a zero-length segment (a point,
       if you will)
d143 1
a143 1
      <entry>~5.0</entry>
d145 4
a148 4
       (rules 5,7) -- creates a zero-length segment AND records 
       '~' in the data. This notation reads 'approximately 5.0', 
       but its meaning is not recognized by the code. It is ignored 
       until you get the value back. View it is a short-hand comment.
d150 1
a150 1
     </row> 
d152 1
a152 1
      <entry>&lt;5.0</entry>
d154 2
a155 2
       (rules 5,7) -- creates a point at 5.0; '&lt;' is ignored but 
       is preserved as a comment
d159 1
a159 1
      <entry>&gt;5.0</entry>
d161 2
a162 2
       (rules 5,7) -- creates a point at 5.0; '&gt;' is ignored but
       is preserved as a comment
d166 1
a166 1
      <entry><para>5(+-)0.3</para><para>5'+-'0.3</para></entry>
d168 2
a169 19
       <para>
        (rules 1,8) -- creates an interval '4.7..5.3'. As of this 
        writing (02/09/2000), this mechanism isn't completely accurate 
        in determining the number of significant digits for the 
        boundaries. For example, it adds an extra digit to the lower
        boundary if the resulting interval includes a power of ten:
       </para>
       <programlisting>
postgres=> select '10(+-)1'::seg as seg;
      seg
---------
9.0 .. 11 -- should be: 9 .. 11
       </programlisting>
       <para>
        Also, the (+-) notation is not preserved: 'a(+-)b' will 
        always be returned as '(a-b) .. (a+b)'. The purpose of this 
        notation is to allow input from certain data sources without 
        conversion.
       </para>
d173 2
a174 2
      <entry>50 .. </entry>
      <entry>(rule 3) -- everything that is greater than or equal to 50</entry>
d177 2
a178 2
      <entry>.. 0</entry>
      <entry>(rule 4) -- everything that is less than or equal to 0</entry>
d181 2
a182 2
      <entry>1.5e-2 .. 2E-2 </entry>
      <entry>(rule 2) -- creates an interval (0.015 .. 0.02)</entry>
d185 1
a185 1
      <entry>1 ... 2</entry>
d187 3
a189 6
       The same as 1...2, or 1 .. 2, or 1..2 (space is ignored).
       Because of the widespread use of '...' in the data sources,
       I decided to stick to is as a range operator. This, and
       also the fact that the white space around the range operator
       is ignored, creates a parsing conflict with numeric constants 
       starting with a decimal point.
a195 19
  <table>
   <title>Examples</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>.1e7</entry>
      <entry>should be: 0.1e7</entry>
     </row>
     <row>
      <entry>.1 .. .2</entry>
      <entry>should be: 0.1 .. 0.2</entry>
     </row>
     <row>
      <entry>2.4 E4</entry>
      <entry>should be: 2.4E4</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
d197 11
a207 2
   The following, although it is not a syntax error, is disallowed to improve
   the sanity of the data:
d209 1
a209 11
  <table>
   <title></title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>5 .. 2</entry>
      <entry>should be: 2 .. 5</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
d214 1
d216 2
a217 2
   The segments are stored internally as pairs of 32-bit floating point
   numbers. It means that the numbers with more than 7 significant digits
d220 1
d222 1
a222 1
   The numbers with less than or exactly 7 significant digits retain their
d233 1
d235 3
a237 12
   The access method for SEG is a GiST index (gist_seg_ops), which is a
   generalization of R-tree. GiSTs allow the postgres implementation of
   R-tree, originally encoded to support 2-D geometric types such as
   boxes and polygons, to be used with any data type whose data domain
   can be partitioned using the concepts of containment, intersection and
   equality. In other words, everything that can intersect or contain
   its own kind can be indexed with a GiST. That includes, among other
   things, all geometric data types, regardless of their dimensionality
   (see also contrib/cube).
  </para>
  <para>
   The operators supported by the GiST access method include:
d239 1
d246 1
a246 2
     The left operand, [a, b], occurs entirely to the left of the
     right operand, [c, d], on the axis (-inf, inf). It means,
d255 2
a256 2
        [a, b] is occurs entirely to the right of [c, d]. 
        [a, b] &gt;&gt; [c, d] is true if a &gt; d and false otherwise
d264 2
a265 2
        This might be better read as "does not extend to right of".
        It is true when b &lt;= d.
d273 2
a274 2
        This might be better read as "does not extend to left of".
        It is true when a &gt;= c.
d279 1
a279 1
[a, b] = [c, d]                Same as
d282 1
a282 2
        The segments [a, b] and [c, d] are identical, that is, a == b
        and c == d
d290 1
a290 1
        The segments [a, b] and [c, d] overlap.
d295 1
a295 1
[a, b] @@&gt; [c, d]                Contains
d298 2
a299 2
        The segment [a, b] contains the segment [c, d], that is, 
        a &lt;= c and b &gt;= d
d304 1
a304 1
[a, b] &lt;@@ [c, d]                Contained in
d307 2
a308 2
        The segment [a, b] is contained in [c, d], that is, 
        a &gt;= c and b &lt;= d
d312 1
d320 1
d322 1
a322 7
   Although the mnemonics of the following operators is questionable, I
   preserved them to maintain visual consistency with other geometric
   data types defined in Postgres.
  </para>
  <para>
   Other operators:
  </para>
d328 1
a328 1
  <para>
d331 1
a331 1
   and if these are equal, compare (b) to (d). That accounts for
d333 1
a333 1
   you want to use ORDER BY with this type
d335 4
d341 1
a341 5
   There are a few other potentially useful functions defined in seg.c 
   that vanished from the schema because I stopped using them. Some of 
   these were meant to support type casting. Let me know if I was wrong: 
   I will then add them back to the schema. I would also appreciate 
   other ideas that would enhance the type and make it more useful.
d343 1
d345 11
a355 1
   For examples of usage, see sql/seg.sql
d357 1
d359 1
a359 1
   NOTE: The performance of an R-tree index can largely depend on the
d361 2
a362 1
   on the SEG column (see the script sort-segments.pl for an example)
d368 6
d376 5
a380 5
   (<ulink url="http://db.cs.berkeley.edu/~jmh/"></ulink>) for elucidating the 
   gist of the GiST (<ulink url="http://gist.cs.berkeley.edu/"></ulink>). I am 
   also grateful to all postgres developers, present and past, for enabling 
   myself to create my own world and live undisturbed in it. And I would like 
   to acknowledge my gratitude to Argonne Lab and to the U.S. Department of 
d383 1
a383 12
  <programlisting>
   Gene Selkov, Jr.
   Computational Scientist
   Mathematics and Computer Science Division
   Argonne National Laboratory
   9700 S Cass Ave.
   Building 221
   Argonne, IL 60439-4844
  </programlisting>
  <para>
   <email>selkovjr@@mcs.anl.gov</email>
  </para>
a386 1

@


1.2
log
@Remove tabs from SGML files.
@
text
@d75 1
a75 1
   Optional certainty indicators (<, > and ~) are ignored by the internal 
d85 1
a85 1
      <entry>seg -> boundary PLUMIN deviation</entry>
d89 1
a89 1
      <entry>seg -> boundary RANGE boundary</entry>
d93 1
a93 1
      <entry>seg -> boundary RANGE</entry>
d97 1
a97 1
      <entry>seg -> RANGE boundary</entry>
d101 1
a101 1
      <entry>seg -> boundary</entry>
d105 1
a105 1
      <entry>boundary -> FLOAT</entry>
d109 1
a109 1
      <entry>boundary -> EXTENSION FLOAT</entry>
d113 1
a113 1
      <entry>deviation -> FLOAT</entry>
d145 1
a145 1
      <entry>[<>~]</entry>
d172 1
a172 1
      <entry><5.0</entry>
d174 1
a174 1
       (rules 5,7) -- creates a point at 5.0; '<' is ignored but 
d179 1
a179 1
      <entry>>5.0</entry>
d181 1
a181 1
       (rules 5,7) -- creates a point at 5.0; '>' is ignored but
d308 1
a308 1
[a, b] << [c, d]        Is left of
d313 1
a313 1
     [a, b] << [c, d] is true if b < c and false otherwise
d318 1
a318 1
[a, b] >> [c, d]        Is right of
d322 1
a322 1
        [a, b] >> [c, d] is true if a > d and false otherwise
d327 1
a327 1
[a, b] &< [c, d]        Overlaps or is left of
d331 1
a331 1
        It is true when b <= d.
d336 1
a336 1
[a, b] &> [c, d]        Overlaps or is right of
d340 1
a340 1
        It is true when a >= c.
d354 1
a354 1
[a, b] && [c, d]        Overlaps
d362 1
a362 1
[a, b] @@> [c, d]                Contains
d366 1
a366 1
        a <= c and b >= d
d371 1
a371 1
[a, b] <@@ [c, d]                Contained in
d375 1
a375 1
        a >= c and b <= d
d380 1
a380 1
   (Before PostgreSQL 8.2, the containment operators @@> and <@@ were
d396 2
a397 2
[a, b] < [c, d]                Less than
[a, b] > [c, d]                Greater than
@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d229 1
a229 1
       starting with a	decimal point.
d308 1
a308 1
[a, b] << [c, d]	Is left of
d318 1
a318 1
[a, b] >> [c, d]	Is right of
d321 2
a322 2
	[a, b] is occurs entirely to the right of [c, d]. 
	[a, b] >> [c, d] is true if a > d and false otherwise
d327 1
a327 1
[a, b] &< [c, d]	Overlaps or is left of
d330 2
a331 2
	This might be better read as "does not extend to right of".
	It is true when b <= d.
d336 1
a336 1
[a, b] &> [c, d]	Overlaps or is right of
d339 2
a340 2
	This might be better read as "does not extend to left of".
	It is true when a >= c.
d345 1
a345 1
[a, b] = [c, d]		Same as
d348 2
a349 2
	The segments [a, b] and [c, d] are identical, that is, a == b
	and c == d
d354 1
a354 1
[a, b] && [c, d]	Overlaps
d357 1
a357 1
	The segments [a, b] and [c, d] overlap.
d362 1
a362 1
[a, b] @@> [c, d]		Contains
d365 2
a366 2
	The segment [a, b] contains the segment [c, d], that is, 
	a <= c and b >= d
d371 1
a371 1
[a, b] <@@ [c, d]		Contained in
d374 2
a375 2
	The segment [a, b] is contained in [c, d], that is, 
	a >= c and b <= d
d396 2
a397 2
[a, b] < [c, d]		Less than
[a, b] > [c, d]		Greater than
@

