NAME

Set::Partition - Enumerate all arrangements of a set in fixed subsets

VERSION

This document describes version 0.03 of Set::Partition, released 2006-10-11.

SYNOPSIS

  use Set::Partition;

  my $s = Set::Partition->new(
    list      => [qw(a b c d e)],
    partition => [2, 3],
  );
  while (my $p = $s->next) {
    print join( ' ', map { "(@$_)" } @$p ), $/;
  }
  # produces
  (a b) (c d e)
  (a c) (b d e)
  (a d) (b c e)
  (a e) (b c d)
  (b c) (a d e)
  (b d) (a c e)
  (b e) (a c d)
  (c d) (a b e)
  (c e) (a b d)
  (d e) (a b c)

  # or with a hash
  my $s = Set::Partition->new(
    list      => { b => 'bat', c => 'cat', d => 'dog' },
    partition => [2, 1],
  );
  while (my $p = $s->next) {
    ...
  }

DESCRIPTION

Set::Partition takes a list or hash of elements and a list numbers that represent the sizes of the partitions into which the list of elements should be arranged.

The resulting object can then be used as an iterator which returns a reference to an array of lists, that represents the original list arranged according to the given partitioning. All possible arrangements are returned, and the object returns undef when the entire combination space has been exhausted.

METHODS

new

Creates a new Set::Partition object. A set of key/value parameters can be supplied to control the finer details of the object's behaviour.

list, the list of elements in the set.

partition, the list of integers representing the size of the partitions used to arrange the set. The sum should be equal to the number of elements given by list. If it less than the number of elements, a dummy partition will be added to equalise the count. This partition will be returned during iteration. If the sum is greater than the number of elements, new() will croak with a fatal error.

next

Returns the next arrangement of subsets, or undef when all arrangements have been enumerated.

reset

Resets the object, which causes it to enumerate the arrangements from the beginning.

  $p->reset; # begin again

DIAGNOSTICS

sum of partitions (%d) exceeds available elements (%d)

A list of partition sizes (for instance, 2, 3, 4) was given, along with a list to partition (for instance, containing 8 elements), however, the number of elements required to fill the different partitions (9) exceeds the number available in the source list (8).

NOTES

The order within a set is unimportant, thus, if

  (a b) (c d)

is produced, then the following arrangement will never be encountered:

  (a b) (d c)

On the other hand, the order of the sets is important, which means that the following arrangement will be encountered:

  (c d) (a b)

SEE ALSO

Algorithm::Combinatorics

Permutations, combinations, derangements and more; all you need for your set transformations.

BUGS

Using a partition of length 0 is valid, although you get back an undef, rather than an empty array. This could be construed as a bug.

Please report all bugs at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Set-Partition|rt.cpan.org

Make sure you include the output from the following two commands:

  perl -MSet::Partition -le 'print Set::Partition::VERSION'
  perl -V

ACKNOWLEDGEMENTS

Ken Williams suggested the possibility to use a hash as a source for partitioning.

AUTHOR

David Landgren, copyright (C) 2006. All rights reserved.

http://www.landgren.net/perl/

If you (find a) use this module, I'd love to hear about it. If you want to be informed of updates, send me a note. You know my first name, you know my domain. Can you guess my e-mail address?

LICENSE

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

cpanm Set::Partition

perl -MCPAN -e shell
install Set::Partition