=over

=item sort SUBNAME LIST
X<sort>

=item sort BLOCK LIST

=item sort LIST

In list context, this sorts the LIST and returns the sorted list value.
In scalar context, the behaviour of L<C<sort>|/sort SUBNAME LIST> is
undefined.

If SUBNAME or BLOCK is omitted, L<C<sort>|/sort SUBNAME LIST>s in
standard string comparison
order.  If SUBNAME is specified, it gives the name of a subroutine
that returns a numeric value less than, equal to, or greater than C<0>,
depending on how the elements of the list are to be ordered.  (The
C<< <=> >> and C<cmp> operators are extremely useful in such routines.)
SUBNAME may be a scalar variable name (unsubscripted), in which case
the value provides the name of (or a reference to) the actual
subroutine to use.  In place of a SUBNAME, you can provide a BLOCK as
an anonymous, in-line sort subroutine.

If the subroutine's prototype is C<($$)>, the elements to be compared are
passed by reference in L<C<@_>|perlvar/@_>, as for a normal subroutine.
This is slower than unprototyped subroutines, where the elements to be
compared are passed into the subroutine as the package global variables
C<$a> and C<$b> (see example below).

If the subroutine is an XSUB, the elements to be compared are pushed on
to the stack, the way arguments are usually passed to XSUBs.  C<$a> and
C<$b> are not set.

The values to be compared are always passed by reference and should not
be modified.

You also cannot exit out of the sort block or subroutine using any of the
loop control operators described in L<perlsyn> or with
L<C<goto>|/goto LABEL>.

When L<C<use locale>|locale> (but not C<use locale ':not_characters'>)
is in effect, C<sort LIST> sorts LIST according to the
current collation locale.  See L<perllocale>.

L<C<sort>|/sort SUBNAME LIST> returns aliases into the original list,
much as a for loop's index variable aliases the list elements.  That is,
modifying an element of a list returned by L<C<sort>|/sort SUBNAME LIST>
(for example, in a C<foreach>, L<C<map>|/map BLOCK LIST> or
L<C<grep>|/grep BLOCK LIST>)
actually modifies the element in the original list.  This is usually
something to be avoided when writing clear code.

Historically Perl has varied in whether sorting is stable by default.
If stability matters, it can be controlled explicitly by using the
L<sort> pragma.

Examples:

    # sort lexically
    my @articles = sort @files;

    # same thing, but with explicit sort routine
    my @articles = sort {$a cmp $b} @files;

    # now case-insensitively
    my @articles = sort {fc($a) cmp fc($b)} @files;

    # same thing in reversed order
    my @articles = sort {$b cmp $a} @files;

    # sort numerically ascending
    my @articles = sort {$a <=> $b} @files;

    # sort numerically descending
    my @articles = sort {$b <=> $a} @files;

    # this sorts the %age hash by value instead of key
    # using an in-line function
    my @eldest = sort { $age{$b} <=> $age{$a} } keys %age;

    # sort using explicit subroutine name
    sub byage {
        $age{$a} <=> $age{$b};  # presuming numeric
    }
    my @sortedclass = sort byage @class;

    sub backwards { $b cmp $a }
    my @harry  = qw(dog cat x Cain Abel);
    my @george = qw(gone chased yz Punished Axed);
    print sort @harry;
        # prints AbelCaincatdogx
    print sort backwards @harry;
        # prints xdogcatCainAbel
    print sort @george, 'to', @harry;
        # prints AbelAxedCainPunishedcatchaseddoggonetoxyz

    # inefficiently sort by descending numeric compare using
    # the first integer after the first = sign, or the
    # whole record case-insensitively otherwise

    my @new = sort {
        ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
                            ||
                    fc($a)  cmp  fc($b)
    } @old;

    # same thing, but much more efficiently;
    # we'll build auxiliary indices instead
    # for speed
    my (@nums, @caps);
    for (@old) {
        push @nums, ( /=(\d+)/ ? $1 : undef );
        push @caps, fc($_);
    }

    my @new = @old[ sort {
                           $nums[$b] <=> $nums[$a]
                                    ||
                           $caps[$a] cmp $caps[$b]
                         } 0..$#old
                  ];

    # same thing, but without any temps
    my @new = map { $_->[0] }
           sort { $b->[1] <=> $a->[1]
                           ||
                  $a->[2] cmp $b->[2]
           } map { [$_, /=(\d+)/, fc($_)] } @old;

    # using a prototype allows you to use any comparison subroutine
    # as a sort subroutine (including other package's subroutines)
    package Other;
    sub backwards ($$) { $_[1] cmp $_[0]; }  # $a and $b are
                                             # not set here
    package main;
    my @new = sort Other::backwards @old;

    ## using a prototype with function signature
    use feature 'signatures';
    sub function_with_signature :prototype($$) ($one, $two) {
        return $one <=> $two
    }

    my @new = sort function_with_signature @old;

    # guarantee stability
    use sort 'stable';
    my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;

