1Math::NumSeq(3) User Contributed Perl Documentation Math::NumSeq(3)
2
6 Math::NumSeq -- number sequences
7
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
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 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 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 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 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 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
47 In the following "Foo" is one of the subclass names.
48 "$seq = Math::NumSeq::Foo->new (key=>value,...)"
50 Create and return a new sequence object.
51 Iterating
53 "($i, $value) = $seq->next()"
54 Return the next index and value in the sequence.
55 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 while (my ($i, $value) = $seq->next) {
61 print "$i $value\n";
62 }
63 "$seq->rewind()"
65 Rewind the sequence to its starting point. The next call to next()
66 will be the initial "$i,$value" again.
67 See "Optional Methods" below for possible arbitrary "seeks".
69 "$i = $seq->tell_i()"
71 Return the current i position. This is the i which the next call
72 to next() will return.
73 Information
75 "$i = $seq->i_start()"
76 Return the first index $i in the sequence. This is the position
77 rewind() returns to.
78 "$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 "$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 "$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 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 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 value_is_radix boolean, value is radix for i
105 "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 "$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 my $seq = Math::NumSeq::Squares->new;
117 my $anum = $seq->oeis_anum;
118 # gives $anum = "A000290"
119 The web page for that is then
121 <http://oeis.org/A000290>
123 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 "$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 {
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 "type" is a string, one of
148 "integer"
150 "enum"
151 "boolean"
152 "string"
153 "filename"
154 "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 For "enum" the "choices" field is an arrayref of possible values,
160 such as
161 { name => "flavour",
163 type => "enum",
164 choices => ["strawberry","chocolate"],
165 }
166 "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 "minimum" and "maximum" are omitted (or "undef") if there's no hard
172 limit on the parameter.
173 "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 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 "$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 Usually seek_to_value() only makes sense for sequences where all
192 values are distinct, so that a value is an unambiguous location.
193 "$value = $seq->ith($i)"
195 Return the $i'th value in the sequence. Only some sequence classes
196 implement this method.
197 "($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 For some sequences a pair of values can be calculated with less
204 work than two separate ith() calls.
205 "$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 "$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 These methods usually only make sense for monotonic increasing
219 sequences, or perhaps non-decreasing so with some repeating values.
220 "$i = $seq->value_to_i_estimate($value)"
222 Return an estimate of the i corresponding to $value.
223 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
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 Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All,
239 Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers,
240 Math::NumSeq::Runs
241 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 Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
250 Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder,
252 Math::NumSeq::PrimeIndexPrimes
253 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 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 Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary,
267 Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin,
268 Math::NumSeq::SpiroFibonacci
269 Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits,
271 Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued,
272 Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
273 Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow,
275 Math::NumSeq::DigitCountHigh
276 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 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 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 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 Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence,
304 Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
305 Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
307 Math::NumSeq::AlphabeticalLength,
309 Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in
310 the Math-NumSeq-Alpha dist)
311 Math::NumSeq::Aronson (in the Math-Aronson dist)
313 Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta,
315 Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the Math-
316 PlanePath dist)
317 Other Modules Etc
319 Math::Sequence and Math::Series, for symbolic recursive sequence
320 definitions
321 math-image, for displaying images with the NumSeq sequences
323
325 http://user42.tuxfamily.org/math-numseq/index.html
326
328 Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2019, 2020 Kevin Ryde
329 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 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 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/>.
342perl v5.38.0 2023-07-20 Math::NumSeq(3)