summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm
diff options
context:
space:
mode:
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm')
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm143
1 files changed, 46 insertions, 97 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm
index 659f3e4f4d..f76a30bfc5 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm
@@ -1,14 +1,9 @@
package sort;
-our $VERSION = '2.04';
-
-# The hints for pp_sort are now stored in $^H{sort}; older versions
-# of perl used the global variable $sort::hints. -- rjh 2005-12-19
-
-$sort::stable_bit = 0x00000100;
-$sort::unstable_bit = 0x00000200;
-
use strict;
+use warnings;
+
+our $VERSION = '2.05';
sub import {
shift;
@@ -16,18 +11,12 @@ sub import {
require Carp;
Carp::croak("sort pragma requires arguments");
}
- local $_;
$^H{sort} //= 0;
- while ($_ = shift(@_)) {
- if ($_ eq 'stable') {
- $^H{sort} |= $sort::stable_bit;
- $^H{sort} &= ~$sort::unstable_bit;
- } elsif ($_ eq 'defaults') {
- $^H{sort} = 0;
- } else {
- require Carp;
- Carp::croak("sort: unknown subpragma '$_'");
- }
+ for my $subpragma (@_) {
+ next
+ if $subpragma eq 'stable' || $subpragma eq 'defaults';
+ require Carp;
+ Carp::croak("sort: unknown subpragma '$_'");
}
}
@@ -37,25 +26,17 @@ sub unimport {
require Carp;
Carp::croak("sort pragma requires arguments");
}
- local $_;
- no warnings 'uninitialized'; # bitops would warn
- while ($_ = shift(@_)) {
- if ($_ eq 'stable') {
- $^H{sort} &= ~$sort::stable_bit;
- $^H{sort} |= $sort::unstable_bit;
- } else {
- require Carp;
- Carp::croak("sort: unknown subpragma '$_'");
- }
+ for my $subpragma (@_) {
+ next
+ if $subpragma eq 'stable';
+ require Carp;
+ Carp::croak("sort: unknown subpragma '$_'");
}
}
sub current {
- my @sort;
- if ($^H{sort}) {
- push @sort, 'stable' if $^H{sort} & $sort::stable_bit;
- }
- join(' ', @sort);
+ warnings::warnif("deprecated", "sort::current is deprecated, and will always return 'stable'");
+ return 'stable';
}
1;
@@ -67,86 +48,54 @@ sort - perl pragma to control sort() behaviour
=head1 SYNOPSIS
+The sort pragma is now a no-op, and its use is discouraged. These three
+operations are valid, but have no effect:
+
use sort 'stable'; # guarantee stability
use sort 'defaults'; # revert to default behavior
no sort 'stable'; # stability not important
- my $current;
- BEGIN {
- $current = sort::current(); # identify prevailing pragmata
- }
-
=head1 DESCRIPTION
-With the C<sort> pragma you can control the behaviour of the builtin
+Historically the C<sort> pragma you can control the behaviour of the builtin
C<sort()> function.
-A stable sort means that for records that compare equal, the original
-input ordering is preserved.
-Stability will matter only if elements that compare equal can be
-distinguished in some other way. That means that simple numerical
-and lexical sorts do not profit from stability, since equal elements
-are indistinguishable. However, with a comparison such as
+Prior to v5.28.0 there were two other options:
- { substr($a, 0, 3) cmp substr($b, 0, 3) }
+ use sort '_mergesort';
+ use sort '_qsort'; # or '_quicksort'
-stability might matter because elements that compare equal on the
-first 3 characters may be distinguished based on subsequent characters.
+If you try and specify either of these in v5.28+ it will croak.
-Whether sorting is stable by default is an accident of implementation
-that can change (and has changed) between Perl versions.
-If stability is important, be sure to
-say so with a
+The default sort has been stable since v5.8.0, and given this consistent
+behaviour for almost two decades, everyone has come to assume stability.
- use sort 'stable';
+Stability will remain the default - hence there is no need for a pragma for
+code to opt into stability "just in case" this changes - it won't.
-The C<no sort> pragma doesn't
-I<forbid> what follows, it just leaves the choice open. Thus, after
+We do not foresee going back to offering multiple implementations of general
+purpose sorting - hence there is no future need to offer a pragma to choose
+between them.
- no sort 'stable';
+If you know that you care that much about performance of your sorting, and
+that for your use case and your data, it was worth investigating
+alternatives, possible to identify an alternative from our default that was
+better, and the cost of switching was worth it, then you know more than we
+do. Likely whatever choices we can give are not as good as implementing your
+own. (For example, a Radix sort can be faster than O(n log n), but can't be
+used for all keys and has larger overheads.)
-sorting may happen to be stable anyway.
+We are not averse to B<changing> the sort algorithm, but we don't see the
+benefit in offering the choice of two general purpose implementations.
=head1 CAVEATS
-As of Perl 5.10, this pragma is lexically scoped and takes effect
-at compile time. In earlier versions its effect was global and took
-effect at run-time; the documentation suggested using C<eval()> to
-change the behaviour:
-
- { eval 'no sort "stable"'; # stability not wanted
- print sort::current . "\n";
- @a = sort @b;
- eval 'use sort "defaults"'; # clean up, for others
- }
- { eval 'use sort qw(defaults stable)'; # force stability
- print sort::current . "\n";
- @c = sort @d;
- eval 'use sort "defaults"'; # clean up, for others
- }
-
-Such code no longer has the desired effect, for two reasons.
-Firstly, the use of C<eval()> means that the sorting algorithm
-is not changed until runtime, by which time it's too late to
-have any effect. Secondly, C<sort::current> is also called at
-run-time, when in fact the compile-time value of C<sort::current>
-is the one that matters.
-
-So now this code would be written:
-
- { no sort "stable"; # stability not wanted
- my $current;
- BEGIN { $current = sort::current; }
- print "$current\n";
- @a = sort @b;
- # Pragmas go out of scope at the end of the block
- }
- { use sort qw(defaults stable); # force stability
- my $current;
- BEGIN { $current = sort::current; }
- print "$current\n";
- @c = sort @d;
- }
+The function C<sort::current()> was provided to report the current state of
+the sort pragmata. This function was not exported, and there is no code to
+call it on CPAN. It is now deprecated, and will warn by default.
-=cut
+As we no longer store any sort "state", it can no longer return the correct
+value, so it will always return the string C<stable>, as this is consistent
+with what we actually have implemented.
+=cut