/ 
Iterator-Misc-0.01
River stage zero No dependents
/ Iterator::Misc

NAME

Iterator::Misc - Miscellaneous iterator functions.

VERSION

This documentation describes version 0.01 of Iterator::Misc, August 18, 2005.

SYNOPSIS

use Iterator::Misc;

# Permute the elements of a list:
$iter = ipermute (@items);

# Select only every nth value of an iterator
$iter = inth ($n, $another_iterator);

# Randomly select iterator values with 1/$n probability
$iter = irand_nth ($n, $another_iterator);

# Fibonacci sequence
$ifib = ifibonacci();         # default sequence starts with 1,1
$ifib = ifibonacci($a, $b);   # or specify alternate starting pair

# Geometric sequence
$iter = igeometric ($start, $end, $multiplier);

# Mesh iterators together
$iter = imesh ($iter, $iter, ...);
$iter = izip  ($iter, $iter, ...);

# Return each value of an iterator once
$iter = iuniq ($another_iterator);

DESCRIPTION

This module contains miscellaneous iterator utility functions that I think aren't as broadly useful as the ones in Iterator::Util. They are here to keep the size of Iterator::Util down.

For more information on iterators and how to use them, see the Iterator module documentation.

FUNCTIONS

ipermute
$iter = ipermute (@list);
$array_ref = $iter->value();

Permutes the items in an arbitrary list. Each time the iterator is called, it returns the next combination of the items, in the form of a reference to an array.

Example:

$iter = ipermute ('one', 'two', 'three');
$ref  = $iter->value();          # -> ['one', 'two', 'three']
$ref  = $iter->value();          # -> ['one', 'three', 'two']
$ref  = $iter->value();          # -> ['two', 'one', 'three']
# ...etc
inth
$iter = inth ($n, $another_iterator);

Returns an iterator to return every nth value from the input iterator. The first $n-1 items are skipped, then one is returned, then the next $n-1 items are skipped, and so on.

This can be useful for sampling data.

irand_nth
$iter = irand_nth ($n, $another_iterator);

Random nth. Returns an iterator to return items from the input iterator, with a probability of 1/$n for each. On average, in the long run, 1 of every $n items will be returned.

This can be useful for random sampling of data.

ifibonacci
$iter = ifibonacci ();
$iter = ifibonacci ($start);
$iter = ifibonacci ($start1, $start2);

Generates a Fibonacci sequence. If starting values are not specified, uses (1, 1). If only one is specified, it is used for both starting values.

igeometric
$iter = igeometric ($start, $end, $multiplier)

Generates a geometric sequence. If $end is undefined, the sequence is unbounded.

Examples:

$iter = igeometric (1, 27, 3);         # 1, 3, 9, 27.
$iter = igeometric (1, undef, 3);      # 1, 3, 9, 27, 81, ...
$iter = igeometric (10, undef, 0.1);   # 10, 1, 0.1, 0.01, ...
imesh
izip
$iter = imesh ($iter1, $iter2, ...);

This iterator accepts any number of other iterators, and "meshes" their values together. First it returns the first value of the first iterator, then the first value of the second iterator, and so on, until it has returned the first value of all of its iterator arguments. Then it goes back and returns the second value of the first iterator, and so on. It stops when any of its iterator arguments is exhausted.

Example:

$i1 = ilist ('a', 'b', 'c');
$i2 = ilist (1, 2, 3);
$i3 = ilist ('rock', 'paper', 'scissors');
$iter = imesh ($i1, $i2, $i3);
# $iter will return, in turn, 'a', 1, 'rock', 'b', 2, 'paper', 'c',...

izip is a synonym for imesh.

iuniq
$iter = iuniq ($another_iterator);

Creates an iterator to return unique values from another iterator; weeds out duplicates.

Example:

$iter = ilist (1, 2, 2, 3, 1, 4);
$uniq = iuniq ($iter);            # returns 1, 2, 3, 4.

EXPORTS

All function names are exported to the caller's namespace by default.

DIAGNOSTICS

Iterator::Util uses Exception::Class objects for throwing exceptions. If you're not familiar with Exception::Class, don't worry; these exception objects work just like $@ does with die and croak, but they are easier to work with if you are trapping errors.

For more information on how to handle these exception objects, see the Iterator documentation.

  • Parameter Errors

    Class: Iterator::X::Parameter_Error

    You called an Iterator::Util function with one or more bad parameters. Since this is almost certainly a coding error, there is probably not much use in handling this sort of exception.

    As a string, this exception provides a human-readable message about what the problem was.

  • Exhausted Iterators

    Class: Iterator::X::Exhausted

    You called value on an iterator that is exhausted; that is, there are no more values in the sequence to return.

    As a string, this exception is "Iterator is exhausted."

  • User Code Exceptions

    Class: Iterator::X::User_Code_Error

    This exception is thrown when the sequence generation code throws any sort of error besides Am_Now_Exhausted. This could be because your code explicitly threw an error (that is, died), or because it otherwise encountered an exception (any runtime error).

    This exception has one method, eval_error, which returns the original $@ that was trapped by the Iterator object. This may be a string or an object, depending on how die was invoked.

    As a string, this exception evaluates to the stringified $@.

  • Internal Errors

    Class: Iterator::X::Internal_Error

    Something happened that I thought couldn't possibly happen. I would appreciate it if you could send me an email message detailing the circumstances of the error.

REQUIREMENTS

Requires the following additional modules:

Iterator

SEE ALSO

Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.

L<http://perl.plover.com/hop/>

THANKS

Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in general) for suggestions for the pre-release version.

AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To avoid my spam filter, please include "Perl", "module", or this module's name in the message's subject line, and/or GPG-sign your message.

If you have suggestions for improvement, please drop me a line. If you make improvements to this software, I ask that you please send me a copy of your changes. Thanks.