1Math::NumSeq::OEIS(3) User Contributed Perl DocumentationMath::NumSeq::OEIS(3)
2
3
4

NAME

6       Math::NumSeq::OEIS -- number sequence by OEIS A-number
7

SYNOPSIS

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

DESCRIPTION

14       This module selects a "NumSeq" by an A-number of Sloane's Online
15       Encyclopedia of Integer Sequences.
16
17       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
21   Files
22       Local files should be in a ~/OEIS direectory, ie. an OEIS directory in
23       the user's home directory (see File::HomeDir).  Files can be HTML, OEIS
24       internal, b-file, and/or a-file.
25
26           ~/OEIS/A000032.html
27           ~/OEIS/A000032.internal.txt
28           ~/OEIS/A000032.internal.html
29           ~/OEIS/b000032.txt
30           ~/OEIS/a000032.txt
31
32       As downloaded from for example
33
34           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
40       The "internal" text format is the most reliable for parsing.  This is
41       the "text" link in the main sequence pages.  The "internal" link is the
42       same wrapped in HTML.  It can be used here as .internal.html.
43
44       b-files b000000.txt are long lists of values.  a-files a000000.txt
45       similarly and even longer, but sometimes they are auxiliary info
46       instead (and in that case not used).  Some sequences don't have these,
47       only the 30 or 40 sample values from the HTML or internal page.  Those
48       samples might be enough for fast growing sequences.
49
50       b-file or a-file can be used alone by this module, without the text or
51       HTML parts.  In that case there's no "$seq->description()" and it may
52       limit the "$seq->characteristic()" attributes.
53
54   Other Notes
55       Sometimes more than one NumSeq module generates an OEIS sequence.  For
56       example A000290 is Squares but also Polygonal k=4.  The catalogue is
57       arranged so "Math::NumSeq::OEIS" selects the better, faster, or more
58       specific one.
59
60       Sometimes the OEIS has duplicates, ie. two A-numbers which are the same
61       sequence.  Both are catalogued so they both give NumSeq module code,
62       but the "$seq->oeis_anum()" method generally only returns whichever is
63       the "primary" one.
64
65       Presently NumSeq code is catalogued with A-numbers only when it is the
66       same as the OEIS sequence.  In particular this means "offset" in the
67       OEIS matching the "i_start" of the NumSeq, so i here corresponds to n
68       there.  Sometimes an "i_start" parameter here can alter numbering
69       suitably (and in "PlanePathCoord" etc tie-ins the similar "n_start"),
70       but some NumSeq may be uncatalogued because numbering or perhaps first
71       few values are not the same.
72

FUNCTIONS

74       See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence
75       classes.
76
77       "$seq = Math::NumSeq::OEIS->new (anum => 'A000000')"
78           Create and return a new sequence object.
79
80   Iterating
81       "($i, $value) = $seq->next()"
82           Return the next index and value in the sequence.
83
84           In the current code when reading from a file, any values bigger
85           than a usual Perl int or float are returned as "Math::BigInt"
86           objects in order to preserve precision.  Is that a good idea?
87
88           An a000000.txt or b000000.txt file is read line by line.  For Perl
89           5.8 ithreads there's a "CLONE" setup which re-opens the file in a
90           new thread so $seq in each thread has its own position.  (See
91           perlthrtut and "Making your module threadsafe" in perlmod.)
92
93           But a process "fork()" will have both parent and child with the
94           same open file so care should be taken that only one of them uses
95           $seq in that case.  The same is true of all open file handling
96           across a "fork()".
97
98   Random Access
99       "$value = $seq->ith($i)"
100           Return the $i'th value from $seq, or "undef" if $i is outside the
101           range of available values.
102
103           An a000000.txt or b000000.txt file is read by a binary search to
104           find the target $i.  This is reasonably efficient and avoids
105           loading or processing an entire file if just a few values are
106           wanted.
107
108           If $i happens to be the next line or just a short distance ahead of
109           what was last read then no search is necessary.  This means that
110           "ith()" called sequentially i=1,2,3,4,etc simply reads successive
111           lines the same as "next()" would do.
112
113   Information
114       "$str = $seq->description()"
115           Return a human-readable description of the sequence.  For the
116           downloaded files this is the name part ("%N") which is a short
117           description of the sequence.
118
119           A few sequences may have non-ASCII characters in the description.
120           For Perl 5.8 and up they're decoded to wide-chars.  Not sure what
121           to do for earlier Perl, currently they're left as the bytes from
122           the download, which may be utf-8.
123
124       "$value = $seq->values_min()"
125       "$value = $seq->values_max()"
126           Return the minimum or maximum values in the sequence, or "undef" if
127           unknown or infinity.
128
129           For files, "values_min()" is guessed from the first few values if
130           non-negative, and "values_max()" is normally considered to be
131           infinite.  For keyword "full" the samples are the entire sequence
132           and gives the range. If a range seems to be limited (eg. sequences
133           of -1,0,1) then min and max are obtained from those.
134
135           (Would like the OEIS data to have range information like this in
136           machine-readable form.  It's usually in sequence comments or
137           description for human readers.)
138
139       "$ret = $seq->characteristic($key)"
140           For a file, the following standard characteristics are obtained
141           (per "Information" in Math::NumSeq),
142
143           ·   "integer" always true.
144
145           ·   "increasing", "non_decreasing" and "smaller" are determined
146               from the sample values or the first few values from an a-file
147               or b-file.  Looking at only the few ensures a big file isn't
148               read in its entirety and is normally enough.  The intention
149               would be to look at enough values not to be tricked by
150               decreasing values after the first few, etc.
151
152           ·   "digits" is from keyword "cons" for decimal constants.  Some
153               other digit sequences are recognised by their name part though
154               this may be unreliable.
155
156           ·   "count" is from a name with "number of".  This is probably
157               unreliable.
158
159           All the keywords from the OEIS are provided as booleans under names
160           "OEIS_easy" etc.  So for example
161
162               if ($seq->characteristic("OEIS_nice")) {
163                 print "nooiice ...\n";
164               }
165

SEE ALSO

167       Math::NumSeq, Math::NumSeq::OEIS::Catalogue
168

HOME PAGE

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

LICENSE

173       Copyright 2011, 2012, 2013, 2014, 2016 Kevin Ryde
174
175       Math-NumSeq is free software; you can redistribute it and/or modify it
176       under the terms of the GNU General Public License as published by the
177       Free Software Foundation; either version 3, or (at your option) any
178       later version.
179
180       Math-NumSeq is distributed in the hope that it will be useful, but
181       WITHOUT ANY WARRANTY; without even the implied warranty of
182       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
183       General Public License for more details.
184
185       You should have received a copy of the GNU General Public License along
186       with Math-NumSeq.  If not, see <http://www.gnu.org/licenses/>.
187
188
189
190perl v5.28.0                      2016-03-19             Math::NumSeq::OEIS(3)
Impressum