5 # The hints for pp_sort are now stored in $^H{sort}; older versions
6 # of perl used the global variable $sort::hints. -- rjh 2005-12-19
8 $sort::stable_bit = 0x00000100;
9 $sort::unstable_bit = 0x00000200;
17 Carp::croak("sort pragma requires arguments");
21 while ($_ = shift(@_)) {
23 $^H{sort} |= $sort::stable_bit;
24 $^H{sort} &= ~$sort::unstable_bit;
25 } elsif ($_ eq 'defaults') {
29 Carp::croak("sort: unknown subpragma '$_'");
38 Carp::croak("sort pragma requires arguments");
41 no warnings 'uninitialized'; # bitops would warn
42 while ($_ = shift(@_)) {
44 $^H{sort} &= ~$sort::stable_bit;
45 $^H{sort} |= $sort::unstable_bit;
48 Carp::croak("sort: unknown subpragma '$_'");
56 push @sort, 'stable' if $^H{sort} & $sort::stable_bit;
66 sort - perl pragma to control sort() behaviour
70 use sort 'stable'; # guarantee stability
71 use sort 'defaults'; # revert to default behavior
72 no sort 'stable'; # stability not important
76 $current = sort::current(); # identify prevailing pragmata
81 With the C<sort> pragma you can control the behaviour of the builtin
84 A stable sort means that for records that compare equal, the original
85 input ordering is preserved.
86 Stability will matter only if elements that compare equal can be
87 distinguished in some other way. That means that simple numerical
88 and lexical sorts do not profit from stability, since equal elements
89 are indistinguishable. However, with a comparison such as
91 { substr($a, 0, 3) cmp substr($b, 0, 3) }
93 stability might matter because elements that compare equal on the
94 first 3 characters may be distinguished based on subsequent characters.
96 Whether sorting is stable by default is an accident of implementation
97 that can change (and has changed) between Perl versions.
98 If stability is important, be sure to
103 The C<no sort> pragma doesn't
104 I<forbid> what follows, it just leaves the choice open. Thus, after
108 sorting may happen to be stable anyway.
112 As of Perl 5.10, this pragma is lexically scoped and takes effect
113 at compile time. In earlier versions its effect was global and took
114 effect at run-time; the documentation suggested using C<eval()> to
115 change the behaviour:
117 { eval 'no sort "stable"'; # stability not wanted
118 print sort::current . "\n";
120 eval 'use sort "defaults"'; # clean up, for others
122 { eval 'use sort qw(defaults stable)'; # force stability
123 print sort::current . "\n";
125 eval 'use sort "defaults"'; # clean up, for others
128 Such code no longer has the desired effect, for two reasons.
129 Firstly, the use of C<eval()> means that the sorting algorithm
130 is not changed until runtime, by which time it's too late to
131 have any effect. Secondly, C<sort::current> is also called at
132 run-time, when in fact the compile-time value of C<sort::current>
133 is the one that matters.
135 So now this code would be written:
137 { no sort "stable"; # stability not wanted
139 BEGIN { $current = sort::current; }
142 # Pragmas go out of scope at the end of the block
144 { use sort qw(defaults stable); # force stability
146 BEGIN { $current = sort::current; }