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

<sect1 id="cube" xreflabel="cube">
 <title>cube &mdash; a multi-dimensional cube data type</title>

 <indexterm zone="cube">
  <primary>cube (extension)</primary>
 </indexterm>

 <para>
  This module implements a data type <type>cube</type> for
  representing multidimensional cubes.
 </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="cube-syntax">
  <title>Syntax</title>

  <para>
   <xref linkend="cube-repr-table"/> shows the valid external
   representations for the <type>cube</type>
   type.  <replaceable>x</replaceable>, <replaceable>y</replaceable>, etc. denote
   floating-point numbers.
  </para>

  <table id="cube-repr-table">
   <title>Cube External Representations</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>External Syntax</entry>
      <entry>Meaning</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal><replaceable>x</replaceable></literal></entry>
      <entry>A one-dimensional point
       (or, zero-length one-dimensional interval)
      </entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x</replaceable>)</literal></entry>
      <entry>Same as above</entry>
     </row>
     <row>
      <entry><literal><replaceable>x1</replaceable>,<replaceable>x2</replaceable>,...,<replaceable>xn</replaceable></literal></entry>
      <entry>A point in n-dimensional space, represented internally as a
      zero-volume cube
      </entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x1</replaceable>,<replaceable>x2</replaceable>,...,<replaceable>xn</replaceable>)</literal></entry>
      <entry>Same as above</entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)</literal></entry>
      <entry>A one-dimensional interval starting at <replaceable>x</replaceable> and ending at <replaceable>y</replaceable> or vice versa; the
       order does not matter
      </entry>
     </row>
     <row>
      <entry><literal>[(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)]</literal></entry>
      <entry>Same as above</entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x1</replaceable>,...,<replaceable>xn</replaceable>),(<replaceable>y1</replaceable>,...,<replaceable>yn</replaceable>)</literal></entry>
      <entry>An n-dimensional cube represented by a pair of its diagonally
       opposite corners
      </entry>
     </row>
     <row>
      <entry><literal>[(<replaceable>x1</replaceable>,...,<replaceable>xn</replaceable>),(<replaceable>y1</replaceable>,...,<replaceable>yn</replaceable>)]</literal></entry>
      <entry>Same as above</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   It does not matter which order the opposite corners of a cube are
   entered in.  The <type>cube</type> functions
   automatically swap values if needed to create a uniform
   <quote>lower left &mdash; upper right</quote> internal representation.
   When the corners coincide, <type>cube</type> stores only one corner
   along with an <quote>is point</quote> flag to avoid wasting space.
  </para>

  <para>
   White space is ignored on input, so
   <literal>[(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)]</literal> is the same as
   <literal>[ ( <replaceable>x</replaceable> ), ( <replaceable>y</replaceable> ) ]</literal>.
  </para>
 </sect2>

 <sect2 id="cube-precision">
  <title>Precision</title>

  <para>
   Values are stored internally as 64-bit floating point numbers. This means
   that numbers with more than about 16 significant digits will be truncated.
  </para>
 </sect2>

 <sect2 id="cube-usage">
  <title>Usage</title>

  <para>
   <xref linkend="cube-operators-table"/> shows the specialized operators
   provided for type <type>cube</type>.
  </para>

  <table id="cube-operators-table">