NAME

VERSION

SYNOPSIS

    use Algorithm::Pair::Swiss;

    my $pairer = Algorithm::Pair::Swiss->new;

    $pairer->parties(1,2,3,4);

    @round_1 = $pairer->pairs;

    $pairer->exclude(@round_1);

    @round_2 = $pairer->pairs;

DESCRIPTION

After creating an Algorithm::Pair::Swiss->new object, use the parties method to supply a list of parties (players or teams) to be paired. At any time the exclude method can be used to indicate which pairs shouldn't be generated (probably because they've already been paired in an earlier round).

The list of parties is sorted and the pairer tries to find a set of pairs that respects the exclude list, and tries to pair the parties that appear first in the sorted list with each other most aggresively.

To influence the sort order, use objects as parties and overload either the cmp or 0+ operators in the object class to sort as desired.

Algorithm::Pair::Swiss->pairs explores the parties and returns the first pairing solution which satisfies the excludes. Because it doesn't exhaustively try all possible solutions, performance is generally pretty reasonable.

For a large number of parties, it is generally easy to find a non-excluded pair, and for a smaller number of parties traversal of the possible pairs is done reasonably fast.

This module uses the parties as keys in a hash, and uses the empty string ('') as a special case in this same hash. For this reason, please observe the following restrictions regarding your party values:

- make sure it is defined (not undef)

- make sure it is defined when stringified

- make sure each is a non-empty string when stringified

- make sure each is unique when stringified

All the restrictions on the stringifications are compatible with the perl's default stringification of objects, and should be safe for any stringification which returns a unique party-identifier (for instance a primary key from a Class::DBI object).

METHODS

my $pairer = Algorithm::Pair::Swiss->new( @parties )

A new Algorithm::Pair::Swiss object is used to generate pairings. Optionally @parties can be given when instantiating the object. This is the same as using the parties method described below.

$pairer->parties( @parties )

Provides the pairer with a complete list of all individuals that can be paired. If no parties are specified, it returns the sorted list of all parties. This allows you to use this method to extract 'rankings' if you happen to have implemented a cmp operator overload in the class your parties belong to.

@pairs = $pairer->pairs

Returns the best pairings found as a list of arrayref's, each containing one pair of parties.

$pair->exclude( @pairs )

Excludes the given pairs from further pairing. The @pairs array should consist of a list of references to arrays, each containing the two parties of that pair. This means you can easily feed it the output of a previous call to $pair->pairs. The selection given is added to previously excluded pairs.

If there was an odd number of parties, the lowest ranked party will be paired with 'undef', unless it has already been paired with 'undef'. In that case, the second-lowest ranked party will get that pairing. Etcetera, etcetera. 'Lowest-ranked' is defined as being last in the party-list after sorting. In MTG terms, being paired with 'undef' would mean getting a bye (and getting the full three points for that round as a consequence).

$pair->drop( @parties )

Excludes the given parties from further pairing. The given parties will be removed from the internal parties list and won't be returned by the parties method anymore. This method is usually used when a participant has decided to quit playing.

EXPORT

BUGS AND LIMITATIONS

The module's performance will probably break down if you use 1000+ parties and 100+ rounds though...

REQUIREMENTS

SEE ALSO

o Algorithm::Pair::Best

The Algorithm::Pair::Best module if you need more control over your pairings.

o overload

For proper results you'll want to overload the cmp and/or 0+ operators of the objects you're using as parties. This will allow for the correct sort order, so higher-ranked parties are matched better.

ACKNOWLEDGEMENTS

Elizabeth Mattijsen for giving me some pointers on getting this module CPAN-ready.

AUTHOR

I can also be found on http://www.perlmonks.org as Gilimanjaro. You can direct any questions concerning this module there as well.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.