Math::NumSeq(3)

📦

version 75 · 2 versions

75 · fedora 43 (latest)
75 · fedora 44

💖 NAME 💖

Math::NumSeq — number sequences. This is the Math::NumSeq(3) page from User Contributed Perl Documentation, hiii bestie. 💅

✨ 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 🦋

Okay so Math::NumSeq 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. Slay.

The whole idea? 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. Periodt.

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. No cap.

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. iykyk.

🌈 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 pre-load Math::BigInt to select a back-end or other global options. 💅

🎀 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. New seq object just dropped, bestie. 👑

🔥 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 example

while (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 position rewind() returns to.
$str = $seq->description() — return a human-readable description of the sequence. This might be translated into the locale language, though there's no message translations yet.
$value = $seq->values_min() — return the minimum value taken by values in the sequence, or undef if unknown or infinity.
$value = $seq->values_max() — return the 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, 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 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 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 $anum = "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() — return an arrayref describing the parameters taken by a given class.
@list = Math::NumSeq::Foo->parameter_info_list() — return a 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 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) — move the current i so next() will return $i on the next call.
$seq->seek_to_value($value) — move the current i so next() will return $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) and ith($i+1) from the sequence. This method can be used whenever ith() exists. $seq->can('ith_pair') says whether ith_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) — return the index i of $value. If $value is not in the sequence then value_to_i() returns undef.
$i = $seq->value_to_i_ceil($value) — return the index i of $value. If $value is not in the sequence then value_to_i_ceil() returns the i of the next higher value which is.
$i = $seq->value_to_i_floor($value) — return the index i of $value. If $value is not in the sequence then value_to_i_floor() returns the i of the next lower value.

These methods usually only make sense for monotonic increasing sequences, or perhaps non-decreasing 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 apply pred() to each target.

🌈 SEE ALSO

okay so bestie, the whole point of this module is that it's the front door to a truly unhinged number of sequence modules 💖 so here's the full tour, grouped how the original groups them, no skipping, we're doing all of them:

Shapes & figurate cuties — 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
Just vibes, honestly — Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All, Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers, Math::NumSeq::Runs
Prime girlies 👑 — 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
Factor era — Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
Prime-indexed lore — Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder, Math::NumSeq::PrimeIndexPrimes
Totient & friends 🎀 — 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
Recursion brainrot ✨ — 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
More recursion, different flavour — Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary, Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin, Math::NumSeq::SpiroFibonacci
Digits of irrationals, iconic — Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits, Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued, Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
Counting digits — Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow, Math::NumSeq::DigitCountHigh
Digit manipulation station — 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
Cute little number quirks 💅 — 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
The weird ones (affectionate) 🦋 — 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
Iterate-until-it-does-something hours — Math::NumSeq::CollatzSteps, Math::NumSeq::ReverseAdd, Math::NumSeq::ReverseAddSteps, Math::NumSeq::JugglerSteps, Math::NumSeq::SternDiatomic, Math::NumSeq::NumAronson, Math::NumSeq::HofstadterFigure, Math::NumSeq::DuffinianNumbers
Self-describing chaos — Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence, Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
Build your own 🔥 — Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
Wordy ones — Math::NumSeq::AlphabeticalLength, Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in the Math-NumSeq-Alpha dist)
Also wordy — Math::NumSeq::Aronson (in the Math-Aronson dist)
Plane path crossover episode — 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

🏠 HOME PAGE

http://user42.tuxfamily.org/math-numseq/index.html

📜 LICENSE

Math-NumSeq 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.

Math-NumSeq 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.

fr fr read that part again bestie — WITHOUT ANY WARRANTY, no implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, that's the actual legal vibe, don't skip it 💀

You should have received a copy of the GNU General Public License along with Math-NumSeq. If not, see <http://www.gnu.org/licenses/>.

and that's the whole page, bestie 🫶 you made it to the end, which is giving main character energy ngl. this was Math::NumSeq(3) from perl v5.42.0, dated 2025-07-25 — go forth and sequence something iconic ✨💖🎀

📦 where this page comes from

fedora 43: perl-Math-NumSeq 75-11.fc43 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms