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 values. The iterators generally try to be progressive, so not calculating too far ahead, yet doing reasonable chunks for efficiency.
Sequence values have an integer index "i" starting either from i=0 or i=1 or whatever best suits the sequence. The values 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 some kind of NaN or infinite return (some unspecified kind as yet).
Some sequences automatically promote to Math::BigInt
, usually when values grows so fast that precision would soon be lost. An application can preload Math::BigInt
to select a backend or other global options.
FUNCTIONS
In the following "Foo" is one of the subclass names.
Iterating
($i, $value) = $seq>next()

Return the next index and value in the sequence.
Most sequences are infinite and for them there's always a next value. But if
$seq
is finite then at the end the return is no values. So for examplewhile (my ($i, $value) = $seq>next) { print "$i $value\n"; }
$seq>rewind()

Rewind the sequence to its starting point. The next call to
next()
will be the initial$i,$value
again.See "Optional Methods" below for possible arbitrary "seeks".
$i = $seq>tell_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 positionrewind()
returns to. $str = $seq>description()

Return a humanreadable description of the sequence. This might be translated into the locale language, though 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
$key
(a string) characteristic, orundef
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 value[i+1] > value[i] always non_decreasing boolean, true if value[i+1] >= value[i] always increasing_from_i integer, i for which value[i+1] > value[i] non_decreasing_from_i integer, i for which value[i+1] >= value[i] value_is_radix boolean, value is radix for i
value_is_radix
means each value is a radix applying to the i index. For exampleRepdigitRadix
value is a radix for which i is a repdigit. These values might also be 0 or 1 or 1 or some such nonradix to indicate no radix. $str = $seq>oeis_anum()

Return the Anumber (a string) for
$seq
in Sloane's Online Encyclopedia of Integer Sequences, or returnundef
if not in the OEIS or not known. For examplemy $seq = Math::NumSeq::Squares>new; my $anum = $seq>oeis_anum; # gives $anum = "A000290"
The web page for that is then
Sometimes the OEIS has duplicates, ie. two Anumbers 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 description => human readable string 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 humanreadable strings for those choices, possibly translated into another language (though there's no translations yet).minimum
andmaximum
are omitted (orundef
) 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 thename
is enough, but when the same name has slightly different meanings in different classes ashare_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.Usually
seek_to_value()
only makes sense for sequences where all values are distinct, so that a value is an unambiguous location. $value = $seq>ith($i)

Return the
$i
'th value in the sequence. Only some sequence classes implement this method. ($v0, $v1) = $seq>ith_pair($i)

Return two values
ith($i)
andith($i+1)
from the sequence. This method can be used wheneverith()
exists.$seq>can('ith_pair')
says whetherith_pair()
can be used (and gives a coderef).For some sequences a pair of values can be calculated with less work than two separate
ith()
calls. $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($value)
$i = $seq>value_to_i_ceil($value)
$i = $seq>value_to_i_floor($value)

Return the index i of
$value
. If$value
is not in the sequence thenvalue_to_i()
returnsundef
, orvalue_to_i_ceil()
returns the i of the next higher value which is,value_to_i_floor()
the i of the next lower value.These methods usually only make sense for monotonic increasing sequences, or perhaps nondecreasing so with some repeating values.
$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 applypred()
to each target.
SEE ALSO
Math::NumSeq::Squares, Math::NumSeq::Cubes, Math::NumSeq::Pronic, Math::NumSeq::Triangular, Math::NumSeq::Polygonal, Math::NumSeq::Tetrahedral, Math::NumSeq::StarNumbers, Math::NumSeq::Powerful, Math::NumSeq::PowerPart, Math::NumSeq::PowerFlip
Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All, Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers, Math::NumSeq::Runs
Math::NumSeq::Primes, Math::NumSeq::TwinPrimes, Math::NumSeq::SophieGermainPrimes, Math::NumSeq::AlmostPrimes, Math::NumSeq::DeletablePrimes, Math::NumSeq::Emirps, Math::NumSeq::MobiusFunction, Math::NumSeq::LiouvilleFunction, Math::NumSeq::DivisorCount, Math::NumSeq::GoldbachCount, Math::NumSeq::LemoineCount, Math::NumSeq::PythagoreanHypots
Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder, Math::NumSeq::PrimeIndexPrimes
Math::NumSeq::Totient, Math::NumSeq::TotientCumulative, Math::NumSeq::TotientSteps, Math::NumSeq::TotientStepsSum, Math::NumSeq::TotientPerfect, Math::NumSeq::DedekindPsiCumulative, Math::NumSeq::DedekindPsiSteps, Math::NumSeq::Abundant, Math::NumSeq::PolignacObstinate
Math::NumSeq::Factorials, Math::NumSeq::Primorials, Math::NumSeq::Fibonacci, Math::NumSeq::LucasNumbers, Math::NumSeq::FibonacciWord, Math::NumSeq::FibonacciRepresentations, Math::NumSeq::PisanoPeriod, Math::NumSeq::PisanoPeriodSteps, Math::NumSeq::Fibbinary, Math::NumSeq::FibbinaryBitCount
Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary, Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin, Math::NumSeq::SpiroFibonacci
Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits, Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued, Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow, Math::NumSeq::DigitCountHigh
Math::NumSeq::DigitLength, Math::NumSeq::DigitLengthCumulative, Math::NumSeq::SelfLengthCumulative, Math::NumSeq::DigitProduct, Math::NumSeq::DigitProductSteps, Math::NumSeq::DigitSum, Math::NumSeq::DigitSumModulo, Math::NumSeq::RadixWithoutDigit, Math::NumSeq::RadixConversion, Math::NumSeq::MaxDigitCount
Math::NumSeq::Palindromes, Math::NumSeq::Xenodromes, Math::NumSeq::Beastly, Math::NumSeq::Repdigits, Math::NumSeq::RepdigitAny, Math::NumSeq::RepdigitRadix, Math::NumSeq::UndulatingNumbers, Math::NumSeq::HarshadNumbers, Math::NumSeq::MoranNumbers, Math::NumSeq::HappyNumbers, Math::NumSeq::HappySteps
Math::NumSeq::CullenNumbers, Math::NumSeq::ProthNumbers, Math::NumSeq::WoodallNumbers, Math::NumSeq::BaumSweet, Math::NumSeq::GolayRudinShapiro, Math::NumSeq::GolayRudinShapiroCumulative, Math::NumSeq::MephistoWaltz, Math::NumSeq::HafermanCarpet, Math::NumSeq::KlarnerRado, Math::NumSeq::UlamSequence, Math::NumSeq::ReRound, Math::NumSeq::ReReplace, Math::NumSeq::LuckyNumbers
Math::NumSeq::CollatzSteps, Math::NumSeq::ReverseAdd, Math::NumSeq::ReverseAddSteps, Math::NumSeq::JugglerSteps, Math::NumSeq::SternDiatomic, Math::NumSeq::NumAronson, Math::NumSeq::HofstadterFigure, Math::NumSeq::DuffinianNumbers
Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence, Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
Math::NumSeq::AlphabeticalLength, Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in the MathNumSeqAlpha dist)
Math::NumSeq::Aronson (in the MathAronson dist)
Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta, Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the MathPlanePath dist)
Other Modules Etc
Math::Sequence and Math::Series, for symbolic recursive sequence definitions
mathimage, for displaying images with the NumSeq sequences
HOME PAGE
http://user42.tuxfamily.org/mathnumseq/index.html
LICENSE
Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2019 Kevin Ryde
MathNumSeq is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.
MathNumSeq is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with MathNumSeq. If not, see <http://www.gnu.org/licenses/>.