Number::Fraction(3pm)

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

ABSTRACT

28       Number::Fraction is a Perl module which allows you to work with
29       fractions in your Perl programs.
30

DESCRIPTION

32       Number::Fraction allows you to work with fractions (i.e. rational
33       numbers) in your Perl programs in a very natural way.
34
35       It was originally written as a demonstration of the techniques of
36       overloading.
37
38       If you use the module in your program in the usual way
39
40         use Number::Fraction;
41
42       you can then create fraction objects using "Number::Fraction-"new> in a
43       number of ways.
44
45         my $f1 = Number::Fraction->new(1, 2);
46
47       creates a fraction with a numerator of 1 and a denominator of 2.
48
49         my $f2 = Number::Fraction->new('1/2');
50
51       does the same thing but from a string constant.
52
53         my $f3 = Number::Fraction->new($f1);
54
55       makes $f3 a copy of $f1
56
57         my $f4 = Number::Fraction->new; # 0/1
58
59       creates a fraction with a denominator of 0 and a numerator of 1.
60
61       If you use the alterative syntax of
62
63         use Number::Fraction ':constants';
64
65       then Number::Fraction will automatically create fraction objects from
66       string constants in your program. Any time your program contains a
67       string constant of the form "\d+/\d+" then that will be automatically
68       replaced with the equivalent fraction object. For example
69
70         my $f1 = '1/2';
71
72       Having created fraction objects you can manipulate them using most of
73       the normal mathematical operations.
74
75         my $one = $f1 + $f2;
76         my $half = $one - $f1;
77
78       Additionally, whenever a fraction object is evaluated in a string
79       context, it will return a string in the format x/y. When a fraction
80       object is evaluated in a numerical context, it will return a floating
81       point representation of its value.
82
83       Fraction objects will always "normalise" themselves. That is, if you
84       create a fraction of '2/4', it will silently be converted to '1/2'.
85
86   Experimental Support for Exponentiation
87       Version 1.13 of Number::Fraction adds experimental support for
88       exponentiation operations. If a Number::Fraction object is used as the
89       left hand operand of an exponentiation expression then the value
90       returned will be another Number::Fraction object - if that makes sense.
91       In all other cases, the expression returns a real number.
92
93       Currently this only works if the right hand operand is an integer (or a
94       Number::Fraction object that has a denominator of 1). Later I hope to
95       extend this so support so that a Number::Fraction object is returned
96       whenever the result of the expression is a rational number.
97
98       For example:
99
100         '1/2' ** 2 #   Returns a Number::Fraction ('1/4')
101         '2/1' ** '2/1' Returns a Number::Fraction ('4/1')
102         '2/1' ** '1/2' Returns a real number (1.414213)
103          0.5  ** '2/1' Returns a real number (0.25)
104
105   Version 2: Now With Added Moose
106       Version 2 of Number::Fraction has been reimplemented using Moose. You
107       should see very little difference in the way that the class works. The
108       only difference I can see is that "new" used to return "undef" if it
109       couldn't create a valid object from its arguments, it now dies. If you
110       aren't sure of the values that are being passed into the constructor,
111       then you'll want to call it within an "eval { ... }" block (or using
112       something equivalent like Try::Tiny).
113

METHODS

115   import
116       Called when module is "use"d. Use to optionally install constant
117       handler.
118
119   unimport
120       Be a good citizen and uninstall constant handler when caller uses "no
121       Number::Fraction".
122
123   BUILDARGS
124       Parameter massager for Number::Fraction object. Takes the following
125       kinds of parameters:
126
127       ·   A single Number::Fraction object which is cloned.
128
129       ·   A string in the form 'x/y' where x and y are integers. x is used as
130           the numerator and y is used as the denominator of the new object.
131
132       ·   Two integers which are used as the numerator and denominator of the
133           new object.
134
135       ·   A single integer which is used as the numerator of the the new
136           object.  The denominator is set to 1.
137
138       ·   No arguments, in which case a numerator of 0 and a denominator of 1
139           are used.
140
141       Dies if a Number::Fraction object can't be created.
142
143   BUILD
144       Object initialiser for Number::Fraction. Ensures that fractions are in
145       a normalised format.
146
147   to_string
148       Returns a string representation of the fraction in the form
149       "numerator/denominator".
150
151   to_num
152       Returns a numeric representation of the fraction by calculating the sum
153       numerator/denominator. Normal caveats about the precision of floating
154       point numbers apply.
155
156   add
157       Add a value to a fraction object and return a new object representing
158       the result of the calculation.
159
160       The first parameter is a fraction object. The second parameter is
161       either another fraction object or a number.
162
163   mult
164       Multiply a fraction object by a value and return a new object
165       representing the result of the calculation.
166
167       The first parameter is a fraction object. The second parameter is
168       either another fraction object or a number.
169
170   subtract
171       Subtract a value from a fraction object and return a new object
172       representing the result of the calculation.
173
174       The first parameter is a fraction object. The second parameter is
175       either another fraction object or a number.
176
177   div
178       Divide a fraction object by a value and return a new object
179       representing the result of the calculation.
180
181       The first parameter is a fraction object. The second parameter is
182       either another fraction object or a number.
183
184   exp
185       Raise a Number::Fraction object to a power.
186
187       The first argument is a number fraction object. The second argument is
188       another Number::Fraction object or a number. If the second argument is
189       an integer or a Number::Fraction object containing an integer then the
190       value returned is a Number::Fraction object, otherwise the value
191       returned is a real number.
192
193   abs
194       Returns a copy of the given object with both the numerator and
195       denominator changed to positive values.
196
197   EXPORT
198       None by default.
199

AUTHOR

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

COPYRIGHT AND LICENSE

207       Copyright 2002-8 by Dave Cross
208
209       This library is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211
212
213
214perl v5.32.0                      2020-07-28               Number::Fraction(3)