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

NAME

6       Math::NumSeq -- number sequences
7

SYNOPSIS

9        # only a base class, use one of the actual classes, such as
10        use Math::NumSeq::Squares;
11        my $seq = Math::NumSeq::Squares->new;
12        my ($i, $value) = $seq->next;
13

DESCRIPTION

15       This is a base class for some number sequences.  Sequence objects can
16       iterate through values and some sequences have random access and/or a
17       predicate test.
18
19       The idea is to generate things like squares or primes in a generic way.
20       Some sequences, like squares, are so easy there's no need for a class
21       except for the genericness.  Other sequences are trickier and an
22       iterator is a good way to go through values.  The iterators generally
23       try to be progressive, so not calculating too far ahead, yet doing
24       reasonable chunks for efficiency.
25
26       Sequence values have an integer index "i" starting either from i=0 or
27       i=1 or whatever best suits the sequence.  The values can be anything,
28       positive, negative, fractional, etc.
29
30       The intention is that all modules "Math::NumSeq::Foo" are sequence
31       classes, and that supporting things are deeper, such as under
32       "Math::NumSeq::Something::Helper" or "Math::NumSeq::Base::SharedStuff".
33
34   Number Types
35       The various methods try to support "Math::BigInt" and similar
36       overloaded number types.  So for instance pred() might be applied to
37       test a big value, or ith() on a bigint to preserve precision from some
38       rapidly growing sequence.  Infinities and NaNs give some kind of NaN or
39       infinite return (some unspecified kind as yet).
40
41       Some sequences automatically promote to "Math::BigInt", usually when
42       values grows so fast that precision would soon be lost.  An application
43       can pre-load "Math::BigInt" to select a back-end or other global
44       options.
45

FUNCTIONS

