root/traduc/trunk/postgresql/cube.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

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

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

 <para>
  Ce module code le type de données <type>cube</type> pour
  représenter des cubes à plusieurs dimensions.
 </para>

 <sect2>
  <title>Syntaxe</title>

  <para>
   Ce qui suit est un ensemble de représentations externes valides pour le
   type <type>cube</type>. <replaceable>x</replaceable>,
   <replaceable>y</replaceable>... sont des nombres en virgule
   flottante&nbsp;:
  </para>

  <table>
   <title>Représentations externes d'un cube</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><literal><replaceable>x</replaceable></literal></entry>
      <entry>point uni-dimensionnel (ou interval unidimensionnel de longueur
      nulle)
      </entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x</replaceable>)</literal></entry>
      <entry>Identique à ci-dessus</entry>
     </row>
     <row>
      <entry><literal><replaceable>x1</replaceable>,<replaceable>x2</replaceable>,...,<replaceable>xn</replaceable></literal></entry>
      <entry>Un point dans un espace à n dimensions, représenté en interne
       comme un cube de volume nul
      </entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x1</replaceable>,<replaceable>x2</replaceable>,...,<replaceable>xn</replaceable>)</literal></entry>
      <entry>Identique à ci-dessus</entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)</literal></entry>
      <entry>Interval uni-dimensionnel débutant à
      <replaceable>x</replaceable> et finissant à
      <replaceable>y</replaceable> ou vice-versa&nbsp;; l'ordre n'importe pas
      </entry>
     </row>
     <row>
      <entry><literal>[(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)]</literal></entry>
      <entry>Identique à ci-dessus</entry>
     </row>
     <row>
      <entry><literal>(<replaceable>x1</replaceable>,...,<replaceable>xn</replaceable>),(<replaceable>y1</replaceable>,...,<replaceable>yn</replaceable>)</literal></entry>
      <entry>Cube à n dimensions représenté par paires de coins diagonalement opposés
      </entry>
     </row>
     <row>
      <entry><literal>[(<replaceable>x1</replaceable>,...,<replaceable>xn</replaceable>),(<replaceable>y1</replaceable>,...,<replaceable>yn</replaceable>)]</literal></entry>
      <entry>Identique à ci-dessus</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   L'ordre de saisie des coins opposés d'un cube n'a aucune importance. 
   Les fonctions <type>cube</type> s'occupent de la bascule
   nécessaire à l'obtention d'une représentation uniforme
   <quote>bas gauche, haut droit</quote>.
  </para>

  <para>
   Les espaces sont ignorées, 
   <literal>[(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)]</literal>
   est donc identique à
   <literal>[ ( <replaceable>x</replaceable> ), ( <replaceable>y</replaceable> ) ]</literal>.
  </para>
 </sect2>

 <sect2>
  <title>Précision</title>

  <para>
   Les valeurs sont enregistrées en interne sous la forme de nombres en
   virgule flottante. Cela signifie que les nombres avec plus de 16 chiffres
   significatifs sont tronqués.
  </para>
 </sect2>

 <sect2>
  <title>Utilisation</title>

  <para>
   Le module <filename>cube</filename> inclut une classe d'opérateur pour
   index GiST pour les valeurs de type <type>cube</type>. Les opérateurs
   supportés par la classe d'opérateur GiST incluent&nbsp;:
  </para>

  <itemizedlist>
   <listitem>
    <programlisting>
a = b                  Identique à
    </programlisting>
    <para>
     Les cubes a et b sont identiques.
    </para>
   </listitem>
   <listitem>
    <programlisting>
a &amp;&amp; b                Recouvre
    </programlisting>
    <para>
     Les cubes a et b se chevauchent.
    </para>
   </listitem>
   <listitem>
    <programlisting>
a @&gt; b                Contient
    </programlisting>
    <para>
     Le cube a contient le cube b.
    </para>
   </listitem>
   <listitem>
  <programlisting>
a &lt;@ b                Contenu dans
  </programlisting>
    <para>
     Le cube a est contenu dans le cube b.
    </para>
   </listitem>
  </itemizedlist>

  <para>
    (Avant PostgreSQL 8.2, les opérateurs de contenance @&gt; et &lt;@ étaient
   appelés respectivement @ et ~. Ces noms sont toujours disponibles mais sont
   déclarés obsolètes et seront supprimés un jour. Les anciens noms
   sont inversés par rapport à la convention suivie par les types de données
   géométriques&nbsp;!)
  </para>

  <para>
   Les opérateurs du standard B-tree sont aussi fournis, par exemple&nbsp;:

  <programlisting>
