List::Tuples - Makes tuples from lists

	use List::Tuples qw(:all) ;

	my @tuples = tuples[2] => (1 .. 6) ;

	# is equivalent to:

	my @tuples = 
		(
		[1, 2],
		[3, 4],
		[5, 6],
		) ;

	#-------------------------------------------------------

	my @meshed_list = ref_mesh([1 .. 3], ['a' .. 'b'], ['*']) ;

	# is equivalent to:

	my @meshed_list = (1, 'a', '*', 2, 'b', undef, 3, undef, undef) ;

	#-------------------------------------------------------

	my @hashes = hash_tuples ['key', 'other_key'] => (1 .. 5) ;

	# is equivalent to :

	my @hashes = 
		(
		{key => 1, other_key => 2},
		{key => 3, other_key => 4},
		{key => 5, other_key => undef},
		) ;

This module defines subroutines that let you create tuples.

Ever got frustrated that you couldn't easily get tuples into map{} or create multiple hashes from an ordered list?

Jonathan Scott in In "Everyday Perl 6" http://www.perl.com/pub/a/2007/05/10/everyday-perl-6.html writes:

    # Perl 6                        # Perl 5
    for @array -> $a     { ... }    for my $a (@array) { ... }
    for @array -> $a, $b { ... }    # too complex :)

The following subroutines will simplify your job. They could certainly be more effective implemented directly in the language, IE in Perl6. If you have millions of tuples to handle, you may want monitor memory usage.

tuples will extract $size elements from @lists and group them in an array reference. It will extract as many tuples as possible up to the, optional, $limit you pass as argument.

	tuples 3 => [2] => (1 .. 14); # 3 tuples with 2 elements are returned
	tuples[2] => (1 .. 14); # 7 tuples with 2 elements are returned

	for my $tuple (tuples[2] => @array) 
		{
		print "[$tuple->[0], $tuple->[1]]\n" ;
		}

Arguments

* $limit - an optional maximum number of tuples to create

* \@size - an array reference containing the number of elements in a tuple

* @list - a list to be split into tuples

Return

* A list of tuples (array references)

	my @tuples = tuples[2] => (1 .. 3)) ; 

	# is equivalent to:

	my @tuples =
		(
		[1, 2],
		[3],
		) ;

* Error: List::Tuples::tuples expects tuple size to be positive!

example:

	my @tuples = tuples[2] => @list ;
	                    ^
	                    `- size must be positive 

* Error: List::Tuples::tuples expects a tuple size!

example:

	my @tuples = tuples[2] => @list ;
	                    ^
	                    `- size must be defined

* Error: List::Tuples::tuples expects tuple limit to be positive !

example:

	my @tuples = tuples 3 => [2] => @list ;
	                    ^
	                    `- limit must be positive 

* Error: List::Tuples::tuples expects an array reference as size argument!

example:

	my @tuples = tuples[2] => @list ;
			   ^
	                   `- size must be in an array reference

Mixes elements from arrays, one element at the time.

	my @list = 
		ref_mesh
			['mum1', 'mum2', 'mum3'],
			['dad1', 'dad2'],
			[['child1_1', 'child1_2'], [], ['child3_1']] ;

	# is equivalent to :

	my @list = 
		(
		'mum1',
		'dad1',
		[child1_1, 'child1_2'],
		'mum2',
		'dad2',
		[],
		'mum3', 
		'undef,
		[child3_1]
		) ;

This is equivalent to mesh from List::MoreUtils except the fact it takes arrays references instead for lists. The implementation is directly taken from List::MoreUtils.

Arguments

* a list of array reference

Return

* a list consisting of the first elements of each array reference, then the second, then the third, etc, until all arrays are exhausted

* Error: List::Tuples::ref_mesh: element '$index' is not an array reference!

example:

	my \@list = ref_mesh([1, 2], [5, 10], [10, 20], ...) ;
			    ^
	                    `-  arguments must be array references

hash_tuples uses elements from \@input_array and combine them with \@hash_keys to create hash references. It will create as many hashes as possible up to the, optional, $limit.

	my @hashes  = 
		hash_tuples
			['Mum',   'Dad',   'Children'] =>
			'Lena',   'Nadim', ['Yasmin', 'Miriam'],
			'Monika', 'ola',   ['astrid'] ;

	# is equivalent to:

	my @hashes =
		(
			{
			'Mum' => 'Lena',
			'Children' => ['Yasmin','Miriam'],
			'Dad' => 'Nadim'
			}, 
			{
			'Mum' => 'Monika',
			'Children' => ['astrid'],
			'Dad' => 'ola'
			}
		) ;

	


	for my $tuple (hash_tuples(['a', 'b'] => @array)) 
		{
		print $tuple->{a} . "\n" ;
		print $tuple->{b} . "\n" ;
		}

Arguments

* $limit - an optional maximum number of hashes to create

* \@hash_keys - an array reference containing the list of keys apply to the input array

* \@input_array- an array reference. the array contains the elements to extract

Return

* A list of hashes

* Error: List::Tuples::hash_tuples expects at least one key in the key list!

example:

	my @hashes  = hash_tuples['Mum',   'Dad',   'Children'] => @list ;
			         ^
				 `-  key list must contain at least one keys

* Error: List::Tuples::hash_tuples expects tuple limit to be positive!

example:

	my @hashes  = hash_tuples 3 => ['Mum',   'Dad',   'Children'] => @list ;
			          ^
				  `-  limit must be positive

* Error: List::Tuples::hash_tuples expects an array reference to define the keys!

example:

	my @hashes  = hash_tuples ['Mum',   'Dad',   'Children'] => @list ;
			          ^
				  `-  key list must be an array reference

None so far.

	Khemir Nadim ibn Hamouda
	CPAN ID: NKH
	mailto:nadim@khemir.net

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

You can find documentation for this module with the perldoc command.

    perldoc List::Tuples

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/List-Tuples

* RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-list-tuples@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.

* Search CPAN

http://search.cpan.org/dist/List-Tuples

List::MoreUtils