perlfunc/printf: corrections, clarifications

[perl5.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index b76da4a..408c915 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1686,6 +1686,13 @@ The exact behaviour may change in a future version of Perl.
 
     while (($key,$value) = each $hashref) { ... }
 
+As of Perl 5.18 you can use a bare C<each> in a C<while> loop,
+which will set C<$_> on every iteration.
+
+    while(each %ENV) {
+       print "$_=$ENV{$_}\n";
+    }
+
 To avoid confusing would-be users of your code who are running earlier
 versions of Perl with mysterious syntax errors, put this sort of thing at
 the top of your file to signal that your code will work I<only> on Perls of
@@ -1693,6 +1700,7 @@ a recent vintage:
 
     use 5.012; # so keys/values/each work on arrays
     use 5.014; # so keys/values/each work on scalars (experimental)
+    use 5.018; # so each assigns to $_ in a lone while test
 
 See also C<keys>, C<values>, and C<sort>.
 
@@ -5170,17 +5178,24 @@ X<printf>
 =for Pod::Functions output a formatted list to a filehandle
 
 Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
-(the output record separator) is not appended.  The first argument of the
-list will be interpreted as the C<printf> format.  See
+(the output record separator) is not appended.  The FORMAT and the
+LIST are actually parsed as a single list.  The first argument
+of the list will be interpreted as the C<printf> format.  This
+means that C<printf(@_)> will use C<$_[0]> as the format.  See
 L<sprintf|/sprintf FORMAT, LIST> for an
-explanation of the format argument.  If you omit the LIST, C<$_> is used;
-to use FILEHANDLE without a LIST, you must use a real filehandle like
-C<FH>, not an indirect one like C<$fh>.  If C<use locale> (including
+explanation of the format argument.  If C<use locale> (including
 C<use locale ':not_characters'>) is in effect and
 POSIX::setlocale() has been called, the character used for the decimal
 separator in formatted floating-point numbers is affected by the LC_NUMERIC
 locale setting.  See L<perllocale> and L<POSIX>.
 
+For historical reasons, if you omit the list, C<$_> is used as the format;
+to use FILEHANDLE without a list, you must use a real filehandle like
+C<FH>, not an indirect one like C<$fh>.  However, this will rarely do what
+you want; if $_ contains formatting codes, they will be replaced with the
+empty string and a warning will be emitted if warnings are enabled.  Just
+use C<print> if you want to print the contents of $_.
+
 Don't fall into the trap of using a C<printf> when a simple
 C<print> would do.  The C<print> is more efficient and less
 error prone.
@@ -5928,8 +5943,8 @@ Used without arguments in scalar context, reverse() reverses C<$_>.
     print scalar reverse;                  # Hello, world
 
 Note that reversing an array to itself (as in C<@a = reverse @a>) will
-preserve non-existent elements whenever possible, i.e., for non magical
-arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
+preserve non-existent elements whenever possible; i.e., for non-magical
+arrays or for tied arrays with C<EXISTS> and C<DELETE> methods.
 
 This operator is also handy for inverting a hash, although there are some
 caveats.  If a value is duplicated in the original hash, only one of those