octoleo/phpseclib
1
0
Fork 0
mirror of https://github.com/phpseclib/phpseclib.git synced 2024-09-28 15:19:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Some more documentation polishing in Math/BigInteger.php.

Browse Source
This commit is contained in:
Andreas Fischer 2014-06-02 20:08:55 +02:00
parent 68ab62e70f
commit 65ec4dc8bc
1 changed files with 68 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
phpseclib/Math/BigInteger.php
View File

@ -11,7 +11,7 @@
* {@internal (all DocBlock comments regarding implementation - such as the one that follows - refer to the * {@internal (all DocBlock comments regarding implementation - such as the one that follows - refer to the
* {@link MATH_BIGINTEGER_MODE_INTERNAL MATH_BIGINTEGER_MODE_INTERNAL} mode) * {@link MATH_BIGINTEGER_MODE_INTERNAL MATH_BIGINTEGER_MODE_INTERNAL} mode)
* *
* Math_BigInteger uses base-2**26 to perform operations such as multiplication and division and * BigInteger uses base-2**26 to perform operations such as multiplication and division and
* base-2**52 (ie. two base 2**26 digits) to perform addition and subtraction. Because the largest possible * base-2**52 (ie. two base 2**26 digits) to perform addition and subtraction. Because the largest possible
* value when multiplying two base-2**26 numbers together is a base-2**52 number, double precision floating * value when multiplying two base-2**26 numbers together is a base-2**52 number, double precision floating
* point numbers - numbers that should be supported on most hardware and whose significand is 53 bits - are * point numbers - numbers that should be supported on most hardware and whose significand is 53 bits - are
@ -72,27 +72,27 @@ namespace phpseclib\Math;
* Reduction constants * Reduction constants
* *
* @access private * @access private
* @see Math_BigInteger::_reduce() * @see BigInteger::_reduce()
*/ */
/** /**
* @see Math_BigInteger::_montgomery() * @see BigInteger::_montgomery()
* @see Math_BigInteger::_prepMontgomery() * @see BigInteger::_prepMontgomery()
*/ */
define('MATH_BIGINTEGER_MONTGOMERY', 0); define('MATH_BIGINTEGER_MONTGOMERY', 0);
/** /**
* @see Math_BigInteger::_barrett() * @see BigInteger::_barrett()
*/ */
define('MATH_BIGINTEGER_BARRETT', 1); define('MATH_BIGINTEGER_BARRETT', 1);
/** /**
* @see Math_BigInteger::_mod2() * @see BigInteger::_mod2()
*/ */
define('MATH_BIGINTEGER_POWEROF2', 2); define('MATH_BIGINTEGER_POWEROF2', 2);
/** /**
* @see Math_BigInteger::_remainder() * @see BigInteger::_remainder()
*/ */
define('MATH_BIGINTEGER_CLASSIC', 3); define('MATH_BIGINTEGER_CLASSIC', 3);
/** /**
* @see Math_BigInteger::__clone() * @see BigInteger::__clone()
*/ */
define('MATH_BIGINTEGER_NONE', 4); define('MATH_BIGINTEGER_NONE', 4);
/**#@-*/ /**#@-*/
@ -117,8 +117,8 @@ define('MATH_BIGINTEGER_SIGN', 1);
/**#@+ /**#@+
* @access private * @access private
* @see Math_BigInteger::_montgomery() * @see BigInteger::_montgomery()
* @see Math_BigInteger::_barrett() * @see BigInteger::_barrett()
*/ */
/** /**
* Cache constants * Cache constants
@ -136,7 +136,7 @@ define('MATH_BIGINTEGER_DATA', 1);
* Mode constants. * Mode constants.
* *
* @access private * @access private
* @see Math_BigInteger::Math_BigInteger() * @see BigInteger::__construct()
*/ */
/** /**
* To use the pure-PHP implementation * To use the pure-PHP implementation
@ -245,7 +245,7 @@ class BigInteger
* *
* @param optional $x base-10 number or base-$base number if $base set. * @param optional $x base-10 number or base-$base number if $base set.
* @param optional integer $base * @param optional integer $base
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function __construct($x = 0, $base = 10) function __construct($x = 0, $base = 10)
@ -718,7 +718,7 @@ class BigInteger
* *
* @access public * @access public
* @see __clone() * @see __clone()
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function copy() function copy()
{ {
@ -748,14 +748,14 @@ class BigInteger
/** /**
* __clone() magic method * __clone() magic method
* *
* Although you can call Math_BigInteger::__toString() directly in PHP5, you cannot call Math_BigInteger::__clone() * Although you can call BigInteger::__toString() directly in PHP5, you cannot call BigInteger::__clone() directly
* directly in PHP5. You can in PHP4 since it's not a magic method, but in PHP5, you have to call it by using the PHP5 * in PHP5. You can in PHP4 since it's not a magic method, but in PHP5, you have to call it by using the PHP5
* only syntax of $y = clone $x. As such, if you're trying to write an application that works on both PHP4 and PHP5, * only syntax of $y = clone $x. As such, if you're trying to write an application that works on both PHP4 and
* call Math_BigInteger::copy(), instead. * PHP5, call BigInteger::copy(), instead.
* *
* @access public * @access public
* @see copy() * @see copy()
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function __clone() function __clone()
{ {
@ -765,7 +765,7 @@ class BigInteger
/** /**
* __sleep() magic method * __sleep() magic method
* *
* Will be called, automatically, when serialize() is called on a Math_BigInteger object. * Will be called, automatically, when serialize() is called on a BigInteger object.
* *
* @see __wakeup() * @see __wakeup()
* @access public * @access public
@ -787,7 +787,7 @@ class BigInteger
/** /**
* __wakeup() magic method * __wakeup() magic method
* *
* Will be called, automatically, when unserialize() is called on a Math_BigInteger object. * Will be called, automatically, when unserialize() is called on a BigInteger object.
* *
* @see __sleep() * @see __sleep()
* @access public * @access public
@ -818,8 +818,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $y * @param \phpseclib\Math\BigInteger $y
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal Performs base-2**52 addition * @internal Performs base-2**52 addition
*/ */
@ -947,8 +947,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $y * @param \phpseclib\Math\BigInteger $y
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal Performs base-2**52 subtraction * @internal Performs base-2**52 subtraction
*/ */
@ -1081,8 +1081,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $x * @param \phpseclib\Math\BigInteger $x
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function multiply($x) function multiply($x)
@ -1365,7 +1365,7 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $y * @param \phpseclib\Math\BigInteger $y
* @return Array * @return Array
* @access public * @access public
* @internal This function is based off of {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=9 HAC 14.20}. * @internal This function is based off of {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=9 HAC 14.20}.
@ -1581,9 +1581,9 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $e * @param \phpseclib\Math\BigInteger $e
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal The most naive approach to modular exponentiation has very unreasonable requirements, and * @internal The most naive approach to modular exponentiation has very unreasonable requirements, and
* and although the approach involving repeated squaring does vastly better, it, too, is impractical * and although the approach involving repeated squaring does vastly better, it, too, is impractical
@ -1743,11 +1743,11 @@ class BigInteger
/** /**
* Performs modular exponentiation. * Performs modular exponentiation.
* *
* Alias for Math_BigInteger::modPow() * Alias for modPow().
* *
* @param Math_BigInteger $e * @param \phpseclib\Math\BigInteger $e
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function powMod($e, $n) function powMod($e, $n)
@ -1763,10 +1763,10 @@ class BigInteger
* however, this function performs a modular reduction after every multiplication and squaring operation. * however, this function performs a modular reduction after every multiplication and squaring operation.
* As such, this function has the same preconditions that the reductions being used do. * As such, this function has the same preconditions that the reductions being used do.
* *
* @param Math_BigInteger $e * @param \phpseclib\Math\BigInteger $e
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @param Integer $mode * @param Integer $mode
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access private * @access private
*/ */
function _slidingWindow($e, $n, $mode) function _slidingWindow($e, $n, $mode)
@ -1935,8 +1935,8 @@ class BigInteger
* *
* @see _slidingWindow() * @see _slidingWindow()
* @access private * @access private
* @param Math_BigInteger * @param \phpseclib\Math\BigInteger
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function _mod2($n) function _mod2($n)
{ {
@ -2057,7 +2057,7 @@ class BigInteger
/** /**
* (Regular) Barrett Modular Reduction * (Regular) Barrett Modular Reduction
* *
* For numbers with more than four digits Math_BigInteger::_barrett() is faster. The difference between that and this * For numbers with more than four digits BigInteger::_barrett() is faster. The difference between that and this
* is that this function does not fold the denominator into a smaller form. * is that this function does not fold the denominator into a smaller form.
* *
* @see _slidingWindow() * @see _slidingWindow()
@ -2388,8 +2388,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @return mixed false, if no modular inverse exists, Math_BigInteger, otherwise. * @return mixed false, if no modular inverse exists, \phpseclib\Math\BigInteger, otherwise.
* @access public * @access public
* @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information. * @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information.
*/ */
@ -2450,8 +2450,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal Calculates the GCD using the binary xGCD algorithim described in * @internal Calculates the GCD using the binary xGCD algorithim described in
* {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=19 HAC 14.61}. As the text above 14.61 notes, * {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=19 HAC 14.61}. As the text above 14.61 notes,
@ -2582,8 +2582,8 @@ class BigInteger
* ?> * ?>
* </code> * </code>
* *
* @param Math_BigInteger $n * @param \phpseclib\Math\BigInteger $n
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function gcd($n) function gcd($n)
@ -2595,7 +2595,7 @@ class BigInteger
/** /**
* Absolute value. * Absolute value.
* *
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function abs() function abs()
@ -2628,7 +2628,7 @@ class BigInteger
* *
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y). * Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
* *
* @param Math_BigInteger $y * @param \phpseclib\Math\BigInteger $y
* @return Integer < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal. * @return Integer < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @access public * @access public
* @see equals() * @see equals()
@ -2685,9 +2685,9 @@ class BigInteger
/** /**
* Tests the equality of two numbers. * Tests the equality of two numbers.
* *
* If you need to see if one number is greater than or less than another number, use Math_BigInteger::compare() * If you need to see if one number is greater than or less than another number, use BigInteger::compare()
* *
* @param Math_BigInteger $x * @param \phpseclib\Math\BigInteger $x
* @return Boolean * @return Boolean
* @access public * @access public
* @see compare() * @see compare()
@ -2727,10 +2727,10 @@ class BigInteger
/** /**
* Logical And * Logical And
* *
* @param Math_BigInteger $x * @param \phpseclib\Math\BigInteger $x
* @access public * @access public
* @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat> * @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat>
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function bitwise_and($x) function bitwise_and($x)
{ {
@ -2768,10 +2768,10 @@ class BigInteger
/** /**
* Logical Or * Logical Or
* *
* @param Math_BigInteger $x * @param \phpseclib\Math\BigInteger $x
* @access public * @access public
* @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat> * @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat>
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function bitwise_or($x) function bitwise_or($x)
{ {
@ -2808,10 +2808,10 @@ class BigInteger
/** /**
* Logical Exclusive-Or * Logical Exclusive-Or
* *
* @param Math_BigInteger $x * @param \phpseclib\Math\BigInteger $x
* @access public * @access public
* @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat> * @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat>
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function bitwise_xor($x) function bitwise_xor($x)
{ {
@ -2850,7 +2850,7 @@ class BigInteger
* *
* @access public * @access public
* @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat> * @internal Implemented per a request by Lluis Pamies i Juarez <lluis _a_ pamies.cat>
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
*/ */
function bitwise_not() function bitwise_not()
{ {
@ -2887,7 +2887,7 @@ class BigInteger
* Shifts BigInteger's by $shift bits, effectively dividing by 2**$shift. * Shifts BigInteger's by $shift bits, effectively dividing by 2**$shift.
* *
* @param Integer $shift * @param Integer $shift
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal The only version that yields any speed increases is the internal version. * @internal The only version that yields any speed increases is the internal version.
*/ */
@ -2925,7 +2925,7 @@ class BigInteger
* Shifts BigInteger's by $shift bits, effectively multiplying by 2**$shift. * Shifts BigInteger's by $shift bits, effectively multiplying by 2**$shift.
* *
* @param Integer $shift * @param Integer $shift
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal The only version that yields any speed increases is the internal version. * @internal The only version that yields any speed increases is the internal version.
*/ */
@ -2963,7 +2963,7 @@ class BigInteger
* Instead of the top x bits being dropped they're appended to the shifted bit string. * Instead of the top x bits being dropped they're appended to the shifted bit string.
* *
* @param Integer $shift * @param Integer $shift
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function bitwise_leftRotate($shift) function bitwise_leftRotate($shift)
@ -3007,7 +3007,7 @@ class BigInteger
* Instead of the bottom x bits being dropped they're prepended to the shifted bit string. * Instead of the bottom x bits being dropped they're prepended to the shifted bit string.
* *
* @param Integer $shift * @param Integer $shift
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function bitwise_rightRotate($shift) function bitwise_rightRotate($shift)
@ -3021,7 +3021,7 @@ class BigInteger
* Byte length is equal to $length. Uses crypt_random if it's loaded and mt_rand if it's not. * Byte length is equal to $length. Uses crypt_random if it's loaded and mt_rand if it's not.
* *
* @param Integer $length * @param Integer $length
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access private * @access private
*/ */
function _random_number_helper($size) function _random_number_helper($size)
@ -3050,7 +3050,7 @@ class BigInteger
* *
* @param optional Integer $min * @param optional Integer $min
* @param optional Integer $max * @param optional Integer $max
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
*/ */
function random($min = false, $max = false) function random($min = false, $max = false)
@ -3126,7 +3126,7 @@ class BigInteger
* @param optional Integer $min * @param optional Integer $min
* @param optional Integer $max * @param optional Integer $max
* @param optional Integer $timeout * @param optional Integer $timeout
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access public * @access public
* @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap4.pdf#page=15 HAC 4.44}. * @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap4.pdf#page=15 HAC 4.44}.
*/ */
@ -3246,7 +3246,7 @@ class BigInteger
* Checks a numer to see if it's prime * Checks a numer to see if it's prime
* *
* Assuming the $t parameter is not set, this function has an error rate of 2**-80. The main motivation for the * Assuming the $t parameter is not set, this function has an error rate of 2**-80. The main motivation for the
* $t parameter is distributability. Math_BigInteger::randomPrime() can be distributed across multiple pageloads * $t parameter is distributability. BigInteger::randomPrime() can be distributed across multiple pageloads
* on a website instead of just one. * on a website instead of just one.
* *
* @param optional Integer $t * @param optional Integer $t
@ -3470,8 +3470,8 @@ class BigInteger
* *
* Removes leading zeros and truncates (if necessary) to maintain the appropriate precision * Removes leading zeros and truncates (if necessary) to maintain the appropriate precision
* *
* @param Math_BigInteger * @param \phpseclib\Math\BigInteger
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @see _trim() * @see _trim()
* @access private * @access private
*/ */
@ -3521,7 +3521,7 @@ class BigInteger
* Removes leading zeros * Removes leading zeros
* *
* @param Array $value * @param Array $value
* @return Math_BigInteger * @return \phpseclib\Math\BigInteger
* @access private * @access private
*/ */
function _trim($value) function _trim($value)