1Number::Fraction(3)   User Contributed Perl Documentation  Number::Fraction(3)
2
3
4

NAME

6       Number::Fraction - Perl extension to model fractions
7

SYNOPSIS

9         use Number::Fraction;
10
11         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
16       or
17
18         use Number::Fraction ':constants';
19
20         my $f1 = '1/2';
21         my $f2 = $f1;
22
23         my $one = $f1 + $f2;
24         my $half = $one - $f1;
25         print $half; # prints '1/2'
26
27       or some famous examples from Ovid or the perldoc
28
29         use Number::Fraction ':constants';
30
31         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
36         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
41       and as of the latest release with unicode support
42
43         my $f1 = Number::Fraction->new('3X');
44         my $f2 = Number::Fraction->new(4.33);
45
46         my $f0 = $f1 * $f2;
47
48         print $f0->to_simple; # 15X
49
50       and for those who love pie
51
52         print '3.14159265359'->nearest(1 ..   10)->to_unicode_mixed  # 3XXX
53
54         print '3.14159265359'->nearest(1 .. 1000)->to_unicode_string # XXXXXXX
55

ABSTRACT

57       Number::Fraction is a Perl module which allows you to work with
58       fractions in your Perl programs.
59

DESCRIPTION

61       Number::Fraction allows you to work with fractions (i.e. rational
62       numbers) in your Perl programs in a very natural way.
63
64       It was originally written as a demonstration of the techniques of
65       overloading.
66
67       If you use the module in your program in the usual way
68
69         use Number::Fraction;
70
71       you can then create fraction objects using "Number::Fraction-"new> in a
72       number of ways.
73
74         my $f1 = Number::Fraction->new(1, 2);
75
76       creates a fraction with a numerator of 1 and a denominator of 2.
77
78         my $fm = Number::Fraction->new(1, 2, 3);
79
80       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
84         my $f2 = Number::Fraction->new('1/2');
85
86       does the same thing but from a string constant.
87
88         my $f3 = Number::Fraction->new($f1);
89
90       makes $f3 a copy of $f1
91
92         my $f4 = Number::Fraction->new; # 0/1
93
94       creates a fraction with a denominator of 0 and a numerator of 1.
95
96       If you use the alterative syntax of
97
98         use Number::Fraction ':constants';
99
100       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
105         my $f1 = '1/2';
106
107       Having created fraction objects you can manipulate them using most of
108       the normal mathematical operations.
109
110         my $one = $f1 + $f2;
111         my $half = $one - $f1;
112
113       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
118       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
121   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
126       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
130         my $mixed = '2_3/4'; # two and three fourths, stored as 11/4
131
132       or
133
134         my $simple = '2X'; # two and a half, stored as 5/2
135
136       Mixed fractions, either in Perl notation or with Unicode fractions can
137       be negative, prepending it with a minus-sign.
138
139         my $negative = '-X'; # minus one eighth
140
141   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
146       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
151         ('5X' ** '1X') ** 'X'
152
153       will produce still the right fraction!
154
155       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
160       For example:
161
162         '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
168   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

METHODS

178   import
179       Called when module is "use"d. Use to optionally install constant
180       handler.
181
182   unimport
183       Be a good citizen and uninstall constant handler when caller uses "no
184       Number::Fraction".
185
186   BUILDARGS
187       Parameter massager for Number::Fraction object. Takes the following
188       kinds of parameters:
189
190       •   A single Number::Fraction object which is cloned.
191
192       •   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
195           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
199       •   Three integers which are used as the integer, numerator and
200           denominator of the new object.
201
202           In order for this to work in version 2.x, one needs to enable
203           'mixed' fractions:
204
205             use Number::Fractions ':mixed';
206
207           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
210       •   Two integers which are used as the numerator and denominator of the
211           new object.
212
213       •   A single integer which is used as the numerator of the the new
214           object.  The denominator is set to 1.
215
216       •   No arguments, in which case a numerator of 0 and a denominator of 1
217           are used.
218
219       •   Note
220
221           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
228       Dies if a Number::Fraction object can't be created.
229
230   BUILD
231       Object initialiser for Number::Fraction. Ensures that fractions are in
232       a normalised format.
233
234   to_string
235       Returns a string representation of the fraction in the form
236       "numerator/denominator".
237
238   to_mixed
239       Returns a string representation of the fraction in the form "integer
240       numerator/denominator".
241
242   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
247   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
252   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
261   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
266       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
269   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
274   add
275       Add a value to a fraction object and return a new object representing
276       the result of the calculation.
277
278       The first parameter is a fraction object. The second parameter is
279       either another fraction object or a number.
280
281   mult
282       Multiply a fraction object by a value and return a new object
283       representing the result of the calculation.
284
285       The first parameter is a fraction object. The second parameter is
286       either another fraction object or a number.
287
288   subtract
289       Subtract a value from a fraction object and return a new object
290       representing the result of the calculation.
291
292       The first parameter is a fraction object. The second parameter is
293       either another fraction object or a number.
294
295   div
296       Divide a fraction object by a value and return a new object
297       representing the result of the calculation.
298
299       The first parameter is a fraction object. The second parameter is
300       either another fraction object or a number.
301
302   exp
303       Raise a Number::Fraction object to a power.
304
305       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
311   abs
312       Returns a copy of the given object with both the numerator and
313       denominator changed to positive values.
314
315   fract
316       Returns the fraction part of a Number::Fraction object as a new
317       Number::Fraction object.
318
319   int
320       Returns the integer part of a Number::Fraction object as a new
321       Number::Fraction object.
322
323   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
327   EXPORT
328       None by default.
329

SEE ALSO

331       perldoc overload
332
333       Lingua::EN::Fractions
334

AUTHOR

336       Dave Cross, <dave@mag-sol.com>
337
339       Copyright 2002-20 by Dave Cross
340
341       This library is free software; you can redistribute it and/or modify it
342       under the same terms as Perl itself.
343
344
345
346perl v5.34.0                      2021-07-22               Number::Fraction(3)
Impressum