~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

<div id="breadCrumbs"><a href="../index.html">Home</a> > <a href="../index-modules-A.html">Core modules</a> > <a href="../index-modules-M.html">M</a> > Math::BigFloat</div>

<div id="contentBody"><div class="title_container"><div class="page_title">Math::BigFloat</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Canonical-notation">Canonical notation</a><li><a href="#Output">Output</a><li><a href="#'mantissa()'%2c-'exponent()'-and-'parts()'"><code class="inline">mantissa()</code>

, <code class="inline">exponent()</code>

and <code class="inline">parts()</code>

</a><li><a href="#Accuracy-vs.-Precision">Accuracy vs. Precision</a><li><a href="#Rounding">Rounding</a></ul><li><a href="#METHODS">METHODS</a><ul><li><a href="#accuracy">accuracy</a><li><a href="#precision()">precision()</a><li><a href="#bexp()">bexp()</a><li><a href="#bnok()">bnok()</a><li><a href="#bpi()">bpi()</a><li><a href="#bcos()">bcos()</a><li><a href="#bsin()">bsin()</a><li><a href="#batan2()">batan2()</a><li><a href="#batan()">batan()</a><li><a href="#bmuladd()">bmuladd()</a></ul><li><a href="#Autocreating-constants">Autocreating constants</a><ul><li><a href="#Math-library">Math library</a><li><a href="#Using-Math%3a%3aBigInt%3a%3aLite">Using Math::BigInt::Lite</a></ul><li><a href="#EXPORTS">EXPORTS</a><li><a href="#BUGS">BUGS</a><li><a href="#CAVEATS">CAVEATS</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#LICENSE">LICENSE</a><li><a href="#AUTHORS">AUTHORS</a></ul><a name="NAME"></a><h1>NAME</h1>

Math::BigFloat - Arbitrary size floating point math package

<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>;</pre>

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> Math::BigFloat;</pre>

<pre class="verbatim"> # Number creation

$x = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->new($str); # defaults to 0

$nan = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->bnan(); # create a NotANumber

$zero = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->bzero(); # create a +0

$inf = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->binf(); # create a +inf

$inf = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->binf('-'); # create a -inf

$one = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->bone(); # create a +1

$one = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->bone('-'); # create a -1</pre>

<a class="l_k" href="../functions/my.html">my</a> $x = Math::BigFloat->new($str); # defaults to 0

<a class="l_k" href="../functions/my.html">my</a> $y = $x->copy(); # make a true copy

<a class="l_k" href="../functions/my.html">my</a> $nan = Math::BigFloat->bnan(); # create a NotANumber

<a class="l_k" href="../functions/my.html">my</a> $zero = Math::BigFloat->bzero(); # create a +0

<a class="l_k" href="../functions/my.html">my</a> $inf = Math::BigFloat->binf(); # create a +inf

100

<a class="l_k" href="../functions/my.html">my</a> $inf = Math::BigFloat->binf('-'); # create a -inf

101

<a class="l_k" href="../functions/my.html">my</a> $one = Math::BigFloat->bone(); # create a +1

102

<a class="l_k" href="../functions/my.html">my</a> $mone = Math::BigFloat->bone('-'); # create a -1</pre>

103

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $pi = Math::BigFloat->bpi(100); # PI to 100 digits</pre>

104

<pre class="verbatim"> # the following examples compute their result to 100 digits accuracy:

105

<a class="l_k" href="../functions/my.html">my</a> $cos = Math::BigFloat->new(1)->bcos(100); # cosinus(1)

106

<a class="l_k" href="../functions/my.html">my</a> $sin = Math::BigFloat->new(1)->bsin(100); # sinus(1)

107

<a class="l_k" href="../functions/my.html">my</a> $atan = Math::BigFloat->new(1)->batan(100); # arcus tangens(1)</pre>

108

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $atan2 = Math::BigFloat->new( 1 )->batan2( 1 ,100); # batan(1)

109

<a class="l_k" href="../functions/my.html">my</a> $atan2 = Math::BigFloat->new( 1 )->batan2( 8 ,100); # batan(1/8)

110

<a class="l_k" href="../functions/my.html">my</a> $atan2 = Math::BigFloat->new( -2 )->batan2( 1 ,100); # batan(-2)</pre>

111

<pre class="verbatim"> # Testing

100

112

