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

<div id="contentBody"><div class="title_container"><div class="page_title">bigint</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="#Options">Options</a><li><a href="#Math-Library">Math Library</a><li><a href="#Internal-Format">Internal Format</a><li><a href="#Sign">Sign</a><li><a href="#Methods">Methods</a><li><a href="#Caveat">Caveat</a></ul><li><a href="#MODULES-USED">MODULES USED</a><li><a href="#EXAMPLES">EXAMPLES</a><li><a href="#LICENSE">LICENSE</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHORS">AUTHORS</a></ul><a name="NAME"></a><h1>NAME</h1>

<div id="contentBody"><div class="title_container"><div class="page_title">bigint</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="#use-integer-vs.-use-bigint">use integer vs. use bigint</a><li><a href="#Options">Options</a><li><a href="#Math-Library">Math Library</a><li><a href="#Internal-Format">Internal Format</a><li><a href="#Sign">Sign</a><li><a href="#Methods">Methods</a><li><a href="#MATH-LIBRARY">MATH LIBRARY</a><li><a href="#Caveat">Caveat</a></ul><li><a href="#CAVAETS">CAVAETS</a><li><a href="#MODULES-USED">MODULES USED</a><li><a href="#EXAMPLES">EXAMPLES</a><li><a href="#LICENSE">LICENSE</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHORS">AUTHORS</a></ul><a name="NAME"></a><h1>NAME</h1>

bigint - Transparent BigInteger support for Perl

<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="bigint.html">bigint</a>;</pre>

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

<pre class="verbatim"> $x = 2 + 4.5,"\n"; # BigInt 6

<a class="l_k" href="functions/print.html">print</a> 2 ** 512,"\n"; # really is what you think it is

<a class="l_k" href="functions/print.html">print</a> inf + 42,"\n"; # inf

<a class="l_k" href="functions/print.html">print</a> NaN * 7,"\n"; # NaN</pre>

<a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/hex.html">hex</a>("0x1234567890123490"),"\n"; # Perl v5.9.4 or later</pre>

<pre class="verbatim"> {

<a class="l_k" href="functions/no.html">no</a> bigint;

<a class="l_k" href="functions/print.html">print</a> 2 ** 256,"\n"; # a normal Perl scalar now

}</pre>

100

<pre class="verbatim"> # Note that this will be global:

101

<a class="l_k" href="functions/use.html">use</a> bigint qw/hex oct/;

102

103

<a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/oct.html">oct</a>("01234567890123490"),"\n";</pre>

104

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

105

All operators (including basic math operations) are overloaded. Integer

106

constants are created as proper BigInts.

Floating point constants are truncated to integer. All results are also

truncated.

107

Floating point constants are truncated to integer. All parts and results of

108

expressions are also truncated.

109

Unlike <a href="integer.html">integer</a>, this pragma creates integer constants that are only

110

limited in their size by the available memory and CPU time.

111

<a name="use-integer-vs.-use-bigint"></a><h2>use integer vs. use bigint</h2>

112

There is one small difference between <code class="inline"><a class="l_k" href="functions/use.html">use</a> integer</code>

113

and <code class="inline"><a class="l_k" href="functions/use.html">use</a> bigint</code>

114

: the

115

former will not affect assignments to variables and the return value of

116

some functions. <code class="inline">bigint</code>

117

truncates these results to integer too:

118

<pre class="verbatim"> # perl -Minteger -wle 'print 3.2'

119

3.2

120

# perl -Minteger -wle 'print 3.2 + 0'

121

122

# perl -Mbigint -wle 'print 3.2'

123

124

# perl -Mbigint -wle 'print 3.2 + 0'

125

3</pre><pre class="verbatim"> # perl -Mbigint -wle 'print exp(1) + 0'

126

127

# perl -Mbigint -wle 'print exp(1)'

128

129

# perl -Minteger -wle 'print exp(1)'

130

2.71828182845905

131

# perl -Minteger -wle 'print exp(1) + 0'

132

2</pre>In practice this makes seldom a difference as parts and results of

133

expressions will be truncated anyway, but this can, for instance, affect the

134

return value of subroutines:

135

<pre class="verbatim"><a name="three_integer"></a> sub three_integer { <a class="l_k" href="functions/use.html">use</a> integer; <a class="l_k" href="functions/return.html">return</a> 3.2; }

136

