bigdecimal.html

API資料大全

<A NAME="ROUND_DOWN"><!-- --></A><H3>
ROUND_DOWN</H3>
<PRE>
public static final int <B>ROUND_DOWN</B></PRE>
<DL>
<DD>Rounding mode to round towards zero.  Never increments the digit
 prior to a discarded fraction (i.e., truncates).  Note that this
 rounding mode never increases the magnitude of the calculated value.</DL>
<HR>

<A NAME="ROUND_CEILING"><!-- --></A><H3>
ROUND_CEILING</H3>
<PRE>
public static final int <B>ROUND_CEILING</B></PRE>
<DL>
<DD>Rounding mode to round towards positive infinity.  If the
 BigDecimal is positive, behaves as for <tt>ROUND_UP</tt>; if negative, 
 behaves as for <tt>ROUND_DOWN</tt>.  Note that this rounding mode never
 decreases the calculated value.</DL>
<HR>

<A NAME="ROUND_FLOOR"><!-- --></A><H3>
ROUND_FLOOR</H3>
<PRE>
public static final int <B>ROUND_FLOOR</B></PRE>
<DL>
<DD>Rounding mode to round towards negative infinity.  If the
 BigDecimal is positive, behave as for <tt>ROUND_DOWN</tt>; if negative,
 behave as for <tt>ROUND_UP</tt>.  Note that this rounding mode never
 increases the calculated value.</DL>
<HR>

<A NAME="ROUND_HALF_UP"><!-- --></A><H3>
ROUND_HALF_UP</H3>
<PRE>
public static final int <B>ROUND_HALF_UP</B></PRE>
<DL>
<DD>Rounding mode to round towards "nearest neighbor" unless both
 neighbors are equidistant, in which case round up.
 Behaves as for <tt>ROUND_UP</tt> if the discarded fraction is &gt;= .5;
 otherwise, behaves as for <tt>ROUND_DOWN</tt>.  Note that this is the
 rounding mode that most of us were taught in grade school.</DL>
<HR>

<A NAME="ROUND_HALF_DOWN"><!-- --></A><H3>
ROUND_HALF_DOWN</H3>
<PRE>
public static final int <B>ROUND_HALF_DOWN</B></PRE>
<DL>
<DD>Rounding mode to round towards "nearest neighbor" unless both
 neighbors are equidistant, in which case round down.
 Behaves as for <tt>ROUND_UP</tt> if the discarded fraction is &gt; .5;
 otherwise, behaves as for <tt>ROUND_DOWN</tt>.</DL>
<HR>

<A NAME="ROUND_HALF_EVEN"><!-- --></A><H3>
ROUND_HALF_EVEN</H3>
<PRE>
public static final int <B>ROUND_HALF_EVEN</B></PRE>
<DL>
<DD>Rounding mode to round towards the "nearest neighbor" unless both
 neighbors are equidistant, in which case, round towards the even
 neighbor.  Behaves as for ROUND_HALF_UP if the digit to the left of the
 discarded fraction is odd; behaves as for ROUND_HALF_DOWN if it's even.
 Note that this is the rounding mode that minimizes cumulative error
 when applied repeatedly over a sequence of calculations.</DL>
<HR>

<A NAME="ROUND_UNNECESSARY"><!-- --></A><H3>
ROUND_UNNECESSARY</H3>
<PRE>
public static final int <B>ROUND_UNNECESSARY</B></PRE>
<DL>
<DD>Rounding mode to assert that the requested operation has an exact
 result, hence no rounding is necessary.  If this rounding mode is
 specified on an operation that yields an inexact result, an
 <tt>ArithmeticException</tt> is thrown.</DL>

<!-- ========= CONSTRUCTOR DETAIL ======== -->

