NAME

Iterator::Misc - Miscellaneous iterator functions.

VERSION

This documentation describes version 0.03 of Iterator::Misc, August 26, 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);

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, ...

EXPORTS

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

DIAGNOSTICS

Iterator::Misc 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::Misc 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.

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.