Integrate mainline

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 78d25be..048ecfb 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1054,16 +1054,16 @@ Equivalent examples:
     die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
     chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
 
-If the value of EXPR does not end in a newline, the current script line
-number and input line number (if any) are also printed, and a newline
-is supplied.  Note that the "input line number" (also known as "chunk")
-is subject to whatever notion of "line" happens to be currently in
-effect, and is also available as the special variable C<$.>.
-See L<perlvar/"$/"> and L<perlvar/"$.">.
+If the last element of LIST does not end in a newline, the current
+script line number and input line number (if any) are also printed,
+and a newline is supplied.  Note that the "input line number" (also
+known as "chunk") is subject to whatever notion of "line" happens to
+be currently in effect, and is also available as the special variable
+C<$.>.  See L<perlvar/"$/"> and L<perlvar/"$.">.
 
-Hint: sometimes appending C<", stopped"> to your message
-will cause it to make better sense when the string C<"at foo line 123"> is
-appended.  Suppose you are running script "canasta".
+Hint: sometimes appending C<", stopped"> to your message will cause it
+to make better sense when the string C<"at foo line 123"> is appended.
+Suppose you are running script "canasta".
 
     die "/etc/games is no good";
     die "/etc/games is no good, stopped";
@@ -2652,8 +2652,14 @@ that executes once.  Thus C<next> will exit such a block early.
 See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
+=item no Module VERSION LIST
+
+=item no Module VERSION
+
 =item no Module LIST
 
+=item no Module
+
 See the L</use> function, which C<no> is the opposite of.
 
 =item oct EXPR
@@ -3018,12 +3024,18 @@ them, and automatically close whenever and however you leave that scope:
 
 See L</seek> for some details about mixing reading and writing.
 
+=item opendir DIRHANDLE,MODE,EXPR
+
 =item opendir DIRHANDLE,EXPR
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
+In three-argument form the middle argument may be C<:utf8> to force
+the filenames returned by readdir() to be in UTF-8 encoding of Unicode.
+This naturally works only if your filesystem returns UTF-8 filenames.
+
 =item ord EXPR
 
 =item ord
@@ -3722,6 +3734,10 @@ C<chdir> there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
     closedir DIR;
 
+In some filesystems it is possible to return UTF-8 encoded filenames.
+To get readdir() to return such filenames, you must use C<:utf8> with
+the three-argument form of opendir(), see L</opendir>.
+
 =item readline EXPR
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
@@ -4604,12 +4620,14 @@ Examples:
     use sort 'stable';
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
-    # force use of quicksort (not portable outside Perl 5.8)
-    use sort '_quicksort';  # note discouraging _
+    # force use of mergesort (not portable outside Perl 5.8)
+    use sort '_mergesort';  # note discouraging _
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
-    # similar to the previous example, but demand stability as well
-    use sort qw( _mergesort stable );
+    # Similar to the previous example, but demand stability as well
+    # Because of the way quicksort is "stabilized", this combination
+    # is not threadsafe
+    use sort qw( _quicksort stable );
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
 If you're using strict, you I<must not> declare $a
@@ -4643,7 +4661,8 @@ returns the last element removed, or C<undef> if no elements are
 removed.  The array grows or shrinks as necessary.
 If OFFSET is negative then it starts that far from the end of the array.
 If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, leaves that many elements off the end of the array.
+If LENGTH is negative, removes the elements from OFFSET onward
+except for -LENGTH elements at the end of the array.
 If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
 past the end of the array, perl issues a warning, and splices at the
 end of the array.