mingw/html/lib/bignum.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>bignum - Transparent BigNumber support for Perl</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;bignum - Transparent BigNumber support for Perl</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         <ul>
  26
  27                 <li><a href="#options">Options</a></li>
  28                 <li><a href="#methods">Methods</a></li>
  29                 <li><a href="#caveat">Caveat</a></li>
  30                 <li><a href="#math_library">MATH LIBRARY</a></li>
  31                 <li><a href="#internal_format">INTERNAL FORMAT</a></li>
  32                 <li><a href="#sign">SIGN</a></li>
  33         </ul>
  34
  35         <li><a href="#modules_used">MODULES USED</a></li>
  36         <li><a href="#examples">EXAMPLES</a></li>
  37         <li><a href="#license">LICENSE</a></li>
  38         <li><a href="#see_also">SEE ALSO</a></li>
  39         <li><a href="#authors">AUTHORS</a></li>
  40 </ul>
  41 <!-- INDEX END -->
  42
  43 <hr />
  44 <p>
  45 </p>
  46 <h1><a name="name">NAME</a></h1>
  47 <p>bignum - Transparent BigNumber support for Perl</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="synopsis">SYNOPSIS</a></h1>
  52 <pre>
  53   use bignum;</pre>
  54 <pre>
  55   $x = 2 + 4.5,&quot;\n&quot;;                    # BigFloat 6.5
  56   print 2 ** 512 * 0.1,&quot;\n&quot;;            # really is what you think it is
  57   print inf * inf,&quot;\n&quot;;                 # prints inf
  58   print NaN * 3,&quot;\n&quot;;                   # prints NaN</pre>
  59 <p>
  60 </p>
  61 <hr />
  62 <h1><a name="description">DESCRIPTION</a></h1>
  63 <p>All operators (including basic math operations) are overloaded. Integer and
  64 floating-point constants are created as proper BigInts or BigFloats,
  65 respectively.</p>
  66 <p>If you do</p>
  67 <pre>
  68         use bignum;</pre>
  69 <p>at the top of your script, Math::BigFloat and Math::BigInt will be loaded
  70 and any constant number will be converted to an object (Math::BigFloat for
  71 floats like 3.1415 and Math::BigInt for integers like 1234).</p>
  72 <p>So, the following line:</p>
  73 <pre>
  74         $x = 1234;</pre>
  75 <p>creates actually a Math::BigInt and stores a reference to in $x.
  76 This happens transparently and behind your back, so to speak.</p>
  77 <p>You can see this with the following:</p>
  78 <pre>
  79         perl -Mbignum -le 'print ref(1234)'</pre>
  80 <p>Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
  81 if it is installed since it is faster for some operations. It will be
  82 automatically upgraded to BigInt whenever neccessary:</p>
  83 <pre>
  84         perl -Mbignum -le 'print ref(2**255)'</pre>
  85 <p>This also means it is a bad idea to check for some specific package, since
  86 the actual contents of $x might be something unexpected. Due to the
  87 transparent way of bignum <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_ref"><code>ref()</code></a> should not be neccessary, anyway.</p>
  88 <p>Since Math::BigInt and BigFloat also overload the normal math operations,
  89 the following line will still work:</p>
  90 <pre>
  91         perl -Mbignum -le 'print ref(1234+1234)'</pre>
  92 <p>Since numbers are actually objects, you can call all the usual methods from
  93 BigInt/BigFloat on them. This even works to some extent on expressions:</p>
  94 <pre>
  95         perl -Mbignum -le '$x = 1234; print $x-&gt;bdec()'
  96         perl -Mbignum -le 'print 1234-&gt;binc();'
  97         perl -Mbignum -le 'print 1234-&gt;binc-&gt;badd(6);'
  98         perl -Mbignum -le 'print +(1234)-&gt;binc()'</pre>
  99 <p>(Note that print doesn't do what you expect if the expression starts with
 100 '(' hence the <code>+</code>)</p>
 101 <p>You can even chain the operations together as usual:</p>
 102 <pre>
 103         perl -Mbignum -le 'print 1234-&gt;binc-&gt;badd(6);'
 104         1241</pre>
 105 <p>Under bignum (or bigint or bigrat), Perl will ``upgrade'' the numbers
 106 appropriately. This means that:</p>
 107 <pre>
 108         perl -Mbignum -le 'print 1234+4.5'
 109         1238.5</pre>
 110 <p>will work correctly. These mixed cases don't do always work when using
 111 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
 112 scalars work.</p>
 113 <p>If you do want to work with large integers like under <code>use integer;</code>, try
 114 <code>use bigint;</code>:</p>
 115 <pre>
 116         perl -Mbigint -le 'print 1234.5+4.5'
 117         1238</pre>
 118 <p>There is also <code>use bigrat;</code> which gives you big rationals:</p>
 119 <pre>
 120         perl -Mbigrat -le 'print 1234+4.1'
 121         12381/10</pre>
 122 <p>The entire upgrading/downgrading is still experimental and might not work
 123 as you expect or may even have bugs.</p>
 124 <p>You might get errors like this:</p>
 125 <pre>
 126         Can't use an undefined value as an ARRAY reference at
 127         /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864</pre>
 128 <p>This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
 129 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
 130 report it so that we can fix it.</p>
 131 <p>You might consider using just Math::BigInt or Math::BigFloat, since they
 132 allow you finer control over what get's done in which module/space. For
 133 instance, simple loop counters will be Math::BigInts under <code>use bignum;</code> and
 134 this is slower than keeping them as Perl scalars:</p>
 135 <pre>
 136         perl -Mbignum -le 'for ($i = 0; $i &lt; 10; $i++) { print ref($i); }'</pre>
 137 <p>Please note the following does not work as expected (prints nothing), since
 138 overloading of '..' is not yet possible in Perl (as of v5.8.0):</p>
 139 <pre>
 140         perl -Mbignum -le 'for (1..2) { print ref($_); }'</pre>
 141 <p>
 142 </p>
 143 <h2><a name="options">Options</a></h2>
 144 <p>bignum recognizes some options that can be passed while loading it via use.
 145 The options can (currently) be either a single letter form, or the long form.
 146 The following options exist:</p>
 147 <dl>
 148 <dt><strong><a name="item_a_or_accuracy">a or accuracy</a></strong>
 149
 150 <dd>
 151 <p>This sets the accuracy for all math operations. The argument must be greater
 152 than or equal to zero. See Math::BigInt's <code>bround()</code> function for details.</p>
 153 </dd>
 154 <dd>
 155 <pre>
 156         perl -Mbignum=a,50 -le 'print sqrt(20)'</pre>
 157 </dd>
 158 </li>
 159 <dt><strong><a name="item_p_or_precision">p or precision</a></strong>
 160
 161 <dd>
 162 <p>This sets the precision for all math operations. The argument can be any
 163 integer. Negative values mean a fixed number of digits after the dot, while
 164 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
 165 integer. See Math::BigInt's <code>bfround()</code> function for details.</p>
 166 </dd>
 167 <dd>
 168 <pre>
 169         perl -Mbignum=p,-50 -le 'print sqrt(20)'</pre>
 170 </dd>
 171 </li>
 172 <dt><strong><a name="item_t_or_trace">t or trace</a></strong>
 173
 174 <dd>
 175 <p>This enables a trace mode and is primarily for debugging bignum or
 176 Math::BigInt/Math::BigFloat.</p>
 177 </dd>
 178 </li>
 179 <dt><strong><a name="item_l_or_lib">l or lib</a></strong>
 180
 181 <dd>
 182 <p>Load a different math lib, see <a href="#math_library">MATH LIBRARY</a>.</p>
 183 </dd>
 184 <dd>
 185 <pre>
 186         perl -Mbignum=l,GMP -e 'print 2 ** 512'</pre>
 187 </dd>
 188 <dd>
 189 <p>Currently there is no way to specify more than one library on the command
 190 line. This will be hopefully fixed soon ;)</p>
 191 </dd>
 192 </li>
 193 <dt><strong><a name="item_v_or_version">v or version</a></strong>
 194
 195 <dd>
 196 <p>This prints out the name and version of all modules used and then exits.</p>
 197 </dd>
 198 <dd>
 199 <pre>
 200         perl -Mbignum=v</pre>
 201 </dd>
 202 </li>
 203 </dl>
 204 <p>
 205 </p>
 206 <h2><a name="methods">Methods</a></h2>
 207 <p>Beside <code>import()</code> and <code>AUTOLOAD()</code> there are only a few other methods.</p>
 208 <p>Since all numbers are now objects, you can use all functions that are part of
 209 the BigInt or BigFloat API. It is wise to use only the <code>bxxx()</code> notation, and not
 210 the <code>fxxx()</code> notation, though. This makes it possible that the underlying object
 211 might morph into a different class than BigFloat.</p>
 212 <p>
 213 </p>
 214 <h2><a name="caveat">Caveat</a></h2>
 215 <p>But a warning is in order. When using the following to make a copy of a number,
 216 only a shallow copy will be made.</p>
 217 <pre>
 218         $x = 9; $y = $x;
 219         $x = $y = 7;</pre>
 220 <p>If you want to make a real copy, use the following:</p>
 221 <pre>
 222         $y = $x-&gt;copy();</pre>
 223 <p>Using the copy or the original with overloaded math is okay, e.g. the
 224 following work:</p>
 225 <pre>
 226         $x = 9; $y = $x;
 227         print $x + 1, &quot; &quot;, $y,&quot;\n&quot;;     # prints 10 9</pre>
 228 <p>but calling any method that modifies the number directly will result in
 229 <strong>both</strong> the original and the copy beeing destroyed:</p>
 230 <pre>
 231         $x = 9; $y = $x;
 232         print $x-&gt;badd(1), &quot; &quot;, $y,&quot;\n&quot;;        # prints 10 10</pre>
 233 <pre>
 234         $x = 9; $y = $x;
 235         print $x-&gt;binc(1), &quot; &quot;, $y,&quot;\n&quot;;        # prints 10 10</pre>
 236 <pre>
 237         $x = 9; $y = $x;
 238         print $x-&gt;bmul(2), &quot; &quot;, $y,&quot;\n&quot;;        # prints 18 18</pre>
 239 <p>Using methods that do not modify, but testthe contents works:</p>
 240 <pre>
 241         $x = 9; $y = $x;
 242         $z = 9 if $x-&gt;is_zero();                # works fine</pre>
 243 <p>See the documentation about the copy constructor and <code>=</code> in overload, as
 244 well as the documentation in BigInt for further details.</p>
 245 <dl>
 246 <dt><strong><a name="item_inf"><code>inf()</code></a></strong>
 247
 248 <dd>
 249 <p>A shortcut to return Math::BigInt-&gt;binf(). Usefull because Perl does not always
 250 handle bareword <a href="#item_inf"><code>inf</code></a> properly.</p>
 251 </dd>
 252 </li>
 253 <dt><strong><a name="item_nan"><code>NaN()</code></a></strong>
 254
 255 <dd>
 256 <p>A shortcut to return Math::BigInt-&gt;bnan(). Usefull because Perl does not always
 257 handle bareword <a href="#item_nan"><code>NaN</code></a> properly.</p>
 258 </dd>
 259 </li>
 260 <dt><strong><a name="item_upgrade"><code>upgrade()</code></a></strong>
 261
 262 <dd>
 263 <p>Return the class that numbers are upgraded to, is in fact returning
 264 <code>$Math::BigInt::upgrade</code>.</p>
 265 </dd>
 266 </li>
 267 </dl>
 268 <p>
 269 </p>
 270 <h2><a name="math_library">MATH LIBRARY</a></h2>
 271 <p>Math with the numbers is done (by default) by a module called
 272 Math::BigInt::Calc. This is equivalent to saying:</p>
 273 <pre>
 274         use bignum lib =&gt; 'Calc';</pre>
 275 <p>You can change this by using:</p>
 276 <pre>
 277         use bignum lib =&gt; 'BitVect';</pre>
 278 <p>The following would first try to find Math::BigInt::Foo, then
 279 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:</p>
 280 <pre>
 281         use bignum lib =&gt; 'Foo,Math::BigInt::Bar';</pre>
 282 <p>Please see respective module documentation for further details.</p>
 283 <p>
 284 </p>
 285 <h2><a name="internal_format">INTERNAL FORMAT</a></h2>
 286 <p>The numbers are stored as objects, and their internals might change at anytime,
 287 especially between math operations. The objects also might belong to different
 288 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
 289 with normal scalars is not extraordinary, but normal and expected.</p>
 290 <p>You should not depend on the internal format, all accesses must go through
 291 accessor methods. E.g. looking at $x-&gt;{sign} is not a bright idea since there
 292 is no guaranty that the object in question has such a hashkey, nor is a hash
 293 underneath at all.</p>
 294 <p>
 295 </p>
 296 <h2><a name="sign">SIGN</a></h2>
 297 <p>The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
 298 You can access it with the <code>sign()</code> method.</p>
 299 <p>A sign of 'NaN' is used to represent the result when input arguments are not
 300 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 301 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 302 '-inf' when dividing any negative number by 0.</p>
 303 <p>
 304 </p>
 305 <hr />
 306 <h1><a name="modules_used">MODULES USED</a></h1>
 307 <p><code>bignum</code> is just a thin wrapper around various modules of the Math::BigInt
 308 family. Think of it as the head of the family, who runs the shop, and orders
 309 the others to do the work.</p>
 310 <p>The following modules are currently used by bignum:</p>
 311 <pre>
 312         Math::BigInt::Lite      (for speed, and only if it is loadable)
 313         Math::BigInt
 314         Math::BigFloat</pre>
 315 <p>
 316 </p>
 317 <hr />
 318 <h1><a name="examples">EXAMPLES</a></h1>
 319 <p>Some cool command line examples to impress the Python crowd ;)
 320 </p>
 321 <pre>
 322
 323         perl -Mbignum -le 'print sqrt(33)'
 324         perl -Mbignum -le 'print 2*255'
 325         perl -Mbignum -le 'print 4.5+2*255'
 326         perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
 327         perl -Mbignum -le 'print 123-&gt;is_odd()'
 328         perl -Mbignum -le 'print log(2)'
 329         perl -Mbignum -le 'print 2 ** 0.5'
 330         perl -Mbignum=a,65 -le 'print 2 ** 0.2'</pre>
 331 <p>
 332 </p>
 333 <hr />
 334 <h1><a name="license">LICENSE</a></h1>
 335 <p>This program is free software; you may redistribute it and/or modify it under
 336 the same terms as Perl itself.</p>
 337 <p>
 338 </p>
 339 <hr />
 340 <h1><a name="see_also">SEE ALSO</a></h1>
 341 <p>Especially <a href="file://C|\msysgit\mingw\html/lib/bigrat.html">the bigrat manpage</a> as in <code>perl -Mbigrat -le 'print 1/3+1/4'</code>.</p>
 342 <p><a href="file://C|\msysgit\mingw\html/lib/Math/BigFloat.html">the Math::BigFloat manpage</a>, <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/BigRat.html">the Math::BigRat manpage</a> and <a href="file://C|\msysgit\mingw\html/Math/Big.html">the Math::Big manpage</a> as well
 343 as <a href="file://C|\msysgit\mingw\html/Math/BigInt/BitVect.html">the Math::BigInt::BitVect manpage</a>, <a href="file://C|\msysgit\mingw\html/Math/BigInt/Pari.html">the Math::BigInt::Pari manpage</a> and  <a href="file://C|\msysgit\mingw\html/Math/BigInt/GMP.html">the Math::BigInt::GMP manpage</a>.</p>
 344 <p>
 345 </p>
 346 <hr />
 347 <h1><a name="authors">AUTHORS</a></h1>
 348 <p>(C) by Tels <a href="http://bloodgate.com/">http://bloodgate.com/</a> in early 2002, 2003.</p>
 349 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 350 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 351 <big><strong><span class="block">&nbsp;bignum - Transparent BigNumber support for Perl</span></strong></big>
 352 </td></tr>
 353 </table>
 354
 355 </body>
 356
 357 </html>