.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Math::BigRat 3perl" .TH Math::BigRat 3perl "2018-11-29" "perl v5.24.1" "Perl Programmers Reference Guide" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Math::BigRat \- Arbitrary big rational numbers .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Math::BigRat; \& \& my $x = Math::BigRat\->new(\*(Aq3/7\*(Aq); $x += \*(Aq5/9\*(Aq; \& \& print $x\->bstr(),"\en"; \& print $x ** 2,"\en"; \& \& my $y = Math::BigRat\->new(\*(Aqinf\*(Aq); \& print "$y ", ($y\->is_inf ? \*(Aqis\*(Aq : \*(Aqis not\*(Aq) , " infinity\en"; \& \& my $z = Math::BigRat\->new(144); $z\->bsqrt(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Math::BigRat complements Math::BigInt and Math::BigFloat by providing support for arbitrary big rational numbers. .SS "\s-1MATH LIBRARY\s0" .IX Subsection "MATH LIBRARY" You can change the underlying module that does the low-level math operations by using: .PP .Vb 1 \& use Math::BigRat try => \*(AqGMP\*(Aq; .Ve .PP Note: This needs Math::BigInt::GMP installed. .PP The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc: .PP .Vb 1 \& use Math::BigRat try => \*(AqFoo,Math::BigInt::Bar\*(Aq; .Ve .PP If you want to get warned when the fallback occurs, replace \*(L"try\*(R" with \&\*(L"lib\*(R": .PP .Vb 1 \& use Math::BigRat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq; .Ve .PP If you want the code to die instead, replace \*(L"try\*(R" with \&\*(L"only\*(R": .PP .Vb 1 \& use Math::BigRat only => \*(AqFoo,Math::BigInt::Bar\*(Aq; .Ve .SH "METHODS" .IX Header "METHODS" Any methods not listed here are derived from Math::BigFloat (or Math::BigInt), so make sure you check these two modules for further information. .SS "\fInew()\fP" .IX Subsection "new()" .Vb 1 \& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); .Ve .PP Create a new Math::BigRat object. Input can come in various forms: .PP .Vb 9 \& $x = Math::BigRat\->new(123); # scalars \& $x = Math::BigRat\->new(\*(Aqinf\*(Aq); # infinity \& $x = Math::BigRat\->new(\*(Aq123.3\*(Aq); # float \& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); # simple string \& $x = Math::BigRat\->new(\*(Aq1 / 3\*(Aq); # spaced \& $x = Math::BigRat\->new(\*(Aq1 / 0.1\*(Aq); # w/ floats \& $x = Math::BigRat\->new(Math::BigInt\->new(3)); # BigInt \& $x = Math::BigRat\->new(Math::BigFloat\->new(\*(Aq3.1\*(Aq)); # BigFloat \& $x = Math::BigRat\->new(Math::BigInt::Lite\->new(\*(Aq2\*(Aq)); # BigLite \& \& # You can also give D and N as different objects: \& $x = Math::BigRat\->new( \& Math::BigInt\->new(\-123), \& Math::BigInt\->new(7), \& ); # => \-123/7 .Ve .SS "\fInumerator()\fP" .IX Subsection "numerator()" .Vb 1 \& $n = $x\->numerator(); .Ve .PP Returns a copy of the numerator (the part above the line) as signed BigInt. .SS "\fIdenominator()\fP" .IX Subsection "denominator()" .Vb 1 \& $d = $x\->denominator(); .Ve .PP Returns a copy of the denominator (the part under the line) as positive BigInt. .SS "\fIparts()\fP" .IX Subsection "parts()" .Vb 1 \& ($n,$d) = $x\->parts(); .Ve .PP Return a list consisting of (signed) numerator and (unsigned) denominator as BigInts. .SS "\fInumify()\fP" .IX Subsection "numify()" .Vb 1 \& my $y = $x\->numify(); .Ve .PP Returns the object as a scalar. This will lose some data if the object cannot be represented by a normal Perl scalar (integer or float), so use \fIas_int()\fR or \*(L"\fIas_float()\fR\*(R" instead. .PP This routine is automatically used whenever a scalar is required: .PP .Vb 3 \& my $x = Math::BigRat\->new(\*(Aq3/1\*(Aq); \& @array = (0,1,2,3); \& $y = $array[$x]; # set $y to 3 .Ve .SS "\fIas_int()\fP/\fIas_number()\fP" .IX Subsection "as_int()/as_number()" .Vb 2 \& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq); \& print $x\->as_int(),"\en"; # \*(Aq1\*(Aq .Ve .PP Returns a copy of the object as BigInt, truncated to an integer. .PP \&\f(CW\*(C`as_number()\*(C'\fR is an alias for \f(CW\*(C`as_int()\*(C'\fR. .SS "\fIas_float()\fP" .IX Subsection "as_float()" .Vb 2 \& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq); \& print $x\->as_float(),"\en"; # \*(Aq1\*(Aq \& \& $x = Math::BigRat\->new(\*(Aq2/3\*(Aq); \& print $x\->as_float(5),"\en"; # \*(Aq0.66667\*(Aq .Ve .PP Returns a copy of the object as BigFloat, preserving the accuracy as wanted, or the default of 40 digits. .PP This method was added in v0.22 of Math::BigRat (April 2008). .SS "\fIas_hex()\fP" .IX Subsection "as_hex()" .Vb 2 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq); \& print $x\->as_hex(),"\en"; # \*(Aq0xd\*(Aq .Ve .PP Returns the BigRat as hexadecimal string. Works only for integers. .SS "\fIas_bin()\fP" .IX Subsection "as_bin()" .Vb 2 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq); \& print $x\->as_bin(),"\en"; # \*(Aq0x1101\*(Aq .Ve .PP Returns the BigRat as binary string. Works only for integers. .SS "\fIas_oct()\fP" .IX Subsection "as_oct()" .Vb 2 \& $x = Math::BigRat\->new(\*(Aq13\*(Aq); \& print $x\->as_oct(),"\en"; # \*(Aq015\*(Aq .Ve .PP Returns the BigRat as octal string. Works only for integers. .SS "\fIfrom_hex()\fP/\fIfrom_bin()\fP/\fIfrom_oct()\fP" .IX Subsection "from_hex()/from_bin()/from_oct()" .Vb 3 \& my $h = Math::BigRat\->from_hex(\*(Aq0x10\*(Aq); \& my $b = Math::BigRat\->from_bin(\*(Aq0b10000000\*(Aq); \& my $o = Math::BigRat\->from_oct(\*(Aq020\*(Aq); .Ve .PP Create a BigRat from an hexadecimal, binary or octal number in string form. .SS "\fIlength()\fP" .IX Subsection "length()" .Vb 1 \& $len = $x\->length(); .Ve .PP Return the length of \f(CW$x\fR in digits for integer values. .SS "\fIdigit()\fP" .IX Subsection "digit()" .Vb 2 \& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(1); # 1 \& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(\-1); # 3 .Ve .PP Return the N'ths digit from X when X is an integer value. .SS "\fIbnorm()\fP" .IX Subsection "bnorm()" .Vb 1 \& $x\->bnorm(); .Ve .PP Reduce the number to the shortest form. This routine is called automatically whenever it is needed. .SS "\fIbfac()\fP" .IX Subsection "bfac()" .Vb 1 \& $x\->bfac(); .Ve .PP Calculates the factorial of \f(CW$x\fR. For instance: .PP .Vb 2 \& print Math::BigRat\->new(\*(Aq3/1\*(Aq)\->bfac(),"\en"; # 1*2*3 \& print Math::BigRat\->new(\*(Aq5/1\*(Aq)\->bfac(),"\en"; # 1*2*3*4*5 .Ve .PP Works currently only for integers. .SS "\fIbround()\fP/\fIround()\fP/\fIbfround()\fP" .IX Subsection "bround()/round()/bfround()" Are not yet implemented. .SS "\fIbmod()\fP" .IX Subsection "bmod()" .Vb 1 \& $x\->bmod($y); .Ve .PP 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 result is identical to the remainder after floored division (F\-division). If, in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result from Perl's % operator. .SS "\fIbneg()\fP" .IX Subsection "bneg()" .Vb 1 \& $x\->bneg(); .Ve .PP Used to negate the object in-place. .SS "\fIis_one()\fP" .IX Subsection "is_one()" .Vb 1 \& print "$x is 1\en" if $x\->is_one(); .Ve .PP Return true if \f(CW$x\fR is exactly one, otherwise false. .SS "\fIis_zero()\fP" .IX Subsection "is_zero()" .Vb 1 \& print "$x is 0\en" if $x\->is_zero(); .Ve .PP Return true if \f(CW$x\fR is exactly zero, otherwise false. .SS "\fIis_pos()\fP/\fIis_positive()\fP" .IX Subsection "is_pos()/is_positive()" .Vb 1 \& print "$x is >= 0\en" if $x\->is_positive(); .Ve .PP Return true if \f(CW$x\fR is positive (greater than or equal to zero), otherwise false. Please note that '+inf' is also positive, while 'NaN' and '\-inf' aren't. .PP \&\f(CW\*(C`is_positive()\*(C'\fR is an alias for \f(CW\*(C`is_pos()\*(C'\fR. .SS "\fIis_neg()\fP/\fIis_negative()\fP" .IX Subsection "is_neg()/is_negative()" .Vb 1 \& print "$x is < 0\en" if $x\->is_negative(); .Ve .PP Return true if \f(CW$x\fR is negative (smaller than zero), otherwise false. Please note that '\-inf' is also negative, while 'NaN' and '+inf' aren't. .PP \&\f(CW\*(C`is_negative()\*(C'\fR is an alias for \f(CW\*(C`is_neg()\*(C'\fR. .SS "\fIis_int()\fP" .IX Subsection "is_int()" .Vb 1 \& print "$x is an integer\en" if $x\->is_int(); .Ve .PP Return true if \f(CW$x\fR has a denominator of 1 (e.g. no fraction parts), otherwise false. Please note that '\-inf', 'inf' and 'NaN' aren't integer. .SS "\fIis_odd()\fP" .IX Subsection "is_odd()" .Vb 1 \& print "$x is odd\en" if $x\->is_odd(); .Ve .PP Return true if \f(CW$x\fR is odd, otherwise false. .SS "\fIis_even()\fP" .IX Subsection "is_even()" .Vb 1 \& print "$x is even\en" if $x\->is_even(); .Ve .PP Return true if \f(CW$x\fR is even, otherwise false. .SS "\fIbceil()\fP" .IX Subsection "bceil()" .Vb 1 \& $x\->bceil(); .Ve .PP Set \f(CW$x\fR to the next bigger integer value (e.g. truncate the number to integer and then increment it by one). .SS "\fIbfloor()\fP" .IX Subsection "bfloor()" .Vb 1 \& $x\->bfloor(); .Ve .PP Truncate \f(CW$x\fR to an integer value. .SS "\fIbsqrt()\fP" .IX Subsection "bsqrt()" .Vb 1 \& $x\->bsqrt(); .Ve .PP Calculate the square root of \f(CW$x\fR. .SS "\fIbroot()\fP" .IX Subsection "broot()" .Vb 1 \& $x\->broot($n); .Ve .PP Calculate the N'th root of \f(CW$x\fR. .SS "\fIbadd()\fP" .IX Subsection "badd()" .Vb 1 \& $x\->badd($y); .Ve .PP Adds \f(CW$y\fR to \f(CW$x\fR and returns the result. .SS "\fIbmul()\fP" .IX Subsection "bmul()" .Vb 1 \& $x\->bmul($y); .Ve .PP Multiplies \f(CW$y\fR to \f(CW$x\fR and returns the result. .SS "\fIbsub()\fP" .IX Subsection "bsub()" .Vb 1 \& $x\->bsub($y); .Ve .PP Subtracts \f(CW$y\fR from \f(CW$x\fR and returns the result. .SS "\fIbdiv()\fP" .IX Subsection "bdiv()" .Vb 2 \& $q = $x\->bdiv($y); \& ($q, $r) = $x\->bdiv($y); .Ve .PP In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result. In list context, does floored division (F\-division), returning an integer \f(CW$q\fR and a remainder \f(CW$r\fR 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 by \f(CW\*(C`$x\-\*(C'\fRbmod($y)>. .SS "\fIbdec()\fP" .IX Subsection "bdec()" .Vb 1 \& $x\->bdec(); .Ve .PP Decrements \f(CW$x\fR by 1 and returns the result. .SS "\fIbinc()\fP" .IX Subsection "binc()" .Vb 1 \& $x\->binc(); .Ve .PP Increments \f(CW$x\fR by 1 and returns the result. .SS "\fIcopy()\fP" .IX Subsection "copy()" .Vb 1 \& my $z = $x\->copy(); .Ve .PP Makes a deep copy of the object. .PP Please see the documentation in Math::BigInt for further details. .SS "\fIbstr()\fP/\fIbsstr()\fP" .IX Subsection "bstr()/bsstr()" .Vb 3 \& my $x = Math::BigInt\->new(\*(Aq8/4\*(Aq); \& print $x\->bstr(),"\en"; # prints 1/2 \& print $x\->bsstr(),"\en"; # prints 1/2 .Ve .PP Return a string representing this object. .SS "\fIbacmp()\fP/\fIbcmp()\fP" .IX Subsection "bacmp()/bcmp()" Used to compare numbers. .PP Please see the documentation in Math::BigInt for further details. .SS "\fIblsft()\fP/\fIbrsft()\fP" .IX Subsection "blsft()/brsft()" Used to shift numbers left/right. .PP Please see the documentation in Math::BigInt for further details. .SS "\fIbpow()\fP" .IX Subsection "bpow()" .Vb 1 \& $x\->bpow($y); .Ve .PP Compute \f(CW$x\fR ** \f(CW$y\fR. .PP Please see the documentation in Math::BigInt for further details. .SS "\fIbexp()\fP" .IX Subsection "bexp()" .Vb 1 \& $x\->bexp($accuracy); # calculate e ** X .Ve .PP 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 Euler's number. .PP This method was added in v0.20 of Math::BigRat (May 2007). .PP See also \f(CW\*(C`blog()\*(C'\fR. .SS "\fIbnok()\fP" .IX Subsection "bnok()" .Vb 1 \& $x\->bnok($y); # x over y (binomial coefficient n over k) .Ve .PP Calculates the binomial coefficient n over k, also called the \*(L"choose\*(R" function. The result is equivalent to: .PP .Vb 3 \& ( n ) n! \& | \- | = \-\-\-\-\-\-\- \& ( k ) k!(n\-k)! .Ve .PP This method was added in v0.20 of Math::BigRat (May 2007). .SS "\fIconfig()\fP" .IX Subsection "config()" .Vb 1 \& use Data::Dumper; \& \& print Dumper ( Math::BigRat\->config() ); \& print Math::BigRat\->config()\->{lib},"\en"; .Ve .PP Returns a hash containing the configuration, e.g. the version number, lib loaded etc. The following hash keys are currently filled in with the appropriate information. .PP .Vb 10 \& key RO/RW Description \& Example \& ============================================================ \& lib RO Name of the Math library \& Math::BigInt::Calc \& lib_version RO Version of \*(Aqlib\*(Aq \& 0.30 \& class RO The class of config you just called \& Math::BigRat \& version RO version number of the class you used \& 0.10 \& upgrade RW To which class numbers are upgraded \& undef \& downgrade RW To which class numbers are downgraded \& undef \& precision RW Global precision \& undef \& accuracy RW Global accuracy \& undef \& round_mode RW Global round mode \& even \& div_scale RW Fallback accuracy for div \& 40 \& trap_nan RW Trap creation of NaN (undef = no) \& undef \& trap_inf RW Trap creation of +inf/\-inf (undef = no) \& undef .Ve .PP By passing a reference to a hash you may set the configuration values. This works only for values that a marked with a \f(CW\*(C`RW\*(C'\fR above, anything else is read-only. .SS "\fIobjectify()\fP" .IX Subsection "objectify()" This is an internal routine that turns scalars into objects. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-math\-bigrat at rt.cpan.org\*(C'\fR, or through the web interface at (requires login). We will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Math::BigRat .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Matrix .Sp .IP "\(bu" 4 The Bignum mailing list .RS 4 .IP "\(bu" 4 Post to mailing list .Sp \&\f(CW\*(C`bignum at lists.scsys.co.uk\*(C'\fR .IP "\(bu" 4 View mailing list .Sp .IP "\(bu" 4 Subscribe/Unsubscribe .Sp .RE .RS 4 .RE .SH "LICENSE" .IX Header "LICENSE" This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" bigrat, Math::BigFloat and Math::BigInt as well as the backends Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari. .SH "AUTHORS" .IX Header "AUTHORS" (C) by Tels 2001 \- 2009. .PP Currently maintained by Peter John Acklam .