$x->is_zero(); # true if arg is +0

101

113

$x->is_nan(); # true if arg is NaN

105

117

$x->is_even(); # true if even, false for odd

106

118

$x->is_pos(); # true if >= 0

107

119

$x->is_neg(); # true if < 0

108

$x->is_inf(sign); # true if +inf, or -inf (default is '+')</pre>

120

$x->is_inf(sign); # true if +inf, or -inf (default is '+')</pre>

109

121

<pre class="verbatim"> $x->bcmp($y); # compare numbers (undef,<0,=0,>0)

110

122

$x->bacmp($y); # compare absolutely (undef,<0,=0,>0)

111

123

$x->sign(); # return the sign, either +,- or NaN

112

124

$x->digit($n); # return the nth digit, counting from right

113

$x->digit(-$n); # return the nth digit, counting from left </pre>

125

114

126

<pre class="verbatim"> # The following all modify their first argument. If you want to preserve

115

127

# $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is

116

# neccessary when mixing $a = $b assigments with non-overloaded math.

117

118

# set

128

# necessary when mixing $a = $b assignments with non-overloaded math.</pre>

129

<pre class="verbatim"> # set

119

130

$x->bzero(); # set $i to 0

120

131

$x->bnan(); # set $i to NaN

121

132

$x->bone(); # set $x to +1

127

138

$x->bnorm(); # normalize (no-op)

128

139

$x->bnot(); # two's complement (bit wise not)

129

140

$x->binc(); # increment x by 1

130

$x->bdec(); # decrement x by 1

131

132

$x->badd($y); # addition (add $y to $x)

141

$x->bdec(); # decrement x by 1</pre>

142

<pre class="verbatim"> $x->badd($y); # addition (add $y to $x)

133

143

$x->bsub($y); # subtraction (subtract $y from $x)

134

144

$x->bmul($y); # multiplication (multiply $x by $y)

135

145

$x->bdiv($y); # divide, set $x to quotient

136

146

# return (quo,rem) or quo if scalar</pre>

137

147

<pre class="verbatim"> $x->bmod($y); # modulus ($x % $y)

138

148

$x->bpow($y); # power of arguments ($x ** $y)

139

$x->blsft($y); # left shift

140

$x->brsft($y); # right shift

141

# return (quo,rem) or quo if scalar

142

143

$x->blog(); # logarithm of $x to base e (Euler's number)

149

$x->bmodpow($exp,$mod); # modular exponentation (($num**$exp) % $mod))

150

$x->blsft($y, $n); # left shift by $y places in base $n

151

$x->brsft($y, $n); # right shift by $y places in base $n

152

# returns (quo,rem) or quo if in scalar context</pre>

153

<pre class="verbatim"> $x->blog(); # logarithm of $x to base e (Euler's number)

144

154

$x->blog($base); # logarithm of $x to base $base (f.i. 2)

145

146

$x->band($y); # bit-wise and

155

$x->bexp(); # calculate e ** $x where e is Euler's number</pre>

156

<pre class="verbatim"> $x->band($y); # bit-wise and

147

157

$x->bior($y); # bit-wise inclusive or

148

158

$x->bxor($y); # bit-wise exclusive or

149

$x->bnot(); # bit-wise not (two's complement)

150

151

$x->bsqrt(); # calculate square-root

159

$x->bnot(); # bit-wise not (two's complement)</pre>

160

<pre class="verbatim"> $x->bsqrt(); # calculate square-root

152

161

$x->broot($y); # $y'th root of $x (e.g. $y == 3 => cubic root)

153

$x->bfac(); # factorial of $x (1*2*3*4*..$x)

154

155

$x->bround($N); # accuracy: preserve $N digits

162

$x->bfac(); # factorial of $x (1*2*3*4*..$x)</pre>

163

<pre class="verbatim"> $x->bround($N); # accuracy: preserve $N digits

156

164

$x->bfround($N); # precision: round to the $Nth digit</pre>

157

165

<pre class="verbatim"> $x->bfloor(); # return integer less or equal than $x

158

166

$x->bceil(); # return integer greater or equal than $x</pre>

159

167

<pre class="verbatim"> # The following do not modify their arguments:</pre>

160

168

<pre class="verbatim"> bgcd(@values); # greatest common divisor

161

blcm(@values); # lowest common multiplicator

162

163