47       In the following "Foo" is one of the subclass names.
48
49       "$seq = Math::NumSeq::Foo->new (key=>value,...)"
50           Create and return a new sequence object.
51
52   Iterating
53       "($i, $value) = $seq->next()"
54           Return the next index and value in the sequence.
55
56           Most sequences are infinite and for them there's always a next
57           value.  But if $seq is finite then at the end the return is no
58           values.  So for example
59
60               while (my ($i, $value) = $seq->next) {
61                 print "$i $value\n";
62               }
63
64       "$seq->rewind()"
65           Rewind the sequence to its starting point.  The next call to next()
66           will be the initial "$i,$value" again.
67
68           See "Optional Methods" below for possible arbitrary "seeks".
69
70       "$i = $seq->tell_i()"
71           Return the current i position.  This is the i which the next call
72           to next() will return.
73
74   Information
75       "$i = $seq->i_start()"
76           Return the first index $i in the sequence.  This is the position
77           rewind() returns to.
78
79       "$str = $seq->description()"
80           Return a human-readable description of the sequence.  This might be
81           translated into the locale language, though there's no message
82           translations yet.
83
84       "$value = $seq->values_min()"
85       "$value = $seq->values_max()"
86           Return the minimum or maximum value taken by values in the
87           sequence, or "undef" if unknown or infinity.
88
89       "$ret = $seq->characteristic($key)"
90           Return something if the sequence has $key (a string)
91           characteristic, or "undef" if not.  This is intended as a loose set
92           of features or properties a sequence can have to describe itself.
93
94               digits            integer or undef, the radix if seq is digits
95               count             boolean, true if values are counts of something
96               smaller           boolean, true if value[i] < i generally
97               integer           boolean, true if all values are integers
98
99               increasing        boolean, true if value[i+1] > value[i] always
100               non_decreasing    boolean, true if value[i+1] >= value[i] always
101               increasing_from_i     integer, i for which value[i+1] > value[i]
102               non_decreasing_from_i integer, i for which value[i+1] >= value[i]
103
104               value_is_radix    boolean, value is radix for i
105
106           "value_is_radix" means each value is a radix applying to the i
107           index.  For example "RepdigitRadix" value is a radix for which i is
108           a repdigit.  These values might also be 0 or 1 or -1 or some such
109           non-radix to indicate no radix.
110
111       "$str = $seq->oeis_anum()"
112           Return the A-number (a string) for $seq in Sloane's Online
113           Encyclopedia of Integer Sequences, or return "undef" if not in the
114           OEIS or not known.  For example
115
116               my $seq = Math::NumSeq::Squares->new;
117               my $anum = $seq->oeis_anum;
118               # gives $anum = "A000290"
119
120           The web page for that is then
121
122               <http://oeis.org/A000290>
123
124           Sometimes the OEIS has duplicates, ie. two A-numbers which are the
125           same sequence.  When that's accidental or historical
126           "$seq->oeis_anum()" is whichever is reckoned the primary one.
127
128       "$aref = Math::NumSeq::Foo->parameter_info_array()"
129       "@list = Math::NumSeq::Foo->parameter_info_list()"
130           Return an arrayref or list describing the parameters taken by a
131           given class.  This meant to help making widgets etc for user
132           interaction in a GUI.  Each element is a hashref
133
134               {
135                 name            => parameter key arg for new()
136                 share_key       => string, or undef
137                 description     => human readable string
138                 type            => string "integer","boolean","enum" etc
139                 default         => value
140                 minimum         => number, or undef
141                 maximum         => number, or undef
142                 width           => integer, suggested display size
143                 choices         => for enum, an arrayref
144                 choices_display => for enum, an arrayref
145               }
146
147           "type" is a string, one of
148
149               "integer"
150               "enum"
151               "boolean"
152               "string"
153               "filename"
154
155           "filename" is separate from "string" since it might require subtly
156           different handling to ensure it reaches Perl as a byte string,
157           whereas a "string" type might in principle take Perl wide chars.
158
159           For "enum" the "choices" field is an arrayref of possible values,
160           such as
161
162               { name    => "flavour",
163                 type    => "enum",
164                 choices => ["strawberry","chocolate"],
165               }
166
167           "choices_display", if provided, is human-readable strings for those
168           choices, possibly translated into another language (though there's
169           no translations yet).
170
171           "minimum" and "maximum" are omitted (or "undef") if there's no hard
172           limit on the parameter.
173
174           "share_key" is designed to indicate when parameters from different
175           NumSeq classes can be a single control widget in a GUI etc.
176           Normally the "name" is enough, but when the same name has slightly
177           different meanings in different classes a "share_key" keeps
178           different meanings separate.
179
180   Optional Methods
181       The following methods are only implemented for some sequences since
182       it's sometimes difficult to generate an arbitrary numbered element etc.
183       Check "$seq->can('ith')" etc before using.
184
185       "$seq->seek_to_i($i)"
186       "$seq->seek_to_value($value)"
187           Move the current i so next() will return $i or $value on the next
188           call.  If $value is not in the sequence then move so as to return
189           the next higher value which is.
190
191           Usually seek_to_value() only makes sense for sequences where all
192           values are distinct, so that a value is an unambiguous location.
193
194       "$value = $seq->ith($i)"
195           Return the $i'th value in the sequence.  Only some sequence classes
196           implement this method.
197
198       "($v0, $v1) = $seq->ith_pair($i)"
199           Return two values ith($i) and ith($i+1) from the sequence.  This
200           method can be used whenever ith() exists.  "$seq->can('ith_pair')"
201           says whether ith_pair() can be used (and gives a coderef).
202
203           For some sequences a pair of values can be calculated with less
204           work than two separate ith() calls.
205
206       "$bool = $seq->pred($value)"
207           Return true if $value occurs in the sequence.  For example, for the
208           squares this returns true if $value is a square or false if not.
209
210       "$i = $seq->value_to_i($value)"
211       "$i = $seq->value_to_i_ceil($value)"
212       "$i = $seq->value_to_i_floor($value)"
213           Return the index i of $value.  If $value is not in the sequence
214           then value_to_i() returns "undef", or value_to_i_ceil() returns the
215           i of the next higher value which is, value_to_i_floor() the i of
216           the next lower value.
217
218           These methods usually only make sense for monotonic increasing
219           sequences, or perhaps non-decreasing so with some repeating values.
220
221       "$i = $seq->value_to_i_estimate($value)"
222           Return an estimate of the i corresponding to $value.
223
224           The accuracy of this estimate is unspecified, but can at least hint
225           at the growth rate of the sequence.  For example if making an
226           "intersection" checking for given values in the sequence then if
227           the estimated i is small it may be fastest to go through the
228           sequence by next() and compare, rather than apply pred() to each
229           target.
230

SEE ALSO

