NAME

Array::Each - iterate over one or more arrays, returning one or more elements from each array followed by the array index.

VERSION

This document refers to version 0.02 of Array::Each, released March 26, 2004.

Note: this version is an alpha release. Hopefully it is all correct and there will be no changes to the interface in future releases, but that may not be the case.

SYNOPSIS

use Array::Each;

# one array
my @x = qw( a b c d e );

my $one = Array::Each->new( \@x );
while( my( $x, $i ) = $one->each() ) {
    printf "%3d: %s\n", $i, $x;
}

# multiple arrays
my @y = ( 1,2,3,4,5 );

my $set = Array::Each->new( \@x, \@y );
while( my( $x, $y, $i ) = $set->each() ) {
    printf "%3d: %s %s\n", $i, $x, $y;
}

# groups of elements (note set=> parm syntax)
my @z = ( a=>1, b=>2, c=>3, d=>4, e=>5 );

my $hash_like = Array::Each->new( set=>[\@z], group=>2 );
while( my( $key, $val ) = $hash_like->each() ) {
    printf "%s => %s\n", $key, $val;
}

DESCRIPTION

Overview

Array::Each provides the each() method to iterate over one or more arrays, returning one or more elements from each, followed by the array index.

Array::Each has an object oriented interface, so it does not export any subroutines (or variables) into your program's namespace.

Use the new() method to create an object that will hold the iterator and other attributes for each set of arrays to iterate over, e.g.,

my $set = Array::Each->new( \@x, \@y );

Use the each() method to iterate over the values in the array or arrays. This is typically done in a while() loop, as with perl's builtin each() function for hashes.

while( my( $x, $y, $i ) = $set->each() ) {
    printf "%3d: %s %s\n", $i, $x, $y;
}

Like perl's, Array::Each's each() returns an empty list (in list context) when the end of the set of arrays is reached. At that point, the iterator is automatically rewound to the beginning, so you can iterate over the same set of arrays again.

Initialization

All attributes can be initialized via the call to the new() method. The attributes are: set, iterator, rewind, bound, undef, stop, group, and count. In addition, every attribute has accessor methods to set and get their values. These are explained in detail below.

Primary Methods

new( ARRAYREFS )

new( set=>[ARRAYREFS] ...other parms... )

new()

Normally--assuming all the attribute defaults are what you want--simply pass a list of array references to the new() method like this:

my $obj = Array::Each->new( \@x, \@y );

However, if you want to initialize any of the object's other attributes, pass the array references in an anonymous array using the set=> named parameter, like this:

my $obj = Array::Each->new( set=>[\@x, \@y] );  # same as above

Then you can pass other attributes by name:

my $obj = Array::Each->new( set=>[\@x, \@y], bound=>0, undef=>'' );

The attributes are: set, iterator, rewind, bound, undef, stop, group, and count, and are explained in detail below.

copy( ARRAYREFS )

copy( set=>[ARRAYREFS] ...other parms... )

copy()

This method is similar to new() in that it constructs a new object and allows you to set any of the attributes. But copy() is intended to be called with an existing Array::Each object. The new copy will take all of its attribute values from the existing object (in particular, the set of arrays and current value of the iterator), unless you specify differently, e.g.,

my $obj2 = $obj->copy();

Thus we might generate permutations of an array like this:

sub permute {
    my $set1 = Array::Each->new( @_ );
    my @permutations;
    while ( my @s1 = $set1->each() ) {
        my $set2 = $set1->copy();
        while ( my @s2 = $set2->each() ) {
            # -1 because each() returns array index, too
            push @permutations,
                [ @s1[0..$#s1-1], @s2[0..$#s2-1] ];
        }
    }
    return @permutations
}

Note: currently, the copy() method is implemented as an alias of the new() method. But do not rely on this always to be the case, because future versions of Array::Each may change this implementation detail. So the rules are:

1) use new() when you create a new object using the class name, e.g., $obj = Array::Each->new().

2) use copy() when you create a copy of an existing object using the object reference, e.g., $obj2 = $obj->copy().

