Manual

Reference

Modules

  • A • B • C • D • E
  • F • G • H • I • L
  • M • N • O • P • S
  • T • U • X

Tools

Math::BigInt::Calc

Perl 5 version 8.9 documentation
Go to top • Download PDF
Show page index • Show recent pages
Recently read

Math::BigInt::Calc

NAME

Math::BigInt::Calc - Pure Perl module to support Math::BigInt

SYNOPSIS

Provides support for big integer calculations. Not intended to be used by other modules. Other modules which sport the same functions can also be used to support Math::BigInt, like Math::BigInt::GMP or Math::BigInt::Pari.

DESCRIPTION

In order to allow for multiple big integer libraries, Math::BigInt was rewritten to use library modules for core math routines. Any module which follows the same API as this can be used instead by using the following:

  1. 	use Math::BigInt lib => 'libname';

'libname' is either the long name ('Math::BigInt::Pari'), or only the short version like 'Pari'.

STORAGE

METHODS

The following functions MUST be defined in order to support the use by Math::BigInt v1.70 or later:

  1. 	api_version()	return API version, 1 for v1.70, 2 for v1.83
  2. 	_new(string)	return ref to new object from ref to decimal string
  3. 	_zero()		return a new object with value 0
  4. 	_one()		return a new object with value 1
  5. 	_two()		return a new object with value 2
  6. 	_ten()		return a new object with value 10
  8. 	_str(obj)	return ref to a string representing the object
  9. 	_num(obj)	returns a Perl integer/floating point number
  10. 			NOTE: because of Perl numeric notation defaults,
  11. 			the _num'ified obj may lose accuracy due to 
  12. 			machine-dependent floating point size limitations
  13.                     
  14. 	_add(obj,obj)	Simple addition of two objects
  15. 	_mul(obj,obj)	Multiplication of two objects
  16. 	_div(obj,obj)	Division of the 1st object by the 2nd
  17. 			In list context, returns (result,remainder).
  18. 			NOTE: this is integer math, so no
  19. 			fractional part will be returned.
  20. 			The second operand will be not be 0, so no need to
  21. 			check for that.
  22. 	_sub(obj,obj)	Simple subtraction of 1 object from another
  23. 			a third, optional parameter indicates that the params
  24. 			are swapped. In this case, the first param needs to
  25. 			be preserved, while you can destroy the second.
  26. 			sub (x,y,1) => return x - y and keep x intact!
  27. 	_dec(obj)	decrement object by one (input is guaranteed to be > 0)
  28. 	_inc(obj)	increment object by one
  31. 	_acmp(obj,obj)	<=> operator for objects (return -1, 0 or 1)
  33. 	_len(obj)	returns count of the decimal digits of the object
  34. 	_digit(obj,n)	returns the n'th decimal digit of object
  36. 	_is_one(obj)	return true if argument is 1
  37. 	_is_two(obj)	return true if argument is 2
  38. 	_is_ten(obj)	return true if argument is 10
  39. 	_is_zero(obj)	return true if argument is 0
  40. 	_is_even(obj)	return true if argument is even (0,2,4,6..)
  41. 	_is_odd(obj)	return true if argument is odd (1,3,5,7..)
  43. 	_copy		return a ref to a true copy of the object
  45. 	_check(obj)	check whether internal representation is still intact
  46. 			return 0 for ok, otherwise error message as string
  48. 	_from_hex(str)	return new object from a hexadecimal string
  49. 	_from_bin(str)	return new object from a binary string
  50. 	_from_oct(str)	return new object from an octal string
  51. 	
  52. 	_as_hex(str)	return string containing the value as
  53. 			unsigned hex string, with the '0x' prepended.
  54. 			Leading zeros must be stripped.
  55. 	_as_bin(str)	Like as_hex, only as binary string containing only
  56. 			zeros and ones. Leading zeros must be stripped and a
  57. 			'0b' must be prepended.
  58. 	
  59. 	_rsft(obj,N,B)	shift object in base B by N 'digits' right
  60. 	_lsft(obj,N,B)	shift object in base B by N 'digits' left
  61. 	
  62. 	_xor(obj1,obj2)	XOR (bit-wise) object 1 with object 2
  63. 			Note: XOR, AND and OR pad with zeros if size mismatches
  64. 	_and(obj1,obj2)	AND (bit-wise) object 1 with object 2
  65. 	_or(obj1,obj2)	OR (bit-wise) object 1 with object 2
  67. 	_mod(obj1,obj2)	Return remainder of div of the 1st by the 2nd object
  68. 	_sqrt(obj)	return the square root of object (truncated to int)
  69. 	_root(obj)	return the n'th (n >= 3) root of obj (truncated to int)
  70. 	_fac(obj)	return factorial of object 1 (1*2*3*4..)
  71. 	_pow(obj1,obj2)	return object 1 to the power of object 2
  72. 			return undef for NaN
  73. 	_zeros(obj)	return number of trailing decimal zeros
  74. 	_modinv		return inverse modulus
  75. 	_modpow		return modulus of power ($x ** $y) % $z
  76. 	_log_int(X,N)	calculate integer log() of X in base N
  77. 			X >= 0, N >= 0 (return undef for NaN)
  78. 			returns (RESULT, EXACT) where EXACT is:
  79. 			 1     : result is exactly RESULT
  80. 			 0     : result was truncated to RESULT
  81. 			 undef : unknown whether result is exactly RESULT
  82.         _gcd(obj,obj)	return Greatest Common Divisor of two objects

The following functions are REQUIRED for an api_version of 2 or greater:

  1. 	_1ex($x)	create the number 1Ex where x >= 0
  2. 	_alen(obj)	returns approximate count of the decimal digits of the
  3. 			object. This estimate MUST always be greater or equal
  4. 			to what _len() returns.
  5.         _nok(n,k)	calculate n over k (binomial coefficient)

The following functions are optional, and can be defined if the underlying lib has a fast way to do them. If undefined, Math::BigInt will use pure Perl (hence slow) fallback routines to emulate these:

  1. 	_signed_or
  2. 	_signed_and
  3. 	_signed_xor

Input strings come in as unsigned but with prefix (i.e. as '123', '0xabc' or '0b1101').

So the library needs only to deal with unsigned big integers. Testing of input parameter validity is done by the caller, so you need not worry about underflow (f.i. in _sub() , _dec() ) nor about division by zero or similar cases.

The first parameter can be modified, that includes the possibility that you return a reference to a completely different object instead. Although keeping the reference and just changing its contents is preferred over creating and returning a different reference.

Return values are always references to objects, strings, or true/false for comparison routines.

WRAP YOUR OWN

If you want to port your own favourite c-lib for big numbers to the Math::BigInt interface, you can take any of the already existing modules as a rough guideline. You should really wrap up the latest BigInt and BigFloat testsuites with your module, and replace in them any of the following:

  1. 	use Math::BigInt;

by this:

  1. 	use Math::BigInt lib => 'yourlib';

This way you ensure that your library really works 100% within Math::BigInt.

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Original math code by Mark Biggar, rewritten by Tels http://bloodgate.com/ in late 2000. Seperated from BigInt and shaped API with the help of John Peacock.

Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2007.

SEE ALSO

Math::BigInt, Math::BigFloat, Math::BigInt::GMP, Math::BigInt::FastCalc and Math::BigInt::Pari.

Page index