Documentation

BigInteger
in package
implements Serializable

Pure-PHP arbitrary precision integer arithmetic library. Supports base-2, base-10, base-16, and base-256 numbers.

Tags
author

Jim Wigginton terrafrost@php.net

access

public

Table of Contents

Interfaces

Serializable

Properties

$engines  : array<string|int, mixed>
Selected Engines
$mainEngine  : string
Main Engine
$modexpEngine  : string
Modular Exponentiation Engine
$value  : object
The actual BigInteger object

Methods

__clone()  : mixed
Clone
__construct()  : BigInteger
Converts base-2, base-10, base-16, and binary strings (base-256) to BigIntegers.
__debugInfo()  : mixed
__debugInfo() magic method
__toString()  : mixed
__toString() magic method
abs()  : BigInteger
Absolute value.
add()  : BigInteger
Adds two BigIntegers.
between()  : bool
Tests BigInteger to see if it is between two integers, inclusive
bitwise_and()  : BigInteger
Logical And
bitwise_leftRotate()  : BigInteger
Logical Left Rotate
bitwise_leftShift()  : BigInteger
Logical Left Shift
bitwise_not()  : BigInteger
Logical Not
bitwise_or()  : BigInteger
Logical Or
bitwise_rightRotate()  : BigInteger
Logical Right Rotate
bitwise_rightShift()  : BigInteger
Logical Right Shift
bitwise_split()  : array<string|int, BigInteger>
Bitwise Split
bitwise_xor()  : BigInteger
Logical Exclusive Or
compare()  : int
Compares two numbers.
createRecurringModuloFunction()  : callable
Create Recurring Modulo Function
divide()  : array<string|int, BigInteger>
Divides two BigIntegers.
equals()  : bool
Tests the equality of two numbers.
extendedGCD()  : array<string|int, BigInteger>
Calculates modular inverses.
gcd()  : BigInteger
Calculates the greatest common divisor
getEngine()  : array<string|int, string>
Returns the engine type
getLength()  : int
Return the size of a BigInteger in bits
getLengthInBytes()  : int
Return the size of a BigInteger in bytes
getPrecision()  : int|bool
Get Precision
isNegative()  : bool
Is Negative?
isOdd()  : bool
Is Odd?
isPrime()  : bool
Checks a numer to see if it's prime
max()  : BigInteger
Return the maximum BigInteger between an arbitrary number of BigIntegers.
min()  : BigInteger
Return the minimum BigInteger between an arbitrary number of BigIntegers.
minMaxBits()  : array<string|int, BigInteger>
Returns the smallest and largest n-bit number
modInverse()  : BigInteger
Calculates modular inverses.
modPow()  : BigInteger
Performs modular exponentiation.
multiply()  : BigInteger
Multiplies two BigIntegers
negate()  : BigInteger
Negate
pow()  : BigInteger
Performs exponentiation.
powMod()  : BigInteger
Performs modular exponentiation.
random()  : BigInteger
Generates a random number of a certain size
randomPrime()  : BigInteger
Generates a random prime number of a certain size
randomRange()  : BigInteger
Generate a random number between a range
randomRangePrime()  : false|BigInteger
Generate a random prime number between a range
root()  : BigInteger
Calculates the nth root of a biginteger.
scan1divide()  : int
Scan for 1 and right shift by that amount
serialize()  : string
Serialize
setEngine()  : mixed
Sets engine type.
setPrecision()  : mixed
Set Precision
subtract()  : BigInteger
Subtracts two BigIntegers.
testBit()  : bool
Tests if a bit is set
toBits()  : string
Converts a BigInteger to a bit string (eg. base-2).
toBytes()  : string
Converts a BigInteger to a byte string (eg. base-256).
toHex()  : string
Converts a BigInteger to a hex string (eg. base-16).
toString()  : string
Converts a BigInteger to a base-10 number.
unserialize()  : mixed
Serialize
initialize_static_variables()  : mixed
Initialize static variables

Properties

$engines

Selected Engines

private static array<string|int, mixed> $engines

$mainEngine

Main Engine

private static string $mainEngine

