Number::Fraction(3pm)

✨ Number::Fraction ✨

okay bestie, so this is Number::Fraction from the 3pm user-contributed Perl docs 💅 — it's a Perl extension to model fractions. Yes. Actual fractions. Like from math class, except this time they behave. 🎀

---

🌸 SYNOPSIS 🌸

the vibe check starts here:

use Number::Fraction;

my $f1 = Number::Fraction->new(1, 2);
my $f2 = Number::Fraction->new('1/2');
my $f3 = Number::Fraction->new($f1); # clone
my $f4 = Number::Fraction->new; # 0/1

or

use Number::Fraction ':constants';

my $f1 = '1/2';
my $f2 = $f1;

my $one = $f1 + $f2;
my $half = $one - $f1;
print $half; # prints '1/2'

or some famous examples from Ovid or the perldoc 🫶

use Number::Fraction ':constants';

print '0.1' + '0.2' - '0.3';
# except for perl6, this is the usual suspect 5.55111512312578e-17
# times the mass of the sun, this would be the size of Mount Everest
# just a small rounding difference

my $f1 = Number::Fraction->new(-6.725);
my $f2 = Number::Fraction->new( 0.025);
print int $f1/$f2;
# the correct -269, no internal  -268.99999999999994315658

and as of the latest release with unicode support 💜

my $f1 = Number::Fraction->new('3½');
my $f2 = Number::Fraction->new(4.33);

my $f0 = $f1 * $f2;

print $f0->to_simple; # 15⅙

and for those who love pie 🥧

print '3.14159265359'->nearest(1 ..   10)->to_unicode_mixed  # 3¹⁄₇

print '3.14159265359'->nearest(1 .. 1000)->to_unicode_string # ³⁵⁵⁄₁₁₃

---

🌈 ABSTRACT 🌈

Number::Fraction is a Perl module which allows you to work with fractions in your Perl programs. periodt. 💅

---

🦋 DESCRIPTION 🦋

Number::Fraction allows you to work with fractions (i.e. rational numbers) in your Perl programs in a very natural way. lowkey iconic.

It was originally written as a demonstration of the techniques of overloading. not me being a show-off, it's literally the origin story bestie.

If you use the module in your program in the usual way

use Number::Fraction;

you can then create fraction objects using Number::Fraction->new in a number of ways. ✨

my $f1 = Number::Fraction->new(1, 2);

creates a fraction with a numerator of 1 and a denominator of 2.

my $fm = Number::Fraction->new(1, 2, 3);

creates a fraction from an integer of 1, a numerator of 2 and a denominator of 3; which results in a fraction of 5/3 since fractions are normalised.

my $f2 = Number::Fraction->new('1/2');

does the same thing but from a string constant.

my $f3 = Number::Fraction->new($f1);

makes $f3 a copy of $f1

my $f4 = Number::Fraction->new; # 0/1

creates a fraction with a denominator of 0 and a numerator of 1. (yes, that's what it says, don't come for me 😭)

If you use the alternative syntax of

use Number::Fraction ':constants';

then Number::Fraction will automatically create fraction objects from string constants in your program. Any time your program contains a string constant of the form \d+/\d+ then that will be automatically replaced with the equivalent fraction object. For example

my $f1 = '1/2';

Having created fraction objects you can manipulate them using most of the normal mathematical operations. 🧚

my $one = $f1 + $f2;
my $half = $one - $f1;

Additionally, whenever a fraction object is evaluated in a string context, it will return a string in the format x/y. When a fraction object is evaluated in a numerical context, it will return a floating point representation of its value.

Fraction objects will always "normalise" themselves. That is, if you create a fraction of '2/4', it will silently be converted to '1/2'. the way it just fixes itself, we love a self-cleaning queen 👑

🍓 Mixed Fractions and Unicode Support 🍓

Since version 3.0 the interpretation of strings and constants has been enriched with a few features for mixed fractions and Unicode characters. glow-up fr.

Number::Fraction now recognises a more Perlish way of entering mixed fractions which consist of an integer-part and a fraction in the form of \d+_\d+/\d+. For example

my $mixed = '2_3/4'; # two and three fourths, stored as 11/4

or

my $simple = '2½'; # two and a half, stored as 5/2

Mixed fractions, either in Perl notation or with Unicode fractions can be negative, prepending it with a minus-sign. 💀

my $negative = '-⅛'; # minus one eighth

🔥 Experimental Support for Exponentiation 🔥

Version 1.13 of Number::Fraction adds experimental support for exponentiation operations. Version 3 has extended support and returns a Number::Fraction.

⚠️ bestie this is experimental — noted as experimental right there in the original, so don't act surprised okay?

It does a lot of cheating, but can give very useful results. And for now will try to make a real number into a Number::Fraction if that real does not have a power of ten component (like 1.234e45, thes numbers will simply fail). Such that

('5⅞' ** '1¼') ** '⅘'

will produce still the right fraction!

In a future version, I might use automatic rounding to a optional accuracy, so that it also works for less forced examples as the above. One could still use nearest to find the nearest fraction to the result of the previous computation.

For example:

'1/2' ** 2 #   Returns a Number::Fraction ('1/4')
'2/1' ** '2/1' Returns a Number::Fraction ('4/1')
'2/1' ** '1/2' Returns a real number (1.414213)
 0.5  ** '2/1' Returns a Number::Fraction ('1/4')
 0.25 ** '1/2' Returns a Number::Fraction ('1/2')

👑 Version 3: Now With Added Moo 👑

