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.