doc-fr/reference/misc/functions/pack.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0545e305cf06937b14b3f0694d6e716c9881ffd7 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.pack" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pack</refname>
  <refpurpose>Compacte des données dans une chaîne binaire</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>pack</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
  </methodsynopsis>
  <para>
   Compacte les arguments <parameter>args</parameter>
   dans une chaîne binaire, suivant le format <parameter>format</parameter>.
  </para>
  <para>
   Le concept vient du Perl et tout le formatage fonctionne de
   la même façon qu'en Perl, mais quelques formats manquent
   encore (comme "<literal>u</literal>").
  </para>
  <para>
   Notez que la distinction entre signé et non signé
   n'affecte que la fonction <function>unpack</function>, tandis que
   la fonction <function>pack</function> fournira le même
   résultat pour les deux formats.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       La &string; <parameter>format</parameter> consiste en des codes
       de format suivis par un argument répéteur optionnel. Le répéteur
       peut être soit une valeur entière, soit <literal>*</literal> pour
       une répétition jusqu'à la fin des données d'entrées. Pour a, A, h, H,
       le répéteur spécifie combien de caractères d'une donnée est pris, pour
       @, c'est la position absolue où l'on insère les prochaines données, pour
       tout le reste, le répéteur spécifie combien d'arguments de données sont
       consommés et compactés dans la chaîne binaire résultante.
      </para>
      <para>
       Les formats actuellement acceptés sont :
       <table>
        <title>Caractères de formatage pour <function>pack</function></title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Code</entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>a</entry>
           <entry>NUL - Une chaîne complétée avec &null;</entry>
          </row>
          <row>
           <entry>A</entry>
           <entry>SPACE - Une chaîne complétée avec un espace</entry></row>
          <row>
           <entry>h</entry>
           <entry>Chaîne hexadécimale h, bit de poids faible en premier</entry></row>
          <row>
           <entry>H</entry>
           <entry>Chaîne hexadécimale H, bit de poids fort en premier</entry></row>
          <row>
           <entry>c</entry>
           <entry>Caractère signé</entry></row>
          <row>
           <entry>C</entry>
           <entry>Caractère non signé</entry></row>
          <row>
           <entry>s</entry>
           <entry>entier court signé (toujours sur 16 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>S</entry>
           <entry>entier court non signé (toujours 16 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>n</entry>
           <entry>entier court non signé (toujours 16 bits, ordre des octets big endian)</entry>
          </row>
          <row>
           <entry>v</entry>
           <entry>entier court non signé (toujours 16 bits, ordre des octets little endian)</entry>
          </row>
          <row>
           <entry>i</entry>
           <entry>entier signé (taille et ordre des octets dépendants de la machine)</entry>
          </row>
          <row>
           <entry>I</entry>
           <entry>entier non signé (taille et ordre des octets dépendants de la machine)</entry>
          </row>
          <row>
           <entry>l</entry>
           <entry>entier long signé (toujours 32 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>L</entry>
           <entry>entier long non signé (toujours 32 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>N</entry>
           <entry>entier long non signé (toujours 32 bits, ordre des octets big endian)</entry>
          </row>
          <row>
           <entry>V</entry>
           <entry>entier long non signé (toujours 32 bits, ordre des octets little endian)</entry>
          </row>
          <row>
           <entry>q</entry>
           <entry>entier doublement long signé (toujours 64 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>Q</entry>
           <entry>entier doublement long non signé (toujours 64 bits, ordre des octets dépendant de la machine)</entry>
          </row>
          <row>
           <entry>J</entry>
           <entry>entier doublement long non signé (toujours 64 bits, ordre des octets big endian)</entry>
          </row>
          <row>
           <entry>P</entry>
           <entry>entier doublement long non signé (toujours 64 bits, ordre des octets little endian)</entry>
          </row>
          <row>
           <entry>f</entry>
           <entry>nombre à virgule flottante (taille et représentation dépendantes de la machine)</entry>
          </row>
          <row>
           <entry>g</entry>
           <entry>nombre à virgule flottante (taille dépendantes de la machine, ordre des octets little endian)</entry>
          </row>
          <row>
           <entry>G</entry>
           <entry>nombre à virgule flottante (taille dépendantes de la machine, ordre des octets big endian)</entry>
          </row>
          <row>
           <entry>d</entry>
           <entry>nombre à virgule flottante double (taille et représentation dépendantes de la machine)</entry>
          </row>
          <row>
           <entry>e</entry>
           <entry>nombre à virgule flottante double (taille dépendantes de la machine, ordre des octets little endian)</entry>
          </row>
          <row>
           <entry>E</entry>
           <entry>nombre à virgule flottante double (taille dépendantes de la machine, ordre des octets big endian)</entry>
          </row>
          <row>
           <entry>x</entry>
           <entry>caractère NUL</entry>
          </row>
          <row>
           <entry>X</entry>
           <entry>Recule d'un caractère</entry>
          </row>
          <row>
           <entry>Z</entry>
           <entry>Chaîne complétée par la valeur NULL</entry>
          </row>
          <row>
           <entry>@</entry>
           <entry>Remplit avec des NUL jusqu'à la position absolue</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une &string; binaire contenant les données.
  </para>
 </refsect1>
 
 <refsect1 role="changelog"><!-- {{{ -->
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.0.0</entry>
       <entry>
        This function no longer returns &false; on failure.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        Les types <type>float</type> et <type>double</type> prennent en charge Big Endian et Little Endian.
       </entry>
      </row>
      <row>
       <entry>7.0.15, 7.1.1</entry>
       <entry>
        Les codes "e", "E", "g" and "G" ont été ajouté pour activer la prise en 
        charge de l'ordre des octets pour les nombres à virgule flottante simple 
        et double précision.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>pack</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
?>
]]>
    </programlisting>
    <para>
     La chaîne binaire résultante aura 6 octets de long,
     et contiendra la séquence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
    </para>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
   <para>Notez que PHP stocke en interne les valeurs <type>int</type> comme valeurs
    signées dépendantes de la machine (type C <literal>long</literal>).   
    Les opérations sur les entiers qui mènent à des chiffres en dehors de l'espace de
    définition de l'<type>int</type> seront stockées dans des <type>float</type>.
    Lors de l'empaquetage de ses flottants en entiers, ils sont transtypés vers le type
    entier. Ceci peut éventuellement mener à une représentation inattendue des octets.
   </para>
   <para>Le cas le plus classique est l'empaquetage de nombres non signés qui seraient
    représentables dans le type <type>int</type> si celui-ci était non signé.
    Sur les systèmes ayant un <type>int</type> d'une taille de 32-bits, le transtypage
    résulte en un octet identique que si le type <type>int</type> était non signé
    (même si cela reste dépendant de l'implémentation non signé vers signé, du standard C).
    Sur les systèmes ayant un <type>int</type> d'une taille de 64-bits, le
    <type>float</type> n'a souvent pas une mantisse assez large pour contenir la valeur
    sans perte de précision. Si ces systèmes possèdent aussi un type C natif
    <literal>int</literal> 64-bits (la plupart des *NIX ne l'ont pas), le seul moyen
    d'utiliser le format de paquetage <literal>I</literal> dans les hautes valeurs est de créer
    des valeurs <type>int</type> négatives avec la même représentation des octets que la
    valeur non signées voulue correspondante.
   </para>
  </caution>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>unpack</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->