← Back to branch summary

~ubuntu-branches/ubuntu/quantal/ruby1.9.1/quantal

« back to all changes in this revision

Viewing changes to ext/bigdecimal/bigdecimal_en.html

  • Committer: Bazaar Package Importer
  • Author(s): Lucas Nussbaum
  • Date: 2011-09-24 19:16:17 UTC
  • mfrom: (1.1.8 upstream) (13.1.7 experimental)
  • Revision ID: james.westby@ubuntu.com-20110924191617-o1qz4rcmqjot8zuy
Tags: 1.9.3~rc1-1
http://bugs.debian.org/639959
* New upstream release: 1.9.3 RC1.
  + Includes load.c fixes. Closes: #639959.
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
ext/bigdecimal/bigdecimal_en.html
31
31
<BODY BGCOLOR=#FFFFE0>
32
32
<H1>BigDecimal(Variable Precision Floating Library for Ruby)</H1>
33
33
<DIV align="right"><A HREF="./bigdecimal_ja.html">Japanese</A></DIV><BR>
34
 
BigDecimal is an extension library for the Ruby interpreter. 
35
 
Using BigDecimal class, you can obtain any number of significant digits in computation. 
 
34
BigDecimal is an extension library for the Ruby interpreter.
 
35
Using BigDecimal class, you can obtain any number of significant digits in computation.
36
36
For the details about Ruby see:<BR>
37
37
<UL>
38
38
<LI><A HREF="http://www.ruby-lang.org/en/">http://www.ruby-lang.org/en/</A>:Official Ruby page(English).</LI>
39
39
<LI><A HREF="http://kahori.com/ruby/ring/">http://kahori.com/ruby/ring/</A>:Mutually linked pages relating to Ruby(Japanese).
40
40
</LI>
41
 
</UL> 
 
41
</UL>
42
42
NOTE:<BR>
43
43
 This software is provided "AS IS" and without any express or
44
44
 implied warranties,including,without limitation,the implied
62
62
<A NAME="#INTRO">
63
63
<H2>Introduction</H2>
64
64
Ruby already has builtin (variable length integer number) class Bignum. Using Bignum class,you can obtain
65
 
 any integer value in magnitude. But, variable length decimal number class is not yet built in. 
 
65
 any integer value in magnitude. But, variable length decimal number class is not yet built in.
66
66
This is why I made variable length floating class BigDecimal.
67
67
Feel free to send any comments or bug reports to me.
68
68
<A HREF="mailto:shigeo@tinyforest.gr.jp">shigeo@tinyforest.gr.jp</A>
69
 