$x->bstr(); # return string

169

blcm(@values); # lowest common multiplicator</pre>

170

<pre class="verbatim"> $x->bstr(); # return string

164

171

$x->bsstr(); # return string in scientific notation</pre>

165

172

<pre class="verbatim"> $x->as_int(); # return $x as BigInt

166

173

$x->exponent(); # return exponent as BigInt

167

174

$x->mantissa(); # return mantissa as BigInt

168

175

$x->parts(); # return (mantissa,exponent) as BigInt</pre>

169

176

<pre class="verbatim"> $x->length(); # number of digits (w/o sign and '.')

170

($l,$f) = $x->length(); # number of digits, and length of fraction </pre>

177

171

178

<pre class="verbatim"> $x->precision(); # return P of $x (or global, if P of $x undef)

172

179

$x->precision($n); # set P of $x to $n

173

180

$x->accuracy(); # return A of $x (or global, if A of $x undef)

174

181

$x->accuracy($n); # set A $x to $n</pre>

175

182

<pre class="verbatim"> # these get/set the appropriate global value for all BigFloat objects

176

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->precision(); # Precision

177

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->accuracy(); # Accuracy

178

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->round_mode(); # rounding mode</pre>

183

Math::BigFloat->precision(); # Precision

184

Math::BigFloat->accuracy(); # Accuracy

185

Math::BigFloat->round_mode(); # rounding mode</pre>

179

186

<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>

180

All operators (inlcuding basic math operations) are overloaded if you

187

All operators (including basic math operations) are overloaded if you

181

188

declare your big floating point numbers as

182

<pre class="verbatim"> $i = new <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a> '12_3.456_789_123_456_789E-2';</pre>

189

<pre class="verbatim"> $i = new Math::BigFloat '12_3.456_789_123_456_789E-2';</pre>

183

190

Operations with overloaded operators preserve the arguments, which is

184

191

exactly what you expect.

185

192

<a name="Canonical-notation"></a><h2>Canonical notation</h2>

203

210

204

211

</li>

205

212

</ul>

206

all with optional leading and trailing zeros and/or spaces. Additonally,

213

all with optional leading and trailing zeros and/or spaces. Additionally,

207

214

numbers are allowed to have an underscore between any two digits.

208

215

Empty strings as well as other illegal numbers results in 'NaN'.

209

216

bnorm() on a BigFloat object is now effectively a no-op, since the numbers

231

238

, <code class="inline">bacmp()</code>

232

239

)

233

240

return either undef, <0, 0 or >0 and are suited for sort.

234

Actual math is done by using the class defined with <code class="inline">with =</code>

241

Actual math is done by using the class defined with <code class="inline">with =</code>

235

242

Class;> (which

236

243

defaults to BigInts) to represent the mantissa and exponent.

237

244

The sign <code class="inline">/^[+-]$/</code>

271

278

If there is no gloabl precision or accuracy set, and the operation in

272

279

question was not called with a requested precision or accuracy, and the

273

280

input $x has no accuracy or precision set, then a fallback parameter will

274

be used. For historical reasons, it is called <code class="inline">div_scale</code>

281

be used. For historical reasons, it is called <code class="inline">div_scale</code>

275

282

and can be accessed

276

283

via:

277

<pre class="verbatim"> $d = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->div_scale(); # query

278

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->div_scale($n); # set to $n digits</pre>

279

The default value for <code class="inline">div_scale</code>

284

<pre class="verbatim"> $d = Math::BigFloat->div_scale(); # query

285

Math::BigFloat->div_scale($n); # set to $n digits</pre>

286

The default value for <code class="inline">div_scale</code>

280

287

is 40.

281

288

In case the result of one operation has more digits than specified,

282

289

it is rounded. The rounding mode taken is either the default mode, or the one

283

290

supplied to the operation after the scale:

284

<pre class="verbatim"> $x = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->new(2);

285

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->accuracy(5); # 5 digits max

291

<pre class="verbatim"> $x = Math::BigFloat->new(2);

292

Math::BigFloat->accuracy(5); # 5 digits max

286

293

287

294

$y = $x->copy()->bdiv(3,6); # will give 0.666667

288

295

$y = $x->copy()->bdiv(3,6,<a class="l_k" href="../functions/undef.html">undef</a>,'odd'); # will give 0.666667

289

