mention unpack('pP',...) footshot (from Albert Dvornik <bert@genscan.com>)

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 87f94f8..a65e3e3 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -546,7 +546,9 @@ number of characters removed from all its arguments.  It's often used to
 remove the newline from the end of an input record when you're worried
 that the final record may be missing its newline.  When in paragraph
 mode (C<$/ = "">), it removes all trailing newlines from the string.
-If VARIABLE is omitted, it chomps C<$_>.  Example:
+When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
+a reference to an integer or the like, see L<perlvar>) chomp() won't
+remove anything.  If VARIABLE is omitted, it chomps C<$_>.  Example:
 
     while (<>) {
        chomp;  # avoid \n on last field
@@ -965,6 +967,27 @@ This is useful for propagating exceptions:
 
 If C<$@> is empty then the string C<"Died"> is used.
 
+die() can also be called with a reference argument.  If this happens to be
+trapped within an eval(), $@ contains the reference.  This behavior permits
+a more elaborate exception handling implementation using objects that
+maintain arbitary state about the nature of the exception.  Such a scheme
+is sometimes preferable to matching particular string values of $@ using
+regular expressions.  Here's an example:
+
+    eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
+    if ($@) {
+        if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
+            # handle Some::Module::Exception
+        }
+        else {
+            # handle all other possible exceptions
+        }
+    }
+
+Since perl will stringify uncaught exception messages before displaying
+them, you may want to overload stringification operations on such custom
+exception objects.  See L<overload> for details about that.
+
 You can arrange for a callback to be run just before the C<die()> does
 its deed, by setting the C<$SIG{__DIE__}> hook.  The associated handler
 will be called with the error text and can change the error message, if
@@ -2223,6 +2246,8 @@ element) and returns the list value composed of the results of each such
 evaluation.  Evaluates BLOCK or EXPR in a list context, so each element of LIST
 may produce zero, one, or more elements in the returned value.
 
+In scalar context, returns the total number of elements so generated.
+
     @chars = map(chr, @nums);
 
 translates a list of numbers to the corresponding characters.  And
@@ -4588,6 +4613,11 @@ The following efficiently counts the number of set bits in a bit vector:
 
     $setbits = unpack("%32b*", $selectmask);
 
+The C<"p"> and C<"P"> formats should be used with care.  Since Perl
+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.
 
 =item untie VARIABLE