Version 3 of Number::Fraction has been reimplemented using Moo. You should see very little difference in the way that the class works. The only difference I can see is that new used to return undef if it couldn't create a valid object from its arguments, it now dies. If you aren't sure of the values that are being passed into the constructor, then you'll want to call it within an eval { ... } block (or using something equivalent like Try::Tiny).

😭 yes this is a real behavioural change: it dies now instead of returning undef. wrap it in eval { ... }, bestie. iykyk.

---

💖 METHODS 💖

import

Called when module is used. Use to optionally install constant handler.

unimport

Be a good citizen and uninstall constant handler when caller uses no Number::Fraction. 🫶 very demure, very mindful.

BUILDARGS

Parameter massager for Number::Fraction object. Takes the following kinds of parameters:

• A single Number::Fraction object which is cloned.
• A string in the form 'x/y' where x and y are integers. x is used as the numerator and y is used as the denominator of the new object.

A string in the form 'a_b/c' where a,b and c are integers. The numerator will be equal to a*c+b! and c is used as the denominator of the new object.

• Three integers which are used as the integer, numerator and denominator of the new object.

In order for this to work in version 2.x, one needs to enable 'mixed' fractions:

use Number::Fractions ':mixed';

This will be the default behaviour in version 3.x; when not enabled in version 2.x it will omit a warning to revise your code.

• Two integers which are used as the numerator and denominator of the new object.
• A single integer which is used as the numerator of the the new object. The denominator is set to 1.
• No arguments, in which case a numerator of 0 and a denominator of 1 are used.
• Note

As of version 2.1 it no longer allows for an array of four or more integer. Before then, it would simply pass in the first two integers. Version 2.1 allows for three integers (when using :mixed) and issues a warning when more then two parameters are passed. Starting with version 3, it will die as it is seen as an error to pass invalid input.

⚠️ Dies if a Number::Fraction object can't be created.

BUILD

Object initialiser for Number::Fraction. Ensures that fractions are in a normalised format. ✨

to_string

Returns a string representation of the fraction in the form numerator/denominator.

to_mixed

Returns a string representation of the fraction in the form integer numerator/denominator.

to_unicode_string

Returns a string representation of the fraction in the form superscript numerator / subscript denominator. A Unicode 'FRACTION SLASH' is used instead of a normal slash.

to_unicode_mixed

Returns a string representation of the fraction in the form integer superscript numerator / subscript denominator. A Unicode 'FRACTION SLASH' is used instead of a normal slash.

to_halfs

to_quarters

to_eighths

to_thirds

to_sixths

to_fifths

Returns a string representation as a mixed fraction, rounded to the nearest possible 'half', 'quarter' ... and so on.

to_simple

Returns a string representation as a mixed fraction, rounded to the nearest possible to any of the above mentioned standard fractions. NB ⅐, ⅑ or ⅒ are not being used.

Optionally, one can pass in a list of well-known denominators (2, 3, 4, 5, 6, 8) to choose which fractions can be used.

to_num

Returns a numeric representation of the fraction by calculating the sum numerator/denominator. Normal caveats about the precision of floating point numbers apply.

🫠 floating point precision, the eternal enemy. caveats stand, no cap.

add

Add a value to a fraction object and return a new object representing the result of the calculation.

The first parameter is a fraction object. The second parameter is either another fraction object or a number.

mult

Multiply a fraction object by a value and return a new object representing the result of the calculation.

The first parameter is a fraction object. The second parameter is either another fraction object or a number.

subtract

Subtract a value from a fraction object and return a new object representing the result of the calculation.

The first parameter is a fraction object. The second parameter is either another fraction object or a number.

div

Divide a fraction object by a value and return a new object representing the result of the calculation.

The first parameter is a fraction object. The second parameter is either another fraction object or a number.

exp

Raise a Number::Fraction object to a power.

The first argument is a number fraction object. The second argument is another Number::Fraction object or a number. It will try to compute another new Number::Fraction object. This may fail if either numerator or denominator of the new one are getting too big. In such case the value returned is a real number.

⚠️ may fail if numerator or denominator get too big — then you just get a real number back. that's the deal.

abs

Returns a copy of the given object with both the numerator and denominator changed to positive values.

fract

Returns the fraction part of a Number::Fraction object as a new Number::Fraction object.

int

Returns the integer part of a Number::Fraction object as a new Number::Fraction object.

nearest

Takes a list of integers and creates a new Number::Fraction object nearest to a fraction with a deniminator from that list.

---

🎀 EXPORT 🎀

None by default.

---

🌟 SEE ALSO 🌟

perldoc overload

Lingua::EN::Fractions

---

💜 AUTHOR 💜

Dave Cross, <dave@mag-sol.com>

---

to be continued bestie… more of the page is coming, don't go anywhere 🦋

✨ COPYRIGHT AND LICENSE ✨

Okay bestie, legal era 💅 but make it cute:

Copyright 2002-20 by Dave Cross

This library is free software 🫶 you can redistribute it and/or modify it under the same terms as Perl itself. That's the whole vibe. No cap, no extra fine print, no spooky hidden clause. Copy it, remix it, ship it — just keep the same deal Perl gives you. Periodt. 👑

---

And that's a wrap on Number::Fraction(3pm), my love 🌸 This little tour came to you courtesy of perl v5.40.1, dated 2026-02-15, straight out of the User Contributed Perl Documentation section of the Number::Fraction(3pm) page 🎀 Go forth and do fractions, you absolute icon. 💖✨