<a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->round_mode('zero');

296

Math::BigFloat->round_mode('zero');

290

297

291

Note that <code class="inline"><a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->accuracy()</code>

292

and <code class="inline"><a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->precision()</code>

298

Note that <code class="inline">Math::BigFloat->accuracy()</code>

299

and <code class="inline">Math::BigFloat->precision()</code>

293

300

294

301

set the global variables, and thus any newly created number will be subject

295

to the global rounding immidiately. This means that in the examples above, the

302

to the global rounding immediately. This means that in the examples above, the

296

303

297

304

as argument to <code class="inline">bdiv()</code>

298

305

will also get an accuracy of 5.

299

306

It is less confusing to either calculate the result fully, and afterwards

300

round it explicitely, or use the additional parameters to the math

307

round it explicitly, or use the additional parameters to the math

301

308

functions like so:

302

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>;

303

$x = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->new(2);

309

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> Math::BigFloat;

310

$x = Math::BigFloat->new(2);

304

311

305

312

<a class="l_k" href="../functions/print.html">print</a> $y->bround(5),"\n"; # will give 0.66667</pre>

306

313

307

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>;

308

$x = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->new(2);

314

<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> Math::BigFloat;

315

$x = Math::BigFloat->new(2);

309

316

$y = $x->copy()->bdiv(3,5); # will give 0.66667

310

317

<a class="l_k" href="../functions/print.html">print</a> "$y\n";</pre>

311

318

<a name="Rounding"></a><h2>Rounding</h2>

312

319

<ul>

313

320

<li><a name="ffround-(-%2b%24scale-)"></a>ffround ( +$scale )

314

321

Rounds to the $scale'th place left from the '.', counting from the dot.

315

The first digit is numbered 1.

322

The first digit is numbered 1.

316

323

</li>

317

324

<li><a name="ffround-(--%24scale-)"></a>ffround ( -$scale )

318

325

Rounds to the $scale'th place right from the '.', counting from the dot.

330

337

</li>

331

338

</ul>

332

339

All rounding functions take as a second parameter a rounding mode from one of

333

the following: 'even', 'odd', '+inf', '-inf', 'zero' or 'trunc'.

340

the following: 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'.

334

341

The default rounding mode is 'even'. By using

335

<code class="inline"><a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->round_mode($round_mode);</code>

342

<code class="inline">Math::BigFloat->round_mode($round_mode);</code>

336

343

you can get and set the default

337

344

mode for subsequent rounding. The usage of <code class="inline">$Math::BigFloat::$round_mode</code> is

338

345

no longer supported.

339

346

The second parameter to the round functions then overrides the default

340

temporarily.

347

temporarily.

341

348

The <code class="inline">as_number()</code>

342

349

function returns a BigInt from a Math::BigFloat. It uses

343

350

'trunc' as rounding mode to make it equivalent to:

346

353

You can override this by passing the desired rounding mode as parameter to

347

354

<code class="inline">as_number()</code>

348

355

:

349

<pre class="verbatim"> $x = <a class="l_w" href="../Math/BigFloat.html">Math::BigFloat</a>->new(2.5);

356

<pre class="verbatim"> $x = Math::BigFloat->new(2.5);

350

357

$y = $x->as_number('odd'); # $y = 3</pre>

351

358

<a name="METHODS"></a><h1>METHODS</h1>

359

Math::BigFloat supports all methods that Math::BigInt supports, except it

360

calculates non-integer results when possible. Please see <a href="../Math/BigInt.html">Math::BigInt</a>

361

for a full description of each method. Below are just the most important

362

differences:

352

363

<a name="accuracy"></a><h2>accuracy</h2>

353

364

<pre class="verbatim"> $x->accuracy(5); # local for $x

354

CLASS->accuracy(5); # global for all members of CLASS

365

CLASS->accuracy(5); # global for all members of CLASS

355

366

# Note: This also applies to new()!</pre>

356

367

<pre class="verbatim"> $A = $x->accuracy(); # read out accuracy that affects $x

357

$A = CLASS->accuracy(); # read out global accuracy</pre>

368

$A = CLASS->accuracy(); # read out global accuracy</pre>

358

369

Set or get the global or local accuracy, aka how many significant digits the

359

370

results have. If you set a global accuracy, then this also applies to new()!

360

371

Warning! The accuracy sticks, e.g. once you created a number under the

