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.
SEE ALSO
Array::Each::Tutorial
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
Copyright (c) 2003-2004, Brad Baxter, All rights reserved. This module
is free software. It may be used, redistributed and/or modified under
the same terms as Perl itself.
__________
[1] Conway, Damian, Object oriented Perl, Greenwich: Manning, 2000.