.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Math::BigRat 3perl" .TH Math::BigRat 3perl "2014-12-27" "perl v5.20.2" "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 4 \& use Math::BigRat; \& my $x = Math::BigRat\->new(\*(Aq7/4\*(Aq); \& my $y = Math::BigRat\->new(\*(Aq4/3\*(Aq); \& print $x\->bmod($y); .Ve .PP Set \f(CW$x\fR to the remainder of the division of \f(CW$x\fR by \f(CW$y\fR. .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/\fIbmul()\fP/\fIbsub()\fP/\fIbdiv()\fP/\fIbdec()\fP/\fIbinc()\fP" .IX Subsection "badd()/bmul()/bsub()/bdiv()/bdec()/binc()" Please see the documentation in Math::BigInt. .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" Some things are not yet implemented, or only implemented half-way: .IP "inf handling (partial)" 2 .IX Item "inf handling (partial)" .PD 0 .IP "NaN handling (partial)" 2 .IX Item "NaN handling (partial)" .IP "rounding (not implemented except for bceil/bfloor)" 2 .IX Item "rounding (not implemented except for bceil/bfloor)" .ie n .IP "$x ** $y where $y is not an integer" 2 .el .IP "\f(CW$x\fR ** \f(CW$y\fR where \f(CW$y\fR is not an integer" 2 .IX Item "$x ** $y where $y is not an integer" .IP "\fIbmod()\fR, \fIblog()\fR, \fIbmodinv()\fR and \fIbmodpow()\fR (partial)" 2 .IX Item "bmod(), blog(), bmodinv() and bmodpow() (partial)" .PD .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" Math::BigFloat and Math::Big as well as Math::BigInt::Pari and Math::BigInt::GMP. .PP See for a way to use Math::BigRat. .PP The package at may contain more documentation and examples as well as testcases. .SH "AUTHORS" .IX Header "AUTHORS" (C) by Tels 2001 \- 2009. .PP Currently maintained by Jonathan \*(L"Duke\*(R" Leto