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: }
|
