MathContext


1   /* Generated from 'MathContext.nrx' 8 Sep 2000 11:07:48 [v2.00] */
2   /* Options: Binary Comments Crossref Format Java Logo Strictargs Strictcase Trace2 Verbose3 */
3   package com.ibm.icu.math;
4   
5   /* ------------------------------------------------------------------ */
6   /* MathContext -- Math context settings                               */
7   /* ------------------------------------------------------------------ */
8   /* Copyright IBM Corporation, 1997, 2000, 2005.  All Rights Reserved.       */
9   /*                                                                    */
10  /*   The MathContext object encapsulates the settings used by the     */
11  /*   BigDecimal class; it could also be used by other arithmetics.    */
12  /* ------------------------------------------------------------------ */
13  /* Notes:                                                             */
14  /*                                                                    */
15  /* 1. The properties are checked for validity on construction, so     */
16  /*    the BigDecimal class may assume that they are correct.          */
17  /* ------------------------------------------------------------------ */
18  /* Author:    Mike Cowlishaw                                          */
19  /* 1997.09.03 Initial version (edited from netrexx.lang.RexxSet)      */
20  /* 1997.09.12 Add lostDigits property                                 */
21  /* 1998.05.02 Make the class immutable and final; drop set methods    */
22  /* 1998.06.05 Add Round (rounding modes) property                     */
23  /* 1998.06.25 Rename from DecimalContext; allow digits=0              */
24  /* 1998.10.12 change to com.ibm.icu.math package                          */
25  /* 1999.02.06 add javadoc comments                                    */
26  /* 1999.03.05 simplify; changes from discussion with J. Bloch         */
27  /* 1999.03.13 1.00 release to IBM Centre for Java Technology          */
28  /* 1999.07.10 1.04 flag serialization unused                          */
29  /* 2000.01.01 1.06 copyright update                                   */
30  /* ------------------------------------------------------------------ */
31  
32  
33  
34  
35  /**
36   * The <code>MathContext</code> immutable class encapsulates the
37   * settings understood by the operator methods of the {@link BigDecimal}
38   * class (and potentially other classes).  Operator methods are those
39   * that effect an operation on a number or a pair of numbers.
40   * <p>
41   * The settings, which are not base-dependent, comprise:
42   * <ol>
43   * <li><code>digits</code>:
44   * the number of digits (precision) to be used for an operation
45   * <li><code>form</code>:
46   * the form of any exponent that results from the operation
47   * <li><code>lostDigits</code>:
48   * whether checking for lost digits is enabled
49   * <li><code>roundingMode</code>:
50   * the algorithm to be used for rounding.
51   * </ol>
52   * <p>
53   * When provided, a <code>MathContext</code> object supplies the
54   * settings for an operation directly.
55   * <p>
56   * When <code>MathContext.DEFAULT</code> is provided for a
57   * <code>MathContext</code> parameter then the default settings are used
58   * (<code>9, SCIENTIFIC, false, ROUND_HALF_UP</code>).
59   * <p>
60   * In the <code>BigDecimal</code> class, all methods which accept a
61   * <code>MathContext</code> object defaults) also have a version of the
62   * method which does not accept a MathContext parameter.  These versions
63   * carry out unlimited precision fixed point arithmetic (as though the
64   * settings were (<code>0, PLAIN, false, ROUND_HALF_UP</code>).
65   * <p>
66   * The instance variables are shared with default access (so they are
67   * directly accessible to the <code>BigDecimal</code> class), but must
68   * never be changed.
69   * <p>
70   * The rounding mode constants have the same names and values as the
71   * constants of the same name in <code>java.math.BigDecimal</code>, to
72   * maintain compatibility with earlier versions of
73   * <code>BigDecimal</code>.
74   *
75   * @see     BigDecimal
76   * @author  Mike Cowlishaw
77   * @stable ICU 2.0
78   */
79  
80  public final class MathContext implements java.io.Serializable  {
81   private static final java.lang.String   $0="MathContext.nrx";
82   
83   /* ----- Properties ----- */
84   /* properties public constant */
85   /**
86    * Plain (fixed point) notation, without any exponent.
87    * Used as a setting to control the form of the result of a
88    * <code>BigDecimal</code> operation.
89    * A zero result in plain form may have a decimal part of one or
90    * more zeros.
91    *
92    * @see #ENGINEERING
93    * @see #SCIENTIFIC
94    * @stable ICU 2.0
95    */
96   public static final int PLAIN=0; // [no exponent]
97   
98   /**
99    * Standard floating point notation (with scientific exponential
100   * format, where there is one digit before any decimal point).
101   * Used as a setting to control the form of the result of a
102   * <code>BigDecimal</code> operation.
103   * A zero result in plain form may have a decimal part of one or
104   * more zeros.
105   *
106   * @see #ENGINEERING
107   * @see #PLAIN
108   * @stable ICU 2.0
109   */
110  public static final int SCIENTIFIC=1; // 1 digit before .
111  
112  /**
113   * Standard floating point notation (with engineering exponential
114   * format, where the power of ten is a multiple of 3).
115   * Used as a setting to control the form of the result of a
116   * <code>BigDecimal</code> operation.
117   * A zero result in plain form may have a decimal part of one or
118   * more zeros.
119   *
120   * @see #PLAIN
121   * @see #SCIENTIFIC
122   * @stable ICU 2.0
123   */
124  public static final int ENGINEERING=2; // 1-3 digits before .
125  
126  // The rounding modes match the original BigDecimal class values
127  /**
128   * Rounding mode to round to a more positive number.
129   * Used as a setting to control the rounding mode used during a
130   * <code>BigDecimal</code> operation.
131   * <p>
132   * If any of the discarded digits are non-zero then the result
133   * should be rounded towards the next more positive digit.
134   * @stable ICU 2.0
135   */
136  public static final int ROUND_CEILING=2;
137  
138  /**
139   * Rounding mode to round towards zero.
140   * Used as a setting to control the rounding mode used during a
141   * <code>BigDecimal</code> operation.
142   * <p>
143   * All discarded digits are ignored (truncated).  The result is
144   * neither incremented nor decremented.
145   * @stable ICU 2.0
146   */
147  public static final int ROUND_DOWN=1;
148  
149  /**
150   * Rounding mode to round to a more negative number.
151   * Used as a setting to control the rounding mode used during a
152   * <code>BigDecimal</code> operation.
153   * <p>
154   * If any of the discarded digits are non-zero then the result
155   * should be rounded towards the next more negative digit.
156   * @stable ICU 2.0
157   */
158  public static final int ROUND_FLOOR=3;
159  
160  /**
161   * Rounding mode to round to nearest neighbor, where an equidistant
162   * value is rounded down.
163   * Used as a setting to control the rounding mode used during a
164   * <code>BigDecimal</code> operation.
165   * <p>
166   * If the discarded digits represent greater than half (0.5 times)
167   * the value of a one in the next position then the result should be
168   * rounded up (away from zero).  Otherwise the discarded digits are
169   * ignored.
170   * @stable ICU 2.0
171   */
172  public static final int ROUND_HALF_DOWN=5;
173  
174  /**
175   * Rounding mode to round to nearest neighbor, where an equidistant
176   * value is rounded to the nearest even neighbor.
177   * Used as a setting to control the rounding mode used during a
178   * <code>BigDecimal</code> operation.
179   * <p>
180   * If the discarded digits represent greater than half (0.5 times)
181   * the value of a one in the next position then the result should be
182   * rounded up (away from zero).  If they represent less than half,
183   * then the result should be rounded down.
184   * <p>
185   * Otherwise (they represent exactly half) the result is rounded
186   * down if its rightmost digit is even, or rounded up if its
187   * rightmost digit is odd (to make an even digit).
188   * @stable ICU 2.0
189   */
190  public static final int ROUND_HALF_EVEN=6;
191  
192  /**
193   * Rounding mode to round to nearest neighbor, where an equidistant
194   * value is rounded up.
195   * Used as a setting to control the rounding mode used during a
196   * <code>BigDecimal</code> operation.
197   * <p>
198   * If the discarded digits represent greater than or equal to half
199   * (0.5 times) the value of a one in the next position then the result
200   * should be rounded up (away from zero).  Otherwise the discarded
201   * digits are ignored.
202   * @stable ICU 2.0
203   */
204  public static final int ROUND_HALF_UP=4;
205  
206  /**
207   * Rounding mode to assert that no rounding is necessary.
208   * Used as a setting to control the rounding mode used during a
209   * <code>BigDecimal</code> operation.
210   * <p>
211   * Rounding (potential loss of information) is not permitted.
212   * If any of the discarded digits are non-zero then an
213   * <code>ArithmeticException</code> should be thrown.
214   * @stable ICU 2.0
215   */
216  public static final int ROUND_UNNECESSARY=7;
217  
218  /**
219   * Rounding mode to round away from zero.
220   * Used as a setting to control the rounding mode used during a
221   * <code>BigDecimal</code> operation.
222   * <p>
223   * If any of the discarded digits are non-zero then the result will
224   * be rounded up (away from zero).
225   * @stable ICU 2.0
226   */
227  public static final int ROUND_UP=0;
228  
229  
230  /* properties shared */
231  /**
232   * The number of digits (precision) to be used for an operation.
233   * A value of 0 indicates that unlimited precision (as many digits
234   * as are required) will be used.
235   * <p>
236   * The {@link BigDecimal} operator methods use this value to
237   * determine the precision of results.
238   * Note that leading zeros (in the integer part of a number) are
239   * never significant.
240   * <p>
241   * <code>digits</code> will always be non-negative.
242   *
243   * @serial
244   */
245  int digits;
246  
247  /**
248   * The form of results from an operation.
249   * <p>
250   * The {@link BigDecimal} operator methods use this value to
251   * determine the form of results, in particular whether and how
252   * exponential notation should be used.
253   *
254   * @see #ENGINEERING
255   * @see #PLAIN
256   * @see #SCIENTIFIC
257   * @serial
258   */
259  int form; // values for this must fit in a byte
260  
261  /**
262   * Controls whether lost digits checking is enabled for an
263   * operation.
264   * Set to <code>true</code> to enable checking, or
265   * to <code>false</code> to disable checking.
266   * <p>
267   * When enabled, the {@link BigDecimal} operator methods check
268   * the precision of their operand or operands, and throw an
269   * <code>ArithmeticException</code> if an operand is more precise
270   * than the digits setting (that is, digits would be lost).
271   * When disabled, operands are rounded to the specified digits.
272   *
273   * @serial
274   */
275  boolean lostDigits;
276  
277  /**
278   * The rounding algorithm to be used for an operation.
279   * <p>
280   * The {@link BigDecimal} operator methods use this value to
281   * determine the algorithm to be used when non-zero digits have to
282   * be discarded in order to reduce the precision of a result.
283   * The value must be one of the public constants whose name starts
284   * with <code>ROUND_</code>.
285   *
286   * @see #ROUND_CEILING
287   * @see #ROUND_DOWN
288   * @see #ROUND_FLOOR
289   * @see #ROUND_HALF_DOWN
290   * @see #ROUND_HALF_EVEN
291   * @see #ROUND_HALF_UP
292   * @see #ROUND_UNNECESSARY
293   * @see #ROUND_UP
294   * @serial
295   */
296  int roundingMode;
297  
298  /* properties private constant */
299  // default settings
300  private static final int DEFAULT_FORM=SCIENTIFIC;
301  private static final int DEFAULT_DIGITS=9;
302  private static final boolean DEFAULT_LOSTDIGITS=false;
303  private static final int DEFAULT_ROUNDINGMODE=ROUND_HALF_UP;
304  
305  /* properties private constant */
306  
307  private static final int MIN_DIGITS=0; // smallest value for DIGITS.
308  private static final int MAX_DIGITS=999999999; // largest value for DIGITS.  If increased,
309  // the BigDecimal class may need update.
310  // list of valid rounding mode values, most common two first
311  private static final int ROUNDS[]=new int[]{ROUND_HALF_UP,ROUND_UNNECESSARY,ROUND_CEILING,ROUND_DOWN,ROUND_FLOOR,ROUND_HALF_DOWN,ROUND_HALF_EVEN,ROUND_UP};
312  
313  
314  private static final java.lang.String   ROUNDWORDS[]=new java.lang.String  []{"ROUND_HALF_UP","ROUND_UNNECESSARY","ROUND_CEILING","ROUND_DOWN","ROUND_FLOOR","ROUND_HALF_DOWN","ROUND_HALF_EVEN","ROUND_UP"}; // matching names of the ROUNDS values
315  
316  
317  
318  
319  /* properties private constant unused */
320  
321  // Serialization version
322  private static final long serialVersionUID=7163376998892515376L;
323  
324  /* properties public constant */
325  /**
326   * A <code>MathContext</code> object initialized to the default
327   * settings for general-purpose arithmetic.  That is,
328   * <code>digits=9 form=SCIENTIFIC lostDigits=false
329   * roundingMode=ROUND_HALF_UP</code>.
330   *
331   * @see #SCIENTIFIC
332   * @see #ROUND_HALF_UP
333   * @stable ICU 2.0
334   */
335  public static final com.ibm.icu.math.MathContext DEFAULT=new com.ibm.icu.math.MathContext(DEFAULT_DIGITS,DEFAULT_FORM,DEFAULT_LOSTDIGITS,DEFAULT_ROUNDINGMODE);
336 
337  
338  
339  
340  /* ----- Constructors ----- */
341  
342  /**
343   * Constructs a new <code>MathContext</code> with a specified
344   * precision.
345   * The other settings are set to the default values
346   * (see {@link #DEFAULT}).
347   *
348   * An <code>IllegalArgumentException</code> is thrown if the
349   * <code>setdigits</code> parameter is out of range
350   * (&lt;0 or &gt;999999999).
351   *
352   * @param setdigits     The <code>int</code> digits setting
353   *                      for this <code>MathContext</code>.
354   * @throws IllegalArgumentException parameter out of range.
355   * @stable ICU 2.0
356   */
357  
358  public MathContext(int setdigits){
359   this(setdigits,DEFAULT_FORM,DEFAULT_LOSTDIGITS,DEFAULT_ROUNDINGMODE);
360   return;}
361 
362  
363  /**
364   * Constructs a new <code>MathContext</code> with a specified
365   * precision and form.
366   * The other settings are set to the default values
367   * (see {@link #DEFAULT}).
368   *
369   * An <code>IllegalArgumentException</code> is thrown if the
370   * <code>setdigits</code> parameter is out of range
371   * (&lt;0 or &gt;999999999), or if the value given for the
372   * <code>setform</code> parameter is not one of the appropriate
373   * constants.
374   *
375   * @param setdigits     The <code>int</code> digits setting
376   *                      for this <code>MathContext</code>.
377   * @param setform       The <code>int</code> form setting
378   *                      for this <code>MathContext</code>.
379   * @throws IllegalArgumentException parameter out of range.
380   * @stable ICU 2.0
381   */
382  
383  public MathContext(int setdigits,int setform){
384   this(setdigits,setform,DEFAULT_LOSTDIGITS,DEFAULT_ROUNDINGMODE);
385   return;}
386 
387  /**
388   * Constructs a new <code>MathContext</code> with a specified
389   * precision, form, and lostDigits setting.
390   * The roundingMode setting is set to its default value
391   * (see {@link #DEFAULT}).
392   *
393   * An <code>IllegalArgumentException</code> is thrown if the
394   * <code>setdigits</code> parameter is out of range
395   * (&lt;0 or &gt;999999999), or if the value given for the
396   * <code>setform</code> parameter is not one of the appropriate
397   * constants.
398   *
399   * @param setdigits     The <code>int</code> digits setting
400   *                      for this <code>MathContext</code>.
401   * @param setform       The <code>int</code> form setting
402   *                      for this <code>MathContext</code>.
403   * @param setlostdigits The <code>boolean</code> lostDigits
404   *                      setting for this <code>MathContext</code>.
405   * @throws IllegalArgumentException parameter out of range.
406   * @stable ICU 2.0
407   */
408  
409  public MathContext(int setdigits,int setform,boolean setlostdigits){
410   this(setdigits,setform,setlostdigits,DEFAULT_ROUNDINGMODE);
411   return;}
412 
413  /**
414   * Constructs a new <code>MathContext</code> with a specified
415   * precision, form, lostDigits, and roundingMode setting.
416   *
417   * An <code>IllegalArgumentException</code> is thrown if the
418   * <code>setdigits</code> parameter is out of range
419   * (&lt;0 or &gt;999999999), or if the value given for the
420   * <code>setform</code> or <code>setroundingmode</code> parameters is
421   * not one of the appropriate constants.
422   *
423   * @param setdigits       The <code>int</code> digits setting
424   *                        for this <code>MathContext</code>.
425   * @param setform         The <code>int</code> form setting
426   *                        for this <code>MathContext</code>.
427   * @param setlostdigits   The <code>boolean</code> lostDigits
428   *                        setting for this <code>MathContext</code>.
429   * @param setroundingmode The <code>int</code> roundingMode setting
430   *                        for this <code>MathContext</code>.
431   * @throws IllegalArgumentException parameter out of range.
432   * @stable ICU 2.0
433   */
434  
435  public MathContext(int setdigits,int setform,boolean setlostdigits,int setroundingmode){super();
436   
437   
438   // set values, after checking
439   if (setdigits!=DEFAULT_DIGITS) 
440    {
441     if (setdigits<MIN_DIGITS) 
442      throw new java.lang.IllegalArgumentException  ("Digits too small:"+" "+setdigits);
443     if (setdigits>MAX_DIGITS) 
444      throw new java.lang.IllegalArgumentException  ("Digits too large:"+" "+setdigits);
445    }
446   {/*select*/
447   if (setform==SCIENTIFIC){
448    // [most common]
449   }else if (setform==ENGINEERING){
450   }else if (setform==PLAIN){
451   }else{
452    throw new java.lang.IllegalArgumentException  ("Bad form value:"+" "+setform);
453   }
454   }
455   if ((!(isValidRound(setroundingmode)))) 
456    throw new java.lang.IllegalArgumentException  ("Bad roundingMode value:"+" "+setroundingmode);
457   digits=setdigits;
458   form=setform;
459   lostDigits=setlostdigits; // [no bad value possible]
460   roundingMode=setroundingmode;
461   return;}
462 
463  /**
464   * Returns the digits setting.
465   * This value is always non-negative.
466   *
467   * @return an <code>int</code> which is the value of the digits
468   *         setting
469   * @stable ICU 2.0
470   */
471  
472  public int getDigits(){
473   return digits;
474   }
475 
476  /**
477   * Returns the form setting.
478   * This will be one of
479   * {@link #ENGINEERING},
480   * {@link #PLAIN}, or
481   * {@link #SCIENTIFIC}.
482   *
483   * @return an <code>int</code> which is the value of the form setting
484   * @stable ICU 2.0
485   */
486  
487  public int getForm(){
488   return form;
489   }
490 
491  /**
492   * Returns the lostDigits setting.
493   * This will be either <code>true</code> (enabled) or
494   * <code>false</code> (disabled).
495   *
496   * @return a <code>boolean</code> which is the value of the lostDigits
497   *           setting
498   * @stable ICU 2.0
499   */
500  
501  public boolean getLostDigits(){
502   return lostDigits;
503   }
504 
505  /**
506   * Returns the roundingMode setting.
507   * This will be one of
508   * {@link  #ROUND_CEILING},
509   * {@link  #ROUND_DOWN},
510   * {@link  #ROUND_FLOOR},
511   * {@link  #ROUND_HALF_DOWN},
512   * {@link  #ROUND_HALF_EVEN},
513   * {@link  #ROUND_HALF_UP},
514   * {@link  #ROUND_UNNECESSARY}, or
515   * {@link  #ROUND_UP}.
516   *
517   * @return an <code>int</code> which is the value of the roundingMode
518   *         setting
519   * @stable ICU 2.0
520   */
521  
522  public int getRoundingMode(){
523   return roundingMode;
524   }
525 
526  /** Returns the <code>MathContext</code> as a readable string.
527   * The <code>String</code> returned represents the settings of the
528   * <code>MathContext</code> object as four blank-delimited words
529   * separated by a single blank and with no leading or trailing blanks,
530   * as follows:
531   * <ol>
532   * <li>
533   * <code>digits=</code>, immediately followed by
534   * the value of the digits setting as a numeric word.
535   * <li>
536   * <code>form=</code>, immediately followed by
537   * the value of the form setting as an uppercase word
538   * (one of <code>SCIENTIFIC</code>, <code>PLAIN</code>, or
539   * <code>ENGINEERING</code>).
540   * <li>
541   * <code>lostDigits=</code>, immediately followed by
542   * the value of the lostDigits setting
543   * (<code>1</code> if enabled, <code>0</code> if disabled).
544   * <li>
545   * <code>roundingMode=</code>, immediately followed by
546   * the value of the roundingMode setting as a word.
547   * This word will be the same as the name of the corresponding public
548   * constant.
549   * </ol>
550   * <p>
551   * For example:
552   * <br><code>
553   * digits=9 form=SCIENTIFIC lostDigits=0 roundingMode=ROUND_HALF_UP
554   * </code>
555   * <p>
556   * Additional words may be appended to the result of
557   * <code>toString</code> in the future if more properties are added
558   * to the class.
559   *
560   * @return a <code>String</code> representing the context settings.
561   * @stable ICU 2.0
562   */
563  
564  public java.lang.String   toString(){
565   java.lang.String   formstr=null;
566   int r=0;
567   java.lang.String   roundword=null;
568   {/*select*/
569   if (form==SCIENTIFIC)
570    formstr="SCIENTIFIC";
571   else if (form==ENGINEERING)
572    formstr="ENGINEERING";
573   else{
574    formstr="PLAIN";/* form=PLAIN */
575   }
576   }
577   {int $1=ROUNDS.length;r=0;r:for(;$1>0;$1--,r++){
578    if (roundingMode==ROUNDS[r]) 
579     {
580      roundword=ROUNDWORDS[r];
581      break r;
582     }
583    }
584   }/*r*/
585   return "digits="+digits+" "+"form="+formstr+" "+"lostDigits="+(lostDigits?"1":"0")+" "+"roundingMode="+roundword;
586   }
587 
588  
589  /* <sgml> Test whether round is valid. </sgml> */
590  // This could be made shared for use by BigDecimal for setScale.
591  
592  private static boolean isValidRound(int testround){
593   int r=0;
594   {int $2=ROUNDS.length;r=0;r:for(;$2>0;$2--,r++){
595    if (testround==ROUNDS[r]) 
596     return true;
597    }
598   }/*r*/
599   return false;
600   }
601  }
602
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags