Math::BigRat(3pm)

1Math::BigRat(3pm)      Perl Programmers Reference Guide      Math::BigRat(3pm)
2
3
4

NAME

6       Math::BigRat - Arbitrary big rational numbers
7

SYNOPSIS

9               use Math::BigRat;
10
11               my $x = Math::BigRat->new('3/7'); $x += '5/9';
12
13               print $x->bstr(),"\n";
14               print $x ** 2,"\n";
15
16               my $y = Math::BigRat->new('inf');
17               print "$y ", ($y->is_inf ? 'is' : 'is not') , " infinity\n";
18
19               my $z = Math::BigRat->new(144); $z->bsqrt();
20

DESCRIPTION

22       Math::BigRat complements Math::BigInt and Math::BigFloat by providing
23       support for arbitrary big rational numbers.
24
25   MATH LIBRARY
26       You can change the underlying module that does the low-level math
27       operations by using:
28
29               use Math::BigRat try => 'GMP';
30
31       Note: This needs Math::BigInt::GMP installed.
32
33       The following would first try to find Math::BigInt::Foo, then
34       Math::BigInt::Bar, and when this also fails, revert to
35       Math::BigInt::Calc:
36
37               use Math::BigRat try => 'Foo,Math::BigInt::Bar';
38
39       If you want to get warned when the fallback occurs, replace "try" with
40       "lib":
41
42               use Math::BigRat lib => 'Foo,Math::BigInt::Bar';
43
44       If you want the code to die instead, replace "try" with "only":
45
46               use Math::BigRat only => 'Foo,Math::BigInt::Bar';
47

METHODS