<a name="three_bigint"></a> sub three_bigint { <a class="l_k" href="functions/use.html">use</a> bigint; <a class="l_k" href="functions/return.html">return</a> 3.2; }</pre>

137

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"</pre>

138

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

139

bigint recognizes some options that can be passed while loading it via use.

140

The options can (currently) be either a single letter form, or the long form.

102

143

<li><a name="a-or-accuracy"></a>a or accuracy

103

144

This sets the accuracy for all math operations. The argument must be greater

104

145

than or equal to zero. See Math::BigInt's bround() function for details.

105

<pre class="verbatim"> perl -Mbigint=a,2 -le 'print 12345+1'</pre>

146

<pre class="verbatim"> perl -Mbigint=a,2 -le 'print 12345+1'</pre>

147

Note that setting precision and accurary at the same time is not possible.

106

148

</li>

107

149

<li><a name="p-or-precision"></a>p or precision

108

150

This sets the precision for all math operations. The argument can be any

111

153

A positive value rounds to this digit left from the dot. 0 or 1 mean round to

112

154

integer and are ignore like negative values.

113

155

See Math::BigInt's bfround() function for details.

114

<pre class="verbatim"> perl -Mbignum=p,5 -le 'print 123456789+123'</pre>

156

<pre class="verbatim"> perl -Mbignum=p,5 -le 'print 123456789+123'</pre>

157

Note that setting precision and accurary at the same time is not possible.

115

158

</li>

116

159

<li><a name="t-or-trace"></a>t or trace

117

160

This enables a trace mode and is primarily for debugging bigint or

118

161

Math::BigInt.

119

162

</li>

120

<li><a name="l-or-lib"></a>l or lib

121

Load a different math lib, see <a href="#MATH-LIBRARY">"MATH LIBRARY"</a>.

122

<pre class="verbatim"> perl -Mbigint=l,GMP -e 'print 2 ** 512'</pre>

123

Currently there is no way to specify more than one library on the command

124

line. This will be hopefully fixed soon ;)

163

<li><a name="hex"></a>hex

164

Override the built-in hex() method with a version that can handle big

165

integers. Note that under Perl v5.9.4 or ealier, this will be global

166

and cannot be disabled with "no bigint;".

167

</li>

168

<li><a name="oct"></a>oct

169

Override the built-in oct() method with a version that can handle big

170

integers. Note that under Perl v5.9.4 or ealier, this will be global

171

and cannot be disabled with "no bigint;".

172

</li>

173

<li><a name="l%2c-lib%2c-try-or-only"></a>l, lib, try or only

174

Load a different math lib, see <a href="#Math-Library">"Math Library"</a>.

175

<pre class="verbatim"> perl -Mbigint=lib,GMP -e 'print 2 ** 512'

176

perl -Mbigint=try,GMP -e 'print 2 ** 512'

177

perl -Mbigint=only,GMP -e 'print 2 ** 512'</pre>Currently there is no way to specify more than one library on the command

178

line. This means the following does not work:

179

<pre class="verbatim"> perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'</pre>

180

This will be hopefully fixed soon ;)

125

181

</li>

126

182

<li><a name="v-or-version"></a>v or version

127

183

This prints out the name and version of all modules used and then exits.

128

<pre class="verbatim"> perl -Mbigint=v</pre>

184

<pre class="verbatim"> perl -Mbigint=v</pre>

129

185

</li>

130

186

</ul>

131

187

<a name="Math-Library"></a><h2>Math Library</h2>

132

188

Math with the numbers is done (by default) by a module called

133

189

Math::BigInt::Calc. This is equivalent to saying:

134

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="bigint.html">bigint</a> <a class="l_w" href="lib.html">lib</a> => 'Calc';</pre>

190

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> bigint lib => 'Calc';</pre>

135

191

You can change this by using:

136

192

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> bignum lib => 'GMP';</pre>

137

193

The following would first try to find Math::BigInt::Foo, then

138

194

Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

139

195

196

Using <code class="inline">lib</code>

197

warns if none of the specified libraries can be found and

198

<a href="Math/BigInt.html">Math::BigInt</a> did fall back to one of the default libraries.

199

To supress this warning, use <code class="inline">try</code>

200

instead:

201

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> bignum try => 'GMP';</pre>

202

If you want the code to die instead of falling back, use <code class="inline">only</code>

203

instead:

204

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> bignum only => 'GMP';</pre>

140

205

Please see respective module documentation for further details.

