Iterator::Misc - Miscellaneous iterator functions.
This documentation describes version 0.03 of Iterator::Misc, August 26, 2005.
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);
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.
$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
$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.
$n-1
This can be useful for sampling data.
$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.
1/$n
$n
This can be useful for random sampling of data.
$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.
$iter = igeometric ($start, $end, $multiplier)
Generates a geometric sequence. If $end is undefined, the sequence is unbounded.
$end
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, ...
All function names are exported to the caller's namespace by default.
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.
$@
die
croak
For more information on how to handle these exception objects, see the Iterator documentation.
Parameter Errors
Class: Iterator::X::Parameter_Error
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
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
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).
Am_Now_Exhausted
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.
eval_error
As a string, this exception evaluates to the stringified $@.
Internal Errors
Class: Iterator::X::Internal_Error
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.
Requires the following additional modules:
Iterator
Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.
http://perl.plover.com/hop/
Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in general) for suggestions for the pre-release version.
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.
To install Iterator::Misc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Iterator::Misc
CPAN shell
perl -MCPAN -e shell install Iterator::Misc
For more information on module installation, please visit the detailed CPAN module installation guide.