mingw/html/lib/Math/BigInt/Calc.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Math::BigInt::Calc - Pure Perl module to support Math::BigInt</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Math::BigInt::Calc - Pure Perl module to support Math::BigInt</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#storage">STORAGE</a></li>
  26         <li><a href="#methods">METHODS</a></li>
  27         <li><a href="#wrap_your_own">WRAP YOUR OWN</a></li>
  28         <li><a href="#license">LICENSE</a></li>
  29         <li><a href="#authors">AUTHORS</a></li>
  30         <li><a href="#see_also">SEE ALSO</a></li>
  31 </ul>
  32 <!-- INDEX END -->
  33
  34 <hr />
  35 <p>
  36 </p>
  37 <h1><a name="name">NAME</a></h1>
  38 <p>Math::BigInt::Calc - Pure Perl module to support Math::BigInt</p>
  39 <p>
  40 </p>
  41 <hr />
  42 <h1><a name="synopsis">SYNOPSIS</a></h1>
  43 <p>Provides support for big integer calculations. Not intended to be used by other
  44 modules. Other modules which sport the same functions can also be used to support
  45 Math::BigInt, like Math::BigInt::GMP or Math::BigInt::Pari.</p>
  46 <p>
  47 </p>
  48 <hr />
  49 <h1><a name="description">DESCRIPTION</a></h1>
  50 <p>In order to allow for multiple big integer libraries, Math::BigInt was
  51 rewritten to use library modules for core math routines. Any module which
  52 follows the same API as this can be used instead by using the following:</p>
  53 <pre>
  54         use Math::BigInt lib =&gt; 'libname';</pre>
  55 <p>'libname' is either the long name ('Math::BigInt::Pari'), or only the short
  56 version like 'Pari'.</p>
  57 <p>
  58 </p>
  59 <hr />
  60 <h1><a name="storage">STORAGE</a></h1>
  61 <p>
  62 </p>
  63 <hr />
  64 <h1><a name="methods">METHODS</a></h1>
  65 <p>The following functions MUST be defined in order to support the use by
  66 Math::BigInt v1.70 or later:</p>
  67 <pre>
  68         api_version()   return API version, minimum 1 for v1.70
  69         _new(string)    return ref to new object from ref to decimal string
  70         _zero()         return a new object with value 0
  71         _one()          return a new object with value 1
  72         _two()          return a new object with value 2
  73         _ten()          return a new object with value 10</pre>
  74 <pre>
  75         _str(obj)       return ref to a string representing the object
  76         _num(obj)       returns a Perl integer/floating point number
  77                         NOTE: because of Perl numeric notation defaults,
  78                         the _num'ified obj may lose accuracy due to
  79                         machine-dependend floating point size limitations
  80
  81         _add(obj,obj)   Simple addition of two objects
  82         _mul(obj,obj)   Multiplication of two objects
  83         _div(obj,obj)   Division of the 1st object by the 2nd
  84                         In list context, returns (result,remainder).
  85                         NOTE: this is integer math, so no
  86                         fractional part will be returned.
  87                         The second operand will be not be 0, so no need to
  88                         check for that.
  89         _sub(obj,obj)   Simple subtraction of 1 object from another
  90                         a third, optional parameter indicates that the params
  91                         are swapped. In this case, the first param needs to
  92                         be preserved, while you can destroy the second.
  93                         sub (x,y,1) =&gt; return x - y and keep x intact!
  94         _dec(obj)       decrement object by one (input is garant. to be &gt; 0)
  95         _inc(obj)       increment object by one</pre>
  96 <pre>
  97         _acmp(obj,obj)  &lt;=&gt; operator for objects (return -1, 0 or 1)</pre>
  98 <pre>
  99         _len(obj)       returns count of the decimal digits of the object
 100         _digit(obj,n)   returns the n'th decimal digit of object</pre>
 101 <pre>
 102         _is_one(obj)    return true if argument is 1
 103         _is_two(obj)    return true if argument is 2
 104         _is_ten(obj)    return true if argument is 10
 105         _is_zero(obj)   return true if argument is 0
 106         _is_even(obj)   return true if argument is even (0,2,4,6..)
 107         _is_odd(obj)    return true if argument is odd (1,3,5,7..)</pre>
 108 <pre>
 109         _copy           return a ref to a true copy of the object</pre>
 110 <pre>
 111         _check(obj)     check whether internal representation is still intact
 112                         return 0 for ok, otherwise error message as string</pre>
 113 <pre>
 114         _from_hex(str)  return ref to new object from ref to hexadecimal string
 115         _from_bin(str)  return ref to new object from ref to binary string
 116
 117         _as_hex(str)    return string containing the value as
 118                         unsigned hex string, with the '0x' prepended.
 119                         Leading zeros must be stripped.
 120         _as_bin(str)    Like as_hex, only as binary string containing only
 121                         zeros and ones. Leading zeros must be stripped and a
 122                         '0b' must be prepended.
 123
 124         _rsft(obj,N,B)  shift object in base B by N 'digits' right
 125         _lsft(obj,N,B)  shift object in base B by N 'digits' left
 126
 127         _xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
 128                         Note: XOR, AND and OR pad with zeros if size mismatches
 129         _and(obj1,obj2) AND (bit-wise) object 1 with object 2
 130         _or(obj1,obj2)  OR (bit-wise) object 1 with object 2</pre>
 131 <pre>
 132         _mod(obj,obj)   Return remainder of div of the 1st by the 2nd object
 133         _sqrt(obj)      return the square root of object (truncated to int)
 134         _root(obj)      return the n'th (n &gt;= 3) root of obj (truncated to int)
 135         _fac(obj)       return factorial of object 1 (1*2*3*4..)
 136         _pow(obj,obj)   return object 1 to the power of object 2
 137                         return undef for NaN
 138         _zeros(obj)     return number of trailing decimal zeros
 139         _modinv         return inverse modulus
 140         _modpow         return modulus of power ($x ** $y) % $z
 141         _log_int(X,N)   calculate integer log() of X in base N
 142                         X &gt;= 0, N &gt;= 0 (return undef for NaN)
 143                         returns (RESULT, EXACT) where EXACT is:
 144                          1     : result is exactly RESULT
 145                          0     : result was truncated to RESULT
 146                          undef : unknown whether result is exactly RESULT
 147         _gcd(obj,obj)   return Greatest Common Divisor of two objects</pre>
 148 <p>The following functions are optional, and can be defined if the underlying lib
 149 has a fast way to do them. If undefined, Math::BigInt will use pure Perl (hence
 150 slow) fallback routines to emulate these:
 151 </p>
 152 <pre>
 153
 154         _signed_or
 155         _signed_and
 156         _signed_xor</pre>
 157 <p>Input strings come in as unsigned but with prefix (i.e. as '123', '0xabc'
 158 or '0b1101').</p>
 159 <p>So the library needs only to deal with unsigned big integers. Testing of input
 160 parameter validity is done by the caller, so you need not worry about
 161 underflow (f.i. in <code>_sub()</code>, <code>_dec()</code>) nor about division by zero or similar
 162 cases.</p>
 163 <p>The first parameter can be modified, that includes the possibility that you
 164 return a reference to a completely different object instead. Although keeping
 165 the reference and just changing it's contents is prefered over creating and
 166 returning a different reference.</p>
 167 <p>Return values are always references to objects, strings, or true/false for
 168 comparisation routines.</p>
 169 <p>
 170 </p>
 171 <hr />
 172 <h1><a name="wrap_your_own">WRAP YOUR OWN</a></h1>
 173 <p>If you want to port your own favourite c-lib for big numbers to the
 174 Math::BigInt interface, you can take any of the already existing modules as
 175 a rough guideline. You should really wrap up the latest BigInt and BigFloat
 176 testsuites with your module, and replace in them any of the following:</p>
 177 <pre>
 178         use Math::BigInt;</pre>
 179 <p>by this:</p>
 180 <pre>
 181         use Math::BigInt lib =&gt; 'yourlib';
 182
 183 </pre>
 184 <p>This way you ensure that your library really works 100% within Math::BigInt.
 185
 186 </p>
 187 <p>
 188 </p>
 189 <hr />
 190 <h1><a name="license_this_program_is_free_software__you_may_redistribute_it_and_or_modify_it_under_the_same_terms_as_perl_itself_">LICENSE
 191
 192 This program is free software; you may redistribute it and/or modify it under
 193 the same terms as Perl itself.</a></h1>
 194 <p>
 195 </p>
 196 <hr />
 197 <h1><a name="authors">AUTHORS</a></h1>
 198 <p>Original math code by Mark Biggar, rewritten by Tels <a href="http://bloodgate.com/">http://bloodgate.com/</a>
 199 in late 2000.
 200 Seperated from BigInt and shaped API with the help of John Peacock.
 201
 202 </p>
 203 <p>Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2005.
 204
 205 </p>
 206 <p>
 207 </p>
 208 <hr />
 209 <h1><a name="see_also">SEE ALSO</a></h1>
 210 <p><a href="file://C|\msysgit\mingw\html/lib/Math/BigInt.html">the Math::BigInt manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Math/BigFloat.html">the Math::BigFloat manpage</a>, <a href="file://C|\msysgit\mingw\html/Math/BigInt/BitVect.html">the Math::BigInt::BitVect manpage</a>,
 211 <a href="file://C|\msysgit\mingw\html/Math/BigInt/GMP.html">the Math::BigInt::GMP manpage</a>, <a href="file://C|\msysgit\mingw\html/Math/BigInt/FastCalc.html">the Math::BigInt::FastCalc manpage</a> and <a href="file://C|\msysgit\mingw\html/Math/BigInt/Pari.html">the Math::BigInt::Pari manpage</a>.
 212
 213 </p>
 214 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 215 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 216 <big><strong><span class="block">&nbsp;Math::BigInt::Calc - Pure Perl module to support Math::BigInt</span></strong></big>
 217 </td></tr>
 218 </table>
 219
 220 </body>
 221
 222 </html>