Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

157 lines
17 KiB

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
  3. <html xmlns=""><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>
  4. Implements an arbitrary precision integer arithmetic library. Uses gmp or bcmath, if available, and an
  5. internal implementation, otherwise. Here's an example:
  6. </p><pre class="programlisting">&lt;?php
  7. include('Math/BigInteger.php');
  8. $a = new Math_BigInteger(2);
  9. $b = new Math_BigInteger(3);
  10. $c = $a-&gt;add($b);
  11. echo $c-&gt;toString(); // outputs 5
  12. ?&gt;</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>
  13. 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.
  14. </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>
  15. The constructor takes two parameters. The first is the number and the second represents the base. Both
  16. are optional (if they're not provided, the Math_BigInteger object will assume a value of 0).
  17. </p><p>
  18. The supported bases are base-2, base-10 (default), base-16, and base-256. To set $a, in the
  19. above example, to 2, using base-2, we'd do <code class="code">new Math_BigInteger('10', 2)</code>. To do it using
  20. base-16, you could do <code class="code">new Math_BigInteger('2', 16)</code> or <code class="code">new Math_BigInteger('0x2', 16)</code>.
  21. To set it to 2 using base-256, you'd do <code class="code">new Math_BigInteger(chr(2), 256)</code>.
  22. </p><p>
  23. If the base is negative (eg. -256), two's compliment will be used. Thus, <code class="code">new Math_BigInteger(chr(0xFF), -256)</code>
  24. 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>.
  25. Basically, if the leading bit is 1, the number is assumed to be negative.
  26. </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>
  27. <code class="code">toString()</code> returns the base-10 form of a number. <code class="code">toBytes()</code> returns the base-256
  28. form of a number, <code class="code">toHex()</code> returns the base-16 form, and <code class="code">toBits()</code> the base-2 form.
  29. <code class="code">toBytes()</code>, <code class="code">toHex()</code>, and <code class="code">toBits()</code> also take an optional parameter which,
  30. if set, will return the two's compliment of a number. So if, for example, $a is equal to -1,
  31. <code class="code">toBytes(true)</code> will return <code class="code">chr(0xFF)</code>.
  32. </p><p>
  33. On PHP 5, <code class="code">toString()</code> is called automatically when used in a string context via the
  34. <a class="ulink" href="" target="_top">__toString() magic method</a>.
  35. </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>
  36. <code class="code">subtract()</code> and <code class="code">multiply()</code> operate similarly to <code class="code">add()</code>. <code class="code">divide()</code>,
  37. however, does not. Namely, it returns an array whose first element contains the quotient and whose
  38. second element contains the "common residue". If the remainder would be positive, the "common residue"
  39. and the remainder are the same. If the remainder would be negative, the "common residue" is equal to
  40. the sum of the remainder and the divisor (basically, the "common residue" is the first positive modulo).
  41. Here's an example:
  42. </p><pre class="programlisting">&lt;?php
  43. include('Math/BigInteger.php');
  44. $a = new Math_BigInteger('10');
  45. $b = new Math_BigInteger('20');
  46. list($quotient, $remainder) = $a-&gt;divide($b);
  47. echo $quotient-&gt;toString(); // outputs 0
  48. echo "\r\n";
  49. echo $remainder-&gt;toString(); // outputs 10
  50. ?&gt;</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>
  51. Examples of each follow:
  52. </p><pre class="programlisting">&lt;?php
  53. include('Math/BigInteger.php');
  54. $a = new Math_BigInteger('10');
  55. $b = new Math_BigInteger('20');
  56. $c = new Math_BigInteger('30');
  57. $c = $a-&gt;powMod($b, $c);
  58. echo $c-&gt;toString(); // outputs 10
  59. ?&gt;</pre><pre class="programlisting">&lt;?php
  60. include('Math/BigInteger.php');
  61. $a = new Math_BigInteger(30);
  62. $b = new Math_BigInteger(17);
  63. $c = $a-&gt;modInverse($b);
  64. echo $c-&gt;toString(); // outputs 4
  65. ?&gt;</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>
  66. <code class="code">extendedGCD()</code> returns an array containing three Math_BigInteger values indexed with x, y,
  67. and gcd. x and y represent Bézout's identity. <code class="code">gcd()</code> returns a Math_BigInteger value
  68. equal to the gcd. An example of each follows:
  69. </p><pre class="programlisting">&lt;?php
  70. include('Math/BigInteger.php');
  71. $a = new Math_BigInteger(693);
  72. $b = new Math_BigInteger(609);
  73. extract($a-&gt;extendedGCD($b));
  74. $c = $a-&gt;gcd($b);
  75. echo $gcd-&gt;toString() . "\r\n"; // outputs 21
  76. echo $c-&gt;toString() . "\r\n"; // outputs 21
  77. echo $a-&gt;toString() * $x-&gt;toString() + $b-&gt;toString() * $y-&gt;toString(); // outputs 21
  78. ?&gt;</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>
  79. <code class="code">$x-&gt;abs()</code> returns the absolute value of <code class="code">$x</code>.
  80. </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>
  81. <code class="code">$x-&gt;equals($y)</code> returns true or false depending on whether or not <code class="code">$x</code> and
  82. <code class="code">$y</code> are equal.
  83. </p><p>
  84. <code class="code">$x-&gt;compare($y)</code> returns 1 if $x &gt; $y, 0 if $x == $y, and -1 if $x &lt; $y. The reason for this
  85. is demonstrated thusly:
  86. </p><pre class="programlisting">$x &gt; $y: $x-&gt;compare($y) &gt; 0
  87. $x &lt; $y: $x-&gt;compare($y) &lt; 0
  88. $x == $y: $x-&gt;compare($y) == 0
  89. $x &gt;= $y: $x-&gt;compare($y) &gt;= 0
  90. $x &lt;= $y: $x-&gt;compare($y) &lt;= 0</pre><p>
  91. As a consequence of this, <code class="code">!$x-&gt;compare($y)</code> does not mean <code class="code">$x != $y</code> but rather
  92. <code class="code">$x == $y</code>.
  93. </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>
  94. Some bitwise operations give different results depending on the precision being used. Examples include
  95. 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>.
  96. This function lets you control the precision.
  97. </p><p>
  98. Whenever a new Math_BigInteger object is created it's precision is set to the same precision as the
  99. calling object. In other words, if you do <code class="code">$b = $a-&gt;bitwise_not()</code> then <code class="code">$b</code> will
  100. have the same precision as <code class="code">$a</code>.
  101. </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>
  102. <code class="code">bitwise_and()</code>, <code class="code">bitwise_or()</code> and <code class="code">bitwise_xor()</code> operate similar to
  103. <code class="code">add()</code>. <code class="code">bitwise_not()</code> is a bit more complicated. To elaborate, if the
  104. precision (see <a class="link" href="math.html#math_biginteger_precision" title="2.1.9. setPrecision()">setPrecision</a>) is arbitrary,
  105. <code class="code">$x-&gt;bitwise_not()</code> will always yield a smaller value since the most significant bit is
  106. assumed to have a value of one. With fixed precision, however, the leading bit can be anything.
  107. </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>
  108. <code class="code">$a-&gt;bitwise_rightShift($shift)</code> shifts $a by $shift bits, effectively dividing by 2**$shift.
  109. <code class="code">$a-&gt;bitwise_leftShift($shift)</code> shifts $a by $shift bits, effectively multiplying by 2**$shift.
  110. </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>
  111. <code class="code">$a-&gt;bitwise_rightRotate($shift)</code> and <code class="code">$a-&gt;bitwise_leftRotate($shift)</code> are
  112. demonstrated thusly:
  113. </p><pre class="programlisting">&lt;?php
  114. include('Math/BigInteger.php');
  115. $a = new Math_BigInteger('00111000', 2);
  116. $a-&gt;setPrecision(8);
  117. $b = $a-&gt;bitwise_leftRotate(2);
  118. echo $b-&gt;toBits(); // returns 11100000
  119. echo "\r\n";
  120. $a = new Math_BigInteger('00111000', 2);
  121. $b = $a-&gt;bitwise_leftRotate(2);
  122. echo $b-&gt;toBits(); // returns 100011
  123. ?&gt;</pre><p>
  124. 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
  125. precision dependant.
  126. </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>
  127. Sets the random generator. To set it to <code class="code">mt_rand()</code> (which is what it is by default), call
  128. <code class="code">$x-&gt;setRandomGenerator('mt_rand')</code>.
  129. </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>
  130. Returns true if a number is prime and false if it isn't.
  131. </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>
  132. <code class="code">random($min, $max)</code> generates a random number between <code class="code">$min</code> and <code class="code">$max</code>.
  133. <code class="code">randomPrime($min, $max)</code> generates a random prime number between <code class="code">$min</code> and <code class="code">$max</code>.
  134. If no prime number exists between <code class="code">$min</code> and <code class="code">$max</code> false is returned.
  135. </p><p>
  136. <code class="code">randomPrime()</code> has an optional third parameter, as well - $timeout. Generating prime numbers
  137. is a particurarly expensive operation and although in certain environments even 512-bit primes can be
  138. generated in a less than a second it can take other environments upwards of around a minute if not more.
  139. </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>