$modexpEngine

Modular Exponentiation Engine

private static string $modexpEngine

$value

The actual BigInteger object

private object $value

Methods

__construct()

Converts base-2, base-10, base-16, and binary strings (base-256) to BigIntegers.

public __construct([string|int|Engine $x = 0 ][, int $base = 10 ]) : BigInteger

If the second parameter - $base - is negative, then it will be assumed that the number's are encoded using two's compliment. The sole exception to this is -10, which is treated the same as 10 is.

Parameters
$x : string|int|Engine = 0

Base-10 number or base-$base number if $base set.

$base : int = 10
Return values
BigInteger

__debugInfo()

__debugInfo() magic method

public __debugInfo() : mixed

Will be called, automatically, when print_r() or var_dump() are called

__toString()

__toString() magic method

public __toString() : mixed

bitwise_leftRotate()

Logical Left Rotate

public bitwise_leftRotate(int $shift) : BigInteger

Instead of the top x bits being dropped they're appended to the shifted bit string.

Parameters
$shift : int
Return values
BigInteger

bitwise_leftShift()

Logical Left Shift

public bitwise_leftShift(int $shift) : BigInteger

Shifts BigInteger's by $shift bits, effectively multiplying by 2**$shift.

Parameters
$shift : int
Return values
BigInteger

bitwise_rightRotate()

Logical Right Rotate

public bitwise_rightRotate(int $shift) : BigInteger

Instead of the bottom x bits being dropped they're prepended to the shifted bit string.

Parameters
$shift : int
Return values
BigInteger

bitwise_rightShift()

Logical Right Shift

public bitwise_rightShift(int $shift) : BigInteger

Shifts BigInteger's by $shift bits, effectively dividing by 2**$shift.

Parameters
$shift : int
Return values
BigInteger

bitwise_split()

Bitwise Split

public bitwise_split(int $split) : array<string|int, BigInteger>

Splits BigInteger's into chunks of $split bits

Parameters
$split : int
Return values
array<string|int, BigInteger>

compare()

Compares two numbers.

public compare(BigInteger $y) : int

Although one might think !$x->compare($y) means $x != $y, it, in fact, means the opposite. The reason for this is demonstrated thusly:

$x > $y: $x->compare($y) > 0 $x < $y: $x->compare($y) < 0 $x == $y: $x->compare($y) == 0

Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).

Parameters
$y : BigInteger
Tags
access

public

see
self::equals()
Return values
int —

in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.

createRecurringModuloFunction()

Create Recurring Modulo Function

public createRecurringModuloFunction() : callable

Sometimes it may be desirable to do repeated modulos with the same number outside of modular exponentiation

Return values
callable

divide()

Divides two BigIntegers.

public divide(BigInteger $y) : array<string|int, BigInteger>

Returns an array whose first element contains the quotient and whose second element contains the "common residue". If the remainder would be positive, the "common residue" and the remainder are the same. If the remainder would be negative, the "common residue" is equal to the sum of the remainder and the divisor (basically, the "common residue" is the first positive modulo).

Here's an example:

divide($b); echo $quotient->toString(); // outputs 0 echo "\r\n"; echo $remainder->toString(); // outputs 10 ?>
Parameters
$y : BigInteger
Return values
array<string|int, BigInteger>

equals()

Tests the equality of two numbers.

public equals(BigInteger $x) : bool

If you need to see if one number is greater than or less than another number, use BigInteger::compare()

Parameters
$x : BigInteger
Return values
bool

extendedGCD()

Calculates modular inverses.

public extendedGCD(BigInteger $n) : array<string|int, BigInteger>

Say you have (30 mod 17 * x mod 17) mod 17 == 1. x can be found using modular inverses.

Parameters
$n : BigInteger
Return values
array<string|int, BigInteger>

getEngine()

Returns the engine type

public static getEngine() : array<string|int, string>
Return values
array<string|int, string>

getLength()

Return the size of a BigInteger in bits

public getLength() : int
Return values
int

getLengthInBytes()

Return the size of a BigInteger in bytes

public getLengthInBytes() : int
Return values
int

