view release on metacpan or  search on metacpan

lib/Array/Each.pm  view on Meta::CPAN

To set C<bound> to 0 (false), pass the B<< 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 C<bound> are 1 and 0.


=item C<undef>, set_undef( SCALAR or undef ), get_undef()

The C<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 C<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 C<undef> attribute will
be returned for the "missing" elements.  (But the shorter arrays will
I<not> be extended.)

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

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

To set C<undef>, pass the B<< 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 C<undef>.


=item C<stop>, set_stop( INDEX ), get_stop()

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

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

If C<bound> is false and the C<stop> value is defined, then the
iteration will stop I<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
C<undef> attribute in the place of any "non-existing" element; see
C<undef> above.

To set C<stop>, pass the B<< 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 C<stop>.


=item C<group>, set_group( NUM_ELEMS ), get_group()

The C<group> attribute makes each() return I<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 C<@a> will contain 11 elements, 5 each from C<@x> and C<@y> and
the value of the iterator when each() was called, namely 0. The
value of C<$i> is 5, because when C<each> was called, the iterator
was incremented by the value of C<group>, i.e., C<0 + 5 == 5>.

By default, C<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 C<group>, pass the B<< 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 );