simplito/bigint-wrapper-php

Common interface for php_gmp and php_bcmath modules

BigInteger wrapper library for PHP

Information

This library is a common interface for php_gmp and php_bcmath modules. It automatically detects supported modules and uses the best of them (gmp>bcmath). Gmp is a lot faster, but is also missing on many hosting services -- that is why this wrapper has been created. It is used for example in encryption functions of the PrivMX WebMail software., _(*1)

Installation

You can install this library via Composer:, _(*2)

composer require simplito/bigint-wrapper-php

Documentation

If you want to force using a specific implementation, then define constant S_MATH_BIGINTEGER_MODE - set it to "gmp" or "bcmath". If you do not do this, mode of operation and the constant will be set automatically., _(*3)

If there are no gmp and bcmath modules, an exception will be thrown. If you want to prevent this, then simply define S_MATH_BIGINTEGER_QUIET constant., _(*4)

All functions of this library are implemented as members of class BigInteger, which is located under BI namespace. Instances of BigInteger are immutable - member functions usually return new instances of the BigInteger class., _(*5)

ConvertibleToBi - a placeholder type

To make the below documentation more readable we use the "ConvertibleToBi" type symbol, which in reality can be one of the following types:
- an instance of the BigInteger class - an integer - a decimal string - a gmp resource or class (only when you are in gmp mode), _(*6)

If you have a non-decimal string and want to use it -- first you have to convert it to BigInteger class using:, _(*7)

new BigInteger($myNonDecimalString, $baseOfMyNonDecimalString)

BI\BigInteger class members

construct(ConvertibleToBi $value = 0, int $base = 10)

Creates a new instance of BigInteger. If you pass an invalid value, an exception will be thrown. If $base === true then passed $value will be used without any check and conversion. Supported bases: 2, 10, 16, 256. - GMP implementation: gmp_init + bin2hex for 256 base - Bcmath implementation: custom(bcadd + bcmul), _(*8)

static BigInteger|false createSafe(ConvertibleToBi $value = 0, int $base = 10)

Creates a new BigInteger instance in the same way as constructor, but if there is an error, false will be returned instead of throwing an exception., _(*9)

BigInteger add(ConvertibleToBi $x)

Adds numbers - GMP implementation: gmp_add - Bcmath implementation: bcadd, _(*10)

BigInteger sub(ConvertibleToBi $x)

Subtracts numbers - GMP implementation: gmp_sub - Bcmath implementation: bcsub, _(*11)

BigInteger mul(ConvertibleToBi $x)

Multiplies numbers - GMP implementation: gmp_mul - Bcmath implementation: bcmul, _(*12)

BigInteger div(ConvertibleToBi $x)

Divides numbers - GMP implementation: gmp_div_q - Bcmath implementation: bcdiv, _(*13)

BigInteger divR(ConvertibleToBi $x)

Returns a remainder of the division of numbers. The remainder has the sign of the divided number. - GMP implementation: gmp_div_r - Bcmath implementation: bcmod, _(*14)

array(BigInteger, BigInteger) divQR(ConvertibleToBi $x)

Divides numbers and returns quotient and remainder. Returns an array(), with the first element being quotient, and the second being remainder. - GMP implementation: gmp_div_qr - Bcmath implementation: div + divR, _(*15)

BigInteger mod(ConvertibleToBi $x)

The "division modulo" operation. The result is always non-negative, the sign of divider is ignored. - GMP implementation: gmp_mod - Bcmath implementation: custom (bcmod + bcadd), _(*16)

BigInteger gcd(ConvertibleToBi $x)

Calculates greatest common divisor - GMP implementation: gmp_gcd - Bcmath implementation: custom (bccomp + bcdiv + bcsub + bcmul), _(*17)

BigInteger|false modInverse(ConvertibleToBi $x)

Inverses by modulo, returns false if inversion does not exist. - GMP implementation: gmp_invert - Bcmath implementation: custom (gcd), _(*18)

BigInteger pow(ConvertibleToBi $x)

The power function. - GMP implementation: gmp_pow - Bcmath implementation: bcpow, _(*19)

BigInteger powMod(ConvertibleToBi $x, ConvertibleToBi $n)

The modular power function. - GMP implementation: gmp_powm - Bcmath implementation: bcpowmod, _(*20)

BigInteger abs()

Returns absolute value. - GMP implementation: gmp_abs - Bcmath implementation: check first character, _(*21)

BigInteger neg()

Negates the number - GMP implementation: gmp_neg - Bcmath implementation: check first character, _(*22)

BigInteger binaryAnd(ConvertibleToBi $x)

Bitwise AND. - GMP implementation: gmp_and - Bcmath implementation: custom (toBytes + php string and), _(*23)

BigInteger binaryOr(ConvertibleToBi $x)

Bitwise OR - GMP implementation: gmp_or - Bcmath implementation: custom (toBytes + php string or), _(*24)

BigInteger binaryXor(ConvertibleToBi $x)

Bitwise XOR - GMP implementation: gmp_xor - Bcmath implementation: custom (toBytes + php string xor), _(*25)

BigInteger setbit($index, $bitOn = true)

Sets bit at given index - GMP implementation: gmp_setbit - Bcmath implementation: custom (toBits), _(*26)

bool testbit($index)

Tests if a bit at given index is set - GMP implementation: gmp_testbit - Bcmath implementation: custom (toBits), _(*27)

int scan0($start)

Scans for 0, and returns index of first found bit - GMP implementation: gmp_scan0 - Bcmath implementation: custom (toBits), _(*28)

int scan1($start)

Scans for 1, and returns index of first found bit - GMP implementation: gmp_scan1 - Bcmath implementation: custom (toBits), _(*29)

int cmp(ConvertibleToBi $x)

Compares numbers, returns <0, 0, >0 - GMP implementation: gmp_cmp - Bcmath implementation: bccomp, _(*30)

bool equals(ConvertibleToBi $x)

Checks if numbers are equal - GMP implementation: gmp_cmp - Bcmath implementation: bccomp, _(*31)

int sign()

Sign of number, returns -1, 0, 1 - GMP implementation: gmp_sign - Bcmath implementation: check first character, _(*32)

int toNumber()

Converts to number (use only with small 32/64bit numbers) - GMP implementation: gmp_intval - Bcmath implementation: intval, _(*33)

string toDec()

Converts to decimal string - GMP implementation: gmp_strval - Bcmath implementation: just the value, _(*34)

string toHex()

Converts to hex string - GMP implementation: gmp_strval - Bcmath implementation: toBytes + bin2hex, _(*35)

string toBytes

Converts to binary string - GMP implementation: gmp_strval + hex2bin - Bcmath implementation: custom (bcmod + bcdiv + bccomp), _(*36)

string toBits()

Converts to bits string (0 and 1 characters) - GMP implementation: gmp_strval - Bcmath implementation: toBytes + decbin, _(*37)

string toString(int $base = 10)

Converts to string using given base (supported bases 2-62, 256) - GMP implementation: all above toX functions, and for non standard gmp_strval - Bcmath implementation: all above toX functions, and for non standard bcmod + bcdiv + bccomp, _(*38)