From: Gary Wright <radar2002@...>
Date: 2007-12-11T11:13:37+09:00
Subject: Array#pack and String#unpack documentation

In working with Array#pack and String#unpack today, I found
the documentation for the a, A, and Z formats somewhat ambiguous.
The docs for Array#pack read:

 A     |  ASCII string (space padded, count is width)
 a     |  ASCII string (null padded, count is width)
 Z     |  Same as ``a'', except that null is added with *

The phrase 'ASCII string' is the part that confused me.  It
looks like the contents of the string is irrelavant--there
is no requirement that the string only contain ASCII values.
For A, the padded space will be an ASCII space though.  For
'a' and 'z', there doesn't seem to be any dependency on ASCII.

Here is a suggested patch against branches/ruby_1_8

Index: pack.c
===================================================================
--- pack.c      (revision 14122)
+++ pack.c      (working copy)
@@ -400,8 +400,8 @@
 *   Directive    Meaning
 *   ---------------------------------------------------------------
 *       @     |  Moves to absolute position
- *       A     |  ASCII string (space padded, count is width)
- *       a     |  ASCII string (null padded, count is width)
+ *       A     |  arbitrary binary string (ASCII space padded, count is width)
+ *       a     |  arbitrary binary string (null padded, count is width)
 *       B     |  Bit string (descending bit order)
 *       b     |  Bit string (ascending bit order)
 *       C     |  Unsigned char
@@ -525,8 +525,8 @@

           switch (type) {
             case 'a':         /* arbitrary binary string (null padded)  */
-             case 'A':         /* ASCII string (space padded) */
-             case 'Z':         /* null terminated ASCII string  */
+             case 'A':         /* arbitrary binary string (ASCII
space padded) */
+             case 'Z':         /* null terminated string  */
               if (plen >= len) {
                   rb_str_buf_cat(res, ptr, len);
                   if (p[-1] == '*' && type == 'Z')
@@ -1193,9 +1193,10 @@
 *
 *     Format | Returns | Function
 *     -------+---------+-----------------------------------------
- *       A    | String  | with trailing nulls and spaces removed
+ *       A    | String  | arbitrary binary string with trailing
+ *            |         | nulls and ASCII spaces removed
 *     -------+---------+-----------------------------------------
- *       a    | String  | string
+ *       a    | String  | arbitrary binary string
 *     -------+---------+-----------------------------------------
 *       B    | String  | extract bits from each character (msb first)
 *     -------+---------+-----------------------------------------