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
38       some rapidly growing sequence.  Infinities and NaNs give some kind of
39       NaN or 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
66           "next()" 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.
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
204           For some sequences a pair of values can be calculated with less
205           work than two separate "ith()" calls.
206
207       "$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
211       "$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
219           These methods usually only make sense for monotonic increasing
220           sequences, or perhaps non-decreasing so with some repeating values.
221
222       "$i = $seq->value_to_i_estimate($value)"
223           Return an estimate of the i corresponding to $value.
224
225           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

SEE ALSO

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
239       Math::NumSeq::Even, Math::NumSeq::Odd, Math::NumSeq::All,
240       Math::NumSeq::AllDigits, Math::NumSeq::ConcatNumbers,
241       Math::NumSeq::Runs
242
243       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
250       Math::NumSeq::PrimeFactorCount, Math::NumSeq::AllPrimeFactors
251
252       Math::NumSeq::ErdosSelfridgeClass, Math::NumSeq::PrimeIndexOrder,
253       Math::NumSeq::PrimeIndexPrimes
254
255       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
261       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
267       Math::NumSeq::Catalan, Math::NumSeq::BalancedBinary,
268       Math::NumSeq::Pell, Math::NumSeq::Tribonacci, Math::NumSeq::Perrin,
269       Math::NumSeq::SpiroFibonacci
270
271       Math::NumSeq::FractionDigits, Math::NumSeq::SqrtDigits,
272       Math::NumSeq::SqrtEngel, Math::NumSeq::SqrtContinued,
273       Math::NumSeq::SqrtContinuedPeriod, Math::NumSeq::AlgebraicContinued
274
275       Math::NumSeq::DigitCount, Math::NumSeq::DigitCountLow,
276       Math::NumSeq::DigitCountHigh
277
278       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
284       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
291       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
299       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
304       Math::NumSeq::Kolakoski, Math::NumSeq::GolombSequence,
305       Math::NumSeq::AsciiSelf, Math::NumSeq::Multiples, Math::NumSeq::Modulo
306
307       Math::NumSeq::Expression, Math::NumSeq::File, Math::NumSeq::OEIS
308
309       Math::NumSeq::AlphabeticalLength,
310       Math::NumSeq::AlphabeticalLengthSteps, Math::NumSeq::SevenSegments (in
311       the Math-NumSeq-Alpha dist)
312
313       Math::NumSeq::Aronson (in the Math-Aronson dist)
314
315       Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta,
316       Math::NumSeq::PlanePathTurn, Math::NumSeq::PlanePathN (in the Math-
317       PlanePath dist)
318
319   Other Modules Etc
320       Math::Sequence and Math::Series, for symbolic recursive sequence
321       definitions
322
323       math-image, for displaying images with the NumSeq sequences
324

HOME PAGE

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

LICENSE

329       Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2019 Kevin Ryde
330
331       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
336       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
341       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/>.
343
344
345
346perl v5.30.1                      2020-01-30                   Math::NumSeq(3)
Impressum