Regen perlapi, regen toc.

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7823d4b..6d79b7a 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2666,6 +2666,8 @@ conversion assumes base 10.)
 
 =item open FILEHANDLE,MODE,EXPR,LIST
 
+=item open FILEHANDLE,MODE,REFERENCE
+
 =item open FILEHANDLE
 
 Opens the file whose filename is given by EXPR, and associates it with
@@ -2778,6 +2780,10 @@ argument being C<undef>:
 
 opens a filehandle to an anonymous temporary file.
 
+File handles can be opened to "in memory" files held in Perl scalars via:
+
+    open($fh,'>', \$variable) || ..
+
 Examples:
 
     $ARTICLE = 100;
@@ -2802,6 +2808,11 @@ Examples:
     open(EXTRACT, "|sort >/tmp/Tmp$$")         # $$ is our process id
        or die "Can't start sort: $!";
 
+    # in memory files
+    open(MEMORY,'>', \$var)
+       or die "Can't open memory file: $!";
+    print MEMORY "foo!\n";                     # output will end up in $var
+
     # process argument list of files along with any includes
 
     foreach $file (@ARGV) {
@@ -4436,11 +4447,19 @@ loop control operators described in L<perlsyn> or with C<goto>.
 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
 current collation locale.  See L<perllocale>.
 
-Perl does B<not> guarantee that sort is stable.  (A I<stable> sort
-preserves the input order of elements that compare equal.)  5.7 and
-5.8 happen to use a stable mergesort, but 5.6 and earlier used quicksort,
-which is not stable.  Do not assume that future perls will continue to
-use a stable sort.
+Perl 5.6 and earlier used a quicksort algorithm to implement sort.
+That algorithm was not stable, and I<could> go quadratic.  (A I<stable> sort
+preserves the input order of elements that compare equal.  Although
+quicksort's run time is O(NlogN) when averaged over all arrays of
+length N, the time can be O(N**2), I<quadratic> behavior, for some
+inputs.)  In 5.7, the quicksort implementation was replaced with
+a stable mergesort algorithm whose worst case behavior is O(NlogN).
+But benchmarks indicated that for some inputs, on some platforms,
+the original quicksort was faster.  5.8 has a sort pragma for
+limited control of the sort.  Its rather blunt control of the
+underlying algorithm may not persist into future perls, but the
+ability to characterize the input or output in implementation
+independent ways quite probably will.  See L</use>.
 
 Examples:
 
@@ -4523,6 +4542,18 @@ Examples:
     package main;
     @new = sort other::backwards @old;
 
+    # guarantee stability, regardless of algorithm
+    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 _
+    @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 );
+    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
+
 If you're using strict, you I<must not> declare $a
 and $b as lexicals.  They are package globals.  That means
 if you're in the C<main> package and type
@@ -5804,6 +5835,7 @@ are also implemented this way.  Currently implemented pragmas are:
     use strict   qw(subs vars refs);
     use subs     qw(afunc blurfl);
     use warnings qw(all);
+    use sort     qw(stable _quicksort _mergesort);
 
 Some of these pseudo-modules import semantics into the current
 block scope (like C<strict> or C<integer>, unlike ordinary modules,
@@ -6120,7 +6152,7 @@ The status is returned in C<$?>.  If you say
     #...
     do {
        $kid = waitpid(-1, WNOHANG);
-    } until $kid == -1;
+    } until $kid > 0;
 
 then you can do a non-blocking wait for all pending zombie processes.
 Non-blocking wait is available on machines supporting either the