Eric J. Roode


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.


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

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.

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.


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


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



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.


  • Exhausted Iterators

    Class: Iterator::X::Exhausted



  • User Code Exceptions

    Class: Iterator::X::User_Code_Error




  • Internal Errors

    Class: Iterator::X::Internal_Error



Requires the following additional modules:



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




Eric J. Roode,

