From 693563124fdd9193594b80b9c9f69fb736c6c9b7 Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Thu, 10 Feb 2011 12:36:37 +0000
Subject: [PATCH] Update pack() documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@308185 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/misc/functions/unpack.xml | 61 +++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 7 deletions(-)

diff --git a/reference/misc/functions/unpack.xml b/reference/misc/functions/unpack.xml
index e068af41dd..a2729cf485 100644
--- a/reference/misc/functions/unpack.xml
+++ b/reference/misc/functions/unpack.xml
@@ -18,10 +18,11 @@
    <parameter>format</parameter>. 
   </para>
   <para>
-   <function>unpack</function> works slightly different from Perl as
-   the unpacked data is stored in an associative array. To
+   The unpacked data is stored in an associative array. To
    accomplish this you have to name the different format codes and
-   separate them by a slash /.
+   separate them by a slash /. If a repeater argument is present,
+   then each of the array keys will have a sequence number behind
+   the given name.
   </para>
  </refsect1>
 
@@ -65,17 +66,35 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$array = unpack("c2chars/nint", $binarydata);
+$binarydata = "\0x04\0x00\0xa0
+$array = unpack("cchar/nint", $binarydata);
 ?>
 ]]>
     </programlisting>
     <para>
-     The resulting array will contain the entries "chars1",
-     "chars2" and "int".
+     The resulting array will contain the entries "chars" with value
+     <literal>4</literal> and "int" with <literal>160</literal>.
     </para>
    </example>
   </para>
- </refsect1>
+
+  <para>
+   <example>
+    <title><function>unpack</function> example with a repeater</title>
+    <programlisting role="php">
+ <![CDATA[
+ <?php
+ $array = unpack("c2chars/nint", $binarydata);
+ ?>
+ ]]>
+     </programlisting>
+     <para>
+      The resulting array will contain the entries "chars1",
+      "chars2" and "int".
+     </para>
+    </example>
+   </para>
+  </refsect1>
 
  <refsect1 role="notes">
   &reftitle.notes;
@@ -87,6 +106,34 @@ $array = unpack("c2chars/nint", $binarydata);
     even though unsigned unpacking was specified.
    </para>
   </caution>
+  <caution>
+   <para>
+    Be aware that if you do not name an element, an empty string is used.
+    If you do not name more than one element, this means
+    that some data is overwritten as the keys are the same such as in:
+   </para>
+   <para>
+    <example>
+     <title><function>unpack</function> example with unnamed keys</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$binarydata = "\x32\x42\x00\xa0";
+$array = unpack("c2/n", $binarydata);
+var_dump($array);
+?>
+]]>
+     </programlisting>
+     <para>
+      The resulting array will contain the entries "1" with value
+      <literal>160</literal> and "2" with <literal>66</literal>. The
+      first value from the <literal>c</literal> specifier is 
+      overwritten by the first value from the <literal>n</literal>
+      specifier.
+     </para>
+    </example>
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="seealso">