I will try(but can't promise) to fix bugs reported. 
 
69
I will try(but can't promise) to fix bugs reported.
70
70
<hr>
71
71
<H2>Installation</H2>
72
72
The Ruby latest version can be downloaded from <A HREF="http://www.ruby-lang.org/en/">Official Ruby page</A>.
73
 
Once decompress the downloaded Ruby archive,follow the normal installation procedures according to the 
 
73
Once decompress the downloaded Ruby archive,follow the normal installation procedures according to the
74
74
documents included.
75
75
 
76
76
<A NAME="#SPEC">
89
89
In 32 bits integer system,every 4 digits(in decimal) are computed simultaneously.
90
90
This means the number of significant digits in BigDecimal is always a multiple of 4.
91
91
<P>
92
 
Some more methods are available in Ruby code (not C code). 
 
92
Some more methods are available in Ruby code (not C code).
93
93
Functions such as sin,cos ...,are in math.rb in bigdecimal directory.
94
94
To use them,require math.rb as:
95
95
<CODE><PRE>
110
110
a=BigDecimal::new(s[,n]) or<BR>
111
111
a=BigDecimal(s[,n]) or<BR>
112
112
where:<BR>
113
 
s: Initial value string. Spaces will be ignored. Any unrecognizable character for 
 
113
s: Initial value string. Spaces will be ignored. Any unrecognizable character for
114
114
representing initial value terminates the string.<BR>
115
115
n: Maximum number of significant digits of a. n must be a Fixnum object.
116
116
If n is omitted or is equal to 0,then the maximum number of significant digits of a is determined from the length of s.
146
146
EXCEPTION_ZERODIVIDE controls the execution when zero-division occurs.<BR>
147
147
EXCEPTION_ALL controls the execution when any defined exception occurs.<BR>
148
148
If the flag is true,then the relating exception is thrown.<BR>
149
 
No exception is thrown when the flag is false(default) and computation 
 
149
No exception is thrown when the flag is false(default) and computation
150
150
continues with the result:<BR>
151
151
<BLOCKQUOTE>
152
152
EXCEPTION_NaN results to NaN<BR>
159
159
 currently the same.<BR>
160
160
The return value of mode method is the value set.<BR>
161
161
If nil is specified for the second argument,then current setting is returned.<BR>
162
 
Suppose the return value of the mode method is f,then 
 
162
Suppose the return value of the mode method is f,then
163
163
 f &amp; BigDecimal::EXCEPTION_NaN !=0 means EXCEPTION_NaN is set to on.
164
164
<P>
165
165
<B>[ROUND error control]</B><P>
185
185
 
186
186
<LI><B>limit[(n)]</B></LI><BLOCKQUOTE>
187
187
Limits the maximum digits that the newly created BigDecimal objects can hold never exceed n.
188
 
This means the rounding operation specified by BigDecimal.mode is 
 
188
This means the rounding operation specified by BigDecimal.mode is
189
189
performed if necessary.
190
190
limit returns the value before set if n is nil or is not specified.
191
191
Zero,the default value,means no upper limit.<BR>
194
194
</BLOCKQUOTE>
195
195
 
196
196
<LI><B>double_fig</B></LI><BLOCKQUOTE>
197
 
double_fig is a class method which returns the number of digits 
 
197
double_fig is a class method which returns the number of digits
198
198
the Float class can have.
199
199
<CODE><PRE>
200
200
  p BigDecimal::double_fig  # ==> 20 (depends on the CPU etc.)
290
290
 c = BigDecimal("-1.23456").floor #  ==> -2
291
291
</PRE></CODE>
292
292
 
293
 
As shown in the following example,an optional integer argument (n) specifying the position 
 
293
As shown in the following example,an optional integer argument (n) specifying the position
294
294
of the target digit can be given.<BR>
295
295
If n> 0,then the (n+1)th digit counted from the decimal point in fraction part is processed(resulting number of fraction part digits is less than or equal to n).<BR>
296
296
If n<0,then the n-th digit counted from the decimal point in integer part is processed(at least n 0's are placed from the decimal point to left).
308
308
 c = BigDecimal("-1.23456").ceil #  ==> -1
309
309
</PRE></CODE>
310
310
 
311
 
As shown in the following example,an optional integer argument (n) specifying the position 
 
311
As shown in the following example,an optional integer argument (n) specifying the position
312
312
of the target digit can be given.<BR>
313
313
If n>0,then the (n+1)th digit counted from the decimal point in fraction part is processed(resulting number of fraction part digits is less than or equal to n).<BR>
314
314
If n<0,then the n-th digit counted from the decimal point in integer part is processed(at least n 0's are placed from the decimal point to left).
327
327
</PRE></CODE>
328
328
The rounding operation changes according to BigDecimal::mode(BigDecimal::ROUND_MODE,flag) if specified.
329
329
 
330
 
As shown in the following example,an optional integer argument (n) specifying the position 
 
330
As shown in the following example,an optional integer argument (n) specifying the position
331
331
of the target digit can be given.<BR>
332
332
If n>0,then the (n+1)th digit counted from the decimal point in fraction part is processed(resulting number of fraction  part digits is less than or equal to n).<BR>
333
333
If n<0,then the n-th digit counted from the decimal point in integer part is processed(at least n 0's are placed from the decimal point to left).
346
346
<LI><B>truncate[(n)]</B></LI><BLOCKQUOTE>
347
347
c = a.truncate<BR>
348
348
truncate a to the nearest 1ÅD<BR>
349
 
As shown in the following example,an optional integer argument (n) specifying the position 
 
349
As shown in the following example,an optional integer argument (n) specifying the position
350
350
of the target digit can be given.<BR>
351
351
If n>0,then the (n+1)th digit counted from the decimal point in fraction part is processed(resulting number of fraction part digits is less than or equal to n).<BR>
352
352
If n<0,then the n-th digit counted from the decimal point in integer part is processed(at least n 0's are placed from the decimal point to left).
373
373
<CODE><PRE>
374
374
BigDecimal("1.23456").to_s  #  ==> "0.123456E1"
375
375
</PRE></CODE>
376
 
If n(>0) is given,then a space is inserted to each of two parts divided by the decimal point 
 
376
If n(>0) is given,then a space is inserted to each of two parts divided by the decimal point
377
377
after every n digits for readability.
378
378
<CODE><PRE>
379
379
BigDecimal("0.1234567890123456789").to_s(10)   #  ==> "0.1234567890 123456789E0"
390
390
BigDecimal("-0.1234567890123456789").to_s("10") #  ==> "-0.1234567890 123456789E0"
391
391
</PRE></CODE>
392
392
 
393
 
At the end of the string,'E'(or 'e') or 'F'(or 'f') can be specified to change 
 
393
At the end of the string,'E'(or 'e') or 'F'(or 'f') can be specified to change
394
394
number representation.
395
395
<CODE><PRE>
396
396
BigDecimal("1234567890.123456789").to_s("E")  #  ==> "0.1234567890123456789E10"
408
408
 
409
409
<LI><B>precs</B></LI><BLOCKQUOTE>
410
410
n,m = a.precs <BR>
411
 
precs returns number of significant digits (n) and maximum number of 
 
411
precs returns number of significant digits (n) and maximum number of
412
412
significant digits (m) of a.
413
413
</BLOCKQUOTE>
414
414
 
473
473
should produce output like "#&lt;0x112344:'0.314E1',4(12)%gt;".
474
474
where "0x112344" is the address,
475
475
'0.314E1' is the value,4 is the number of the significant digits,
476
 
and 12 is the maximum number of the significant digits 
 
476
and 12 is the maximum number of the significant digits
477
477
the object can hold.
478
478
</BLOCKQUOTE>
479
479
 
527
527
<DT> 2.A is the BigDecimal object but B is other than BigDecimal object</DT>
528
528
<DD> Operation is performed,after B is translated to corresponding BigDecimal object(because BigDecimal supports coerce method).</DD>
529
529
<DT> 3.A is not the BigDecimal object but B is BigDecimal object</DT>
530
 
<DD>If A has coerce method,then B will translate A to corresponding 
 
530
<DD>If A has coerce method,then B will translate A to corresponding
531
531
BigDecimal object and the operation is performed,otherwise an error occures.</DD>
532
532
</DL>
533
533
 
534
534
String is not translated to BigDecimal in default.
535
 
Uncomment /* #define ENABLE_NUMERIC_STRING */ in bigdecimal.c, compile and install 
 
535
Uncomment /* #define ENABLE_NUMERIC_STRING */ in bigdecimal.c, compile and install
536
536
again if you want to enable string to BigDecimal conversion.
537
537
Translation stops without error at the character representing non digit.
538
538
For instance,"10XX" is translated to 10,"XXXX" is translated to 0.<BR>
563
563
Infinite numbers and NaN can be represented by string writing "+Infinity"(or "Infinity"),"-Infinity",and "NaN" respectively in your program.
564
564
Infinite numbers can be obtained by 1.0/0.0(=Infinity) or -1.0/0.0(=-Infinity).
565
565
<BR><BR>
566
 
NaN(Not a number) can be obtained by undefined computation like 0.0/0.0 
 
566
NaN(Not a number) can be obtained by undefined computation like 0.0/0.0
567
567
or Infinity-Infinity.
568
568
Any computation including NaN results to NaN.
569
569
Comparisons with NaN never become true,including comparison with NaN itself.
602
602
BASE is base value(=10000 in 32 bit integer system),
603
603
and n is the exponent value.<BR>
604
604
Larger BASE value enables smaller size of the array frac[],and increases computation speed.
605
 
The value of BASE is defined ind VpInit(). In 32 bit integer system, this value is 
 
605
The value of BASE is defined ind VpInit(). In 32 bit integer system, this value is
606
606
10000. In 64 bit integer system, the value is 1000000000.
607
607
When BASE is 10000,an element of the array frac[] can have value of from 0 to 9999.
608
608
(up to 4 digits).<BR>
630
630
    0.1234 5678 4321*(10000)**1
631
631
</PRE>
632
632
where frac[0]=1234,frac[1]=5678,frac[2]=4321,
633
 
Prec=3,sign=2,exponent=1. MaxPrec can be any value greater than or equal to 
 
633
Prec=3,sign=2,exponent=1. MaxPrec can be any value greater than or equal to
634
634
Prec.
635
635
<hr>
636
636
 
657
657
   end
658
658
</PRE></CODE>
659
659
 
660
 
If the internal representation is binary,translation from decimal to 
 
660
If the internal representation is binary,translation from decimal to
661
661
binary is required and the translation error is inevitable.
662
662
For example, 0.1 can not exactly be represented in binary.<BR>
663
663
0.1 => b1*2**(-1)+b1*2**(-2)+b3*2**(-3)+b4*2**(-4)....<BR>
669
669
<DD>In binary representation,0.1 can not be represented in finite series of digit.
670
670
 
671
671
But we only need one element(frac[0]=1) in decimal representation.
672
 
This means that we can always determine the size of the array frac[] in Real 
 
672
This means that we can always determine the size of the array frac[] in Real
673
673
structure.
674
674
</DL>
675
675
 
689
689
multiplication,and division,I prepared 2 group of methods<BR>
690
690
 
691
691
<H3>1. +,-,*,/</H3>
692
 
For the operation + - * /,you can not specify the resulting 
 
692
For the operation + - * /,you can not specify the resulting
693
693
number of significant digits.<BR>
694
694
Resulting number of significant digits are defined as:<BR>
695
 
1.1 For *,resulting number of significant digits is the sum of the 
696
 
significant digits of both side of the operator. For / ,resulting number of significant digits is the sum of the 
 
695
1.1 For *,resulting number of significant digits is the sum of the
 
696
significant digits of both side of the operator. For / ,resulting number of significant digits is the sum of the
697
697
maximum significant digits of both side of the operator.<BR>
698
698
1.2 For + and -,resulting number of significant digits is determined so that
699
699
 no round operation is needed. <br>
705
705
But,the division such as c=1.0/3.0 will always be rounded.<BR>
706
706
 
707
707
<H3>2. add,sub,mult,div</H3>
708
 
The length of the significant digits obtained from +,-,*,/ 
 
708
The length of the significant digits obtained from +,-,*,/
709
709
is always defined by that of right and left side of the operator.
710
710
To specify the length of the significant digits by your self,
711
711
use methos add,sub,mult,div.
724
724
 
725
725
 
726
726
<H3>4. Example</H3>
727
 
Following example compute the ratio of the circumference of a circle to 
 
727
Following example compute the ratio of the circumference of a circle to
728
728
its diameter(pi=3.14159265358979....) using J.Machin's formula.
729
729
<BR><BR>
730
730
<CODE><PRE>
746
746
  k = BigDecimal::new("1")
747
747
  w = BigDecimal::new("1")
748
748
  t = BigDecimal::new("-80")
749
 
  while (u.nonzero? && u.exponent >= exp) 
 
749
  while (u.nonzero? && u.exponent >= exp)
750
750
    t   = t*m25
751
751
    u   = t.div(k,sig)
752
752
    pi  = pi + u