141

206

<a name="Internal-Format"></a><h2>Internal Format</h2>

142

207

The numbers are stored as objects, and their internals might change at anytime,

157

222

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

158

223

Since all numbers are now objects, you can use all functions that are part of

159

224

the BigInt API. You can only use the bxxx() notation, and not the fxxx()

160

notation, though.

225

notation, though.

226

<ul>

227

<li><a name="inf()"></a>inf()

228

A shortcut to return Math::BigInt->binf(). Useful because Perl does not always

229

handle bareword <code class="inline">inf</code>

230

properly.

231

</li>

232

<li><a name="NaN()"></a>NaN()

233

A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always

234

handle bareword <code class="inline">NaN</code>

235

properly.

236

</li>

237

<li><a name="e"></a>e

238

<pre class="verbatim"> # perl -Mbigint=e -wle 'print e'</pre>

239

Returns Euler's number <code class="inline">e</code>

240

, aka exp(1). Note that under bigint, this is

241

truncated to an integer, and hence simple '2'.

242

</li>

243

<li><a name="PI"></a>PI

244

<pre class="verbatim"> # perl -Mbigint=PI -wle 'print PI'</pre>

245

Returns PI. Note that under bigint, this is truncated to an integer, and hence

246

simple '3'.

247

</li>

248

<li><a name="bexp()"></a>bexp()

249

<pre class="verbatim"> bexp($power,$accuracy);</pre>

250

Returns Euler's number <code class="inline">e</code>

251

raised to the appropriate power, to

252

the wanted accuracy.

253

Note that under bigint, the result is truncated to an integer.

254

Example:

255

<pre class="verbatim"> # perl -Mbigint=bexp -wle 'print bexp(1,80)'</pre>

256

</li>

257

<li><a name="bpi()"></a>bpi()

258

<pre class="verbatim"> bpi($accuracy);</pre>

259

Returns PI to the wanted accuracy. Note that under bigint, this is truncated

260

to an integer, and hence simple '3'.

261

Example:

262

<pre class="verbatim"> # perl -Mbigint=bpi -wle 'print bpi(80)'</pre>

263

</li>

264

<li><a name="upgrade()"></a>upgrade()

265

Return the class that numbers are upgraded to, is in fact returning

266

<code class="inline">$Math::BigInt::upgrade</code>

267

.

268

</li>

269

<li><a name="in_effect()"></a>in_effect()

270

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

271

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "in effect\n" if bigint::in_effect; # true

272

{

273

<a class="l_k" href="functions/no.html">no</a> bigint;

274

<a class="l_k" href="functions/print.html">print</a> "in effect\n" if bigint::in_effect; # false

275

}</pre>

276

Returns true or false if <code class="inline">bigint</code>

277

is in effect in the current scope.

278

This method only works on Perl v5.9.4 or later.

279

</li>

280

</ul>

281

<a name="MATH-LIBRARY"></a><h2>MATH LIBRARY</h2>

282

Math with the numbers is done (by default) by a module called

161

283

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

162

284

But a warning is in order. When using the following to make a copy of a number,

163

285

only a shallow copy will be made.

168

290

<pre class="verbatim"> $x = 9; $y = $x;

169

291

<a class="l_k" href="functions/print.html">print</a> $x + 1, " ", $y,"\n"; # prints 10 9</pre>

170

292

but calling any method that modifies the number directly will result in

171

both the original and the copy beeing destroyed:

172

173

$x = 9; $y = $x;

174

print $x->badd(1), " ", $y,"\n"; # prints 10 10

175

176

$x = 9; $y = $x;

177

print $x->binc(1), " ", $y,"\n"; # prints 10 10

178

179

$x = 9; $y = $x;

180

print $x->bmul(2), " ", $y,"\n"; # prints 18 18

181

182

Using methods that do not modify, but testthe contents works:

293

both the original and the copy being destroyed:

294

<pre class="verbatim"> $x = 9; $y = $x;

295

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

296

<pre class="verbatim"> $x = 9; $y = $x;

297

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

298

<pre class="verbatim"> $x = 9; $y = $x;

299

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

300

Using methods that do not modify, but testthe contents works:

183

301

<pre class="verbatim"> $x = 9; $y = $x;

184

302

$z = 9 if $x->is_zero(); # works fine</pre>

185

303

See the documentation about the copy constructor and <code class="inline">=</code>

186

304

