mingw/html/lib/Math/BigFloat.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::BigFloat - Arbitrary size floating point math package</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::BigFloat - Arbitrary size floating point math package</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="#canonical_notation">Canonical notation</a></li>
  28                 <li><a href="#output">Output</a></li>
  29                 <li><a href="#mantissa____exponent___and_parts__"><code>mantissa()</code>, <code>exponent()</code> and <code>parts()</code></a></li>
  30                 <li><a href="#accuracy_vs__precision">Accuracy vs. Precision</a></li>
  31                 <li><a href="#rounding">Rounding</a></li>
  32         </ul>
  33
  34         <li><a href="#methods">METHODS</a></li>
  35         <ul>
  36
  37                 <li><a href="#accuracy">accuracy</a></li>
  38                 <li><a href="#precision__"><code>precision()</code></a></li>
  39         </ul>
  40
  41         <li><a href="#autocreating_constants">Autocreating constants</a></li>
  42         <ul>
  43
  44                 <li><a href="#math_library">Math library</a></li>
  45                 <li><a href="#using_math__bigint__lite">Using Math::BigInt::Lite</a></li>
  46         </ul>
  47
  48         <li><a href="#bugs">BUGS</a></li>
  49         <li><a href="#caveats">CAVEATS</a></li>
  50         <li><a href="#see_also">SEE ALSO</a></li>
  51         <li><a href="#license">LICENSE</a></li>
  52         <li><a href="#authors">AUTHORS</a></li>
  53 </ul>
  54 <!-- INDEX END -->
  55
  56 <hr />
  57 <p>
  58 </p>
  59 <h1><a name="name">NAME</a></h1>
  60 <p>Math::BigFloat - Arbitrary size floating point math package</p>
  61 <p>
  62 </p>
  63 <hr />
  64 <h1><a name="synopsis">SYNOPSIS</a></h1>
  65 <pre>
  66   use Math::BigFloat;</pre>
  67 <pre>
  68   # Number creation
  69   $x = Math::BigFloat-&gt;new($str);       # defaults to 0
  70   $nan  = Math::BigFloat-&gt;bnan();       # create a NotANumber
  71   $zero = Math::BigFloat-&gt;bzero();      # create a +0
  72   $inf = Math::BigFloat-&gt;binf();        # create a +inf
  73   $inf = Math::BigFloat-&gt;binf('-');     # create a -inf
  74   $one = Math::BigFloat-&gt;bone();        # create a +1
  75   $one = Math::BigFloat-&gt;bone('-');     # create a -1</pre>
  76 <pre>
  77   # Testing
  78   $x-&gt;is_zero();                # true if arg is +0
  79   $x-&gt;is_nan();                 # true if arg is NaN
  80   $x-&gt;is_one();                 # true if arg is +1
  81   $x-&gt;is_one('-');              # true if arg is -1
  82   $x-&gt;is_odd();                 # true if odd, false for even
  83   $x-&gt;is_even();                # true if even, false for odd
  84   $x-&gt;is_pos();                 # true if &gt;= 0
  85   $x-&gt;is_neg();                 # true if &lt;  0
  86   $x-&gt;is_inf(sign);             # true if +inf, or -inf (default is '+')</pre>
  87 <pre>
  88   $x-&gt;bcmp($y);                 # compare numbers (undef,&lt;0,=0,&gt;0)
  89   $x-&gt;bacmp($y);                # compare absolutely (undef,&lt;0,=0,&gt;0)
  90   $x-&gt;sign();                   # return the sign, either +,- or NaN
  91   $x-&gt;digit($n);                # return the nth digit, counting from right
  92   $x-&gt;digit(-$n);               # return the nth digit, counting from left</pre>
  93 <pre>
  94   # The following all modify their first argument. If you want to preserve
  95   # $x, use $z = $x-&gt;copy()-&gt;bXXX($y); See under L&lt;CAVEATS&gt; for why this is
  96   # neccessary when mixing $a = $b assigments with non-overloaded math.
  97
  98   # set
  99   $x-&gt;bzero();                  # set $i to 0
 100   $x-&gt;bnan();                   # set $i to NaN
 101   $x-&gt;bone();                   # set $x to +1
 102   $x-&gt;bone('-');                # set $x to -1
 103   $x-&gt;binf();                   # set $x to inf
 104   $x-&gt;binf('-');                # set $x to -inf</pre>
 105 <pre>
 106   $x-&gt;bneg();                   # negation
 107   $x-&gt;babs();                   # absolute value
 108   $x-&gt;bnorm();                  # normalize (no-op)
 109   $x-&gt;bnot();                   # two's complement (bit wise not)
 110   $x-&gt;binc();                   # increment x by 1
 111   $x-&gt;bdec();                   # decrement x by 1
 112
 113   $x-&gt;badd($y);                 # addition (add $y to $x)
 114   $x-&gt;bsub($y);                 # subtraction (subtract $y from $x)
 115   $x-&gt;bmul($y);                 # multiplication (multiply $x by $y)
 116   $x-&gt;bdiv($y);                 # divide, set $x to quotient
 117                                 # return (quo,rem) or quo if scalar</pre>
 118 <pre>
 119   $x-&gt;bmod($y);                 # modulus ($x % $y)
 120   $x-&gt;bpow($y);                 # power of arguments ($x ** $y)
 121   $x-&gt;blsft($y);                # left shift
 122   $x-&gt;brsft($y);                # right shift
 123                                 # return (quo,rem) or quo if scalar
 124
 125   $x-&gt;blog();                   # logarithm of $x to base e (Euler's number)
 126   $x-&gt;blog($base);              # logarithm of $x to base $base (f.i. 2)
 127
 128   $x-&gt;band($y);                 # bit-wise and
 129   $x-&gt;bior($y);                 # bit-wise inclusive or
 130   $x-&gt;bxor($y);                 # bit-wise exclusive or
 131   $x-&gt;bnot();                   # bit-wise not (two's complement)
 132
 133   $x-&gt;bsqrt();                  # calculate square-root
 134   $x-&gt;broot($y);                # $y'th root of $x (e.g. $y == 3 =&gt; cubic root)
 135   $x-&gt;bfac();                   # factorial of $x (1*2*3*4*..$x)
 136
 137   $x-&gt;bround($N);               # accuracy: preserve $N digits
 138   $x-&gt;bfround($N);              # precision: round to the $Nth digit</pre>
 139 <pre>
 140   $x-&gt;bfloor();                 # return integer less or equal than $x
 141   $x-&gt;bceil();                  # return integer greater or equal than $x</pre>
 142 <pre>
 143   # The following do not modify their arguments:</pre>
 144 <pre>
 145   bgcd(@values);                # greatest common divisor
 146   blcm(@values);                # lowest common multiplicator
 147
 148   $x-&gt;bstr();                   # return string
 149   $x-&gt;bsstr();                  # return string in scientific notation</pre>
 150 <pre>
 151   $x-&gt;as_int();                 # return $x as BigInt
 152   $x-&gt;exponent();               # return exponent as BigInt
 153   $x-&gt;mantissa();               # return mantissa as BigInt
 154   $x-&gt;parts();                  # return (mantissa,exponent) as BigInt</pre>
 155 <pre>
 156   $x-&gt;length();                 # number of digits (w/o sign and '.')
 157   ($l,$f) = $x-&gt;length();       # number of digits, and length of fraction</pre>
 158 <pre>
 159   $x-&gt;precision();              # return P of $x (or global, if P of $x undef)
 160   $x-&gt;precision($n);            # set P of $x to $n
 161   $x-&gt;accuracy();               # return A of $x (or global, if A of $x undef)
 162   $x-&gt;accuracy($n);             # set A $x to $n</pre>
 163 <pre>
 164   # these get/set the appropriate global value for all BigFloat objects
 165   Math::BigFloat-&gt;precision();  # Precision
 166   Math::BigFloat-&gt;accuracy();   # Accuracy
 167   Math::BigFloat-&gt;round_mode(); # rounding mode</pre>
 168 <p>
 169 </p>
 170 <hr />
 171 <h1><a name="description">DESCRIPTION</a></h1>
 172 <p>All operators (inlcuding basic math operations) are overloaded if you
 173 declare your big floating point numbers as</p>
 174 <pre>
 175   $i = new Math::BigFloat '12_3.456_789_123_456_789E-2';</pre>
 176 <p>Operations with overloaded operators preserve the arguments, which is
 177 exactly what you expect.</p>
 178 <p>
 179 </p>
 180 <h2><a name="canonical_notation">Canonical notation</a></h2>
 181 <p>Input to these routines are either BigFloat objects, or strings of the
 182 following four forms:</p>
 183 <ul>
 184 <li>
 185 <p><code>/^[+-]\d+$/</code></p>
 186 </li>
 187 <li>
 188 <p><code>/^[+-]\d+\.\d*$/</code></p>
 189 </li>
 190 <li>
 191 <p><code>/^[+-]\d+E[+-]?\d+$/</code></p>
 192 </li>
 193 <li>
 194 <p><code>/^[+-]\d*\.\d+E[+-]?\d+$/</code></p>
 195 </li>
 196 </ul>
 197 <p>all with optional leading and trailing zeros and/or spaces. Additonally,
 198 numbers are allowed to have an underscore between any two digits.</p>
 199 <p>Empty strings as well as other illegal numbers results in 'NaN'.</p>
 200 <p><code>bnorm()</code> on a BigFloat object is now effectively a no-op, since the numbers
 201 are always stored in normalized form. On a string, it creates a BigFloat
 202 object.</p>
 203 <p>
 204 </p>
 205 <h2><a name="output">Output</a></h2>
 206 <p>Output values are BigFloat objects (normalized), except for <a href="#item_bstr"><code>bstr()</code></a> and bsstr().</p>
 207 <p>The string output will always have leading and trailing zeros stripped and drop
 208 a plus sign. <a href="#item_bstr"><code>bstr()</code></a> will give you always the form with a decimal point,
 209 while <code>bsstr()</code> (s for scientific) gives you the scientific notation.</p>
 210 <pre>
 211         Input                   bstr()          bsstr()
 212         '-0'                    '0'             '0E1'
 213         '  -123 123 123'        '-123123123'    '-123123123E0'
 214         '00.0123'               '0.0123'        '123E-4'
 215         '123.45E-2'             '1.2345'        '12345E-4'
 216         '10E+3'                 '10000'         '1E4'</pre>
 217 <p>Some routines (<code>is_odd()</code>, <code>is_even()</code>, <code>is_zero()</code>, <code>is_one()</code>,
 218 <code>is_nan()</code>) return true or false, while others (<code>bcmp()</code>, <code>bacmp()</code>)
 219 return either undef, &lt;0, 0 or &gt;0 and are suited for sort.</p>
 220 <p>Actual math is done by using the class defined with <code>with =</code> Class;&gt; (which
 221 defaults to BigInts) to represent the mantissa and exponent.</p>
 222 <p>The sign <code>/^[+-]$/</code> is stored separately. The string 'NaN' is used to
 223 represent the result when input arguments are not numbers, as well as
 224 the result of dividing by zero.</p>
 225 <p>
 226 </p>
 227 <h2><a name="mantissa____exponent___and_parts__"><code>mantissa()</code>, <code>exponent()</code> and <code>parts()</code></a></h2>
 228 <p><code>mantissa()</code> and <code>exponent()</code> return the said parts of the BigFloat
 229 as BigInts such that:</p>
 230 <pre>
 231         $m = $x-&gt;mantissa();
 232         $e = $x-&gt;exponent();
 233         $y = $m * ( 10 ** $e );
 234         print &quot;ok\n&quot; if $x == $y;</pre>
 235 <p><code>($m,$e) = $x-&gt;parts();</code> is just a shortcut giving you both of them.</p>
 236 <p>A zero is represented and returned as <code>0E1</code>, <strong>not</strong> <code>0E0</code> (after Knuth).</p>
 237 <p>Currently the mantissa is reduced as much as possible, favouring higher
 238 exponents over lower ones (e.g. returning 1e7 instead of 10e6 or 10000000e0).
 239 This might change in the future, so do not depend on it.</p>
 240 <p>
 241 </p>
 242 <h2><a name="accuracy_vs__precision">Accuracy vs. Precision</a></h2>
 243 <p>See also: <em>Rounding</em>.</p>
 244 <p>Math::BigFloat supports both precision (rounding to a certain place before or
 245 after the dot) and accuracy (rounding to a certain number of digits). For a
 246 full documentation, examples and tips on these topics please see the large
 247 section about rounding in <a href="file://C|\msysgit\mingw\html/lib/Math/BigInt.html">the Math::BigInt manpage</a>.</p>
 248 <p>Since things like <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_sqrt"><code>sqrt(2)</code></a> or <code>1 / 3</code> must presented with a limited
 249 accuracy lest a operation consumes all resources, each operation produces
 250 no more than the requested number of digits.</p>
 251 <p>If there is no gloabl precision or accuracy set, <strong>and</strong> the operation in
 252 question was not called with a requested precision or accuracy, <strong>and</strong> the
 253 input $x has no accuracy or precision set, then a fallback parameter will
 254 be used. For historical reasons, it is called <code>div_scale</code> and can be accessed
 255 via:</p>
 256 <pre>
 257         $d = Math::BigFloat-&gt;div_scale();               # query
 258         Math::BigFloat-&gt;div_scale($n);                  # set to $n digits</pre>
 259 <p>The default value for <code>div_scale</code> is 40.</p>
 260 <p>In case the result of one operation has more digits than specified,
 261 it is rounded. The rounding mode taken is either the default mode, or the one
 262 supplied to the operation after the <em>scale</em>:</p>
 263 <pre>
 264         $x = Math::BigFloat-&gt;new(2);
 265         Math::BigFloat-&gt;accuracy(5);            # 5 digits max
 266         $y = $x-&gt;copy()-&gt;bdiv(3);               # will give 0.66667
 267         $y = $x-&gt;copy()-&gt;bdiv(3,6);             # will give 0.666667
 268         $y = $x-&gt;copy()-&gt;bdiv(3,6,undef,'odd'); # will give 0.666667
 269         Math::BigFloat-&gt;round_mode('zero');
 270         $y = $x-&gt;copy()-&gt;bdiv(3,6);             # will also give 0.666667</pre>
 271 <p>Note that <code>Math::BigFloat-&gt;accuracy()</code> and <a href="#item_precision"><code>Math::BigFloat-&gt;precision()</code></a>
 272 set the global variables, and thus <strong>any</strong> newly created number will be subject
 273 to the global rounding <strong>immidiately</strong>. This means that in the examples above, the
 274 <code>3</code> as argument to <a href="#item_bdiv"><code>bdiv()</code></a> will also get an accuracy of <strong>5</strong>.</p>
 275 <p>It is less confusing to either calculate the result fully, and afterwards
 276 round it explicitely, or use the additional parameters to the math
 277 functions like so:</p>
 278 <pre>
 279         use Math::BigFloat;
 280         $x = Math::BigFloat-&gt;new(2);
 281         $y = $x-&gt;copy()-&gt;bdiv(3);
 282         print $y-&gt;bround(5),&quot;\n&quot;;               # will give 0.66667</pre>
 283 <pre>
 284         or</pre>
 285 <pre>
 286         use Math::BigFloat;
 287         $x = Math::BigFloat-&gt;new(2);
 288         $y = $x-&gt;copy()-&gt;bdiv(3,5);             # will give 0.66667
 289         print &quot;$y\n&quot;;</pre>
 290 <p>
 291 </p>
 292 <h2><a name="rounding">Rounding</a></h2>
 293 <dl>
 294 <dt><strong><a name="item_ffround">ffround ( +$scale )</a></strong>
 295
 296 <dd>
 297 <p>Rounds to the $scale'th place left from the '.', counting from the dot.
 298 The first digit is numbered 1.</p>
 299 </dd>
 300 </li>
 301 <dt><strong>ffround ( -$scale )</strong>
 302
 303 <dd>
 304 <p>Rounds to the $scale'th place right from the '.', counting from the dot.</p>
 305 </dd>
 306 </li>
 307 <dt><strong>ffround ( 0 )</strong>
 308
 309 <dd>
 310 <p>Rounds to an integer.</p>
 311 </dd>
 312 </li>
 313 <dt><strong><a name="item_fround">fround  ( +$scale )</a></strong>
 314
 315 <dd>
 316 <p>Preserves accuracy to $scale digits from the left (aka significant digits)
 317 and pads the rest with zeros. If the number is between 1 and -1, the
 318 significant digits count from the first non-zero after the '.'</p>
 319 </dd>
 320 </li>
 321 <dt><strong>fround  ( -$scale ) and fround ( 0 )</strong>
 322
 323 <dd>
 324 <p>These are effectively no-ops.</p>
 325 </dd>
 326 </li>
 327 </dl>
 328 <p>All rounding functions take as a second parameter a rounding mode from one of
 329 the following: 'even', 'odd', '+inf', '-inf', 'zero' or 'trunc'.</p>
 330 <p>The default rounding mode is 'even'. By using
 331 <code>Math::BigFloat-&gt;round_mode($round_mode);</code> you can get and set the default
 332 mode for subsequent rounding. The usage of <code>$Math::BigFloat::$round_mode</code> is
 333 no longer supported.
 334 The second parameter to the round functions then overrides the default
 335 temporarily.</p>
 336 <p>The <code>as_number()</code> function returns a BigInt from a Math::BigFloat. It uses
 337 'trunc' as rounding mode to make it equivalent to:</p>
 338 <pre>
 339         $x = 2.5;
 340         $y = int($x) + 2;</pre>
 341 <p>You can override this by passing the desired rounding mode as parameter to
 342 <code>as_number()</code>:</p>
 343 <pre>
 344         $x = Math::BigFloat-&gt;new(2.5);
 345         $y = $x-&gt;as_number('odd');      # $y = 3</pre>
 346 <p>
 347 </p>
 348 <hr />
 349 <h1><a name="methods">METHODS</a></h1>
 350 <p>
 351 </p>
 352 <h2><a name="accuracy">accuracy</a></h2>
 353 <pre>
 354         $x-&gt;accuracy(5);                # local for $x
 355         CLASS-&gt;accuracy(5);             # global for all members of CLASS
 356                                         # Note: This also applies to new()!</pre>
 357 <pre>
 358         $A = $x-&gt;accuracy();            # read out accuracy that affects $x
 359         $A = CLASS-&gt;accuracy();         # read out global accuracy</pre>
 360 <p>Set or get the global or local accuracy, aka how many significant digits the
 361 results have. If you set a global accuracy, then this also applies to new()!</p>
 362 <p>Warning! The accuracy <em>sticks</em>, e.g. once you created a number under the
 363 influence of <code>CLASS-&gt;accuracy($A)</code>, all results from math operations with
 364 that number will also be rounded.</p>
 365 <p>In most cases, you should probably round the results explicitely using one of
 366 <em>round()</em>, <em>bround()</em> or <em>bfround()</em> or by passing the desired accuracy
 367 to the math operation as additional parameter:</p>
 368 <pre>
 369         my $x = Math::BigInt-&gt;new(30000);
 370         my $y = Math::BigInt-&gt;new(7);
 371         print scalar $x-&gt;copy()-&gt;bdiv($y, 2);           # print 4300
 372         print scalar $x-&gt;copy()-&gt;bdiv($y)-&gt;bround(2);   # print 4300</pre>
 373 <p>
 374 </p>
 375 <h2><a name="precision__"><a href="#item_precision"><code>precision()</code></a></a></h2>
 376 <pre>
 377         $x-&gt;precision(-2);      # local for $x, round at the second digit right of the dot
 378         $x-&gt;precision(2);       # ditto, round at the second digit left of the dot</pre>
 379 <pre>
 380         CLASS-&gt;precision(5);    # Global for all members of CLASS
 381                                 # This also applies to new()!
 382         CLASS-&gt;precision(-5);   # ditto</pre>
 383 <pre>
 384         $P = CLASS-&gt;precision();        # read out global precision
 385         $P = $x-&gt;precision();           # read out precision that affects $x</pre>
 386 <p>Note: You probably want to use <em>accuracy()</em> instead. With <a href="#accuracy">the accuracy manpage</a> you
 387 set the number of digits each result should have, with <a href="#item_precision">precision</a> you
 388 set the place where to round!</p>
 389 <p>
 390 </p>
 391 <hr />
 392 <h1><a name="autocreating_constants">Autocreating constants</a></h1>
 393 <p>After <code>use Math::BigFloat ':constant'</code> all the floating point constants
 394 in the given scope are converted to <code>Math::BigFloat</code>. This conversion
 395 happens at compile time.</p>
 396 <p>In particular</p>
 397 <pre>
 398   perl -MMath::BigFloat=:constant -e 'print 2E-100,&quot;\n&quot;'</pre>
 399 <p>prints the value of <code>2E-100</code>. Note that without conversion of
 400 constants the expression 2E-100 will be calculated as normal floating point
 401 number.</p>
 402 <p>Please note that ':constant' does not affect integer constants, nor binary
 403 nor hexadecimal constants. Use <a href="file://C|\msysgit\mingw\html/lib/bignum.html">the bignum manpage</a> or <a href="file://C|\msysgit\mingw\html/lib/Math/BigInt.html">the Math::BigInt manpage</a> to get this to
 404 work.</p>
 405 <p>
 406 </p>
 407 <h2><a name="math_library">Math library</a></h2>
 408 <p>Math with the numbers is done (by default) by a module called
 409 Math::BigInt::Calc. This is equivalent to saying:</p>
 410 <pre>
 411         use Math::BigFloat lib =&gt; 'Calc';</pre>
 412 <p>You can change this by using:</p>
 413 <pre>
 414         use Math::BigFloat lib =&gt; 'BitVect';</pre>
 415 <p>The following would first try to find Math::BigInt::Foo, then
 416 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:</p>
 417 <pre>
 418         use Math::BigFloat lib =&gt; 'Foo,Math::BigInt::Bar';</pre>
 419 <p>Calc.pm uses as internal format an array of elements of some decimal base
 420 (usually 1e7, but this might be differen for some systems) with the least
 421 significant digit first, while BitVect.pm uses a bit vector of base 2, most
 422 significant bit first. Other modules might use even different means of
 423 representing the numbers. See the respective module documentation for further
 424 details.</p>
 425 <p>Please note that Math::BigFloat does <strong>not</strong> use the denoted library itself,
 426 but it merely passes the lib argument to Math::BigInt. So, instead of the need
 427 to do:</p>
 428 <pre>
 429         use Math::BigInt lib =&gt; 'GMP';
 430         use Math::BigFloat;</pre>
 431 <p>you can roll it all into one line:</p>
 432 <pre>
 433         use Math::BigFloat lib =&gt; 'GMP';</pre>
 434 <p>It is also possible to just require Math::BigFloat:</p>
 435 <pre>
 436         require Math::BigFloat;</pre>
 437 <p>This will load the neccessary things (like BigInt) when they are needed, and
 438 automatically.</p>
 439 <p>Use the lib, Luke! And see <a href="#using_math__bigint__lite">Using Math::BigInt::Lite</a> for more details than
 440 you ever wanted to know about loading a different library.</p>
 441 <p>
 442 </p>
 443 <h2><a name="using_math__bigint__lite">Using Math::BigInt::Lite</a></h2>
 444 <p>It is possible to use <a href="file://C|\msysgit\mingw\html/Math/BigInt/Lite.html">the Math::BigInt::Lite manpage</a> with Math::BigFloat:</p>
 445 <pre>
 446         # 1
 447         use Math::BigFloat with =&gt; 'Math::BigInt::Lite';</pre>
 448 <p>There is no need to ``use Math::BigInt'' or ``use Math::BigInt::Lite'', but you
 449 can combine these if you want. For instance, you may want to use
 450 Math::BigInt objects in your main script, too.</p>
 451 <pre>
 452         # 2
 453         use Math::BigInt;
 454         use Math::BigFloat with =&gt; 'Math::BigInt::Lite';</pre>
 455 <p>Of course, you can combine this with the <code>lib</code> parameter.</p>
 456 <pre>
 457         # 3
 458         use Math::BigFloat with =&gt; 'Math::BigInt::Lite', lib =&gt; 'GMP,Pari';</pre>
 459 <p>There is no need for a ``use Math::BigInt;'' statement, even if you want to
 460 use Math::BigInt's, since Math::BigFloat will needs Math::BigInt and thus
 461 always loads it. But if you add it, add it <strong>before</strong>:</p>
 462 <pre>
 463         # 4
 464         use Math::BigInt;
 465         use Math::BigFloat with =&gt; 'Math::BigInt::Lite', lib =&gt; 'GMP,Pari';</pre>
 466 <p>Notice that the module with the last <code>lib</code> will ``win'' and thus
 467 it's lib will be used if the lib is available:</p>
 468 <pre>
 469         # 5
 470         use Math::BigInt lib =&gt; 'Bar,Baz';
 471         use Math::BigFloat with =&gt; 'Math::BigInt::Lite', lib =&gt; 'Foo';</pre>
 472 <p>That would try to load Foo, Bar, Baz and Calc (in that order). Or in other
 473 words, Math::BigFloat will try to retain previously loaded libs when you
 474 don't specify it onem but if you specify one, it will try to load them.</p>
 475 <p>Actually, the lib loading order would be ``Bar,Baz,Calc'', and then
 476 ``Foo,Bar,Baz,Calc'', but independend of which lib exists, the result is the
 477 same as trying the latter load alone, except for the fact that one of Bar or
 478 Baz might be loaded needlessly in an intermidiate step (and thus hang around
 479 and waste memory). If neither Bar nor Baz exist (or don't work/compile), they
 480 will still be tried to be loaded, but this is not as time/memory consuming as
 481 actually loading one of them. Still, this type of usage is not recommended due
 482 to these issues.</p>
 483 <p>The old way (loading the lib only in BigInt) still works though:</p>
 484 <pre>
 485         # 6
 486         use Math::BigInt lib =&gt; 'Bar,Baz';
 487         use Math::BigFloat;</pre>
 488 <p>You can even load Math::BigInt afterwards:</p>
 489 <pre>
 490         # 7
 491         use Math::BigFloat;
 492         use Math::BigInt lib =&gt; 'Bar,Baz';</pre>
 493 <p>But this has the same problems like #5, it will first load Calc
 494 (Math::BigFloat needs Math::BigInt and thus loads it) and then later Bar or
 495 Baz, depending on which of them works and is usable/loadable. Since this
 496 loads Calc unnecc., it is not recommended.</p>
 497 <p>Since it also possible to just require Math::BigFloat, this poses the question
 498 about what libary this will use:</p>
 499 <pre>
 500         require Math::BigFloat;
 501         my $x = Math::BigFloat-&gt;new(123); $x += 123;</pre>
 502 <p>It will use Calc. Please note that the call to <code>import()</code> is still done, but
 503 only when you use for the first time some Math::BigFloat math (it is triggered
 504 via any constructor, so the first time you create a Math::BigFloat, the load
 505 will happen in the background). This means:</p>
 506 <pre>
 507         require Math::BigFloat;
 508         Math::BigFloat-&gt;import ( lib =&gt; 'Foo,Bar' );</pre>
 509 <p>would be the same as:</p>
 510 <pre>
 511         use Math::BigFloat lib =&gt; 'Foo, Bar';</pre>
 512 <p>But don't try to be clever to insert some operations in between:</p>
 513 <pre>
 514         require Math::BigFloat;
 515         my $x = Math::BigFloat-&gt;bone() + 4;             # load BigInt and Calc
 516         Math::BigFloat-&gt;import( lib =&gt; 'Pari' );        # load Pari, too
 517         $x = Math::BigFloat-&gt;bone()+4;                  # now use Pari</pre>
 518 <p>While this works, it loads Calc needlessly. But maybe you just wanted that?</p>
 519 <p><strong>Examples #3 is highly recommended</strong> for daily usage.</p>
 520 <p>
 521 </p>
 522 <hr />
 523 <h1><a name="bugs">BUGS</a></h1>
 524 <p>Please see the file BUGS in the CPAN distribution Math::BigInt for known bugs.</p>
 525 <p>
 526 </p>
 527 <hr />
 528 <h1><a name="caveats">CAVEATS</a></h1>
 529 <dl>
 530 <dt><strong><a name="item_bstr">stringify, <code>bstr()</code></a></strong>
 531
 532 <dd>
 533 <p>Both stringify and <a href="#item_bstr"><code>bstr()</code></a> now drop the leading '+'. The old code would return
 534 '+1.23', the new returns '1.23'. See the documentation in <a href="file://C|\msysgit\mingw\html/lib/Math/BigInt.html">the Math::BigInt manpage</a> for
 535 reasoning and details.</p>
 536 </dd>
 537 </li>
 538 <dt><strong><a name="item_bdiv">bdiv</a></strong>
 539
 540 <dd>
 541 <p>The following will probably not do what you expect:</p>
 542 </dd>
 543 <dd>
 544 <pre>
 545         print $c-&gt;bdiv(123.456),&quot;\n&quot;;</pre>
 546 </dd>
 547 <dd>
 548 <p>It prints both quotient and reminder since print works in list context. Also,
 549 <a href="#item_bdiv"><code>bdiv()</code></a> will modify $c, so be carefull. You probably want to use
 550 </p>
 551 </dd>
 552 <dd>
 553 <pre>
 554
 555         print $c / 123.456,&quot;\n&quot;;
 556         print scalar $c-&gt;bdiv(123.456),&quot;\n&quot;;  # or if you want to modify $c</pre>
 557 </dd>
 558 <dd>
 559 <p>instead.</p>
 560 </dd>
 561 </li>
 562 <dt><strong><a name="item_modifying_and__3d">Modifying and =</a></strong>
 563
 564 <dd>
 565 <p>Beware of:</p>
 566 </dd>
 567 <dd>
 568 <pre>
 569         $x = Math::BigFloat-&gt;new(5);
 570         $y = $x;</pre>
 571 </dd>
 572 <dd>
 573 <p>It will not do what you think, e.g. making a copy of $x. Instead it just makes
 574 a second reference to the <strong>same</strong> object and stores it in $y. Thus anything
 575 that modifies $x will modify $y (except overloaded math operators), and vice
 576 versa. See <a href="file://C|\msysgit\mingw\html/lib/Math/BigInt.html">the Math::BigInt manpage</a> for details and how to avoid that.</p>
 577 </dd>
 578 </li>
 579 <dt><strong><a name="item_bpow">bpow</a></strong>
 580
 581 <dd>
 582 <p><a href="#item_bpow"><code>bpow()</code></a> now modifies the first argument, unlike the old code which left
 583 it alone and only returned the result. This is to be consistent with
 584 <code>badd()</code> etc. The first will modify $x, the second one won't:</p>
 585 </dd>
 586 <dd>
 587 <pre>
 588         print bpow($x,$i),&quot;\n&quot;;         # modify $x
 589         print $x-&gt;bpow($i),&quot;\n&quot;;        # ditto
 590         print $x ** $i,&quot;\n&quot;;            # leave $x alone</pre>
 591 </dd>
 592 </li>
 593 <dt><strong><a name="item_precision"><code>precision()</code> vs. <code>accuracy()</code></a></strong>
 594
 595 <dd>
 596 <p>A common pitfall is to use <a href="#item_precision">precision()</a> when you want to round a result to
 597 a certain number of digits:</p>
 598 </dd>
 599 <dd>
 600 <pre>
 601         use Math::BigFloat;</pre>
 602 </dd>
 603 <dd>
 604 <pre>
 605         Math::BigFloat-&gt;precision(4);           # does not do what you think it does
 606         my $x = Math::BigFloat-&gt;new(12345);     # rounds $x to &quot;12000&quot;!
 607         print &quot;$x\n&quot;;                           # print &quot;12000&quot;
 608         my $y = Math::BigFloat-&gt;new(3);         # rounds $y to &quot;0&quot;!
 609         print &quot;$y\n&quot;;                           # print &quot;0&quot;
 610         $z = $x / $y;                           # 12000 / 0 =&gt; NaN!
 611         print &quot;$z\n&quot;;
 612         print $z-&gt;precision(),&quot;\n&quot;;             # 4</pre>
 613 </dd>
 614 <dd>
 615 <p>Replacing <a href="#item_precision">precision</a> with <a href="#accuracy">the accuracy manpage</a> is probably not what you want, either:</p>
 616 </dd>
 617 <dd>
 618 <pre>
 619         use Math::BigFloat;</pre>
 620 </dd>
 621 <dd>
 622 <pre>
 623         Math::BigFloat-&gt;accuracy(4);            # enables global rounding:
 624         my $x = Math::BigFloat-&gt;new(123456);    # rounded immidiately to &quot;12350&quot;
 625         print &quot;$x\n&quot;;                           # print &quot;123500&quot;
 626         my $y = Math::BigFloat-&gt;new(3);         # rounded to &quot;3
 627         print &quot;$y\n&quot;;                           # print &quot;3&quot;
 628         print $z = $x-&gt;copy()-&gt;bdiv($y),&quot;\n&quot;;   # 41170
 629         print $z-&gt;accuracy(),&quot;\n&quot;;              # 4</pre>
 630 </dd>
 631 <dd>
 632 <p>What you want to use instead is:</p>
 633 </dd>
 634 <dd>
 635 <pre>
 636         use Math::BigFloat;</pre>
 637 </dd>
 638 <dd>
 639 <pre>
 640         my $x = Math::BigFloat-&gt;new(123456);    # no rounding
 641         print &quot;$x\n&quot;;                           # print &quot;123456&quot;
 642         my $y = Math::BigFloat-&gt;new(3);         # no rounding
 643         print &quot;$y\n&quot;;                           # print &quot;3&quot;
 644         print $z = $x-&gt;copy()-&gt;bdiv($y,4),&quot;\n&quot;; # 41150
 645         print $z-&gt;accuracy(),&quot;\n&quot;;              # undef</pre>
 646 </dd>
 647 <dd>
 648 <p>In addition to computing what you expected, the last example also does <strong>not</strong>
 649 ``taint'' the result with an accuracy or precision setting, which would
 650 influence any further operation.
 651
 652 </p>
 653 </dd>
 654 </li>
 655 </dl>
 656 <p>
 657 </p>
 658 <hr />
 659 <h1><a name="see_also">SEE ALSO</a></h1>
 660 <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 as
 661 <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>.
 662
 663 </p>
 664 <p>The pragmas <a href="file://C|\msysgit\mingw\html/lib/bignum.html">the bignum manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/bigint.html">the bigint manpage</a> and <a href="file://C|\msysgit\mingw\html/lib/bigrat.html">the bigrat manpage</a> might also be of interest
 665 because they solve the autoupgrading/downgrading issue, at least partly.
 666
 667 </p>
 668 <p>The package at
 669 <a href="http://search.cpan.org/search?mode=module&query=Math%3A%3ABigInt">http://search.cpan.org/search</a> contains
 670 more documentation including a full version history, testcases, empty
 671 subclass files and benchmarks.
 672
 673 </p>
 674 <p>
 675 </p>
 676 <hr />
 677 <h1><a name="license">LICENSE</a></h1>
 678 <p>This program is free software; you may redistribute it and/or modify it under
 679 the same terms as Perl itself.
 680
 681 </p>
 682 <p>
 683 </p>
 684 <hr />
 685 <h1><a name="authors">AUTHORS</a></h1>
 686 <p>Mark Biggar, overloaded interface by Ilya Zakharevich.
 687 Completely rewritten by Tels <a href="http://bloodgate.com">http://bloodgate.com</a> in 2001 - 2004, and still
 688 at it in 2005.
 689
 690 </p>
 691 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 692 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 693 <big><strong><span class="block">&nbsp;Math::BigFloat - Arbitrary size floating point math package</span></strong></big>
 694 </td></tr>
 695 </table>
 696
 697 </body>
 698
 699 </html>