each()

The each() method for arrays is similar to the builtin perl function of the same name for hashes. Perl's each() will iterate over a hash, returning a key and its value at each pass. Array::Each's each() will iterate over one or more arrays, each time returning one or more values, followed by an array index, e.g.,

while( my( $x, $y, $i ) = $obj->each() ) {
    printf "%3d: %s %s\n", $i, $x, $y;
}

In list context, Array::Each's each() returns an empty list when the end of the set of arrays is reached. In scalar context, it returns undef. At that point, the iterator is automatically rewound to the beginning, so you can iterate over the same set of arrays again.

See more examples above and below, and in Array::Each::Tutorial.

Incidentally, for what it's worth, each() returns just the array index when called in scalar context, e.g.,

while( defined( my $i = $obj->each() ) ) {
    printf "%3d\n", $i;
}

As the example implies, be aware that the first index returned will likely be 0.

Utility Methods

These methods are used internally and called automatically but can be called manually as needed.

rewind( INDEX )

rewind()

When you iterate over a set of arrays and reach the end, the iterator for that set is automatically "rewound" to index 0 (or to the value of the rewind attribute; see details about rewind below).

But you can rewind() it manually at any time, e.g.,

$obj->rewind();

You can also rewind it to a particular point by passing the array INDEX of the next desired iteration, e.g.,

$obj->rewind( 10 );

The rewind() method returns the value passed to it, or the value of the rewind attribute if no value is passed.

incr_iterator()

As each() iterates over a set of arrays, it automatically increments the iterator. But you can increment it manually with incr_iterator(), e.g.,

$obj->incr_iterator();

Note: if the group attribute is set, this method will increment the iterator by that amount; see details about group below.

The incr_iterator() method returns the value of the iterator prior to its being incremented.

Currently, incr_iterator() does not take any parameters. If you want to increment the iterator by other than the usual amount, first get its current value and then set the new value explicitly, e.g.,

$obj->set_iterator( $obj->get_iterator() + $amount );

Object Attributes and Accessor Methods

Since all object attributes can be set when new() is called, ordinarily there is no need to call any of the accessor methods. They are provided for completeness and for special cases.

set, set_set( ARRAYREFS ), get_set()

The set attribute is the list of arrays (i.e., the "set" of arrays) to iterate over. These arrays must be passed to the new(), copy(), and set_set() methods as array references. If no other attributes are initialized when you call new(), you can pass the array references "directly", e.g.,

$obj->Array::Each->new( \@x, \@y );

On the other hand, if you set other attributes when calling new(), you must pass the array references "indirectly" in an anonymous array using the set=> named parameter, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y] );  # same as above

If you want to specify the set of arrays separately from the call to new(), you can do so by calling set_set(), e.g.,

$obj->Array::Each->new();   # ...
$obj->set_set( \@x, \@y );  # same as above

Note, always pass the array references "directly" to set_set(), i.e., don't pass them inside an anonymous array.

In list context, the set_set() method returns the list of array references passed to it. In scalar context, it returns the number of references. E.g.,

my @array_refs = $obj->set_set( \@x, \@y );
my $num = $obj->set_set( @array_refs );

Get the list of array references by calling get_set(), e.g.,

my @array_refs = $obj->get_set();

(... yes, the term "set" is somewhat overloaded in this class. Sorry about that.)

iterator, set_iterator( INDEX ), get_iterator()

The iterator value is where the next iteration will begin. By default, it is set to 0, i.e., the first array index. To set a different initial value, pass the iterator=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], iterator=>10 );

This will start the iteration at array index 10 instead of 0.

(Note, this does not change where rewind() will rewind to. To change the rewind value, set the rewind attribute; see below. Or you can manually rewind to a particular index by calling the rewind method with that value, e.g., $obj->rewind( 10 ).)