361

influence of <code class="inline">CLASS->accuracy($A)</code>

372

influence of <code class="inline">CLASS->accuracy($A)</code>

362

373

, all results from math operations with

363

374

that number will also be rounded.

364

In most cases, you should probably round the results explicitely using one of

375

In most cases, you should probably round the results explicitly using one of

365

376

round(), bround() or bfround() or by passing the desired accuracy

366

377

to the math operation as additional parameter:

367

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $x = <a class="l_w" href="../Math/BigInt.html">Math::BigInt</a>->new(30000);

368

<a class="l_k" href="../functions/my.html">my</a> $y = <a class="l_w" href="../Math/BigInt.html">Math::BigInt</a>->new(7);

378

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $x = Math::BigInt->new(30000);

379

<a class="l_k" href="../functions/my.html">my</a> $y = Math::BigInt->new(7);

369

380

<a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/scalar.html">scalar</a> $x->copy()->bdiv($y, 2); # print 4300

370

381

<a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/scalar.html">scalar</a> $x->copy()->bdiv($y)->bround(2); # print 4300</pre>

371

382

<a name="precision()"></a><h2>precision()</h2>

372

383

<pre class="verbatim"> $x->precision(-2); # local for $x, round at the second digit right of the dot

373

384

$x->precision(2); # ditto, round at the second digit left of the dot</pre>

374

<pre class="verbatim"> CLASS->precision(5); # Global for all members of CLASS

385

<pre class="verbatim"> CLASS->precision(5); # Global for all members of CLASS

375

386

# This also applies to new()!

376

CLASS->precision(-5); # ditto</pre>

377

<pre class="verbatim"> $P = CLASS->precision(); # read out global precision

387

CLASS->precision(-5); # ditto</pre>

388

<pre class="verbatim"> $P = CLASS->precision(); # read out global precision

378

389

$P = $x->precision(); # read out precision that affects $x</pre>

379

390

Note: You probably want to use accuracy() instead. With <a href="http://search.cpan.org/perldoc/accuracy">accuracy</a> you

380

391

set the number of digits each result should have, with <a href="http://search.cpan.org/perldoc/precision">precision</a> you

381

392

set the place where to round!

393

394

<pre class="verbatim"> $x->bexp($accuracy); # calculate e ** X</pre>

395

Calculates the expression <code class="inline">e ** $x</code>

396

where <code class="inline">e</code>

397

is Euler's number.

398

This method was added in v1.82 of Math::BigInt (April 2007).

399

400

<pre class="verbatim"> $x->bnok($y); # x over y (binomial coefficient n over k)</pre>

401

Calculates the binomial coefficient n over k, also called the "choose"

402

function. The result is equivalent to:

403

<pre class="verbatim"> ( n ) n!

404

| - | = -------

405

( k ) k!(n-k)!</pre>This method was added in v1.84 of Math::BigInt (April 2007).

406

407

<pre class="verbatim"> <a class="l_k" href="../functions/print.html">print</a> Math::BigFloat->bpi(100), "\n";</pre>

408

Calculate PI to N digits (including the 3 before the dot). The result is

409

rounded according to the current rounding mode, which defaults to "even".

410

This method was added in v1.87 of Math::BigInt (June 2007).

411

412

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $x = Math::BigFloat->new(1);

413

<a class="l_k" href="../functions/print.html">print</a> $x->bcos(100), "\n";</pre>

414

Calculate the cosinus of $x, modifying $x in place.

415

This method was added in v1.87 of Math::BigInt (June 2007).

416

417

418

<a class="l_k" href="../functions/print.html">print</a> $x->bsin(100), "\n";</pre>

419

Calculate the sinus of $x, modifying $x in place.

420

This method was added in v1.87 of Math::BigInt (June 2007).

421

<a name="batan2()"></a><h2>batan2()</h2>

422

<pre class="verbatim"> <a class="l_k" href="../functions/my.html">my</a> $y = Math::BigFloat->new(2);

423

<a class="l_k" href="../functions/my.html">my</a> $x = Math::BigFloat->new(3);

424

<a class="l_k" href="../functions/print.html">print</a> $y->batan2($x), "\n";</pre>

425

Calculate the arcus tanges of <code class="inline">$y</code>

426

divided by <code class="inline">$x</code>

427

, modifying $y in place.

428