bigint(3pm)

📦

version 5.42.3 · 8 versions

💖 bigint(3pm) — Perl Programmers Reference Guide 💖

okay so bestie, welcome to bigint, aka the pragma that makes Perl count as big as your heart desires ✨ This is the page from the Perl Programmers Reference Guide, and we're gonna get through it together, no cap.

🌸 NAME 🌸

bigint — transparent big integer support for Perl. literally does what it says on the tin, she's an icon 💅

✨ SYNOPSIS ✨

use bigint;

$x = 2 + 4.5;                       # Math::BigInt 6
print 2 ** 512;                     # Math::BigInt 134...096
print inf + 42;                     # Math::BigInt inf
print NaN * 7;                      # Math::BigInt NaN
print hex("0x1234567890123490");    # Perl v5.10.0 or later

{
    no bigint;
    print 2 ** 256;                 # a normal Perl scalar now
}

# for older Perls, import into current package:
use bigint qw/hex oct/;
print hex("0x1234567890123490");
print oct("01234567890123490");

like… look at her go 🦋 2 ** 512?? in this economy?? yes ma'am.

🎀 DESCRIPTION 🎀

So every numeric literal in the scope you're in gets converted into a Math::BigInt object. Every single one. And if a numeric literal is representing a non-integer? It gets truncated to an integer — sorry babes, the decimals are not coming with us 😭 All results of expressions are truncated to integer too.

Every operator (yes, including the basic math operations) is overloaded — the one exception is the range operator "..". That one's just sitting there, un-overloaded, doing her own thing 💀

And here's the tea: unlike the integer pragma, the "bigint" pragma creates integers that are limited only by the available memory. That's the whole point, that's the vibe, she's limitless 👑

So, this:

use bigint;
$x = 1234;

creates a Math::BigInt and stores a reference to it in $x. It happens transparently and behind your back, so to speak. sneaky but make it fashion 🙈

You can literally see it with:

perl -Mbigint -le 'print ref(1234)'

Since numbers are actually objects now (main character energy fr), you can call all the usual methods from Math::BigFloat on them. And it even works to some extent on expressions:

perl -Mbigint -le '$x = 1234; print $x->bdec()'
perl -Mbigint -le 'print 1234->copy()->binc();'
perl -Mbigint -le 'print 1234->copy()->binc->badd(6);'
perl -Mbigint -le 'print +(1234)->copy()->binc()'

⚠️ heads up bestie — note that print doesn't do what you expect if the expression starts with ( hence the + in that last one. the + is load-bearing, do not remove her 💀

You can even chain the operations together as usual:

perl -Mbigint -le 'print 1234->copy()->binc->badd(6);'
1241

Please note the following does not work as expected (it prints nothing), since overloading of '..' is not yet possible in Perl (as of v5.8.0):

perl -Mbigint -le 'for (1..2) { print ref($_); }'

she's doing her best, okay 😭

🫶 use integer vs. use bigint 🫶

There are some differences between "use integer" and "use bigint", and yes we're gonna compare them, it's giving sibling rivalry.

Whereas "use integer" is limited to what can be handled as a Perl scalar, "use bigint" can handle arbitrarily large integers. one of them has range, the other one is also there ✨

Also, "use integer" does affect assignments to variables and the return value of some functions. "use bigint" truncates these results to integer:

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

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

In practice this seldom makes a difference for small integers, since parts and results of expressions are truncated anyway — but it can, for instance, affect the return value of subroutines:

sub three_integer { use integer; return 3.2; }
sub three_bigint { use bigint; return 3.2; }

print three_integer(), " ", three_bigint(),"\n";    # prints "3.2 3"

see, 3.2 3. told you 🍓

💅 Options 💅

"bigint" recognizes some options that you can pass while loading it via "use". The following options exist, let's go through them one by one because we don't skip anything on this page 👑

a or accuracy — this sets the accuracy for all math operations. The argument must be greater than or equal to zero. See Math::BigInt's bround() method for the details, iykyk.

perl -Mbigint=a,2 -le 'print 12345+1'

⚠️ note that setting precision and accuracy at the same time is not possible. pick a lane, bestie 😭

