/ 
Set-CartesianProduct-Lazy-0.004
River stage zero No dependents
/ Set::CartesianProduct::Lazy

NAME

Set::CartesianProduct::Lazy - lazily calculate the tuples of a cartesian-product

VERSION

version 0.004

SYNOPSIS

my @a   = qw( foo bar baz bah );
my @b   = qw( wibble wobble weeble );
my @c   = qw( nip nop );

my $cpl = Set::CartesianProduct::Lazy->new( \@a, \@b, \@c );

my $tuple;

$tuple = $cpl->get(0);   # [ qw( foo wibble nip ) ]

$tuple = $cpl->get(21);  # [ qw( bah wobble nop ) ]

$tuple = $cpl->get(7);   # [ qw( bar wobble nip ) ]

$cpl->count;             # 24
$cpl->last_idx;          # 23

DESCRIPTION

If you have some number of arrays, say like this:

@a = qw( foo bar baz bah );
@b = qw( wibble wobble weeble );
@c = qw( nip nop );

And you want all the combinations of one element from each array, like this:

@cp = (
  [qw( foo wibble nip )],
  [qw( foo wibble nop )],
  [qw( foo wobble nip )],
  [qw( foo wobble nop )],
  [qw( foo weeble nip )],
  # ...
  [qw( bah wobble nop )],
  [qw( bah weeble nip )],
  [qw( bah weeble nop )],
)

What you want is a Cartesian Product (also called a Cross Product, but my mathy friends insist that Cartesian is correct)

Yes, there are already a lot of other modules on the CPAN that do this. I won't claim that this module does this calculation any better or faster, but it does do it differently, as far as I can tell.

Nothing else seemed to offer a specific feature - I needed to pick random individual tuples from the Cartesian Product, without iterating over the whole set and without calculating any tuples until they were asked for. Bonus points for not making a copy of the original input sets.

I needed the calculation to be lazy, and I needed random-access with O(1) (well, O(n) for the persnickety but n is so small it might as well be 1) retrieval time, even if that meant a slower implementation overall. And I didn't want to use RAM unnecessarily by creating copies of the original arrays, since the data I was working with was of a significant size.

METHODS

new

Construct a new object. Takes the following arguments:

  • options

    A hashref of options that modify the way the object works. If you don't want to specify any options, simply omit this argument.

    less_lazy

    Makes the get method slightly faster, at the expense of not being able to account for any modifications made to the original input arrays, and using more memory. If you modify one of the arrays used to consruct the object, the results of all the other methods are undefined. You might get the wrong answer. You might trigger an exception, you might get mutations that give you super-powers at the expense of never being able to touch another human being without killing them.

  • sets

    A list of arrayrefs from which to compute the cartesian product. You can list as many as you want.

Some examples:

my $cpl = Set::CartesianProduct::Lazy->new(\@a, [qw(foo bar baz)], \@b);
my $cpl = Set::CartesianProduct::Lazy->new( { less_lazy => 1 }, \@a, \@b, \@c);

get

Return the tuple at the given "position" in the cartesian product. The positions, like array indices, are based at 0.

If called in scalar context, an arrayref is returned. If called in list context, a list is returned.

If you ask for a position that exceeds the bounds of the array defining the cartesian product the result will be... interesting. I won't make any guarantees, but if it's useful, let me know.

Examples:

my @tuple  = $cpl->get(12);                # list context
my $tuple2 = $cpl->get( $cpl->count / 2 ); # scalar context

my $fail  = $cpl->get( $cpl->count ); # probably equal to ->get(0)
my $fail2 = $cpl->get( -1 );          # who knows

count

Return the count of tuples that would be in the cartesian product if it had been generated.

Example:

my $count = $cpl->count;

last_idx

Return the index of the last tuple that would be in the cartesian product if it had been generated. This is just for conveniece so you don't have to write code like this:

for my $i ( 0 .. $cpl->count - 1 ) { ... }

And you can do this instead:

for my $i ( 0 .. $cpl->last_idx ) { ... }

Which I feel is more readable.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-set-cartesianproduct-lazy at rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Set-CartesianProduct-Lazy. You will be automatically notified of any progress on the request by the system.

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

https://github.com/hercynium/Set-CartesianProduct-Lazy

git clone https://github.com/hercynium/Set-CartesianProduct-Lazy.git

AUTHOR

Stephen R. Scaffidi <sscaffidi@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Stephen R. Scaffidi.

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