49       Any methods not listed here are derived from Math::BigFloat (or
50       Math::BigInt), so make sure you check these two modules for further
51       information.
52
53   new()
54               $x = Math::BigRat->new('1/3');
55
56       Create a new Math::BigRat object. Input can come in various forms:
57
58               $x = Math::BigRat->new(123);                            # scalars
59               $x = Math::BigRat->new('inf');                          # infinity
60               $x = Math::BigRat->new('123.3');                        # float
61               $x = Math::BigRat->new('1/3');                          # simple string
62               $x = Math::BigRat->new('1 / 3');                        # spaced
63               $x = Math::BigRat->new('1 / 0.1');                      # w/ floats
64               $x = Math::BigRat->new(Math::BigInt->new(3));           # BigInt
65               $x = Math::BigRat->new(Math::BigFloat->new('3.1'));     # BigFloat
66               $x = Math::BigRat->new(Math::BigInt::Lite->new('2'));   # BigLite
67
68               # You can also give D and N as different objects:
69               $x = Math::BigRat->new(
70                       Math::BigInt->new(-123),
71                       Math::BigInt->new(7),
72                       );                      # => -123/7
73
74   numerator()
75               $n = $x->numerator();
76
77       Returns a copy of the numerator (the part above the line) as signed
78       BigInt.
79
80   denominator()
81               $d = $x->denominator();
82
83       Returns a copy of the denominator (the part under the line) as positive
84       BigInt.
85
86   parts()
87               ($n,$d) = $x->parts();
88
89       Return a list consisting of (signed) numerator and (unsigned)
90       denominator as BigInts.
91
92   numify()
93               my $y = $x->numify();
94
95       Returns the object as a scalar. This will lose some data if the object
96       cannot be represented by a normal Perl scalar (integer or float), so
97       use as_int() or as_float() instead.
98
99       This routine is automatically used whenever a scalar is required:
100
101               my $x = Math::BigRat->new('3/1');
102               @array = (0,1,2,3);
103               $y = $array[$x];                # set $y to 3
104
105   as_int()/as_number()
106               $x = Math::BigRat->new('13/7');
107               print $x->as_int(),"\n";                # '1'
108
109       Returns a copy of the object as BigInt, truncated to an integer.
110
111       "as_number()" is an alias for "as_int()".
112
113   as_float()
114               $x = Math::BigRat->new('13/7');
115               print $x->as_float(),"\n";              # '1'
116
117               $x = Math::BigRat->new('2/3');
118               print $x->as_float(5),"\n";             # '0.66667'
119
120       Returns a copy of the object as BigFloat, preserving the accuracy as
121       wanted, or the default of 40 digits.
122
123       This method was added in v0.22 of Math::BigRat (April 2008).
124
125   as_hex()
126               $x = Math::BigRat->new('13');
127               print $x->as_hex(),"\n";                # '0xd'
128
129       Returns the BigRat as hexadecimal string. Works only for integers.
130
131   as_bin()
132               $x = Math::BigRat->new('13');
133               print $x->as_bin(),"\n";                # '0x1101'
134
135       Returns the BigRat as binary string. Works only for integers.
136
137   as_oct()
138               $x = Math::BigRat->new('13');
139               print $x->as_oct(),"\n";                # '015'
140
141       Returns the BigRat as octal string. Works only for integers.
142
143   from_hex()/from_bin()/from_oct()
144               my $h = Math::BigRat->from_hex('0x10');
145               my $b = Math::BigRat->from_bin('0b10000000');
146               my $o = Math::BigRat->from_oct('020');
147
148       Create a BigRat from an hexadecimal, binary or octal number in string
149       form.
150
151   length()
152               $len = $x->length();
153
154       Return the length of $x in digitis for integer values.
155
156   digit()
157               print Math::BigRat->new('123/1')->digit(1);     # 1
158               print Math::BigRat->new('123/1')->digit(-1);    # 3
159
160       Return the N'ths digit from X when X is an integer value.
161
162   bnorm()
163               $x->bnorm();
164
165       Reduce the number to the shortest form. This routine is called
166       automatically whenever it is needed.
167
168   bfac()
169               $x->bfac();
170
171       Calculates the factorial of $x. For instance:
172
173               print Math::BigRat->new('3/1')->bfac(),"\n";    # 1*2*3
174               print Math::BigRat->new('5/1')->bfac(),"\n";    # 1*2*3*4*5
175
176       Works currently only for integers.
177
178   bround()/round()/bfround()
179       Are not yet implemented.
180
181   bmod()
182               use Math::BigRat;
183               my $x = Math::BigRat->new('7/4');
184               my $y = Math::BigRat->new('4/3');
185               print $x->bmod($y);
186
187       Set $x to the remainder of the division of $x by $y.
188
189   bneg()
190               $x->bneg();
191
192       Used to negate the object in-place.
193
194   is_one()
195               print "$x is 1\n" if $x->is_one();
196
197       Return true if $x is exactly one, otherwise false.
198
199   is_zero()
200               print "$x is 0\n" if $x->is_zero();
201
202       Return true if $x is exactly zero, otherwise false.
203
204   is_pos()/is_positive()
205               print "$x is >= 0\n" if $x->is_positive();
206
207       Return true if $x is positive (greater than or equal to zero),
208       otherwise false. Please note that '+inf' is also positive, while 'NaN'
209       and '-inf' aren't.
210
211       "is_positive()" is an alias for "is_pos()".
212
213   is_neg()/is_negative()
214               print "$x is < 0\n" if $x->is_negative();
215
216       Return true if $x is negative (smaller than zero), otherwise false.
217       Please note that '-inf' is also negative, while 'NaN' and '+inf'
218       aren't.
219
220       "is_negative()" is an alias for "is_neg()".
221
222   is_int()
223               print "$x is an integer\n" if $x->is_int();
224
225       Return true if $x has a denominator of 1 (e.g. no fraction parts),
226       otherwise false. Please note that '-inf', 'inf' and 'NaN' aren't
227       integer.
228
229   is_odd()
230               print "$x is odd\n" if $x->is_odd();
231
232       Return true if $x is odd, otherwise false.
233
234   is_even()
235               print "$x is even\n" if $x->is_even();
236
237       Return true if $x is even, otherwise false.
238
239   bceil()
240               $x->bceil();
241
242       Set $x to the next bigger integer value (e.g. truncate the number to
243       integer and then increment it by one).
244
245   bfloor()
246               $x->bfloor();
247
248       Truncate $x to an integer value.
249
250   bsqrt()
251               $x->bsqrt();
252
253       Calculate the square root of $x.
254
255   broot()
256               $x->broot($n);
257
258       Calculate the N'th root of $x.
259
260   badd()/bmul()/bsub()/bdiv()/bdec()/binc()
261       Please see the documentation in Math::BigInt.
262
263   copy()
264               my $z = $x->copy();
265
266       Makes a deep copy of the object.
267
268       Please see the documentation in Math::BigInt for further details.
269
270   bstr()/bsstr()
271               my $x = Math::BigInt->new('8/4');
272               print $x->bstr(),"\n";                  # prints 1/2
273               print $x->bsstr(),"\n";                 # prints 1/2
274
275       Return a string representating this object.
276
277   bacmp()/bcmp()
278       Used to compare numbers.
279
280       Please see the documentation in Math::BigInt for further details.
281
282   blsft()/brsft()
283       Used to shift numbers left/right.
284
285       Please see the documentation in Math::BigInt for further details.
286
287   bpow()
288               $x->bpow($y);
289
290       Compute $x ** $y.
291
292       Please see the documentation in Math::BigInt for further details.
293
294   bexp()
295               $x->bexp($accuracy);            # calculate e ** X
296
297       Calculates two integers A and B so that A/B is equal to "e ** $x",
298       where "e" is Euler's number.
299
300       This method was added in v0.20 of Math::BigRat (May 2007).
301
302       See also blog().
303
304   bnok()
305               $x->bnok($y);              # x over y (binomial coefficient n over k)
306
307       Calculates the binomial coefficient n over k, also called the "choose"
308       function. The result is equivalent to:
309
310               ( n )      n!
311               | - |  = -------
312               ( k )    k!(n-k)!
313
314       This method was added in v0.20 of Math::BigRat (May 2007).
315
316   config()
317               use Data::Dumper;
318
319               print Dumper ( Math::BigRat->config() );
320               print Math::BigRat->config()->{lib},"\n";
321
322       Returns a hash containing the configuration, e.g. the version number,
323       lib loaded etc. The following hash keys are currently filled in with
324       the appropriate information.
325
326               key             RO/RW   Description
327                                       Example
328               ============================================================
329               lib             RO      Name of the Math library
330                                       Math::BigInt::Calc
331               lib_version     RO      Version of 'lib'
332                                       0.30
333               class           RO      The class of config you just called
334                                       Math::BigRat
335               version         RO      version number of the class you used
336                                       0.10
337               upgrade         RW      To which class numbers are upgraded
338                                       undef
339               downgrade       RW      To which class numbers are downgraded
340                                       undef
341               precision       RW      Global precision
342                                       undef
343               accuracy        RW      Global accuracy
344                                       undef
345               round_mode      RW      Global round mode
346                                       even
347               div_scale       RW      Fallback accuracy for div
348                                       40
349               trap_nan        RW      Trap creation of NaN (undef = no)
350                                       undef
351               trap_inf        RW      Trap creation of +inf/-inf (undef = no)
352                                       undef
353
354       By passing a reference to a hash you may set the configuration values.
355       This works only for values that a marked with a "RW" above, anything
356       else is read-only.
357
358   objectify()
359       This is an internal routine that turns scalars into objects.
360

BUGS

362       Some things are not yet implemented, or only implemented half-way:
363
364       inf handling (partial)
365       NaN handling (partial)
366       rounding (not implemented except for bceil/bfloor)
367       $x ** $y where $y is not an integer
368       bmod(), blog(), bmodinv() and bmodpow() (partial)
369

LICENSE

371       This program is free software; you may redistribute it and/or modify it
372       under the same terms as Perl itself.
373

AUTHORS

385       (C) by Tels <http://bloodgate.com/> 2001 - 2009.
386
387       Currently maintained by Jonathan "Duke" Leto <jonathan@leto.net>
388       <http://leto.net>
389
390
391
392perl v5.12.4                      2011-06-20                 Math::BigRat(3pm)