The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Iterator-Flex-0.18
River stage zero No dependents
++
/ Iterator::Flex::Common

NAME

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

VERSION

version 0.18

SYNOPSIS

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

 # generate an iterator which returns undef upon exhaustion
 my $iter = iseq( 0, 10, 2 );
 my $value;
 say $value while defined $value = $iter->next;
 # 0 2 4 6 8 10

 # generate an iterator which returns -1 upon exhaustion
 my $iter = iseq( 1, 10, 2, { exhaustion => [ 'return', -1 ] } );
 my $value;
 say $value while ($value = $iter->next) >= 0 ;
 # 1 3 4 7 9

DESCRIPTION

Iterator::Flex::Common provides generators for iterators for common uses, such as iterating over arrays, generating numeric sequences, wrapping subroutines or other iterable objects or adapting other iterator data streams.

All of the generated iterators and adaptors support the next capability; some support additional ones. For adapters, 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.

See "Capabilities" in Iterator::Flex::Manual::Overview for a full list of capabilities.

Generator Parameters

Most of the generators take an optional trailing hash, %pars, to accommodate optional parameters.

Iterator generators accept the exhaustion (see "exhaustion" in Iterator::Flex::Manual::Overview) and error (see "error" in Iterator::Flex::Manual::Overview) parameters, which indicate how the generated iterator or adaptor will signal exhaustion and error.

Adapter generators additionally accept the input_exhaustion (see "input_exhaustion" in Iterator::Flex::Manual::Overview) parameter, specifying how the input iterator will signal exhaustion.

Some generators have parameters specific to what they do, for example the icache adaptor generator has an optional capacity option.

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 assumption can be changed by setting the input_exhaustion parameter (see "input_exhaustion" in Iterator::Flex::Manual::Overview).

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 $iterable is expected to return undef upon exhaustion; this assumption can be changed by setting the input_exhaustion parameter (see "input_exhaustion" in Iterator::Flex::Manual::Overview).

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

icat

  $iterator = icat( \@iterables, ?\%pars );

Concatenate the iterables. As each iterator is exhausted, the next one is queried for its values. See Iterator::Flex::Cat for more details.

The returned iterator supports the following methods:

reset

If all of the iterables support it.

rewind

If all of the iterables support it.

next
prev
current
freeze

If all of the iterables support it.

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

istack

  $iterator = istack( \@iterables, ?\%pars );

A stack of iterables. It returns the next value from the iterator at the top of the stack. Iterators are popped when they are exhausted. It supports push, pop, shift, and unshift methods, which have same API as the Perl builtin subroutines. See Iterator::Flex::Stack for more details.

The returned iterator supports the following methods:

next
prev
current

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.

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