/ 
Sort-BySpec-0.040
River stage three • 14 direct dependents • 799 total dependents
/ Sort::BySpec

NAME

Sort::BySpec - Sort array (or create a list sorter) according to specification

VERSION

This document describes version 0.040 of Sort::BySpec (from Perl distribution Sort-BySpec), released on 2021-05-01.

SYNOPSIS

use Sort::BySpec qw(sort_by_spec cmp_by_spec);

my $sorter = sort_by_spec(spec => [
    # put odd numbers first, in ascending order
    qr/[13579]\z/ => sub { $_[0] <=> $_[1] },

    # then put specific numbers here, in this order
    4, 2, 42,

    # put even numbers last, in descending order
    sub { $_[0] % 2 == 0 } => sub { $_[1] <=> $_[0] },
]);

my @res = $sorter->(1..15, 42);
# => (1,3,5,7,9,11,13,15,  4,2,42,   14,12,10,8,6)

DESCRIPTION

This package provides a more powerful alternative to Sort::ByExample. Unlike in `Sort::ByExample` where you only provide a single array of example, you can specify multiple examples as well as regex or matcher subroutine coupled with sort rules. With this, you can more precisely specify how elements of your list should be ordered. If your needs are not met by Sort::ByExample, you might want to consider this package. The downside is performance penalty, especially when your list is large.

To sort using Sort::BySpec, you provide a "spec" which is an array of strings, regexes, or coderefs to match against elements of your list to be sorted. In the simplest form, the spec contains only a list of examples:

my $sorter = sort_by_spec(spec => ["foo", "bar", "baz"]); # [1]

and this is equivalent to Sort::ByExample:

my $sorter = sbe(["foo", "bar", "baz"]);

You can also specify regex to match elements. This is evaluated after strings, so this work:

my $sorter = sort_by_spec(spec => [qr/o/, "foo", "bar", "baz", qr/a/]);
my @list = ("foo", "food", "bar", "back", "baz", "fool", "boat");
my @res = $sorter->(@list);
# => ("food","boat","fool",   "foo","bar","baz",   "back")

Right after a regex, you can optionally specify a sort subroutine to tell how to sort elements matching that regex, for example:

my $sorter = sort_by_spec(spec => [
    qr/o/ => sub { $_[0] cmp $_[1] },
    "foo", "bar", "baz",
    qr/a/
]);

# the same list @list above will now be sorted into:
# => ("boat","food","fool",   "foo","bar","baz",   "back")

Note that instead of $a and $b, you should use $_[0] and $_[1] respectively. This avoids the package scoping issue of $a and $b, making your sorter subroutine works everywhere without any special workaround.

Finally, aside from strings and regexes, you can also specify a coderef matcher for more complex matching. Just like in the case of regex, right after the coderef you can optionally specify a sort subroutine (another coderef) to tell how to sort matching elements. For example:

my $sorter = sort_by_spec(spec => [
    # put odd numbers first, in ascending order
    sub { $_[0] % 2 } => sub { $_[0] <=> $_[1] },

    # then put specific numbers here, in this order
    4, 2, 42,

    # put even numbers last, in descending order
    sub { $_[0] % 2 == 0 } => sub { $_[1] <=> $_[0] },
]);

my @res = $sorter->(1..15, 42);
# => (1,3,5,7,9,11,13,15,  4,2,42,   14,12,10,8,6)

FUNCTIONS

cmp_by_spec

Usage:

cmp_by_spec(%args) -> code

Create a compare subroutine to be used in sort().

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • reverse => bool

    If set to true, will reverse the sort order.

  • spec* => array

  • xform => code

    Code to return sort keys from data elements.

    This is just like xform in Sort::ByExample.

Return value: (code)

sort_by_spec

Usage:

sort_by_spec(%args) -> array|code

Sort array (or create a list sorter) according to specification.

Examples:

  • Sort according to a sequence of scalars (like Sort::ByExample):

    sort_by_spec(
  spec  => ["foo", "bar", "baz"],
  array => [1, 2, 3, "bar", "a", "b", "c", "baz"]
);

    Result:

    ["bar", "baz", 1, 2, 3, "a", "b", "c"]

  • Like previous example, but reversed:

    sort_by_spec(
  spec    => ["foo", "bar", "baz"],
  array   => [1, 2, 3, "bar", "a", "b", "c", "baz"],
  reverse => 1
);

    Result:

    ["bar", "baz", 1, 2, 3, "a", "b", "c"]

  • Put integers first (in descending order), then a sequence of scalars, then others (in ascending order):

    sort_by_spec(
  spec  => [
             qr/\A\d+\z/,
             sub { $_[1] <=> $_[0] },
             "foo",
             "bar",
             "baz",
             qr//,
             sub { $_[0] cmp $_[1] },
           ],
  array => ["qux", "b", "a", "bar", "foo", 1, 10, 2]
);

    Result:

    [10, 2, 1, "foo", "bar", "a", "b", "qux"]

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • array => array

  • reverse => bool

    If set to true, will reverse the sort order.

  • spec* => array

  • xform => code

    Code to return sort keys from data elements.

    This is just like xform in Sort::ByExample.

Return value: Sorted array, or sort coderef (array|code)

If array is specified, will returned the sorted array. If array is not specified in the argument, will return a sort subroutine that can be used to sort a list and return the sorted list.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Sort-BySpec.

SOURCE

Source repository is at https://github.com/perlancar/perl-Sort-BySpec.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Sort-BySpec

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Sort::ByExample

Bencher::Scenario::SortBySpec

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2017, 2015 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.