The file is the README for Set::Partition version 0.02

INSTALLATION

perl Makefile.PL
make
make test
make install

TESTING

This module requires the following modules for thorough testing:

    Test::More
    Test::Pod
    Test::Pod::Coverage

It can also make use of Devel::Cover if available.

UNINSTALLATION

This is a pure-Perl module. The following one-liner should print
out the canonical path of the file:

  perl -MSet::Partition -le 'print $INC{"Set/Partition.pm"}'

Just delete this file. There is also the question of the man page.
Finding that is left as an exercise to the reader.

USAGE

use Set::Partition;

my $s = Set::Partition->new(
    list      => [1..20],
    partition => [6, 5, 3, 3, 3],
);

while (my $p = $s->next) {
    print join( ' ', map { "(@$_)" } @$p ), $/;
}

IMPLEMENTATION

The partitioning algorithm works as follows:

A state array maintains the information necessary
to store which elements belong to which
partition. Each time a new partition is called for,
with next(), the state array is perturbed to generate
a new partition arrangement, until all arrangements
have been returned.

Consider a list of five elements qw(a e i o u), to
be partitioned as sets of 2, 1 and 2. The first
time next() is called, there is no state array.
The state array is therefore generated, to describe
the following state of affairs:

The first two elements (a e) are stored in the
first partition. The second two elements (i o)
are stored in the second partition. The final
element (u) is stored in the last partition.

Therefore, the state array looks as follows

  [0 0 1 1 2]

It is then a simple matter of stepping down the
list of given values, and the state array to
produce the output:
  
  [0 0 1 1 2]
  [a e i o u]

The following structure is generated:

  [
    [a e], # 0
    [i o], # 1
    [u],   # 2
  ]

The following call to next() generates a new
arrangement as follow: the list is scanned from
right to left, starting at the second rightmost
element. If it is smaller than the element to
the right, these elements are swapped.

  [0 0 1 1 2]
         ^    (swap with the 2 to the right)
  [0 0 1 2 1]

This gives the following result:

  [0 0 1 2 1]
  [a e i o u]

  [
    [a e], # 0
    [i u], # 1
    [o],   # 2
  ]

The next result is achieved as follows:

  [0 0 1 2 1]
         ^    (2 is greater than 1, no swap)
  [0 0 1 2 1]
       ^      (1 is greater than 2, swap)
  [0 0 2 1 1]
  [a e i o u]

gives

  [
    [a e], # 0
    [o u], # 1
    [i],   # 2
  ]

The next arrangement requires more care.

  [0 0 2 1 1]
         ^
  [0 0 2 1 1]
       ^
  [0 0 2 1 1]
     ^

At this point, the 0 and 2 need to be swapped, however,
the difference of 2-0 is greater than 1, so the 0 is
swapped with the rightmost smallest number larger
than itself (1):

  [0 0 2 1 1]
     ^     ^  (swap)
  [0 1 2 1 0]
           ^  (swap)

And then the rightmost numbers beyond the first number
used in the swap are reversed

  [0 1 2 1 0]
       ^ ^ ^  (reverse)
  [0 1 0 1 2]
  [a e i o u]

which gives

  [
    [a i], # 0
    [e o], # 1
    [u],   # 2
  ]

The process continues in this manner until the final
arrangement is obtained

  [2 1 1 0 0]
  [a e i o u]

which gives

  [
    [o u], # 0
    [e i], # 1
    [a],   # 2
  ]

At this point, no number to the right is larger than
any number to the left, and the process is complete.

The reset() function simply deletes the state array.
The subsequent call to next() will initialise it to
the start arrangement.

STATUS

This module is under active development.

AUTHOR

David Landgren

COPYRIGHT

This module is copyright (C) David Landgren 2006.
All rights reserved.

LICENSE

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