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

# 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

Requires the following additional modules:

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.

# 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: