=head1 NAME

Sort::KeyExtract - Sort using a user-specified key extractor

=head1 SYNOPSIS

 use Sort::KeyExtract;

 my %months = (
     January => 1,
     February => 2,
     March => 3,
     April => 4,
     May => 5,
 );
 
 my @array = (
         'District conferences will happen in =February (20-21)',
         'Coat sales are in =January.',
         'In =May, we meet with the directors.',
         '=March will see new matrices form.',
         'Taxes are to be paid in =April.',
     );
 
 my $sorted = sort_keys {
         code => sub { s/=(\w+)/$1/ && $months{$1} },
     }, \@array;
 
 print "$_\n" for (@$sorted);


=head1 DESCRIPTION

This module allows the programmer to easily sort an array
using key-extraction code that he or she specifies. The 
extraction code can be as complicated or simple as the
programmer desires.

A single function is exported: C<sort-keys>. C<Sort-keys> is called
like so:

  my $sorted_reference = sort_keys \%sort_options, \@array_to_sort;

C<Sort-keys> always wants a reference to the array to sort,
and it always returns a reference to the sorted array. The
original array is unmodified unless the user's
key-extraction code performs some modifications.

=head1 SORT OPTIONS

=over

=item code

This option is required. You would specify the code
reference or subroutine to execute using the C<code> option,
e.g.:

  my $sorted_ref = sort_keys {
      code => sub { $_ },
      }, \@array_to_sort;

=item numbers

By default, extracted keys are sorted as strings. This option
tells C<sort-keys> to treat the keys as numbers. 

  my $sorted_ref = sort_keys {
      numbers => 1,
      code => sub { $_ },
      }, \@array_to_sort;

=item reverse

This option tells C<sort-keys> to sort the elements in
reverse order, i.e. descending order.

=item keeprefs

To avoid copying potentially large amounts of data,
C<sort-keys> sorts B<references> to the original array
elements--not the elements themselves. 

As a result, right after the references have been sorted,
C<sort-keys> has to decide whether to return copies of the
original elements or to return the references. The C<keeprefs>
option tells C<sort-keys> not to dereference the sorted
array elements before returning them.

=back

=head1 EXAMPLES

Do what sort does by default:

 my $sorted_ref = sort_keys { code => sub { $_ } },
 \@array_to_sort;

Sort numerically:

 my @array_to_sort = qw(Yahoo_2600 Google_4541 Lycos_611);
 my $sorted_ref = sort_keys {
        numbers => 1,
        code => sub { /(\d+)/ && $1 },
    }, \@array_to_sort;

Sort numerically, keep references and print out the data:

 my @array_to_sort = qw(Yahoo_2600 Google_4541 Lycos_611);
 my $sorted_ref = sort_keys {
        numbers => 1,
        keeprefs => 1,
        code => sub { /(\d+)/ && $1 },
    }, \@array_to_sort;

 print "${$_}\n" for (@$sorted_ref);



=head1 BUGS

None discovered so far--but that's probably because you
haven't started looking yet :-)

 E-mail bug reports to
 mumia.w.18.spam+nospam.bug [at] earthlink.net


=head1 AUTHOR

 Mumia Wotse
 Copyright (C) 2006 Mumia Wotse
 <mumia.w.18.spam+nospam.bug [at] earthlink.net>

This program and its documentation are under the GPL.

This program and its documentation are provided without
any warranty--not even a warranty of merchantability
or fitness for a particular purpose. Read KeyExtract.LICENSE.txt
for the details.

=cut