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

DIVISION BY ZERO

384       Whereas perl normally catches division by zero to provide a standard
385       perl-level error message, "libgmp" does not; the result is usually a
386       SIGFPE (floating point exception) giving a core dump if you ever
387       attempt to divide a "Math::GMP" object by anything that evaluates to
388       zero. This can make it hard to diagnose where the error has occurred in
389       your perl code.
390
391       As of perl-5.36.0, SIGFPE is delivered in a way that can be caught by a
392       %SIG handler. So you can get a stack trace with code like:
393
394         use Carp;  # load it up front
395         local $SIG{FPE} = sub { confess(@_) };
396
397       Before perl-5.36.0 this approach won't work: you'll need to use
398       "sigaction" in POSIX instead:
399
400         use Carp;
401         use POSIX qw{ sigaction SIGFPE };
402         sigaction(SIGFPE, POSIX::SigAction->new(sub { confess(@_) }));
403
404       In either case, you should not attempt to return from the signal
405       handler, since the signal will just be thrown again.
406

BUGS

408       As of version 1.0, Math::GMP is mostly compatible with the old
409       Math::BigInt version. It is not a full replacement for the rewritten
410       Math::BigInt versions, though. See the SEE ALSO section on how to
411       achieve to use Math::GMP and retain full compatibility to Math::BigInt.
412
413       There are some slight incompatibilities, such as output of positive
414       numbers not being prefixed by a '+' sign.  This is intentional.
415
416       There are also some things missing, and not everything might work as
417       expected.
418

VERSION CONTROL

420       The version control repository of this module is a git repository
421       hosted on GitHub at: <https://github.com/turnstep/Math-GMP>. Pull
422       requests are welcome.
423

AUTHOR

442       Chip Turner <chip@redhat.com>, based on the old Math::BigInt by Mark
443       Biggar and Ilya Zakharevich.  Further extensive work provided by Tels
444       <tels@bloodgate.com>.
445
446       Shlomi Fish ( <https://www.shlomifish.org/> ) has done some maintenance
447       work while putting his changes under CC0.
448

AUTHOR

450       Shlomi Fish <shlomif@cpan.org>
451

COPYRIGHT AND LICENSE

453       This software is Copyright (c) 2000 by James H. Turner.
454
455       This is free software, licensed under:
456
457         The GNU Lesser General Public License, Version 2.1, February 1999
458

BUGS

460       Please report any bugs or feature requests on the bugtracker website
461       <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP> or by
462       email to bug-math-gmp@rt.cpan.org <mailto:bug-math-gmp@rt.cpan.org>.
463
464       When submitting a bug or request, please include a test-file or a patch
465       to an existing test-file that illustrates the bug or desired feature.
466

SUPPORT

468   Perldoc
469       You can find documentation for this module with the perldoc command.
470
471         perldoc Math::GMP
472
473   Websites
474       The following websites have more information about this module, and may
475       be of help to you. As always, in addition to those websites please use
476       your favorite search engine to discover more resources.
477
478       •   MetaCPAN
479
480           A modern, open-source CPAN search engine, useful to view POD in
481           HTML format.
482
483           <https://metacpan.org/release/Math-GMP>
484
485       •   RT: CPAN's Bug Tracker
486
487           The RT ( Request Tracker ) website is the default bug/issue
488           tracking system for CPAN.
489
490           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP>
491
492       •   CPANTS
493
494           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
495           of a distribution.
496
497           <http://cpants.cpanauthors.org/dist/Math-GMP>
498
499       •   CPAN Testers
500
501           The CPAN Testers is a network of smoke testers who run automated
502           tests on uploaded CPAN distributions.
503
504           <http://www.cpantesters.org/distro/M/Math-GMP>
505
506       •   CPAN Testers Matrix
507
508           The CPAN Testers Matrix is a website that provides a visual
509           overview of the test results for a distribution on various
510           Perls/platforms.
511
512           <http://matrix.cpantesters.org/?dist=Math-GMP>
513
514       •   CPAN Testers Dependencies
515
516           The CPAN Testers Dependencies is a website that shows a chart of
517           the test results of all dependencies for a distribution.
518
519           <http://deps.cpantesters.org/?module=Math::GMP>
520
521   Bugs / Feature Requests
522       Please report any bugs or feature requests by email to "bug-math-gmp at
523       rt.cpan.org", or through the web interface at
524       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Math-GMP>. You will
525       be automatically notified of any progress on the request by the system.
526
527   Source Code
528       The code is open to the world, and available for you to hack on. Please
529       feel free to browse it and play with it, or whatever. If you want to
530       contribute patches, please send me a diff or prod me to pull from your
531       repository :)
532
533       <https://github.com/turnstep/Math-GMP>
534
535         git clone https://github.com/turnstep/Math-GMP.git
536
537
538
539perl v5.36.0                      2023-01-20                      Math::GMP(3)