1Math::NumSeq::OEIS(3) User Contributed Perl DocumentationMath::NumSeq::OEIS(3)
2
6 Math::NumSeq::OEIS -- number sequence by OEIS A-number
7
9 use Math::NumSeq::OEIS;
10 my $seq = Math::NumSeq::OEIS->new (anum => 'A000032');
11 my ($i, $value) = $seq->next;
12
14 This module selects a "NumSeq" by an A-number of Sloane's Online
15 Encyclopedia of Integer Sequences.
16 If there's "NumSeq" code implementing the sequence then that's used,
18 otherwise local downloaded OEIS files if available. See
19 Math::NumSeq::OEIS::Catalogue for querying available A-numbers.
20 Files
22 Local files should be in a ~/OEIS direectory, ie. an OEIS directory in
23 the user's home directory (File::HomeDir). Files can be HTML, OEIS
24 internal, b-file, and/or a-file.
25 ~/OEIS/A000032.html
27 ~/OEIS/A000032.internal.txt
28 ~/OEIS/A000032.internal.html
29 ~/OEIS/b000032.txt
30 ~/OEIS/a000032.txt
31 As downloaded from for example
33 http://oeis.org/A000032
35 http://oeis.org/search?q=id:A000032&fmt=text
36 http://oeis.org/A000032/internal
37 http://oeis.org/A000032/b000032.txt
38 http://oeis.org/A000032/a000032.txt
39 The "internal" text format is the most reliable for parsing. This is
41 the "text" link in each sequence web page (filename .internal.txt).
42 The "internal" link is the same wrapped in HTML (filename
43 .internal.html).
44 b-files b000000.txt are long lists of values. a-files a000000.txt
46 similarly and even longer, but sometimes they are auxiliary info
47 instead (and in that case not used). All sequences have a b-file, but
48 sometimes they are merely the web page samples put into a separate
49 file. (The web page samples might be enough for fast growing
50 sequences.)
51 b-file or a-file can be used alone by this module, without the text or
53 HTML parts. In that case there's no "$seq->description()" and it may
54 limit the "$seq->characteristic()" attributes.
55 Other Notes
57 Sometimes more than one NumSeq module generates an OEIS sequence. For
58 example A000290 is Squares, and also Polygonal k=4. The catalogue is
59 arranged so "Math::NumSeq::OEIS" selects the better, faster, or more
60 specific one.
61 Sometimes the OEIS has duplicates, ie. two A-numbers which are the same
63 sequence. Both are catalogued so they both give NumSeq module code,
64 but the "$seq->oeis_anum()" method generally only returns whichever is
65 the "primary" one.
66 Presently NumSeq code is catalogued with A-numbers only when it is the
68 same as the OEIS sequence. In particular this means "offset" in the
69 OEIS matching "i_start" of the NumSeq, so i here corresponds to n
70 there. Sometimes an "i_start" parameter here can alter numbering
71 suitably (and in "PlanePathCoord" etc tie-ins the similar "n_start"),
72 but some NumSeq may be uncatalogued because numbering or first few
73 values are not the same.
74
76 See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence
77 classes.
78 "$seq = Math::NumSeq::OEIS->new (anum => 'A000000')"
80 Create and return a new sequence object.
81 Iterating
83 "($i, $value) = $seq->next()"
84 Return the next index and value in the sequence.
85 In the current code, when reading from a file, any values bigger
87 than a usual Perl int or float are returned as "Math::BigInt"
88 objects in order to preserve precision for numeric operations. An
89 application can pre-load "Math::BigInt" to choose its back-end or
90 other global options.
91 An a000000.txt or b000000.txt file is read line by line. For
93 ithreads of Perl 5.8 up there's a "CLONE" setup which re-opens the
94 file in the new thread so $seq in each thread has its own position.
95 (See perlthrtut and "Making your module threadsafe" in perlmod.)
96 But a process "fork()" will have both parent and child with the
98 same open file so care should be taken that only one of them uses
99 $seq in that case. This is the same as for all open files across a
100 "fork()".
101 Random Access
103 "$value = $seq->ith($i)"
104 Return the $i'th value from $seq, or "undef" if $i is outside the
105 range of available values.
106 An a000000.txt or b000000.txt file is read by a binary search to
108 find the target $i. This is reasonably efficient and avoids
109 loading or processing an entire file if just a few values are
110 wanted.
111 If $i happens to be the next line or just a short distance ahead of
113 what was last read then no search is necessary. So "ith()" called
114 sequentially i=1,2,3,4,etc simply reads successive lines the same
115 as "next()" would do.
116 Information
118 "$str = $seq->description()"
119 Return a human-readable description of the sequence. For
120 downloaded files, this is the name part ("%N") which is a short
121 description of the sequence.
122 Some sequences may have non-ASCII characters in the description,
124 usually in names of people. For Perl 5.8 and up they're decoded to
125 wide-chars. For earlier Perl they're left as the bytes from the
126 download, which is UTF-8.
127 "$value = $seq->values_min()"
129 "$value = $seq->values_max()"
130 Return the minimum or maximum values in the sequence, or "undef" if
131 unknown or infinity.
132 For files, "values_min()" is guessed from the first few values if
134 non-negative, and "values_max()" is normally considered to be
135 infinite. For keyword "full", the samples are the entire sequence
136 and they give the range. If a range seems to be limited (eg.
137 sequences of -1,0,1) then min and max are obtained from those.
138 (Would like the OEIS data to have range information like this in
140 machine-readable form. It's usually in sequence comments or
141 implicit in the definition for human readers.)
142 "$ret = $seq->characteristic($key)"
144 For a file, the following standard characteristics are obtained
145 (per "Information" in Math::NumSeq),
146 • "integer" always true.
148 • "increasing", "non_decreasing" and "smaller" are determined
150 from the sample values or the first few values from an a-file
151 or b-file. Looking at only the few ensures a big file isn't
152 read in its entirety and is normally enough. The intention
153 would be to look at enough values not to be tricked by
154 decreasing values after the first few, etc.
155 • "digits" is from keyword "cons" for decimal constants. Some
157 other digit sequences are recognised by their name part though
158 this may be unreliable.
159 • "count" is from a name with "number of". This is unreliable
161 but often close enough.
162 All the keywords from the OEIS are provided as booleans under names
164 "OEIS_easy" etc. So for example
165 if ($seq->characteristic("OEIS_nice")) {
167 print "nooiice ...\n";
168 }
169
171 Math::NumSeq, Math::NumSeq::OEIS::Catalogue
172
174 <http://user42.tuxfamily.org/math-numseq/index.html>
175
177 Copyright 2011, 2012, 2013, 2014, 2016, 2018, 2019 Kevin Ryde
178 Math-NumSeq is free software; you can redistribute it and/or modify it
180 under the terms of the GNU General Public License as published by the
181 Free Software Foundation; either version 3, or (at your option) any
182 later version.
183 Math-NumSeq is distributed in the hope that it will be useful, but
185 WITHOUT ANY WARRANTY; without even the implied warranty of
186 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
187 General Public License for more details.
188 You should have received a copy of the GNU General Public License along
190 with Math-NumSeq. If not, see <http://www.gnu.org/licenses/>.
191perl v5.34.0 2021-07-22 Math::NumSeq::OEIS(3)