+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Math</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="PHP Secure Communications Library" /><link rel="up" href="index.html" title="PHP Secure Communications Library" /><link rel="prev" href="intro.html" title="Chapter 1. Introduction" /><link rel="next" href="sym_crypt.html" title="Chapter 3. Symmetric-key Cryptography" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Math</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="sym_crypt.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="math"></a>Chapter 2. Math</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="math.html#math_biginteger">2.1. Math_BigInteger</a></span></dt><dd><dl><dt><span class="section"><a href="math.html#math_biginteger_dependencies">2.1.1. Dependencies</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_constructor">2.1.2. The constructor</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_output">2.1.3. toString(), toBytes(), toHex() and toBits()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_fourfunctions">2.1.4. add(), subtract(), multiply() and divide()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_modulo">2.1.5. powMod() and modInverse()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_gcd">2.1.6. gcd() and extendedGCD()</a></span></dt><dt><span class="section"><a href="math.html#math_abs">2.1.7. abs()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_compare">2.1.8. equals() and compare()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_precision">2.1.9. setPrecision()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_bitwise">2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_shifts">2.1.11. bitwise_rightShift() and bitwise_leftShift()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_rotates">2.1.12. bitwise_rightRotate() and bitwise_leftRotate()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_setrandom">2.1.13. setRandomGenerator()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_prime">2.1.14. isPrime()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_random">2.1.15. random() and randomPrime()</a></span></dt></dl></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="math_biginteger"></a>2.1. Math_BigInteger</h2></div></div></div><p>
- Implements an arbitrary precision integer arithmetic library. Uses gmp or bcmath, if available, and an
- internal implementation, otherwise. Here's an example:
- </p><pre class="programlisting"><?php
- include('Math/BigInteger.php');
-
- $a = new Math_BigInteger(2);
- $b = new Math_BigInteger(3);
-
- $c = $a->add($b);
-
- echo $c->toString(); // outputs 5
-?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_dependencies"></a>2.1.1. Dependencies</h3></div></div></div><p>
- If you're running PHP 5, Math_BigInteger's only dependancy is the PCRE extension (which is enabled by default). Math_BigInteger also works on PHP 4 if PHP/Compat/Function/array_fill.php and PHP/Compat/Function/bcpowmod.php are included.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_constructor"></a>2.1.2. The constructor</h3></div></div></div><p>
- The constructor takes two parameters. The first is the number and the second represents the base. Both
- are optional (if they're not provided, the Math_BigInteger object will assume a value of 0).
- </p><p>
- The supported bases are base-2, base-10 (default), base-16, and base-256. To set $a, in the
- above example, to 2, using base-2, we'd do <code class="code">new Math_BigInteger('10', 2)</code>. To do it using
- base-16, you could do <code class="code">new Math_BigInteger('2', 16)</code> or <code class="code">new Math_BigInteger('0x2', 16)</code>.
- To set it to 2 using base-256, you'd do <code class="code">new Math_BigInteger(chr(2), 256)</code>.
- </p><p>
- If the base is negative (eg. -256), two's compliment will be used. Thus, <code class="code">new Math_BigInteger(chr(0xFF), -256)</code>
- is equal to -1, as is <code class="code">new Math_BigInteger('0xFFFFFFFF', -16)</code> and <code class="code">new Math_BigInteger('11', -2)</code>.
- Basically, if the leading bit is 1, the number is assumed to be negative.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_output"></a>2.1.3. toString(), toBytes(), toHex() and toBits()</h3></div></div></div><p>
- <code class="code">toString()</code> returns the base-10 form of a number. <code class="code">toBytes()</code> returns the base-256
- form of a number, <code class="code">toHex()</code> returns the base-16 form, and <code class="code">toBits()</code> the base-2 form.
- <code class="code">toBytes()</code>, <code class="code">toHex()</code>, and <code class="code">toBits()</code> also take an optional parameter which,
- if set, will return the two's compliment of a number. So if, for example, $a is equal to -1,
- <code class="code">toBytes(true)</code> will return <code class="code">chr(0xFF)</code>.
- </p><p>
- On PHP 5, <code class="code">toString()</code> is called automatically when used in a string context via the
- <a class="ulink" href="http://php.net/language.oop5.magic#language.oop5.magic.tostring" target="_top">__toString() magic method</a>.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_fourfunctions"></a>2.1.4. add(), subtract(), multiply() and divide()</h3></div></div></div><p>
- <code class="code">subtract()</code> and <code class="code">multiply()</code> operate similarly to <code class="code">add()</code>. <code class="code">divide()</code>,
- however, does not. Namely, it 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:
- </p><pre class="programlisting"><?php
- include('Math/BigInteger.php');
-
- $a = new Math_BigInteger('10');
- $b = new Math_BigInteger('20');
-
- list($quotient, $remainder) = $a->divide($b);
-
- echo $quotient->toString(); // outputs 0
- echo "\r\n";
- echo $remainder->toString(); // outputs 10
-?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_modulo"></a>2.1.5. powMod() and modInverse()</h3></div></div></div><p>
- Examples of each follow:
- </p><pre class="programlisting"><?php
- include('Math/BigInteger.php');
-
- $a = new Math_BigInteger('10');
- $b = new Math_BigInteger('20');
- $c = new Math_BigInteger('30');
-
- $c = $a->powMod($b, $c);
-
- echo $c->toString(); // outputs 10
-?></pre><pre class="programlisting"><?php
- include('Math/BigInteger.php');
-
- $a = new Math_BigInteger(30);
- $b = new Math_BigInteger(17);
-
- $c = $a->modInverse($b);
-
- echo $c->toString(); // outputs 4
-?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_gcd"></a>2.1.6. gcd() and extendedGCD()</h3></div></div></div><p>
- <code class="code">extendedGCD()</code> returns an array containing three Math_BigInteger values indexed with x, y,
- and gcd. x and y represent Bézout's identity. <code class="code">gcd()</code> returns a Math_BigInteger value
- equal to the gcd. An example of each follows:
- </p><pre class="programlisting"><?php
-include('Math/BigInteger.php');
-
-$a = new Math_BigInteger(693);
-$b = new Math_BigInteger(609);
-
-extract($a->extendedGCD($b));
-$c = $a->gcd($b);
-
-echo $gcd->toString() . "\r\n"; // outputs 21
-echo $c->toString() . "\r\n"; // outputs 21
-echo $a->toString() * $x->toString() + $b->toString() * $y->toString(); // outputs 21
-?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_abs"></a>2.1.7. abs()</h3></div></div></div><p>
- <code class="code">$x->abs()</code> returns the absolute value of <code class="code">$x</code>.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_compare"></a>2.1.8. equals() and compare()</h3></div></div></div><p>
- <code class="code">$x->equals($y)</code> returns true or false depending on whether or not <code class="code">$x</code> and
- <code class="code">$y</code> are equal.
- </p><p>
- <code class="code">$x->compare($y)</code> returns 1 if $x > $y, 0 if $x == $y, and -1 if $x < $y. The reason for this
- is demonstrated thusly:
- </p><pre class="programlisting">$x > $y: $x->compare($y) > 0
-$x < $y: $x->compare($y) < 0
-$x == $y: $x->compare($y) == 0
-$x >= $y: $x->compare($y) >= 0
-$x <= $y: $x->compare($y) <= 0</pre><p>
- As a consequence of this, <code class="code">!$x->compare($y)</code> does not mean <code class="code">$x != $y</code> but rather
- <code class="code">$x == $y</code>.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_precision"></a>2.1.9. setPrecision()</h3></div></div></div><p>
- Some bitwise operations give different results depending on the precision being used. Examples include
- left shift, not, and rotates, as discussed for <a class="link" href="math.html#math_biginteger_bitwise" title="2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()">bitwise_not()</a>.
- This function lets you control the precision.
- </p><p>
- Whenever a new Math_BigInteger object is created it's precision is set to the same precision as the
- calling object. In other words, if you do <code class="code">$b = $a->bitwise_not()</code> then <code class="code">$b</code> will
- have the same precision as <code class="code">$a</code>.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_bitwise"></a>2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()</h3></div></div></div><p>
- <code class="code">bitwise_and()</code>, <code class="code">bitwise_or()</code> and <code class="code">bitwise_xor()</code> operate similar to
- <code class="code">add()</code>. <code class="code">bitwise_not()</code> is a bit more complicated. To elaborate, if the
- precision (see <a class="link" href="math.html#math_biginteger_precision" title="2.1.9. setPrecision()">setPrecision</a>) is arbitrary,
- <code class="code">$x->bitwise_not()</code> will always yield a smaller value since the most significant bit is
- assumed to have a value of one. With fixed precision, however, the leading bit can be anything.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_shifts"></a>2.1.11. bitwise_rightShift() and bitwise_leftShift()</h3></div></div></div><p>
- <code class="code">$a->bitwise_rightShift($shift)</code> shifts $a by $shift bits, effectively dividing by 2**$shift.
- <code class="code">$a->bitwise_leftShift($shift)</code> shifts $a by $shift bits, effectively multiplying by 2**$shift.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_rotates"></a>2.1.12. bitwise_rightRotate() and bitwise_leftRotate()</h3></div></div></div><p>
- <code class="code">$a->bitwise_rightRotate($shift)</code> and <code class="code">$a->bitwise_leftRotate($shift)</code> are
- demonstrated thusly:
- </p><pre class="programlisting"><?php
-include('Math/BigInteger.php');
-
-$a = new Math_BigInteger('00111000', 2);
-$a->setPrecision(8);
-$b = $a->bitwise_leftRotate(2);
-echo $b->toBits(); // returns 11100000
-
-echo "\r\n";
-
-$a = new Math_BigInteger('00111000', 2);
-$b = $a->bitwise_leftRotate(2);
-echo $b->toBits(); // returns 100011
-?></pre><p>
- Just as with <a class="link" href="math.html#math_biginteger_bitwise" title="2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()">bitwise_not()</a>, these operations are
- precision dependant.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_setrandom"></a>2.1.13. setRandomGenerator()</h3></div></div></div><p>
- Sets the random generator. To set it to <code class="code">mt_rand()</code> (which is what it is by default), call
- <code class="code">$x->setRandomGenerator('mt_rand')</code>.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_prime"></a>2.1.14. isPrime()</h3></div></div></div><p>
- Returns true if a number is prime and false if it isn't.
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_random"></a>2.1.15. random() and randomPrime()</h3></div></div></div><p>
- <code class="code">random($min, $max)</code> generates a random number between <code class="code">$min</code> and <code class="code">$max</code>.
- <code class="code">randomPrime($min, $max)</code> generates a random prime number between <code class="code">$min</code> and <code class="code">$max</code>.
- If no prime number exists between <code class="code">$min</code> and <code class="code">$max</code> false is returned.
- </p><p>
- <code class="code">randomPrime()</code> has an optional third parameter, as well - $timeout. Generating prime numbers
- is a particurarly expensive operation and although in certain environments even 512-bit primes can be
- generated in a less than a second it can take other environments upwards of around a minute if not more.
- </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="sym_crypt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Symmetric-key Cryptography</td></tr></table></div></body></html>
projects / friendica.git / blobdiff