232       Math::NumSeq::Squares, Math::NumSeq::Cubes, Math::NumSeq::Pronic,
233       Math::NumSeq::Triangular, Math::NumSeq::Polygonal,
234       Math::NumSeq::Tetrahedral, Math::NumSeq::StarNumbers,
235       Math::NumSeq::Powerful, Math::NumSeq::PowerPart,
236       Math::NumSeq::PowerFlip
237
238       Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All,
239       Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers,
240       Math::NumSeq::Runs
241
242       Math::NumSeq::Primes, Math::NumSeq::TwinPrimes,
243       Math::NumSeq::SophieGermainPrimes, Math::NumSeq::AlmostPrimes,
244       Math::NumSeq::DeletablePrimes, Math::NumSeq::Emirps,
245       Math::NumSeq::MobiusFunction, Math::NumSeq::LiouvilleFunction,
246       Math::NumSeq::DivisorCount, Math::NumSeq::GoldbachCount,
247       Math::NumSeq::LemoineCount, Math::NumSeq::PythagoreanHypots
248
249       Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
250
251       Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder,
252       Math::NumSeq::PrimeIndexPrimes
253
254       Math::NumSeq::Totient, Math::NumSeq::TotientCumulative,
255       Math::NumSeq::TotientSteps, Math::NumSeq::TotientStepsSum,
256       Math::NumSeq::TotientPerfect, Math::NumSeq::DedekindPsiCumulative,
257       Math::NumSeq::DedekindPsiSteps, Math::NumSeq::Abundant,
258       Math::NumSeq::PolignacObstinate
259
260       Math::NumSeq::Factorials, Math::NumSeq::Primorials,
261       Math::NumSeq::Fibonacci, Math::NumSeq::LucasNumbers,
262       Math::NumSeq::FibonacciWord, Math::NumSeq::FibonacciRepresentations,
263       Math::NumSeq::PisanoPeriod, Math::NumSeq::PisanoPeriodSteps,
264       Math::NumSeq::Fibbinary, Math::NumSeq::FibbinaryBitCount
265
266       Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary,
267       Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin,
268       Math::NumSeq::SpiroFibonacci
269
270       Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits,
271       Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued,
272       Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
273
274       Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow,
275       Math::NumSeq::DigitCountHigh
276
277       Math::NumSeq::DigitLength, Math::NumSeq::DigitLengthCumulative,
278       Math::NumSeq::SelfLengthCumulative, Math::NumSeq::DigitProduct,
279       Math::NumSeq::DigitProductSteps, Math::NumSeq::DigitSum,
280       Math::NumSeq::DigitSumModulo, Math::NumSeq::RadixWithoutDigit,
281       Math::NumSeq::RadixConversion, Math::NumSeq::MaxDigitCount
282
283       Math::NumSeq::Palindromes, Math::NumSeq::Xenodromes,
284       Math::NumSeq::Beastly, Math::NumSeq::Repdigits,
285       Math::NumSeq::RepdigitAny, Math::NumSeq::RepdigitRadix,
286       Math::NumSeq::UndulatingNumbers, Math::NumSeq::HarshadNumbers,
287       Math::NumSeq::MoranNumbers, Math::NumSeq::HappyNumbers,
288       Math::NumSeq::HappySteps
289
290       Math::NumSeq::CullenNumbers, Math::NumSeq::ProthNumbers,
291       Math::NumSeq::WoodallNumbers, Math::NumSeq::BaumSweet,
292       Math::NumSeq::GolayRudinShapiro,
293       Math::NumSeq::GolayRudinShapiroCumulative, Math::NumSeq::MephistoWaltz,
294       Math::NumSeq::HafermanCarpet, Math::NumSeq::KlarnerRado,
295       Math::NumSeq::UlamSequence, Math::NumSeq::ReRound,
296       Math::NumSeq::ReReplace, Math::NumSeq::LuckyNumbers
297
298       Math::NumSeq::CollatzSteps, Math::NumSeq::ReverseAdd,
299       Math::NumSeq::ReverseAddSteps, Math::NumSeq::JugglerSteps,
300       Math::NumSeq::SternDiatomic, Math::NumSeq::NumAronson,
301       Math::NumSeq::HofstadterFigure, Math::NumSeq::DuffinianNumbers
302
303       Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence,
304       Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
305
306       Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
307
308       Math::NumSeq::AlphabeticalLength,
309       Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in
310       the Math-NumSeq-Alpha dist)
311
312       Math::NumSeq::Aronson (in the Math-Aronson dist)
313
314       Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta,
315       Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the Math-
316       PlanePath dist)
317
318   Other Modules Etc
319       Math::Sequence and Math::Series, for symbolic recursive sequence
320       definitions
321
322       math-image, for displaying images with the NumSeq sequences
323

HOME PAGE

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

LICENSE

328       Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2019, 2020 Kevin Ryde
329
330       Math-NumSeq is free software; you can redistribute it and/or modify it
331       under the terms of the GNU General Public License as published by the
332       Free Software Foundation; either version 3, or (at your option) any
333       later version.
334
335       Math-NumSeq is distributed in the hope that it will be useful, but
336       WITHOUT ANY WARRANTY; without even the implied warranty of
337       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
338       General Public License for more details.
339
340       You should have received a copy of the GNU General Public License along
341       with Math-NumSeq.  If not, see <http://www.gnu.org/licenses/>.
342
343
344
345perl v5.36.0                      2023-01-20                   Math::NumSeq(3)
Impressum