/ 
Iterator-Flex-0.25
River stage zero No dependents
/ Iterator::Flex::Gather

NAME

Iterator::Flex::Gather - Gather Iterator Class

VERSION

version 0.25

METHODS

new

use Iterator::Flex::Gather::Constants ':all';

$iterator = Ierator::Flex::Gather->new( $coderef, $iterable, ?\%pars );

Returns an iterator which accumulates elements returned by $iterable based upon the return result of $coderef. Gathered items are returned as an arrayref.

$iterable is converted into an iterator via "to_iterator" in Iterator::Flex::Factory if required.

$coderef is called with the next item from iterable in the $_ variable, and two parameters; the first is an arrayref containing the gathered items, the second is a flag indicating whether the coderef is called while gathering items (GATHER_GATHERING)or after the source has been exhausted (GATHER_SRC_EXHAUSTED).

It should return the binary AND of two result codes.

The first result code indicates whether the the element should be gathered (GATHER_ELEMENT_INCLUDE) or skipped (GATHER_ELEMENT_EXCLUDE).

The second indicates whether the gathering cycle should stop and if so, whether it should be restarted:

GATHER_CYCLE_CONTINUE

Continue gathering.

GATHER_CYCLE_RESET

Stop gathering, and return the gathered items. The next time the iterator is invoked, it will begin a new cycle.

GATHER_CYCLE_STOP

Stop gathering, and return the gathered items. The next time the iterator is invoked, it will signal exhaustion.

GATHER_CYCLE_ABORT

Stop gathering, and signal exhaustion. Any gathered items are discarded.

When the $iterable signals exhaustion, $coderef is called one last time. It should return either GATHER_CYCLE_STOP or GATHER_CYCLE_ABORT.

Here's an example for a gathering operation which batches integer elements into groups of 10, only accepts even numbers, and drops the last batch if it has fewer than ten, but only if the last element isn't 100

sub ( $gathered, $state ) {

    return $gathered->@* && $gathered->[-1] == 100 ? GATHER_CYCLE_STOP : GATHER_CYCLE_ABORT
      if $state == GATHER_SRC_EXHAUSTED;

    return GATHER_ELEMENT_EXCLUDE | GATHER_CYCLE_CONTINUE
      if $_ % 2;

    return GATHER_ELEMENT_INCLUDE
      | ( $gathered->@* == 9 ? GATHER_CYCLE_RESTART : GATHER_CYCLE_CONTINUE );

}

The optional %pars hash may contain standard signal parameters.

The iterator supports the following capabilities:

next
reset

INTERNALS

SUPPORT

Bugs

Please report any bugs or feature requests to bug-iterator-flex@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Iterator-Flex

Source

Source is available at

https://gitlab.com/djerius/iterator-flex

and may be cloned from

https://gitlab.com/djerius/iterator-flex.git

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007