Set the iterator of an existing object with set_iterator(), e.g.,

$obj->set_iterator( 10 );

Again, this sets where the next iteration will begin.

The set_iterator() method returns the value passed to it.

Get the value of the iterator with get_iterator(), e.g.,

my $i = $obj->get_iterator();

This is where the next iteration will begin, not where the last one happened.

Any integer >= 0 is valid for iterator.

rewind, set_rewind( INDEX ), get_rewind()

The rewind attribute is where rewind() will rewind to. By default, it is set to 0, i.e., the first array index. To set a different value, pass the rewind=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], rewind=>10, iterator=>10 );

(Note: setting rewind doesn't change where the initial iteration begins; for that, set the iterator value as shown above.)

Set an object's rewind value with set_rewind(), e.g.,

$obj->set_rewind( 10 );

The set_rewind() method returns the value passed to it.

Get the rewind value with get_rewind(), e.g.,

my $rewind_val = $obj->get_rewind();

Any integer >= 0 is valid for rewind.

bound, set_bound( 0 or 1 ), get_bound()

The bound attribute is a boolean flag and is 1 (true) by default. When this attribute is true, the iteration over the set of arrays will stop when the end of the shortest array is reached. That is, the iteration is "bound" by the shortest array.

Note: ordinarily this means that no "non-existing" values will be returned by each(). However, if the group attribute is set, "non-existing" values may be returned even if bound is true. "Non-existing" values are discussed below under undef.

To set bound to 0 (false), pass the bound=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], bound=>0 );

Or set the value with set_bound(), e.g.,

$obj->set_bound( 0 );  # now we're not bound by the shortest array

The set_bound() method returns the value passed to it.

Get the value with get_bound(), e.g.,

my $bound_val = $obj->get_bound();

The valid values for bound are 1 and 0.

undef, set_undef( SCALAR or undef ), get_undef()

The undef attribute is a scalar value that will be returned by each() when a "non-existing" array element is encountered. By default, this attribute's value is (perl's) undef.

"Non-existing" array elements may be encountered if bound is false, and the arrays are of different sizes. In other words, the iteration will continue to the end of the longest array. When the ends of any shorter arrays are surpassed, the value of the undef attribute will be returned for the "missing" elements. (But the shorter arrays will not be extended.)

"Non-existing" elements may also be encountered if group is set, even if bound is true. This is because if the shortest array's size is not a multiple of the group value, the last iteration will be "padded" using the value of the undef attribute.

Note: each() will not return the value of the undef attribute for existing array elements that are undefined. Instead, it will return the (perl) undef value, as normal.

To set undef, pass the undef=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], undef=>'' );

Or set the value with set_undef(), e.g.,

$obj->set_undef( 0 );

The set_undef() method returns the value passed to it.

Get the value with get_undef(), e.g.,

my $undef_val = $obj->get_undef();

Any value is valid for undef.

stop, set_stop( INDEX ), get_stop()

The stop attribute tells each() where to stop its iterations. By default, stop is undefined, meaning each() will stop where it wants, depending on bound, group, and the sizes of the arrays.

If bound is true and stop is set higher than $#shortest_array, then stop will have no effect (it will never be reached). If it is set lower, then the iteration will stop after that element has been returned by each().

If bound is false and the stop value is defined, then the iteration will stop after that element has been returned, regardless of the sizes of the arrays. If the end of any or all of the arrays is surpassed, each() will return the value of the undef attribute in the place of any "non-existing" element; see undef above.

To set stop, pass the stop=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], stop=>99 ); # give me 100

Or set the value with set_stop(), e.g.,

$obj->set_stop( 49 ); # give me 50 (probably)

The set_stop() method returns the value passed to it.

Get the value with get_stop(), e.g.,

my $stop_index = $obj->get_stop();

Any integer >= 0 is valid for stop.

group, set_group( NUM_ELEMS ), get_group()