getPrecision()

Get Precision

public getPrecision() : int|bool

Returns the precision if it exists, false if it doesn't

Return values
int|bool

isNegative()

Is Negative?

public isNegative() : bool
Return values
bool

isOdd()

Is Odd?

public isOdd() : bool
Return values
bool

isPrime()

Checks a numer to see if it's prime

public isPrime([int|bool $t = false ]) : bool

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. BigInteger::randomPrime() can be distributed across multiple pageloads on a website instead of just one.

Parameters
$t : int|bool = false
Return values
bool

minMaxBits()

Returns the smallest and largest n-bit number

public static minMaxBits(int $bits) : array<string|int, BigInteger>
Parameters
$bits : int
Return values
array<string|int, BigInteger>

random()

Generates a random number of a certain size

public static random(int $size) : BigInteger

Bit length is equal to $size

Parameters
$size : int
Return values
BigInteger

randomPrime()

Generates a random prime number of a certain size

public static randomPrime(int $size) : BigInteger

Bit length is equal to $size

Parameters
$size : int
Return values
BigInteger

randomRange()

Generate a random number between a range

public static randomRange(BigInteger $min, BigInteger $max) : BigInteger

Returns a random number between $min and $max where $min and $max can be defined using one of the two methods:

BigInteger::randomRange($min, $max) BigInteger::randomRange($max, $min)

Parameters
$min : BigInteger
$max : BigInteger
Return values
BigInteger

root()

Calculates the nth root of a biginteger.

public root([int $n = 2 ]) : BigInteger

Returns the nth root of a positive biginteger, where n defaults to 2

Parameters
$n : int = 2

optional

Return values
BigInteger

scan1divide()

Scan for 1 and right shift by that amount

public static scan1divide(BigInteger $r) : int

ie. $s = gmp_scan1($n, 0) and $r = gmp_div_q($n, gmp_pow(gmp_init('2'), $s));

Parameters
$r : BigInteger
Return values
int

serialize()

Serialize

public serialize() : string

Will be called, automatically, when serialize() is called on a BigInteger object.

phpseclib 1.0 serialized strings look like this: O:15:"Math_BigInteger":1:{s:3:"hex";s:18:"00ab54a98ceb1f0ad2";}

phpseclib 3.0 serialized strings look like this: C:25:"phpseclib\Math\BigInteger":42:{a:1:{s:3:"hex";s:18:"00ab54a98ceb1f0ad2";}}

Return values
string

setEngine()

Sets engine type.

public static setEngine(string $main[, array<string|int, mixed> $modexps = ['DefaultEngine'] ]) : mixed

Throws an exception if the type is invalid

Parameters
$main : string
$modexps : array<string|int, mixed> = ['DefaultEngine']

optional

setPrecision()

Set Precision

public setPrecision(int $bits) : mixed

Some bitwise operations give different results depending on the precision being used. Examples include left shift, not, and rotates.

Parameters
$bits : int

testBit()

Tests if a bit is set

public testBit(int $x) : bool
Parameters
$x : int
Return values
bool

toBits()

Converts a BigInteger to a bit string (eg. base-2).

public toBits([bool $twos_compliment = false ]) : string

Negative numbers are saved as positive numbers, unless $twos_compliment is set to true, at which point, they're saved as two's compliment.

Parameters
$twos_compliment : bool = false
Return values
string

toBytes()

Converts a BigInteger to a byte string (eg. base-256).

public toBytes([bool $twos_compliment = false ]) : string
Parameters
$twos_compliment : bool = false
Return values
string

toHex()

Converts a BigInteger to a hex string (eg. base-16).

public toHex([bool $twos_compliment = false ]) : string
Parameters
$twos_compliment : bool = false
Return values
string

toString()

Converts a BigInteger to a base-10 number.

public toString() : string
Return values
string

unserialize()

Serialize

public unserialize(string $serialized) : mixed

Will be called, automatically, when unserialize() is called on a BigInteger object.

Parameters
$serialized : string

initialize_static_variables()

Initialize static variables

private static initialize_static_variables() : mixed 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results