Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SET::PARTITION (3)

.ds Aq ’


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



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


  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) {


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.


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.

<B>listB>, the list of elements in the set.

<B>partitionB>, 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 <B>listB>. 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


    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).


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)


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


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 <|>

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

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


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


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

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?


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 PARTITION (3) 2006-10-11

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.