in overload, as

187

305

well as the documentation in BigInt for further details.

306

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

307

<ul>

308

<li><a name="in_effect()"></a>in_effect()

309

This method only works on Perl v5.9.4 or later.

310

</li>

311

<li><a name="hex()%2foct()"></a>hex()/oct()

312

<code class="inline">bigint</code>

313

overrides these routines with versions that can also handle

314

big integer values. Under Perl prior to version v5.9.4, however, this

315

will not happen unless you specifically ask for it with the two

316

import tags "hex" and "oct" - and then it will be global and cannot be

317

disabled inside a scope with "no bigint":

318

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> bigint qw/hex oct/;</pre>

319

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/hex.html">hex</a>("0x1234567890123456");

320

{

321

<a class="l_k" href="functions/no.html">no</a> bigint;

322

323

}</pre>

324

The second call to hex() will warn about a non-portable constant.

325

Compare this to:

326

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

327

<pre class="verbatim"> # will warn only under Perl older than v5.9.4

328

329

</li>

330

</ul>

188

331

<a name="MODULES-USED"></a><h1>MODULES USED</h1>

189

<code class="inline"><a class="l_w" href="bigint.html">bigint</a></code> is just a thin wrapper around various modules of the Math::BigInt

332

<code class="inline">bigint</code>

333

is just a thin wrapper around various modules of the Math::BigInt

190

334

family. Think of it as the head of the family, who runs the shop, and orders

191

335

the others to do the work.

192

336

The following modules are currently used by bigint:

193

337

<pre class="verbatim"> Math::BigInt::Lite (for speed, and only if it is loadable)

194

338

Math::BigInt</pre><a name="EXAMPLES"></a><h1>EXAMPLES</h1>

195

339

Some cool command line examples to impress the Python crowd ;) You might want

196

to compare them to the results under -Mbignum or -Mbigrat:

197

198

perl -Mbigint -le 'print sqrt(33)'

340

to compare them to the results under -Mbignum or -Mbigrat:

341

<pre class="verbatim"> perl -Mbigint -le 'print sqrt(33)'

199

342

perl -Mbigint -le 'print 2*255'

200

343

perl -Mbigint -le 'print 4.5+2*255'

201

344

perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'

202

345

perl -Mbigint -le 'print 123->is_odd()'

203

346

perl -Mbigint -le 'print log(2)'

204

347

perl -Mbigint -le 'print 2 ** 0.5'

205

perl -Mbigint=a,65 -le 'print 2 ** 0.2'

206

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

348

perl -Mbigint=a,65 -le 'print 2 ** 0.2'

349

perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'</pre><a name="LICENSE"></a><h1>LICENSE</h1>

207

350

This program is free software; you may redistribute it and/or modify it under

208

351

the same terms as Perl itself.

209

352

210

Especially <a href="bigrat.html">bigrat</a> as in <code class="inline">perl -Mbigrat -le 'print 1/3+1/4'</code>

353

Especially <a href="bigrat.html">bigrat</a> as in <code class="inline">perl -Mbigrat -le 'print 1/3+1/4'</code>

211

354

and

212

<a href="bignum.html">bignum</a> as in <code class="inline">perl -Mbignum -le 'print sqrt(2)'</code>

355

<a href="bignum.html">bignum</a> as in <code class="inline">perl -Mbignum -le 'print sqrt(2)'</code>

213

356

.

214

357

<a href="Math/BigInt.html">Math::BigInt</a>, <a href="Math/BigRat.html">Math::BigRat</a> and <a href="http://search.cpan.org/perldoc/Math::Big">Math::Big</a> as well

215

358

as <a href="http://search.cpan.org/perldoc/Math::BigInt::BitVect">Math::BigInt::BitVect</a>, <a href="http://search.cpan.org/perldoc/Math::BigInt::Pari">Math::BigInt::Pari</a> and <a href="http://search.cpan.org/perldoc/Math::BigInt::GMP">Math::BigInt::GMP</a>.

216

359

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

217

(C) by Tels <a href="http://bloodgate.com/">http://bloodgate.com/</a> in early 2002 - 2005.

360

(C) by Tels <a href="http://bloodgate.com/">http://bloodgate.com/</a> in early 2002 - 2007.

218

361

</div>

219

362

220

363

</div>

232

375

233

376

</form>

234

377

378

235

379

<h2>Labels:</h2>

236

380

237

381

Older »