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
38 some rapidly growing sequence. Infinities and NaNs give some kind of
39 NaN or 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
66 "next()" 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.
200 This method can be used whenever "ith()" exists.
201 "$seq->can('ith_pair')" says whether "ith_pair()" can be used (and
202 gives a coderef).
203 For some sequences a pair of values can be calculated with less
205 work than two separate "ith()" calls.
206 "$bool = $seq->pred($value)"
208 Return true if $value occurs in the sequence. For example, for the
209 squares this returns true if $value is a square or false if not.
210 "$i = $seq->value_to_i($value)"
212 "$i = $seq->value_to_i_ceil($value)"
213 "$i = $seq->value_to_i_floor($value)"
214 Return the index i of $value. If $value is not in the sequence
215 then "value_to_i()" returns "undef", or "value_to_i_ceil()" returns
216 the i of the next higher value which is, "value_to_i_floor()" the i
217 of the next lower value.
218 These methods usually only make sense for monotonic increasing
220 sequences, or perhaps non-decreasing so with some repeating values.
221 "$i = $seq->value_to_i_estimate($value)"
223 Return an estimate of the i corresponding to $value.
224 The accuracy of this estimate is unspecified, but can at least hint
226 at the growth rate of the sequence. For example if making an
227 "intersection" checking for given values in the sequence then if
228 the estimated i is small it may be fastest to go through the
229 sequence by "next()" and compare, rather than apply "pred()" to
230 each target.
231
233 Math::NumSeq::Squares, Math::NumSeq::Cubes, Math::NumSeq::Pronic,
234 Math::NumSeq::Triangular, Math::NumSeq::Polygonal,
235 Math::NumSeq::Tetrahedral, Math::NumSeq::StarNumbers,
236 Math::NumSeq::Powerful, Math::NumSeq::PowerPart,
237 Math::NumSeq::PowerFlip
238 Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All,
240 Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers,
241 Math::NumSeq::Runs
242 Math::NumSeq::Primes, Math::NumSeq::TwinPrimes,
244 Math::NumSeq::SophieGermainPrimes, Math::NumSeq::AlmostPrimes,
245 Math::NumSeq::DeletablePrimes, Math::NumSeq::Emirps,
246 Math::NumSeq::MobiusFunction, Math::NumSeq::LiouvilleFunction,
247 Math::NumSeq::DivisorCount, Math::NumSeq::GoldbachCount,
248 Math::NumSeq::LemoineCount, Math::NumSeq::PythagoreanHypots
249 Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
251 Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder,
253 Math::NumSeq::PrimeIndexPrimes
254 Math::NumSeq::Totient, Math::NumSeq::TotientCumulative,
256 Math::NumSeq::TotientSteps, Math::NumSeq::TotientStepsSum,
257 Math::NumSeq::TotientPerfect, Math::NumSeq::DedekindPsiCumulative,
258 Math::NumSeq::DedekindPsiSteps, Math::NumSeq::Abundant,
259 Math::NumSeq::PolignacObstinate
260 Math::NumSeq::Factorials, Math::NumSeq::Primorials,
262 Math::NumSeq::Fibonacci, Math::NumSeq::LucasNumbers,
263 Math::NumSeq::FibonacciWord, Math::NumSeq::FibonacciRepresentations,
264 Math::NumSeq::PisanoPeriod, Math::NumSeq::PisanoPeriodSteps,
265 Math::NumSeq::Fibbinary, Math::NumSeq::FibbinaryBitCount
266 Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary,
268 Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin,
269 Math::NumSeq::SpiroFibonacci
270 Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits,
272 Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued,
273 Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
274 Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow,
276 Math::NumSeq::DigitCountHigh
277 Math::NumSeq::DigitLength, Math::NumSeq::DigitLengthCumulative,
279 Math::NumSeq::SelfLengthCumulative, Math::NumSeq::DigitProduct,
280 Math::NumSeq::DigitProductSteps, Math::NumSeq::DigitSum,
281 Math::NumSeq::DigitSumModulo, Math::NumSeq::RadixWithoutDigit,
282 Math::NumSeq::RadixConversion, Math::NumSeq::MaxDigitCount
283 Math::NumSeq::Palindromes, Math::NumSeq::Xenodromes,
285 Math::NumSeq::Beastly, Math::NumSeq::Repdigits,
286 Math::NumSeq::RepdigitAny, Math::NumSeq::RepdigitRadix,
287 Math::NumSeq::UndulatingNumbers, Math::NumSeq::HarshadNumbers,
288 Math::NumSeq::MoranNumbers, Math::NumSeq::HappyNumbers,
289 Math::NumSeq::HappySteps
290 Math::NumSeq::CullenNumbers, Math::NumSeq::ProthNumbers,
292 Math::NumSeq::WoodallNumbers, Math::NumSeq::BaumSweet,
293 Math::NumSeq::GolayRudinShapiro,
294 Math::NumSeq::GolayRudinShapiroCumulative, Math::NumSeq::MephistoWaltz,
295 Math::NumSeq::HafermanCarpet, Math::NumSeq::KlarnerRado,
296 Math::NumSeq::UlamSequence, Math::NumSeq::ReRound,
297 Math::NumSeq::ReReplace, Math::NumSeq::LuckyNumbers
298 Math::NumSeq::CollatzSteps, Math::NumSeq::ReverseAdd,
300 Math::NumSeq::ReverseAddSteps, Math::NumSeq::JugglerSteps,
301 Math::NumSeq::SternDiatomic, Math::NumSeq::NumAronson,
302 Math::NumSeq::HofstadterFigure, Math::NumSeq::DuffinianNumbers
303 Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence,
305 Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
306 Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
308 Math::NumSeq::AlphabeticalLength,
310 Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in
311 the Math-NumSeq-Alpha dist)
312 Math::NumSeq::Aronson (in the Math-Aronson dist)
314 Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta,
316 Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the Math-
317 PlanePath dist)
318 Other Modules Etc
320 Math::Sequence and Math::Series, for symbolic recursive sequence
321 definitions
322 math-image, for displaying images with the NumSeq sequences
324
326 http://user42.tuxfamily.org/math-numseq/index.html
327
329 Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2019 Kevin Ryde
330 Math-NumSeq is free software; you can redistribute it and/or modify it
332 under the terms of the GNU General Public License as published by the
333 Free Software Foundation; either version 3, or (at your option) any
334 later version.
335 Math-NumSeq is distributed in the hope that it will be useful, but
337 WITHOUT ANY WARRANTY; without even the implied warranty of
338 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
339 General Public License for more details.
340 You should have received a copy of the GNU General Public License along
342 with Math-NumSeq. If not, see <http://www.gnu.org/licenses/>.
343perl v5.32.0 2020-07-28 Math::NumSeq(3)