root/traduc/branches/bv747/manuel/ref/create_cast.sgml

<!-- $Header: /var/lib/cvs/pgsql-fr/sgml/ref/create_cast.sgml,v 1.7.2.2 2005/06/13 06:24:08 guillaume Exp $ -->

<refentry id="SQL-CREATECAST">
 <refmeta>
  <refentrytitle id="SQL-CREATECAST-TITLE">CREATE CAST</refentrytitle>
  <refmiscinfo>SQL - Instructions du langage</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE CAST</refname>
  <refpurpose>définit une nouvelle conversion</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createcast">
  <primary>CREATE CAST</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE CAST (<replaceable>typesource</replaceable> AS <replaceable>typecible</replaceable>)
    WITH FUNCTION <replaceable>nomfonction</replaceable> (<replaceable>argtype</replaceable>)
    [ AS ASSIGNMENT | AS IMPLICIT ]

CREATE CAST (<replaceable>typesource</replaceable> AS <replaceable>typecible</replaceable>)
    WITHOUT FUNCTION
    [ AS ASSIGNMENT | AS IMPLICIT ]
</synopsis>
 </refsynopsisdiv>

 <refsect1 id="sql-createcast-description">
  <title>Description</title>

  <para>
   <command>CREATE CAST</command> définit une nouvelle conversion. Une
   conversion spécifie la façon de réaliser une conversion entre deux types de
   données. Par exemple,
