/ 
Iterator-Flex-0.13
River stage zero No dependents
/ Iterator::Flex::Common

NAME

Iterator::Flex::Common - Iterator Generators and Adapters

VERSION

version 0.13

SYNOPSIS

DESCRIPTION

Iterator::Flex::Common provides generators for iterators for some common cases (arrays, sequences), arbitrary code, and iterator adaptors. As described in "Capabilities" in Iterator::Flex::Manual::Overview, iterators have optional capabilities; the descriptions below list which capabilities each iterator provides.

For iterator adapters, such as "icache", some capabilities are supported only if the iterable they operate on supports them. For example, "icache" can't provide the reset or rewind capabilities if the iterable reads from the terminal. In these cases, attempting to use this capability will result in an error.

Parameters

Most of the generators take an optional trailing hash, %pars to accommodate optional parameters. Parameters come in three classes, explained in "Iterator Parameters" in Iterator::Flex::Manual::Overview. General Parameters are documented there. Model Parameters are specific to a type of iterators and are noted in the documentation for the generators, below.

For example, to construct a caching iterator, setting the size of the cache, and indicating that the returned iterator should signal exhaustion by throwing an exception:

$iter = icache( $iterable,
                { capacity => 2,
                  exhaustion => 'throw',
                } );

Or, to indicate that an iterable signals exhaustion via throwing an exception:

$iter = igrep( $iterable, { input_exhaustion => 'throw' } );

SUBROUTINES

iterator

$iter = iterator { CODE } ?\%pars;

Construct an iterator from code. The code will have access to the iterator object through $_[0]. By default the code is expected to return undef upon exhaustion (this can be changed by setting the "input_exhaustion" in Iterator::Flex::Manual::Overview parameter).

For example, here's a simple integer sequence iterator that counts up to 100:

#! /usr/bin/perl
use strict;
use warnings;
use v5.10.0;

use Iterator::Flex::Common ':all';

my $seq = 0;
my $iter = iterator { return $seq < 100 ? ++$seq : undef } ;
while ( defined ( my $r = $iter->() ) ) {
    #...
}
1;

See "Parameters" for a description of %pars

The returned iterator supports the following methods:

next

iter

$iter = iter( $iterable, ?\%pars );

Construct an iterator from an iterable thing. By default the code is expected to return undef upon exhaustion (this can be changed by setting the "input_exhaustion" in Iterator::Flex::Manual::Overview parameter).

See "Parameters" for a description of %pars

iarray

$iterator = iarray( $array_ref, ?\%pars );

Wrap an array in an iterator. See Iterator::Flex::Array for more details.

The returned iterator supports the following methods:

current
next
prev
rewind
reset
freeze

icache

$iterator = icache( $iterable, ?\%pars );

The iterator caches the current and previous values of the passed iterator, See Iterator::Flex::Cache for more details.

The returned iterator supports the following methods:

reset
rewind
next
prev
current
freeze

icycle

$iterator = icycle( $array_ref, ?\%pars );

Wrap an array in an iterator. The iterator will continuously cycle through the array's values. See Iterator::Flex::Cycle for more details.

current
next
prev
rewind
reset
freeze

igrep

$iterator = igrep { CODE } $iterable, ?\%pars;

Returns an iterator equivalent to running grep on $iterable with the specified code. CODE is not run if $iterable is exhausted. To indicate how $iterable signals exhaustion, use the input_exhaustion general parameter; by default it is expected to return undef. See Iterator::Flex::Grep for more details.

The iterator supports the following methods:

next
reset

imap

$iterator = imap { CODE } $iterable, ?\%pars;

Returns an iterator equivalent to running map on $iterable with the specified code. CODE is not run if $iterable is exhausted. To indicate how $iterable signals exhaustion, use the input_exhaustion general parameter; by default it is expected to return undef. See Iterator::Flex::Map for more details.

The iterator supports the following methods:

next
reset

iproduct

$iterator = iproduct( $iterable1, $iterable2, ..., ?\%pars );
$iterator = iproduct( key1 => $iterable1, key2 => iterable2, ..., ?\%pars );

Returns an iterator which produces a Cartesian product of the input iterables. If the input to iproduct is a list of iterables, $iterator will return an array reference containing an element from each iterable.

If the input is a list of key, iterable pairs, $iterator will return a hash reference.

All of the iterables must support the rewind method.

The iterator supports the following methods:

current
next
reset
rewind
freeze

This iterator may be frozen only if all of the iterables support the prev or __prev__ method.

iseq

# integer sequence starting at 0, incrementing by 1, ending at $end
$iterator = iseq( $end );

# integer sequence starting at $begin, incrementing by 1, ending at $end
$iterator = iseq( $begin, $end );

# real sequence starting at $begin, incrementing by $step, ending <= $end
$iterator = iseq( $begin, $end, $step );

The iterator supports the following methods:

current
next
prev
rewind
freeze

ifreeze

$iter = ifreeze { CODE } $iterator, ?\%pars;

Construct a pass-through iterator which freezes the input iterator after every call to next. CODE will be passed the frozen state (generated by calling $iterator-freeze> via $_, with which it can do as it pleases.

<CODE> is executed when $iterator returns undef (that is, when $iterator is exhausted).

The returned iterator supports the following methods:

next
prev

If $iterator provides a prev method.

rewind
freeze

See Iterator::Flex::Manual::Serialization for more information.

thaw

$frozen = $iterator->freeze;
$iterator = thaw( $frozen, ?\%pars );

Restore an iterator that has been frozen. See Iterator::Flex::Manual::Serialization for more information.

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