[a, b] &lt; [c, d]                Plus petit que
[a, b] &gt; [c, d]                Plus grand que
  </programlisting>

   Ces opérateurs n'ont vraiment de sens que pour le tri.
   Ces opérateurs comparent en premier (a) à (c) et, s'ils sont égaux,
   comparent (b) à (d). Cela fait un bon tri dans la plupart des cas, ce qui
   permet d'utiliser ORDER BY avec ce type.
  </para>

  <para>
   Les fonctions suivantes sont disponibles&nbsp;:
  </para>

  <table>
   <title>Fonctions cube</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><literal>cube(float8) returns cube</literal></entry>
      <entry>Crée un cube uni-dimensionnel de coordonnées identiques.
       <literal>cube(1) == '(1)'</literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube(float8, float8) returns cube</literal></entry>
      <entry>Crée un cube uni-dimensionnel.
       <literal>cube(1,2) == '(1),(2)'</literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube(float8[]) returns cube</literal></entry>
      <entry>Crée un cube de volume nul en utilisant les coordonnées
       définies par le tableau.
       <literal>cube(ARRAY[1,2]) == '(1,2)'</literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube(float8[], float8[]) returns cube</literal></entry>
      <entry>Crée un cube avec les coordonnées haut droit et 
       bas gauche définies par deux tableaux de flottants, obligatoirement
       de même taille.
       <literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)'
       </literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube(cube, float8) returns cube</literal></entry>
      <entry>Construit un nouveau cube en ajoutant une dimension à un
       cube existant avec les mêmes valeurs pour les deux parties de la
       nouvelle coordonnée. Ceci est utile pour construire des cubes pièce
       par pièce à partir de valeurs calculées.
       <literal>cube('(1)',2) == '(1,2),(1,2)'</literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube(cube, float8, float8) returns cube</literal></entry>
      <entry>Crée un nouveau cube en ajoutant une dimension à un cube
       existant. Ceci est utile pour construire des cubes pièce par pièce à partir
       de valeurs calculées.
       <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal>
      </entry>
     </row>

     <row>
      <entry><literal>cube_dim(cube) returns int</literal></entry>
      <entry>Renvoie le nombre de dimensions du cube.
      </entry>
     </row>

     <row>
      <entry><literal>cube_ll_coord(cube, int) returns double </literal></entry>
      <entry>Renvoie la n-ième coordonnée pour le coin en bas à
       gauche d'un cube.
      </entry>
     </row>

    <row>
      <entry><literal>cube_ur_coord(cube, int) returns double
      </literal></entry>
      <entry>Renvoie la n-ième coordonnée pour le coin en haut à droite d'un
       cube.
      </entry>
     </row>

     <row>
      <entry><literal>cube_is_point(cube) returns bool</literal></entry>
      <entry>Renvoie true si un cube est aussi un point, c'est-à-dire si
       les deux coins de définition sont identiques.</entry>
     </row>

     <row>
      <entry><literal>cube_distance(cube, cube) returns double</literal></entry>
      <entry>Renvoie la distance entre deux cubes. Si les deux cubes sont des
       points, il s'agit de la fonction de distance habituelle.
      </entry>
     </row>

     <row>
      <entry><literal>cube_subset(cube, int[]) returns cube
      </literal></entry>
      <entry>Crée un nouveau cube à partir d'un cube existant en utilisant une
       liste d'index de dimension d'un tableau. Peut être utilisé pour
       trouver les coordonnées bas gauche et haut droit d'une
       dimension, par exemple&nbsp;:
       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'</literal>.
       Peut aussi être utilisé pour supprimer des dimensions, ou pour les
       réordonner, par exemple&nbsp;:
       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3,
       1, 1),(8, 7, 6, 6)'</literal>.
      </entry>
     </row>

     <row>
      <entry><literal>cube_union(cube, cube) returns cube</literal></entry>
      <entry>Réalise l'union de deux cubes.
      </entry>
     </row>

     <row>
      <entry><literal>cube_inter(cube, cube) returns cube</literal></entry>
      <entry>Réalise l'intersection de deux cubes.
      </entry>
     </row>

     <row>
      <entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry>
      <entry>Augmente la taille d'un cube suivant un rayon précisé
       dans au moins n dimensions. Si le rayon est négatif, la boîte est
       diminuée. C'est utile pour créer des boîtes limitantes autour d'un
       point dans le but de rechercher les points voisins. Toutes les
       dimensions définies sont modifiées de la valeur du rayon r.
       Les coordonnées bas gauche sont décrémentées de r et les coordonnées
       haut droit sont incrémentées de r. Si une coordonnée bas gauche est
       incrémentée au-delà de la valeur correspondante haut droit (ce qui ne
       peut arriver que lorsque r &lt; 0), les deux coordonnées sont
       positionnées à leur moyenne.  Si n est plus grand
       que le nombre de dimensions définies et que le cube est augmenté
       (r >= 0), alors 0 est utilisé comme base des coordonnées
       supplémentaires.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </sect2>

 <sect2>
  <title>Par défaut</title>

  <para>
   Le développeur pense que l'union&nbsp;:
  </para>
