pack.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 13732997f37ed612e14f33f7071f7c7ec1858a7c Maintainer: hholzgra Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: f9c4a68ef4f89e51e6d9b905ad3ddb6492386dd3 Reviewer: samesch -->
<refentry xml:id="function.pack" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pack</refname>
  <refpurpose>Packt Daten in eine binäre Zeichenkette</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>
   Packt die angegebenen Argumente unter Beachtung von
   <parameter>format</parameter> in eine binäre Zeichenkette.
  </para>
  <para>
   Die Idee für diese Funktion entstammt Perl. Alle Formatierungs-Anweisungen
   funktionieren genau wie dort, allerdings fehlen in PHP einige Format-Codes
   von Perl (&zb; "u").
  </para>
  <para>
   Beachten sie, dass der Unterschied zwischen vorzeichenlosen und
   vorzeichenbehafteten Werten nur Einfluss auf die Funktion
   <function>unpack</function> hat, wogegen die Funktion
   <function>pack</function> bei vorzeichenlosen und vorzeichenbehafteten
   Format-Codes dasselbe Ergebnis liefert.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       Die Zeichenkette <parameter>format</parameter> besteht aus
       Format-Codes, gefolgt von einem optionalen Wiederholungs-Argument.
       Dieses Argument kann ein ganzzahliger Wert sein oder ein
       <literal>*</literal> für Wiederholung bis ans Ende der Daten. Bei den
       Format-Codes a, A, h und H gibt das Wiederholungs-Argument an, wie
       viele gleiche Zeichen folgen. Im Zusammenhang mit "@" gibt das
       Wiederholungs-Argument die absolute Position an, ab der das nächste
       Zeichen steht. Bei allen anderen steht der Wiederholungs-Zähler für die
       Anzahl der benutzten Daten-Argumente, die in die sich ergebende binäre
       Zeichenkette gepackt werden sollen.
      </para>
      <para>
       Zurzeit sind folgende Formate implementiert:
       <table>
        <title><function>pack</function>-Formatzeichen</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Code</entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>a</entry>
           <entry>mit NUL gefüllte Zeichenkette</entry>
          </row>
          <row>
           <entry>A</entry>
           <entry>mit Leerzeichen gefüllte Zeichenkette</entry>
          </row>
          <row>
           <entry>h</entry>
           <entry>Hex-Zeichenkette, unterer Halbwert zuerst</entry>
          </row>
          <row>
           <entry>H</entry>
           <entry>Hex-Zeichenkette, oberer Halbwert zuerst</entry>
          </row>
          <row>
           <entry>c</entry>
           <entry>vorzeichenbehaftetes Zeichen</entry>
          </row>
          <row>
           <entry>C</entry>
           <entry>vorzeichenloses Zeichen</entry>
          </row>
          <row>
           <entry>s</entry>
           <entry>
            vorzeichenbehafteter Short-Typ (immer 16 Bit, Byte-Folge
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>S</entry>
           <entry>
            vorzeichenloser Short-Typ (immer 16 Bit, Byte-Folge
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>n</entry>
           <entry>
            vorzeichenloser Short-Typ (immer 16 Bit, Byte-Folge Big-Endian)
           </entry>
          </row>
          <row>
           <entry>v</entry>
           <entry>
            vorzeichenloser Short-Typ (immer 16 Bit, Byte-Folge Little-Endian)
           </entry>
          </row>
          <row>
           <entry>i</entry>
           <entry>
            vorzeichenbehaftete Ganzzahl (Größe und Byte-Folge
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>I</entry>
           <entry>
            vorzeichenlose Ganzzahl (Größe und Byte-Folge maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>l</entry>
           <entry>
            vorzeichenbehafteter Long-Typ (immer 32 Bit, Byte-Folge
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>L</entry>
           <entry>
            vorzeichenloser Long-Typ (immer 32 Bit, Byte-Folge
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>N</entry>
           <entry>
            vorzeichenloser Long-Typ (immer 32 Bit, Byte-Folge Big-Endian)
           </entry>
          </row>
          <row>
           <entry>V</entry>
           <entry>
            vorzeichenloser Long-Typ (immer 32 Bit, Byte-Folge Little-Endian)
           </entry>
          </row>
          <row>
           <entry>q</entry>
           <entry>
            vorzeichenbehafteter Long-Long-Typ (immer 64 Bit,
            maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>Q</entry>
           <entry>
            vorzeichenloser Long-Long-Typ (immer 64 Bit, maschinenabhängig)
           </entry>
          </row>
          <row>
           <entry>J</entry>
           <entry>
            vorzeichenloser Long-Long-Typ (immer 64 Bit, Byte-Folge
            Big-Endian)
           </entry>
          </row>
          <row>
           <entry>P</entry>
           <entry>
            vorzeichenloser Long-Long-Typ (immer 64 Bit, Byte-Folge
            Little-Endian)
           </entry>
          </row>
          <row>
           <entry>f</entry>
           <entry>
            Gleitkommazahl (maschinenabhängige Größe und Wiedergabe)
           </entry>
          </row>
          <row>
           <entry>g</entry>
           <entry>
            Gleitkommazahl (maschinenabhängige Größe, Byte-Folge
            Little-Endian)
           </entry>
          </row>
          <row>
           <entry>G</entry>
           <entry>
            Gleitkommazahl (maschinenabhängige Größe, Byte-Folge Big-Endian)
           </entry>
          </row>
          <row>
           <entry>d</entry>
           <entry>Double-Typ (maschinenabhängige Größe und Wiedergabe)</entry>
          </row>
          <row>
           <entry>e</entry>
           <entry>
            Double-Typ (maschinenabhängige Größe, Byte-Folge Little-Endian)
           </entry>
          </row>
          <row>
           <entry>E</entry>
           <entry>
            Double-Typ (maschinenabhängige Größe, Byte-Folge Big-Endian)
           </entry>
          </row>
          <row>
           <entry>x</entry>
           <entry>NUL Byte</entry>
          </row>
          <row>
           <entry>X</entry>
           <entry>geht in der Zeichenkette ein Byte rückwärts</entry>
          </row>
          <row>
           <entry>Z</entry>
           <entry>NUL-aufgefüllte Zeichenkette</entry>
          </row>
          <row>
           <entry>@</entry>
           <entry>NUL-Auffüllung bis zur absoluten Position</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>
   Gibt die Daten als binäre Zeichenkette zurück.
  </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>
        Diese Funktion gibt bei einem Fehler nicht mehr &false; zurück.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        <type>float</type>- und <type>double</type>-Typen unterstützen sowohl
        Big-Endian als auch Little-Endian.
       </entry>
      </row>
      <row>
       <entry>7.0.15, 7.1.1</entry>
       <entry>
        Die Codes "e", "E", "g" und "G" wurden hinzugefügt, um die
        Byte-Folgen-Unterstützung für float und double zu ermöglichen.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>pack</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php
$binaerdaten = pack("nvc*", 0x1234, 0x5678, 65, 66);
?>
]]>
    </programlisting>
    <para>
     Die sich daraus ergebende binäre Zeichenkette ist sechs Bytes lang und
     enthält die Byte-Folge 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
    </para>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
   <para>
    Es ist zu beachten, dass PHP <type>int</type>-Werte intern als
    vorzeichenbehaftete Werte einer maschinenabhängigen Größe speichert.
    Integer-Literale und Operationen, die Zahlen außerhalb der Grenzen des Typs
    <type>int</type> ergeben, werden als <type>float</type> gespeichert.
    Wenn diese Floats als Integer gepackt werden, werden sie zuerst in den
    Integer-Typ gewandelt. Dies kann u.U. ein nicht erwünschtes Byte-Muster
    ergeben.
   </para>
   <para>
    Der wichtigste Fall ist das Packen vorzeichenloser Zahlen, die als
    <type>int</type>-Typ darstellbar wären, wenn dieser vorzeichenlos wäre.
    Auf Systemen wo der Typ <type>int</type> 32 Bit groß ist, resultiert die
    Umwandlung üblicherweise im selben Byte-Muster, wie wenn der
    <type>int</type> vorzeichenlos wäre (allerdings ist das auf
    implementierungsspezifische Konvertierungen von vorzeichenlosen in
    vorzeichenbehaftete Zahlen gemäß dem C-Standard angewiesen). Auf Systemen,
    wo der Typ <type>int</type> 64 Bit groß ist, hat <type>float</type>
    vermutlich keine Mantisse, die groß genug ist, um den Wert ohne
    Genauigkeitsverlust zu speichern. Haben diese Systeme ebenfalls einen
    nativen 64bit-C-<literal>int</literal>-Typ (die meisten UNIX-artigen
    Systeme haben das nicht), dann ist die einzige Möglichkeit, das Packformat
    <literal>I</literal> im oberen Bereich zu nutzen, negative
    <type>int</type>-Werte mit der gleichen Byte-Darstellung wie die
    gewünschten vorzeichenlosen Werte zu erzeugen.
   </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
-->