Some mandatory syntax warnings emitted by the lexer weren't

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4d4efc5..8b13ebd 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1033,8 +1033,18 @@ In the case of an array, if the array elements happen to be at the end,
 the size of the array will shrink to the highest element that tests
 true for exists() (or 0 if no such element exists).
 
-Returns each element so deleted or the undefined value if there was no such
-element.  Deleting from C<$ENV{}> modifies the environment.  Deleting from
+Returns a list with the same number of elements as the number of elements
+for which deletion was attempted.  Each element of that list consists of
+either the value of the element deleted, or the undefined value.  In scalar
+context, this means that you get the value of the last element deleted (or
+the undefined value if that element did not exist).
+
+    %hash = (foo => 11, bar => 22, baz => 33);
+    $scalar = delete $hash{foo};             # $scalar is 11
+    $scalar = delete @hash{qw(foo bar)};     # $scalar is 22
+    @array  = delete @hash{qw(foo bar baz)}; # @array  is (undef,undef,33)
+
+Deleting from C<%ENV> modifies the environment.  Deleting from
 a hash tied to a DBM file deletes the entry from the DBM file.  Deleting
 from a C<tie>d hash or array may not necessarily return anything.
 
@@ -1654,6 +1664,18 @@ Note that C<fcntl> will produce a fatal error if used on a machine that
 doesn't implement fcntl(2).  See the Fcntl module or your fcntl(2)
 manpage to learn what functions are available on your system.
 
+Here's an example of setting a filehandle named C<REMOTE> to be
+non-blocking at the system level.  You'll have to negotiate C<$|>
+on your own, though.
+
+    use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
+
+    $flags = fcntl(REMOTE, F_GETFL, 0)
+                or die "Can't get flags for the socket: $!\n";
+
+    $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
+                or die "Can't set flags for the socket: $!\n";
+
 =item fileno FILEHANDLE
 
 Returns the file descriptor for a filehandle, or undefined if the
@@ -2286,21 +2308,9 @@ system:
     $retval = ioctl(...) || -1;
     printf "System returned %d\n", $retval;
 
-The special string "C<0> but true" is exempt from B<-w> complaints
+The special string C<"0 but true"> is exempt from B<-w> complaints
 about improper numeric conversions.
 
-Here's an example of setting a filehandle named C<REMOTE> to be
-non-blocking at the system level.  You'll have to negotiate C<$|>
-on your own, though.
-
-    use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
-
-    $flags = fcntl(REMOTE, F_GETFL, 0)
-                or die "Can't get flags for the socket: $!\n";
-
-    $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
-                or die "Can't set flags for the socket: $!\n";
-
 =item join EXPR,LIST
 
 Joins the separate strings of LIST into a single string with fields
@@ -2325,7 +2335,8 @@ Perl for security reasons (see L<perlsec/"Algorithmic Complexity
 Attacks">).
 
 As a side effect, calling keys() resets the HASH's internal iterator,
-see L</each>.
+see L</each>. (In particular, calling keys() in void context resets
+the iterator with no other overhead.)
 
 Here is yet another way to print your environment:
 
@@ -4087,7 +4098,9 @@ following subroutine:
     }
 
 Note that the file will not be included twice under the same specified
-name.  The file must return true as the last statement to indicate
+name.
+
+The file must return true as the last statement to indicate
 successful execution of any initialization code, so it's customary to
 end such a file with C<1;> unless you're sure it'll return true
 otherwise.  But it's better just to put the C<1;>, in case you add more
@@ -5868,6 +5881,7 @@ A class implementing a hash should have the following methods:
     EXISTS this, key
     FIRSTKEY this
     NEXTKEY this, lastkey
+    SCALAR this
     DESTROY this
     UNTIE this
 
@@ -6260,12 +6274,8 @@ to the current time.  For example, this code has the same effect as the
 Unix touch(1) command when the files I<already exist>.
 
     #!/usr/bin/perl
-    $now = time;
-    utime $now, $now, @ARGV;
-
-B<Note:>  Under NFS, touch(1) uses the time of the NFS server, not
-the time of the local machine.  If there is a time synchronization
-problem, the NFS server and local machine will have different times.
+    $atime = $mtime = time;
+    utime $atime, $mtime, @ARGV;
 
 Since perl 5.7.2, if the first two elements of the list are C<undef>, then
 the utime(2) function in the C library will be called with a null second
@@ -6275,6 +6285,17 @@ above.)
 
     utime undef, undef, @ARGV;
 
+Under NFS this will use the time of the NFS server, not the time of
+the local machine.  If there is a time synchronization problem, the
+NFS server and local machine will have different times.  The Unix
+touch(1) command will in fact normally use this form instead of the
+one shown in the first example.
+
+Note that only passing one of the first two elements as C<undef> will
+be equivalent of passing it as 0 and will not have the same effect as
+described when they are both C<undef>.  This case will also trigger an
+uninitialized warning.
+
 =item values HASH
 
 Returns a list consisting of all the values of the named hash.
@@ -6288,7 +6309,8 @@ function would produce on the same (unmodified) hash.  Since Perl
 for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
 
 As a side effect, calling values() resets the HASH's internal iterator,
-see L</each>.
+see L</each>. (In particular, calling values() in void context resets
+the iterator with no other overhead.)
 
 Note that the values are not copied, which means modifying them will
 modify the contents of the hash: