Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Math::GMP(3)	      User Contributed Perl Documentation	  Math::GMP(3)

NAME
       Math::GMP - High	speed arbitrary	size integer math

VERSION
       version 2.20

SYNOPSIS
	 use Math::GMP;
	 my $n = Math::GMP->new('2');

	 $n = $n ** (256*1024);
	 $n = $n - 1;
	 print "n is now $n\n";

DESCRIPTION
       Math::GMP was designed to be a drop-in replacement both for
       Math::BigInt and	for regular integer arithmetic.	 Unlike	BigInt,
       though, Math::GMP uses the GNU gmp library for all of its calculations,
       as opposed to straight Perl functions.  This can	result in speed
       improvements.

       The downside is that this module	requires a C compiler to install -- a
       small tradeoff in most cases. Also, this	module is not 100% compatible
       with Math::BigInt.

       A Math::GMP object can be used just as a	normal numeric scalar would be
       -- the module overloads most of the normal arithmetic operators to
       provide as seamless an interface	as possible. However, if you need a
       perfect interface, you can do the following:

	 use Math::GMP qw(:constant);

	 $n = 2	** (256	* 1024);
	 print "n is $n\n";

       This would fail without the ':constant' since Perl would	use normal
       doubles to compute the 250,000 bit number, and thereby overflow it into
       meaninglessness (smaller	exponents yield	less accurate data due to
       floating	point rounding).

METHODS
       Although	the non-overload interface is not complete, the	following
       functions do exist:

   new
	 $x = Math::GMP->new(123);

       Creates a new Math::GMP object from the passed string or	scalar.

	 $x = Math::GMP->new('abcd', 36);

       Creates a new Math::GMP object from the first parameter which should be
       represented in the base specified by the	second parameter.

   bfac
	 $x = Math::GMP->new(5);
	 my $val = $x->bfac();	    # 1*2*3*4*5	= 120
	 print $val;

       Calculates the factorial	of $x and returns the result.

   my $val = $x->band($y, $swap)
	 $x = Math::GMP->new(6);
	 my $val = $x->band(3, 0);	# 0b110	& 0b11 = 1
	 print $val;

       Calculates the bit-wise AND of its two arguments	and returns the
       result.	$swap should be	provided but is	ignored.

   my $ret = $x->bxor($y, $swap);
	 $x = Math::GMP->new(6);
	 my $val = $x->bxor(3, 0);	# 0b110	^ 0b11 = 0b101
	 print $val;

       Calculates the bit-wise XOR of its two arguments	and returns the
       result.

   my $ret = $x->bior($y, $swap);
	 $x = Math::GMP->new(6);
	 my $val = $x->bior(3);	     # 0b110 | 0b11 = 0b111
	 print $val;

       Calculates the bit-wise OR of its two arguments and returns the result.

   blshift
	 $x = Math::GMP->new(0b11);
	 my $result = $x->blshift(4, 0);
	 # $result = 0b11 << 4 = 0b110000

       Calculates the bit-wise left-shift of its two arguments and returns the
       result. Second argument is swap.

   brshift
	 $x = Math::GMP->new(0b11001);
	 my $result = $x->brshift(3, 0);
	 # $result = 0b11001 <<	3 = 0b11

       Calculates the bit-wise right-shift of its two arguments	and returns
       the result. Second argument is swap.

   bgcd
	 my $x = Math::GMP->new(6);
	 my $gcd = $x->bgcd(4);
	 # 6 / 2 = 3, 4	/ 2 = 2	=> 2
	 print $gcd

       Returns the Greatest Common Divisor of the two arguments.

   blcm
	 my $x = Math::GMP->new(6);
	 my $lcm = $x->blcm(4);	     # 6 * 2 = 12, 4 * 3 = 12 => 12
	 print $lcm;

       Returns the Least Common	Multiple of the	two arguments.

   bmodinv
	 my $x = Math::GMP->new(5);
	 my $modinv = $x->bmodinv(7);	# 5 * 3	== 1 (mod 7) =>	3
	 print $modinv;

       Returns the modular inverse of $x (mod $y), if defined. This currently
       returns 0 if there is no	inverse	(but that may change in	the future).
       Behaviour is undefined when $y is 0.

   broot
	 my $x = Math::GMP->new(100);
	 my $root = $x->root(3);    # int(100 ** (1/3))	=> 4
	 print $root;

       Returns the integer n'th	root of	its argument, given a positive integer
       n.

   brootrem
	 my $x = Math::GMP->new(100);
	 my($root, $rem) = $x->rootrem(3); # 4 ** 3 + 36 = 100
	 print "$x is $rem more	than the cube of $root";

       Returns the integer n'th	root of	its argument, and the difference such
       that " $root ** $n + $rem == $x ".

   bsqrt
	 my $x = Math::GMP->new(6);
	 my $root = $x->bsqrt();      #	int(sqrt(6)) =>	2
	 print $root;

       Returns the integer square root of its argument.

   bsqrtrem
	 my $x = Math::GMP->new(7);
	 my($root, $rem) = $x->sqrtrem(); # 2 ** 2 + 3 = 7
	 print "$x is $rem more	than the square	of $root";

       Returns the integer square root of its argument,	and the	difference
       such that " $root ** 2 +	$rem ==	$x ".

   is_perfect_power
	 my $x = Math::GMP->new(100);
	 my $is_power =	$x->is_perfect_power();
	 print "$x is "	. ($is_power ? "" : "not ") . "a perfect power";

       Returns "TRUE" if its argument is a power, ie if	there exist integers a
       and b with b > 1	such that " $x == $a **	$b ".

   is_perfect_square
	 my $x = Math::GMP->new(100);
	 my $is_square = $x->is_perfect_square();
	 print "$x is "	. ($is_square ?	"" : "not ") . "a perfect square";

       Returns "TRUE" if its argument is the square of an integer.

   legendre
	 $x = Math::GMP->new(6);
	 my $ret = $x->legendre(3);

       Returns the value of the	Legendre symbol	($x/$y). The value is defined
       only when $y is an odd prime; when the value is not defined, this
       currently returns 0 (but	that may change	in the future).

   jacobi
	 my $x = Math::GMP->new(6);
	 my $jacobi_verdict = $x->jacobi(3);

       Returns the value of the	Jacobi symbol ($x/$y). The value is defined
       only when $y is odd; when the value is not defined, this	currently
       returns 0 (but that may change in the future).

   fibonacci
	 my $fib = Math::GMP::fibonacci(16);

       Calculates the n'th number in the Fibonacci sequence.

   probab_prime
	 my $x = Math::GMP->new(7);
	 my $is_prime_verdict =	$x->probab_prime(10);

       Probabilistically determines if the number is a prime. Argument is the
       number of checks	to perform. Returns 0 if the number is definitely not
       a prime,	1 if it	may be,	and 2 if it definitely is a prime.

   $x->add_ui_gmp($n)
       Adds to $x and mutates it in-place. $n must be a	regular	non-GMP,
       positive, integer.

   ($quotient, $remainder) = $x->bdiv($y);
	 my $x = Math::GMP->new(7);
	 my ($quo, $rem) = $x->bdiv(3);

       Returns both the	division and the modulo	of an integer division
       operation.

   my $ret = $x->div_2exp_gmp($n);
	 my $x = Math::GMP->new(200);
	 my $ret = $x->div_2exp_gmp(2);

       Returns a right-shift of	the Math::GMP object by	an unsigned regular
       integer.	 Also look at blshift()	.

   my $str = $x->get_str_gmp($base)
	 my $init_n = 3	* 7 + 2	* 7 * 7	+ 6 * 7	* 7 * 7;
	 my $x = Math::GMP->new($init_n);
	 my $ret = $x->get_str_gmp(7);

	 print $ret; # Prints "6230".

       Returns a string	representation of the number in	base $base.

   my $clone = $x->gmp_copy()
       Returns a copy of $x that can be	modified without affecting the
       original.

   my $verdict = $x->gmp_tstbit($bit_index);
       Returns whether or not bit No. $bit_index is 1 in $x.

   my $remainder = $dividend->mmod_gmp($divisor)
	 my $x = Math::GMP->new(2 . ('0' x 200)	. 4);
	 my $y = Math::GMP->new(5);

	 my $ret = $x->mmod_gmp($y);
	 # $ret	is now Math::GMP of 4.

       From the	GMP documentation:

       Divide dividend and divisor and put the remainder in remainder. The
       remainder is always positive, and its value is less than	the value of
       the divisor.

   my $result =	$x->mod_2exp_gmp($shift);
	 my $x = Math::GMP->new(0b10001011);
	 my $ret = $x->mod_2exp_gmp(4);

	 # $ret	is now Math::GMP of 0b1011

       Returns a Math::GMP object containing the lower $shift bits of $x
       (while not modifying $x).

   my $left_shifted = $x->mul_2exp_gmp($shift);
	 my $x = Math::GMP->new(0b10001011);
	 my $ret = $x->mul_2exp_gmp(4);

	 # $ret	is now Math::GMP of 0b1000_1011_0000

       Returns a Math::GMP object containing $x	shifted	by $shift bits (where
       $shift is a plain integer).

   my $ret = $base->powm_gmp($exp, $mod);
	   my $base = Math::GMP->new(157);
	   my $exp = Math::GMP->new(100);
	   my $mod = Math::GMP->new(5013);

	   my $ret = $base->powm_gmp($exp, $mod);

	   # $ret is now (($base ** $exp) % $mod)

       Returns $base raised to the power of $exp modulo	$mod.

   my $plain_int_ret = $x->sizeinbase_gmp($plain_int_base);
       Returns the size	of $x in base $plain_int_base .

   my $int = $x->intify();
       Returns the value of the	object as an unblessed (and limited-in-
       precision) integer.

   _gmp_build_version()
	 my $gmp_version = Math::GMP::_gmp_build_version;
	 if ($gmp_version ge 6.0.0) {
	   print "Math::GMP was	built against libgmp-6.0.0 or later";
	 }

       Class method that returns as a vstring the version of libgmp against
       which this module was built.

   _gmp_lib_version()
	 my $gmp_version = Math::GMP::_gmp_lib_version;
	 if ($gmp_version ge 6.0.0) {
	   print "Math::GMP is now running with	libgmp-6.0.0 or	later";
	 }

       Class method that returns as a vstring the version of libgmp it is
       currently running.

   gcd()
       An alias	to bgcd() .

   lcm()
       An alias	to blcm() .

   constant
       For internal use. Do not	use directly.

   destroy
       For internal use. Do not	use directly.

   new_from_scalar
       For internal use. Do not	use directly.

   new_from_scalar_with_base
       For internal use. Do not	use directly.

   op_add
       For internal use. Do not	use directly.

   op_div
       For internal use. Do not	use directly.

   op_eq
       For internal use. Do not	use directly.

   op_mod
       For internal use. Do not	use directly.

   op_mul
       For internal use. Do not	use directly.

   op_pow
       For internal use. Do not	use directly.

   op_spaceship
       For internal use. Do not	use directly.

   op_sub
       For internal use. Do not	use directly.

   stringify
       For internal use. Do not	use directly.

   uintify
       For internal use. Do not	use directly.

