1 /*
2 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
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
48 * more than one definition for a function (such as
49 * {@code acos}), use the "IEEE 754 core function" version
50 * (residing in a file whose name begins with the letter
51 * {@code e}). The methods which require {@code fdlibm}
52 * semantics are {@code sin}, {@code cos}, {@code tan},
53 * {@code asin}, {@code acos}, {@code atan},
54 * {@code exp}, {@code log}, {@code log10},
55 * {@code cbrt}, {@code atan2}, {@code pow},
56 * {@code sinh}, {@code cosh}, {@code tanh},
57 * {@code hypot}, {@code expm1}, and {@code log1p}.
58 *
59 * <p>
60 * The platform uses signed two's complement integer arithmetic with
61 * int and long primitive types. The developer should choose
62 * the primitive type to ensure that arithmetic operations consistently
63 * produce correct results, which in some cases means the operations
64 * will not overflow the range of values of the computation.
65 * The best practice is to choose the primitive type and algorithm to avoid
66 * overflow. In cases where the size is {@code int} or {@code long} and
67 * overflow errors need to be detected, the methods {@code addExact},
68 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact}
69 * throw an {@code ArithmeticException} when the results overflow.
70 * For other arithmetic operations such as divide, absolute value,
71 * increment, decrement, and negation overflow occurs only with
72 * a specific minimum or maximum value and should be checked against
73 * the minimum or maximum as appropriate.
74 *
75 * @author unascribed
76 * @author Joseph D. Darcy
77 * @since 1.3
78 */
79
80 public final class StrictMath {
81
82 /**
83 * Don't let anyone instantiate this class.
84 */
85 private StrictMath() {}
86
87 /**
88 * The {@code double} value that is closer than any other to
89 * <i>e</i>, the base of the natural logarithms.
90 */
91 public static final double E = 2.7182818284590452354;
92
93 /**
94 * The {@code double} value that is closer than any other to
95 * <i>pi</i>, the ratio of the circumference of a circle to its
96 * diameter.
97 */
98 public static final double PI = 3.14159265358979323846;
99
100 /**
101 * Returns the trigonometric sine of an angle. Special cases:
102 * <ul><li>If the argument is NaN or an infinity, then the
103 * result is NaN.
104 * <li>If the argument is zero, then the result is a zero with the
105 * same sign as the argument.</ul>
106 *
107 * @param a an angle, in radians.
108 * @return the sine of the argument.
109 */
110 public static native double sin(double a);
111
112 /**
113 * Returns the trigonometric cosine of an angle. Special cases:
114 * <ul><li>If the argument is NaN or an infinity, then the
115 * result is NaN.</ul>
116 *
117 * @param a an angle, in radians.
118 * @return the cosine of the argument.
119 */
120 public static native double cos(double a);
121
122 /**
123 * Returns the trigonometric tangent of an angle. Special cases:
124 * <ul><li>If the argument is NaN or an infinity, then the result
125 * is NaN.
126 * <li>If the argument is zero, then the result is a zero with the
127 * same sign as the argument.</ul>
128 *
129 * @param a an angle, in radians.
130 * @return the tangent of the argument.
131 */
132 public static native double tan(double a);
133
134 /**
135 * Returns the arc sine of a value; the returned angle is in the
136 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
137 * <ul><li>If the argument is NaN or its absolute value is greater
138 * than 1, then the result is NaN.
139 * <li>If the argument is zero, then the result is a zero with the
140 * same sign as the argument.</ul>
141 *
142 * @param a the value whose arc sine is to be returned.
143 * @return the arc sine of the argument.
144 */
145 public static native double asin(double a);
146
147 /**
148 * Returns the arc cosine of a value; the returned angle is in the
149 * range 0.0 through <i>pi</i>. Special case:
150 * <ul><li>If the argument is NaN or its absolute value is greater
151 * than 1, then the result is NaN.</ul>
152 *
153 * @param a the value whose arc cosine is to be returned.
154 * @return the arc cosine of the argument.
155 */
156 public static native double acos(double a);
157
158 /**
159 * Returns the arc tangent of a value; the returned angle is in the
160 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
161 * <ul><li>If the argument is NaN, then the result is NaN.
162 * <li>If the argument is zero, then the result is a zero with the
163 * same sign as the argument.</ul>
164 *
165 * @param a the value whose arc tangent is to be returned.
166 * @return the arc tangent of the argument.
167 */
168 public static native double atan(double a);
169
170 /**
171 * Converts an angle measured in degrees to an approximately
172 * equivalent angle measured in radians. The conversion from
173 * degrees to radians is generally inexact.
174 *
175 * @param angdeg an angle, in degrees
176 * @return the measurement of the angle {@code angdeg}
177 * in radians.
178 */
179 public static strictfp double toRadians(double angdeg) {
180 // Do not delegate to Math.toRadians(angdeg) because
181 // this method has the strictfp modifier.
182 return angdeg / 180.0 * PI;
183 }
184
185 /**
186 * Converts an angle measured in radians to an approximately
187 * equivalent angle measured in degrees. The conversion from
188 * radians to degrees is generally inexact; users should
189 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly
190 * equal {@code 0.0}.
191 *
192 * @param angrad an angle, in radians
193 * @return the measurement of the angle {@code angrad}
194 * in degrees.
195 */
196 public static strictfp double toDegrees(double angrad) {
197 // Do not delegate to Math.toDegrees(angrad) because
198 // this method has the strictfp modifier.
199 return angrad * 180.0 / PI;
200 }
201
202 /**
203 * Returns Euler's number <i>e</i> raised to the power of a
204 * {@code double} value. Special cases:
205 * <ul><li>If the argument is NaN, the result is NaN.
206 * <li>If the argument is positive infinity, then the result is
207 * positive infinity.
208 * <li>If the argument is negative infinity, then the result is
209 * positive zero.</ul>
210 *
211 * @param a the exponent to raise <i>e</i> to.
212 * @return the value <i>e</i><sup>{@code a}</sup>,
213 * where <i>e</i> is the base of the natural logarithms.
214 */
215 public static native double exp(double a);
216
217 /**
218 * Returns the natural logarithm (base <i>e</i>) of a {@code double}
219 * value. Special cases:
220 * <ul><li>If the argument is NaN or less than zero, then the result
221 * is NaN.
222 * <li>If the argument is positive infinity, then the result is
223 * positive infinity.
224 * <li>If the argument is positive zero or negative zero, then the
225 * result is negative infinity.</ul>
226 *
227 * @param a a value
228 * @return the value ln {@code a}, the natural logarithm of
229 * {@code a}.
230 */
231 public static native double log(double a);
232
233
234 /**
235 * Returns the base 10 logarithm of a {@code double} value.
236 * Special cases:
237 *
238 * <ul><li>If the argument is NaN or less than zero, then the result
239 * is NaN.
240 * <li>If the argument is positive infinity, then the result is
241 * positive infinity.
242 * <li>If the argument is positive zero or negative zero, then the
243 * result is negative infinity.
244 * <li> If the argument is equal to 10<sup><i>n</i></sup> for
245 * integer <i>n</i>, then the result is <i>n</i>.
246 * </ul>
247 *
248 * @param a a value
249 * @return the base 10 logarithm of {@code a}.
250 * @since 1.5
251 */
252 public static native double log10(double a);
253
254 /**
255 * Returns the correctly rounded positive square root of a
256 * {@code double} value.
257 * Special cases:
258 * <ul><li>If the argument is NaN or less than zero, then the result
259 * is NaN.
260 * <li>If the argument is positive infinity, then the result is positive
261 * infinity.
262 * <li>If the argument is positive zero or negative zero, then the
263 * result is the same as the argument.</ul>
264 * Otherwise, the result is the {@code double} value closest to
265 * the true mathematical square root of the argument value.
266 *
267 * @param a a value.
268 * @return the positive square root of {@code a}.
269 */
270 public static native double sqrt(double a);
271
272 /**
273 * Returns the cube root of a {@code double} value. For
274 * positive finite {@code x}, {@code cbrt(-x) ==
275 * -cbrt(x)}; that is, the cube root of a negative value is
276 * the negative of the cube root of that value's magnitude.
277 * Special cases:
278 *
279 * <ul>
280 *
281 * <li>If the argument is NaN, then the result is NaN.
282 *
283 * <li>If the argument is infinite, then the result is an infinity
284 * with the same sign as the argument.
285 *
286 * <li>If the argument is zero, then the result is a zero with the
287 * same sign as the argument.
288 *
289 * </ul>
290 *
291 * @param a a value.
292 * @return the cube root of {@code a}.
293 * @since 1.5
294 */
295 public static native double cbrt(double a);
296
297 /**
298 * Computes the remainder operation on two arguments as prescribed
299 * by the IEEE 754 standard.
300 * The remainder value is mathematically equal to
301 * <code>f1 - f2</code> × <i>n</i>,
302 * where <i>n</i> is the mathematical integer closest to the exact
303 * mathematical value of the quotient {@code f1/f2}, and if two
304 * mathematical integers are equally close to {@code f1/f2},
305 * then <i>n</i> is the integer that is even. If the remainder is
306 * zero, its sign is the same as the sign of the first argument.
307 * Special cases:
308 * <ul><li>If either argument is NaN, or the first argument is infinite,
309 * or the second argument is positive zero or negative zero, then the
310 * result is NaN.
311 * <li>If the first argument is finite and the second argument is
312 * infinite, then the result is the same as the first argument.</ul>
313 *
314 * @param f1 the dividend.
315 * @param f2 the divisor.
316 * @return the remainder when {@code f1} is divided by
317 * {@code f2}.
318 */
319 public static native double IEEEremainder(double f1, double f2);
320
321 /**
322 * Returns the smallest (closest to negative infinity)
323 * {@code double} value that is greater than or equal to the
324 * argument and is equal to a mathematical integer. Special cases:
325 * <ul><li>If the argument value is already equal to a
326 * mathematical integer, then the result is the same as the
327 * argument. <li>If the argument is NaN or an infinity or
328 * positive zero or negative zero, then the result is the same as
329 * the argument. <li>If the argument value is less than zero but
330 * greater than -1.0, then the result is negative zero.</ul> Note
331 * that the value of {@code StrictMath.ceil(x)} is exactly the
332 * value of {@code -StrictMath.floor(-x)}.
333 *
334 * @param a a value.
335 * @return the smallest (closest to negative infinity)
336 * floating-point value that is greater than or equal to
337 * the argument and is equal to a mathematical integer.
338 */
339 public static double ceil(double a) {
340 return floorOrCeil(a, -0.0, 1.0, 1.0);
341 }
342
343 /**
344 * Returns the largest (closest to positive infinity)
345 * {@code double} value that is less than or equal to the
346 * argument and is equal to a mathematical integer. Special cases:
347 * <ul><li>If the argument value is already equal to a
348 * mathematical integer, then the result is the same as the
349 * argument. <li>If the argument is NaN or an infinity or
350 * positive zero or negative zero, then the result is the same as
351 * the argument.</ul>
352 *
353 * @param a a value.
354 * @return the largest (closest to positive infinity)
355 * floating-point value that less than or equal to the argument
356 * and is equal to a mathematical integer.
357 */
358 public static double floor(double a) {
359 return floorOrCeil(a, -1.0, 0.0, -1.0);
360 }
361
362 /**
363 * Internal method to share logic between floor and ceil.
364 *
365 * @param a the value to be floored or ceiled
366 * @param negativeBoundary result for values in (-1, 0)
367 * @param positiveBoundary result for values in (0, 1)
368 * @param increment value to add when the argument is non-integral
369 */
370 private static double floorOrCeil(double a,
371 double negativeBoundary,
372 double positiveBoundary,
373 double sign) {
374 int exponent = Math.getExponent(a);
375
376 if (exponent < 0) {
377 /*
378 * Absolute value of argument is less than 1.
379 * floorOrceil(-0.0) => -0.0
380 * floorOrceil(+0.0) => +0.0
381 */
382 return ((a == 0.0) ? a :
383 ( (a < 0.0) ? negativeBoundary : positiveBoundary) );
384 } else if (exponent >= 52) {
385 /*
386 * Infinity, NaN, or a value so large it must be integral.
387 */
388 return a;
389 }
390 // Else the argument is either an integral value already XOR it
391 // has to be rounded to one.
392 assert exponent >= 0 && exponent <= 51;
393
394 long doppel = Double.doubleToRawLongBits(a);
395 long mask = DoubleConsts.SIGNIF_BIT_MASK >> exponent;
396
397 if ( (mask & doppel) == 0L )
398 return a; // integral value
399 else {
400 double result = Double.longBitsToDouble(doppel & (~mask));
401 if (sign*a > 0.0)
402 result = result + sign;
403 return result;
404 }
405 }
406
407 /**
408 * Returns the {@code double} value that is closest in value
409 * to the argument and is equal to a mathematical integer. If two
410 * {@code double} values that are mathematical integers are
411 * equally close to the value of the argument, the result is the
412 * integer value that is even. Special cases:
413 * <ul><li>If the argument value is already equal to a mathematical
414 * integer, then the result is the same as the argument.
415 * <li>If the argument is NaN or an infinity or positive zero or negative
416 * zero, then the result is the same as the argument.</ul>
417 *
418 * @param a a value.
419 * @return the closest floating-point value to {@code a} that is
420 * equal to a mathematical integer.
421 * @author Joseph D. Darcy
422 */
423 public static double rint(double a) {
424 /*
425 * If the absolute value of a is not less than 2^52, it
426 * is either a finite integer (the double format does not have
427 * enough significand bits for a number that large to have any
428 * fractional portion), an infinity, or a NaN. In any of
429 * these cases, rint of the argument is the argument.
430 *
431 * Otherwise, the sum (twoToThe52 + a ) will properly round
432 * away any fractional portion of a since ulp(twoToThe52) ==
433 * 1.0; subtracting out twoToThe52 from this sum will then be
434 * exact and leave the rounded integer portion of a.
435 *
436 * This method does *not* need to be declared strictfp to get
437 * fully reproducible results. Whether or not a method is
438 * declared strictfp can only make a difference in the
439 * returned result if some operation would overflow or
440 * underflow with strictfp semantics. The operation
441 * (twoToThe52 + a ) cannot overflow since large values of a
442 * are screened out; the add cannot underflow since twoToThe52
443 * is too large. The subtraction ((twoToThe52 + a ) -
444 * twoToThe52) will be exact as discussed above and thus
445 * cannot overflow or meaningfully underflow. Finally, the
446 * last multiply in the return statement is by plus or minus
447 * 1.0, which is exact too.
448 */
449 double twoToThe52 = (double)(1L << 52); // 2^52
450 double sign = Math.copySign(1.0, a); // preserve sign info
451 a = Math.abs(a);
452
453 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51
454 a = ((twoToThe52 + a ) - twoToThe52);
455 }
456
457 return sign * a; // restore original sign
458 }
459
460 /**
461 * Returns the angle <i>theta</i> from the conversion of rectangular
462 * coordinates ({@code x}, {@code y}) to polar
463 * coordinates (r, <i>theta</i>).
464 * This method computes the phase <i>theta</i> by computing an arc tangent
465 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
466 * cases:
467 * <ul><li>If either argument is NaN, then the result is NaN.
468 * <li>If the first argument is positive zero and the second argument
469 * is positive, or the first argument is positive and finite and the
470 * second argument is positive infinity, then the result is positive
471 * zero.
472 * <li>If the first argument is negative zero and the second argument
473 * is positive, or the first argument is negative and finite and the
474 * second argument is positive infinity, then the result is negative zero.
475 * <li>If the first argument is positive zero and the second argument
476 * is negative, or the first argument is positive and finite and the
477 * second argument is negative infinity, then the result is the
478 * {@code double} value closest to <i>pi</i>.
479 * <li>If the first argument is negative zero and the second argument
480 * is negative, or the first argument is negative and finite and the
481 * second argument is negative infinity, then the result is the
482 * {@code double} value closest to -<i>pi</i>.
483 * <li>If the first argument is positive and the second argument is
484 * positive zero or negative zero, or the first argument is positive
485 * infinity and the second argument is finite, then the result is the
486 * {@code double} value closest to <i>pi</i>/2.
487 * <li>If the first argument is negative and the second argument is
488 * positive zero or negative zero, or the first argument is negative
489 * infinity and the second argument is finite, then the result is the
490 * {@code double} value closest to -<i>pi</i>/2.
491 * <li>If both arguments are positive infinity, then the result is the
492 * {@code double} value closest to <i>pi</i>/4.
493 * <li>If the first argument is positive infinity and the second argument
494 * is negative infinity, then the result is the {@code double}
495 * value closest to 3*<i>pi</i>/4.
496 * <li>If the first argument is negative infinity and the second argument
497 * is positive infinity, then the result is the {@code double} value
498 * closest to -<i>pi</i>/4.
499 * <li>If both arguments are negative infinity, then the result is the
500 * {@code double} value closest to -3*<i>pi</i>/4.</ul>
501 *
502 * @param y the ordinate coordinate
503 * @param x the abscissa coordinate
504 * @return the <i>theta</i> component of the point
505 * (<i>r</i>, <i>theta</i>)
506 * in polar coordinates that corresponds to the point
507 * (<i>x</i>, <i>y</i>) in Cartesian coordinates.
508 */
509 public static native double atan2(double y, double x);
510
511
512 /**
513 * Returns the value of the first argument raised to the power of the
514 * second argument. Special cases:
515 *
516 * <ul><li>If the second argument is positive or negative zero, then the
517 * result is 1.0.
518 * <li>If the second argument is 1.0, then the result is the same as the
519 * first argument.
520 * <li>If the second argument is NaN, then the result is NaN.
521 * <li>If the first argument is NaN and the second argument is nonzero,
522 * then the result is NaN.
523 *
524 * <li>If
525 * <ul>
526 * <li>the absolute value of the first argument is greater than 1
527 * and the second argument is positive infinity, or
528 * <li>the absolute value of the first argument is less than 1 and
529 * the second argument is negative infinity,
530 * </ul>
531 * then the result is positive infinity.
532 *
533 * <li>If
534 * <ul>
535 * <li>the absolute value of the first argument is greater than 1 and
536 * the second argument is negative infinity, or
537 * <li>the absolute value of the
538 * first argument is less than 1 and the second argument is positive
539 * infinity,
540 * </ul>
541 * then the result is positive zero.
542 *
543 * <li>If the absolute value of the first argument equals 1 and the
544 * second argument is infinite, then the result is NaN.
545 *
546 * <li>If
547 * <ul>
548 * <li>the first argument is positive zero and the second argument
549 * is greater than zero, or
550 * <li>the first argument is positive infinity and the second
551 * argument is less than zero,
552 * </ul>
553 * then the result is positive zero.
554 *
555 * <li>If
556 * <ul>
557 * <li>the first argument is positive zero and the second argument
558 * is less than zero, or
559 * <li>the first argument is positive infinity and the second
560 * argument is greater than zero,
561 * </ul>
562 * then the result is positive infinity.
563 *
564 * <li>If
565 * <ul>
566 * <li>the first argument is negative zero and the second argument
567 * is greater than zero but not a finite odd integer, or
568 * <li>the first argument is negative infinity and the second
569 * argument is less than zero but not a finite odd integer,
570 * </ul>
571 * then the result is positive zero.
572 *
573 * <li>If
574 * <ul>
575 * <li>the first argument is negative zero and the second argument
576 * is a positive finite odd integer, or
577 * <li>the first argument is negative infinity and the second
578 * argument is a negative finite odd integer,
579 * </ul>
580 * then the result is negative zero.
581 *
582 * <li>If
583 * <ul>
584 * <li>the first argument is negative zero and the second argument
585 * is less than zero but not a finite odd integer, or
586 * <li>the first argument is negative infinity and the second
587 * argument is greater than zero but not a finite odd integer,
588 * </ul>
589 * then the result is positive infinity.
590 *
591 * <li>If
592 * <ul>
593 * <li>the first argument is negative zero and the second argument
594 * is a negative finite odd integer, or
595 * <li>the first argument is negative infinity and the second
596 * argument is a positive finite odd integer,
597 * </ul>
598 * then the result is negative infinity.
599 *
600 * <li>If the first argument is finite and less than zero
601 * <ul>
602 * <li> if the second argument is a finite even integer, the
603 * result is equal to the result of raising the absolute value of
604 * the first argument to the power of the second argument
605 *
606 * <li>if the second argument is a finite odd integer, the result
607 * is equal to the negative of the result of raising the absolute
608 * value of the first argument to the power of the second
609 * argument
610 *
611 * <li>if the second argument is finite and not an integer, then
612 * the result is NaN.
613 * </ul>
614 *
615 * <li>If both arguments are integers, then the result is exactly equal
616 * to the mathematical result of raising the first argument to the power
617 * of the second argument if that result can in fact be represented
618 * exactly as a {@code double} value.</ul>
619 *
620 * <p>(In the foregoing descriptions, a floating-point value is
621 * considered to be an integer if and only if it is finite and a
622 * fixed point of the method {@link #ceil ceil} or,
623 * equivalently, a fixed point of the method {@link #floor
624 * floor}. A value is a fixed point of a one-argument
625 * method if and only if the result of applying the method to the
626 * value is equal to the value.)
627 *
628 * @param a base.
629 * @param b the exponent.
630 * @return the value {@code a}<sup>{@code b}</sup>.
631 */
632 public static native double pow(double a, double b);
633
634 /**
635 * Returns the closest {@code int} to the argument, with ties
636 * rounding up.
637 *
638 * <p>Special cases:
639 * <ul><li>If the argument is NaN, the result is 0.
640 * <li>If the argument is negative infinity or any value less than or
641 * equal to the value of {@code Integer.MIN_VALUE}, the result is
642 * equal to the value of {@code Integer.MIN_VALUE}.
643 * <li>If the argument is positive infinity or any value greater than or
644 * equal to the value of {@code Integer.MAX_VALUE}, the result is
645 * equal to the value of {@code Integer.MAX_VALUE}.</ul>
646 *
647 * @param a a floating-point value to be rounded to an integer.
648 * @return the value of the argument rounded to the nearest
649 * {@code int} value.
650 * @see java.lang.Integer#MAX_VALUE
651 * @see java.lang.Integer#MIN_VALUE
652 */
653 public static int round(float a) {
654 return Math.round(a);
655 }
656
657 /**
658 * Returns the closest {@code long} to the argument, with ties
659 * rounding up.
660 *
661 * <p>Special cases:
662 * <ul><li>If the argument is NaN, the result is 0.
663 * <li>If the argument is negative infinity or any value less than or
664 * equal to the value of {@code Long.MIN_VALUE}, the result is
665 * equal to the value of {@code Long.MIN_VALUE}.
666 * <li>If the argument is positive infinity or any value greater than or
667 * equal to the value of {@code Long.MAX_VALUE}, the result is
668 * equal to the value of {@code Long.MAX_VALUE}.</ul>
669 *
670 * @param a a floating-point value to be rounded to a
671 * {@code long}.
672 * @return the value of the argument rounded to the nearest
673 * {@code long} value.
674 * @see java.lang.Long#MAX_VALUE
675 * @see java.lang.Long#MIN_VALUE
676 */
677 public static long round(double a) {
678 return Math.round(a);
679 }
680
681 private static final class RandomNumberGeneratorHolder {
682 static final Random randomNumberGenerator = new Random();
683 }
684
685 /**
686 * Returns a {@code double} value with a positive sign, greater
687 * than or equal to {@code 0.0} and less than {@code 1.0}.
688 * Returned values are chosen pseudorandomly with (approximately)
689 * uniform distribution from that range.
690 *
691 * <p>When this method is first called, it creates a single new
692 * pseudorandom-number generator, exactly as if by the expression
693 *
694 * <blockquote>{@code new java.util.Random()}</blockquote>
695 *
696 * This new pseudorandom-number generator is used thereafter for
697 * all calls to this method and is used nowhere else.
698 *
699 * <p>This method is properly synchronized to allow correct use by
700 * more than one thread. However, if many threads need to generate
701 * pseudorandom numbers at a great rate, it may reduce contention
702 * for each thread to have its own pseudorandom-number generator.
703 *
704 * @return a pseudorandom {@code double} greater than or equal
705 * to {@code 0.0} and less than {@code 1.0}.
706 * @see Random#nextDouble()
707 */
708 public static double random() {
709 return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble();
710 }
711
712 /**
713 * Returns the sum of its arguments,
714 * throwing an exception if the result overflows an {@code int}.
715 *
716 * @param x the first value
717 * @param y the second value
718 * @return the result
719 * @throws ArithmeticException if the result overflows an int
720 * @see Math#addExact(int,int)
721 * @since 1.8
722 */
723 public static int addExact(int x, int y) {
724 return Math.addExact(x, y);
725 }
726
727 /**
728 * Returns the sum of its arguments,
729 * throwing an exception if the result overflows a {@code long}.
730 *
731 * @param x the first value
732 * @param y the second value
733 * @return the result
734 * @throws ArithmeticException if the result overflows a long
735 * @see Math#addExact(long,long)
736 * @since 1.8
737 */
738 public static long addExact(long x, long y) {
739 return Math.addExact(x, y);
740 }
741
742 /**
743 * Returns the difference of the arguments,
744 * throwing an exception if the result overflows an {@code int}.
745 *
746 * @param x the first value
747 * @param y the second value to subtract from the first
748 * @return the result
749 * @throws ArithmeticException if the result overflows an int
750 * @see Math#subtractExact(int,int)
751 * @since 1.8
752 */
753 public static int subtractExact(int x, int y) {
754 return Math.subtractExact(x, y);
755 }
756
757 /**
758 * Returns the difference of the arguments,
759 * throwing an exception if the result overflows a {@code long}.
760 *
761 * @param x the first value
762 * @param y the second value to subtract from the first
763 * @return the result
764 * @throws ArithmeticException if the result overflows a long
765 * @see Math#subtractExact(long,long)
766 * @since 1.8
767 */
768 public static long subtractExact(long x, long y) {
769 return Math.subtractExact(x, y);
770 }
771
772 /**
773 * Returns the product of the arguments,
774 * throwing an exception if the result overflows an {@code int}.
775 *
776 * @param x the first value
777 * @param y the second value
778 * @return the result
779 * @throws ArithmeticException if the result overflows an int
780 * @see Math#multiplyExact(int,int)
781 * @since 1.8
782 */
783 public static int multiplyExact(int x, int y) {
784 return Math.multiplyExact(x, y);
785 }
786
787 /**
788 * Returns the product of the arguments,
789 * throwing an exception if the result overflows a {@code long}.
790 *
791 * @param x the first value
792 * @param y the second value
793 * @return the result
794 * @throws ArithmeticException if the result overflows a long
795 * @see Math#multiplyExact(long,long)
796 * @since 1.8
797 */
798 public static long multiplyExact(long x, long y) {
799 return Math.multiplyExact(x, y);
800 }
801
802 /**
803 * Returns the value of the {@code long} argument;
804 * throwing an exception if the value overflows an {@code int}.
805 *
806 * @param value the long value
807 * @return the argument as an int
808 * @throws ArithmeticException if the {@code argument} overflows an int
809 * @see Math#toIntExact(long)
810 * @since 1.8
811 */
812 public static int toIntExact(long value) {
813 return Math.toIntExact(value);
814 }
815
816 /**
817 * Returns the largest (closest to positive infinity)
818 * {@code int} value that is less than or equal to the algebraic quotient.
819 * There is one special case, if the dividend is the
820 * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1},
821 * then integer overflow occurs and
822 * the result is equal to the {@code Integer.MIN_VALUE}.
823 * <p>
824 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
825 * a comparison to the integer division {@code /} operator.
826 *
827 * @param x the dividend
828 * @param y the divisor
829 * @return the largest (closest to positive infinity)
830 * {@code int} value that is less than or equal to the algebraic quotient.
831 * @throws ArithmeticException if the divisor {@code y} is zero
832 * @see Math#floorDiv(int, int)
833 * @see Math#floor(double)
834 * @since 1.8
835 */
836 public static int floorDiv(int x, int y) {
837 return Math.floorDiv(x, y);
838 }
839
840 /**
841 * Returns the largest (closest to positive infinity)
842 * {@code long} value that is less than or equal to the algebraic quotient.
843 * There is one special case, if the dividend is the
844 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1},
845 * then integer overflow occurs and
846 * the result is equal to the {@code Long.MIN_VALUE}.
847 * <p>
848 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
849 * a comparison to the integer division {@code /} operator.
850 *
851 * @param x the dividend
852 * @param y the divisor
853 * @return the largest (closest to positive infinity)
854 * {@code long} value that is less than or equal to the algebraic quotient.
855 * @throws ArithmeticException if the divisor {@code y} is zero
856 * @see Math#floorDiv(long, long)
857 * @see Math#floor(double)
858 * @since 1.8
859 */
860 public static long floorDiv(long x, long y) {
861 return Math.floorDiv(x, y);
862 }
863
864 /**
865 * Returns the floor modulus of the {@code int} arguments.
866 * <p>
867 * The floor modulus is {@code x - (floorDiv(x, y) * y)},
868 * has the same sign as the divisor {@code y}, and
869 * is in the range of {@code -abs(y) < r < +abs(y)}.
870 * <p>
871 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
872 * <ul>
873 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
874 * </ul>
875 * <p>
876 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
877 * a comparison to the {@code %} operator.
878 *
879 * @param x the dividend
880 * @param y the divisor
881 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
882 * @throws ArithmeticException if the divisor {@code y} is zero
883 * @see Math#floorMod(int, int)
884 * @see StrictMath#floorDiv(int, int)
885 * @since 1.8
886 */
887 public static int floorMod(int x, int y) {
888 return Math.floorMod(x , y);
889 }
890 /**
891 * Returns the floor modulus of the {@code long} arguments.
892 * <p>
893 * The floor modulus is {@code x - (floorDiv(x, y) * y)},
894 * has the same sign as the divisor {@code y}, and
895 * is in the range of {@code -abs(y) < r < +abs(y)}.
896 * <p>
897 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
898 * <ul>
899 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
900 * </ul>
901 * <p>
902 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
903 * a comparison to the {@code %} operator.
904 *
905 * @param x the dividend
906 * @param y the divisor
907 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
908 * @throws ArithmeticException if the divisor {@code y} is zero
909 * @see Math#floorMod(long, long)
910 * @see StrictMath#floorDiv(long, long)
911 * @since 1.8
912 */
913 public static long floorMod(long x, long y) {
914 return Math.floorMod(x, y);
915 }
916
917 /**
918 * Returns the absolute value of an {@code int} value.
919 * If the argument is not negative, the argument is returned.
920 * If the argument is negative, the negation of the argument is returned.
921 *
922 * <p>Note that if the argument is equal to the value of
923 * {@link Integer#MIN_VALUE}, the most negative representable
924 * {@code int} value, the result is that same value, which is
925 * negative.
926 *
927 * @param a the argument whose absolute value is to be determined.
928 * @return the absolute value of the argument.
929 */
930 public static int abs(int a) {
931 return Math.abs(a);
932 }
933
934 /**
935 * Returns the absolute value of a {@code long} value.
936 * If the argument is not negative, the argument is returned.
937 * If the argument is negative, the negation of the argument is returned.
938 *
939 * <p>Note that if the argument is equal to the value of
940 * {@link Long#MIN_VALUE}, the most negative representable
941 * {@code long} value, the result is that same value, which
942 * is negative.
943 *
944 * @param a the argument whose absolute value is to be determined.
945 * @return the absolute value of the argument.
946 */
947 public static long abs(long a) {
948 return Math.abs(a);
949 }
950
951 /**
952 * Returns the absolute value of a {@code float} value.
953 * If the argument is not negative, the argument is returned.
954 * If the argument is negative, the negation of the argument is returned.
955 * Special cases:
956 * <ul><li>If the argument is positive zero or negative zero, the
957 * result is positive zero.
958 * <li>If the argument is infinite, the result is positive infinity.
959 * <li>If the argument is NaN, the result is NaN.</ul>
960 * In other words, the result is the same as the value of the expression:
961 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))}
962 *
963 * @param a the argument whose absolute value is to be determined
964 * @return the absolute value of the argument.
965 */
966 public static float abs(float a) {
967 return Math.abs(a);
968 }
969
970 /**
971 * Returns the absolute value of a {@code double} value.
972 * If the argument is not negative, the argument is returned.
973 * If the argument is negative, the negation of the argument is returned.
974 * Special cases:
975 * <ul><li>If the argument is positive zero or negative zero, the result
976 * is positive zero.
977 * <li>If the argument is infinite, the result is positive infinity.
978 * <li>If the argument is NaN, the result is NaN.</ul>
979 * In other words, the result is the same as the value of the expression:
980 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
981 *
982 * @param a the argument whose absolute value is to be determined
983 * @return the absolute value of the argument.
984 */
985 public static double abs(double a) {
986 return Math.abs(a);
987 }
988
989 /**
990 * Returns the greater of two {@code int} values. That is, the
991 * result is the argument closer to the value of
992 * {@link Integer#MAX_VALUE}. If the arguments have the same value,
993 * the result is that same value.
994 *
995 * @param a an argument.
996 * @param b another argument.
997 * @return the larger of {@code a} and {@code b}.
998 */
999 public static int max(int a, int b) {
1000 return Math.max(a, b);
1001 }
1002
1003 /**
1004 * Returns the greater of two {@code long} values. That is, the
1005 * result is the argument closer to the value of
1006 * {@link Long#MAX_VALUE}. If the arguments have the same value,
1007 * the result is that same value.
1008 *
1009 * @param a an argument.
1010 * @param b another argument.
1011 * @return the larger of {@code a} and {@code b}.
1012 */
1013 public static long max(long a, long b) {
1014 return Math.max(a, b);
1015 }
1016
1017 /**
1018 * Returns the greater of two {@code float} values. That is,
1019 * the result is the argument closer to positive infinity. If the
1020 * arguments have the same value, the result is that same
1021 * value. If either value is NaN, then the result is NaN. Unlike
1022 * the numerical comparison operators, this method considers
1023 * negative zero to be strictly smaller than positive zero. If one
1024 * argument is positive zero and the other negative zero, the
1025 * result is positive zero.
1026 *
1027 * @param a an argument.
1028 * @param b another argument.
1029 * @return the larger of {@code a} and {@code b}.
1030 */
1031 public static float max(float a, float b) {
1032 return Math.max(a, b);
1033 }
1034
1035 /**
1036 * Returns the greater of two {@code double} values. That
1037 * is, the result is the argument closer to positive infinity. If
1038 * the arguments have the same value, the result is that same
1039 * value. If either value is NaN, then the result is NaN. Unlike
1040 * the numerical comparison operators, this method considers
1041 * negative zero to be strictly smaller than positive zero. If one
1042 * argument is positive zero and the other negative zero, the
1043 * result is positive zero.
1044 *
1045 * @param a an argument.
1046 * @param b another argument.
1047 * @return the larger of {@code a} and {@code b}.
1048 */
1049 public static double max(double a, double b) {
1050 return Math.max(a, b);
1051 }
1052
1053 /**
1054 * Returns the smaller of two {@code int} values. That is,
1055 * the result the argument closer to the value of
1056 * {@link Integer#MIN_VALUE}. If the arguments have the same
1057 * value, the result is that same value.
1058 *
1059 * @param a an argument.
1060 * @param b another argument.
1061 * @return the smaller of {@code a} and {@code b}.
1062 */
1063 public static int min(int a, int b) {
1064 return Math.min(a, b);
1065 }
1066
1067 /**
1068 * Returns the smaller of two {@code long} values. That is,
1069 * the result is the argument closer to the value of
1070 * {@link Long#MIN_VALUE}. If the arguments have the same
1071 * value, the result is that same value.
1072 *
1073 * @param a an argument.
1074 * @param b another argument.
1075 * @return the smaller of {@code a} and {@code b}.
1076 */
1077 public static long min(long a, long b) {
1078 return Math.min(a, b);
1079 }
1080
1081 /**
1082 * Returns the smaller of two {@code float} values. That is,
1083 * the result is the value closer to negative infinity. If the
1084 * arguments have the same value, the result is that same
1085 * value. If either value is NaN, then the result is NaN. Unlike
1086 * the numerical comparison operators, this method considers
1087 * negative zero to be strictly smaller than positive zero. If
1088 * one argument is positive zero and the other is negative zero,
1089 * the result is negative zero.
1090 *
1091 * @param a an argument.
1092 * @param b another argument.
1093 * @return the smaller of {@code a} and {@code b.}
1094 */
1095 public static float min(float a, float b) {
1096 return Math.min(a, b);
1097 }
1098
1099 /**
1100 * Returns the smaller of two {@code double} values. That
1101 * is, the result is the value closer to negative infinity. If the
1102 * arguments have the same value, the result is that same
1103 * value. If either value is NaN, then the result is NaN. Unlike
1104 * the numerical comparison operators, this method considers
1105 * negative zero to be strictly smaller than positive zero. If one
1106 * argument is positive zero and the other is negative zero, the
1107 * result is negative zero.
1108 *
1109 * @param a an argument.
1110 * @param b another argument.
1111 * @return the smaller of {@code a} and {@code b}.
1112 */
1113 public static double min(double a, double b) {
1114 return Math.min(a, b);
1115 }
1116
1117 /**
1118 * Returns the size of an ulp of the argument. An ulp, unit in
1119 * the last place, of a {@code double} value is the positive
1120 * distance between this floating-point value and the {@code
1121 * double} value next larger in magnitude. Note that for non-NaN
1122 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1123 *
1124 * <p>Special Cases:
1125 * <ul>
1126 * <li> If the argument is NaN, then the result is NaN.
1127 * <li> If the argument is positive or negative infinity, then the
1128 * result is positive infinity.
1129 * <li> If the argument is positive or negative zero, then the result is
1130 * {@code Double.MIN_VALUE}.
1131 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
1132 * the result is equal to 2<sup>971</sup>.
1133 * </ul>
1134 *
1135 * @param d the floating-point value whose ulp is to be returned
1136 * @return the size of an ulp of the argument
1137 * @author Joseph D. Darcy
1138 * @since 1.5
1139 */
1140 public static double ulp(double d) {
1141 return Math.ulp(d);
1142 }
1143
1144 /**
1145 * Returns the size of an ulp of the argument. An ulp, unit in
1146 * the last place, of a {@code float} value is the positive
1147 * distance between this floating-point value and the {@code
1148 * float} value next larger in magnitude. Note that for non-NaN
1149 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1150 *
1151 * <p>Special Cases:
1152 * <ul>
1153 * <li> If the argument is NaN, then the result is NaN.
1154 * <li> If the argument is positive or negative infinity, then the
1155 * result is positive infinity.
1156 * <li> If the argument is positive or negative zero, then the result is
1157 * {@code Float.MIN_VALUE}.
1158 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
1159 * the result is equal to 2<sup>104</sup>.
1160 * </ul>
1161 *
1162 * @param f the floating-point value whose ulp is to be returned
1163 * @return the size of an ulp of the argument
1164 * @author Joseph D. Darcy
1165 * @since 1.5
1166 */
1167 public static float ulp(float f) {
1168 return Math.ulp(f);
1169 }
1170
1171 /**
1172 * Returns the signum function of the argument; zero if the argument
1173 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
1174 * argument is less than zero.
1175 *
1176 * <p>Special Cases:
1177 * <ul>
1178 * <li> If the argument is NaN, then the result is NaN.
1179 * <li> If the argument is positive zero or negative zero, then the
1180 * result is the same as the argument.
1181 * </ul>
1182 *
1183 * @param d the floating-point value whose signum is to be returned
1184 * @return the signum function of the argument
1185 * @author Joseph D. Darcy
1186 * @since 1.5
1187 */
1188 public static double signum(double d) {
1189 return Math.signum(d);
1190 }
1191
1192 /**
1193 * Returns the signum function of the argument; zero if the argument
1194 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
1195 * argument is less than zero.
1196 *
1197 * <p>Special Cases:
1198 * <ul>
1199 * <li> If the argument is NaN, then the result is NaN.
1200 * <li> If the argument is positive zero or negative zero, then the
1201 * result is the same as the argument.
1202 * </ul>
1203 *
1204 * @param f the floating-point value whose signum is to be returned
1205 * @return the signum function of the argument
1206 * @author Joseph D. Darcy
1207 * @since 1.5
1208 */
1209 public static float signum(float f) {
1210 return Math.signum(f);
1211 }
1212
1213 /**
1214 * Returns the hyperbolic sine of a {@code double} value.
1215 * The hyperbolic sine of <i>x</i> is defined to be
1216 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
1217 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1218 *
1219 * <p>Special cases:
1220 * <ul>
1221 *
1222 * <li>If the argument is NaN, then the result is NaN.
1223 *
1224 * <li>If the argument is infinite, then the result is an infinity
1225 * with the same sign as the argument.
1226 *
1227 * <li>If the argument is zero, then the result is a zero with the
1228 * same sign as the argument.
1229 *
1230 * </ul>
1231 *
1232 * @param x The number whose hyperbolic sine is to be returned.
1233 * @return The hyperbolic sine of {@code x}.
1234 * @since 1.5
1235 */
1236 public static native double sinh(double x);
1237
1238 /**
1239 * Returns the hyperbolic cosine of a {@code double} value.
1240 * The hyperbolic cosine of <i>x</i> is defined to be
1241 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
1242 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1243 *
1244 * <p>Special cases:
1245 * <ul>
1246 *
1247 * <li>If the argument is NaN, then the result is NaN.
1248 *
1249 * <li>If the argument is infinite, then the result is positive
1250 * infinity.
1251 *
1252 * <li>If the argument is zero, then the result is {@code 1.0}.
1253 *
1254 * </ul>
1255 *
1256 * @param x The number whose hyperbolic cosine is to be returned.
1257 * @return The hyperbolic cosine of {@code x}.
1258 * @since 1.5
1259 */
1260 public static native double cosh(double x);
1261
1262 /**
1263 * Returns the hyperbolic tangent of a {@code double} value.
1264 * The hyperbolic tangent of <i>x</i> is defined to be
1265 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
1266 * in other words, {@linkplain Math#sinh
1267 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
1268 * that the absolute value of the exact tanh is always less than
1269 * 1.
1270 *
1271 * <p>Special cases:
1272 * <ul>
1273 *
1274 * <li>If the argument is NaN, then the result is NaN.
1275 *
1276 * <li>If the argument is zero, then the result is a zero with the
1277 * same sign as the argument.
1278 *
1279 * <li>If the argument is positive infinity, then the result is
1280 * {@code +1.0}.
1281 *
1282 * <li>If the argument is negative infinity, then the result is
1283 * {@code -1.0}.
1284 *
1285 * </ul>
1286 *
1287 * @param x The number whose hyperbolic tangent is to be returned.
1288 * @return The hyperbolic tangent of {@code x}.
1289 * @since 1.5
1290 */
1291 public static native double tanh(double x);
1292
1293 /**
1294 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1295 * without intermediate overflow or underflow.
1296 *
1297 * <p>Special cases:
1298 * <ul>
1299 *
1300 * <li> If either argument is infinite, then the result
1301 * is positive infinity.
1302 *
1303 * <li> If either argument is NaN and neither argument is infinite,
1304 * then the result is NaN.
1305 *
1306 * </ul>
1307 *
1308 * @param x a value
1309 * @param y a value
1310 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1311 * without intermediate overflow or underflow
1312 * @since 1.5
1313 */
1314 public static native double hypot(double x, double y);
1315
1316 /**
1317 * Returns <i>e</i><sup>x</sup> -1. Note that for values of
1318 * <i>x</i> near 0, the exact sum of
1319 * {@code expm1(x)} + 1 is much closer to the true
1320 * result of <i>e</i><sup>x</sup> than {@code exp(x)}.
1321 *
1322 * <p>Special cases:
1323 * <ul>
1324 * <li>If the argument is NaN, the result is NaN.
1325 *
1326 * <li>If the argument is positive infinity, then the result is
1327 * positive infinity.
1328 *
1329 * <li>If the argument is negative infinity, then the result is
1330 * -1.0.
1331 *
1332 * <li>If the argument is zero, then the result is a zero with the
1333 * same sign as the argument.
1334 *
1335 * </ul>
1336 *
1337 * @param x the exponent to raise <i>e</i> to in the computation of
1338 * <i>e</i><sup>{@code x}</sup> -1.
1339 * @return the value <i>e</i><sup>{@code x}</sup> - 1.
1340 * @since 1.5
1341 */
1342 public static native double expm1(double x);
1343
1344 /**
1345 * Returns the natural logarithm of the sum of the argument and 1.
1346 * Note that for small values {@code x}, the result of
1347 * {@code log1p(x)} is much closer to the true result of ln(1
1348 * + {@code x}) than the floating-point evaluation of
1349 * {@code log(1.0+x)}.
1350 *
1351 * <p>Special cases:
1352 * <ul>
1353 *
1354 * <li>If the argument is NaN or less than -1, then the result is
1355 * NaN.
1356 *
1357 * <li>If the argument is positive infinity, then the result is
1358 * positive infinity.
1359 *
1360 * <li>If the argument is negative one, then the result is
1361 * negative infinity.
1362 *
1363 * <li>If the argument is zero, then the result is a zero with the
1364 * same sign as the argument.
1365 *
1366 * </ul>
1367 *
1368 * @param x a value
1369 * @return the value ln({@code x} + 1), the natural
1370 * log of {@code x} + 1
1371 * @since 1.5
1372 */
1373 public static native double log1p(double x);
1374
1375 /**
1376 * Returns the first floating-point argument with the sign of the
1377 * second floating-point argument. For this method, a NaN
1378 * {@code sign} argument is always treated as if it were
1379 * positive.
1380 *
1381 * @param magnitude the parameter providing the magnitude of the result
1382 * @param sign the parameter providing the sign of the result
1383 * @return a value with the magnitude of {@code magnitude}
1384 * and the sign of {@code sign}.
1385 * @since 1.6
1386 */
1387 public static double copySign(double magnitude, double sign) {
1388 return Math.copySign(magnitude, (Double.isNaN(sign)?1.0d:sign));
1389 }
1390
1391 /**
1392 * Returns the first floating-point argument with the sign of the
1393 * second floating-point argument. For this method, a NaN
1394 * {@code sign} argument is always treated as if it were
1395 * positive.
1396 *
1397 * @param magnitude the parameter providing the magnitude of the result
1398 * @param sign the parameter providing the sign of the result
1399 * @return a value with the magnitude of {@code magnitude}
1400 * and the sign of {@code sign}.
1401 * @since 1.6
1402 */
1403 public static float copySign(float magnitude, float sign) {
1404 return Math.copySign(magnitude, (Float.isNaN(sign)?1.0f:sign));
1405 }
1406 /**
1407 * Returns the unbiased exponent used in the representation of a
1408 * {@code float}. Special cases:
1409 *
1410 * <ul>
1411 * <li>If the argument is NaN or infinite, then the result is
1412 * {@link Float#MAX_EXPONENT} + 1.
1413 * <li>If the argument is zero or subnormal, then the result is
1414 * {@link Float#MIN_EXPONENT} -1.
1415 * </ul>
1416 * @param f a {@code float} value
1417 * @return the unbiased exponent of the argument
1418 * @since 1.6
1419 */
1420 public static int getExponent(float f) {
1421 return Math.getExponent(f);
1422 }
1423
1424 /**
1425 * Returns the unbiased exponent used in the representation of a
1426 * {@code double}. Special cases:
1427 *
1428 * <ul>
1429 * <li>If the argument is NaN or infinite, then the result is
1430 * {@link Double#MAX_EXPONENT} + 1.
1431 * <li>If the argument is zero or subnormal, then the result is
1432 * {@link Double#MIN_EXPONENT} -1.
1433 * </ul>
1434 * @param d a {@code double} value
1435 * @return the unbiased exponent of the argument
1436 * @since 1.6
1437 */
1438 public static int getExponent(double d) {
1439 return Math.getExponent(d);
1440 }
1441
1442 /**
1443 * Returns the floating-point number adjacent to the first
1444 * argument in the direction of the second argument. If both
1445 * arguments compare as equal the second argument is returned.
1446 *
1447 * <p>Special cases:
1448 * <ul>
1449 * <li> If either argument is a NaN, then NaN is returned.
1450 *
1451 * <li> If both arguments are signed zeros, {@code direction}
1452 * is returned unchanged (as implied by the requirement of
1453 * returning the second argument if the arguments compare as
1454 * equal).
1455 *
1456 * <li> If {@code start} is
1457 * ±{@link Double#MIN_VALUE} and {@code direction}
1458 * has a value such that the result should have a smaller
1459 * magnitude, then a zero with the same sign as {@code start}
1460 * is returned.
1461 *
1462 * <li> If {@code start} is infinite and
1463 * {@code direction} has a value such that the result should
1464 * have a smaller magnitude, {@link Double#MAX_VALUE} with the
1465 * same sign as {@code start} is returned.
1466 *
1467 * <li> If {@code start} is equal to ±
1468 * {@link Double#MAX_VALUE} and {@code direction} has a
1469 * value such that the result should have a larger magnitude, an
1470 * infinity with same sign as {@code start} is returned.
1471 * </ul>
1472 *
1473 * @param start starting floating-point value
1474 * @param direction value indicating which of
1475 * {@code start}'s neighbors or {@code start} should
1476 * be returned
1477 * @return The floating-point number adjacent to {@code start} in the
1478 * direction of {@code direction}.
1479 * @since 1.6
1480 */
1481 public static double nextAfter(double start, double direction) {
1482 return Math.nextAfter(start, direction);
1483 }
1484
1485 /**
1486 * Returns the floating-point number adjacent to the first
1487 * argument in the direction of the second argument. If both
1488 * arguments compare as equal a value equivalent to the second argument
1489 * is returned.
1490 *
1491 * <p>Special cases:
1492 * <ul>
1493 * <li> If either argument is a NaN, then NaN is returned.
1494 *
1495 * <li> If both arguments are signed zeros, a value equivalent
1496 * to {@code direction} is returned.
1497 *
1498 * <li> If {@code start} is
1499 * ±{@link Float#MIN_VALUE} and {@code direction}
1500 * has a value such that the result should have a smaller
1501 * magnitude, then a zero with the same sign as {@code start}
1502 * is returned.
1503 *
1504 * <li> If {@code start} is infinite and
1505 * {@code direction} has a value such that the result should
1506 * have a smaller magnitude, {@link Float#MAX_VALUE} with the
1507 * same sign as {@code start} is returned.
1508 *
1509 * <li> If {@code start} is equal to ±
1510 * {@link Float#MAX_VALUE} and {@code direction} has a
1511 * value such that the result should have a larger magnitude, an
1512 * infinity with same sign as {@code start} is returned.
1513 * </ul>
1514 *
1515 * @param start starting floating-point value
1516 * @param direction value indicating which of
1517 * {@code start}'s neighbors or {@code start} should
1518 * be returned
1519 * @return The floating-point number adjacent to {@code start} in the
1520 * direction of {@code direction}.
1521 * @since 1.6
1522 */
1523 public static float nextAfter(float start, double direction) {
1524 return Math.nextAfter(start, direction);
1525 }
1526
1527 /**
1528 * Returns the floating-point value adjacent to {@code d} in
1529 * the direction of positive infinity. This method is
1530 * semantically equivalent to {@code nextAfter(d,
1531 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
1532 * implementation may run faster than its equivalent
1533 * {@code nextAfter} call.
1534 *
1535 * <p>Special Cases:
1536 * <ul>
1537 * <li> If the argument is NaN, the result is NaN.
1538 *
1539 * <li> If the argument is positive infinity, the result is
1540 * positive infinity.
1541 *
1542 * <li> If the argument is zero, the result is
1543 * {@link Double#MIN_VALUE}
1544 *
1545 * </ul>
1546 *
1547 * @param d starting floating-point value
1548 * @return The adjacent floating-point value closer to positive
1549 * infinity.
1550 * @since 1.6
1551 */
1552 public static double nextUp(double d) {
1553 return Math.nextUp(d);
1554 }
1555
1556 /**
1557 * Returns the floating-point value adjacent to {@code f} in
1558 * the direction of positive infinity. This method is
1559 * semantically equivalent to {@code nextAfter(f,
1560 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
1561 * implementation may run faster than its equivalent
1562 * {@code nextAfter} call.
1563 *
1564 * <p>Special Cases:
1565 * <ul>
1566 * <li> If the argument is NaN, the result is NaN.
1567 *
1568 * <li> If the argument is positive infinity, the result is
1569 * positive infinity.
1570 *
1571 * <li> If the argument is zero, the result is
1572 * {@link Float#MIN_VALUE}
1573 *
1574 * </ul>
1575 *
1576 * @param f starting floating-point value
1577 * @return The adjacent floating-point value closer to positive
1578 * infinity.
1579 * @since 1.6
1580 */
1581 public static float nextUp(float f) {
1582 return Math.nextUp(f);
1583 }
1584
1585 /**
1586 * Returns the floating-point value adjacent to {@code d} in
1587 * the direction of negative infinity. This method is
1588 * semantically equivalent to {@code nextAfter(d,
1589 * Double.NEGATIVE_INFINITY)}; however, a
1590 * {@code nextDown} implementation may run faster than its
1591 * equivalent {@code nextAfter} call.
1592 *
1593 * <p>Special Cases:
1594 * <ul>
1595 * <li> If the argument is NaN, the result is NaN.
1596 *
1597 * <li> If the argument is negative infinity, the result is
1598 * negative infinity.
1599 *
1600 * <li> If the argument is zero, the result is
1601 * {@code -Double.MIN_VALUE}
1602 *
1603 * </ul>
1604 *
1605 * @param d starting floating-point value
1606 * @return The adjacent floating-point value closer to negative
1607 * infinity.
1608 * @since 1.8
1609 */
1610 public static double nextDown(double d) {
1611 return Math.nextDown(d);
1612 }
1613
1614 /**
1615 * Returns the floating-point value adjacent to {@code f} in
1616 * the direction of negative infinity. This method is
1617 * semantically equivalent to {@code nextAfter(f,
1618 * Float.NEGATIVE_INFINITY)}; however, a
1619 * {@code nextDown} implementation may run faster than its
1620 * equivalent {@code nextAfter} call.
1621 *
1622 * <p>Special Cases:
1623 * <ul>
1624 * <li> If the argument is NaN, the result is NaN.
1625 *
1626 * <li> If the argument is negative infinity, the result is
1627 * negative infinity.
1628 *
1629 * <li> If the argument is zero, the result is
1630 * {@code -Float.MIN_VALUE}
1631 *
1632 * </ul>
1633 *
1634 * @param f starting floating-point value
1635 * @return The adjacent floating-point value closer to negative
1636 * infinity.
1637 * @since 1.8
1638 */
1639 public static float nextDown(float f) {
1640 return Math.nextDown(f);
1641 }
1642
1643 /**
1644 * Returns {@code d} ×
1645 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1646 * by a single correctly rounded floating-point multiply to a
1647 * member of the double value set. See the Java
1648 * Language Specification for a discussion of floating-point
1649 * value sets. If the exponent of the result is between {@link
1650 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
1651 * answer is calculated exactly. If the exponent of the result
1652 * would be larger than {@code Double.MAX_EXPONENT}, an
1653 * infinity is returned. Note that if the result is subnormal,
1654 * precision may be lost; that is, when {@code scalb(x, n)}
1655 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1656 * <i>x</i>. When the result is non-NaN, the result has the same
1657 * sign as {@code d}.
1658 *
1659 * <p>Special cases:
1660 * <ul>
1661 * <li> If the first argument is NaN, NaN is returned.
1662 * <li> If the first argument is infinite, then an infinity of the
1663 * same sign is returned.
1664 * <li> If the first argument is zero, then a zero of the same
1665 * sign is returned.
1666 * </ul>
1667 *
1668 * @param d number to be scaled by a power of two.
1669 * @param scaleFactor power of 2 used to scale {@code d}
1670 * @return {@code d} × 2<sup>{@code scaleFactor}</sup>
1671 * @since 1.6
1672 */
1673 public static double scalb(double d, int scaleFactor) {
1674 return Math.scalb(d, scaleFactor);
1675 }
1676
1677 /**
1678 * Returns {@code f} ×
1679 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1680 * by a single correctly rounded floating-point multiply to a
1681 * member of the float value set. See the Java
1682 * Language Specification for a discussion of floating-point
1683 * value sets. If the exponent of the result is between {@link
1684 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
1685 * answer is calculated exactly. If the exponent of the result
1686 * would be larger than {@code Float.MAX_EXPONENT}, an
1687 * infinity is returned. Note that if the result is subnormal,
1688 * precision may be lost; that is, when {@code scalb(x, n)}
1689 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1690 * <i>x</i>. When the result is non-NaN, the result has the same
1691 * sign as {@code f}.
1692 *
1693 * <p>Special cases:
1694 * <ul>
1695 * <li> If the first argument is NaN, NaN is returned.
1696 * <li> If the first argument is infinite, then an infinity of the
1697 * same sign is returned.
1698 * <li> If the first argument is zero, then a zero of the same
1699 * sign is returned.
1700 * </ul>
1701 *
1702 * @param f number to be scaled by a power of two.
1703 * @param scaleFactor power of 2 used to scale {@code f}
1704 * @return {@code f} × 2<sup>{@code scaleFactor}</sup>
1705 * @since 1.6
1706 */
1707 public static float scalb(float f, int scaleFactor) {
1708 return Math.scalb(f, scaleFactor);
1709 }
1710 }