/ 
List-Tuples-0.04.4
River stage zero No dependents
/ List::Tuples

NAME

List::Tuples - Makes tuples from lists

SYNOPSIS

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},
	) ;

DESCRIPTION

This module defines subroutines that let you create tuples.

DOCUMENTATION

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.

SUBROUTINES

tuples([$limit], \@size, @list)

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)

Input list with insufficient elements

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

# is equivalent to:

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

Diagnostics

  • 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

ref_mesh(\@array1, \@array2, ...)

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

Diagnostics

  • 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([$limit], \@hash_keys, @input_array)

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

Diagnostics

  • 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

BUGS AND LIMITATIONS

None so far.

AUTHOR

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

LICENSE AND COPYRIGHT

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

SUPPORT

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

perldoc List::Tuples

You can also look for information at:

SEE ALSO

List::MoreUtils