<A NAME="constructor_detail"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Constructor Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="BigDecimal(java.lang.String)"><!-- --></A><H3>
BigDecimal</H3>
<PRE>
public <B>BigDecimal</B>(<A HREF="../../java/lang/String.html">String</A>&nbsp;val)</PRE>
<DL>
<DD>Translates the String representation of a BigDecmal into a BigDecimal.
 The String representation consists of an optional sign (<tt>'+'</tt> or
 <tt>'-'</tt>) followed by a sequence of zero or more decimal digits
 ("the integer"), optionally followed by a fraction, optionally followed
 by an exponent.

 <p>The fraction consists of of a decimal point followed by zero or more
 decimal digits.  The string must contain at least one digit in either
 the integer or the fraction.  The number formed by the sign, the
 integer and the fraction is referred to as the <i>significand</i>.

 <p>The exponent consists of the character <tt>'e'</tt>(<tt>0x75</tt>)
 or <tt>E</tt> (<tt>0x45</tt>) followed by one or more decimal digits.
 The value of the exponenet must lie between <tt>Integer.MIN_VALUE</tt>
 and <tt>Integer.MAX_VALUE</tt>, inclusive.

 <p>The scale of the returned BigDecimal will be the number of digits in
 the fraction, or zero if the string contains no decimal point, subject
 to adjustment for any exponent:  If the string contains an exponent, the
 exponent is subtracted from the scale.  If the resulting scale is
 negative, the scale of the returned BigDecimal is zero and the unscaled
 value is multiplied by the appropriate power of ten so that, in every
 case, the resulting BigDecimal is equal to <i>significand *
 10<sup>exponent</sup></i>. (If in the future this specification is 
 amended to permit negative scales, the final step of zeroing the scale
 and adjusting the unscaled value will be eliminated.)

 <p>The character-to-digit mapping is provided by <A HREF="../../java/lang/Character.html#digit(char, int)"><CODE>Character.digit(char, int)</CODE></A>.  The String may not contain any extraneous
 characters (whitespace, for example).

 <p>Note: For floats (and doubles) other that NAN, +INFINITY and
 -INFINITY, this constructor is compatible with the values returned by
 <tt>Float.toString</tt> (and <tt>Double.toString</tt>).  This is
 generally the preferred way to convert a float (or double) into a
 BigDecimal, as it doesn't suffer from the unpredictability of the
 <A HREF="../../java/math/BigDecimal.html#BigDecimal(double)"><CODE>BigDecimal(double)</CODE></A> constructor.

 <p>Note: the optional leading plus sign and trailing exponent were
 added in release 1.3.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - String representation of BigDecimal.<DT><B>Throws:</B><DD><CODE><A HREF="../../java/lang/NumberFormatException.html">NumberFormatException</A></CODE> - <tt>val</tt> is not a valid representation
	       of a BigDecimal.</DL>
</DD>
</DL>
<HR>

<A NAME="BigDecimal(double)"><!-- --></A><H3>
BigDecimal</H3>
<PRE>
public <B>BigDecimal</B>(double&nbsp;val)</PRE>
<DL>
<DD>Translates a double into a BigDecimal.  The scale of the BigDecimal
 is the smallest value such that <tt>(10<sup>scale</sup> * val)</tt>
 is an integer.
 <p>
 Note: the results of this constructor can be somewhat unpredictable.
 One might assume that <tt>new BigDecimal(.1)</tt> is exactly equal
 to .1, but it is actually equal
 to .1000000000000000055511151231257827021181583404541015625.
 This is so because .1 cannot be represented exactly as a double
 (or, for that matter, as a binary fraction of any finite length).
 Thus, the long value that is being passed <i>in</i> to the constructor is
 not exactly equal to .1, appearances nonwithstanding.
 <p>
 The (String) constructor, on the other hand, is perfectly predictable:
 <tt>new BigDecimal(".1")</tt> is <i>exactly</i> equal to .1, as one
 would expect.  Therefore, it is generally recommended that the (String)
 constructor be used in preference to this one.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - double value to be converted to BigDecimal.<DT><B>Throws:</B><DD><CODE><A HREF="../../java/lang/NumberFormatException.html">NumberFormatException</A></CODE> - <tt>val</tt> is equal to
 	       <tt>Double.NEGATIVE_INFINITY</tt>,
	       <tt>Double.POSITIVE_INFINITY</tt>, or <tt>Double.NaN</tt>.</DL>
</DD>
</DL>
<HR>

