lib/sort.pm

   1 package sort;
   2
   3 use strict;
   4 use warnings;
   5
   6 our $VERSION = '2.06';
   7
   8 sub import {
   9     shift;
  10     if (@_ == 0) {
  11         require Carp;
  12         Carp::croak("sort pragma requires arguments");
  13     }
  14     $^H{sort} //= 0;
  15     for my $subpragma (@_) {
  16         next
  17             if $subpragma eq 'stable' || $subpragma eq 'defaults';
  18         require Carp;
  19         Carp::croak("sort: unknown subpragma '$_'");
  20     }
  21 }
  22
  23 sub unimport {
  24     shift;
  25     if (@_ == 0) {
  26         require Carp;
  27         Carp::croak("sort pragma requires arguments");
  28     }
  29     for my $subpragma (@_) {
  30         next
  31             if $subpragma eq 'stable';
  32         require Carp;
  33         Carp::croak("sort: unknown subpragma '$_'");
  34     }
  35 }
  36
  37 sub current {
  38     warnings::warnif("deprecated", "sort::current is deprecated, and will always return 'stable'");
  39     return 'stable';
  40 }
  41
  42 1;
  43 __END__
  44
  45 =head1 NAME
  46
  47 sort - perl pragma to control sort() behaviour
  48
  49 =head1 SYNOPSIS
  50
  51 The sort pragma is now a no-op, and its use is discouraged. These three
  52 operations are valid, but have no effect:
  53
  54     use sort 'stable';          # guarantee stability
  55     use sort 'defaults';        # revert to default behavior
  56     no  sort 'stable';          # stability not important
  57
  58 =head1 DESCRIPTION
  59
  60 Historically the C<sort> pragma you can control the behaviour of the builtin
  61 C<sort()> function.
  62
  63 Prior to v5.28.0 there were two other options:
  64
  65     use sort '_mergesort';
  66     use sort '_qsort';          # or '_quicksort'
  67
  68 If you try and specify either of these in v5.28+ it will croak.
  69
  70 The default sort has been stable since v5.8.0, and given this consistent
  71 behaviour for almost two decades, everyone has come to assume stability.
  72
  73 Stability will remain the default - hence there is no need for a pragma for
  74 code to opt into stability "just in case" this changes - it won't.
  75
  76 We do not foresee going back to offering multiple implementations of general
  77 purpose sorting - hence there is no future need to offer a pragma to choose
  78 between them.
  79
  80 If you know that you care that much about performance of your sorting, and
  81 that for your use case and your data, it was worth investigating
  82 alternatives, possible to identify an alternative from our default that was
  83 better, and the cost of switching was worth it, then you know more than we
  84 do. Likely whatever choices we can give are not as good as implementing your
  85 own. (For example, a Radix sort can be faster than O(n log n), but can't be
  86 used for all keys and has larger overheads.)
  87
  88 We are not averse to B<changing> the sort algorithm, but we don't see the
  89 benefit in offering the choice of two general purpose implementations.
  90
  91 =head1 CAVEATS
  92
  93 The function C<sort::current()> was provided to report the current state of
  94 the sort pragmata. This function was not exported, and there is no code to
  95 call it on CPAN. It is now deprecated, and will warn by default.
  96
  97 As we no longer store any sort "state", it can no longer return the correct
  98 value, so it will always return the string C<stable>, as this is consistent
  99 with what we actually have implemented.
 100
 101 =cut