Math::GMP(3pm)

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

NAME

6       Math::GMP - High speed arbitrary size integer math
7

VERSION

9       version 2.22
10

SYNOPSIS

12         use Math::GMP;
13         my $n = Math::GMP->new('2');
14
15         $n = $n ** (256*1024);
16         $n = $n - 1;
17         print "n is now $n\n";
18

DESCRIPTION

20       Math::GMP was designed to be a drop-in replacement both for
21       Math::BigInt and for regular integer arithmetic.  Unlike BigInt,
22       though, Math::GMP uses the GNU gmp library for all of its calculations,
23       as opposed to straight Perl functions.  This can result in speed
24       improvements.
25
26       The downside is that this module requires a C compiler to install -- a
27       small tradeoff in most cases. Also, this module is not 100% compatible
28       with Math::BigInt.
29
30       A Math::GMP object can be used just as a normal numeric scalar would be
31       -- the module overloads most of the normal arithmetic operators to
32       provide as seamless an interface as possible. However, if you need a
33       perfect interface, you can do the following:
34
35         use Math::GMP qw(:constant);
36
37         $n = 2 ** (256 * 1024);
38         print "n is $n\n";
39
40       This would fail without the ':constant' since Perl would use normal
41       doubles to compute the 250,000 bit number, and thereby overflow it into
42       meaninglessness (smaller exponents yield less accurate data due to
43       floating point rounding).
44

METHODS

