8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27 import java.util.Random;
28 import sun.misc.FpUtils;
29 import sun.misc.DoubleConsts;
30
31 /**
32 * The class {@code StrictMath} contains methods for performing basic
33 * numeric operations such as the elementary exponential, logarithm,
34 * square root, and trigonometric functions.
35 *
36 * <p>To help ensure portability of Java programs, the definitions of
37 * some of the numeric functions in this package require that they
38 * produce the same results as certain published algorithms. These
39 * algorithms are available from the well-known network library
40 * {@code netlib} as the package "Freely Distributable Math
41 * Library," <a
42 * href="ftp://ftp.netlib.org/fdlibm.tar">{@code fdlibm}</a>. These
43 * algorithms, which are written in the C programming language, are
44 * then to be understood as executed with all floating-point
45 * operations following the rules of Java floating-point arithmetic.
46 *
47 * <p>The Java math library is defined with respect to
48 * {@code fdlibm} version 5.3. Where {@code fdlibm} provides
411 *
412 * Otherwise, the sum (twoToThe52 + a ) will properly round
413 * away any fractional portion of a since ulp(twoToThe52) ==
414 * 1.0; subtracting out twoToThe52 from this sum will then be
415 * exact and leave the rounded integer portion of a.
416 *
417 * This method does *not* need to be declared strictfp to get
418 * fully reproducible results. Whether or not a method is
419 * declared strictfp can only make a difference in the
420 * returned result if some operation would overflow or
421 * underflow with strictfp semantics. The operation
422 * (twoToThe52 + a ) cannot overflow since large values of a
423 * are screened out; the add cannot underflow since twoToThe52
424 * is too large. The subtraction ((twoToThe52 + a ) -
425 * twoToThe52) will be exact as discussed above and thus
426 * cannot overflow or meaningfully underflow. Finally, the
427 * last multiply in the return statement is by plus or minus
428 * 1.0, which is exact too.
429 */
430 double twoToThe52 = (double)(1L << 52); // 2^52
431 double sign = FpUtils.rawCopySign(1.0, a); // preserve sign info
432 a = Math.abs(a);
433
434 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51
435 a = ((twoToThe52 + a ) - twoToThe52);
436 }
437
438 return sign * a; // restore original sign
439 }
440
441 /**
442 * Returns the angle <i>theta</i> from the conversion of rectangular
443 * coordinates ({@code x}, {@code y}) to polar
444 * coordinates (r, <i>theta</i>).
445 * This method computes the phase <i>theta</i> by computing an arc tangent
446 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
447 * cases:
448 * <ul><li>If either argument is NaN, then the result is NaN.
449 * <li>If the first argument is positive zero and the second argument
450 * is positive, or the first argument is positive and finite and the
451 * second argument is positive infinity, then the result is positive
938 * double} value next larger in magnitude. Note that for non-NaN
939 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
940 *
941 * <p>Special Cases:
942 * <ul>
943 * <li> If the argument is NaN, then the result is NaN.
944 * <li> If the argument is positive or negative infinity, then the
945 * result is positive infinity.
946 * <li> If the argument is positive or negative zero, then the result is
947 * {@code Double.MIN_VALUE}.
948 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
949 * the result is equal to 2<sup>971</sup>.
950 * </ul>
951 *
952 * @param d the floating-point value whose ulp is to be returned
953 * @return the size of an ulp of the argument
954 * @author Joseph D. Darcy
955 * @since 1.5
956 */
957 public static double ulp(double d) {
958 return sun.misc.FpUtils.ulp(d);
959 }
960
961 /**
962 * Returns the size of an ulp of the argument. An ulp, unit in
963 * the last place, of a {@code float} value is the positive
964 * distance between this floating-point value and the {@code
965 * float} value next larger in magnitude. Note that for non-NaN
966 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
967 *
968 * <p>Special Cases:
969 * <ul>
970 * <li> If the argument is NaN, then the result is NaN.
971 * <li> If the argument is positive or negative infinity, then the
972 * result is positive infinity.
973 * <li> If the argument is positive or negative zero, then the result is
974 * {@code Float.MIN_VALUE}.
975 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
976 * the result is equal to 2<sup>104</sup>.
977 * </ul>
978 *
979 * @param f the floating-point value whose ulp is to be returned
980 * @return the size of an ulp of the argument
981 * @author Joseph D. Darcy
982 * @since 1.5
983 */
984 public static float ulp(float f) {
985 return sun.misc.FpUtils.ulp(f);
986 }
987
988 /**
989 * Returns the signum function of the argument; zero if the argument
990 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
991 * argument is less than zero.
992 *
993 * <p>Special Cases:
994 * <ul>
995 * <li> If the argument is NaN, then the result is NaN.
996 * <li> If the argument is positive zero or negative zero, then the
997 * result is the same as the argument.
998 * </ul>
999 *
1000 * @param d the floating-point value whose signum is to be returned
1001 * @return the signum function of the argument
1002 * @author Joseph D. Darcy
1003 * @since 1.5
1004 */
1005 public static double signum(double d) {
1006 return sun.misc.FpUtils.signum(d);
1007 }
1008
1009 /**
1010 * Returns the signum function of the argument; zero if the argument
1011 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
1012 * argument is less than zero.
1013 *
1014 * <p>Special Cases:
1015 * <ul>
1016 * <li> If the argument is NaN, then the result is NaN.
1017 * <li> If the argument is positive zero or negative zero, then the
1018 * result is the same as the argument.
1019 * </ul>
1020 *
1021 * @param f the floating-point value whose signum is to be returned
1022 * @return the signum function of the argument
1023 * @author Joseph D. Darcy
1024 * @since 1.5
1025 */
1026 public static float signum(float f) {
1027 return sun.misc.FpUtils.signum(f);
1028 }
1029
1030 /**
1031 * Returns the hyperbolic sine of a {@code double} value.
1032 * The hyperbolic sine of <i>x</i> is defined to be
1033 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
1034 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1035 *
1036 * <p>Special cases:
1037 * <ul>
1038 *
1039 * <li>If the argument is NaN, then the result is NaN.
1040 *
1041 * <li>If the argument is infinite, then the result is an infinity
1042 * with the same sign as the argument.
1043 *
1044 * <li>If the argument is zero, then the result is a zero with the
1045 * same sign as the argument.
1046 *
1047 * </ul>
1185 * @param x a value
1186 * @return the value ln({@code x} + 1), the natural
1187 * log of {@code x} + 1
1188 * @since 1.5
1189 */
1190 public static native double log1p(double x);
1191
1192 /**
1193 * Returns the first floating-point argument with the sign of the
1194 * second floating-point argument. For this method, a NaN
1195 * {@code sign} argument is always treated as if it were
1196 * positive.
1197 *
1198 * @param magnitude the parameter providing the magnitude of the result
1199 * @param sign the parameter providing the sign of the result
1200 * @return a value with the magnitude of {@code magnitude}
1201 * and the sign of {@code sign}.
1202 * @since 1.6
1203 */
1204 public static double copySign(double magnitude, double sign) {
1205 return sun.misc.FpUtils.copySign(magnitude, sign);
1206 }
1207
1208 /**
1209 * Returns the first floating-point argument with the sign of the
1210 * second floating-point argument. For this method, a NaN
1211 * {@code sign} argument is always treated as if it were
1212 * positive.
1213 *
1214 * @param magnitude the parameter providing the magnitude of the result
1215 * @param sign the parameter providing the sign of the result
1216 * @return a value with the magnitude of {@code magnitude}
1217 * and the sign of {@code sign}.
1218 * @since 1.6
1219 */
1220 public static float copySign(float magnitude, float sign) {
1221 return sun.misc.FpUtils.copySign(magnitude, sign);
1222 }
1223 /**
1224 * Returns the unbiased exponent used in the representation of a
1225 * {@code float}. Special cases:
1226 *
1227 * <ul>
1228 * <li>If the argument is NaN or infinite, then the result is
1229 * {@link Float#MAX_EXPONENT} + 1.
1230 * <li>If the argument is zero or subnormal, then the result is
1231 * {@link Float#MIN_EXPONENT} -1.
1232 * </ul>
1233 * @param f a {@code float} value
1234 * @since 1.6
1235 */
1236 public static int getExponent(float f) {
1237 return sun.misc.FpUtils.getExponent(f);
1238 }
1239
1240 /**
1241 * Returns the unbiased exponent used in the representation of a
1242 * {@code double}. Special cases:
1243 *
1244 * <ul>
1245 * <li>If the argument is NaN or infinite, then the result is
1246 * {@link Double#MAX_EXPONENT} + 1.
1247 * <li>If the argument is zero or subnormal, then the result is
1248 * {@link Double#MIN_EXPONENT} -1.
1249 * </ul>
1250 * @param d a {@code double} value
1251 * @since 1.6
1252 */
1253 public static int getExponent(double d) {
1254 return sun.misc.FpUtils.getExponent(d);
1255 }
1256
1257 /**
1258 * Returns the floating-point number adjacent to the first
1259 * argument in the direction of the second argument. If both
1260 * arguments compare as equal the second argument is returned.
1261 *
1262 * <p>Special cases:
1263 * <ul>
1264 * <li> If either argument is a NaN, then NaN is returned.
1265 *
1266 * <li> If both arguments are signed zeros, {@code direction}
1267 * is returned unchanged (as implied by the requirement of
1268 * returning the second argument if the arguments compare as
1269 * equal).
1270 *
1271 * <li> If {@code start} is
1272 * ±{@link Double#MIN_VALUE} and {@code direction}
1273 * has a value such that the result should have a smaller
1274 * magnitude, then a zero with the same sign as {@code start}
1277 * <li> If {@code start} is infinite and
1278 * {@code direction} has a value such that the result should
1279 * have a smaller magnitude, {@link Double#MAX_VALUE} with the
1280 * same sign as {@code start} is returned.
1281 *
1282 * <li> If {@code start} is equal to ±
1283 * {@link Double#MAX_VALUE} and {@code direction} has a
1284 * value such that the result should have a larger magnitude, an
1285 * infinity with same sign as {@code start} is returned.
1286 * </ul>
1287 *
1288 * @param start starting floating-point value
1289 * @param direction value indicating which of
1290 * {@code start}'s neighbors or {@code start} should
1291 * be returned
1292 * @return The floating-point number adjacent to {@code start} in the
1293 * direction of {@code direction}.
1294 * @since 1.6
1295 */
1296 public static double nextAfter(double start, double direction) {
1297 return sun.misc.FpUtils.nextAfter(start, direction);
1298 }
1299
1300 /**
1301 * Returns the floating-point number adjacent to the first
1302 * argument in the direction of the second argument. If both
1303 * arguments compare as equal a value equivalent to the second argument
1304 * is returned.
1305 *
1306 * <p>Special cases:
1307 * <ul>
1308 * <li> If either argument is a NaN, then NaN is returned.
1309 *
1310 * <li> If both arguments are signed zeros, a value equivalent
1311 * to {@code direction} is returned.
1312 *
1313 * <li> If {@code start} is
1314 * ±{@link Float#MIN_VALUE} and {@code direction}
1315 * has a value such that the result should have a smaller
1316 * magnitude, then a zero with the same sign as {@code start}
1317 * is returned.
1319 * <li> If {@code start} is infinite and
1320 * {@code direction} has a value such that the result should
1321 * have a smaller magnitude, {@link Float#MAX_VALUE} with the
1322 * same sign as {@code start} is returned.
1323 *
1324 * <li> If {@code start} is equal to ±
1325 * {@link Float#MAX_VALUE} and {@code direction} has a
1326 * value such that the result should have a larger magnitude, an
1327 * infinity with same sign as {@code start} is returned.
1328 * </ul>
1329 *
1330 * @param start starting floating-point value
1331 * @param direction value indicating which of
1332 * {@code start}'s neighbors or {@code start} should
1333 * be returned
1334 * @return The floating-point number adjacent to {@code start} in the
1335 * direction of {@code direction}.
1336 * @since 1.6
1337 */
1338 public static float nextAfter(float start, double direction) {
1339 return sun.misc.FpUtils.nextAfter(start, direction);
1340 }
1341
1342 /**
1343 * Returns the floating-point value adjacent to {@code d} in
1344 * the direction of positive infinity. This method is
1345 * semantically equivalent to {@code nextAfter(d,
1346 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
1347 * implementation may run faster than its equivalent
1348 * {@code nextAfter} call.
1349 *
1350 * <p>Special Cases:
1351 * <ul>
1352 * <li> If the argument is NaN, the result is NaN.
1353 *
1354 * <li> If the argument is positive infinity, the result is
1355 * positive infinity.
1356 *
1357 * <li> If the argument is zero, the result is
1358 * {@link Double#MIN_VALUE}
1359 *
1360 * </ul>
1361 *
1362 * @param d starting floating-point value
1363 * @return The adjacent floating-point value closer to positive
1364 * infinity.
1365 * @since 1.6
1366 */
1367 public static double nextUp(double d) {
1368 return sun.misc.FpUtils.nextUp(d);
1369 }
1370
1371 /**
1372 * Returns the floating-point value adjacent to {@code f} in
1373 * the direction of positive infinity. This method is
1374 * semantically equivalent to {@code nextAfter(f,
1375 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
1376 * implementation may run faster than its equivalent
1377 * {@code nextAfter} call.
1378 *
1379 * <p>Special Cases:
1380 * <ul>
1381 * <li> If the argument is NaN, the result is NaN.
1382 *
1383 * <li> If the argument is positive infinity, the result is
1384 * positive infinity.
1385 *
1386 * <li> If the argument is zero, the result is
1387 * {@link Float#MIN_VALUE}
1388 *
1389 * </ul>
1390 *
1391 * @param f starting floating-point value
1392 * @return The adjacent floating-point value closer to positive
1393 * infinity.
1394 * @since 1.6
1395 */
1396 public static float nextUp(float f) {
1397 return sun.misc.FpUtils.nextUp(f);
1398 }
1399
1400
1401 /**
1402 * Return {@code d} ×
1403 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1404 * by a single correctly rounded floating-point multiply to a
1405 * member of the double value set. See the Java
1406 * Language Specification for a discussion of floating-point
1407 * value sets. If the exponent of the result is between {@link
1408 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
1409 * answer is calculated exactly. If the exponent of the result
1410 * would be larger than {@code Double.MAX_EXPONENT}, an
1411 * infinity is returned. Note that if the result is subnormal,
1412 * precision may be lost; that is, when {@code scalb(x, n)}
1413 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1414 * <i>x</i>. When the result is non-NaN, the result has the same
1415 * sign as {@code d}.
1416 *
1417 * <p>Special cases:
1418 * <ul>
1419 * <li> If the first argument is NaN, NaN is returned.
1420 * <li> If the first argument is infinite, then an infinity of the
1421 * same sign is returned.
1422 * <li> If the first argument is zero, then a zero of the same
1423 * sign is returned.
1424 * </ul>
1425 *
1426 * @param d number to be scaled by a power of two.
1427 * @param scaleFactor power of 2 used to scale {@code d}
1428 * @return {@code d} × 2<sup>{@code scaleFactor}</sup>
1429 * @since 1.6
1430 */
1431 public static double scalb(double d, int scaleFactor) {
1432 return sun.misc.FpUtils.scalb(d, scaleFactor);
1433 }
1434
1435 /**
1436 * Return {@code f} ×
1437 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1438 * by a single correctly rounded floating-point multiply to a
1439 * member of the float value set. See the Java
1440 * Language Specification for a discussion of floating-point
1441 * value sets. If the exponent of the result is between {@link
1442 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
1443 * answer is calculated exactly. If the exponent of the result
1444 * would be larger than {@code Float.MAX_EXPONENT}, an
1445 * infinity is returned. Note that if the result is subnormal,
1446 * precision may be lost; that is, when {@code scalb(x, n)}
1447 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1448 * <i>x</i>. When the result is non-NaN, the result has the same
1449 * sign as {@code f}.
1450 *
1451 * <p>Special cases:
1452 * <ul>
1453 * <li> If the first argument is NaN, NaN is returned.
1454 * <li> If the first argument is infinite, then an infinity of the
1455 * same sign is returned.
1456 * <li> If the first argument is zero, then a zero of the same
1457 * sign is returned.
1458 * </ul>
1459 *
1460 * @param f number to be scaled by a power of two.
1461 * @param scaleFactor power of 2 used to scale {@code f}
1462 * @return {@code f} × 2<sup>{@code scaleFactor}</sup>
1463 * @since 1.6
1464 */
1465 public static float scalb(float f, int scaleFactor) {
1466 return sun.misc.FpUtils.scalb(f, scaleFactor);
1467 }
1468 }
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27 import java.util.Random;
28 import sun.misc.DoubleConsts;
29
30 /**
31 * The class {@code StrictMath} contains methods for performing basic
32 * numeric operations such as the elementary exponential, logarithm,
33 * square root, and trigonometric functions.
34 *
35 * <p>To help ensure portability of Java programs, the definitions of
36 * some of the numeric functions in this package require that they
37 * produce the same results as certain published algorithms. These
38 * algorithms are available from the well-known network library
39 * {@code netlib} as the package "Freely Distributable Math
40 * Library," <a
41 * href="ftp://ftp.netlib.org/fdlibm.tar">{@code fdlibm}</a>. These
42 * algorithms, which are written in the C programming language, are
43 * then to be understood as executed with all floating-point
44 * operations following the rules of Java floating-point arithmetic.
45 *
46 * <p>The Java math library is defined with respect to
47 * {@code fdlibm} version 5.3. Where {@code fdlibm} provides
410 *
411 * Otherwise, the sum (twoToThe52 + a ) will properly round
412 * away any fractional portion of a since ulp(twoToThe52) ==
413 * 1.0; subtracting out twoToThe52 from this sum will then be
414 * exact and leave the rounded integer portion of a.
415 *
416 * This method does *not* need to be declared strictfp to get
417 * fully reproducible results. Whether or not a method is
418 * declared strictfp can only make a difference in the
419 * returned result if some operation would overflow or
420 * underflow with strictfp semantics. The operation
421 * (twoToThe52 + a ) cannot overflow since large values of a
422 * are screened out; the add cannot underflow since twoToThe52
423 * is too large. The subtraction ((twoToThe52 + a ) -
424 * twoToThe52) will be exact as discussed above and thus
425 * cannot overflow or meaningfully underflow. Finally, the
426 * last multiply in the return statement is by plus or minus
427 * 1.0, which is exact too.
428 */
429 double twoToThe52 = (double)(1L << 52); // 2^52
430 double sign = Math.copySign(1.0, a); // preserve sign info
431 a = Math.abs(a);
432
433 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51
434 a = ((twoToThe52 + a ) - twoToThe52);
435 }
436
437 return sign * a; // restore original sign
438 }
439
440 /**
441 * Returns the angle <i>theta</i> from the conversion of rectangular
442 * coordinates ({@code x}, {@code y}) to polar
443 * coordinates (r, <i>theta</i>).
444 * This method computes the phase <i>theta</i> by computing an arc tangent
445 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
446 * cases:
447 * <ul><li>If either argument is NaN, then the result is NaN.
448 * <li>If the first argument is positive zero and the second argument
449 * is positive, or the first argument is positive and finite and the
450 * second argument is positive infinity, then the result is positive
937 * double} value next larger in magnitude. Note that for non-NaN
938 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
939 *
940 * <p>Special Cases:
941 * <ul>
942 * <li> If the argument is NaN, then the result is NaN.
943 * <li> If the argument is positive or negative infinity, then the
944 * result is positive infinity.
945 * <li> If the argument is positive or negative zero, then the result is
946 * {@code Double.MIN_VALUE}.
947 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
948 * the result is equal to 2<sup>971</sup>.
949 * </ul>
950 *
951 * @param d the floating-point value whose ulp is to be returned
952 * @return the size of an ulp of the argument
953 * @author Joseph D. Darcy
954 * @since 1.5
955 */
956 public static double ulp(double d) {
957 return Math.ulp(d);
958 }
959
960 /**
961 * Returns the size of an ulp of the argument. An ulp, unit in
962 * the last place, of a {@code float} value is the positive
963 * distance between this floating-point value and the {@code
964 * float} value next larger in magnitude. Note that for non-NaN
965 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
966 *
967 * <p>Special Cases:
968 * <ul>
969 * <li> If the argument is NaN, then the result is NaN.
970 * <li> If the argument is positive or negative infinity, then the
971 * result is positive infinity.
972 * <li> If the argument is positive or negative zero, then the result is
973 * {@code Float.MIN_VALUE}.
974 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
975 * the result is equal to 2<sup>104</sup>.
976 * </ul>
977 *
978 * @param f the floating-point value whose ulp is to be returned
979 * @return the size of an ulp of the argument
980 * @author Joseph D. Darcy
981 * @since 1.5
982 */
983 public static float ulp(float f) {
984 return Math.ulp(f);
985 }
986
987 /**
988 * Returns the signum function of the argument; zero if the argument
989 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
990 * argument is less than zero.
991 *
992 * <p>Special Cases:
993 * <ul>
994 * <li> If the argument is NaN, then the result is NaN.
995 * <li> If the argument is positive zero or negative zero, then the
996 * result is the same as the argument.
997 * </ul>
998 *
999 * @param d the floating-point value whose signum is to be returned
1000 * @return the signum function of the argument
1001 * @author Joseph D. Darcy
1002 * @since 1.5
1003 */
1004 public static double signum(double d) {
1005 return Math.signum(d);
1006 }
1007
1008 /**
1009 * Returns the signum function of the argument; zero if the argument
1010 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
1011 * argument is less than zero.
1012 *
1013 * <p>Special Cases:
1014 * <ul>
1015 * <li> If the argument is NaN, then the result is NaN.
1016 * <li> If the argument is positive zero or negative zero, then the
1017 * result is the same as the argument.
1018 * </ul>
1019 *
1020 * @param f the floating-point value whose signum is to be returned
1021 * @return the signum function of the argument
1022 * @author Joseph D. Darcy
1023 * @since 1.5
1024 */
1025 public static float signum(float f) {
1026 return Math.signum(f);
1027 }
1028
1029 /**
1030 * Returns the hyperbolic sine of a {@code double} value.
1031 * The hyperbolic sine of <i>x</i> is defined to be
1032 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
1033 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1034 *
1035 * <p>Special cases:
1036 * <ul>
1037 *
1038 * <li>If the argument is NaN, then the result is NaN.
1039 *
1040 * <li>If the argument is infinite, then the result is an infinity
1041 * with the same sign as the argument.
1042 *
1043 * <li>If the argument is zero, then the result is a zero with the
1044 * same sign as the argument.
1045 *
1046 * </ul>
1184 * @param x a value
1185 * @return the value ln({@code x} + 1), the natural
1186 * log of {@code x} + 1
1187 * @since 1.5
1188 */
1189 public static native double log1p(double x);
1190
1191 /**
1192 * Returns the first floating-point argument with the sign of the
1193 * second floating-point argument. For this method, a NaN
1194 * {@code sign} argument is always treated as if it were
1195 * positive.
1196 *
1197 * @param magnitude the parameter providing the magnitude of the result
1198 * @param sign the parameter providing the sign of the result
1199 * @return a value with the magnitude of {@code magnitude}
1200 * and the sign of {@code sign}.
1201 * @since 1.6
1202 */
1203 public static double copySign(double magnitude, double sign) {
1204 return Math.copySign(magnitude, (Double.isNaN(sign)?1.0d:sign));
1205 }
1206
1207 /**
1208 * Returns the first floating-point argument with the sign of the
1209 * second floating-point argument. For this method, a NaN
1210 * {@code sign} argument is always treated as if it were
1211 * positive.
1212 *
1213 * @param magnitude the parameter providing the magnitude of the result
1214 * @param sign the parameter providing the sign of the result
1215 * @return a value with the magnitude of {@code magnitude}
1216 * and the sign of {@code sign}.
1217 * @since 1.6
1218 */
1219 public static float copySign(float magnitude, float sign) {
1220 return Math.copySign(magnitude, (Float.isNaN(sign)?1.0f:sign));
1221 }
1222 /**
1223 * Returns the unbiased exponent used in the representation of a
1224 * {@code float}. Special cases:
1225 *
1226 * <ul>
1227 * <li>If the argument is NaN or infinite, then the result is
1228 * {@link Float#MAX_EXPONENT} + 1.
1229 * <li>If the argument is zero or subnormal, then the result is
1230 * {@link Float#MIN_EXPONENT} -1.
1231 * </ul>
1232 * @param f a {@code float} value
1233 * @since 1.6
1234 */
1235 public static int getExponent(float f) {
1236 return Math.getExponent(f);
1237 }
1238
1239 /**
1240 * Returns the unbiased exponent used in the representation of a
1241 * {@code double}. Special cases:
1242 *
1243 * <ul>
1244 * <li>If the argument is NaN or infinite, then the result is
1245 * {@link Double#MAX_EXPONENT} + 1.
1246 * <li>If the argument is zero or subnormal, then the result is
1247 * {@link Double#MIN_EXPONENT} -1.
1248 * </ul>
1249 * @param d a {@code double} value
1250 * @since 1.6
1251 */
1252 public static int getExponent(double d) {
1253 return Math.getExponent(d);
1254 }
1255
1256 /**
1257 * Returns the floating-point number adjacent to the first
1258 * argument in the direction of the second argument. If both
1259 * arguments compare as equal the second argument is returned.
1260 *
1261 * <p>Special cases:
1262 * <ul>
1263 * <li> If either argument is a NaN, then NaN is returned.
1264 *
1265 * <li> If both arguments are signed zeros, {@code direction}
1266 * is returned unchanged (as implied by the requirement of
1267 * returning the second argument if the arguments compare as
1268 * equal).
1269 *
1270 * <li> If {@code start} is
1271 * ±{@link Double#MIN_VALUE} and {@code direction}
1272 * has a value such that the result should have a smaller
1273 * magnitude, then a zero with the same sign as {@code start}
1276 * <li> If {@code start} is infinite and
1277 * {@code direction} has a value such that the result should
1278 * have a smaller magnitude, {@link Double#MAX_VALUE} with the
1279 * same sign as {@code start} is returned.
1280 *
1281 * <li> If {@code start} is equal to ±
1282 * {@link Double#MAX_VALUE} and {@code direction} has a
1283 * value such that the result should have a larger magnitude, an
1284 * infinity with same sign as {@code start} is returned.
1285 * </ul>
1286 *
1287 * @param start starting floating-point value
1288 * @param direction value indicating which of
1289 * {@code start}'s neighbors or {@code start} should
1290 * be returned
1291 * @return The floating-point number adjacent to {@code start} in the
1292 * direction of {@code direction}.
1293 * @since 1.6
1294 */
1295 public static double nextAfter(double start, double direction) {
1296 return Math.nextAfter(start, direction);
1297 }
1298
1299 /**
1300 * Returns the floating-point number adjacent to the first
1301 * argument in the direction of the second argument. If both
1302 * arguments compare as equal a value equivalent to the second argument
1303 * is returned.
1304 *
1305 * <p>Special cases:
1306 * <ul>
1307 * <li> If either argument is a NaN, then NaN is returned.
1308 *
1309 * <li> If both arguments are signed zeros, a value equivalent
1310 * to {@code direction} is returned.
1311 *
1312 * <li> If {@code start} is
1313 * ±{@link Float#MIN_VALUE} and {@code direction}
1314 * has a value such that the result should have a smaller
1315 * magnitude, then a zero with the same sign as {@code start}
1316 * is returned.
1318 * <li> If {@code start} is infinite and
1319 * {@code direction} has a value such that the result should
1320 * have a smaller magnitude, {@link Float#MAX_VALUE} with the
1321 * same sign as {@code start} is returned.
1322 *
1323 * <li> If {@code start} is equal to ±
1324 * {@link Float#MAX_VALUE} and {@code direction} has a
1325 * value such that the result should have a larger magnitude, an
1326 * infinity with same sign as {@code start} is returned.
1327 * </ul>
1328 *
1329 * @param start starting floating-point value
1330 * @param direction value indicating which of
1331 * {@code start}'s neighbors or {@code start} should
1332 * be returned
1333 * @return The floating-point number adjacent to {@code start} in the
1334 * direction of {@code direction}.
1335 * @since 1.6
1336 */
1337 public static float nextAfter(float start, double direction) {
1338 return Math.nextAfter(start, direction);
1339 }
1340
1341 /**
1342 * Returns the floating-point value adjacent to {@code d} in
1343 * the direction of positive infinity. This method is
1344 * semantically equivalent to {@code nextAfter(d,
1345 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
1346 * implementation may run faster than its equivalent
1347 * {@code nextAfter} call.
1348 *
1349 * <p>Special Cases:
1350 * <ul>
1351 * <li> If the argument is NaN, the result is NaN.
1352 *
1353 * <li> If the argument is positive infinity, the result is
1354 * positive infinity.
1355 *
1356 * <li> If the argument is zero, the result is
1357 * {@link Double#MIN_VALUE}
1358 *
1359 * </ul>
1360 *
1361 * @param d starting floating-point value
1362 * @return The adjacent floating-point value closer to positive
1363 * infinity.
1364 * @since 1.6
1365 */
1366 public static double nextUp(double d) {
1367 return Math.nextUp(d);
1368 }
1369
1370 /**
1371 * Returns the floating-point value adjacent to {@code f} in
1372 * the direction of positive infinity. This method is
1373 * semantically equivalent to {@code nextAfter(f,
1374 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
1375 * implementation may run faster than its equivalent
1376 * {@code nextAfter} call.
1377 *
1378 * <p>Special Cases:
1379 * <ul>
1380 * <li> If the argument is NaN, the result is NaN.
1381 *
1382 * <li> If the argument is positive infinity, the result is
1383 * positive infinity.
1384 *
1385 * <li> If the argument is zero, the result is
1386 * {@link Float#MIN_VALUE}
1387 *
1388 * </ul>
1389 *
1390 * @param f starting floating-point value
1391 * @return The adjacent floating-point value closer to positive
1392 * infinity.
1393 * @since 1.6
1394 */
1395 public static float nextUp(float f) {
1396 return Math.nextUp(f);
1397 }
1398
1399 /**
1400 * Return {@code d} ×
1401 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1402 * by a single correctly rounded floating-point multiply to a
1403 * member of the double value set. See the Java
1404 * Language Specification for a discussion of floating-point
1405 * value sets. If the exponent of the result is between {@link
1406 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
1407 * answer is calculated exactly. If the exponent of the result
1408 * would be larger than {@code Double.MAX_EXPONENT}, an
1409 * infinity is returned. Note that if the result is subnormal,
1410 * precision may be lost; that is, when {@code scalb(x, n)}
1411 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1412 * <i>x</i>. When the result is non-NaN, the result has the same
1413 * sign as {@code d}.
1414 *
1415 * <p>Special cases:
1416 * <ul>
1417 * <li> If the first argument is NaN, NaN is returned.
1418 * <li> If the first argument is infinite, then an infinity of the
1419 * same sign is returned.
1420 * <li> If the first argument is zero, then a zero of the same
1421 * sign is returned.
1422 * </ul>
1423 *
1424 * @param d number to be scaled by a power of two.
1425 * @param scaleFactor power of 2 used to scale {@code d}
1426 * @return {@code d} × 2<sup>{@code scaleFactor}</sup>
1427 * @since 1.6
1428 */
1429 public static double scalb(double d, int scaleFactor) {
1430 return Math.scalb(d, scaleFactor);
1431 }
1432
1433 /**
1434 * Return {@code f} ×
1435 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1436 * by a single correctly rounded floating-point multiply to a
1437 * member of the float value set. See the Java
1438 * Language Specification for a discussion of floating-point
1439 * value sets. If the exponent of the result is between {@link
1440 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
1441 * answer is calculated exactly. If the exponent of the result
1442 * would be larger than {@code Float.MAX_EXPONENT}, an
1443 * infinity is returned. Note that if the result is subnormal,
1444 * precision may be lost; that is, when {@code scalb(x, n)}
1445 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1446 * <i>x</i>. When the result is non-NaN, the result has the same
1447 * sign as {@code f}.
1448 *
1449 * <p>Special cases:
1450 * <ul>
1451 * <li> If the first argument is NaN, NaN is returned.
1452 * <li> If the first argument is infinite, then an infinity of the
1453 * same sign is returned.
1454 * <li> If the first argument is zero, then a zero of the same
1455 * sign is returned.
1456 * </ul>
1457 *
1458 * @param f number to be scaled by a power of two.
1459 * @param scaleFactor power of 2 used to scale {@code f}
1460 * @return {@code f} × 2<sup>{@code scaleFactor}</sup>
1461 * @since 1.6
1462 */
1463 public static float scalb(float f, int scaleFactor) {
1464 return Math.scalb(f, scaleFactor);
1465 }
1466 }
|