1Number::Fraction(3) User Contributed Perl Documentation Number::Fraction(3)
2
6 Number::Fraction - Perl extension to model fractions
7
9 use Number::Fraction;
10 my $f1 = Number::Fraction->new(1, 2);
12 my $f2 = Number::Fraction->new('1/2');
13 my $f3 = Number::Fraction->new($f1); # clone
14 my $f4 = Number::Fraction->new; # 0/1
15 or
17 use Number::Fraction ':constants';
19 my $f1 = '1/2';
21 my $f2 = $f1;
22 my $one = $f1 + $f2;
24 my $half = $one - $f1;
25 print $half; # prints '1/2'
26 or some famous examples from Ovid or the perldoc
28 use Number::Fraction ':constants';
30 print '0.1' + '0.2' - '0.3';
32 # except for perl6, this is the usual suspect 5.55111512312578e-17
33 # times the mass of the sun, this would be the size of Mount Everest
34 # just a small rounding difference
35 my $f1 = Number::Fraction->new(-6.725);
37 my $f2 = Number::Fraction->new( 0.025);
38 print int $f1/$f2;
39 # the correct -269, no internal -268.99999999999994315658
40 and as of the latest release with unicode support
42 my $f1 = Number::Fraction->new('3X');
44 my $f2 = Number::Fraction->new(4.33);
45 my $f0 = $f1 * $f2;
47 print $f0->to_simple; # 15X
49 and for those who love pie
51 print '3.14159265359'->nearest(1 .. 10)->to_unicode_mixed # 3XXX
53 print '3.14159265359'->nearest(1 .. 1000)->to_unicode_string # XXXXXXX
55
57 Number::Fraction is a Perl module which allows you to work with
58 fractions in your Perl programs.
59
61 Number::Fraction allows you to work with fractions (i.e. rational
62 numbers) in your Perl programs in a very natural way.
63 It was originally written as a demonstration of the techniques of
65 overloading.
66 If you use the module in your program in the usual way
68 use Number::Fraction;
70 you can then create fraction objects using "Number::Fraction-"new> in a
72 number of ways.
73 my $f1 = Number::Fraction->new(1, 2);
75 creates a fraction with a numerator of 1 and a denominator of 2.
77 my $fm = Number::Fraction->new(1, 2, 3);
79 creates a fraction from an integer of 1, a numerator of 2 and a
81 denominator of 3; which results in a fraction of 5/3 since fractions
82 are normalised.
83 my $f2 = Number::Fraction->new('1/2');
85 does the same thing but from a string constant.
87 my $f3 = Number::Fraction->new($f1);
89 makes $f3 a copy of $f1
91 my $f4 = Number::Fraction->new; # 0/1
93 creates a fraction with a denominator of 0 and a numerator of 1.
95 If you use the alterative syntax of
97 use Number::Fraction ':constants';
99 then Number::Fraction will automatically create fraction objects from
101 string constants in your program. Any time your program contains a
102 string constant of the form "\d+/\d+" then that will be automatically
103 replaced with the equivalent fraction object. For example
104 my $f1 = '1/2';
106 Having created fraction objects you can manipulate them using most of
108 the normal mathematical operations.
109 my $one = $f1 + $f2;
111 my $half = $one - $f1;
112 Additionally, whenever a fraction object is evaluated in a string
114 context, it will return a string in the format x/y. When a fraction
115 object is evaluated in a numerical context, it will return a floating
116 point representation of its value.
117 Fraction objects will always "normalise" themselves. That is, if you
119 create a fraction of '2/4', it will silently be converted to '1/2'.
120 Mixed Fractions and Unicode Support
122 Since version 3.0 the interpretation of strings and constants has been
123 enriched with a few features for mixed fractions and Unicode
124 characters.
125 Number::Fraction now recognises a more Perlish way of entering mixed
127 fractions which consist of an integer-part and a fraction in the form
128 of "\d+_\d+/\d+". For example
129 my $mixed = '2_3/4'; # two and three fourths, stored as 11/4
131 or
133 my $simple = '2X'; # two and a half, stored as 5/2
135 Mixed fractions, either in Perl notation or with Unicode fractions can
137 be negative, prepending it with a minus-sign.
138 my $negative = '-X'; # minus one eighth
140 Experimental Support for Exponentiation
142 Version 1.13 of Number::Fraction adds experimental support for
143 exponentiation operations. Version 3 has extended support and returns a
144 Number::Fraction.
145 It does a lot of cheating, but can give very useful results. And for
147 now will try to make a real number into a Number::Fraction if that real
148 does not have a power of ten component (like 1.234e45, thes numbers
149 will simply fail). Such that
150 ('5X' ** '1X') ** 'X'
152 will produce still the right fraction!
154 In a future version, I might use automatic rounding to a optional
156 accuracy, so that it also works for less forced examples as the above.
157 One could still use "nearest" to find the nearest fraction to the
158 result of the previous computation.
159 For example:
161 '1/2' ** 2 # Returns a Number::Fraction ('1/4')
163 '2/1' ** '2/1' Returns a Number::Fraction ('4/1')
164 '2/1' ** '1/2' Returns a real number (1.414213)
165 0.5 ** '2/1' Returns a Number::Fraction ('1/4')
166 0.25 ** '1/2' Returns a Number::Fraction ('1/2')
167 Version 3: Now With Added Moo
169 Version 3 of Number::Fraction has been reimplemented using Moo. You
170 should see very little difference in the way that the class works. The
171 only difference I can see is that "new" used to return "undef" if it
172 couldn't create a valid object from its arguments, it now dies. If you
173 aren't sure of the values that are being passed into the constructor,
174 then you'll want to call it within an "eval { ... }" block (or using
175 something equivalent like Try::Tiny).
176
178 import
179 Called when module is "use"d. Use to optionally install constant
180 handler.
181 unimport
183 Be a good citizen and uninstall constant handler when caller uses "no
184 Number::Fraction".
185 BUILDARGS
187 Parameter massager for Number::Fraction object. Takes the following
188 kinds of parameters:
189 • A single Number::Fraction object which is cloned.
191 • A string in the form 'x/y' where x and y are integers. x is used as
193 the numerator and y is used as the denominator of the new object.
194 A string in the form 'a_b/c' where a,b and c are integers. The
196 numerator will be equal to a*c+b! and c is used as the denominator
197 of the new object.
198 • Three integers which are used as the integer, numerator and
200 denominator of the new object.
201 In order for this to work in version 2.x, one needs to enable
203 'mixed' fractions:
204 use Number::Fractions ':mixed';
206 This will be the default behaviour in version 3.x; when not enabled
208 in version 2.x it will omit a warning to revise your code.
209 • Two integers which are used as the numerator and denominator of the
211 new object.
212 • A single integer which is used as the numerator of the the new
214 object. The denominator is set to 1.
215 • No arguments, in which case a numerator of 0 and a denominator of 1
217 are used.
218 • Note
220 As of version 2.1 it no longer allows for an array of four or more
222 integer. Before then, it would simply pass in the first two
223 integers. Version 2.1 allows for three integers (when using
224 ":mixed") and issues a warning when more then two parameters are
225 passed. Starting with version 3, it will die as it is seen as an
226 error to pass invalid input.
227 Dies if a Number::Fraction object can't be created.
229 BUILD
231 Object initialiser for Number::Fraction. Ensures that fractions are in
232 a normalised format.
233 to_string
235 Returns a string representation of the fraction in the form
236 "numerator/denominator".
237 to_mixed
239 Returns a string representation of the fraction in the form "integer
240 numerator/denominator".
241 to_unicode_string
243 Returns a string representation of the fraction in the form
244 "superscript numerator / subscript denominator". A Unicode 'FRACTION
245 SLASH' is used instead of a normal slash.
246 to_unicode_mixed
248 Returns a string representation of the fraction in the form "integer
249 superscript numerator / subscript denominator". A Unicode 'FRACTION
250 SLASH' is used instead of a normal slash.
251 to_halfs
253 to_quarters
254 to_eighths
255 to_thirds
256 to_sixths
257 to_fifths
258 Returns a string representation as a mixed fraction, rounded to the
259 nearest possible 'half', 'quarter' ... and so on.
260 to_simple
262 Returns a string representation as a mixed fraction, rounded to the
263 nearest possible to any of the above mentioned standard fractions. NB
264 X, X or X are not being used.
265 Optionally, one can pass in a list of well-known denominators (2, 3, 4,
267 5, 6, 8) to choose which fractions can be used.
268 to_num
270 Returns a numeric representation of the fraction by calculating the sum
271 numerator/denominator. Normal caveats about the precision of floating
272 point numbers apply.
273 add
275 Add a value to a fraction object and return a new object representing
276 the result of the calculation.
277 The first parameter is a fraction object. The second parameter is
279 either another fraction object or a number.
280 mult
282 Multiply a fraction object by a value and return a new object
283 representing the result of the calculation.
284 The first parameter is a fraction object. The second parameter is
286 either another fraction object or a number.
287 subtract
289 Subtract a value from a fraction object and return a new object
290 representing the result of the calculation.
291 The first parameter is a fraction object. The second parameter is
293 either another fraction object or a number.
294 div
296 Divide a fraction object by a value and return a new object
297 representing the result of the calculation.
298 The first parameter is a fraction object. The second parameter is
300 either another fraction object or a number.
301 exp
303 Raise a Number::Fraction object to a power.
304 The first argument is a number fraction object. The second argument is
306 another Number::Fraction object or a number. It will try to compute
307 another new Number::Fraction object. This may fail if either numerator
308 or denominator of the new one are getting too big. In such case the
309 value returned is a real number.
310 abs
312 Returns a copy of the given object with both the numerator and
313 denominator changed to positive values.
314 fract
316 Returns the fraction part of a Number::Fraction object as a new
317 Number::Fraction object.
318 int
320 Returns the integer part of a Number::Fraction object as a new
321 Number::Fraction object.
322 nearest
324 Takes a list of integers and creates a new Number::Fraction object
325 nearest to a fraction with a deniminator from that list.
326 EXPORT
328 None by default.
329
331 perldoc overload
332 Lingua::EN::Fractions
334
336 Dave Cross, <dave@mag-sol.com>
337
339 Copyright 2002-20 by Dave Cross
340 This library is free software; you can redistribute it and/or modify it
342 under the same terms as Perl itself.
343perl v5.34.0 2021-07-22 Number::Fraction(3)