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.20
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

BUGS

354       As of version 1.0, Math::GMP is mostly compatible with the old
355       Math::BigInt version. It is not a full replacement for the rewritten
356       Math::BigInt versions, though. See the SEE ALSO section on how to
357       achieve to use Math::GMP and retain full compatibility to Math::BigInt.
358
359       There are some slight incompatibilities, such as output of positive
360       numbers not being prefixed by a '+' sign.  This is intentional.
361
362       There are also some things missing, and not everything might work as
363       expected.
364

VERSION CONTROL

366       The version control repository of this module is a git repository
367       hosted on GitHub at: <https://github.com/turnstep/Math-GMP>. Pull
368       requests are welcome.
369

AUTHOR

384       Chip Turner <chip@redhat.com>, based on the old Math::BigInt by Mark
385       Biggar and Ilya Zakharevich.  Further extensive work provided by Tels
386       <tels@bloodgate.com>.
387

AUTHOR

389       Shlomi Fish <shlomif@cpan.org>
390

COPYRIGHT AND LICENSE

392       This software is Copyright (c) 2000 by James H. Turner.
393
394       This is free software, licensed under:
395
396         The GNU Lesser General Public License, Version 2.1, February 1999
397

BUGS

399       Please report any bugs or feature requests on the bugtracker website
400       <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP> or by
401       email to bug-math-gmp@rt.cpan.org <mailto:bug-math-gmp@rt.cpan.org>.
402
403       When submitting a bug or request, please include a test-file or a patch
404       to an existing test-file that illustrates the bug or desired feature.
405

SUPPORT

407   Perldoc
408       You can find documentation for this module with the perldoc command.
409
410         perldoc Math::GMP
411
412   Websites
413       The following websites have more information about this module, and may
414       be of help to you. As always, in addition to those websites please use
415       your favorite search engine to discover more resources.
416
417       ·   MetaCPAN
418
419           A modern, open-source CPAN search engine, useful to view POD in
420           HTML format.
421
422           <https://metacpan.org/release/Math-GMP>
423
424       ·   RT: CPAN's Bug Tracker
425
426           The RT ( Request Tracker ) website is the default bug/issue
427           tracking system for CPAN.
428
429           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP>
430
431       ·   CPANTS
432
433           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
434           of a distribution.
435
436           <http://cpants.cpanauthors.org/dist/Math-GMP>
437
438       ·   CPAN Testers
439
440           The CPAN Testers is a network of smoke testers who run automated
441           tests on uploaded CPAN distributions.
442
443           <http://www.cpantesters.org/distro/M/Math-GMP>
444
445       ·   CPAN Testers Matrix
446
447           The CPAN Testers Matrix is a website that provides a visual
448           overview of the test results for a distribution on various
449           Perls/platforms.
450
451           <http://matrix.cpantesters.org/?dist=Math-GMP>
452
453       ·   CPAN Testers Dependencies
454
455           The CPAN Testers Dependencies is a website that shows a chart of
456           the test results of all dependencies for a distribution.
457
458           <http://deps.cpantesters.org/?module=Math::GMP>
459
460   Bugs / Feature Requests
461       Please report any bugs or feature requests by email to "bug-math-gmp at
462       rt.cpan.org", or through the web interface at
463       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Math-GMP>. You will
464       be automatically notified of any progress on the request by the system.
465
466   Source Code
467       The code is open to the world, and available for you to hack on. Please
468       feel free to browse it and play with it, or whatever. If you want to
469       contribute patches, please send me a diff or prod me to pull from your
470       repository :)
471
472       <https://github.com/turnstep/Math-GMP>
473
474         git clone https://github.com/turnstep/Math-GMP.git
475
476
477
478perl v5.32.0                      2020-07-28                      Math::GMP(3)