<A NAME="BigDecimal(java.math.BigInteger)"><!-- --></A><H3>
BigDecimal</H3>
<PRE>
public <B>BigDecimal</B>(<A HREF="../../java/math/BigInteger.html">BigInteger</A>&nbsp;val)</PRE>
<DL>
<DD>Translates a BigInteger into a BigDecimal.  The scale of the BigDecimal
 is zero.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - BigInteger value to be converted to BigDecimal.</DL>
</DD>
</DL>
<HR>

<A NAME="BigDecimal(java.math.BigInteger, int)"><!-- --></A><H3>
BigDecimal</H3>
<PRE>
public <B>BigDecimal</B>(<A HREF="../../java/math/BigInteger.html">BigInteger</A>&nbsp;unscaledVal,
                  int&nbsp;scale)</PRE>
<DL>
<DD>Translates a BigInteger unscaled value and an int scale into a
 BigDecimal.  The value of the BigDecimal is
 <tt>(unscaledVal/10<sup>scale</sup>)</tt>.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>unscaledVal</CODE> - unscaled value of the BigDecimal.<DD><CODE>scale</CODE> - scale of the BigDecimal.<DT><B>Throws:</B><DD><CODE><A HREF="../../java/lang/NumberFormatException.html">NumberFormatException</A></CODE> - scale is negative</DL>
</DD>
</DL>

<!-- ============ METHOD DETAIL ========== -->

<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="valueOf(long, int)"><!-- --></A><H3>
valueOf</H3>
<PRE>
public static <A HREF="../../java/math/BigDecimal.html">BigDecimal</A> <B>valueOf</B>(long&nbsp;unscaledVal,
                                 int&nbsp;scale)</PRE>
<DL>
<DD>Translates a long unscaled value and an int scale into a BigDecimal.
 This "static factory method" is provided in preference to a
 (long, int) constructor because it allows for reuse of frequently used
 BigDecimals.<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>unscaledVal</CODE> - unscaled value of the BigDecimal.<DD><CODE>scale</CODE> - scale of the BigDecimal.<DT><B>Returns:</B><DD>a BigDecimal whose value is
	       <tt>(unscaledVal/10<sup>scale</sup>)</tt>.</DL>
</DD>
</DL>
<HR>

<A NAME="valueOf(long)"><!-- --></A><H3>
valueOf</H3>
<PRE>
public static <A HREF="../../java/math/BigDecimal.html">BigDecimal</A> <B>valueOf</B>(long&nbsp;val)</PRE>
<DL>
<DD>Translates a long value into a BigDecimal with a scale of zero.
 This "static factory method" is provided in preference to a
 (long) constructor because it allows for reuse of frequently
 used BigDecimals.<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - value of the BigDecimal.<DT><B>Returns:</B><DD>a BigDecimal whose value is <tt>val</tt>.</DL>
</DD>
</DL>
<HR>

<A NAME="add(java.math.BigDecimal)"><!-- --></A><H3>
add</H3>
<PRE>
public <A HREF="../../java/math/BigDecimal.html">BigDecimal</A> <B>add</B>(<A HREF="../../java/math/BigDecimal.html">BigDecimal</A>&nbsp;val)</PRE>
<DL>
<DD>Returns a BigDecimal whose value is <tt>(this + val)</tt>, and whose
 scale is <tt>max(this.scale(), val.scale())</tt>.<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - value to be added to this BigDecimal.<DT><B>Returns:</B><DD><tt>this + val</tt></DL>
</DD>
</DL>
<HR>

<A NAME="subtract(java.math.BigDecimal)"><!-- --></A><H3>
subtract</H3>
<PRE>
public <A HREF="../../java/math/BigDecimal.html">BigDecimal</A> <B>subtract</B>(<A HREF="../../java/math/BigDecimal.html">BigDecimal</A>&nbsp;val)</PRE>
<DL>
<DD>Returns a BigDecimal whose value is <tt>(this - val)</tt>, and whose
 scale is <tt>max(this.scale(), val.scale())</tt>.<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>val</CODE> - value to be subtracted from this BigDecimal.<DT><B>Returns:</B><DD><tt>this - val</tt></DL>