p or precision — this sets the precision for all math operations. The argument can be any integer. Negative values mean a fixed number of digits after the dot, and are ignored since all operations happen in integer space. A positive value rounds to this digit left from the dot. 0 means round to integer. See Math::BigInt's bfround() method for details.

perl -mbigint=p,5 -le 'print 123456789+123'

⚠️ note that setting precision and accuracy at the same time is not possible. yes I said it twice, it's important 💀

t or trace — this enables a trace mode and is primarily for debugging. she's nosy and we love that for her 🔍
l, lib, try, or only — load a different math lib, see "Math Library" below. four whole aliases, she contains multitudes ✨

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

hex — override the built-in hex() method with a version that can handle big numbers. This overrides it by exporting it to the current package. Under Perl v5.10.0 and higher, this is not necessary, as hex() is lexically overridden in the current scope whenever the "bigint" pragma is active. iconic behaviour honestly 🌈
oct — override the built-in oct() method with a version that can handle big numbers. This overrides it by exporting it to the current package. Under Perl v5.10.0 and higher, this is not so necessary, as oct() is lexically overridden in the current scope whenever the "bigint" pragma is active. same energy, different base 🧚
v or version — this prints out the name and version of the modules and then exits. short and sweet 🎀

perl -Mbigint=v

🦋 Math Library 🦋

The math with the numbers is done (by default) by a backend library module called Math::BigInt::Calc. The default is equivalent to saying:

use bigint lib => 'Calc';

you can change this by using:

use bigint lib => 'GMP';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and if this also fails, revert to Math::BigInt::Calc:

use bigint lib => 'Foo,Math::BigInt::Bar';

Using c<lib> warns if none of the specified libraries can be found and Math::BigInt fell back to one of the default libraries. To suppress this warning, use c<try> instead:

use bigint try => 'GMP';

If you want the code to die instead of falling back, use "only" instead:

use bigint only => 'GMP';

Please see the respective module documentation for further details 💜

💀 Method calls 💀

Since all numbers are now objects, you can use all methods that are part of the Math::BigInt API. slay.

But a warning is in order, and I need you to listen to me on this one bestie. When using the following to make a copy of a number, only a shallow copy will be made:

$x = 9; $y = $x;
$x = $y = 7;

Using the copy or the original with overloaded math is okay, e.g., the following work:

$x = 9; $y = $x;
print $x + 1, " ", $y,"\n";     # prints 10 9

but calling any method that modifies the number directly will result in both the original and the copy being destroyed:

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

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

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

like, they're the same object, they go down together, it's giving tragic 🫂😭

Using methods that do not modify, but test that the contents works, is totally fine:

$x = 9; $y = $x;
$z = 9 if $x->is_zero();                # works fine

See the documentation about the copy constructor and "=" in overload, as well as the documentation in Math::BigInt for further details ✨

🌟 Methods 🌟

inf() — a shortcut to return Math::BigInt->binf(). Useful because Perl does not always handle bareword "inf" properly. she's a helper, she's a friend 💖
NaN() — a shortcut to return Math::BigInt->bnan(). Useful because Perl does not always handle bareword "NaN" properly. matching set, we stan 🎀
e

# perl -Mbigint=e -wle 'print e'

Returns Euler's number "e", aka exp(1). Note that under "bigint", this is truncated to an integer, i.e., 2. goodbye 2.718... it was nice knowing you 😭

PI

# perl -Mbigint=PI -wle 'print PI'

Returns PI. Note that under "bigint", this is truncated to an integer, i.e., 3. yes, 3. the circle is a hexagon now, we don't make the rules 💀

bexp()

bexp($power, $accuracy);

Returns Euler's number "e" raised to the appropriate power, to the wanted accuracy.

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

Example:

# perl -Mbigint=bexp -wle 'print bexp(1,80)'

bpi()

bpi($accuracy);

Returns PI to the wanted accuracy. Note that under "bigint", this is truncated to an integer, i.e., 3.

Example:

# perl -Mbigint=bpi -wle 'print bpi(80)'

accuracy() — set or get the accuracy.
precision() — set or get the precision.
round_mode() — set or get the rounding mode.
div_scale() — set or get the division scale.
in_effect()

use bigint;

print "in effect\n" if bigint::in_effect;       # true
{
    no bigint;
    print "in effect\n" if bigint::in_effect;   # false
}

