< prev index next >

## src/java.base/share/classes/java/math/BigDecimal.java

 ``` `````` 111 * are discarded. When rounding increases the magnitude of the 112 * returned result, it is possible for a new digit position to be 113 * created by a carry propagating to a leading {@literal "9"} digit. 114 * For example, rounding the value 999.9 to three digits rounding up 115 * would be numerically equal to one thousand, represented as 116 * 100×101. In such cases, the new {@literal "1"} is 117 * the leading digit position of the returned result. 118 * 119 *

Besides a logical exact result, each arithmetic operation has a 120 * preferred scale for representing a result. The preferred 121 * scale for each operation is listed in the table below. 122 * 123 * 124 *

Preferred Scales for Results of Arithmetic Operations 125 * 126 *
OperationPreferred Scale of Result
Subtractmax(minuend.scale(), subtrahend.scale())
Multiplymultiplier.scale() + multiplicand.scale()
Dividedividend.scale() - divisor.scale()
127 * 128 * 129 * 130 * 131 * 132 * 133 * These scales are the ones used by the methods which return exact 134 * arithmetic results; except that an exact divide may have to use a 135 * larger scale since the exact result may have more digits. For 136 * example, {@code 1/32} is {@code 0.03125}. 137 * 138 *

Before rounding, the scale of the logical exact intermediate 139 * result is the preferred scale for that operation. If the exact 140 * numerical result cannot be represented in {@code precision} 141 * digits, rounding selects the set of digits to return and the scale 142 * of the result is reduced from the scale of the intermediate result 143 * to the least scale which can represent the {@code precision} 144 * digits actually returned. If the exact result can be represented 145 * with at most {@code precision} digits, the representation 146 * of the result with the scale closest to the preferred scale is 147 * returned. In particular, an exactly representable quotient may be 148 * represented in fewer than {@code precision} digits by removing 149 * trailing zeros and decreasing the scale. For example, rounding to 150 * three digits using the {@linkplain RoundingMode#FLOOR floor} `````` 329 */ 330 public static final BigDecimal ZERO = 331 ZERO_THROUGH_TEN[0]; 332 333 /** 334 * The value 1, with a scale of 0. 335 * 336 * @since 1.5 337 */ 338 public static final BigDecimal ONE = 339 ZERO_THROUGH_TEN[1]; 340 341 /** 342 * The value 10, with a scale of 0. 343 * 344 * @since 1.5 345 */ 346 public static final BigDecimal TEN = 347 ZERO_THROUGH_TEN[10]; 348 349 // Constructors 350 351 /** 352 * Trusted package private constructor. 353 * Trusted simply means if val is INFLATED, intVal could not be null and 354 * if intVal is null, val could not be INFLATED. 355 */ 356 BigDecimal(BigInteger intVal, long val, int scale, int prec) { 357 this.scale = scale; 358 this.precision = prec; 359 this.intCompact = val; 360 this.intVal = intVal; 361 } 362 363 /** 364 * Translates a character array representation of a 365 * {@code BigDecimal} into a {@code BigDecimal}, accepting the 366 * same sequence of characters as the {@link #BigDecimal(String)} 367 * constructor, while allowing a sub-array to be specified. 368 * ``````1976 * initial element and the remainder is the final element. 1977 * @throws ArithmeticException if {@code divisor==0} 1978 * @throws ArithmeticException if the result is inexact but the 1979 * rounding mode is {@code UNNECESSARY}, or {@code mc.precision} 1980 * {@literal >} 0 and the result of {@code this.divideToIntgralValue(divisor)} would 1981 * require a precision of more than {@code mc.precision} digits. 1982 * @see #divideToIntegralValue(java.math.BigDecimal, java.math.MathContext) 1983 * @see #remainder(java.math.BigDecimal, java.math.MathContext) 1984 * @since 1.5 1985 */ 1986 public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc) { 1987 if (mc.precision == 0) 1988 return divideAndRemainder(divisor); 1989 1990 BigDecimal[] result = new BigDecimal[2]; 1991 BigDecimal lhs = this; 1992 1993 result[0] = lhs.divideToIntegralValue(divisor, mc); 1994 result[1] = lhs.subtract(result[0].multiply(divisor)); 1995 return result; 1996 } 1997 1998 /** 1999 * Returns a {@code BigDecimal} whose value is 2000 * (thisn), The power is computed exactly, to 2001 * unlimited precision. 2002 * 2003 *

The parameter {@code n} must be in the range 0 through 2004 * 999999999, inclusive. {@code ZERO.pow(0)} returns {@link 2005 * #ONE}. 2006 * 2007 * Note that future releases may expand the allowable exponent 2008 * range of this method. 2009 * 2010 * @param n power to raise this {@code BigDecimal} to. 2011 * @return thisn 2012 * @throws ArithmeticException if {@code n} is out of range. 2013 * @since 1.5 2014 */ 2015 public BigDecimal pow(int n) { ``` ``` `````` 111 * are discarded. When rounding increases the magnitude of the 112 * returned result, it is possible for a new digit position to be 113 * created by a carry propagating to a leading {@literal "9"} digit. 114 * For example, rounding the value 999.9 to three digits rounding up 115 * would be numerically equal to one thousand, represented as 116 * 100×101. In such cases, the new {@literal "1"} is 117 * the leading digit position of the returned result. 118 * 119 *

Besides a logical exact result, each arithmetic operation has a 120 * preferred scale for representing a result. The preferred 121 * scale for each operation is listed in the table below. 122 * 123 * 124 *

Preferred Scales for Results of Arithmetic Operations 125 * 126 *
OperationPreferred Scale of Result
Subtractmax(minuend.scale(), subtrahend.scale())
Multiplymultiplier.scale() + multiplicand.scale()
Dividedividend.scale() - divisor.scale()
127 * 128 * 129 * 130 * 131 * 132 * 133 * 134 * These scales are the ones used by the methods which return exact 135 * arithmetic results; except that an exact divide may have to use a 136 * larger scale since the exact result may have more digits. For 137 * example, {@code 1/32} is {@code 0.03125}. 138 * 139 *

Before rounding, the scale of the logical exact intermediate 140 * result is the preferred scale for that operation. If the exact 141 * numerical result cannot be represented in {@code precision} 142 * digits, rounding selects the set of digits to return and the scale 143 * of the result is reduced from the scale of the intermediate result 144 * to the least scale which can represent the {@code precision} 145 * digits actually returned. If the exact result can be represented 146 * with at most {@code precision} digits, the representation 147 * of the result with the scale closest to the preferred scale is 148 * returned. In particular, an exactly representable quotient may be 149 * represented in fewer than {@code precision} digits by removing 150 * trailing zeros and decreasing the scale. For example, rounding to 151 * three digits using the {@linkplain RoundingMode#FLOOR floor} `````` 330 */ 331 public static final BigDecimal ZERO = 332 ZERO_THROUGH_TEN[0]; 333 334 /** 335 * The value 1, with a scale of 0. 336 * 337 * @since 1.5 338 */ 339 public static final BigDecimal ONE = 340 ZERO_THROUGH_TEN[1]; 341 342 /** 343 * The value 10, with a scale of 0. 344 * 345 * @since 1.5 346 */ 347 public static final BigDecimal TEN = 348 ZERO_THROUGH_TEN[10]; 349 350 /** 351 * The value 0.1, with a scale of 1. 352 */ 353 private static final BigDecimal ONE_TENTH = valueOf(1L, 1); 354 355 /** 356 * The value 0.5, with a scale of 1. 357 */ 358 private static final BigDecimal ONE_HALF = valueOf(5L, 1); 359 360 // Constructors 361 362 /** 363 * Trusted package private constructor. 364 * Trusted simply means if val is INFLATED, intVal could not be null and 365 * if intVal is null, val could not be INFLATED. 366 */ 367 BigDecimal(BigInteger intVal, long val, int scale, int prec) { 368 this.scale = scale; 369 this.precision = prec; 370 this.intCompact = val; 371 this.intVal = intVal; 372 } 373 374 /** 375 * Translates a character array representation of a 376 * {@code BigDecimal} into a {@code BigDecimal}, accepting the 377 * same sequence of characters as the {@link #BigDecimal(String)} 378 * constructor, while allowing a sub-array to be specified. 379 * ``````1987 * initial element and the remainder is the final element. 1988 * @throws ArithmeticException if {@code divisor==0} 1989 * @throws ArithmeticException if the result is inexact but the 1990 * rounding mode is {@code UNNECESSARY}, or {@code mc.precision} 1991 * {@literal >} 0 and the result of {@code this.divideToIntgralValue(divisor)} would 1992 * require a precision of more than {@code mc.precision} digits. 1993 * @see #divideToIntegralValue(java.math.BigDecimal, java.math.MathContext) 1994 * @see #remainder(java.math.BigDecimal, java.math.MathContext) 1995 * @since 1.5 1996 */ 1997 public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc) { 1998 if (mc.precision == 0) 1999 return divideAndRemainder(divisor); 2000 2001 BigDecimal[] result = new BigDecimal[2]; 2002 BigDecimal lhs = this; 2003 2004 result[0] = lhs.divideToIntegralValue(divisor, mc); 2005 result[1] = lhs.subtract(result[0].multiply(divisor)); 2006 return result; 2007 } 2008 2009 /** 2010 * Returns an approximation to the square root of {@code this} 2011 * with rounding according to the context settings. 2012 * 2013 *

The preferred scale of the returned result is equal to 2014 * {@code this.scale()/2}. The value of the returned result is 2015 * always within one ulp of the exact decimal value for the 2016 * precision in question. If the rounding mode is {@link 2017 * RoundingMode#HALF_UP HALF_UP}, {@link RoundingMode#HALF_DOWN 2018 * HALF_DOWN}, or {@link RoundingMode#HALF_EVEN HALF_EVEN}, the 2019 * result is within one half an ulp of the exact decimal value. 2020 * 2021 *

Special case: 2022 *

2023 *
• The square root of a number numerically equal to {@code 2024 * ZERO} is numerically equal to {@code ZERO} with a preferred 2025 * scale according to the general rule above. In particular, for 2026 * {@code ZERO}}, {@code ZERO.sqrt(mc).equals(ZERO)} is true with 2027 * any {@code MathContext} as an argument. 2028 *