Debian Codegraph @

upstream/debian-unstable/man3/Math::BigRat.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Math::BigRat 3perl"
58 .TH Math::BigRat 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Math::BigRat \- arbitrary size rational number math package
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Math::BigRat;
69 \&
70 \& my $x = Math::BigRat\->new(\*(Aq3/7\*(Aq); $x += \*(Aq5/9\*(Aq;
71 \&
72 \& print $x\->bstr(), "\en";
73 \& print $x ** 2, "\en";
74 \&
75 \& my $y = Math::BigRat\->new(\*(Aqinf\*(Aq);
76 \& print "$y ", ($y\->is_inf ? \*(Aqis\*(Aq : \*(Aqis not\*(Aq), " infinity\en";
77 \&
78 \& my $z = Math::BigRat\->new(144); $z\->bsqrt();
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 Math::BigRat complements Math::BigInt and Math::BigFloat by providing support
83 for arbitrary big rational numbers.
84 .SS "MATH LIBRARY"
85 .IX Subsection "MATH LIBRARY"
86 You can change the underlying module that does the low-level
87 math operations by using:
88 .PP
89 .Vb 1
90 \& use Math::BigRat try => \*(AqGMP\*(Aq;
91 .Ve
92 .PP
93 Note: This needs Math::BigInt::GMP installed.
94 .PP
95 The following would first try to find Math::BigInt::Foo, then
96 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
97 .PP
98 .Vb 1
99 \& use Math::BigRat try => \*(AqFoo,Math::BigInt::Bar\*(Aq;
100 .Ve
101 .PP
102 If you want to get warned when the fallback occurs, replace "try" with "lib":
103 .PP
104 .Vb 1
105 \& use Math::BigRat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq;
106 .Ve
107 .PP
108 If you want the code to die instead, replace "try" with "only":
109 .PP
110 .Vb 1
111 \& use Math::BigRat only => \*(AqFoo,Math::BigInt::Bar\*(Aq;
112 .Ve
113 .SH METHODS
114 .IX Header "METHODS"
115 Any methods not listed here are derived from Math::BigFloat (or
116 Math::BigInt), so make sure you check these two modules for further
117 information.
118 .IP \fBnew()\fR 4
119 .IX Item "new()"
120 .Vb 1
121 \& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq);
122 .Ve
123 .Sp
124 Create a new Math::BigRat object. Input can come in various forms:
125 .Sp
126 .Vb 9
127 \& $x = Math::BigRat\->new(123); # scalars
128 \& $x = Math::BigRat\->new(\*(Aqinf\*(Aq); # infinity
129 \& $x = Math::BigRat\->new(\*(Aq123.3\*(Aq); # float
130 \& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); # simple string
131 \& $x = Math::BigRat\->new(\*(Aq1 / 3\*(Aq); # spaced
132 \& $x = Math::BigRat\->new(\*(Aq1 / 0.1\*(Aq); # w/ floats
133 \& $x = Math::BigRat\->new(Math::BigInt\->new(3)); # BigInt
134 \& $x = Math::BigRat\->new(Math::BigFloat\->new(\*(Aq3.1\*(Aq)); # BigFloat
135 \& $x = Math::BigRat\->new(Math::BigInt::Lite\->new(\*(Aq2\*(Aq)); # BigLite
136 \&
137 \& # You can also give D and N as different objects:
138 \& $x = Math::BigRat\->new(
139 \& Math::BigInt\->new(\-123),
140 \& Math::BigInt\->new(7),
141 \& ); # => \-123/7
142 .Ve
143 .IP \fBnumerator()\fR 4
144 .IX Item "numerator()"
145 .Vb 1
146 \& $n = $x\->numerator();
147 .Ve
148 .Sp
149 Returns a copy of the numerator (the part above the line) as signed BigInt.
150 .IP \fBdenominator()\fR 4
151 .IX Item "denominator()"
152 .Vb 1
153 \& $d = $x\->denominator();
154 .Ve
155 .Sp
156 Returns a copy of the denominator (the part under the line) as positive BigInt.
157 .IP \fBparts()\fR 4
158 .IX Item "parts()"
159 .Vb 1
160 \& ($n, $d) = $x\->parts();
161 .Ve
162 .Sp
163 Return a list consisting of (signed) numerator and (unsigned) denominator as
164 BigInts.
165 .IP \fBdparts()\fR 4
166 .IX Item "dparts()"
167 Returns the integer part and the fraction part.
168 .IP \fBfparts()\fR 4
169 .IX Item "fparts()"
170 Returns the smallest possible numerator and denominator so that the numerator
171 divided by the denominator gives back the original value. For finite numbers,
172 both values are integers. Mnemonic: fraction.
173 .IP \fBnumify()\fR 4
174 .IX Item "numify()"
175 .Vb 1
176 \& my $y = $x\->numify();
177 .Ve
178 .Sp
179 Returns the object as a scalar. This will lose some data if the object
180 cannot be represented by a normal Perl scalar (integer or float), so
181 use "\fBas_int()\fR" or "\fBas_float()\fR" instead.
182 .Sp
183 This routine is automatically used whenever a scalar is required:
184 .Sp
185 .Vb 3
186 \& my $x = Math::BigRat\->new(\*(Aq3/1\*(Aq);
187 \& @array = (0, 1, 2, 3);
188 \& $y = $array[$x]; # set $y to 3
189 .Ve
190 .IP \fBas_int()\fR 4
191 .IX Item "as_int()"
192 .PD 0
193 .IP \fBas_number()\fR 4
194 .IX Item "as_number()"
195 .PD
196 .Vb 2
197 \& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq);
198 \& print $x\->as_int(), "\en"; # \*(Aq1\*(Aq
199 .Ve
200 .Sp
201 Returns a copy of the object as BigInt, truncated to an integer.
202 .Sp
203 \&\f(CWas_number()\fR is an alias for \f(CWas_int()\fR.
204 .IP \fBas_float()\fR 4
205 .IX Item "as_float()"
206 .Vb 2
207 \& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq);
208 \& print $x\->as_float(), "\en"; # \*(Aq1\*(Aq
209 \&
210 \& $x = Math::BigRat\->new(\*(Aq2/3\*(Aq);
211 \& print $x\->as_float(5), "\en"; # \*(Aq0.66667\*(Aq
212 .Ve
213 .Sp
214 Returns a copy of the object as BigFloat, preserving the
215 accuracy as wanted, or the default of 40 digits.
216 .Sp
217 This method was added in v0.22 of Math::BigRat (April 2008).
218 .IP \fBas_hex()\fR 4
219 .IX Item "as_hex()"
220 .Vb 2
221 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq);
222 \& print $x\->as_hex(), "\en"; # \*(Aq0xd\*(Aq
223 .Ve
224 .Sp
225 Returns the BigRat as hexadecimal string. Works only for integers.
226 .IP \fBas_bin()\fR 4
227 .IX Item "as_bin()"
228 .Vb 2
229 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq);
230 \& print $x\->as_bin(), "\en"; # \*(Aq0x1101\*(Aq
231 .Ve
232 .Sp
233 Returns the BigRat as binary string. Works only for integers.
234 .IP \fBas_oct()\fR 4
235 .IX Item "as_oct()"
236 .Vb 2
237 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq);
238 \& print $x\->as_oct(), "\en"; # \*(Aq015\*(Aq
239 .Ve
240 .Sp
241 Returns the BigRat as octal string. Works only for integers.
242 .IP \fBfrom_hex()\fR 4
243 .IX Item "from_hex()"
244 .Vb 1
245 \& my $h = Math::BigRat\->from_hex(\*(Aq0x10\*(Aq);
246 .Ve
247 .Sp
248 Create a BigRat from a hexadecimal number in string form.
249 .IP \fBfrom_oct()\fR 4
250 .IX Item "from_oct()"
251 .Vb 1
252 \& my $o = Math::BigRat\->from_oct(\*(Aq020\*(Aq);
253 .Ve
254 .Sp
255 Create a BigRat from an octal number in string form.
256 .IP \fBfrom_bin()\fR 4
257 .IX Item "from_bin()"
258 .Vb 1
259 \& my $b = Math::BigRat\->from_bin(\*(Aq0b10000000\*(Aq);
260 .Ve
261 .Sp
262 Create a BigRat from an binary number in string form.
263 .IP \fBbnan()\fR 4
264 .IX Item "bnan()"
265 .Vb 1
266 \& $x = Math::BigRat\->bnan();
267 .Ve
268 .Sp
269 Creates a new BigRat object representing NaN (Not A Number).
270 If used on an object, it will set it to NaN:
271 .Sp
272 .Vb 1
273 \& $x\->bnan();
274 .Ve
275 .IP \fBbzero()\fR 4
276 .IX Item "bzero()"
277 .Vb 1
278 \& $x = Math::BigRat\->bzero();
279 .Ve
280 .Sp
281 Creates a new BigRat object representing zero.
282 If used on an object, it will set it to zero:
283 .Sp
284 .Vb 1
285 \& $x\->bzero();
286 .Ve
287 .IP \fBbinf()\fR 4
288 .IX Item "binf()"
289 .Vb 1
290 \& $x = Math::BigRat\->binf($sign);
291 .Ve
292 .Sp
293 Creates a new BigRat object representing infinity. The optional argument is
294 either '\-' or '+', indicating whether you want infinity or minus infinity.
295 If used on an object, it will set it to infinity:
296 .Sp
297 .Vb 2
298 \& $x\->binf();
299 \& $x\->binf(\*(Aq\-\*(Aq);
300 .Ve
301 .IP \fBbone()\fR 4
302 .IX Item "bone()"
303 .Vb 1
304 \& $x = Math::BigRat\->bone($sign);
305 .Ve
306 .Sp
307 Creates a new BigRat object representing one. The optional argument is
308 either '\-' or '+', indicating whether you want one or minus one.
309 If used on an object, it will set it to one:
310 .Sp
311 .Vb 2
312 \& $x\->bone(); # +1
313 \& $x\->bone(\*(Aq\-\*(Aq); # \-1
314 .Ve
315 .IP \fBlength()\fR 4
316 .IX Item "length()"
317 .Vb 1
318 \& $len = $x\->length();
319 .Ve
320 .Sp
321 Return the length of \f(CW$x\fR in digits for integer values.
322 .IP \fBdigit()\fR 4
323 .IX Item "digit()"
324 .Vb 2
325 \& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(1); # 1
326 \& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(\-1); # 3
327 .Ve
328 .Sp
329 Return the N'ths digit from X when X is an integer value.
330 .IP \fBbnorm()\fR 4
331 .IX Item "bnorm()"
332 .Vb 1
333 \& $x\->bnorm();
334 .Ve
335 .Sp
336 Reduce the number to the shortest form. This routine is called
337 automatically whenever it is needed.
338 .IP \fBbfac()\fR 4
339 .IX Item "bfac()"
340 .Vb 1
341 \& $x\->bfac();
342 .Ve
343 .Sp
344 Calculates the factorial of \f(CW$x\fR. For instance:
345 .Sp
346 .Vb 2
347 \& print Math::BigRat\->new(\*(Aq3/1\*(Aq)\->bfac(), "\en"; # 1*2*3
348 \& print Math::BigRat\->new(\*(Aq5/1\*(Aq)\->bfac(), "\en"; # 1*2*3*4*5
349 .Ve
350 .Sp
351 Works currently only for integers.
352 .IP \fBbround()\fR/\fBround()\fR/\fBbfround()\fR 4
353 .IX Item "bround()/round()/bfround()"
354 Are not yet implemented.
355 .IP \fBbmod()\fR 4
356 .IX Item "bmod()"
357 .Vb 1
358 \& $x\->bmod($y);
359 .Ve
360 .Sp
361 Returns \f(CW$x\fR modulo \f(CW$y\fR. When \f(CW$x\fR is finite, and \f(CW$y\fR is finite and non-zero, the
362 result is identical to the remainder after floored division (F\-division). If,
363 in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result
364 from Perl's % operator.
365 .IP \fBbmodinv()\fR 4
366 .IX Item "bmodinv()"
367 .Vb 1
368 \& $x\->bmodinv($mod); # modular multiplicative inverse
369 .Ve
370 .Sp
371 Returns the multiplicative inverse of \f(CW$x\fR modulo \f(CW$mod\fR. If
372 .Sp
373 .Vb 1
374 \& $y = $x \-> copy() \-> bmodinv($mod)
375 .Ve
376 .Sp
377 then \f(CW$y\fR is the number closest to zero, and with the same sign as \f(CW$mod\fR,
378 satisfying
379 .Sp
380 .Vb 1
381 \& ($x * $y) % $mod = 1 % $mod
382 .Ve
383 .Sp
384 If \f(CW$x\fR and \f(CW$y\fR are non-zero, they must be relative primes, i.e.,
385 \&\f(CW\*(C`bgcd($y, $mod)==1\*(C'\fR. '\f(CW\*(C`NaN\*(C'\fR' is returned when no modular multiplicative
386 inverse exists.
387 .IP \fBbmodpow()\fR 4
388 .IX Item "bmodpow()"
389 .Vb 2
390 \& $num\->bmodpow($exp,$mod); # modular exponentiation
391 \& # ($num**$exp % $mod)
392 .Ve
393 .Sp
394 Returns the value of \f(CW$num\fR taken to the power \f(CW$exp\fR in the modulus
395 \&\f(CW$mod\fR using binary exponentiation. \f(CW\*(C`bmodpow\*(C'\fR is far superior to
396 writing
397 .Sp
398 .Vb 1
399 \& $num ** $exp % $mod
400 .Ve
401 .Sp
402 because it is much faster \- it reduces internal variables into
403 the modulus whenever possible, so it operates on smaller numbers.
404 .Sp
405 \&\f(CW\*(C`bmodpow\*(C'\fR also supports negative exponents.
406 .Sp
407 .Vb 1
408 \& bmodpow($num, \-1, $mod)
409 .Ve
410 .Sp
411 is exactly equivalent to
412 .Sp
413 .Vb 1
414 \& bmodinv($num, $mod)
415 .Ve
416 .IP \fBbneg()\fR 4
417 .IX Item "bneg()"
418 .Vb 1
419 \& $x\->bneg();
420 .Ve
421 .Sp
422 Used to negate the object in-place.
423 .IP \fBis_one()\fR 4
424 .IX Item "is_one()"
425 .Vb 1
426 \& print "$x is 1\en" if $x\->is_one();
427 .Ve
428 .Sp
429 Return true if \f(CW$x\fR is exactly one, otherwise false.
430 .IP \fBis_zero()\fR 4
431 .IX Item "is_zero()"
432 .Vb 1
433 \& print "$x is 0\en" if $x\->is_zero();
434 .Ve
435 .Sp
436 Return true if \f(CW$x\fR is exactly zero, otherwise false.
437 .IP \fBis_pos()\fR/\fBis_positive()\fR 4
438 .IX Item "is_pos()/is_positive()"
439 .Vb 1
440 \& print "$x is >= 0\en" if $x\->is_positive();
441 .Ve
442 .Sp
443 Return true if \f(CW$x\fR is positive (greater than or equal to zero), otherwise
444 false. Please note that '+inf' is also positive, while 'NaN' and '\-inf' aren't.
445 .Sp
446 \&\f(CWis_positive()\fR is an alias for \f(CWis_pos()\fR.
447 .IP \fBis_neg()\fR/\fBis_negative()\fR 4
448 .IX Item "is_neg()/is_negative()"
449 .Vb 1
450 \& print "$x is < 0\en" if $x\->is_negative();
451 .Ve
452 .Sp
453 Return true if \f(CW$x\fR is negative (smaller than zero), otherwise false. Please
454 note that '\-inf' is also negative, while 'NaN' and '+inf' aren't.
455 .Sp
456 \&\f(CWis_negative()\fR is an alias for \f(CWis_neg()\fR.
457 .IP \fBis_int()\fR 4
458 .IX Item "is_int()"
459 .Vb 1
460 \& print "$x is an integer\en" if $x\->is_int();
461 .Ve
462 .Sp
463 Return true if \f(CW$x\fR has a denominator of 1 (e.g. no fraction parts), otherwise
464 false. Please note that '\-inf', 'inf' and 'NaN' aren't integer.
465 .IP \fBis_odd()\fR 4
466 .IX Item "is_odd()"
467 .Vb 1
468 \& print "$x is odd\en" if $x\->is_odd();
469 .Ve
470 .Sp
471 Return true if \f(CW$x\fR is odd, otherwise false.
472 .IP \fBis_even()\fR 4
473 .IX Item "is_even()"
474 .Vb 1
475 \& print "$x is even\en" if $x\->is_even();
476 .Ve
477 .Sp
478 Return true if \f(CW$x\fR is even, otherwise false.
479 .IP \fBbceil()\fR 4
480 .IX Item "bceil()"
481 .Vb 1
482 \& $x\->bceil();
483 .Ve
484 .Sp
485 Set \f(CW$x\fR to the next bigger integer value (e.g. truncate the number to integer
486 and then increment it by one).
487 .IP \fBbfloor()\fR 4
488 .IX Item "bfloor()"
489 .Vb 1
490 \& $x\->bfloor();
491 .Ve
492 .Sp
493 Truncate \f(CW$x\fR to an integer value.
494 .IP \fBbint()\fR 4
495 .IX Item "bint()"
496 .Vb 1
497 \& $x\->bint();
498 .Ve
499 .Sp
500 Round \f(CW$x\fR towards zero.
501 .IP \fBbsqrt()\fR 4
502 .IX Item "bsqrt()"
503 .Vb 1
504 \& $x\->bsqrt();
505 .Ve
506 .Sp
507 Calculate the square root of \f(CW$x\fR.
508 .IP \fBbroot()\fR 4
509 .IX Item "broot()"
510 .Vb 1
511 \& $x\->broot($n);
512 .Ve
513 .Sp
514 Calculate the N'th root of \f(CW$x\fR.
515 .IP \fBbadd()\fR 4
516 .IX Item "badd()"
517 .Vb 1
518 \& $x\->badd($y);
519 .Ve
520 .Sp
521 Adds \f(CW$y\fR to \f(CW$x\fR and returns the result.
522 .IP \fBbmul()\fR 4
523 .IX Item "bmul()"
524 .Vb 1
525 \& $x\->bmul($y);
526 .Ve
527 .Sp
528 Multiplies \f(CW$y\fR to \f(CW$x\fR and returns the result.
529 .IP \fBbsub()\fR 4
530 .IX Item "bsub()"
531 .Vb 1
532 \& $x\->bsub($y);
533 .Ve
534 .Sp
535 Subtracts \f(CW$y\fR from \f(CW$x\fR and returns the result.
536 .IP \fBbdiv()\fR 4
537 .IX Item "bdiv()"
538 .Vb 2
539 \& $q = $x\->bdiv($y);
540 \& ($q, $r) = $x\->bdiv($y);
541 .Ve
542 .Sp
543 In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result. In list context,
544 does floored division (F\-division), returning an integer \f(CW$q\fR and a remainder \f(CW$r\fR
545 so that \f(CW$x\fR = \f(CW$q\fR * \f(CW$y\fR + \f(CW$r\fR. The remainer (modulo) is equal to what is returned
546 by \f(CW\*(C`$x\->bmod($y)\*(C'\fR.
547 .IP \fBbinv()\fR 4
548 .IX Item "binv()"
549 .Vb 1
550 \& $x\->binv();
551 .Ve
552 .Sp
553 Inverse of \f(CW$x\fR.
554 .IP \fBbdec()\fR 4
555 .IX Item "bdec()"
556 .Vb 1
557 \& $x\->bdec();
558 .Ve
559 .Sp
560 Decrements \f(CW$x\fR by 1 and returns the result.
561 .IP \fBbinc()\fR 4
562 .IX Item "binc()"
563 .Vb 1
564 \& $x\->binc();
565 .Ve
566 .Sp
567 Increments \f(CW$x\fR by 1 and returns the result.
568 .IP \fBcopy()\fR 4
569 .IX Item "copy()"
570 .Vb 1
571 \& my $z = $x\->copy();
572 .Ve
573 .Sp
574 Makes a deep copy of the object.
575 .Sp
576 Please see the documentation in Math::BigInt for further details.
577 .IP \fBbstr()\fR/\fBbsstr()\fR 4
578 .IX Item "bstr()/bsstr()"
579 .Vb 3
580 \& my $x = Math::BigRat\->new(\*(Aq8/4\*(Aq);
581 \& print $x\->bstr(), "\en"; # prints 1/2
582 \& print $x\->bsstr(), "\en"; # prints 1/2
583 .Ve
584 .Sp
585 Return a string representing this object.
586 .IP \fBbcmp()\fR 4
587 .IX Item "bcmp()"
588 .Vb 1
589 \& $x\->bcmp($y);
590 .Ve
591 .Sp
592 Compares \f(CW$x\fR with \f(CW$y\fR and takes the sign into account.
593 Returns \-1, 0, 1 or undef.
594 .IP \fBbacmp()\fR 4
595 .IX Item "bacmp()"
596 .Vb 1
597 \& $x\->bacmp($y);
598 .Ve
599 .Sp
600 Compares \f(CW$x\fR with \f(CW$y\fR while ignoring their sign. Returns \-1, 0, 1 or undef.
601 .IP \fBbeq()\fR 4
602 .IX Item "beq()"
603 .Vb 1
604 \& $x \-> beq($y);
605 .Ve
606 .Sp
607 Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise.
608 .IP \fBbne()\fR 4
609 .IX Item "bne()"
610 .Vb 1
611 \& $x \-> bne($y);
612 .Ve
613 .Sp
614 Returns true if and only if \f(CW$x\fR is not equal to \f(CW$y\fR, and false otherwise.
615 .IP \fBblt()\fR 4
616 .IX Item "blt()"
617 .Vb 1
618 \& $x \-> blt($y);
619 .Ve
620 .Sp
621 Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise.
622 .IP \fBble()\fR 4
623 .IX Item "ble()"
624 .Vb 1
625 \& $x \-> ble($y);
626 .Ve
627 .Sp
628 Returns true if and only if \f(CW$x\fR is less than or equal to \f(CW$y\fR, and false
629 otherwise.
630 .IP \fBbgt()\fR 4
631 .IX Item "bgt()"
632 .Vb 1
633 \& $x \-> bgt($y);
634 .Ve
635 .Sp
636 Returns true if and only if \f(CW$x\fR is greater than \f(CW$y\fR, and false otherwise.
637 .IP \fBbge()\fR 4
638 .IX Item "bge()"
639 .Vb 1
640 \& $x \-> bge($y);
641 .Ve
642 .Sp
643 Returns true if and only if \f(CW$x\fR is greater than or equal to \f(CW$y\fR, and false
644 otherwise.
645 .IP \fBblsft()\fR/\fBbrsft()\fR 4
646 .IX Item "blsft()/brsft()"
647 Used to shift numbers left/right.
648 .Sp
649 Please see the documentation in Math::BigInt for further details.
650 .IP \fBband()\fR 4
651 .IX Item "band()"
652 .Vb 1
653 \& $x\->band($y); # bitwise and
654 .Ve
655 .IP \fBbior()\fR 4
656 .IX Item "bior()"
657 .Vb 1
658 \& $x\->bior($y); # bitwise inclusive or
659 .Ve
660 .IP \fBbxor()\fR 4
661 .IX Item "bxor()"
662 .Vb 1
663 \& $x\->bxor($y); # bitwise exclusive or
664 .Ve
665 .IP \fBbnot()\fR 4
666 .IX Item "bnot()"
667 .Vb 1
668 \& $x\->bnot(); # bitwise not (two\*(Aqs complement)
669 .Ve
670 .IP \fBbpow()\fR 4
671 .IX Item "bpow()"
672 .Vb 1
673 \& $x\->bpow($y);
674 .Ve
675 .Sp
676 Compute \f(CW$x\fR ** \f(CW$y\fR.
677 .Sp
678 Please see the documentation in Math::BigInt for further details.
679 .IP \fBblog()\fR 4
680 .IX Item "blog()"
681 .Vb 1
682 \& $x\->blog($base, $accuracy); # logarithm of x to the base $base
683 .Ve
684 .Sp
685 If \f(CW$base\fR is not defined, Euler's number (e) is used:
686 .Sp
687 .Vb 1
688 \& print $x\->blog(undef, 100); # log(x) to 100 digits
689 .Ve
690 .IP \fBbexp()\fR 4
691 .IX Item "bexp()"
692 .Vb 1
693 \& $x\->bexp($accuracy); # calculate e ** X
694 .Ve
695 .Sp
696 Calculates two integers A and B so that A/B is equal to \f(CW\*(C`e ** $x\*(C'\fR, where \f(CW\*(C`e\*(C'\fR is
697 Euler's number.
698 .Sp
699 This method was added in v0.20 of Math::BigRat (May 2007).
700 .Sp
701 See also \f(CWblog()\fR.
702 .IP \fBbnok()\fR 4
703 .IX Item "bnok()"
704 .Vb 1
705 \& $x\->bnok($y); # x over y (binomial coefficient n over k)
706 .Ve
707 .Sp
708 Calculates the binomial coefficient n over k, also called the "choose"
709 function. The result is equivalent to:
710 .Sp
711 .Vb 3
712 \& ( n ) n!
713 \& | \- | = \-\-\-\-\-\-\-
714 \& ( k ) k!(n\-k)!
715 .Ve
716 .Sp
717 This method was added in v0.20 of Math::BigRat (May 2007).
718 .IP \fBconfig()\fR 4
719 .IX Item "config()"
720 .Vb 2
721 \& Math::BigRat\->config("trap_nan" => 1); # set
722 \& $accu = Math::BigRat\->config("accuracy"); # get
723 .Ve
724 .Sp
725 Set or get configuration parameter values. Read-only parameters are marked as
726 RO. Read-write parameters are marked as RW. The following parameters are
727 supported.
728 .Sp
729 .Vb 10
730 \& Parameter RO/RW Description
731 \& Example
732 \& ============================================================
733 \& lib RO Name of the math backend library
734 \& Math::BigInt::Calc
735 \& lib_version RO Version of the math backend library
736 \& 0.30
737 \& class RO The class of config you just called
738 \& Math::BigRat
739 \& version RO version number of the class you used
740 \& 0.10
741 \& upgrade RW To which class numbers are upgraded
742 \& undef
743 \& downgrade RW To which class numbers are downgraded
744 \& undef
745 \& precision RW Global precision
746 \& undef
747 \& accuracy RW Global accuracy
748 \& undef
749 \& round_mode RW Global round mode
750 \& even
751 \& div_scale RW Fallback accuracy for div, sqrt etc.
752 \& 40
753 \& trap_nan RW Trap NaNs
754 \& undef
755 \& trap_inf RW Trap +inf/\-inf
756 \& undef
757 .Ve
758 .SH "NUMERIC LITERALS"
759 .IX Header "NUMERIC LITERALS"
760 After \f(CW\*(C`use Math::BigRat \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope
761 are converted to \f(CW\*(C`Math::BigRat\*(C'\fR objects. This conversion happens at compile
762 time. Every non-integer is convert to a NaN.
763 .PP
764 For example,
765 .PP
766 .Vb 1
767 \& perl \-MMath::BigRat=:constant \-le \*(Aqprint 2**150\*(Aq
768 .Ve
769 .PP
770 prints the exact value of \f(CW\*(C`2**150\*(C'\fR. Note that without conversion of constants
771 to objects the expression \f(CW\*(C`2**150\*(C'\fR is calculated using Perl scalars, which
772 leads to an inaccurate result.
773 .PP
774 Please note that strings are not affected, so that
775 .PP
776 .Vb 1
777 \& use Math::BigRat qw/:constant/;
778 \&
779 \& $x = "1234567890123456789012345678901234567890"
780 \& + "123456789123456789";
781 .Ve
782 .PP
783 does give you what you expect. You need an explicit Math::BigRat\->\fBnew()\fR around
784 at least one of the operands. You should also quote large constants to prevent
785 loss of precision:
786 .PP
787 .Vb 1
788 \& use Math::BigRat;
789 \&
790 \& $x = Math::BigRat\->new("1234567889123456789123456789123456789");
791 .Ve
792 .PP
793 Without the quotes Perl first converts the large number to a floating point
794 constant at compile time, and then converts the result to a Math::BigRat object
795 at run time, which results in an inaccurate result.
796 .SS "Hexadecimal, octal, and binary floating point literals"
797 .IX Subsection "Hexadecimal, octal, and binary floating point literals"
798 Perl (and this module) accepts hexadecimal, octal, and binary floating point
799 literals, but use them with care with Perl versions before v5.32.0, because some
800 versions of Perl silently give the wrong result. Below are some examples of
801 different ways to write the number decimal 314.
802 .PP
803 Hexadecimal floating point literals:
804 .PP
805 .Vb 3
806 \& 0x1.3ap+8 0X1.3AP+8
807 \& 0x1.3ap8 0X1.3AP8
808 \& 0x13a0p\-4 0X13A0P\-4
809 .Ve
810 .PP
811 Octal floating point literals (with "0" prefix):
812 .PP
813 .Vb 3
814 \& 01.164p+8 01.164P+8
815 \& 01.164p8 01.164P8
816 \& 011640p\-4 011640P\-4
817 .Ve
818 .PP
819 Octal floating point literals (with "0o" prefix) (requires v5.34.0):
820 .PP
821 .Vb 3
822 \& 0o1.164p+8 0O1.164P+8
823 \& 0o1.164p8 0O1.164P8
824 \& 0o11640p\-4 0O11640P\-4
825 .Ve
826 .PP
827 Binary floating point literals:
828 .PP
829 .Vb 3
830 \& 0b1.0011101p+8 0B1.0011101P+8
831 \& 0b1.0011101p8 0B1.0011101P8
832 \& 0b10011101000p\-2 0B10011101000P\-2
833 .Ve
834 .SH BUGS
835 .IX Header "BUGS"
836 Please report any bugs or feature requests to
837 \&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at
838 <https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login).
839 We will be notified, and then you'll automatically be notified of progress on
840 your bug as I make changes.
841 .SH SUPPORT
842 .IX Header "SUPPORT"
843 You can find documentation for this module with the perldoc command.
844 .PP
845 .Vb 1
846 \& perldoc Math::BigInt
847 .Ve
848 .PP
849 You can also look for information at:
850 .IP \(bu 4
851 GitHub
852 .Sp
853 <https://github.com/pjacklam/p5\-Math\-BigInt>
854 .IP \(bu 4
855 RT: CPAN's request tracker
856 .Sp
857 <https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt>
858 .IP \(bu 4
859 MetaCPAN
860 .Sp
861 <https://metacpan.org/release/Math\-BigInt>
862 .IP \(bu 4
863 CPAN Testers Matrix
864 .Sp
865 <http://matrix.cpantesters.org/?dist=Math\-BigInt>
866 .SH LICENSE
867 .IX Header "LICENSE"
868 This program is free software; you may redistribute it and/or modify it under
869 the same terms as Perl itself.
870 .SH "SEE ALSO"
871 .IX Header "SEE ALSO"
872 Math::BigInt and Math::BigFloat as well as the backend libraries
873 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari,
874 Math::BigInt::GMPz, and Math::BigInt::BitVect.
875 .PP
876 The pragmas bigint, bigfloat, and bigrat might also be of interest. In
877 addition there is the bignum pragma which does upgrading and downgrading.
878 .SH AUTHORS
879 .IX Header "AUTHORS"
880 .IP \(bu 4
881 Tels <http://bloodgate.com/> 2001\-2009.
882 .IP \(bu 4
883 Maintained by Peter John Acklam <[email protected]> 2011\-