<programlisting>
select cube_union('(0,5,2),(2,3,1)', '0');
cube_union
-------------------
(0, 0, 0),(2, 5, 2)
(1 row)
</programlisting>

   <para>
    n'est pas en contradiction avec le bon sens. Pas plus que l'intersection
   </para>

<programlisting>
select cube_inter('(0,-1),(1,1)', '(-2),(2)');
cube_inter
-------------
(0, 0),(1, 0)
(1 row)
</programlisting>

   <para>
    Dans toutes les opérations binaires sur des boîtes de tailles différentes,
    l'auteur suppose que la plus petite est une projection cartésienne,
    c'est-à-dire qu'il y a des zéros à la place des coordonnées omises dans la représentation
    sous forme de chaîne. Les exemples ci-dessus sont équivalents à&nbsp;:
   </para>

<programlisting>
cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');
</programlisting>

   <para>
    Le prédicat de contenance suivant utilise la syntaxe en points alors qu'en
    fait, le second argument est représenté en interne par une boîte. Cette
    syntaxe rend inutile la définition du type point et des fonctions
    pour les prédicats (boîte,point).
   </para>

<programlisting>
select cube_contains('(0,0),(1,1)', '0.5,0.5');
cube_contains
--------------
t
(1 row)
</programlisting>
 </sect2>

 <sect2>
  <title>Notes</title>

  <para>
   Pour des exemples d'utilisation, voir les tests de régression
   <filename>sql/cube.sql</filename>.
  </para>

  <para>
   Pour éviter toute mauvaise utilisation, le nombre de dimensions des cubes
   est limité à 100. Cela se configure dans <filename>cubedata.h</filename>.
  </para>
 </sect2>

 <sect2>
  <title>Crédits</title>

  <para>
   Auteur d'origine&nbsp;: Gene Selkov, Jr. <email>selkovjr@mcs.anl.gov</email>,
   Mathematics and Computer Science Division, Argonne National Laboratory.
  </para>
 </sect2>
 
 <sect2>
  <title>Note de l'auteur</title>
  <para>
    Mes remerciements vont tout particulièrement au professeur Joe Hellerstein
   (<ulink url="http://db.cs.berkeley.edu/~jmh/"></ulink>) qui a su extraire 
   l'idée centrale de GiST (<ulink
   url="http://gist.cs.berkeley.edu/"></ulink>), et à son étudiant précédant,
   Andy Dong 
   (<ulink url="http://best.me.berkeley.edu/~adong/"></ulink>), pour son
   exemple rédigé dans Illustra. Mes remerciements vont également aux
   développeurs de PostgreSQL qui m'ont permis de créer mon propre monde
   et de pouvoir y vivre sans être dérangé. Toute ma gratitude aussi à
   Argonne Lab et au département américain de l'énergie pour les années de
   support dans mes recherches sur les bases de données.
  </para>

  <para>
   Des modifications mineures ont été effectuées sur ce module par Bruno Wolff
   III <email>bruno@wolff.to</email> en août/septembre 2002. Elles incluent
   la modification de la précision (de simple à double) et l'ajout de
   quelques nouvelles fonctions.
  </para>

  <para>
   Des mises à jour supplémentaires ont été réalisées par Joshua Reich
   <email>josh@root.net</email> en juillet 2006. Elles concernent
   l'ajout de <literal>cube(float8[], float8[])</literal> et le nettoyage du code pour
   utiliser le protocole d'appel V1 à la place de la forme V0 maintenant
   obsolète.
  </para>
 </sect2>

</sect1>