<programlisting>
SELECT CAST(42 AS text);
</programlisting>
   convertit la constante entière 42 dans le type <type>text</type> en appelant
   une fonction précédemment spécifiée, dans ce cas <literal>text(int4)</>. (Si
   aucune conversion convenable n'a été définie, la conversion échoue.)
  </para>

  <para>
   Deux types pourraient être <firstterm>compatibles binairement</firstterm>,
   ce qui signifie qu'ils peuvent être convertis dans l'autre type
   <quote>librement</quote> sans appeler de fonction. Ceci requiert que les
   valeurs correspondantes utilisent la même représentation interne. En fait,
   les types <type>text</type> et <type>varchar</type> sont compatibles
   binairement.
  </para>

  <para>
   Par défaut, une conversion peut être appelée par une demande explicite.
   Voici des constructions explicites&nbsp;: <literal>CAST(<replaceable>x</> AS
   <replaceable>nomtype</>)</literal>,
   <replaceable>x</><literal>::</><replaceable>nomtype</> ou
   <replaceable>nomtype</>(<replaceable>x</>).
  </para>

  <para>
   Si la conversion est marquée <literal>AS ASSIGNMENT</>, alors elle peut être
   appelée implicitement lors de l'affectation d'une valeur à une colonne du
   type de données cible. Par exemple, en supposant que
   <literal>foo.f1</literal> est une colonne de type <type>text</type>, alors
<programlisting>
INSERT INTO foo (f1) VALUES (42);
</programlisting>
   sera autorisé si la conversion du type <type>integer</type> vers le type
   <type>text</type> est indiquée <literal>AS ASSIGNMENT</>, sinon cela sera
   interdit. (Nous utilisons généralement le terme de <firstterm>conversion
   d'affectation</firstterm> pour décrire ce type de conversion.)
  </para>

  <para>
   Si la conversion est marquée <literal>AS IMPLICIT</>, alors elle peut être
   appelée implicitement dans tout contexte, que ce soit une affectation ou en
   interne dans une expression. Par exemple, comme <literal>||</> prend deux
   opérandes <type>text</>,
<programlisting>
SELECT 'L\'heure est ' || now();
</programlisting>
   sera autorisé seulement si la conversion du type <type>timestamp</> vers le
   type <type>text</type> est marquée <literal>AS IMPLICIT</>. Sinon, il sera
   nécessaire d'écrire explicitement la conversion, par exemple
<programlisting>
SELECT 'L\'heure est ' || CAST(now() AS text);
</programlisting>
   (Nous utilisons généralement le terme de <firstterm>conversion
   implicite</firstterm> pour décrire ce type de conversion.)
  </para>

  <para>
   Il est conseillé d'être conservateur sur le marquage des conversions comme 
   implicites. Une surabondance de chemins de conversions implicites peut faire
   en sorte que <productname>PostgreSQL</productname> effectue des choix
   surprenant suite à l'interprétations des commandes ou soit complètement
   incapable de résoudre les commandes parce qu'il existe plusieurs
   interprétations possibles. Une bonne règle à suivre est de réaliser une
   conversion implicite appelable seulement pour les transformations préservant
   l'information entre les types dans la même catégorie générale. Par exemple,
   la conversion entre <type>int2</type> et <type>int4</type> peut être
   raisonnablement implicite mais celle entre <type>float8</type> et
   <type>int4</type> devraient être probablement uniquement sur affectation. Les
   conversions entre catégorie, tels que de <type>text</> vers <type>int4</>,
   sont bien préférables en mode explicite seul.
  </para>

  <para>
   Pour être capable de créer une conversion, vous devez être le propriétaire
   du type source ou destination. Pour créer une conversion compatible
   binairement, vous devez être superutilisateur. (Cette restriction est faite
   parce qu'une conversion compatible binairement erronée peut facilement causer
   un arrêt brutal du serveur.)
  </para>
 </refsect1>

 <refsect1>
  <title>Paramètres</title>

   <variablelist>
    <varlistentry>
     <term><replaceable>typesource</replaceable></term>

     <listitem>
      <para>
       Le nom du type de données source dans la conversion.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>typecible</replaceable></term>

     <listitem>
      <para>
       Le nom du type de données cible dans la conversion.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>    
     <term><replaceable>nomfonction</replaceable>
      (<replaceable>type_argument</replaceable>)</term>

     <listitem>
      <para>
       La fonction utilisée pour effectuer la conversion. Le nom de la fonction
       pourrait être qualifié du nom du schéma. Si ce n'est pas le cas, la
       fonction sera recherchée dans le chemin. Le type d'argument doit être
       identique au type source, le type de données résultat doit correspondre
       au type cible de la conversion.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>WITHOUT FUNCTION</literal></term>

     <listitem>
      <para>
       Indique que le type source et le type cible sont compatibles binairement,
       donc aucune fonction n'est requise pour effectuer la conversion.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>AS ASSIGNMENT</literal></term>

     <listitem>
      <para>
       Indique que la conversion pourrait être appelée implicitement dans les
       contextes d'affectation.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>AS IMPLICIT</literal></term>

     <listitem>
      <para>
       Indique que la conversion pourrait être appelée implicitement dans tout
       contexte.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

 </refsect1>

 <refsect1 id="sql-createcast-notes">
  <title>Notes</title>

  <para>
   Utilisez <command>DROP CAST</command> pour supprimer les conversions
   définies par l'utilisateur.
  </para>

  <para>
   Rappelez-vous que si vous souhaitez être capable de convertir les types dans
   les deux sens, vous devez déclarer explicitement les deux sens.
  </para>

  <para>
   Avant <productname>PostgreSQL</> 7.3, chaque fonction qui avait le même nom
   qu'un type de données, envoyait ce type de données et prenait un argument
   d'un autre type était automatiquement détectée comme une fonction de
   conversion. Ceci a été abandonné lors de l'introduction des schémas et pour
   être capable de représenter des conversions compatibles binairement dans les
   catalogues système. (Les fonctions de conversion intégrées suivent toujours
   le même schéma de nommage mais elle doivent maintenant être données comme
   conversion dans le catalogue système <literal>pg_cast</>.)
  </para>
 </refsect1>


 <refsect1 id="sql-createcast-examples">
  <title>Exemples</title>

  <para>
   Pour créer une conversion du type <type>text</type> vers le type
   <type>int4</type> en utilisant la fonction
   <literal>int4(text)</literal>&nbsp;:
<programlisting>
CREATE CAST (text AS int4) WITH FUNCTION int4(text);
</programlisting>
   (Cette conversion est déjà prédéfinie dans le système.)
  </para>
 </refsect1>

 
 <refsect1 id="sql-createcast-compat">
  <title>Compatibilité</title>

  <para>
   La commande <command>CREATE CAST</command> est conforme à SQL99 sauf que
   SQL99 ne parle pas des types compatibles binairement. <literal>AS IMPLICIT</>
   est aussi une extension <productname>PostgreSQL</productname>.
  </para>
 </refsect1>


 <refsect1 id="sql-createcast-seealso">
  <title>Voir aussi</title>

  <para>
   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">,
   <xref linkend="sql-createtype" endterm="sql-createtype-title">,
   <xref linkend="sql-dropcast" endterm="sql-dropcast-title">
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->