1Math::BigRat(3)       User Contributed Perl Documentation      Math::BigRat(3)
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
84           positive 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
96           object cannot be represented by a normal Perl scalar (integer or
97           float), so 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()
106       as_number()
107               $x = Math::BigRat->new('13/7');
108               print $x->as_int(), "\n";               # '1'
109
110           Returns a copy of the object as BigInt, truncated to an integer.
111
112           "as_number()" is an alias for "as_int()".
113
114       as_float()
115               $x = Math::BigRat->new('13/7');
116               print $x->as_float(), "\n";             # '1'
117
118               $x = Math::BigRat->new('2/3');
119               print $x->as_float(5), "\n";            # '0.66667'
120
121           Returns a copy of the object as BigFloat, preserving the accuracy
122           as wanted, or the default of 40 digits.
123
124           This method was added in v0.22 of Math::BigRat (April 2008).
125
126       as_hex()
127               $x = Math::BigRat->new('13');
128               print $x->as_hex(), "\n";               # '0xd'
129
130           Returns the BigRat as hexadecimal string. Works only for integers.
131
132       as_bin()
133               $x = Math::BigRat->new('13');
134               print $x->as_bin(), "\n";               # '0x1101'
135
136           Returns the BigRat as binary string. Works only for integers.
137
138       as_oct()
139               $x = Math::BigRat->new('13');
140               print $x->as_oct(), "\n";               # '015'
141
142           Returns the BigRat as octal string. Works only for integers.
143
144       from_hex()
145               my $h = Math::BigRat->from_hex('0x10');
146
147           Create a BigRat from a hexadecimal number in string form.
148
149       from_oct()
150               my $o = Math::BigRat->from_oct('020');
151
152           Create a BigRat from an octal number in string form.
153
154       from_bin()
155               my $b = Math::BigRat->from_bin('0b10000000');
156
157           Create a BigRat from an binary number in string form.
158
159       bnan()
160               $x = Math::BigRat->bnan();
161
162           Creates a new BigRat object representing NaN (Not A Number).  If
163           used on an object, it will set it to NaN:
164
165               $x->bnan();
166
167       bzero()
168               $x = Math::BigRat->bzero();
169
170           Creates a new BigRat object representing zero.  If used on an
171           object, it will set it to zero:
172
173               $x->bzero();
174
175       binf()
176               $x = Math::BigRat->binf($sign);
177
178           Creates a new BigRat object representing infinity. The optional
179           argument is either '-' or '+', indicating whether you want infinity
180           or minus infinity.  If used on an object, it will set it to
181           infinity:
182
183               $x->binf();
184               $x->binf('-');
185
186       bone()
187               $x = Math::BigRat->bone($sign);
188
189           Creates a new BigRat object representing one. The optional argument
190           is either '-' or '+', indicating whether you want one or minus one.
191           If used on an object, it will set it to one:
192
193               $x->bone();                 # +1
194               $x->bone('-');              # -1
195
196       length()
197               $len = $x->length();
198
199           Return the length of $x in digits for integer values.
200
201       digit()
202               print Math::BigRat->new('123/1')->digit(1);     # 1
203               print Math::BigRat->new('123/1')->digit(-1);    # 3
204
205           Return the N'ths digit from X when X is an integer value.
206
207       bnorm()
208               $x->bnorm();
209
210           Reduce the number to the shortest form. This routine is called
211           automatically whenever it is needed.
212
213       bfac()
214               $x->bfac();
215
216           Calculates the factorial of $x. For instance:
217
218               print Math::BigRat->new('3/1')->bfac(), "\n";   # 1*2*3
219               print Math::BigRat->new('5/1')->bfac(), "\n";   # 1*2*3*4*5
220
221           Works currently only for integers.
222
223       bround()/round()/bfround()
224           Are not yet implemented.
225
226       bmod()
227               $x->bmod($y);
228
229           Returns $x modulo $y. When $x is finite, and $y is finite and non-
230           zero, the result is identical to the remainder after floored
231           division (F-division). If, in addition, both $x and $y are
232           integers, the result is identical to the result from Perl's %
233           operator.
234
235       bmodinv()
236               $x->bmodinv($mod);          # modular multiplicative inverse
237
238           Returns the multiplicative inverse of $x modulo $mod. If
239
240               $y = $x -> copy() -> bmodinv($mod)
241
242           then $y is the number closest to zero, and with the same sign as
243           $mod, satisfying
244
245               ($x * $y) % $mod = 1 % $mod
246
247           If $x and $y are non-zero, they must be relative primes, i.e.,
248           "bgcd($y, $mod)==1". '"NaN"' is returned when no modular
249           multiplicative inverse exists.
250
251       bmodpow()
252               $num->bmodpow($exp,$mod);           # modular exponentiation
253                                                   # ($num**$exp % $mod)
254
255           Returns the value of $num taken to the power $exp in the modulus
256           $mod using binary exponentiation.  "bmodpow" is far superior to
257           writing
258
259               $num ** $exp % $mod
260
261           because it is much faster - it reduces internal variables into the
262           modulus whenever possible, so it operates on smaller numbers.
263
264           "bmodpow" also supports negative exponents.
265
266               bmodpow($num, -1, $mod)
267
268           is exactly equivalent to
269
270               bmodinv($num, $mod)
271
272       bneg()
273               $x->bneg();
274
275           Used to negate the object in-place.
276
277       is_one()
278               print "$x is 1\n" if $x->is_one();
279
280           Return true if $x is exactly one, otherwise false.
281
282       is_zero()
283               print "$x is 0\n" if $x->is_zero();
284
285           Return true if $x is exactly zero, otherwise false.
286
287       is_pos()/is_positive()
288               print "$x is >= 0\n" if $x->is_positive();
289
290           Return true if $x is positive (greater than or equal to zero),
291           otherwise false. Please note that '+inf' is also positive, while
292           'NaN' and '-inf' aren't.
293
294           "is_positive()" is an alias for "is_pos()".
295
296       is_neg()/is_negative()
297               print "$x is < 0\n" if $x->is_negative();
298
299           Return true if $x is negative (smaller than zero), otherwise false.
300           Please note that '-inf' is also negative, while 'NaN' and '+inf'
301           aren't.
302
303           "is_negative()" is an alias for "is_neg()".
304
305       is_int()
306               print "$x is an integer\n" if $x->is_int();
307
308           Return true if $x has a denominator of 1 (e.g. no fraction parts),
309           otherwise false. Please note that '-inf', 'inf' and 'NaN' aren't
310           integer.
311
312       is_odd()
313               print "$x is odd\n" if $x->is_odd();
314
315           Return true if $x is odd, otherwise false.
316
317       is_even()
318               print "$x is even\n" if $x->is_even();
319
320           Return true if $x is even, otherwise false.
321
322       bceil()
323               $x->bceil();
324
325           Set $x to the next bigger integer value (e.g. truncate the number
326           to integer and then increment it by one).
327
328       bfloor()
329               $x->bfloor();
330
331           Truncate $x to an integer value.
332
333       bint()
334               $x->bint();
335
336           Round $x towards zero.
337
338       bsqrt()
339               $x->bsqrt();
340
341           Calculate the square root of $x.
342
343       broot()
344               $x->broot($n);
345
346           Calculate the N'th root of $x.
347
348       badd()
349               $x->badd($y);
350
351           Adds $y to $x and returns the result.
352
353       bmul()
354               $x->bmul($y);
355
356           Multiplies $y to $x and returns the result.
357
358       bsub()
359               $x->bsub($y);
360
361           Subtracts $y from $x and returns the result.
362
363       bdiv()
364               $q = $x->bdiv($y);
365               ($q, $r) = $x->bdiv($y);
366
367           In scalar context, divides $x by $y and returns the result. In list
368           context, does floored division (F-division), returning an integer
369           $q and a remainder $r so that $x = $q * $y + $r. The remainer
370           (modulo) is equal to what is returned by "$x-"bmod($y)>.
371
372       bdec()
373               $x->bdec();
374
375           Decrements $x by 1 and returns the result.
376
377       binc()
378               $x->binc();
379
380           Increments $x by 1 and returns the result.
381
382       copy()
383               my $z = $x->copy();
384
385           Makes a deep copy of the object.
386
387           Please see the documentation in Math::BigInt for further details.
388
389       bstr()/bsstr()
390               my $x = Math::BigRat->new('8/4');
391               print $x->bstr(), "\n";             # prints 1/2
392               print $x->bsstr(), "\n";            # prints 1/2
393
394           Return a string representing this object.
395
396       bcmp()
397               $x->bcmp($y);
398
399           Compares $x with $y and takes the sign into account.  Returns -1,
400           0, 1 or undef.
401
402       bacmp()
403               $x->bacmp($y);
404
405           Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or
406           undef.
407
408       beq()
409               $x -> beq($y);
410
411           Returns true if and only if $x is equal to $y, and false otherwise.
412
413       bne()
414               $x -> bne($y);
415
416           Returns true if and only if $x is not equal to $y, and false
417           otherwise.
418
419       blt()
420               $x -> blt($y);
421
422           Returns true if and only if $x is equal to $y, and false otherwise.
423
424       ble()
425               $x -> ble($y);
426
427           Returns true if and only if $x is less than or equal to $y, and
428           false otherwise.
429
430       bgt()
431               $x -> bgt($y);
432
433           Returns true if and only if $x is greater than $y, and false
434           otherwise.
435
436       bge()
437               $x -> bge($y);
438
439           Returns true if and only if $x is greater than or equal to $y, and
440           false otherwise.
441
442       blsft()/brsft()
443           Used to shift numbers left/right.
444
445           Please see the documentation in Math::BigInt for further details.
446
447       band()
448               $x->band($y);               # bitwise and
449
450       bior()
451               $x->bior($y);               # bitwise inclusive or
452
453       bxor()
454               $x->bxor($y);               # bitwise exclusive or
455
456       bnot()
457               $x->bnot();                 # bitwise not (two's complement)
458
459       bpow()
460               $x->bpow($y);
461
462           Compute $x ** $y.
463
464           Please see the documentation in Math::BigInt for further details.
465
466       blog()
467               $x->blog($base, $accuracy);         # logarithm of x to the base $base
468
469           If $base is not defined, Euler's number (e) is used:
470
471               print $x->blog(undef, 100);         # log(x) to 100 digits
472
473       bexp()
474               $x->bexp($accuracy);        # calculate e ** X
475
476           Calculates two integers A and B so that A/B is equal to "e ** $x",
477           where "e" is Euler's number.
478
479           This method was added in v0.20 of Math::BigRat (May 2007).
480
481           See also "blog()".
482
483       bnok()
484               $x->bnok($y);               # x over y (binomial coefficient n over k)
485
486           Calculates the binomial coefficient n over k, also called the
487           "choose" function. The result is equivalent to:
488
489               ( n )      n!
490               | - |  = -------
491               ( k )    k!(n-k)!
492
493           This method was added in v0.20 of Math::BigRat (May 2007).
494
495       config()
496               Math::BigRat->config("trap_nan" => 1);      # set
497               $accu = Math::BigRat->config("accuracy");   # get
498
499           Set or get configuration parameter values. Read-only parameters are
500           marked as RO. Read-write parameters are marked as RW. The following
501           parameters are supported.
502
503               Parameter       RO/RW   Description
504                                       Example
505               ============================================================
506               lib             RO      Name of the math backend library
507                                       Math::BigInt::Calc
508               lib_version     RO      Version of the math backend library
509                                       0.30
510               class           RO      The class of config you just called
511                                       Math::BigRat
512               version         RO      version number of the class you used
513                                       0.10
514               upgrade         RW      To which class numbers are upgraded
515                                       undef
516               downgrade       RW      To which class numbers are downgraded
517                                       undef
518               precision       RW      Global precision
519                                       undef
520               accuracy        RW      Global accuracy
521                                       undef
522               round_mode      RW      Global round mode
523                                       even
524               div_scale       RW      Fallback accuracy for div, sqrt etc.
525                                       40
526               trap_nan        RW      Trap NaNs
527                                       undef
528               trap_inf        RW      Trap +inf/-inf
529                                       undef
530

