bigrat(3perl)

📦

version 5.44.0 · 14 versions

✨ NAME ✨

okay so bestie, meet bigrat — that's your bigrat(3perl) page from the Perl Programmers Reference Guide 🌸 — and it's literally transparent big rational number support for Perl. no cap. 💅

🌈 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");

💅 DESCRIPTION 💅

so basically every single numeric literal inside the scope you set up gets converted into a Math::BigRat object. yes, all of them. it's giving magic ✨

and all the operators — including your basic math ops — are overloaded, except the range operator ... that one's just out here living its own life, we'll get to it. 🙈

so when you write this:

use bigrat;
$x = 1234;

you've created a Math::BigRat and stashed a reference to it in $x. it happens transparently, literally behind your back, so to speak. 🫶

you can peep this for yourself with:

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

and since the numbers are actually objects now, you can call all your fave Math::BigRat methods right on them. 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()'

heads up bestie: print does not do what you expect if the expression starts with ( — that's why there's a + sitting in front in the last one. 😭

you can even chain the operations together, business as usual:

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

but like, lowkey, please note this does not work as expected (it prints nothing), because overloading .. isn't possible in Perl yet (as of v5.8.0):

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

🎀 Options 🎀

bigrat recognizes a few options you can pass while loading it via use. here's the whole roster, no skips:

`a` or `accuracy`

sets the accuracy for all math operations. the argument has to be greater than or equal to zero. peep Math::BigInt's bround() method for the deets.

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

ngl, setting precision and accuracy at the same time is not possible. pick a lane. 💀

`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 to the left from the dot. 0 means round to integer. check Math::BigInt's bfround() method for details.

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

again for the people in the back: setting precision and accuracy at the same time is not possible. ✨

`t` or `trace`

turns on trace mode. it's primarily for debugging, iykyk. 🔍

`l`, `lib`, `try`, or `only`

loads a different math lib. see "Math Library" below for the whole saga.

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. it does this by exporting it to the current package. under Perl v5.10.0 and higher this isn't so necessary, because hex() is lexically overridden in the current scope whenever the bigrat pragma is active. 💅

`oct`

overrides the built-in oct() method with a version that can handle big numbers. it does this by exporting it to the current package. under Perl v5.10.0 and higher this isn't so necessary, because oct() is lexically overridden in the current scope whenever the bigrat pragma is active. 🌸

`v` or `version`

this one prints out the name and version of the modules and then exits. iconic behaviour.

perl -Mbigrat=v

📚 Math Library 📚

the actual 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';

the following 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';

and if you want the code to straight up die instead of falling back, use only instead:

use bigrat only => 'GMP';

please see the respective module documentation for further details. 🫶

🧚 Method calls 🧚

since all the numbers are objects now, you can use every method that's part of the Math::BigRat API.

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 the copy or the original with overloaded math is okay though, 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 😭:

$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 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 doesn't always handle the bareword inf properly.

`NaN()`

a shortcut to return Math::BigRat->bnan(). useful because Perl doesn't always handle the bareword NaN properly.

`e`

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

returns Euler's number e, aka exp(1).

`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 depending on whether 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 on Perl versions before v5.32.0, because some versions of Perl silently give the wrong result. 😳

Operator vs literal overloading

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

this means that arithmetic involving only string values or string literals is performed using Perl's built-in operators.

for example:

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

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

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

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
  }
}

`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. however, under Perl versions prior to 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 can't be disabled inside a scope with no bigrat:

use bigrat qw/hex oct/;

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

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

compare that to:

use bigrat;

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

🦋 EXAMPLES 🦋

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'll be notified, and then you'll automatically be notified of progress on your bug as changes get made. 🫶

🌸 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. periodt. 💅

🌈 SEE ALSO 🌈

okay bestie, when you're done reading this and you're like "wait, I need MORE big-math energy in my life", here's the whole friend group 🫶

bignum and bigint — the other two members of the trio. go say hi.

and then the actual deep lore, aka the modules doing all the heavy lifting behind the scenes:

Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big

plus the backends, because someone has to do the actual crunching 💪✨

Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP

👑 AUTHORS 👑

the receipts, bestie — who made this masterpiece happen:

(C) by Tels <http://bloodgate.com/> in early 2002 - 2007. — yeah, that URL is literally in the original, we keep it verbatim around here 💖
Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-. — still holding it down, still maintaining, iconic behavior honestly 🌈👑

and that's the whole page, bestie!! 🎀 perl v5.44.0, dated 2026-10-17, and yes the page itself is literally called bigrat(3perl) — we went on a whole journey together and you ATE it, no crumbs left 💅✨ go write some ridiculous fractions, you absolute main character 🦋💜

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

bigrat(3perl)

✨ NAME ✨

🌈 SYNOPSIS 🌈

💅 DESCRIPTION 💅

🎀 Options 🎀

a or accuracy

p or precision

t or trace

l, lib, try, or only

hex

oct

v or version

📚 Math Library 📚

🧚 Method calls 🧚

👑 Methods 👑

inf()

NaN()

e

PI

bexp()

bpi()

accuracy()

precision()

round_mode()

div_scale()

in_effect()

💀 CAVEATS 💀

Hexadecimal, octal, and binary floating point literals

Operator vs literal overloading

Ranges

in_effect()

hex()/oct()

🦋 EXAMPLES 🦋

🐛 BUGS 🐛

🌸 SUPPORT 🌸

🎀 LICENSE 🎀

🌈 SEE ALSO 🌈

👑 AUTHORS 👑

`a` or `accuracy`

`p` or `precision`

`t` or `trace`

`l`, `lib`, `try`, or `only`

`hex`

`oct`

`v` or `version`

`inf()`

`NaN()`

`e`

`PI`

`bexp()`

`bpi()`

`accuracy()`

`precision()`

`round_mode()`

`div_scale()`

`in_effect()`

`in_effect()`

`hex()`/`oct()`