HTTPS SSH

NAME

Iterator::Flex - Iterators which can be rewound and serialized

VERSION

version 0.11

SYNOPSIS

DESCRIPTION

Iterator::Flex implements iterators with the following characteristics:

  • next

    All iterators provide a next method which advances the iterator and returns the new value.

  • exhaustion

    Iterator exhaustion is signified by next return undef.

  • reset

    Iterators may optionally be rewound to their initial state

  • previous values

    Iterators may optionally return their previous value.

  • current

    Iterators return their current value.

  • freeze

    Iterators may optionally provide a freeze method for serialization. Iterators may be chained, and an iterator's dependencies are frozen automatically.

Serialization of Iterators

  • freeze optional

    A subroutine which returns an array reference with the following elements, in the specified order :

    1. The name of the package containing the thaw subroutine.
    2. The name of the thaw subroutine.
    3. The data to be passed to the thaw routine. The routine will be called as:

      thaw( @{$data}, ?$depends );
      

      if $data is an arrayref,

      thaw( %{$data}, ?( depends => $depends )  );
      

      if $data is a hashref, or

      thaw( $data, ?$depends );
      

      for any other type of data.

      Dependencies are passed to the thaw routine only if they are present.

SUBROUTINES

iterator

$iter = iterator { CODE } ?%params;

Construct an iterator from code. The code will have access to the iterator object through $_[0]. The optional parameters are any of the parameters recognized by "construct" in Iterator::Flex::Base.

By default the code is expected to return C<undef> upon exhaustion.

iter

$iter = iter( $iterable );

Construct an iterator from an iterable thing. The iterator will return undef upon exhaustion.

An iterable thing is
  • an object

    An iterable object has one or more of the following methods

    • __iter__ or iter
    • __next__ or next
    • an overloaded <> operator

      This should return the next item.

    • an overloaded &{} operator

      This should return a subroutine which returns the next item.

    Additionally, if the object has the following methods, they are used by the constructed iterator:

    • __prev__ or prev
    • __current__ or current

    See "construct_from_object"

  • an arrayref

    The returned iterator will be an "iarray" in Iterator::Flex iterator.

  • a coderef

    The coderef must return the next element in the iteration.

  • a globref

iarray

$iterator = iarray( $array_ref );

Wrap an array in an iterator.

The returned iterator supports the following methods:

  • current
  • next
  • prev
  • rewind
  • reset
  • freeze

icache

$iterator = icache( $iterable );

The iterator caches the current and previous values of the passed iterator,

The returned iterator supports the following methods:

  • reset
  • rewind
  • next
  • prev
  • current
  • freeze

icycle

$iterator = icycle( $array_ref );

Wrap an array in an iterator. The iterator will continuously cycle through the array's values.

  • current
  • next
  • prev
  • rewind
  • reset
  • freeze

igrep

$iterator = igrep { CODE } $iterable;

Returns an iterator equivalent to running grep on $iterable with the specified code. CODE is not run if $iterable returns undef (that is, it is exhausted).

The iterator supports the following methods:

  • next
  • reset

imap

$iterator = imap { CODE } $iteraable;

Returns an iterator equivalent to running map on $iterable with the specified code. CODE is not run if $iterable returns undef (that is, it is exhausted).

The iterator supports the following methods:

  • next
  • reset

iproduct

$iterator = iproduct( $iterable1, $iterable2, ... );
$iterator = iproduct( key1 => $iterable1, key2 => iterable2, ... );

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;

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

thaw

$frozen = $iterator->freeze;
$iterator = thaw( $frozen );

Restore an iterator that has been frozen. See "Serialization of Iterators" for more information.

METHODS

Not all iterators support all methods.

  • prev

    $value = $iter->prev;
    

    Returns the previous value of the iterator. If the iterator was never advanced, this returns undef. If the iterator is exhausted, this returns the last retrieved value. Use the state method to determine which state the iterator is in.

  • current

    $value = $iter->current;
    

    Returns the current value of the iterator. If the iterator was never advanced, this returns undef. If the iterator is exhausted, this returns undef. Use the state method to determine which state the iterator is in.

  • next

    $value = $iter->next;
    

    Return the next value from the iterator.

  • rewind

    $iter->rewind;
    

    Resets the iterator so that the next value returned is the very first value. It should not affect the results of the prev and current methods.

  • reset

    $iter->reset;
    

    Resets the iterator to its initial state. The iterator's state is not changed.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Iterator-Flex or by email to bug-Iterator-Flex@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SOURCE

The development version is on github at https://github.com/djerius/iterator-flex and may be cloned from git://github.com/djerius/iterator-flex.git

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