BUGS

532       Please report any bugs or feature requests to "bug-math-bigrat at
533       rt.cpan.org", or through the web interface at
534       <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigRat> (requires
535       login).  We will be notified, and then you'll automatically be notified
536       of progress on your bug as I make changes.
537

SUPPORT

539       You can find documentation for this module with the perldoc command.
540
541           perldoc Math::BigRat
542
543       You can also look for information at:
544
545       •   RT: CPAN's request tracker
546
547           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigRat>
548
549       •   AnnoCPAN: Annotated CPAN documentation
550
551           <http://annocpan.org/dist/Math-BigRat>
552
553       •   CPAN Ratings
554
555           <http://cpanratings.perl.org/dist/Math-BigRat>
556
557       •   Search CPAN
558
559           <http://search.cpan.org/dist/Math-BigRat/>
560
561       •   CPAN Testers Matrix
562
563           <http://matrix.cpantesters.org/?dist=Math-BigRat>
564
565       •   The Bignum mailing list
566
567           •   Post to mailing list
568
569               "bignum at lists.scsys.co.uk"
570
571           •   View mailing list
572
573               <http://lists.scsys.co.uk/pipermail/bignum/>
574
575           •   Subscribe/Unsubscribe
576
577               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
578

LICENSE

580       This program is free software; you may redistribute it and/or modify it
581       under the same terms as Perl itself.
582

SEE ALSO

584       bigrat, Math::BigFloat and Math::BigInt as well as the backends
585       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
586

AUTHORS

588       •   Tels <http://bloodgate.com/> 2001-2009.
589
590       •   Maintained by Peter John Acklam <pjacklam@online.no> 2011-
591
592
593
594perl v5.32.1                      2021-01-27                   Math::BigRat(3)