Math::NumSeq::OEIS(3)

💖 Math::NumSeq::OEIS 💖

okay bestie, welcome to the Math::NumSeq::OEIS(3) page — that's the manual for the User Contributed Perl Documentation era of things, and it's about pulling a number sequence out of the OEIS by its A-number. no cap, it's giving "I have 400,000 integer sequences and I only want one". let's go 🦋

---

✨ NAME ✨

Math::NumSeq::OEIS — get a number sequence by its OEIS A-number 💅

---

🌸 SYNOPSIS 🌸

use Math::NumSeq::OEIS;
my $seq = Math::NumSeq::OEIS->new (anum => 'A000032');
my ($i, $value) = $seq->next;

see how easy? you hand it an A-number, it hands you a sequence. iconic behavior, honestly 👑

---

🎀 DESCRIPTION 🎀

so this module picks out a "NumSeq" using an A-number from Sloane's Online Encyclopedia of Integer Sequences. that's the whole vibe.

if there's actual "NumSeq" code that already implements the sequence, then that's what gets used ✨. otherwise it falls back to local downloaded OEIS files, if you have any. and if you wanna know which A-numbers are even available to query? go see Math::NumSeq::OEIS::Catalogue, she has the receipts.

---

📁 Files 📁

local files need to live in a ~/OEIS direectory — yes, that spelling is in the original, i'm keeping it, don't @ me — which is an OEIS directory in the user's home directory (that's File::HomeDir doing the finding 🧚). files can be HTML, OEIS internal, b-file, and/or a-file. like:

~/OEIS/A000032.html
~/OEIS/A000032.internal.txt
~/OEIS/A000032.internal.html
~/OEIS/b000032.txt
~/OEIS/a000032.txt

as downloaded from, for example:

http://oeis.org/A000032
http://oeis.org/search?q=id:A000032&fmt=text
http://oeis.org/A000032/internal
http://oeis.org/A000032/b000032.txt
http://oeis.org/A000032/a000032.txt

the "internal" text format is the most reliable one for parsing, periodt. that's the "text" link on each sequence web page (filename .internal.txt). and the "internal" link? same thing but wrapped in HTML (filename .internal.html).

b-files like b000000.txt are long lists of values 📜. a-files like a000000.txt are similar and even longer — but sometimes they're auxiliary info instead (and in that case, not used, sorry girl). all sequences have a b-file, but sometimes they're just the web page samples dropped into a separate file 🙈. (the web page samples might be plenty for fast growing sequences, so it's fine.)

b-file or a-file can be used alone by this module, without the text or HTML parts. but in that case there's no $seq->description() and it may limit the $seq->characteristic() attributes. so like, tradeoffs 💀

---

💭 Other Notes 💭

sometimes more than one NumSeq module generates the same OEIS sequence. for example A000290 is Squares, and also Polygonal k=4. the catalogue is arranged so "Math::NumSeq::OEIS" picks the better, faster, or more specific one. she has taste 💅

sometimes the OEIS has duplicates — two A-numbers that are literally the same sequence. both get catalogued so both give NumSeq module code, but the $seq->oeis_anum() method generally only returns whichever one is the "primary" one. main character energy only 👑

right now, NumSeq code is only catalogued with A-numbers when it's the same as the OEIS sequence. in particular that means "offset" in the OEIS matches "i_start" of the NumSeq, so i here corresponds to n there. sometimes an "i_start" parameter here can alter the numbering suitably (and in "PlanePathCoord" etc tie-ins, the similar "n_start"), but some NumSeq may be uncatalogued because the numbering or the first few values just aren't the same. it's not them, it's the offset 😭

---

🔥 FUNCTIONS 🔥

see "FUNCTIONS" in Math::NumSeq for the behaviour common to all sequence classes. group-chat-wide rules, iykyk.

• $seq = Math::NumSeq::OEIS->new (anum => 'A000000') — create and return a new sequence object. that's it, that's the girl ✨

---

🔁 Iterating 🔁

• ($i, $value) = $seq->next() — return the next index and value in the sequence.

in the current code, when reading from a file, any values bigger than a usual Perl int or float get returned as "Math::BigInt" objects, so that precision is preserved for numeric operations 🫶. an application can pre-load "Math::BigInt" to choose its back-end or other global options. big numbers deserve big care, bestie.

an a000000.txt or b000000.txt file is read line by line. for ithreads of Perl 5.8 up there's a "CLONE" setup which re-opens the file in the new thread, so $seq in each thread has its own position. (see perlthrtut and "Making your module threadsafe" in perlmod.)

⚠️ but a process fork() will have both parent and child with the same open file — so be careful that only one of them uses $seq in that case. this is the same as for all open files across a fork(). no duplicating the vibe, okay? 🙈

---

🎲 Random Access 🎲

• $value = $seq->ith($i) — return the $i'th value from $seq, or "undef" if $i is outside the range of available values.

an a000000.txt or b000000.txt file is read by a binary search to find the target $i. this is reasonably efficient and avoids loading or processing an entire file if you only want a few values. efficient queen 🧚

if $i happens to be the next line, or just a short distance ahead of what was last read, then no search is necessary at all. so ith() called sequentially i=1,2,3,4,etc simply reads successive lines the same as next() would do. lowkey seamless ✨

---

📖 Information 📖

• $str = $seq->description() — return a human-readable description of the sequence. for downloaded files, this is the name part ("%N"), which is a short description of the sequence.

some sequences may have non-ASCII characters in the description, usually in names of people 🫶. for Perl 5.8 and up they're decoded to wide-chars. for earlier Perl they're left as the bytes from the download, which is UTF-8.

• $value = $seq->values_min()
• $value = $seq->values_max()

return the minimum or maximum values in the sequence, or "undef" if unknown or infinity.

for files, values_min() is guessed from the first few values if non-negative, and values_max() is normally considered to be infinite ♾️. for keyword "full", the samples are the entire sequence and they give the range. if a range seems to be limited (eg. sequences of -1,0,1) then min and max are obtained from those.

(they would like the OEIS data to have range information like this in machine-readable form. it's usually in sequence comments or implicit in the definition for human readers. so, you know, vibes-based 💀)

• $ret = $seq->characteristic($key) — for a file, the following standard characteristics are obtained (per "Information" in Math::NumSeq):
  • "integer" is always true. ✅
  • "increasing", "non_decreasing" and "smaller" are determined from the sample values, or the first few values from an a-file or b-file. looking at only the few ensures a big file isn't read in its entirety and is normally enough. the intention would be to look at enough values not to be tricked by decreasing values after the first few, etc. sneaky little sequences 🙈
  • "digits" comes from keyword "cons" for decimal constants. some other digit sequences are recognised by their name part, though this may be unreliable.
  • "count" comes from a name with "number of". this is unreliable but often close enough. ngl, it's giving approximation 💅

all the keywords from the OEIS are provided as booleans under names like "OEIS_easy" etc. so for example:

if ($seq->characteristic("OEIS_nice")) {
  print "nooiice ...\n";
}

---

👀 SEE ALSO 👀

Math::NumSeq, Math::NumSeq::OEIS::Catalogue

---

🏠 HOME PAGE 🏠

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

---

📜 LICENSE 📜

Copyright 2011, 2012, 2013, 2014, 2016, 2018, 2019, 2020 Kevin Ryde

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.

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, slay 💖✨

this lil manual page came from perl v5.42.0, dated 2025-07-25, and it's Math::NumSeq::OEIS(3) — go forth and sequence responsibly, mwah 🎀🦋