0001 /*
0002 * Copyright 1994-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package java.lang;
0027
0028 import java.util.Random;
0029
0030 /**
0031 * The class {@code Math} contains methods for performing basic
0032 * numeric operations such as the elementary exponential, logarithm,
0033 * square root, and trigonometric functions.
0034 *
0035 * <p>Unlike some of the numeric methods of class
0036 * {@code StrictMath}, all implementations of the equivalent
0037 * functions of class {@code Math} are not defined to return the
0038 * bit-for-bit same results. This relaxation permits
0039 * better-performing implementations where strict reproducibility is
0040 * not required.
0041 *
0042 * <p>By default many of the {@code Math} methods simply call
0043 * the equivalent method in {@code StrictMath} for their
0044 * implementation. Code generators are encouraged to use
0045 * platform-specific native libraries or microprocessor instructions,
0046 * where available, to provide higher-performance implementations of
0047 * {@code Math} methods. Such higher-performance
0048 * implementations still must conform to the specification for
0049 * {@code Math}.
0050 *
0051 * <p>The quality of implementation specifications concern two
0052 * properties, accuracy of the returned result and monotonicity of the
0053 * method. Accuracy of the floating-point {@code Math} methods
0054 * is measured in terms of <i>ulps</i>, units in the last place. For
0055 * a given floating-point format, an ulp of a specific real number
0056 * value is the distance between the two floating-point values
0057 * bracketing that numerical value. When discussing the accuracy of a
0058 * method as a whole rather than at a specific argument, the number of
0059 * ulps cited is for the worst-case error at any argument. If a
0060 * method always has an error less than 0.5 ulps, the method always
0061 * returns the floating-point number nearest the exact result; such a
0062 * method is <i>correctly rounded</i>. A correctly rounded method is
0063 * generally the best a floating-point approximation can be; however,
0064 * it is impractical for many floating-point methods to be correctly
0065 * rounded. Instead, for the {@code Math} class, a larger error
0066 * bound of 1 or 2 ulps is allowed for certain methods. Informally,
0067 * with a 1 ulp error bound, when the exact result is a representable
0068 * number, the exact result should be returned as the computed result;
0069 * otherwise, either of the two floating-point values which bracket
0070 * the exact result may be returned. For exact results large in
0071 * magnitude, one of the endpoints of the bracket may be infinite.
0072 * Besides accuracy at individual arguments, maintaining proper
0073 * relations between the method at different arguments is also
0074 * important. Therefore, most methods with more than 0.5 ulp errors
0075 * are required to be <i>semi-monotonic</i>: whenever the mathematical
0076 * function is non-decreasing, so is the floating-point approximation,
0077 * likewise, whenever the mathematical function is non-increasing, so
0078 * is the floating-point approximation. Not all approximations that
0079 * have 1 ulp accuracy will automatically meet the monotonicity
0080 * requirements.
0081 *
0082 * @author unascribed
0083 * @author Joseph D. Darcy
0084 * @version 1.80, 06/20/07
0085 * @since JDK1.0
0086 */
0087
0088 public final class Math {
0089
0090 /**
0091 * Don't let anyone instantiate this class.
0092 */
0093 private Math() {
0094 }
0095
0096 /**
0097 * The {@code double} value that is closer than any other to
0098 * <i>e</i>, the base of the natural logarithms.
0099 */
0100 public static final double E = 2.7182818284590452354;
0101
0102 /**
0103 * The {@code double} value that is closer than any other to
0104 * <i>pi</i>, the ratio of the circumference of a circle to its
0105 * diameter.
0106 */
0107 public static final double PI = 3.14159265358979323846;
0108
0109 /**
0110 * Returns the trigonometric sine of an angle. Special cases:
0111 * <ul><li>If the argument is NaN or an infinity, then the
0112 * result is NaN.
0113 * <li>If the argument is zero, then the result is a zero with the
0114 * same sign as the argument.</ul>
0115 *
0116 * <p>The computed result must be within 1 ulp of the exact result.
0117 * Results must be semi-monotonic.
0118 *
0119 * @param a an angle, in radians.
0120 * @return the sine of the argument.
0121 */
0122 public static double sin(double a) {
0123 return StrictMath.sin(a); // default impl. delegates to StrictMath
0124 }
0125
0126 /**
0127 * Returns the trigonometric cosine of an angle. Special cases:
0128 * <ul><li>If the argument is NaN or an infinity, then the
0129 * result is NaN.</ul>
0130 *
0131 * <p>The computed result must be within 1 ulp of the exact result.
0132 * Results must be semi-monotonic.
0133 *
0134 * @param a an angle, in radians.
0135 * @return the cosine of the argument.
0136 */
0137 public static double cos(double a) {
0138 return StrictMath.cos(a); // default impl. delegates to StrictMath
0139 }
0140
0141 /**
0142 * Returns the trigonometric tangent of an angle. Special cases:
0143 * <ul><li>If the argument is NaN or an infinity, then the result
0144 * is NaN.
0145 * <li>If the argument is zero, then the result is a zero with the
0146 * same sign as the argument.</ul>
0147 *
0148 * <p>The computed result must be within 1 ulp of the exact result.
0149 * Results must be semi-monotonic.
0150 *
0151 * @param a an angle, in radians.
0152 * @return the tangent of the argument.
0153 */
0154 public static double tan(double a) {
0155 return StrictMath.tan(a); // default impl. delegates to StrictMath
0156 }
0157
0158 /**
0159 * Returns the arc sine of a value; the returned angle is in the
0160 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
0161 * <ul><li>If the argument is NaN or its absolute value is greater
0162 * than 1, then the result is NaN.
0163 * <li>If the argument is zero, then the result is a zero with the
0164 * same sign as the argument.</ul>
0165 *
0166 * <p>The computed result must be within 1 ulp of the exact result.
0167 * Results must be semi-monotonic.
0168 *
0169 * @param a the value whose arc sine is to be returned.
0170 * @return the arc sine of the argument.
0171 */
0172 public static double asin(double a) {
0173 return StrictMath.asin(a); // default impl. delegates to StrictMath
0174 }
0175
0176 /**
0177 * Returns the arc cosine of a value; the returned angle is in the
0178 * range 0.0 through <i>pi</i>. Special case:
0179 * <ul><li>If the argument is NaN or its absolute value is greater
0180 * than 1, then the result is NaN.</ul>
0181 *
0182 * <p>The computed result must be within 1 ulp of the exact result.
0183 * Results must be semi-monotonic.
0184 *
0185 * @param a the value whose arc cosine is to be returned.
0186 * @return the arc cosine of the argument.
0187 */
0188 public static double acos(double a) {
0189 return StrictMath.acos(a); // default impl. delegates to StrictMath
0190 }
0191
0192 /**
0193 * Returns the arc tangent of a value; the returned angle is in the
0194 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
0195 * <ul><li>If the argument is NaN, then the result is NaN.
0196 * <li>If the argument is zero, then the result is a zero with the
0197 * same sign as the argument.</ul>
0198 *
0199 * <p>The computed result must be within 1 ulp of the exact result.
0200 * Results must be semi-monotonic.
0201 *
0202 * @param a the value whose arc tangent is to be returned.
0203 * @return the arc tangent of the argument.
0204 */
0205 public static double atan(double a) {
0206 return StrictMath.atan(a); // default impl. delegates to StrictMath
0207 }
0208
0209 /**
0210 * Converts an angle measured in degrees to an approximately
0211 * equivalent angle measured in radians. The conversion from
0212 * degrees to radians is generally inexact.
0213 *
0214 * @param angdeg an angle, in degrees
0215 * @return the measurement of the angle {@code angdeg}
0216 * in radians.
0217 * @since 1.2
0218 */
0219 public static double toRadians(double angdeg) {
0220 return angdeg / 180.0 * PI;
0221 }
0222
0223 /**
0224 * Converts an angle measured in radians to an approximately
0225 * equivalent angle measured in degrees. The conversion from
0226 * radians to degrees is generally inexact; users should
0227 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly
0228 * equal {@code 0.0}.
0229 *
0230 * @param angrad an angle, in radians
0231 * @return the measurement of the angle {@code angrad}
0232 * in degrees.
0233 * @since 1.2
0234 */
0235 public static double toDegrees(double angrad) {
0236 return angrad * 180.0 / PI;
0237 }
0238
0239 /**
0240 * Returns Euler's number <i>e</i> raised to the power of a
0241 * {@code double} value. Special cases:
0242 * <ul><li>If the argument is NaN, the result is NaN.
0243 * <li>If the argument is positive infinity, then the result is
0244 * positive infinity.
0245 * <li>If the argument is negative infinity, then the result is
0246 * positive zero.</ul>
0247 *
0248 * <p>The computed result must be within 1 ulp of the exact result.
0249 * Results must be semi-monotonic.
0250 *
0251 * @param a the exponent to raise <i>e</i> to.
0252 * @return the value <i>e</i><sup>{@code a}</sup>,
0253 * where <i>e</i> is the base of the natural logarithms.
0254 */
0255 public static double exp(double a) {
0256 return StrictMath.exp(a); // default impl. delegates to StrictMath
0257 }
0258
0259 /**
0260 * Returns the natural logarithm (base <i>e</i>) of a {@code double}
0261 * value. Special cases:
0262 * <ul><li>If the argument is NaN or less than zero, then the result
0263 * is NaN.
0264 * <li>If the argument is positive infinity, then the result is
0265 * positive infinity.
0266 * <li>If the argument is positive zero or negative zero, then the
0267 * result is negative infinity.</ul>
0268 *
0269 * <p>The computed result must be within 1 ulp of the exact result.
0270 * Results must be semi-monotonic.
0271 *
0272 * @param a a value
0273 * @return the value ln {@code a}, the natural logarithm of
0274 * {@code a}.
0275 */
0276 public static double log(double a) {
0277 return StrictMath.log(a); // default impl. delegates to StrictMath
0278 }
0279
0280 /**
0281 * Returns the base 10 logarithm of a {@code double} value.
0282 * Special cases:
0283 *
0284 * <ul><li>If the argument is NaN or less than zero, then the result
0285 * is NaN.
0286 * <li>If the argument is positive infinity, then the result is
0287 * positive infinity.
0288 * <li>If the argument is positive zero or negative zero, then the
0289 * result is negative infinity.
0290 * <li> If the argument is equal to 10<sup><i>n</i></sup> for
0291 * integer <i>n</i>, then the result is <i>n</i>.
0292 * </ul>
0293 *
0294 * <p>The computed result must be within 1 ulp of the exact result.
0295 * Results must be semi-monotonic.
0296 *
0297 * @param a a value
0298 * @return the base 10 logarithm of {@code a}.
0299 * @since 1.5
0300 */
0301 public static double log10(double a) {
0302 return StrictMath.log10(a); // default impl. delegates to StrictMath
0303 }
0304
0305 /**
0306 * Returns the correctly rounded positive square root of a
0307 * {@code double} value.
0308 * Special cases:
0309 * <ul><li>If the argument is NaN or less than zero, then the result
0310 * is NaN.
0311 * <li>If the argument is positive infinity, then the result is positive
0312 * infinity.
0313 * <li>If the argument is positive zero or negative zero, then the
0314 * result is the same as the argument.</ul>
0315 * Otherwise, the result is the {@code double} value closest to
0316 * the true mathematical square root of the argument value.
0317 *
0318 * @param a a value.
0319 * @return the positive square root of {@code a}.
0320 * If the argument is NaN or less than zero, the result is NaN.
0321 */
0322 public static double sqrt(double a) {
0323 return StrictMath.sqrt(a); // default impl. delegates to StrictMath
0324 // Note that hardware sqrt instructions
0325 // frequently can be directly used by JITs
0326 // and should be much faster than doing
0327 // Math.sqrt in software.
0328 }
0329
0330 /**
0331 * Returns the cube root of a {@code double} value. For
0332 * positive finite {@code x}, {@code cbrt(-x) ==
0333 * -cbrt(x)}; that is, the cube root of a negative value is
0334 * the negative of the cube root of that value's magnitude.
0335 *
0336 * Special cases:
0337 *
0338 * <ul>
0339 *
0340 * <li>If the argument is NaN, then the result is NaN.
0341 *
0342 * <li>If the argument is infinite, then the result is an infinity
0343 * with the same sign as the argument.
0344 *
0345 * <li>If the argument is zero, then the result is a zero with the
0346 * same sign as the argument.
0347 *
0348 * </ul>
0349 *
0350 * <p>The computed result must be within 1 ulp of the exact result.
0351 *
0352 * @param a a value.
0353 * @return the cube root of {@code a}.
0354 * @since 1.5
0355 */
0356 public static double cbrt(double a) {
0357 return StrictMath.cbrt(a);
0358 }
0359
0360 /**
0361 * Computes the remainder operation on two arguments as prescribed
0362 * by the IEEE 754 standard.
0363 * The remainder value is mathematically equal to
0364 * <code>f1 - f2</code> × <i>n</i>,
0365 * where <i>n</i> is the mathematical integer closest to the exact
0366 * mathematical value of the quotient {@code f1/f2}, and if two
0367 * mathematical integers are equally close to {@code f1/f2},
0368 * then <i>n</i> is the integer that is even. If the remainder is
0369 * zero, its sign is the same as the sign of the first argument.
0370 * Special cases:
0371 * <ul><li>If either argument is NaN, or the first argument is infinite,
0372 * or the second argument is positive zero or negative zero, then the
0373 * result is NaN.
0374 * <li>If the first argument is finite and the second argument is
0375 * infinite, then the result is the same as the first argument.</ul>
0376 *
0377 * @param f1 the dividend.
0378 * @param f2 the divisor.
0379 * @return the remainder when {@code f1} is divided by
0380 * {@code f2}.
0381 */
0382 public static double IEEEremainder(double f1, double f2) {
0383 return StrictMath.IEEEremainder(f1, f2); // delegate to StrictMath
0384 }
0385
0386 /**
0387 * Returns the smallest (closest to negative infinity)
0388 * {@code double} value that is greater than or equal to the
0389 * argument and is equal to a mathematical integer. Special cases:
0390 * <ul><li>If the argument value is already equal to a
0391 * mathematical integer, then the result is the same as the
0392 * argument. <li>If the argument is NaN or an infinity or
0393 * positive zero or negative zero, then the result is the same as
0394 * the argument. <li>If the argument value is less than zero but
0395 * greater than -1.0, then the result is negative zero.</ul> Note
0396 * that the value of {@code Math.ceil(x)} is exactly the
0397 * value of {@code -Math.floor(-x)}.
0398 *
0399 *
0400 * @param a a value.
0401 * @return the smallest (closest to negative infinity)
0402 * floating-point value that is greater than or equal to
0403 * the argument and is equal to a mathematical integer.
0404 */
0405 public static double ceil(double a) {
0406 return StrictMath.ceil(a); // default impl. delegates to StrictMath
0407 }
0408
0409 /**
0410 * Returns the largest (closest to positive infinity)
0411 * {@code double} value that is less than or equal to the
0412 * argument and is equal to a mathematical integer. Special cases:
0413 * <ul><li>If the argument value is already equal to a
0414 * mathematical integer, then the result is the same as the
0415 * argument. <li>If the argument is NaN or an infinity or
0416 * positive zero or negative zero, then the result is the same as
0417 * the argument.</ul>
0418 *
0419 * @param a a value.
0420 * @return the largest (closest to positive infinity)
0421 * floating-point value that less than or equal to the argument
0422 * and is equal to a mathematical integer.
0423 */
0424 public static double floor(double a) {
0425 return StrictMath.floor(a); // default impl. delegates to StrictMath
0426 }
0427
0428 /**
0429 * Returns the {@code double} value that is closest in value
0430 * to the argument and is equal to a mathematical integer. If two
0431 * {@code double} values that are mathematical integers are
0432 * equally close, the result is the integer value that is
0433 * even. Special cases:
0434 * <ul><li>If the argument value is already equal to a mathematical
0435 * integer, then the result is the same as the argument.
0436 * <li>If the argument is NaN or an infinity or positive zero or negative
0437 * zero, then the result is the same as the argument.</ul>
0438 *
0439 * @param a a {@code double} value.
0440 * @return the closest floating-point value to {@code a} that is
0441 * equal to a mathematical integer.
0442 */
0443 public static double rint(double a) {
0444 return StrictMath.rint(a); // default impl. delegates to StrictMath
0445 }
0446
0447 /**
0448 * Returns the angle <i>theta</i> from the conversion of rectangular
0449 * coordinates ({@code x}, {@code y}) to polar
0450 * coordinates (r, <i>theta</i>).
0451 * This method computes the phase <i>theta</i> by computing an arc tangent
0452 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
0453 * cases:
0454 * <ul><li>If either argument is NaN, then the result is NaN.
0455 * <li>If the first argument is positive zero and the second argument
0456 * is positive, or the first argument is positive and finite and the
0457 * second argument is positive infinity, then the result is positive
0458 * zero.
0459 * <li>If the first argument is negative zero and the second argument
0460 * is positive, or the first argument is negative and finite and the
0461 * second argument is positive infinity, then the result is negative zero.
0462 * <li>If the first argument is positive zero and the second argument
0463 * is negative, or the first argument is positive and finite and the
0464 * second argument is negative infinity, then the result is the
0465 * {@code double} value closest to <i>pi</i>.
0466 * <li>If the first argument is negative zero and the second argument
0467 * is negative, or the first argument is negative and finite and the
0468 * second argument is negative infinity, then the result is the
0469 * {@code double} value closest to -<i>pi</i>.
0470 * <li>If the first argument is positive and the second argument is
0471 * positive zero or negative zero, or the first argument is positive
0472 * infinity and the second argument is finite, then the result is the
0473 * {@code double} value closest to <i>pi</i>/2.
0474 * <li>If the first argument is negative and the second argument is
0475 * positive zero or negative zero, or the first argument is negative
0476 * infinity and the second argument is finite, then the result is the
0477 * {@code double} value closest to -<i>pi</i>/2.
0478 * <li>If both arguments are positive infinity, then the result is the
0479 * {@code double} value closest to <i>pi</i>/4.
0480 * <li>If the first argument is positive infinity and the second argument
0481 * is negative infinity, then the result is the {@code double}
0482 * value closest to 3*<i>pi</i>/4.
0483 * <li>If the first argument is negative infinity and the second argument
0484 * is positive infinity, then the result is the {@code double} value
0485 * closest to -<i>pi</i>/4.
0486 * <li>If both arguments are negative infinity, then the result is the
0487 * {@code double} value closest to -3*<i>pi</i>/4.</ul>
0488 *
0489 * <p>The computed result must be within 2 ulps of the exact result.
0490 * Results must be semi-monotonic.
0491 *
0492 * @param y the ordinate coordinate
0493 * @param x the abscissa coordinate
0494 * @return the <i>theta</i> component of the point
0495 * (<i>r</i>, <i>theta</i>)
0496 * in polar coordinates that corresponds to the point
0497 * (<i>x</i>, <i>y</i>) in Cartesian coordinates.
0498 */
0499 public static double atan2(double y, double x) {
0500 return StrictMath.atan2(y, x); // default impl. delegates to StrictMath
0501 }
0502
0503 /**
0504 * Returns the value of the first argument raised to the power of the
0505 * second argument. Special cases:
0506 *
0507 * <ul><li>If the second argument is positive or negative zero, then the
0508 * result is 1.0.
0509 * <li>If the second argument is 1.0, then the result is the same as the
0510 * first argument.
0511 * <li>If the second argument is NaN, then the result is NaN.
0512 * <li>If the first argument is NaN and the second argument is nonzero,
0513 * then the result is NaN.
0514 *
0515 * <li>If
0516 * <ul>
0517 * <li>the absolute value of the first argument is greater than 1
0518 * and the second argument is positive infinity, or
0519 * <li>the absolute value of the first argument is less than 1 and
0520 * the second argument is negative infinity,
0521 * </ul>
0522 * then the result is positive infinity.
0523 *
0524 * <li>If
0525 * <ul>
0526 * <li>the absolute value of the first argument is greater than 1 and
0527 * the second argument is negative infinity, or
0528 * <li>the absolute value of the
0529 * first argument is less than 1 and the second argument is positive
0530 * infinity,
0531 * </ul>
0532 * then the result is positive zero.
0533 *
0534 * <li>If the absolute value of the first argument equals 1 and the
0535 * second argument is infinite, then the result is NaN.
0536 *
0537 * <li>If
0538 * <ul>
0539 * <li>the first argument is positive zero and the second argument
0540 * is greater than zero, or
0541 * <li>the first argument is positive infinity and the second
0542 * argument is less than zero,
0543 * </ul>
0544 * then the result is positive zero.
0545 *
0546 * <li>If
0547 * <ul>
0548 * <li>the first argument is positive zero and the second argument
0549 * is less than zero, or
0550 * <li>the first argument is positive infinity and the second
0551 * argument is greater than zero,
0552 * </ul>
0553 * then the result is positive infinity.
0554 *
0555 * <li>If
0556 * <ul>
0557 * <li>the first argument is negative zero and the second argument
0558 * is greater than zero but not a finite odd integer, or
0559 * <li>the first argument is negative infinity and the second
0560 * argument is less than zero but not a finite odd integer,
0561 * </ul>
0562 * then the result is positive zero.
0563 *
0564 * <li>If
0565 * <ul>
0566 * <li>the first argument is negative zero and the second argument
0567 * is a positive finite odd integer, or
0568 * <li>the first argument is negative infinity and the second
0569 * argument is a negative finite odd integer,
0570 * </ul>
0571 * then the result is negative zero.
0572 *
0573 * <li>If
0574 * <ul>
0575 * <li>the first argument is negative zero and the second argument
0576 * is less than zero but not a finite odd integer, or
0577 * <li>the first argument is negative infinity and the second
0578 * argument is greater than zero but not a finite odd integer,
0579 * </ul>
0580 * then the result is positive infinity.
0581 *
0582 * <li>If
0583 * <ul>
0584 * <li>the first argument is negative zero and the second argument
0585 * is a negative finite odd integer, or
0586 * <li>the first argument is negative infinity and the second
0587 * argument is a positive finite odd integer,
0588 * </ul>
0589 * then the result is negative infinity.
0590 *
0591 * <li>If the first argument is finite and less than zero
0592 * <ul>
0593 * <li> if the second argument is a finite even integer, the
0594 * result is equal to the result of raising the absolute value of
0595 * the first argument to the power of the second argument
0596 *
0597 * <li>if the second argument is a finite odd integer, the result
0598 * is equal to the negative of the result of raising the absolute
0599 * value of the first argument to the power of the second
0600 * argument
0601 *
0602 * <li>if the second argument is finite and not an integer, then
0603 * the result is NaN.
0604 * </ul>
0605 *
0606 * <li>If both arguments are integers, then the result is exactly equal
0607 * to the mathematical result of raising the first argument to the power
0608 * of the second argument if that result can in fact be represented
0609 * exactly as a {@code double} value.</ul>
0610 *
0611 * <p>(In the foregoing descriptions, a floating-point value is
0612 * considered to be an integer if and only if it is finite and a
0613 * fixed point of the method {@link #ceil ceil} or,
0614 * equivalently, a fixed point of the method {@link #floor
0615 * floor}. A value is a fixed point of a one-argument
0616 * method if and only if the result of applying the method to the
0617 * value is equal to the value.)
0618 *
0619 * <p>The computed result must be within 1 ulp of the exact result.
0620 * Results must be semi-monotonic.
0621 *
0622 * @param a the base.
0623 * @param b the exponent.
0624 * @return the value {@code a}<sup>{@code b}</sup>.
0625 */
0626 public static double pow(double a, double b) {
0627 return StrictMath.pow(a, b); // default impl. delegates to StrictMath
0628 }
0629
0630 /**
0631 * Returns the closest {@code int} to the argument. The
0632 * result is rounded to an integer by adding 1/2, taking the
0633 * floor of the result, and casting the result to type {@code int}.
0634 * In other words, the result is equal to the value of the expression:
0635 * <p>{@code (int)Math.floor(a + 0.5f)}
0636 * <p>
0637 * Special cases:
0638 * <ul><li>If the argument is NaN, the result is 0.
0639 * <li>If the argument is negative infinity or any value less than or
0640 * equal to the value of {@code Integer.MIN_VALUE}, the result is
0641 * equal to the value of {@code Integer.MIN_VALUE}.
0642 * <li>If the argument is positive infinity or any value greater than or
0643 * equal to the value of {@code Integer.MAX_VALUE}, the result is
0644 * equal to the value of {@code Integer.MAX_VALUE}.</ul>
0645 *
0646 * @param a a floating-point value to be rounded to an integer.
0647 * @return the value of the argument rounded to the nearest
0648 * {@code int} value.
0649 * @see java.lang.Integer#MAX_VALUE
0650 * @see java.lang.Integer#MIN_VALUE
0651 */
0652 public static int round(float a) {
0653 return (int) floor(a + 0.5f);
0654 }
0655
0656 /**
0657 * Returns the closest {@code long} to the argument. The result
0658 * is rounded to an integer by adding 1/2, taking the floor of the
0659 * result, and casting the result to type {@code long}. In other
0660 * words, the result is equal to the value of the expression:
0661 * <p>{@code (long)Math.floor(a + 0.5d)}
0662 * <p>
0663 * Special cases:
0664 * <ul><li>If the argument is NaN, the result is 0.
0665 * <li>If the argument is negative infinity or any value less than or
0666 * equal to the value of {@code Long.MIN_VALUE}, the result is
0667 * equal to the value of {@code Long.MIN_VALUE}.
0668 * <li>If the argument is positive infinity or any value greater than or
0669 * equal to the value of {@code Long.MAX_VALUE}, the result is
0670 * equal to the value of {@code Long.MAX_VALUE}.</ul>
0671 *
0672 * @param a a floating-point value to be rounded to a
0673 * {@code long}.
0674 * @return the value of the argument rounded to the nearest
0675 * {@code long} value.
0676 * @see java.lang.Long#MAX_VALUE
0677 * @see java.lang.Long#MIN_VALUE
0678 */
0679 public static long round(double a) {
0680 return (long) floor(a + 0.5d);
0681 }
0682
0683 private static Random randomNumberGenerator;
0684
0685 private static synchronized void initRNG() {
0686 if (randomNumberGenerator == null)
0687 randomNumberGenerator = new Random();
0688 }
0689
0690 /**
0691 * Returns a {@code double} value with a positive sign, greater
0692 * than or equal to {@code 0.0} and less than {@code 1.0}.
0693 * Returned values are chosen pseudorandomly with (approximately)
0694 * uniform distribution from that range.
0695 *
0696 * <p>When this method is first called, it creates a single new
0697 * pseudorandom-number generator, exactly as if by the expression
0698 * <blockquote>{@code new java.util.Random}</blockquote> This
0699 * new pseudorandom-number generator is used thereafter for all
0700 * calls to this method and is used nowhere else.
0701 *
0702 * <p>This method is properly synchronized to allow correct use by
0703 * more than one thread. However, if many threads need to generate
0704 * pseudorandom numbers at a great rate, it may reduce contention
0705 * for each thread to have its own pseudorandom-number generator.
0706 *
0707 * @return a pseudorandom {@code double} greater than or equal
0708 * to {@code 0.0} and less than {@code 1.0}.
0709 * @see java.util.Random#nextDouble()
0710 */
0711 public static double random() {
0712 if (randomNumberGenerator == null)
0713 initRNG();
0714 return randomNumberGenerator.nextDouble();
0715 }
0716
0717 /**
0718 * Returns the absolute value of an {@code int} value.
0719 * If the argument is not negative, the argument is returned.
0720 * If the argument is negative, the negation of the argument is returned.
0721 *
0722 * <p>Note that if the argument is equal to the value of
0723 * {@link Integer#MIN_VALUE}, the most negative representable
0724 * {@code int} value, the result is that same value, which is
0725 * negative.
0726 *
0727 * @param a the argument whose absolute value is to be determined
0728 * @return the absolute value of the argument.
0729 */
0730 public static int abs(int a) {
0731 return (a < 0) ? -a : a;
0732 }
0733
0734 /**
0735 * Returns the absolute value of a {@code long} value.
0736 * If the argument is not negative, the argument is returned.
0737 * If the argument is negative, the negation of the argument is returned.
0738 *
0739 * <p>Note that if the argument is equal to the value of
0740 * {@link Long#MIN_VALUE}, the most negative representable
0741 * {@code long} value, the result is that same value, which
0742 * is negative.
0743 *
0744 * @param a the argument whose absolute value is to be determined
0745 * @return the absolute value of the argument.
0746 */
0747 public static long abs(long a) {
0748 return (a < 0) ? -a : a;
0749 }
0750
0751 /**
0752 * Returns the absolute value of a {@code float} value.
0753 * If the argument is not negative, the argument is returned.
0754 * If the argument is negative, the negation of the argument is returned.
0755 * Special cases:
0756 * <ul><li>If the argument is positive zero or negative zero, the
0757 * result is positive zero.
0758 * <li>If the argument is infinite, the result is positive infinity.
0759 * <li>If the argument is NaN, the result is NaN.</ul>
0760 * In other words, the result is the same as the value of the expression:
0761 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))}
0762 *
0763 * @param a the argument whose absolute value is to be determined
0764 * @return the absolute value of the argument.
0765 */
0766 public static float abs(float a) {
0767 return (a <= 0.0F) ? 0.0F - a : a;
0768 }
0769
0770 /**
0771 * Returns the absolute value of a {@code double} value.
0772 * If the argument is not negative, the argument is returned.
0773 * If the argument is negative, the negation of the argument is returned.
0774 * Special cases:
0775 * <ul><li>If the argument is positive zero or negative zero, the result
0776 * is positive zero.
0777 * <li>If the argument is infinite, the result is positive infinity.
0778 * <li>If the argument is NaN, the result is NaN.</ul>
0779 * In other words, the result is the same as the value of the expression:
0780 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
0781 *
0782 * @param a the argument whose absolute value is to be determined
0783 * @return the absolute value of the argument.
0784 */
0785 public static double abs(double a) {
0786 return (a <= 0.0D) ? 0.0D - a : a;
0787 }
0788
0789 /**
0790 * Returns the greater of two {@code int} values. That is, the
0791 * result is the argument closer to the value of
0792 * {@link Integer#MAX_VALUE}. If the arguments have the same value,
0793 * the result is that same value.
0794 *
0795 * @param a an argument.
0796 * @param b another argument.
0797 * @return the larger of {@code a} and {@code b}.
0798 */
0799 public static int max(int a, int b) {
0800 return (a >= b) ? a : b;
0801 }
0802
0803 /**
0804 * Returns the greater of two {@code long} values. That is, the
0805 * result is the argument closer to the value of
0806 * {@link Long#MAX_VALUE}. If the arguments have the same value,
0807 * the result is that same value.
0808 *
0809 * @param a an argument.
0810 * @param b another argument.
0811 * @return the larger of {@code a} and {@code b}.
0812 */
0813 public static long max(long a, long b) {
0814 return (a >= b) ? a : b;
0815 }
0816
0817 private static long negativeZeroFloatBits = Float
0818 .floatToIntBits(-0.0f);
0819 private static long negativeZeroDoubleBits = Double
0820 .doubleToLongBits(-0.0d);
0821
0822 /**
0823 * Returns the greater of two {@code float} values. That is,
0824 * the result is the argument closer to positive infinity. If the
0825 * arguments have the same value, the result is that same
0826 * value. If either value is NaN, then the result is NaN. Unlike
0827 * the numerical comparison operators, this method considers
0828 * negative zero to be strictly smaller than positive zero. If one
0829 * argument is positive zero and the other negative zero, the
0830 * result is positive zero.
0831 *
0832 * @param a an argument.
0833 * @param b another argument.
0834 * @return the larger of {@code a} and {@code b}.
0835 */
0836 public static float max(float a, float b) {
0837 if (a != a)
0838 return a; // a is NaN
0839 if ((a == 0.0f) && (b == 0.0f)
0840 && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
0841 return b;
0842 }
0843 return (a >= b) ? a : b;
0844 }
0845
0846 /**
0847 * Returns the greater of two {@code double} values. That
0848 * is, the result is the argument closer to positive infinity. If
0849 * the arguments have the same value, the result is that same
0850 * value. If either value is NaN, then the result is NaN. Unlike
0851 * the numerical comparison operators, this method considers
0852 * negative zero to be strictly smaller than positive zero. If one
0853 * argument is positive zero and the other negative zero, the
0854 * result is positive zero.
0855 *
0856 * @param a an argument.
0857 * @param b another argument.
0858 * @return the larger of {@code a} and {@code b}.
0859 */
0860 public static double max(double a, double b) {
0861 if (a != a)
0862 return a; // a is NaN
0863 if ((a == 0.0d)
0864 && (b == 0.0d)
0865 && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
0866 return b;
0867 }
0868 return (a >= b) ? a : b;
0869 }
0870
0871 /**
0872 * Returns the smaller of two {@code int} values. That is,
0873 * the result the argument closer to the value of
0874 * {@link Integer#MIN_VALUE}. If the arguments have the same
0875 * value, the result is that same value.
0876 *
0877 * @param a an argument.
0878 * @param b another argument.
0879 * @return the smaller of {@code a} and {@code b}.
0880 */
0881 public static int min(int a, int b) {
0882 return (a <= b) ? a : b;
0883 }
0884
0885 /**
0886 * Returns the smaller of two {@code long} values. That is,
0887 * the result is the argument closer to the value of
0888 * {@link Long#MIN_VALUE}. If the arguments have the same
0889 * value, the result is that same value.
0890 *
0891 * @param a an argument.
0892 * @param b another argument.
0893 * @return the smaller of {@code a} and {@code b}.
0894 */
0895 public static long min(long a, long b) {
0896 return (a <= b) ? a : b;
0897 }
0898
0899 /**
0900 * Returns the smaller of two {@code float} values. That is,
0901 * the result is the value closer to negative infinity. If the
0902 * arguments have the same value, the result is that same
0903 * value. If either value is NaN, then the result is NaN. Unlike
0904 * the numerical comparison operators, this method considers
0905 * negative zero to be strictly smaller than positive zero. If
0906 * one argument is positive zero and the other is negative zero,
0907 * the result is negative zero.
0908 *
0909 * @param a an argument.
0910 * @param b another argument.
0911 * @return the smaller of {@code a} and {@code b}.
0912 */
0913 public static float min(float a, float b) {
0914 if (a != a)
0915 return a; // a is NaN
0916 if ((a == 0.0f) && (b == 0.0f)
0917 && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
0918 return b;
0919 }
0920 return (a <= b) ? a : b;
0921 }
0922
0923 /**
0924 * Returns the smaller of two {@code double} values. That
0925 * is, the result is the value closer to negative infinity. If the
0926 * arguments have the same value, the result is that same
0927 * value. If either value is NaN, then the result is NaN. Unlike
0928 * the numerical comparison operators, this method considers
0929 * negative zero to be strictly smaller than positive zero. If one
0930 * argument is positive zero and the other is negative zero, the
0931 * result is negative zero.
0932 *
0933 * @param a an argument.
0934 * @param b another argument.
0935 * @return the smaller of {@code a} and {@code b}.
0936 */
0937 public static double min(double a, double b) {
0938 if (a != a)
0939 return a; // a is NaN
0940 if ((a == 0.0d)
0941 && (b == 0.0d)
0942 && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
0943 return b;
0944 }
0945 return (a <= b) ? a : b;
0946 }
0947
0948 /**
0949 * Returns the size of an ulp of the argument. An ulp of a
0950 * {@code double} value is the positive distance between this
0951 * floating-point value and the {@code double} value next
0952 * larger in magnitude. Note that for non-NaN <i>x</i>,
0953 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
0954 *
0955 * <p>Special Cases:
0956 * <ul>
0957 * <li> If the argument is NaN, then the result is NaN.
0958 * <li> If the argument is positive or negative infinity, then the
0959 * result is positive infinity.
0960 * <li> If the argument is positive or negative zero, then the result is
0961 * {@code Double.MIN_VALUE}.
0962 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
0963 * the result is equal to 2<sup>971</sup>.
0964 * </ul>
0965 *
0966 * @param d the floating-point value whose ulp is to be returned
0967 * @return the size of an ulp of the argument
0968 * @author Joseph D. Darcy
0969 * @since 1.5
0970 */
0971 public static double ulp(double d) {
0972 return sun.misc.FpUtils.ulp(d);
0973 }
0974
0975 /**
0976 * Returns the size of an ulp of the argument. An ulp of a
0977 * {@code float} value is the positive distance between this
0978 * floating-point value and the {@code float} value next
0979 * larger in magnitude. Note that for non-NaN <i>x</i>,
0980 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
0981 *
0982 * <p>Special Cases:
0983 * <ul>
0984 * <li> If the argument is NaN, then the result is NaN.
0985 * <li> If the argument is positive or negative infinity, then the
0986 * result is positive infinity.
0987 * <li> If the argument is positive or negative zero, then the result is
0988 * {@code Float.MIN_VALUE}.
0989 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
0990 * the result is equal to 2<sup>104</sup>.
0991 * </ul>
0992 *
0993 * @param f the floating-point value whose ulp is to be returned
0994 * @return the size of an ulp of the argument
0995 * @author Joseph D. Darcy
0996 * @since 1.5
0997 */
0998 public static float ulp(float f) {
0999 return sun.misc.FpUtils.ulp(f);
1000 }
1001
1002 /**
1003 * Returns the signum function of the argument; zero if the argument
1004 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
1005 * argument is less than zero.
1006 *
1007 * <p>Special Cases:
1008 * <ul>
1009 * <li> If the argument is NaN, then the result is NaN.
1010 * <li> If the argument is positive zero or negative zero, then the
1011 * result is the same as the argument.
1012 * </ul>
1013 *
1014 * @param d the floating-point value whose signum is to be returned
1015 * @return the signum function of the argument
1016 * @author Joseph D. Darcy
1017 * @since 1.5
1018 */
1019 public static double signum(double d) {
1020 return sun.misc.FpUtils.signum(d);
1021 }
1022
1023 /**
1024 * Returns the signum function of the argument; zero if the argument
1025 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
1026 * argument is less than zero.
1027 *
1028 * <p>Special Cases:
1029 * <ul>
1030 * <li> If the argument is NaN, then the result is NaN.
1031 * <li> If the argument is positive zero or negative zero, then the
1032 * result is the same as the argument.
1033 * </ul>
1034 *
1035 * @param f the floating-point value whose signum is to be returned
1036 * @return the signum function of the argument
1037 * @author Joseph D. Darcy
1038 * @since 1.5
1039 */
1040 public static float signum(float f) {
1041 return sun.misc.FpUtils.signum(f);
1042 }
1043
1044 /**
1045 * Returns the hyperbolic sine of a {@code double} value.
1046 * The hyperbolic sine of <i>x</i> is defined to be
1047 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
1048 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1049 *
1050 * <p>Special cases:
1051 * <ul>
1052 *
1053 * <li>If the argument is NaN, then the result is NaN.
1054 *
1055 * <li>If the argument is infinite, then the result is an infinity
1056 * with the same sign as the argument.
1057 *
1058 * <li>If the argument is zero, then the result is a zero with the
1059 * same sign as the argument.
1060 *
1061 * </ul>
1062 *
1063 * <p>The computed result must be within 2.5 ulps of the exact result.
1064 *
1065 * @param x The number whose hyperbolic sine is to be returned.
1066 * @return The hyperbolic sine of {@code x}.
1067 * @since 1.5
1068 */
1069 public static double sinh(double x) {
1070 return StrictMath.sinh(x);
1071 }
1072
1073 /**
1074 * Returns the hyperbolic cosine of a {@code double} value.
1075 * The hyperbolic cosine of <i>x</i> is defined to be
1076 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
1077 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1078 *
1079 * <p>Special cases:
1080 * <ul>
1081 *
1082 * <li>If the argument is NaN, then the result is NaN.
1083 *
1084 * <li>If the argument is infinite, then the result is positive
1085 * infinity.
1086 *
1087 * <li>If the argument is zero, then the result is {@code 1.0}.
1088 *
1089 * </ul>
1090 *
1091 * <p>The computed result must be within 2.5 ulps of the exact result.
1092 *
1093 * @param x The number whose hyperbolic cosine is to be returned.
1094 * @return The hyperbolic cosine of {@code x}.
1095 * @since 1.5
1096 */
1097 public static double cosh(double x) {
1098 return StrictMath.cosh(x);
1099 }
1100
1101 /**
1102 * Returns the hyperbolic tangent of a {@code double} value.
1103 * The hyperbolic tangent of <i>x</i> is defined to be
1104 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
1105 * in other words, {@linkplain Math#sinh
1106 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
1107 * that the absolute value of the exact tanh is always less than
1108 * 1.
1109 *
1110 * <p>Special cases:
1111 * <ul>
1112 *
1113 * <li>If the argument is NaN, then the result is NaN.
1114 *
1115 * <li>If the argument is zero, then the result is a zero with the
1116 * same sign as the argument.
1117 *
1118 * <li>If the argument is positive infinity, then the result is
1119 * {@code +1.0}.
1120 *
1121 * <li>If the argument is negative infinity, then the result is
1122 * {@code -1.0}.
1123 *
1124 * </ul>
1125 *
1126 * <p>The computed result must be within 2.5 ulps of the exact result.
1127 * The result of {@code tanh} for any finite input must have
1128 * an absolute value less than or equal to 1. Note that once the
1129 * exact result of tanh is within 1/2 of an ulp of the limit value
1130 * of ±1, correctly signed ±{@code 1.0} should
1131 * be returned.
1132 *
1133 * @param x The number whose hyperbolic tangent is to be returned.
1134 * @return The hyperbolic tangent of {@code x}.
1135 * @since 1.5
1136 */
1137 public static double tanh(double x) {
1138 return StrictMath.tanh(x);
1139 }
1140
1141 /**
1142 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1143 * without intermediate overflow or underflow.
1144 *
1145 * <p>Special cases:
1146 * <ul>
1147 *
1148 * <li> If either argument is infinite, then the result
1149 * is positive infinity.
1150 *
1151 * <li> If either argument is NaN and neither argument is infinite,
1152 * then the result is NaN.
1153 *
1154 * </ul>
1155 *
1156 * <p>The computed result must be within 1 ulp of the exact
1157 * result. If one parameter is held constant, the results must be
1158 * semi-monotonic in the other parameter.
1159 *
1160 * @param x a value
1161 * @param y a value
1162 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1163 * without intermediate overflow or underflow
1164 * @since 1.5
1165 */
1166 public static double hypot(double x, double y) {
1167 return StrictMath.hypot(x, y);
1168 }
1169
1170 /**
1171 * Returns <i>e</i><sup>x</sup> -1. Note that for values of
1172 * <i>x</i> near 0, the exact sum of
1173 * {@code expm1(x)} + 1 is much closer to the true
1174 * result of <i>e</i><sup>x</sup> than {@code exp(x)}.
1175 *
1176 * <p>Special cases:
1177 * <ul>
1178 * <li>If the argument is NaN, the result is NaN.
1179 *
1180 * <li>If the argument is positive infinity, then the result is
1181 * positive infinity.
1182 *
1183 * <li>If the argument is negative infinity, then the result is
1184 * -1.0.
1185 *
1186 * <li>If the argument is zero, then the result is a zero with the
1187 * same sign as the argument.
1188 *
1189 * </ul>
1190 *
1191 * <p>The computed result must be within 1 ulp of the exact result.
1192 * Results must be semi-monotonic. The result of
1193 * {@code expm1} for any finite input must be greater than or
1194 * equal to {@code -1.0}. Note that once the exact result of
1195 * <i>e</i><sup>{@code x}</sup> - 1 is within 1/2
1196 * ulp of the limit value -1, {@code -1.0} should be
1197 * returned.
1198 *
1199 * @param x the exponent to raise <i>e</i> to in the computation of
1200 * <i>e</i><sup>{@code x}</sup> -1.
1201 * @return the value <i>e</i><sup>{@code x}</sup> - 1.
1202 * @since 1.5
1203 */
1204 public static double expm1(double x) {
1205 return StrictMath.expm1(x);
1206 }
1207
1208 /**
1209 * Returns the natural logarithm of the sum of the argument and 1.
1210 * Note that for small values {@code x}, the result of
1211 * {@code log1p(x)} is much closer to the true result of ln(1
1212 * + {@code x}) than the floating-point evaluation of
1213 * {@code log(1.0+x)}.
1214 *
1215 * <p>Special cases:
1216 *
1217 * <ul>
1218 *
1219 * <li>If the argument is NaN or less than -1, then the result is
1220 * NaN.
1221 *
1222 * <li>If the argument is positive infinity, then the result is
1223 * positive infinity.
1224 *
1225 * <li>If the argument is negative one, then the result is
1226 * negative infinity.
1227 *
1228 * <li>If the argument is zero, then the result is a zero with the
1229 * same sign as the argument.
1230 *
1231 * </ul>
1232 *
1233 * <p>The computed result must be within 1 ulp of the exact result.
1234 * Results must be semi-monotonic.
1235 *
1236 * @param x a value
1237 * @return the value ln({@code x} + 1), the natural
1238 * log of {@code x} + 1
1239 * @since 1.5
1240 */
1241 public static double log1p(double x) {
1242 return StrictMath.log1p(x);
1243 }
1244
1245 /**
1246 * Returns the first floating-point argument with the sign of the
1247 * second floating-point argument. Note that unlike the {@link
1248 * StrictMath#copySign(double, double) StrictMath.copySign}
1249 * method, this method does not require NaN {@code sign}
1250 * arguments to be treated as positive values; implementations are
1251 * permitted to treat some NaN arguments as positive and other NaN
1252 * arguments as negative to allow greater performance.
1253 *
1254 * @param magnitude the parameter providing the magnitude of the result
1255 * @param sign the parameter providing the sign of the result
1256 * @return a value with the magnitude of {@code magnitude}
1257 * and the sign of {@code sign}.
1258 * @since 1.6
1259 */
1260 public static double copySign(double magnitude, double sign) {
1261 return sun.misc.FpUtils.rawCopySign(magnitude, sign);
1262 }
1263
1264 /**
1265 * Returns the first floating-point argument with the sign of the
1266 * second floating-point argument. Note that unlike the {@link
1267 * StrictMath#copySign(float, float) StrictMath.copySign}
1268 * method, this method does not require NaN {@code sign}
1269 * arguments to be treated as positive values; implementations are
1270 * permitted to treat some NaN arguments as positive and other NaN
1271 * arguments as negative to allow greater performance.
1272 *
1273 * @param magnitude the parameter providing the magnitude of the result
1274 * @param sign the parameter providing the sign of the result
1275 * @return a value with the magnitude of {@code magnitude}
1276 * and the sign of {@code sign}.
1277 * @since 1.6
1278 */
1279 public static float copySign(float magnitude, float sign) {
1280 return sun.misc.FpUtils.rawCopySign(magnitude, sign);
1281 }
1282
1283 /**
1284 * Returns the unbiased exponent used in the representation of a
1285 * {@code float}. Special cases:
1286 *
1287 * <ul>
1288 * <li>If the argument is NaN or infinite, then the result is
1289 * {@link Float#MAX_EXPONENT} + 1.
1290 * <li>If the argument is zero or subnormal, then the result is
1291 * {@link Float#MIN_EXPONENT} -1.
1292 * </ul>
1293 * @param f a {@code float} value
1294 * @return the unbiased exponent of the argument
1295 * @since 1.6
1296 */
1297 public static int getExponent(float f) {
1298 return sun.misc.FpUtils.getExponent(f);
1299 }
1300
1301 /**
1302 * Returns the unbiased exponent used in the representation of a
1303 * {@code double}. Special cases:
1304 *
1305 * <ul>
1306 * <li>If the argument is NaN or infinite, then the result is
1307 * {@link Double#MAX_EXPONENT} + 1.
1308 * <li>If the argument is zero or subnormal, then the result is
1309 * {@link Double#MIN_EXPONENT} -1.
1310 * </ul>
1311 * @param d a {@code double} value
1312 * @return the unbiased exponent of the argument
1313 * @since 1.6
1314 */
1315 public static int getExponent(double d) {
1316 return sun.misc.FpUtils.getExponent(d);
1317 }
1318
1319 /**
1320 * Returns the floating-point number adjacent to the first
1321 * argument in the direction of the second argument. If both
1322 * arguments compare as equal the second argument is returned.
1323 *
1324 * <p>
1325 * Special cases:
1326 * <ul>
1327 * <li> If either argument is a NaN, then NaN is returned.
1328 *
1329 * <li> If both arguments are signed zeros, {@code direction}
1330 * is returned unchanged (as implied by the requirement of
1331 * returning the second argument if the arguments compare as
1332 * equal).
1333 *
1334 * <li> If {@code start} is
1335 * ±{@link Double#MIN_VALUE} and {@code direction}
1336 * has a value such that the result should have a smaller
1337 * magnitude, then a zero with the same sign as {@code start}
1338 * is returned.
1339 *
1340 * <li> If {@code start} is infinite and
1341 * {@code direction} has a value such that the result should
1342 * have a smaller magnitude, {@link Double#MAX_VALUE} with the
1343 * same sign as {@code start} is returned.
1344 *
1345 * <li> If {@code start} is equal to ±
1346 * {@link Double#MAX_VALUE} and {@code direction} has a
1347 * value such that the result should have a larger magnitude, an
1348 * infinity with same sign as {@code start} is returned.
1349 * </ul>
1350 *
1351 * @param start starting floating-point value
1352 * @param direction value indicating which of
1353 * {@code start}'s neighbors or {@code start} should
1354 * be returned
1355 * @return The floating-point number adjacent to {@code start} in the
1356 * direction of {@code direction}.
1357 * @since 1.6
1358 */
1359 public static double nextAfter(double start, double direction) {
1360 return sun.misc.FpUtils.nextAfter(start, direction);
1361 }
1362
1363 /**
1364 * Returns the floating-point number adjacent to the first
1365 * argument in the direction of the second argument. If both
1366 * arguments compare as equal a value equivalent to the second argument
1367 * is returned.
1368 *
1369 * <p>
1370 * Special cases:
1371 * <ul>
1372 * <li> If either argument is a NaN, then NaN is returned.
1373 *
1374 * <li> If both arguments are signed zeros, a value equivalent
1375 * to {@code direction} is returned.
1376 *
1377 * <li> If {@code start} is
1378 * ±{@link Float#MIN_VALUE} and {@code direction}
1379 * has a value such that the result should have a smaller
1380 * magnitude, then a zero with the same sign as {@code start}
1381 * is returned.
1382 *
1383 * <li> If {@code start} is infinite and
1384 * {@code direction} has a value such that the result should
1385 * have a smaller magnitude, {@link Float#MAX_VALUE} with the
1386 * same sign as {@code start} is returned.
1387 *
1388 * <li> If {@code start} is equal to ±
1389 * {@link Float#MAX_VALUE} and {@code direction} has a
1390 * value such that the result should have a larger magnitude, an
1391 * infinity with same sign as {@code start} is returned.
1392 * </ul>
1393 *
1394 * @param start starting floating-point value
1395 * @param direction value indicating which of
1396 * {@code start}'s neighbors or {@code start} should
1397 * be returned
1398 * @return The floating-point number adjacent to {@code start} in the
1399 * direction of {@code direction}.
1400 * @since 1.6
1401 */
1402 public static float nextAfter(float start, double direction) {
1403 return sun.misc.FpUtils.nextAfter(start, direction);
1404 }
1405
1406 /**
1407 * Returns the floating-point value adjacent to {@code d} in
1408 * the direction of positive infinity. This method is
1409 * semantically equivalent to {@code nextAfter(d,
1410 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
1411 * implementation may run faster than its equivalent
1412 * {@code nextAfter} call.
1413 *
1414 * <p>Special Cases:
1415 * <ul>
1416 * <li> If the argument is NaN, the result is NaN.
1417 *
1418 * <li> If the argument is positive infinity, the result is
1419 * positive infinity.
1420 *
1421 * <li> If the argument is zero, the result is
1422 * {@link Double#MIN_VALUE}
1423 *
1424 * </ul>
1425 *
1426 * @param d starting floating-point value
1427 * @return The adjacent floating-point value closer to positive
1428 * infinity.
1429 * @since 1.6
1430 */
1431 public static double nextUp(double d) {
1432 return sun.misc.FpUtils.nextUp(d);
1433 }
1434
1435 /**
1436 * Returns the floating-point value adjacent to {@code f} in
1437 * the direction of positive infinity. This method is
1438 * semantically equivalent to {@code nextAfter(f,
1439 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
1440 * implementation may run faster than its equivalent
1441 * {@code nextAfter} call.
1442 *
1443 * <p>Special Cases:
1444 * <ul>
1445 * <li> If the argument is NaN, the result is NaN.
1446 *
1447 * <li> If the argument is positive infinity, the result is
1448 * positive infinity.
1449 *
1450 * <li> If the argument is zero, the result is
1451 * {@link Float#MIN_VALUE}
1452 *
1453 * </ul>
1454 *
1455 * @param f starting floating-point value
1456 * @return The adjacent floating-point value closer to positive
1457 * infinity.
1458 * @since 1.6
1459 */
1460 public static float nextUp(float f) {
1461 return sun.misc.FpUtils.nextUp(f);
1462 }
1463
1464 /**
1465 * Return {@code d} ×
1466 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1467 * by a single correctly rounded floating-point multiply to a
1468 * member of the double value set. See the Java
1469 * Language Specification for a discussion of floating-point
1470 * value sets. If the exponent of the result is between {@link
1471 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
1472 * answer is calculated exactly. If the exponent of the result
1473 * would be larger than {@code Double.MAX_EXPONENT}, an
1474 * infinity is returned. Note that if the result is subnormal,
1475 * precision may be lost; that is, when {@code scalb(x, n)}
1476 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1477 * <i>x</i>. When the result is non-NaN, the result has the same
1478 * sign as {@code d}.
1479 *
1480 * <p>Special cases:
1481 * <ul>
1482 * <li> If the first argument is NaN, NaN is returned.
1483 * <li> If the first argument is infinite, then an infinity of the
1484 * same sign is returned.
1485 * <li> If the first argument is zero, then a zero of the same
1486 * sign is returned.
1487 * </ul>
1488 *
1489 * @param d number to be scaled by a power of two.
1490 * @param scaleFactor power of 2 used to scale {@code d}
1491 * @return {@code d} × 2<sup>{@code scaleFactor}</sup>
1492 * @since 1.6
1493 */
1494 public static double scalb(double d, int scaleFactor) {
1495 return sun.misc.FpUtils.scalb(d, scaleFactor);
1496 }
1497
1498 /**
1499 * Return {@code f} ×
1500 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1501 * by a single correctly rounded floating-point multiply to a
1502 * member of the float value set. See the Java
1503 * Language Specification for a discussion of floating-point
1504 * value sets. If the exponent of the result is between {@link
1505 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
1506 * answer is calculated exactly. If the exponent of the result
1507 * would be larger than {@code Float.MAX_EXPONENT}, an
1508 * infinity is returned. Note that if the result is subnormal,
1509 * precision may be lost; that is, when {@code scalb(x, n)}
1510 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1511 * <i>x</i>. When the result is non-NaN, the result has the same
1512 * sign as {@code f}.
1513 *
1514 * <p>Special cases:
1515 * <ul>
1516 * <li> If the first argument is NaN, NaN is returned.
1517 * <li> If the first argument is infinite, then an infinity of the
1518 * same sign is returned.
1519 * <li> If the first argument is zero, then a zero of the same
1520 * sign is returned.
1521 * </ul>
1522 *
1523 * @param f number to be scaled by a power of two.
1524 * @param scaleFactor power of 2 used to scale {@code f}
1525 * @return {@code f} × 2<sup>{@code scaleFactor}</sup>
1526 * @since 1.6
1527 */
1528 public static float scalb(float f, int scaleFactor) {
1529 return sun.misc.FpUtils.scalb(f, scaleFactor);
1530 }
1531 }
|
