# FreeBSD Manual Pages

```Math::Sequence(3)     User Contributed Perl Documentation    Math::Sequence(3)

NAME
Math::Sequence -	Perl extension dealing with mathematic sequences

SYNOPSIS
use Math::Sequence;
my \$x_n = Math::Sequence->new('x^2 - 1', 2);
print \$x_n->next(), "\n" foreach 0..9;
# prints 2, 3,	8, 63...

print \$x_n->at_index(5);
# prints 15745023

\$x_n->cached(0); # don't cache	the results (slow!)
\$x_n->cached(1); # cache the results (default)

DESCRIPTION
Math::Sequence defines a	class for simple mathematic sequences with a
recursive definition such as "x_(n+1) = 1 / (x_n	+ 1)". Creation	of a
Math::Sequence object is	described below	in the paragraph about the
constructor.

Math::Sequence uses Math::Symbolic to parse and modify the recursive
sequence	definitions. That means	you specify the	sequence as a string
which is	parsed by Math::Symbolic. Alternatively, you can pass the
constructor a Math::Symbolic tree directly.

Because Math::Sequence uses Math::Symbolic for its implementation, all
results will be Math::Symbolic objects which may	contain	other
variables than the sequence variable itself.

Each Math::Sequence object is an	iterator to iterate over the elements
of the sequence starting	at the first element (which was	specified by
the starting element, the second	argument to the	new() constructor). It
offers facilities to cache all calculated elements and access any
element directly, though	unless the element has been cached in a
previous	calculation, this is just a shortcut for repeated use of the
iterator.

Every element in	the sequence may only access its predecessor, not the
elements	before that.

EXAMPLE
use strict;
use warnings;
use Math::Sequence;

my \$seq = Math::Sequence->new('x+a', 0, 'x');
print(\$seq->current_index(), '	=> ', \$seq->next(), "\n") for 1..10;

CLASS DATA
Math::Sequence defines the following package variables:

\$Math::Sequence::Parser
This scalar contains a	Parse::RecDescent parser to parse formulas.
It is derived from the	Math::Symbolic::Parser grammar.

\$Math::Sequence::warnings
This scalar indicates whether Math::Sequence should warn about	the
performance implications of using the back() method on	uncached
sequences. It defaults	to true.

METHODS
new()
The constructor for Math::Sequence objects. Takes two or three
arguments.  In	the two	argument form, the first argument specifies
the recursion definition. It must be either a string to be parsed by
a Math::Symbolic parser or a Math::Symbolic tree. In the two argument
version, the recursion	variable (the one which	will be	recursively
replaced by its predecessor) will be inferred from the	function
signature. Thus, the formula must contain exactly one variable. The
second	argument must be a starting value. It may either be a constant
or a Math::Symbolic tree or a string to be parsed as such.

The three argument version adds to the	two argument version a string
indicating a variable name to be used as the recursion	variable.
Then, the recursion formula may contain any number of variables.

next()
The next() method returns the next element of the sequence and
advances the iterator by one. This is the prefered method of walking
down a	sequence's recursion.

cached()
Returns a true	value if the sequence is currently being cached, false
if it isn't. By default, new objects have caching enabled. It is
suggested that	you only disable caching if space is an	issue and you
will only walk	the sequence uni-directionally and only	once.

cached() can be used to change	the caching behaviour. If the first
argument is true, caching will	be enabled. If it is false, caching
will be disabled.

current_index()
Returns the index of the current element. That	is, the	index of the
element that will be returned by the next call	to the next() method.

This method also allows (re-)setting the element that will be next
returned by the next()	method.	In that	case, the first	argument
shoudl	be the appropriate index.

Returns undef and doesn't set the current index if the	argument is
below 0.

at_index()
This method returns the sequence element with the index denoted by
the first argument to the method. It does not change the state	of the
iterator.  This method	is extremely slow for uncached sequences.

Returns undef for indices below 0.

back()
This methods returns the sequence element previously returned by the
next()	method.	Since it is extremely slow on uncached sequences, it
off, set the \$Math::Sequence::warnings	scalar to a false value.

This method decrements	the current iterator sequence element.

Returns undef if the current index goes below 0.

AUTHOR
Steffen Mueller,	<sequence-module at steffen-mueller dot	net<gt>