Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Math::BigRat 3" | |
132 | .TH Math::BigRat 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Math::BigRat \- Arbitrary big rational numbers | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use Math::BigRat; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 1 | |
142 | \& my $x = Math::BigRat->new('3/7'); $x += '5/9'; | |
143 | .Ve | |
144 | .PP | |
145 | .Vb 2 | |
146 | \& print $x->bstr(),"\en"; | |
147 | \& print $x ** 2,"\en"; | |
148 | .Ve | |
149 | .PP | |
150 | .Vb 2 | |
151 | \& my $y = Math::BigRat->new('inf'); | |
152 | \& print "$y ", ($y->is_inf ? 'is' : 'is not') , " infinity\en"; | |
153 | .Ve | |
154 | .PP | |
155 | .Vb 1 | |
156 | \& my $z = Math::BigRat->new(144); $z->bsqrt(); | |
157 | .Ve | |
158 | .SH "DESCRIPTION" | |
159 | .IX Header "DESCRIPTION" | |
160 | Math::BigRat complements Math::BigInt and Math::BigFloat by providing support | |
161 | for arbitrary big rational numbers. | |
162 | .Sh "\s-1MATH\s0 \s-1LIBRARY\s0" | |
163 | .IX Subsection "MATH LIBRARY" | |
164 | Math with the numbers is done (by default) by a module called | |
165 | Math::BigInt::Calc. This is equivalent to saying: | |
166 | .PP | |
167 | .Vb 1 | |
168 | \& use Math::BigRat lib => 'Calc'; | |
169 | .Ve | |
170 | .PP | |
171 | You can change this by using: | |
172 | .PP | |
173 | .Vb 1 | |
174 | \& use Math::BigRat lib => 'BitVect'; | |
175 | .Ve | |
176 | .PP | |
177 | The following would first try to find Math::BigInt::Foo, then | |
178 | Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc: | |
179 | .PP | |
180 | .Vb 1 | |
181 | \& use Math::BigRat lib => 'Foo,Math::BigInt::Bar'; | |
182 | .Ve | |
183 | .PP | |
184 | Calc.pm uses as internal format an array of elements of some decimal base | |
185 | (usually 1e7, but this might be different for some systems) with the least | |
186 | significant digit first, while BitVect.pm uses a bit vector of base 2, most | |
187 | significant bit first. Other modules might use even different means of | |
188 | representing the numbers. See the respective module documentation for further | |
189 | details. | |
190 | .PP | |
191 | Currently the following replacement libraries exist, search for them at \s-1CPAN:\s0 | |
192 | .PP | |
193 | .Vb 4 | |
194 | \& Math::BigInt::BitVect | |
195 | \& Math::BigInt::GMP | |
196 | \& Math::BigInt::Pari | |
197 | \& Math::BigInt::FastCalc | |
198 | .Ve | |
199 | .SH "METHODS" | |
200 | .IX Header "METHODS" | |
201 | Any methods not listed here are dervied from Math::BigFloat (or | |
202 | Math::BigInt), so make sure you check these two modules for further | |
203 | information. | |
204 | .Sh "\fInew()\fP" | |
205 | .IX Subsection "new()" | |
206 | .Vb 1 | |
207 | \& $x = Math::BigRat->new('1/3'); | |
208 | .Ve | |
209 | .PP | |
210 | Create a new Math::BigRat object. Input can come in various forms: | |
211 | .PP | |
212 | .Vb 9 | |
213 | \& $x = Math::BigRat->new(123); # scalars | |
214 | \& $x = Math::BigRat->new('inf'); # infinity | |
215 | \& $x = Math::BigRat->new('123.3'); # float | |
216 | \& $x = Math::BigRat->new('1/3'); # simple string | |
217 | \& $x = Math::BigRat->new('1 / 3'); # spaced | |
218 | \& $x = Math::BigRat->new('1 / 0.1'); # w/ floats | |
219 | \& $x = Math::BigRat->new(Math::BigInt->new(3)); # BigInt | |
220 | \& $x = Math::BigRat->new(Math::BigFloat->new('3.1')); # BigFloat | |
221 | \& $x = Math::BigRat->new(Math::BigInt::Lite->new('2')); # BigLite | |
222 | .Ve | |
223 | .PP | |
224 | .Vb 5 | |
225 | \& # You can also give D and N as different objects: | |
226 | \& $x = Math::BigRat->new( | |
227 | \& Math::BigInt->new(-123), | |
228 | \& Math::BigInt->new(7), | |
229 | \& ); # => -123/7 | |
230 | .Ve | |
231 | .Sh "\fInumerator()\fP" | |
232 | .IX Subsection "numerator()" | |
233 | .Vb 1 | |
234 | \& $n = $x->numerator(); | |
235 | .Ve | |
236 | .PP | |
237 | Returns a copy of the numerator (the part above the line) as signed BigInt. | |
238 | .Sh "\fIdenominator()\fP" | |
239 | .IX Subsection "denominator()" | |
240 | .Vb 1 | |
241 | \& $d = $x->denominator(); | |
242 | .Ve | |
243 | .PP | |
244 | Returns a copy of the denominator (the part under the line) as positive BigInt. | |
245 | .Sh "\fIparts()\fP" | |
246 | .IX Subsection "parts()" | |
247 | .Vb 1 | |
248 | \& ($n,$d) = $x->parts(); | |
249 | .Ve | |
250 | .PP | |
251 | Return a list consisting of (signed) numerator and (unsigned) denominator as | |
252 | BigInts. | |
253 | .Sh "\fIas_int()\fP" | |
254 | .IX Subsection "as_int()" | |
255 | .Vb 2 | |
256 | \& $x = Math::BigRat->new('13/7'); | |
257 | \& print $x->as_int(),"\en"; # '1' | |
258 | .Ve | |
259 | .PP | |
260 | Returns a copy of the object as BigInt, truncated to an integer. | |
261 | .PP | |
262 | \&\f(CW\*(C`as_number()\*(C'\fR is an alias for \f(CW\*(C`as_int()\*(C'\fR. | |
263 | .Sh "\fIas_hex()\fP" | |
264 | .IX Subsection "as_hex()" | |
265 | .Vb 2 | |
266 | \& $x = Math::BigRat->new('13'); | |
267 | \& print $x->as_hex(),"\en"; # '0xd' | |
268 | .Ve | |
269 | .PP | |
270 | Returns the BigRat as hexadecimal string. Works only for integers. | |
271 | .Sh "\fIas_bin()\fP" | |
272 | .IX Subsection "as_bin()" | |
273 | .Vb 2 | |
274 | \& $x = Math::BigRat->new('13'); | |
275 | \& print $x->as_bin(),"\en"; # '0x1101' | |
276 | .Ve | |
277 | .PP | |
278 | Returns the BigRat as binary string. Works only for integers. | |
279 | .Sh "\fIbfac()\fP" | |
280 | .IX Subsection "bfac()" | |
281 | .Vb 1 | |
282 | \& $x->bfac(); | |
283 | .Ve | |
284 | .PP | |
285 | Calculates the factorial of \f(CW$x\fR. For instance: | |
286 | .PP | |
287 | .Vb 2 | |
288 | \& print Math::BigRat->new('3/1')->bfac(),"\en"; # 1*2*3 | |
289 | \& print Math::BigRat->new('5/1')->bfac(),"\en"; # 1*2*3*4*5 | |
290 | .Ve | |
291 | .PP | |
292 | Works currently only for integers. | |
293 | .Sh "\fIblog()\fP" | |
294 | .IX Subsection "blog()" | |
295 | Is not yet implemented. | |
296 | .Sh "\fIbround()\fP/\fIround()\fP/\fIbfround()\fP" | |
297 | .IX Subsection "bround()/round()/bfround()" | |
298 | Are not yet implemented. | |
299 | .Sh "\fIbmod()\fP" | |
300 | .IX Subsection "bmod()" | |
301 | .Vb 4 | |
302 | \& use Math::BigRat; | |
303 | \& my $x = Math::BigRat->new('7/4'); | |
304 | \& my $y = Math::BigRat->new('4/3'); | |
305 | \& print $x->bmod($y); | |
306 | .Ve | |
307 | .PP | |
308 | Set \f(CW$x\fR to the remainder of the division of \f(CW$x\fR by \f(CW$y\fR. | |
309 | .Sh "\fIis_one()\fP" | |
310 | .IX Subsection "is_one()" | |
311 | .Vb 1 | |
312 | \& print "$x is 1\en" if $x->is_one(); | |
313 | .Ve | |
314 | .PP | |
315 | Return true if \f(CW$x\fR is exactly one, otherwise false. | |
316 | .Sh "\fIis_zero()\fP" | |
317 | .IX Subsection "is_zero()" | |
318 | .Vb 1 | |
319 | \& print "$x is 0\en" if $x->is_zero(); | |
320 | .Ve | |
321 | .PP | |
322 | Return true if \f(CW$x\fR is exactly zero, otherwise false. | |
323 | .Sh "\fIis_pos()\fP" | |
324 | .IX Subsection "is_pos()" | |
325 | .Vb 1 | |
326 | \& print "$x is >= 0\en" if $x->is_positive(); | |
327 | .Ve | |
328 | .PP | |
329 | Return true if \f(CW$x\fR is positive (greater than or equal to zero), otherwise | |
330 | false. Please note that '+inf' is also positive, while 'NaN' and '\-inf' aren't. | |
331 | .PP | |
332 | \&\f(CW\*(C`is_positive()\*(C'\fR is an alias for \f(CW\*(C`is_pos()\*(C'\fR. | |
333 | .Sh "\fIis_neg()\fP" | |
334 | .IX Subsection "is_neg()" | |
335 | .Vb 1 | |
336 | \& print "$x is < 0\en" if $x->is_negative(); | |
337 | .Ve | |
338 | .PP | |
339 | Return true if \f(CW$x\fR is negative (smaller than zero), otherwise false. Please | |
340 | note that '\-inf' is also negative, while 'NaN' and '+inf' aren't. | |
341 | .PP | |
342 | \&\f(CW\*(C`is_negative()\*(C'\fR is an alias for \f(CW\*(C`is_neg()\*(C'\fR. | |
343 | .Sh "\fIis_int()\fP" | |
344 | .IX Subsection "is_int()" | |
345 | .Vb 1 | |
346 | \& print "$x is an integer\en" if $x->is_int(); | |
347 | .Ve | |
348 | .PP | |
349 | Return true if \f(CW$x\fR has a denominator of 1 (e.g. no fraction parts), otherwise | |
350 | false. Please note that '\-inf', 'inf' and 'NaN' aren't integer. | |
351 | .Sh "\fIis_odd()\fP" | |
352 | .IX Subsection "is_odd()" | |
353 | .Vb 1 | |
354 | \& print "$x is odd\en" if $x->is_odd(); | |
355 | .Ve | |
356 | .PP | |
357 | Return true if \f(CW$x\fR is odd, otherwise false. | |
358 | .Sh "\fIis_even()\fP" | |
359 | .IX Subsection "is_even()" | |
360 | .Vb 1 | |
361 | \& print "$x is even\en" if $x->is_even(); | |
362 | .Ve | |
363 | .PP | |
364 | Return true if \f(CW$x\fR is even, otherwise false. | |
365 | .Sh "\fIbceil()\fP" | |
366 | .IX Subsection "bceil()" | |
367 | .Vb 1 | |
368 | \& $x->bceil(); | |
369 | .Ve | |
370 | .PP | |
371 | Set \f(CW$x\fR to the next bigger integer value (e.g. truncate the number to integer | |
372 | and then increment it by one). | |
373 | .Sh "\fIbfloor()\fP" | |
374 | .IX Subsection "bfloor()" | |
375 | .Vb 1 | |
376 | \& $x->bfloor(); | |
377 | .Ve | |
378 | .PP | |
379 | Truncate \f(CW$x\fR to an integer value. | |
380 | .Sh "\fIbsqrt()\fP" | |
381 | .IX Subsection "bsqrt()" | |
382 | .Vb 1 | |
383 | \& $x->bsqrt(); | |
384 | .Ve | |
385 | .PP | |
386 | Calculate the square root of \f(CW$x\fR. | |
387 | .Sh "config" | |
388 | .IX Subsection "config" | |
389 | .Vb 1 | |
390 | \& use Data::Dumper; | |
391 | .Ve | |
392 | .PP | |
393 | .Vb 2 | |
394 | \& print Dumper ( Math::BigRat->config() ); | |
395 | \& print Math::BigRat->config()->{lib},"\en"; | |
396 | .Ve | |
397 | .PP | |
398 | Returns a hash containing the configuration, e.g. the version number, lib | |
399 | loaded etc. The following hash keys are currently filled in with the | |
400 | appropriate information. | |
401 | .PP | |
402 | .Vb 27 | |
403 | \& key RO/RW Description | |
404 | \& Example | |
405 | \& ============================================================ | |
406 | \& lib RO Name of the Math library | |
407 | \& Math::BigInt::Calc | |
408 | \& lib_version RO Version of 'lib' | |
409 | \& 0.30 | |
410 | \& class RO The class of config you just called | |
411 | \& Math::BigRat | |
412 | \& version RO version number of the class you used | |
413 | \& 0.10 | |
414 | \& upgrade RW To which class numbers are upgraded | |
415 | \& undef | |
416 | \& downgrade RW To which class numbers are downgraded | |
417 | \& undef | |
418 | \& precision RW Global precision | |
419 | \& undef | |
420 | \& accuracy RW Global accuracy | |
421 | \& undef | |
422 | \& round_mode RW Global round mode | |
423 | \& even | |
424 | \& div_scale RW Fallback acccuracy for div | |
425 | \& 40 | |
426 | \& trap_nan RW Trap creation of NaN (undef = no) | |
427 | \& undef | |
428 | \& trap_inf RW Trap creation of +inf/-inf (undef = no) | |
429 | \& undef | |
430 | .Ve | |
431 | .PP | |
432 | By passing a reference to a hash you may set the configuration values. This | |
433 | works only for values that a marked with a \f(CW\*(C`RW\*(C'\fR above, anything else is | |
434 | read\-only. | |
435 | .SH "BUGS" | |
436 | .IX Header "BUGS" | |
437 | Some things are not yet implemented, or only implemented half\-way: | |
438 | .IP "inf handling (partial)" 2 | |
439 | .IX Item "inf handling (partial)" | |
440 | .PD 0 | |
441 | .IP "NaN handling (partial)" 2 | |
442 | .IX Item "NaN handling (partial)" | |
443 | .IP "rounding (not implemented except for bceil/bfloor)" 2 | |
444 | .IX Item "rounding (not implemented except for bceil/bfloor)" | |
445 | .ie n .IP "$x ** $y\fR where \f(CW$y is not an integer" 2 | |
446 | .el .IP "$x ** \f(CW$y\fR where \f(CW$y\fR is not an integer" 2 | |
447 | .IX Item "$x ** $y where $y is not an integer" | |
448 | .IP "\fIbmod()\fR, \fIblog()\fR, \fIbmodinv()\fR and \fIbmodpow()\fR (partial)" 2 | |
449 | .IX Item "bmod(), blog(), bmodinv() and bmodpow() (partial)" | |
450 | .PD | |
451 | .SH "LICENSE" | |
452 | .IX Header "LICENSE" | |
453 | This program is free software; you may redistribute it and/or modify it under | |
454 | the same terms as Perl itself. | |
455 | .SH "SEE ALSO" | |
456 | .IX Header "SEE ALSO" | |
457 | Math::BigFloat and Math::Big as well as Math::BigInt::BitVect, | |
458 | Math::BigInt::Pari and Math::BigInt::GMP. | |
459 | .PP | |
460 | See <http://search.cpan.org/search?dist=bignum> for a way to use | |
461 | Math::BigRat. | |
462 | .PP | |
463 | The package at <http://search.cpan.org/search?dist=Math%3A%3ABigRat> | |
464 | may contain more documentation and examples as well as testcases. | |
465 | .SH "AUTHORS" | |
466 | .IX Header "AUTHORS" | |
467 | (C) by Tels <http://bloodgate.com/> 2001 \- 2005. |