Enhance pack() doc.

p4raw-id: //depot/cfgperl@3822

1 files changed, 34 insertions, 15 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7072d72bbf..edcb969672 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2719,7 +2719,8 @@ follows:
     s	A signed short value.
     S	An unsigned short value.
 	  (This 'short' is _exactly_ 16 bits, which may differ from
-	   what a local C compiler calls 'short'.)
+	   what a local C compiler calls 'short'.  If you want
+	   native-length shorts, use the '!' suffix.)
 
     i	A signed integer value.
     I	An unsigned integer value.
@@ -2731,7 +2732,8 @@ follows:
     l	A signed long value.
     L	An unsigned long value.
 	  (This 'long' is _exactly_ 32 bits, which may differ from
-	   what a local C compiler calls 'long'.)
+	   what a local C compiler calls 'long'.  If you want
+	   native-length longs, use the '!' suffix.)
 
     n	A short in "network" (big-endian) order.
     N	A long in "network" (big-endian) order.
@@ -2742,8 +2744,8 @@ follows:
 
     q	A signed quad (64-bit) value.
     Q	An unsigned quad value.
-	  (Available only if your system supports 64-bit integer values
-	   _and_ if Perl has been compiled to support those.
+	  (Quads are available only if your system supports 64-bit
+	   integer values _and_ if Perl has been compiled to support those.
            Causes a fatal error otherwise.)
 
     f	A single-precision float in the native format.
@@ -2790,7 +2792,8 @@ Likewise, the C<"b"> and C<"B"> fields pack a string that many bits long.
 
 =item *
 
-The C<"h"> and C<"H"> fields pack a string that many nybbles long.
+The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups,
+representable as hexadecimal digits, 0-9a-f) long.
 
 =item *
 
@@ -2833,11 +2836,11 @@ which Perl does not regard as legal in numeric strings.
 =item *
 
 The integer types C<"s">, C<"S">, C<"l">, and C<"L"> may be
-immediately followed by a C<"!"> to signify native shorts or longs--as
-you can see from above for example a bare C<"l"> does mean exactly 32
-bits, the native C<long> (as seen by the local C compiler) may be
-larger.  This is an issue mainly in 64-bit platforms.  You can see
-whether using C<"!"> makes any difference by
+immediately followed by a C<"!"> suffix to signify native shorts or
+longs--as you can see from above for example a bare C<"l"> does mean
+exactly 32 bits, the native C<long> (as seen by the local C compiler)
+may be larger.  This is an issue mainly in 64-bit platforms.  You can
+see whether using C<"!"> makes any difference by
 
 	print length(pack("s")), " ", length(pack("s!")), "\n";
 	print length(pack("l")), " ", length(pack("l!")), "\n";
@@ -2845,9 +2848,6 @@ whether using C<"!"> makes any difference by
 C<"i!"> and C<"I!"> also work but only because of completeness;
 they are identical to C<"i"> and C<"I">.
 
-The actual sizes (in bytes) of native shorts, ints, and longs on
-the platform where Perl was built are also available via L<Config>:
-
 The actual sizes (in bytes) of native shorts, ints, longs, and long
 longs on the platform where Perl was built are also available via
 L<Config>:
@@ -2858,6 +2858,9 @@ L<Config>:
        print $Config{longsize},     "\n";
        print $Config{longlongsize}, "\n";
 
+(The C<$Config{longlongsize}> will be empty if your system does
+not support long longs.) 
+
 =item *
 
 The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L">
@@ -2900,6 +2903,7 @@ and C<'87654321'> are big-endian.
 
 If you want portable packed integers use the formats C<"n">, C<"N">,
 C<"v">, and C<"V">, their byte endianness and size is known.
+See also L<perlport>.
 
 =item *
 
@@ -2909,13 +2913,22 @@ standard "network" representation, no facility for interchange has been
 made.  This means that packed floating point data written on one machine
 may not be readable on another - even if both use IEEE floating point
 arithmetic (as the endian-ness of the memory representation is not part
-of the IEEE spec).
+of the IEEE spec).  See also L<perlport>.
 
 Note that Perl uses doubles internally for all numeric calculation, and
 converting from double into float and thence back to double again will
 lose precision (i.e., C<unpack("f", pack("f", $foo)>) will not in general
 equal $foo).
 
+=item *
+
+You must yourself do any alignment or padding by inserting for example
+enough C<'x'>es while packing.  There is no way to they could know
+from where the bytes are coming from, they might be coming from a
+completely different system than the one your script is running in.
+Therefore C<pack> (and C<unpack>) handle their output and input as
+flat sequences of bytes.
+
 =back
 
 Examples:
@@ -2957,6 +2970,12 @@ Examples:
 	unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
     }
 
+    $foo = pack('sx2l', 12, 34);
+    # short 12, two zero bytes padding, long 34
+    $bar = pack('s@4l', 12, 34);
+    # short 12, zero fill to position 4, long 34
+    # $foo eq $bar
+
 The same template may generally also be used in unpack().
 
 =item package 
@@ -4779,7 +4798,7 @@ has no way of checking whether the value passed to C<unpack()>
 corresponds to a valid memory location, passing a pointer value that's
 not known to be valid is likely to have disastrous consequences.
 
-See L</pack> for more examples.
+See L</pack> for more examples and notes.
 
 =item untie VARIABLE