# 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, `die`d), 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

Iterator

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.