bigrat(3pm)

💖 bigrat(3pm) — the bigrat pragma, explained by your favorite Perl bestie 💖

okay so real talk, this page is bigrat(3pm) from the Perl Programmers Reference Guide, and it's literally the moment your numbers stop being little baby floats and start being exact rationals. no cap. let's get into it 🎀

---

✨ NAME ✨

bigrat — transparent big rational number support for Perl 🧚

like, transparent. you don't even see it happening. it's giving invisible main character energy.

---

🌸 SYNOPSIS 🌸

use bigrat;

print 2 + 4.5;                      # Math::BigRat 13/2
print 1/3 + 1/4;                    # Math::BigRat 7/12
print inf + 42;                     # Math::BigRat inf
print NaN * 7;                      # Math::BigRat NaN
print hex("0x1234567890123490");    # Perl v5.10.0 or later

{
    no bigrat;
    print 1/3;                      # 0.33333...
}

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

look at 1/3 + 1/4 giving you 7/12 instead of some cursed 0.5833333333 situation. that's the vibe. 💅

---

🦋 DESCRIPTION 🦋

Every single numeric literal in the scope you're in gets converted into Math::BigRat objects. all of them. no survivors. 🔥

Every operator (including the basic math ones) is overloaded — except the range operator ... we'll get to why that's a whole thing later, and yes it's a tragedy. 😭

So this:

use bigrat;
$x = 1234;

creates a Math::BigRat and stores a reference to it in $x. it happens transparently and behind your back, so to speak. like a little math goblin doing your homework. 🧚

You can see it for yourself with this:

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

Since the numbers are actually objects now, you can call all the usual methods from Math::BigRat on them. and it even works, to some extent, on expressions:

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

(okay important glow-up note: print doesn't do what you expect if the expression starts with ( — hence that + at the front. that little plus is doing so much work, respect it 🫶)

You can even chain operations together like normal, bestie:

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

and now the sad part 😔 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 -Mbigrat -le 'for (1..2) { print ref($_); }'

---

🎀 Options 🎀

bigrat recognizes some options that you can pass while loading it via use. here's the whole menu, no skips:

• a or accuracy — 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 deets.

perl -Mbigrat=a,50 -le 'print sqrt(20)'

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

• p or precision — sets the precision for all math operations. the argument can be any integer. negative values mean a fixed number of digits after the dot, while 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 -Mbigrat=p,-50 -le 'print sqrt(20)'

⚠️ and again: setting precision and accuracy at the same time is not possible.

• t or trace — enables a trace mode. it's primarily for debugging, so like, bring it out when things are being weird. 🔍
• l, lib, try, or only — load a different math lib. see "Math Library" (right below, keep scrolling 💖).

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

• hex — overrides 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 isn't so necessary, because hex() gets lexically overridden in the current scope whenever the bigrat pragma is active. slay. ✨
• oct — overrides 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 isn't so necessary, because oct() gets lexically overridden in the current scope whenever the bigrat pragma is active. same energy, different base. 🌈
• v or version — this prints out the name and version of the modules and then exits.

perl -Mbigrat=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 bigrat lib => 'Calc';

you can change that by using:

use bigrat lib => 'GMP';

and this next one would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and if that also fails, revert to Math::BigInt::Calc:

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

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

use bigrat try => 'GMP';

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

use bigrat only => 'GMP';

Please see the respective module documentation for further details. iykyk. 📚

---

🍓 Method calls 🍓

Since all the numbers are objects now, you can use every method that's part of the Math::BigRat API. it's a whole buffet. 🍽️

But a warning is in order, bestie. ⚠️ when you use the following to make a copy of a number, only a shallow copy gets made:

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

Using copy or the original with overloaded math is okay — e.g. these all 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 😭 (they're literally the same object, this is not a drill):

$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

Using methods that do not modify, but only test the contents, works 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::BigFloat for further details. 🫶

---

💅 Methods 💅

• inf() — a shortcut to return Math::BigRat->binf(). useful because Perl does not always handle bareword inf properly.
• NaN() — a shortcut to return Math::BigRat->bnan(). useful because Perl does not always handle bareword NaN properly.
• e

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

returns Euler's number e, aka exp(1). iconic irrational behavior. 🌈

• PI

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

returns PI. 🥧

• bexp()

bexp($power, $accuracy);

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

Example:

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

• bpi()

bpi($accuracy);

returns PI to the wanted accuracy.

Example:

# perl -Mbigrat=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 bigrat;

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

returns true or false if bigrat is in effect in the current scope.

🚨 this method only works on Perl v5.9.4 or later.

---

💀 CAVEATS 💀

🌸 Hexadecimal, octal, and binary floating point literals 🌸

Perl (and this module) accepts hexadecimal, octal, and binary floating point literals, but use them with care with Perl versions before v5.32.0, because some versions of Perl silently give the wrong result. silently! the worst kind of wrong! 😱

🌸 Operator vs literal overloading 🌸

bigrat works by overloading the handling of integer and floating point literals, converting them to Math::BigRat objects.

This means that arithmetic involving only string values or string literals is performed using Perl's built-in operators. big yikes for exactness, but that's how it is.

For example:

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

outputs 0 on default 32-bit builds, since bigrat never sees the string literals. 💀 to ensure the expression is all treated as Math::BigRat objects, use a literal number in the expression:

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

that 0+ is the little nudge that makes it notice you. 🫶

🌸 Ranges 🌸

Perl does not allow overloading of ranges, so you can neither safely use ranges with bigrat endpoints, nor is the iterator variable a Math::BigRat.

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

read that comment again. a floating-point number. not an object. the audacity. 😭

🌸 in_effect() 🌸

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

🌸 hex()/oct() 🌸

bigrat overrides these routines with versions that can also handle big integer values. under Perl prior to version v5.9.4, however, 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 bigrat:

use bigrat qw/hex oct/;

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

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

Compare this to:

use bigrat;

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

see the difference? that's the whole point. 👑

---

⭐ EXAMPLES ⭐

go ahead, run them, they're cute:

perl -Mbigrat -le 'print sqrt(33)'
perl -Mbigrat -le 'print 2**255'
perl -Mbigrat -le 'print 4.5+2**255'
perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
perl -Mbigrat -le 'print 12->is_odd()';
perl -Mbigrat=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. teamwork, bestie. 🤝

---

🫶 SUPPORT 🫶

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

perldoc bigrat

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. 💖

---

...okay we're not done yet, there's more of this page coming, don't go anywhere 🦋

🌈 SEE ALSO 🌈

okay so if you liked this vibe (and you did, bestie, don't even front), go check out its siblings:

• bignum and bigint — the other two members of the trio 🫶

and like, the whole extended fam, fr fr:

• Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big — the main characters 👑
• plus the backend besties: Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP ✨

seriously, go say hi, they're all iconic 💅

---

👑 AUTHORS 👑

the lore, as requested 🎀

• (C) by Tels <http://bloodgate.com/> in early 2002 - 2007. like, literally the original icon, we stan 🫡
• Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-. carrying the torch, no cap 🔥

---

okay that's the whole page, you made it to the end, I'm so proud of you 😭💖 go write something big and rational and slay, bestie. this page is from perl version v5.42.3, dated 2026-11-03, so if you're reading this in the future, hi, ily, the vibes are timeless 🦋✨