46       Although the non-overload interface is not complete, the following
47       functions do exist:
48
49   new
50         $x = Math::GMP->new(123);
51
52       Creates a new Math::GMP object from the passed string or scalar.
53
54         $x = Math::GMP->new('abcd', 36);
55
56       Creates a new Math::GMP object from the first parameter which should be
57       represented in the base specified by the second parameter.
58
59   bfac
60         $x = Math::GMP->new(5);
61         my $val = $x->bfac();      # 1*2*3*4*5 = 120
62         print $val;
63
64       Calculates the factorial of $x and returns the result.
65
66   my $val = $x->band($y, $swap)
67         $x = Math::GMP->new(6);
68         my $val = $x->band(3, 0);      # 0b110 & 0b11 = 1
69         print $val;
70
71       Calculates the bit-wise AND of its two arguments and returns the
72       result.  $swap should be provided but is ignored.
73
74   my $ret = $x->bxor($y, $swap);
75         $x = Math::GMP->new(6);
76         my $val = $x->bxor(3, 0);      # 0b110 ^ 0b11 = 0b101
77         print $val;
78
79       Calculates the bit-wise XOR of its two arguments and returns the
80       result.
81
82   my $ret = $x->bior($y, $swap);
83         $x = Math::GMP->new(6);
84         my $val = $x->bior(3);      # 0b110 | 0b11 = 0b111
85         print $val;
86
87       Calculates the bit-wise OR of its two arguments and returns the result.
88
89   blshift
90         $x = Math::GMP->new(0b11);
91         my $result = $x->blshift(4, 0);
92         # $result = 0b11 << 4 = 0b110000
93
94       Calculates the bit-wise left-shift of its two arguments and returns the
95       result. Second argument is swap.
96
97   brshift
98         $x = Math::GMP->new(0b11001);
99         my $result = $x->brshift(3, 0);
100         # $result = 0b11001 << 3 = 0b11
101
102       Calculates the bit-wise right-shift of its two arguments and returns
103       the result. Second argument is swap.
104
105   bgcd
106         my $x = Math::GMP->new(6);
107         my $gcd = $x->bgcd(4);
108         # 6 / 2 = 3, 4 / 2 = 2 => 2
109         print $gcd
110
111       Returns the Greatest Common Divisor of the two arguments.
112
113   blcm
114         my $x = Math::GMP->new(6);
115         my $lcm = $x->blcm(4);      # 6 * 2 = 12, 4 * 3 = 12 => 12
116         print $lcm;
117
118       Returns the Least Common Multiple of the two arguments.
119
120   bmodinv
121         my $x = Math::GMP->new(5);
122         my $modinv = $x->bmodinv(7);   # 5 * 3 == 1 (mod 7) => 3
123         print $modinv;
124
125       Returns the modular inverse of $x (mod $y), if defined. This currently
126       returns 0 if there is no inverse (but that may change in the future).
127       Behaviour is undefined when $y is 0.
128
129   broot
130         my $x = Math::GMP->new(100);
131         my $root = $x->root(3);    # int(100 ** (1/3)) => 4
132         print $root;
133
134       Returns the integer n'th root of its argument, given a positive integer
135       n.
136
137   brootrem
138         my $x = Math::GMP->new(100);
139         my($root, $rem) = $x->rootrem(3); # 4 ** 3 + 36 = 100
140         print "$x is $rem more than the cube of $root";
141
142       Returns the integer n'th root of its argument, and the difference such
143       that " $root ** $n + $rem == $x ".
144
145   bsqrt
146         my $x = Math::GMP->new(6);
147         my $root = $x->bsqrt();      # int(sqrt(6)) => 2
148         print $root;
149
150       Returns the integer square root of its argument.
151
152   bsqrtrem
153         my $x = Math::GMP->new(7);
154         my($root, $rem) = $x->sqrtrem(); # 2 ** 2 + 3 = 7
155         print "$x is $rem more than the square of $root";
156
157       Returns the integer square root of its argument, and the difference
158       such that " $root ** 2 + $rem == $x ".
159
160   is_perfect_power
161         my $x = Math::GMP->new(100);
162         my $is_power = $x->is_perfect_power();
163         print "$x is " . ($is_power ? "" : "not ") . "a perfect power";
164
165       Returns "TRUE" if its argument is a power, ie if there exist integers a
166       and b with b > 1 such that " $x == $a ** $b ".
167
168   is_perfect_square
169         my $x = Math::GMP->new(100);
170         my $is_square = $x->is_perfect_square();
171         print "$x is " . ($is_square ? "" : "not ") . "a perfect square";
172
173       Returns "TRUE" if its argument is the square of an integer.
174
175   legendre
176         $x = Math::GMP->new(6);
177         my $ret = $x->legendre(3);
178
179       Returns the value of the Legendre symbol ($x/$y). The value is defined
180       only when $y is an odd prime; when the value is not defined, this
181       currently returns 0 (but that may change in the future).
182
183   jacobi
184         my $x = Math::GMP->new(6);
185         my $jacobi_verdict = $x->jacobi(3);
186
187       Returns the value of the Jacobi symbol ($x/$y). The value is defined
188       only when $y is odd; when the value is not defined, this currently
189       returns 0 (but that may change in the future).
190
191   fibonacci
192         my $fib = Math::GMP::fibonacci(16);
193
194       Calculates the n'th number in the Fibonacci sequence.
195
196   probab_prime
197         my $x = Math::GMP->new(7);
198         my $is_prime_verdict = $x->probab_prime(10);
199
200       Probabilistically determines if the number is a prime. Argument is the
201       number of checks to perform. Returns 0 if the number is definitely not
202       a prime, 1 if it may be, and 2 if it definitely is a prime.
203
204   $x->add_ui_gmp($n)
205       Adds to $x and mutates it in-place. $n must be a regular non-GMP,
206       positive, integer.
207
208   ($quotient, $remainder) = $x->bdiv($y);
209         my $x = Math::GMP->new(7);
210         my ($quo, $rem) = $x->bdiv(3);
211
212       Returns both the division and the modulo of an integer division
213       operation.
214
215   my $ret = $x->div_2exp_gmp($n);
216         my $x = Math::GMP->new(200);
217         my $ret = $x->div_2exp_gmp(2);
218
219       Returns a right-shift of the Math::GMP object by an unsigned regular
220       integer.  Also look at blshift() .
221
222   my $str = $x->get_str_gmp($base)
223         my $init_n = 3 * 7 + 2 * 7 * 7 + 6 * 7 * 7 * 7;
224         my $x = Math::GMP->new($init_n);
225         my $ret = $x->get_str_gmp(7);
226
227         print $ret; # Prints "6230".
228
229       Returns a string representation of the number in base $base.
230
231   my $clone = $x->gmp_copy()
232       Returns a copy of $x that can be modified without affecting the
233       original.
234
235   my $verdict = $x->gmp_tstbit($bit_index);
236       Returns whether or not bit No. $bit_index is 1 in $x.
237
238   my $remainder = $dividend->mmod_gmp($divisor)
239         my $x = Math::GMP->new(2 . ('0' x 200) . 4);
240         my $y = Math::GMP->new(5);
241
242         my $ret = $x->mmod_gmp($y);
243         # $ret is now Math::GMP of 4.
244
245       From the GMP documentation:
246
247       Divide dividend and divisor and put the remainder in remainder. The
248       remainder is always positive, and its value is less than the value of
249       the divisor.
250
251   my $result = $x->mod_2exp_gmp($shift);
252         my $x = Math::GMP->new(0b10001011);
253         my $ret = $x->mod_2exp_gmp(4);
254
255         # $ret is now Math::GMP of 0b1011
256
257       Returns a Math::GMP object containing the lower $shift bits of $x
258       (while not modifying $x).
259
260   my $left_shifted = $x->mul_2exp_gmp($shift);
261         my $x = Math::GMP->new(0b10001011);
262         my $ret = $x->mul_2exp_gmp(4);
263
264         # $ret is now Math::GMP of 0b1000_1011_0000
265
266       Returns a Math::GMP object containing $x shifted by $shift bits (where
267       $shift is a plain integer).
268
269   my $ret = $base->powm_gmp($exp, $mod);
270           my $base = Math::GMP->new(157);
271           my $exp = Math::GMP->new(100);
272           my $mod = Math::GMP->new(5013);
273
274           my $ret = $base->powm_gmp($exp, $mod);
275
276           # $ret is now (($base ** $exp) % $mod)
277
278       Returns $base raised to the power of $exp modulo $mod.
279
280   my $plain_int_ret = $x->sizeinbase_gmp($plain_int_base);
281       Returns the size of $x in base $plain_int_base .
282
283   my $int = $x->intify();
284       Returns the value of the object as an unblessed (and limited-in-
285       precision) integer.
286
287   _gmp_build_version()
288         my $gmp_version = Math::GMP::_gmp_build_version;
289         if ($gmp_version ge 6.0.0) {
290           print "Math::GMP was built against libgmp-6.0.0 or later";
291         }
292
293       Class method that returns as a vstring the version of libgmp against
294       which this module was built.
295
296   _gmp_lib_version()
297         my $gmp_version = Math::GMP::_gmp_lib_version;
298         if ($gmp_version ge 6.0.0) {
299           print "Math::GMP is now running with libgmp-6.0.0 or later";
300         }
301
302       Class method that returns as a vstring the version of libgmp it is
303       currently running.
304
305   gcd()
306       An alias to bgcd() .
307
308   lcm()
309       An alias to blcm() .
310
311   constant
312       For internal use. Do not use directly.
313
314   destroy
315       For internal use. Do not use directly.
316
317   new_from_scalar
318       For internal use. Do not use directly.
319
320   new_from_scalar_with_base
321       For internal use. Do not use directly.
322
323   op_add
324       For internal use. Do not use directly.
325
326   op_div
327       For internal use. Do not use directly.
328
329   op_eq
330       For internal use. Do not use directly.
331
332   op_mod
333       For internal use. Do not use directly.
334
335   op_mul
336       For internal use. Do not use directly.
337
338   op_pow
339       For internal use. Do not use directly.
340
341   op_spaceship
342       For internal use. Do not use directly.
343
344   op_sub
345       For internal use. Do not use directly.
346
347   stringify
348       For internal use. Do not use directly.
349
350   uintify
351       For internal use. Do not use directly.
352

