++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 some number sequences. Sequence objects can iterate through values and some sequences have random access and/or a predicate test.

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 a class except for the genericness. Other sequences are trickier and an iterator is a good way to go through the values. The iterating tries to be progressive, so not calculating too far ahead yet doing reasonable size chunks for efficiency.

Sequence values have an integer index "i" starting either from i=0 or i=1 or similar as best suits the sequence. The values themselves can be anything, positive, negative, fractional, etc.

The intention is that all modules `Math::NumSeq::Foo` are sequence classes, and that supporting things are deeper, such as under `Math::NumSeq::Something::Helper` or `Math::NumSeq::Base::SharedStuff`.

## Number Types

The various methods try to support `Math::BigInt` and similar overloaded number types. So for instance `pred()` might be applied to test a big value, or `ith()` on a bigint to preserve precision from some rapidly growing sequence. Infinities and NaNs give nan or infinite returns of some kind (some unspecified kind as yet).

# FUNCTIONS

In the following "Foo" is one of the subclass names.

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

Create and return a new sequence object.

## Iterating

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

Return the next index and value in the sequence.

`\$seq->rewind()`

Rewind the sequence to its starting point.

`\$i = \$seq->tell_i(\$i)`

Return the current i position. This is the i which the next call to `next()` will return.

## Information

`\$i = \$seq->i_start()`

Return the first index `\$i` in the sequence. This is the position `rewind()` returns to.

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

Return a human-readable description of the sequence. This might be translated into the locale language, but there's no message translations yet.

`\$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 features or properties a sequence can have to describe itself.

``````    digits            integer or undef, the radix if seq is digits
count             boolean, true if values are counts of something
smaller           boolean, true if value[i] < i generally
integer           boolean, true if all values are integers

increasing        boolean, true if v[i+1] > v[i] always
non_decreasing    boolean, true if v[i+1] >= v[i] always
increasing_from_i     integer, i for which v[i+1] > v[i]
non_decreasing_from_i integer, i for which v[i+1] >= v[i]

`value_is_radix` means each value is a radix applying to the i index. For example `RepdigitRadix` value is a radix for which i is a repdigit. These values might also be 0 or 1 or -1 or some such non-radix to indicate no radix.

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

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

``````    my \$seq = Math::NumSeq::Squares->new;
my \$anum = \$seq->oeis_anum;
# gives "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. When that's accidental or historical `\$seq->oeis_anum()` is whichever is reckoned the primary one.

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

Return an arrayref or 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()
share_key       => string, or undef
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
choices_display => 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 an arrayref of possible values, such as

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

`choices_display`, if provided, is human-readable strings for those choices, possibly translated into another language (though there's no translations yet).

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

`share_key` is designed to indicate when parameters from different NumSeq classes can be a single control widget in a GUI etc. Normally the `name` is enough, but when the same name has slightly different meanings in different classes a `share_key` keeps different meanings separate.

## Optional Methods

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

`\$seq->seek_to_i(\$i)`
`\$seq->seek_to_value(\$value)`

Move the current i so `next()` will return `\$i` or `\$value` on the next call. If `\$value` is not in the sequence then move so as to return the next higher value which is.

`\$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 returns true if `\$value` is a square or false if not.

`\$i = \$seq->value_to_i_ceil(\$value)`
`\$i = \$seq->value_to_i_floor(\$value)`

Return the index i of `\$value`, or if `\$value` is not in the sequence then the i of the next higher or lower value which is. These methods usually only make sense for monotonic increasing sequences, or perhaps with some repeating values so non-decreasing.

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

Return an estimate of the i corresponding to `\$value`.

The accuracy of this estimate is unspecified, but can at least hint at the growth rate of the sequence. For example if making an "intersection" checking for given values in the sequence then if the estimated i is small it may be fastest to go through the sequence by `next()` and compare, rather than apply `pred()` to each target.

Math::NumSeq::AlphabeticalLength, Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in the Math-NumSeq-Alpha dist)

Math::NumSeq::Aronson (in the Math-Aronson dist)

Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta, Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the Math-PlanePath dist)

## Other Modules Etc

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

math-image, for displaying images with the NumSeq sequences