Warning: syntactical care is required when sorting the list returned from
a function.  If you want to sort the list returned by the function call
C<find_records(@key)>, you can use:

    my @contact = sort { $a cmp $b } find_records @key;
    my @contact = sort +find_records(@key);
    my @contact = sort &find_records(@key);
    my @contact = sort(find_records(@key));

If instead you want to sort the array C<@key> with the comparison routine
C<find_records()> then you can use:

    my @contact = sort { find_records() } @key;
    my @contact = sort find_records(@key);
    my @contact = sort(find_records @key);
    my @contact = sort(find_records (@key));

C<$a> and C<$b> are set as package globals in the package the sort() is
called from.  That means C<$main::a> and C<$main::b> (or C<$::a> and
C<$::b>) in the C<main> package, C<$FooPack::a> and C<$FooPack::b> in the
C<FooPack> package, etc.  If the sort block is in scope of a C<my> or
C<state> declaration of C<$a> and/or C<$b>, you I<must> spell out the full
name of the variables in the sort block :

   package main;
   my $a = "C"; # DANGER, Will Robinson, DANGER !!!

   print sort { $a cmp $b }               qw(A C E G B D F H);
                                          # WRONG
   sub badlexi { $a cmp $b }
   print sort badlexi                     qw(A C E G B D F H);
                                          # WRONG
   # the above prints BACFEDGH or some other incorrect ordering

   print sort { $::a cmp $::b }           qw(A C E G B D F H);
                                          # OK
   print sort { our $a cmp our $b }       qw(A C E G B D F H);
                                          # also OK
   print sort { our ($a, $b); $a cmp $b } qw(A C E G B D F H);
                                          # also OK
   sub lexi { our $a cmp our $b }
   print sort lexi                        qw(A C E G B D F H);
                                          # also OK
   # the above print ABCDEFGH

With proper care you may mix package and my (or state) C<$a> and/or C<$b>:

   my $a = {
      tiny   => -2,
      small  => -1,
      normal => 0,
      big    => 1,
      huge   => 2
   };

   say sort { $a->{our $a} <=> $a->{our $b} }
       qw{ huge normal tiny small big};

   # prints tinysmallnormalbighuge

C<$a> and C<$b> are implicitly local to the sort() execution and regain their
former values upon completing the sort.

Sort subroutines written using C<$a> and C<$b> are bound to their calling
package. It is possible, but of limited interest, to define them in a
different package, since the subroutine must still refer to the calling
package's C<$a> and C<$b> :

   package Foo;
   sub lexi { $Bar::a cmp $Bar::b }
   package Bar;
   ... sort Foo::lexi ...

Use the prototyped versions (see above) for a more generic alternative.

The comparison function is required to behave.  If it returns
inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
sometimes saying the opposite, for example) the results are not
well-defined.

Because C<< <=> >> returns L<C<undef>|/undef EXPR> when either operand
is C<NaN> (not-a-number), be careful when sorting with a
comparison function like C<< $a <=> $b >> any lists that might contain a
C<NaN>.  The following example takes advantage that C<NaN != NaN> to
eliminate any C<NaN>s from the input list.

    my @result = sort { $a <=> $b } grep { $_ == $_ } @input;

In this version of F<perl>, the C<sort> function is implemented via the
mergesort algorithm.

=back