DIVISION BY ZERO

354       Whereas perl normally catches division by zero to provide a standard
355       perl-level error message, "libgmp" does not; the result is usually a
356       SIGFPE (floating point exception) giving a core dump if you ever
357       attempt to divide a "Math::GMP" object by anything that evaluates to
358       zero. This can make it hard to diagnose where the error has occurred in
359       your perl code.
360
361       As of perl-5.36.0, SIGFPE is delivered in a way that can be caught by a
362       %SIG handler. So you can get a stack trace with code like:
363
364         use Carp;  # load it up front
365         local $SIG{FPE} = sub { confess(@_) };
366
367       Before perl-5.36.0 this approach won't work: you'll need to use
368       "sigaction" in POSIX instead:
369
370         use Carp;
371         use POSIX qw{ sigaction SIGFPE };
372         sigaction(SIGFPE, POSIX::SigAction->new(sub { confess(@_) }));
373
374       In either case, you should not attempt to return from the signal
375       handler, since the signal will just be thrown again.
376

BUGS

378       As of version 1.0, Math::GMP is mostly compatible with the old
379       Math::BigInt version. It is not a full replacement for the rewritten
380       Math::BigInt versions, though. See the SEE ALSO section on how to
381       achieve to use Math::GMP and retain full compatibility to Math::BigInt.
382
383       There are some slight incompatibilities, such as output of positive
384       numbers not being prefixed by a '+' sign.  This is intentional.
385
386       There are also some things missing, and not everything might work as
387       expected.
388

