view release on metacpan or  search on metacpan

lib/Algorithm/Pair/Best2.pm  view on Meta::CPAN

    @new_pairs = $pair->pick( [ window ] );

=head1 DESCRIPTION

This is a re-write of Algorithm::Pair::Best.  The interface is simplified
and the implementation is significantly streamlined.

After creating an Algorithm::Pair::Best2 object (with -E<gt>B<new>), B<add>
items to the list of items (i.e: players) to be paired.  The final list
must contain an even number of items or B<pick>ing the pairs will throw an
exception.

Algorithm::Pair::Best2-E<gt>B<pick> explores all combinations of items and
returns the pairing list with the best (lowest) score.  This can be an
expensive proposition - the number of combinations goes up very fast with
respect to the number of items:

    items combinations
      2         1       (1)
      4         3       (1 * 3)

lib/Algorithm/Pair/Best2.pm  view on Meta::CPAN

Returns the best pairing found using the sliding window technique as
discussed in DESCRIPTION above.  B<window> is the number of pairs in the
sliding window.  If no B<window> argument is passed, the B<window> selected
in the B<new>, or the default value is used.

B<pick> returns the list (or a reference to the list in scalar context) of
items in pairing order: new_pair[0] is paired to new_pair[1], new_pair[2]
to new_pair[3], etc.

If the number of items in the list (from B<add>) is not even, an exception
is thrown.

=back

=head1 OPTIONS

The B<-E<gt>new> method accepts the following options:

=over 4

=item B<window> => number of pairs

lib/Algorithm/Pair/Best2.pm  view on Meta::CPAN

also be set by passing a B<window> argument to B<pick>.

Default: 5

=item B<scoreSub> => reference to scoring callback

The callback is called as B<scoreSub>(item_0, item_1), where item_0 and item_1
are members of the list created by B<add>ing items.  The callback must
return a positive number representing the 'badness' of this pairing.  A
good pairing should have a number closer to 0 than a worse pairing.  If
B<scoreSub> returns a negative number, an exception is thrown.

B<scoreSub>(A, B) should be equal to B<scoreSub>(B, A).  B<scoreSub>(A, B)
is called only one time (for any particular A and B), and the result is
cached.  B<scoreSub>(B, A) is never called.

Note that scores are always positive (Algorithm::Pair::Best2 searches for
the lowest combined score).

Default: a subroutine that throws an exception.

=item B<progress> => reference to progress callback

Each time a pair is finalized in the B<pick> routine, the
B<progress>($item_0, $item_1, $idx_0, $idx_1) callback is called where
$item_0 and $item_1 are the most recently finalized pair, and $idx_0, $idx_1
are their indices in $pair's B<items> array:

  progress => sub {
    my ($item_0, $item_1, $idx_0, $idx_1) = @_;