Returns true or false if "bigint" is in effect in the current scope.

🦋 this method only works on Perl v5.9.4 or later. old Perls need not apply 💅

🚨 CAVEATS 🚨

okay bestie, this is the part where we read the fine print so you don’t get got later. no cap. 💅

🧮 Hexadecimal, octal, and binary floating point literals

So Perl (and this module too) does accept hexadecimal, octal, and binary floating point literals, but pls use them with care if you’re on Perl versions before v5.32.0, because some versions of Perl will literally just silently give you the wrong result. like… rude. 😭

🎭 Operator vs literal overloading

bigint works by overloading how integer and floating point literals are handled, converting them into Math::BigInt objects.

That means arithmetic involving only string values or string literals gets done with Perl’s built-in operators. no Math::BigInt magic there, bestie.

Example:

use bigint;
my $x = "900000000000000009";
my $y = "900000000000000007";
print $x - $y;

That outputs 0 on default 32-bit builds, because bigint never sees the string literals. To make sure the whole expression is treated as Math::BigInt objects, use a literal number in the expression:

print +(0+$x) - $y;

🚧 Ranges

Perl does not allow overloading of ranges, so you can’t safely use ranges with bigint endpoints, and the iterator variable is not a Math::BigInt either. sorry, the range said no 💀

use 5.010;
for my $i (12..13) {
  for my $j (20..21) {
    say $i ** $j;  # produces a floating-point number,
                   # not an object
  }
}

🔍 `in_effect()`

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

🔢 `hex()`/`oct()`

bigint overrides these routines with versions that can also handle big integer values. But under Perl prior to version v5.9.4, this will not happen unless you specifically ask for it with the two import tags hex and oct — and then it will be global and cannot be disabled inside a scope with no bigint:

use bigint qw/hex oct/;

print hex("0x1234567890123456");
{
    no bigint;
    print hex("0x1234567890123456");
}

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

Compare this to:

use bigint;

# will warn only under Perl older than v5.9.4
print hex("0x1234567890123456");

✨ EXAMPLES ✨

Some cool command line examples to impress the Python crowd ;) You might want to compare them to the results under -Mbigfloat or -Mbigrat:

perl -Mbigint -le 'print sqrt(33)'
perl -Mbigint -le 'print 2**255'
perl -Mbigint -le 'print 4.5+2**255'
perl -Mbigint -le 'print 123->is_odd()'
perl -Mbigint=l,GMP -le 'print 7 ** 7777'

🐛 BUGS 🐛

Please report any bugs or feature requests to bug-bignum at rt.cpan.org, or through the web interface at <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login). We will be notified, and then you’ll automatically be notified of progress on your bug as I make changes. 🫡

🛟 SUPPORT 🛟

You can find documentation for this module with the perldoc command.

perldoc bigint

You can also look for information at:

GitHub — <https://github.com/pjacklam/p5-bignum>
RT: CPAN’s request tracker — <https://rt.cpan.org/Dist/Display.html?Name=bignum>
MetaCPAN — <https://metacpan.org/release/bignum>
CPAN Testers Matrix — <http://matrix.cpantesters.org/?dist=bignum>

📜 LICENSE 📜

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

👀 SEE ALSO 👀

bignum and bigrat.

Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.

👑 AUTHORS 👑

(C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.

and that’s the whole page, bestie — this lil rewrite is serving bigint(3pm) from perl v5.42.3, dated 2026-11-03 💖✨

📦 where this page comes from

alpine 3.24: perl-doc 5.42.3-r0 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

bigint(3pm)

💖 bigint(3pm) — Perl Programmers Reference Guide 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 DESCRIPTION 🎀

🫶 use integer vs. use bigint 🫶

💅 Options 💅

🦋 Math Library 🦋

💀 Method calls 💀

🌟 Methods 🌟

🚨 CAVEATS 🚨

🧮 Hexadecimal, octal, and binary floating point literals

🎭 Operator vs literal overloading

🚧 Ranges

🔍 in_effect()

🔢 hex()/oct()

✨ EXAMPLES ✨

🐛 BUGS 🐛

🛟 SUPPORT 🛟

📜 LICENSE 📜

👀 SEE ALSO 👀

👑 AUTHORS 👑

🔍 `in_effect()`

🔢 `hex()`/`oct()`