VERSION CONTROL

390       The version control repository of this module is a git repository
391       hosted on GitHub at: <https://github.com/turnstep/Math-GMP>. Pull
392       requests are welcome.
393

AUTHOR

412       Chip Turner <chip@redhat.com>, based on the old Math::BigInt by Mark
413       Biggar and Ilya Zakharevich.  Further extensive work provided by Tels
414       <tels@bloodgate.com>.
415
416       Shlomi Fish ( <https://www.shlomifish.org/> ) has done some maintenance
417       work while putting his changes under CC0.
418

AUTHOR

420       Shlomi Fish <shlomif@cpan.org>
421

COPYRIGHT AND LICENSE

423       This software is Copyright (c) 2000 by James H. Turner.
424
425       This is free software, licensed under:
426
427         The GNU Lesser General Public License, Version 2.1, February 1999
428

BUGS

430       Please report any bugs or feature requests on the bugtracker website
431       <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP> or by
432       email to bug-math-gmp@rt.cpan.org <mailto:bug-math-gmp@rt.cpan.org>.
433
434       When submitting a bug or request, please include a test-file or a patch
435       to an existing test-file that illustrates the bug or desired feature.
436

SUPPORT

438   Perldoc
439       You can find documentation for this module with the perldoc command.
440
441         perldoc Math::GMP
442
443   Websites
444       The following websites have more information about this module, and may
445       be of help to you. As always, in addition to those websites please use
446       your favorite search engine to discover more resources.
447
448       •   MetaCPAN
449
450           A modern, open-source CPAN search engine, useful to view POD in
451           HTML format.
452
453           <https://metacpan.org/release/Math-GMP>
454
455       •   RT: CPAN's Bug Tracker
456
457           The RT ( Request Tracker ) website is the default bug/issue
458           tracking system for CPAN.
459
460           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP>
461
462       •   CPANTS
463
464           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
465           of a distribution.
466
467           <http://cpants.cpanauthors.org/dist/Math-GMP>
468
469       •   CPAN Testers
470
471           The CPAN Testers is a network of smoke testers who run automated
472           tests on uploaded CPAN distributions.
473
474           <http://www.cpantesters.org/distro/M/Math-GMP>
475
476       •   CPAN Testers Matrix
477
478           The CPAN Testers Matrix is a website that provides a visual
479           overview of the test results for a distribution on various
480           Perls/platforms.
481
482           <http://matrix.cpantesters.org/?dist=Math-GMP>
483
484       •   CPAN Testers Dependencies
485
486           The CPAN Testers Dependencies is a website that shows a chart of
487           the test results of all dependencies for a distribution.
488
489           <http://deps.cpantesters.org/?module=Math::GMP>
490
491   Bugs / Feature Requests
492       Please report any bugs or feature requests by email to "bug-math-gmp at
493       rt.cpan.org", or through the web interface at
494       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Math-GMP>. You will
495       be automatically notified of any progress on the request by the system.
496
497   Source Code
498       The code is open to the world, and available for you to hack on. Please
499       feel free to browse it and play with it, or whatever. If you want to
500       contribute patches, please send me a diff or prod me to pull from your
501       repository :)
502
503       <https://github.com/turnstep/Math-GMP>
504
505         git clone https://github.com/turnstep/Math-GMP.git
506
507
508
509perl v5.34.0                      2021-09-21                      Math::GMP(3)