BUGS
       As of version 1.0, Math::GMP is mostly compatible with the old
       Math::BigInt version. It	is not a full replacement for the rewritten
       Math::BigInt versions, though. See the SEE ALSO section on how to
       achieve to use Math::GMP	and retain full	compatibility to Math::BigInt.

       There are some slight incompatibilities,	such as	output of positive
       numbers not being prefixed by a '+' sign.  This is intentional.

       There are also some things missing, and not everything might work as
       expected.

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

SEE ALSO
       Math::BigInt has	a new interface	to use a different library than	the
       default pure Perl implementation. You can use, for instance, Math::GMP
       with it:

	 use Math::BigInt lib => 'GMP';

       If Math::GMP is not installed, it will fall back	to its own Perl
       implementation.

       See Math::BigInt	and Math::BigInt::GMP or Math::BigInt::Pari or
       Math::BigInt::BitVect.

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

AUTHOR
       Shlomi Fish <shlomif@cpan.org>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2000 by James H. Turner.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

BUGS
       Please report any bugs or feature requests on the bugtracker website
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP> or by
       email to	bug-math-gmp@rt.cpan.org <mailto:bug-math-gmp@rt.cpan.org>.

       When submitting a bug or	request, please	include	a test-file or a patch
       to an existing test-file	that illustrates the bug or desired feature.

SUPPORT
   Perldoc
       You can find documentation for this module with the perldoc command.

	 perldoc Math::GMP

   Websites
       The following websites have more	information about this module, and may
       be of help to you. As always, in	addition to those websites please use
       your favorite search engine to discover more resources.

       o   MetaCPAN

	   A modern, open-source CPAN search engine, useful to view POD	in
	   HTML	format.

	   <https://metacpan.org/release/Math-GMP>

       o   RT: CPAN's Bug Tracker

	   The RT ( Request Tracker ) website is the default bug/issue
	   tracking system for CPAN.

	   <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP>

       o   CPANTS

	   The CPANTS is a website that	analyzes the Kwalitee (	code metrics )
	   of a	distribution.

	   <http://cpants.cpanauthors.org/dist/Math-GMP>

       o   CPAN	Testers

	   The CPAN Testers is a network of smoke testers who run automated
	   tests on uploaded CPAN distributions.

	   <http://www.cpantesters.org/distro/M/Math-GMP>

       o   CPAN	Testers	Matrix

	   The CPAN Testers Matrix is a	website	that provides a	visual
	   overview of the test	results	for a distribution on various
	   Perls/platforms.

	   <http://matrix.cpantesters.org/?dist=Math-GMP>

       o   CPAN	Testers	Dependencies

	   The CPAN Testers Dependencies is a website that shows a chart of
	   the test results of all dependencies	for a distribution.

	   <http://deps.cpantesters.org/?module=Math::GMP>

   Bugs	/ Feature Requests
       Please report any bugs or feature requests by email to "bug-math-gmp at
       rt.cpan.org", or	through	the web	interface at
       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Math-GMP>. You	will
       be automatically	notified of any	progress on the	request	by the system.

   Source Code
       The code	is open	to the world, and available for	you to hack on.	Please
       feel free to browse it and play with it,	or whatever. If	you want to
       contribute patches, please send me a diff or prod me to pull from your
       repository :)

       <https://github.com/turnstep/Math-GMP>

	 git clone https://github.com/turnstep/Math-GMP.git

perl v5.32.0			  2020-02-09			  Math::GMP(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | BUGS | VERSION CONTROL | SEE ALSO | AUTHOR | AUTHOR | COPYRIGHT AND LICENSE | BUGS | SUPPORT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Math::GMP&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help