mingw/html/lib/bigint.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>bigint - Transparent BigInteger 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;bigint - Transparent BigInteger 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="#math_library">Math Library</a></li>
  29                 <li><a href="#internal_format">Internal Format</a></li>
  30                 <li><a href="#sign">Sign</a></li>
  31                 <li><a href="#methods">Methods</a></li>
  32                 <li><a href="#caveat">Caveat</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>bigint - Transparent BigInteger support for Perl</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="synopsis">SYNOPSIS</a></h1>
  52 <pre>
  53   use bigint;</pre>
  54 <pre>
  55   $x = 2 + 4.5,&quot;\n&quot;;                    # BigInt 6
  56   print 2 ** 512,&quot;\n&quot;;                  # really is what you think it is
  57   print inf + 42,&quot;\n&quot;;                  # inf
  58   print NaN * 7,&quot;\n&quot;;                   # 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
  64 constants are created as proper BigInts.</p>
  65 <p>Floating point constants are truncated to integer. All results are also
  66 truncated.</p>
  67 <p>
  68 </p>
  69 <h2><a name="options">Options</a></h2>
  70 <p>bigint recognizes some options that can be passed while loading it via use.
  71 The options can (currently) be either a single letter form, or the long form.
  72 The following options exist:</p>
  73 <dl>
  74 <dt><strong><a name="item_a_or_accuracy">a or accuracy</a></strong>
  75
  76 <dd>
  77 <p>This sets the accuracy for all math operations. The argument must be greater
  78 than or equal to zero. See Math::BigInt's <code>bround()</code> function for details.</p>
  79 </dd>
  80 <dd>
  81 <pre>
  82         perl -Mbigint=a,2 -le 'print 12345+1'</pre>
  83 </dd>
  84 </li>
  85 <dt><strong><a name="item_p_or_precision">p or precision</a></strong>
  86
  87 <dd>
  88 <p>This sets the precision for all math operations. The argument can be any
  89 integer. Negative values mean a fixed number of digits after the dot, and
  90 are &lt;B&gt;ignored&lt;/B&gt; since all operations happen in integer space.
  91 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
  92 integer and are ignore like negative values.</p>
  93 </dd>
  94 <dd>
  95 <p>See Math::BigInt's <code>bfround()</code> function for details.</p>
  96 </dd>
  97 <dd>
  98 <pre>
  99         perl -Mbignum=p,5 -le 'print 123456789+123'</pre>
 100 </dd>
 101 </li>
 102 <dt><strong><a name="item_t_or_trace">t or trace</a></strong>
 103
 104 <dd>
 105 <p>This enables a trace mode and is primarily for debugging bigint or
 106 Math::BigInt.</p>
 107 </dd>
 108 </li>
 109 <dt><strong><a name="item_l_or_lib">l or lib</a></strong>
 110
 111 <dd>
 112 <p>Load a different math lib, see <a href="#math_library">MATH LIBRARY</a>.</p>
 113 </dd>
 114 <dd>
 115 <pre>
 116         perl -Mbigint=l,GMP -e 'print 2 ** 512'</pre>
 117 </dd>
 118 <dd>
 119 <p>Currently there is no way to specify more than one library on the command
 120 line. This will be hopefully fixed soon ;)</p>
 121 </dd>
 122 </li>
 123 <dt><strong><a name="item_v_or_version">v or version</a></strong>
 124
 125 <dd>
 126 <p>This prints out the name and version of all modules used and then exits.</p>
 127 </dd>
 128 <dd>
 129 <pre>
 130         perl -Mbigint=v</pre>
 131 </dd>
 132 </li>
 133 </dl>
 134 <p>
 135 </p>
 136 <h2><a name="math_library">Math Library</a></h2>
 137 <p>Math with the numbers is done (by default) by a module called
 138 Math::BigInt::Calc. This is equivalent to saying:</p>
 139 <pre>
 140         use bigint lib =&gt; 'Calc';</pre>
 141 <p>You can change this by using:</p>
 142 <pre>
 143         use bigint lib =&gt; 'BitVect';</pre>
 144 <p>The following would first try to find Math::BigInt::Foo, then
 145 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:</p>
 146 <pre>
 147         use bigint lib =&gt; 'Foo,Math::BigInt::Bar';</pre>
 148 <p>Please see respective module documentation for further details.</p>
 149 <p>
 150 </p>
 151 <h2><a name="internal_format">Internal Format</a></h2>
 152 <p>The numbers are stored as objects, and their internals might change at anytime,
 153 especially between math operations. The objects also might belong to different
 154 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
 155 with normal scalars is not extraordinary, but normal and expected.</p>
 156 <p>You should not depend on the internal format, all accesses must go through
 157 accessor methods. E.g. looking at $x-&gt;{sign} is not a good idea since there
 158 is no guaranty that the object in question has such a hash key, nor is a hash
 159 underneath at all.</p>
 160 <p>
 161 </p>
 162 <h2><a name="sign">Sign</a></h2>
 163 <p>The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 164 You can access it with the <code>sign()</code> method.</p>
 165 <p>A sign of 'NaN' is used to represent the result when input arguments are not
 166 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 167 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 168 '-inf' when dividing any negative number by 0.</p>
 169 <p>
 170 </p>
 171 <h2><a name="methods">Methods</a></h2>
 172 <p>Since all numbers are now objects, you can use all functions that are part of
 173 the BigInt API. You can only use the <code>bxxx()</code> notation, and not the <code>fxxx()</code>
 174 notation, though.</p>
 175 <p>
 176 </p>
 177 <h2><a name="caveat">Caveat</a></h2>
 178 <p>But a warning is in order. When using the following to make a copy of a number,
 179 only a shallow copy will be made.</p>
 180 <pre>
 181         $x = 9; $y = $x;
 182         $x = $y = 7;</pre>
 183 <p>Using the copy or the original with overloaded math is okay, e.g. the
 184 following work:</p>
 185 <pre>
 186         $x = 9; $y = $x;
 187         print $x + 1, &quot; &quot;, $y,&quot;\n&quot;;     # prints 10 9</pre>
 188 <p>but calling any method that modifies the number directly will result in
 189 <strong>both</strong> the original and the copy beeing destroyed:
 190 </p>
 191 <pre>
 192
 193         $x = 9; $y = $x;
 194         print $x-&gt;badd(1), &quot; &quot;, $y,&quot;\n&quot;;        # prints 10 10</pre>
 195 <pre>
 196
 197         $x = 9; $y = $x;
 198         print $x-&gt;binc(1), &quot; &quot;, $y,&quot;\n&quot;;        # prints 10 10</pre>
 199 <pre>
 200
 201         $x = 9; $y = $x;
 202         print $x-&gt;bmul(2), &quot; &quot;, $y,&quot;\n&quot;;        # prints 18 18</pre>
 203 <pre>
 204
 205 Using methods that do not modify, but testthe contents works:</pre>
 206 <pre>
 207         $x = 9; $y = $x;
 208         $z = 9 if $x-&gt;is_zero();                # works fine</pre>
 209 <p>See the documentation about the copy constructor and <code>=</code> in overload, as
 210 well as the documentation in BigInt for further details.</p>
 211 <p>
 212 </p>
 213 <hr />
 214 <h1><a name="modules_used">MODULES USED</a></h1>
 215 <p><code>bigint</code> is just a thin wrapper around various modules of the Math::BigInt
 216 family. Think of it as the head of the family, who runs the shop, and orders
 217 the others to do the work.</p>
 218 <p>The following modules are currently used by bigint:</p>
 219 <pre>
 220         Math::BigInt::Lite      (for speed, and only if it is loadable)
 221         Math::BigInt</pre>
 222 <p>
 223 </p>
 224 <hr />
 225 <h1><a name="examples">EXAMPLES</a></h1>
 226 <p>Some cool command line examples to impress the Python crowd ;) You might want
 227 to compare them to the results under -Mbignum or -Mbigrat:
 228 </p>
 229 <pre>
 230
 231         perl -Mbigint -le 'print sqrt(33)'
 232         perl -Mbigint -le 'print 2*255'
 233         perl -Mbigint -le 'print 4.5+2*255'
 234         perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
 235         perl -Mbigint -le 'print 123-&gt;is_odd()'
 236         perl -Mbigint -le 'print log(2)'
 237         perl -Mbigint -le 'print 2 ** 0.5'
 238         perl -Mbigint=a,65 -le 'print 2 ** 0.2'</pre>
 239 <p>
 240 </p>
 241 <hr />
 242 <h1><a name="license">LICENSE</a></h1>
 243 <p>This program is free software; you may redistribute it and/or modify it under
 244 the same terms as Perl itself.</p>
 245 <p>
 246 </p>
 247 <hr />
 248 <h1><a name="see_also">SEE ALSO</a></h1>
 249 <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> and
 250 <a href="file://C|\msysgit\mingw\html/lib/bignum.html">the bignum manpage</a> as in <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_sqrt"><code>perl -Mbignum -le 'print sqrt(2)'</code></a>.
 251
 252 </p>
 253 <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/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
 254 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>.
 255
 256 </p>
 257 <p>
 258 </p>
 259 <hr />
 260 <h1><a name="authors">AUTHORS</a></h1>
 261 <p>(C) by Tels <a href="http://bloodgate.com/">http://bloodgate.com/</a> in early 2002 - 2005.
 262
 263 </p>
 264 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 265 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 266 <big><strong><span class="block">&nbsp;bigint - Transparent BigInteger support for Perl</span></strong></big>
 267 </td></tr>
 268 </table>
 269
 270 </body>
 271
 272 </html>