++ed by:
Kevin Ryde
and 1 contributors

# NAME

Math::NumSeq -- number sequences

# SYNOPSIS

`````` # only a base class, use one of the actual classes such as
use Math::NumSeq::Squares;
my \$seq = Math::NumSeq::Squares->new;
my (\$i, \$value) = \$seq->next;``````

# DESCRIPTION

This is a base class for number sequences. Sequence objects can iterate through the values, and some sequences have random access and predicate. It's a touch rough yet.

The idea is to generate things like squares or primes in a generic way. Some sequences, like squares, are so easy there's no need for this except for the genericness. Other sequences are trickier and an iterator is a good way to go through the values.

# FUNCTIONS

In the following "Foo" is one of the actual subclass names. The intention is that all modules `Math::NumSeq::Something` are sequence classes, and that supporting things are deeper, such as under `Math::NumSeq::Something::Helper` or `Math::NumSeq::Base::SharedStuff`.

`\$seq = Math::NumSeq::Foo->new (key=>value,...)`

Create and return a new sequence object.

`(\$i, \$value) = \$seq->next()`

Return the next index and value in the sequence.

`\$seq->rewind()`

Rewind the sequence to its starting point.

`\$str = \$seq->description()`

A human-readable description of the sequence.

`\$value = \$seq->values_min()`
`\$value = \$seq->values_max()`

Return the minimum or maximum value taken by values in the sequence, or `undef` if unknown or infinity.

`\$ret = \$seq->characteristic(\$key)`

Return something if the sequence has a `\$key` (a string) characteristic, or `undef` if not. This is intended as a loose set of expressing features or properties a sequence might have.

``    digits      the radix (an integer), if sequence is digits``
`\$str = \$seq->oeis_anum()`

Return the Online Encyclopedia of Integer Sequences A-number (a string) of `\$seq`, or `undef` if not in the OEIS or not known. For example

``````    my \$seq = Math::NumSeq::Squares->new;
my \$anum = \$seq->oeis_anum;
# gives \$anum eq "A000290"``````

The web page for that is then

``    http://oeis.org/A000290``

Sometimes the OEIS has duplicates, ie. two A-numbers which are the same sequence. `\$seq->oeis_anum()` generally returns whichever is the primary one, at least for accidental duplication.

`\$aref = Math::NumSeq::Foo->parameter_info_array()`
`@list = Math::NumSeq::Foo->parameter_info_list()`

Return an arrayref of list describing the parameters taken by a given class. This meant to help making widgets etc for user interaction in a GUI. Each element is a hashref

``````    {
name        =>    parameter key arg for new()
type        =>    string "integer","boolean","enum" etc
default     =>    value
minimum     =>    number, or undef
maximum     =>    number, or undef
width       =>    integer, suggested display size
choices     =>    for enum, an arrayref
}``````

`type` is a string, one of

``````    "integer"
"enum"
"boolean"
"string"
"filename"``````

"filename" is separate from "string" since it might require subtly different handling to ensure it reaches Perl as a byte string, whereas a "string" type might in principle take Perl wide chars.

For "enum" the `choices` field is the possible values, such as

``````    { name => "flavour",
type => "enum",
choices => ["strawberry","chocolate"],
}``````

`minimum` and `maximum` are omitted if there's no hard limit on the parameter.

## Optional Methods

The following methods are only implemented for some sequences, since it's sometimes difficult to generate an arbitrary numbered element etc. Check with `\$seq->can('ith')` etc before using.

`\$value = \$seq->ith(\$i)`

Return the `\$i`'th value in the sequence. Only some sequence classes implement this method.

`\$bool = \$seq->pred(\$value)`

Return true if `\$value` occurs in the sequence. For example for the squares this would return true if `\$value` is a square or false if not.

Math::NumSeq::Aronson, in the Math-Aronson dist

Math::Sequence and Math::Series, for symbolic recursive sequence definitions

math-image