# FreeBSD Manual Pages

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

NAME
Math::Series - Perl extension dealing with mathematic series

SYNOPSIS
use Math::Series;
my \$x_n = Math::Series->new( formula	    => 'n*x',
start_value   => 1,
iteration_var => 'n',
previous_var  => 'x',
start_index   => 0,
cached	    => 1      );

print \$x_n->next(), "\n" foreach 0..5;
# prints 1, 2,	6, 24...

print \$x_n->at_index(3);
# prints 24

DESCRIPTION
Math::Series defines a class for	simple mathematic series with a
recursive definition such as "x_(n+1) = 1 / (x_n	+ 1)". Such a
recursive definition is treated as a sequence whose elements will be
added to	form a series. You can refer to	the previous sequence element
as well as to the current index in the series. Creation of a
Math::Series object is described	below in the paragraph about the
constructor.

Math::Series 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::Series uses Math::Symbolic	for its	implementation,	all
results will be Math::Symbolic objects which may	contain	other
variables than the sequence variable and	the iterator variable.

Each Math::Series object	is an iterator to iterate over the elements of
the series 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 series may only access its predecessor, not	the
elements	before that.

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

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

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

METHODS
new()
The constructor for Math::Series objects. It takes named parameters.
The following parameters are required:

formula
The formula is the recursive	definition of a	sequence whose
elements up to the current element will be summed to	form the
current element of the series.  The formula may contain various
Math::Symbolic variables that are assigned a	value elsewhere	in
your	code, but it may also contain two special variables: The
number of the current iteration step, starting with 0, and the
previous element of the series.

The formula may be specified	as a string that can be	parsed by a
Math::Symbolic parser or as a Math::Symbolic	tree directly. Please
refer to the	Math::Symbolic and Math::Symbolic::Parser man pages
for details.

start_value
This	parameter defines the starting value for the series. It	used
as the element in the series	that is	defined	as the lowest series
element by the start_index parameter.  The starting value may be a
string that can be parsed as	a valid	Math::Symbolic tree or a
preconstructed Math::Symbolic tree.

The following parameters are optional:

iteration_var
The iteration variable is the name of the variable in the
Math::Symbolic tree that refers to the current iteration step. It
defaults to the variable 'n'.

It must be a	valid Math::Symbolic variable identifier. (That	means
it is "/[A-Za-z][A-Za-z0-9_]*/".)

previous_var
The previous_var parameter sets the name of the variable that
represents the previous iteration step. It defaults to the name 'x'
and must be a valid Math::Symbolic variable identifier just like
the iteration variable.

cached
This	parameter indicates whether or not to cache the	calculated
series' elements for	faster direct access. It defaults to true. At
run-time, the caching behaviour may be altered using	the cached()
method.

start_index
The lower boundary for the series' summation. It defaults to	0, but
may be set to any positive integer or zero.

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

cached()
Returns a true	value if the series 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 series 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 series	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 series.

Returns undef for indices below the starting index.

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

This method decrements	the current iterator series element.

Returns undef if the current index goes below the starting index.

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

You may find the	current	versions of this module	at
http://steffen-mueller.net/ or on CPAN.

This module is based on Math::Sequence.	Math::Symbolic and
Math::Symbolic::Parser for the kinds of formulas	accepted by
Math::Series.

perl v5.24.1			  2004-02-24		       Math::Series(3)
```