The group attribute makes each() return multiple elements from each array. For example, if you do this ...

my $obj = Array::Each->new( set=>[\@x, \@y],
    group=>5, stop=>99, bound=>0 );
my @a = $obj->each;
my $i = $obj->get_iterator;

... then @a will contain 11 elements, 5 each from @x and @y and the value of the iterator when each() was called, namely 0. The value of $i is 5, because when each was called, the iterator was incremented by the value of group, i.e., 0 + 5 == 5.

By default, group is undefined. Logically this is the same as if it were set to 1. (But leave it undefined if 1 is what you want.)

To set group, pass the group=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], group=>5 );

Or set the value with set_group(), e.g.,

$obj->set_group( 5 );

The set_group() method returns the value passed to it.

Get the value with get_group(), e.g.,

my $group_val = $obj->get_group();

Any integer > 0 is valid for group.

As discussed above, if group causes each() to surpass the end of any array, the value of undef will be returned for any "non-existing" elements.

count, set_count( BEGIN_VAL ), get_count()

The count attribute makes each() return a count instead of the array index. When used, count will be returned and incremented by 1 every time each() returns array elements for a given Array::Each object. It is not automatically rewound.

By default, count is undefined and each() will ignore it.

To set count, pass the count=> named parameter to the new() (or copy()) method, e.g.,

$obj->Array::Each->new( set=>[\@x, \@y], count=>1 );

Or set the value with set_count(), e.g.,

$obj->set_count( 1 );

The set_count() method returns the value passed to it.

Get the value with get_count(), e.g.,

my $count_val = $obj->get_count();

Any integer >= 0 is valid for count.

See examples of using count in Array::Each::Tutorial.

Semi-Private Attributes and Accessor Methods

_each, _set_each( CODE_REF ), _get_each_name(), _get_each_ref()

The _each attribute contains a reference to the subroutine that will run when each() is called. Setting this attribute is handled under the covers, so you needn't do anything.

However, for debugging or testing, you may set the _each attribute to one of:

\&Array::Each::each_default
\&Array::Each::each_unbound
\&Array::Each::each_group
\&Array::Each::each_complete

using either the _each=> named attribute in the call to new() or by calling _set_each(), e.g.,

$obj->Array::Each->new( set=>[\@x, \@y],
    _each=>\&Array::Each::each_default );
$obj->_set_each( \&Array::Each::each_complete );

The _set_each() method returns the resulting value of _each (a code reference).

Setting _each this way may result in unexpected warning messages and/or in some attributes being ignored, so don't do it except for debugging or testing. For example, each_default() assumes that most of the attributes are set to their default values, even if they're not; each_unbound() assumes bound is false; etc.

Calling _set_each() without parameters will reset the _each attribute to its appropriate value and correctly honor all of the attributes.

Get the _each (code ref) value with _get_each_ref(), e.g.,

my $each_ref = $obj->_get_each_ref();

Get the _each stringified value with _get_each_name(), e.g.,

my $each_name = $obj->_get_each_name();

While changing parameters may change the value of _each, do not rely on a certain parameter combination always resulting in a specific _each subroutine.

INHERITING

user: The user attribute is reserved for use by classes that inherit from Array::Each. It may be used as needed without fear of colliding with future versions of Array::Each.

BUGS

Please feel free to report any bugs or suspected bugs to the author.

AUTHOR

Brad Baxter, bbaxter@cpan.org

Acknowledgments to Anno Siegel, Ben Morrow, and others on newsgroup comp.lang.perl.misc, and to Damian Conway, author of "Object Oriented Perl"[1].

COPYRIGHT

__________

[1] Conway, Damian, Object oriented Perl, Greenwich: Manning, 2000.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 806:: You forgot a '=back' before '=head2'
Around line 808:: '=item' outside of any '=over'

To install Array::Each, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Array::Each

CPAN shell

perl -MCPAN -e shell
install Array::Each

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)