Eric J. Roode > Iterator-Misc-0.03 > Iterator::Misc

Download:
Iterator-Misc-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

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.

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.

syntax highlighting: