diff options
author | Norbert Preining <norbert@preining.info> | 2024-03-15 03:06:35 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2024-03-15 03:06:35 +0000 |
commit | 12679ab7d3c2a210f4123163671b532b8b55d5f9 (patch) | |
tree | 0060d13467186ad977f4e73488ee20dd6c0017ab /systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm | |
parent | 62170822e034fdd3f81de7274835d0d3b0467100 (diff) |
CTAN sync 202403150306
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm')
-rw-r--r-- | systems/texlive/tlnet/tlpkg/tlperl/lib/sort.pm | 143 |
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 |