newsupernova/vendor/zendframework/zend-math/doc/book/zend.math.introduction.md

Introduction to Zend\Math

Zend\Math namespace provides general mathematical functions. So far the supported functionalities are:

• Zend\Math\Rand, a random number generator;
• Zend\Math\BigInteger, a library to manage big integers.

We expect to add more functionalities in the future.

Random number generator

Zend\Math\Rand implements a random number generator that is able to generate random numbers for general purpose usage and for cryptographic scopes. To generate good random numbers this component uses different approaches. If PHP 7 is running we used the cryptographically secure pseudo-random functions random_bytes and random_int, otherwise we use the Mcrypt extension or /dev/urandom source. If you don't have a secure random source in your environment the component will use the library ircmaxell/RandomLib with a medium strength generator.

The Zend\Math\Rand class offers the following methods to generate random values:

• getBytes($length, $strong = false) to generate a random set of $length bytes;
• getBoolean($strong = false) to generate a random boolean value (true or false);
• getInteger($min, $max, $strong = false) to generate a random integer between $min and $max;
• getFloat($strong = false) to generate a random float number between 0 and 1;
• getString($length, $charlist = null, $strong = false) to generate a random string of $length characters using the alphabet $charlist (if not provided the default alphabet is the Base64).

In all these methods the parameter $strong specify the usage of a strong random number generator. We suggest to set the $strong to true if you need to generate random number for cryptographic and security implementation.

If $strong is set to true and you try to generate random values in a PHP environment without a secure pseudo-random source the component will throw an Exception.

Below we reported an example on how to generate random data using Zend\Math\Rand.

use Zend\Math\Rand;

$bytes = Rand::getBytes(32, true);
printf("Random bytes (in Base64): %s\n", base64_encode($bytes));

$boolean = Rand::getBoolean();
printf("Random boolean: %s\n", $boolean ? 'true' : 'false');

$integer = Rand::getInteger(0,1000);
printf("Random integer in [0-1000]: %d\n", $integer);

$float = Rand::getFloat();
printf("Random float in [0-1): %f\n", $float);

$string = Rand::getString(32, 'abcdefghijklmnopqrstuvwxyz', true);
printf("Random string in latin alphabet: %s\n", $string);

Big integers

Zend\Math\BigInteger\BigInteger offers a class to manage arbitrary length integer. PHP supports integer numbers with a maximum value of PHP_INT_MAX. If you need to manage integers bigger than PHP_INT_MAX you have to use external libraries or PHP extensions like GMP or BC Math.

Zend\Math\BigInteger\BigInteger is able to manage big integers using the GMP or the BC Math extensions as adapters.

The mathematical functions implemented in Zend\Math\BigInteger\BigInteger are:

• add($leftOperand, $rightOperand), add two big integers;
• sub($leftOperand, $rightOperand), subtract two big integers;
• mul($leftOperand, $rightOperand), multiply two big integers;
• div($leftOperand, $rightOperand), divide two big integers (this method returns only integer part of result);
• pow($operand, $exp), raise a big integers to another;
• sqrt($operand), get the square root of a big integer;
• abs($operand), get the absolute value of a big integer;
• mod($leftOperand, $modulus), get modulus of a big integer;
• powmod($leftOperand, $rightOperand, $modulus), raise a big integer to another, reduced by a specified modulus;
• comp($leftOperand, $rightOperand), compare two big integers, returns < 0 if leftOperand is less than rightOperand; > 0 if leftOperand is greater than rightOperand, and 0 if they are equal;
• intToBin($int, $twoc = false), convert big integer into it's binary number representation;
• binToInt($bytes, $twoc = false), convert binary number into big integer;
• baseConvert($operand, $fromBase, $toBase = 10), convert a number between arbitrary bases;

Below is reported an example using the BC Math adapter to calculate the sum of two integer random numbers with 100 digits.

use Zend\Math\BigInteger\BigInteger;
use Zend\Math\Rand;

$bigInt = BigInteger::factory('bcmath');

$x = Rand::getString(100,'0123456789');
$y = Rand::getString(100,'0123456789');

$sum = $bigInt->add($x, $y);
$len = strlen($sum);

printf("%{$len}s +\n%{$len}s =\n%s\n%s\n", $x, $y, str_repeat('-', $len), $sum);

As you can see in the code the big integers are managed using strings. Even the result of the sum is represented as a string.

Below is reported another example using the BC Math adapter to generate the binary representation of a negative big integer of 100 digits.

use Zend\Math\BigInteger\BigInteger;
use Zend\Math\Rand;

$bigInt = BigInteger::factory('bcmath');

$digit = 100;
$x = '-' . Rand::getString($digit,'0123456789');

$byte = $bigInt->intToBin($x);

printf("The binary representation of the big integer with $digit digit:\n%s\nis (in Base64 format):
%s\n",
       $x, base64_encode($byte));
printf("Length in bytes: %d\n", strlen($byte));

$byte = $bigInt->intToBin($x, true);

printf("The two's complement binary representation of the big integer with $digit digit:\n%s\nis (in
Base64 format): %s\n",
       $x, base64_encode($byte));
printf("Length in bytes: %d\n", strlen($byte));

We generated the binary representation of the big integer number using the default binary format and the two's complement representation (specified with the true parameter in the intToBin function).