.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Algorithm::Pair::Swiss 3"
.TH Algorithm::Pair::Swiss 3 "2008-01-05" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Algorithm::Pair::Swiss \- Generate unique pairings for tournaments
.SH "VERSION"
.IX Header "VERSION"
This document describes Algorithm::Pair::Swiss version 0.14
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Algorithm::Pair::Swiss;
.Ve
.PP
.Vb 1
\&    my $pairer = Algorithm::Pair::Swiss->new;
.Ve
.PP
.Vb 1
\&    $pairer->parties(1,2,3,4);
.Ve
.PP
.Vb 1
\&    @round_1 = $pairer->pairs;
.Ve
.PP
.Vb 1
\&    $pairer->exclude(@round_1);
.Ve
.PP
.Vb 1
\&    @round_2 = $pairer->pairs;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module was created as an alternative for Algorithm::Pair::Best, which
probably offers more control over the pairings, in particular regarding
ensuring the highest overal quality of pairings. Algorithm::Pair::Swiss is
sort of dumb in this regard, but uses a slightly more intuitive interface
and an algorithm that should perform noticably faster. The module was
primarily designed based on the Swiss rounds system used for Magic: The
Gathering tournaments.
.PP
After creating an Algorithm::Pair::Swiss\->\fBnew\fR object, use the \fBparties\fR
method to supply a list of parties (players or teams) to be paired. At any
time the \fBexclude\fR method can be used to indicate which pairs shouldn't be
generated (probably because they've already been paired in an earlier round).        
.PP
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.
.PP
To influence the sort order, use objects as parties and overload either the
\&\fBcmp\fR or \fB0+\fR operators in the object class to sort as desired.
.PP
Algorithm::Pair::Swiss\->\fBpairs\fR 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.
.PP
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.
.PP
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:
.IP "\- make sure it is defined (not undef)" 1
.IX Item "- make sure it is defined (not undef)"
.PD 0
.IP "\- make sure it is defined when stringified" 1
.IX Item "- make sure it is defined when stringified"
.IP "\- make sure each is a non-empty string when stringified" 1
.IX Item "- make sure each is a non-empty string when stringified"
.IP "\- make sure each is unique when stringified" 1
.IX Item "- make sure each is unique when stringified"
.PD
.PP
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).        
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $pairer\fR = \fBAlgorithm::Pair::Swiss\->new\fR( \f(CW@parties )" 4
.el .IP "my \f(CW$pairer\fR = \fBAlgorithm::Pair::Swiss\->new\fR( \f(CW@parties\fR )" 4
.IX Item "my $pairer = Algorithm::Pair::Swiss->new( @parties )"
A \fBnew\fR Algorithm::Pair::Swiss object is used to generate pairings.
Optionally \f(CW@parties\fR can be given when instantiating the object. This is
the same as using the \fBparties\fR method described below.
.ie n .IP "$pairer\->\fBparties\fR( @parties )" 4
.el .IP "$pairer\->\fBparties\fR( \f(CW@parties\fR )" 4
.IX Item "$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 \fBcmp\fR operator overload in the
class your parties belong to.
.ie n .IP "@pairs = $pairer\fR\->\fBpairs" 4
.el .IP "@pairs = \f(CW$pairer\fR\->\fBpairs\fR" 4
.IX Item "@pairs = $pairer->pairs"
Returns the best pairings found as a list of arrayref's, each containing
one pair of parties.
.ie n .IP "$pair\->\fBexclude\fR( @pairs )" 4
.el .IP "$pair\->\fBexclude\fR( \f(CW@pairs\fR )" 4
.IX Item "$pair->exclude( @pairs )"
Excludes the given pairs from further pairing. The \f(CW@pairs\fR 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 \f(CW$pair\fR\->\fBpairs\fR. The selection given is added
to previously excluded pairs.
.Sp
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 \s-1MTG\s0 terms, being paired with 'undef' would mean getting a bye
(and getting the full three points for that round as a consequence).
.ie n .IP "$pair\->\fBdrop\fR( @parties )" 4
.el .IP "$pair\->\fBdrop\fR( \f(CW@parties\fR )" 4
.IX Item "$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.
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs that I know of...
.PP
The module's performance will probably break down 
if you use 1000+ parties and 100+ rounds though...
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
Perl 5.6.0 or later (though it will probably work ok with earlier versions)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "o Algorithm::Pair::Best" 1
.IX Item "Algorithm::Pair::Best"
The \fBAlgorithm::Pair::Best\fR module if you need more control
over your pairings.
.IP "o overload" 1
.IX Item "overload"
For proper results you'll want to overload the \fBcmp\fR and/or \fB0+\fR
operators of the objects you're using as parties. This will allow
for the correct sort order, so higher-ranked parties are matched
better.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Reid Augustin for by \fBAlgorithm::Pair::Best\fR
.PP
Elizabeth Mattijsen for giving me some pointers on getting this module CPAN\-ready.
.SH "AUTHOR"
.IX Header "AUTHOR"
Gilion Goudsmit, <ggoudsmit@shebang.nl>
.PP
I can also be found on http://www.perlmonks.org as Gilimanjaro. You can direct 
any questions concerning this module there as well.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Gilion Goudsmit
.PP
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.