1 /*
2 * Copyright (c) 1999, 2011, 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 * @author unascribed
60 * @author Joseph D. Darcy
61 * @since 1.3
62 */
63
64 public final class StrictMath {
65
66 /**
67 * Don't let anyone instantiate this class.
68 */
69 private StrictMath() {}
70
71 /**
72 * The {@code double} value that is closer than any other to
73 * <i>e</i>, the base of the natural logarithms.
74 */
75 public static final double E = 2.7182818284590452354;
76
77 /**
78 * The {@code double} value that is closer than any other to
79 * <i>pi</i>, the ratio of the circumference of a circle to its
80 * diameter.
81 */
82 public static final double PI = 3.14159265358979323846;
83
84 /**
85 * Returns the trigonometric sine of an angle. Special cases:
86 * <ul><li>If the argument is NaN or an infinity, then the
87 * result is NaN.
88 * <li>If the argument is zero, then the result is a zero with the
89 * same sign as the argument.</ul>
90 *
91 * @param a an angle, in radians.
92 * @return the sine of the argument.
93 */
94 public static native double sin(double a);
95
96 /**
97 * Returns the trigonometric cosine of an angle. Special cases:
98 * <ul><li>If the argument is NaN or an infinity, then the
99 * result is NaN.</ul>
100 *
101 * @param a an angle, in radians.
102 * @return the cosine of the argument.
103 */
104 public static native double cos(double a);
105
106 /**
107 * Returns the trigonometric tangent of an angle. Special cases:
108 * <ul><li>If the argument is NaN or an infinity, then the result
109 * is NaN.
110 * <li>If the argument is zero, then the result is a zero with the
111 * same sign as the argument.</ul>
112 *
113 * @param a an angle, in radians.
114 * @return the tangent of the argument.
115 */
116 public static native double tan(double a);
117
118 /**
119 * Returns the arc sine of a value; the returned angle is in the
120 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
121 * <ul><li>If the argument is NaN or its absolute value is greater
122 * than 1, then the result is NaN.
123 * <li>If the argument is zero, then the result is a zero with the
124 * same sign as the argument.</ul>
125 *
126 * @param a the value whose arc sine is to be returned.
127 * @return the arc sine of the argument.
128 */
129 public static native double asin(double a);
130
131 /**
132 * Returns the arc cosine of a value; the returned angle is in the
133 * range 0.0 through <i>pi</i>. Special case:
134 * <ul><li>If the argument is NaN or its absolute value is greater
135 * than 1, then the result is NaN.</ul>
136 *
137 * @param a the value whose arc cosine is to be returned.
138 * @return the arc cosine of the argument.
139 */
140 public static native double acos(double a);
141
142 /**
143 * Returns the arc tangent of a value; the returned angle is in the
144 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
145 * <ul><li>If the argument is NaN, then the result is NaN.
146 * <li>If the argument is zero, then the result is a zero with the
147 * same sign as the argument.</ul>
148 *
149 * @param a the value whose arc tangent is to be returned.
150 * @return the arc tangent of the argument.
151 */
152 public static native double atan(double a);
153
154 /**
155 * Converts an angle measured in degrees to an approximately
156 * equivalent angle measured in radians. The conversion from
157 * degrees to radians is generally inexact.
158 *
159 * @param angdeg an angle, in degrees
160 * @return the measurement of the angle {@code angdeg}
161 * in radians.
162 */
163 public static strictfp double toRadians(double angdeg) {
164 return angdeg / 180.0 * PI;
165 }
166
167 /**
168 * Converts an angle measured in radians to an approximately
169 * equivalent angle measured in degrees. The conversion from
170 * radians to degrees is generally inexact; users should
171 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly
172 * equal {@code 0.0}.
173 *
174 * @param angrad an angle, in radians
175 * @return the measurement of the angle {@code angrad}
176 * in degrees.
177 */
178 public static strictfp double toDegrees(double angrad) {
179 return angrad * 180.0 / PI;
180 }
181
182 /**
183 * Returns Euler's number <i>e</i> raised to the power of a
184 * {@code double} value. Special cases:
185 * <ul><li>If the argument is NaN, the result is NaN.
186 * <li>If the argument is positive infinity, then the result is
187 * positive infinity.
188 * <li>If the argument is negative infinity, then the result is
189 * positive zero.</ul>
190 *
191 * @param a the exponent to raise <i>e</i> to.
192 * @return the value <i>e</i><sup>{@code a}</sup>,
193 * where <i>e</i> is the base of the natural logarithms.
194 */
195 public static native double exp(double a);
196
197 /**
198 * Returns the natural logarithm (base <i>e</i>) of a {@code double}
199 * value. Special cases:
200 * <ul><li>If the argument is NaN or less than zero, then the result
201 * is NaN.
202 * <li>If the argument is positive infinity, then the result is
203 * positive infinity.
204 * <li>If the argument is positive zero or negative zero, then the
205 * result is negative infinity.</ul>
206 *
207 * @param a a value
208 * @return the value ln {@code a}, the natural logarithm of
209 * {@code a}.
210 */
211 public static native double log(double a);
212
213
214 /**
215 * Returns the base 10 logarithm of a {@code double} value.
216 * Special cases:
217 *
218 * <ul><li>If the argument is NaN or less than zero, then the result
219 * is NaN.
220 * <li>If the argument is positive infinity, then the result is
221 * positive infinity.
222 * <li>If the argument is positive zero or negative zero, then the
223 * result is negative infinity.
224 * <li> If the argument is equal to 10<sup><i>n</i></sup> for
225 * integer <i>n</i>, then the result is <i>n</i>.
226 * </ul>
227 *
228 * @param a a value
229 * @return the base 10 logarithm of {@code a}.
230 * @since 1.5
231 */
232 public static native double log10(double a);
233
234 /**
235 * Returns the correctly rounded positive square root of a
236 * {@code double} value.
237 * Special cases:
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 positive
241 * infinity.
242 * <li>If the argument is positive zero or negative zero, then the
243 * result is the same as the argument.</ul>
244 * Otherwise, the result is the {@code double} value closest to
245 * the true mathematical square root of the argument value.
246 *
247 * @param a a value.
248 * @return the positive square root of {@code a}.
249 */
250 public static native double sqrt(double a);
251
252 /**
253 * Returns the cube root of a {@code double} value. For
254 * positive finite {@code x}, {@code cbrt(-x) ==
255 * -cbrt(x)}; that is, the cube root of a negative value is
256 * the negative of the cube root of that value's magnitude.
257 * Special cases:
258 *
259 * <ul>
260 *
261 * <li>If the argument is NaN, then the result is NaN.
262 *
263 * <li>If the argument is infinite, then the result is an infinity
264 * with the same sign as the argument.
265 *
266 * <li>If the argument is zero, then the result is a zero with the
267 * same sign as the argument.
268 *
269 * </ul>
270 *
271 * @param a a value.
272 * @return the cube root of {@code a}.
273 * @since 1.5
274 */
275 public static native double cbrt(double a);
276
277 /**
278 * Computes the remainder operation on two arguments as prescribed
279 * by the IEEE 754 standard.
280 * The remainder value is mathematically equal to
281 * <code>f1 - f2</code> × <i>n</i>,
282 * where <i>n</i> is the mathematical integer closest to the exact
283 * mathematical value of the quotient {@code f1/f2}, and if two
284 * mathematical integers are equally close to {@code f1/f2},
285 * then <i>n</i> is the integer that is even. If the remainder is
286 * zero, its sign is the same as the sign of the first argument.
287 * Special cases:
288 * <ul><li>If either argument is NaN, or the first argument is infinite,
289 * or the second argument is positive zero or negative zero, then the
290 * result is NaN.
291 * <li>If the first argument is finite and the second argument is
292 * infinite, then the result is the same as the first argument.</ul>
293 *
294 * @param f1 the dividend.
295 * @param f2 the divisor.
296 * @return the remainder when {@code f1} is divided by
297 * {@code f2}.
298 */
299 public static native double IEEEremainder(double f1, double f2);
300
301 /**
302 * Returns the smallest (closest to negative infinity)
303 * {@code double} value that is greater than or equal to the
304 * argument and is equal to a mathematical integer. Special cases:
305 * <ul><li>If the argument value is already equal to a
306 * mathematical integer, then the result is the same as the
307 * argument. <li>If the argument is NaN or an infinity or
308 * positive zero or negative zero, then the result is the same as
309 * the argument. <li>If the argument value is less than zero but
310 * greater than -1.0, then the result is negative zero.</ul> Note
311 * that the value of {@code StrictMath.ceil(x)} is exactly the
312 * value of {@code -StrictMath.floor(-x)}.
313 *
314 * @param a a value.
315 * @return the smallest (closest to negative infinity)
316 * floating-point value that is greater than or equal to
317 * the argument and is equal to a mathematical integer.
318 */
319 public static double ceil(double a) {
320 return floorOrCeil(a, -0.0, 1.0, 1.0);
321 }
322
323 /**
324 * Returns the largest (closest to positive infinity)
325 * {@code double} value that is less than or equal to the
326 * argument and is equal to a mathematical integer. Special cases:
327 * <ul><li>If the argument value is already equal to a
328 * mathematical integer, then the result is the same as the
329 * argument. <li>If the argument is NaN or an infinity or
330 * positive zero or negative zero, then the result is the same as
331 * the argument.</ul>
332 *
333 * @param a a value.
334 * @return the largest (closest to positive infinity)
335 * floating-point value that less than or equal to the argument
336 * and is equal to a mathematical integer.
337 */
338 public static double floor(double a) {
339 return floorOrCeil(a, -1.0, 0.0, -1.0);
340 }
341
342 /**
343 * Internal method to share logic between floor and ceil.
344 *
345 * @param a the value to be floored or ceiled
346 * @param negativeBoundary result for values in (-1, 0)
347 * @param positiveBoundary result for values in (0, 1)
348 * @param increment value to add when the argument is non-integral
349 */
350 private static double floorOrCeil(double a,
351 double negativeBoundary,
352 double positiveBoundary,
353 double sign) {
354 int exponent = Math.getExponent(a);
355
356 if (exponent < 0) {
357 /*
358 * Absolute value of argument is less than 1.
359 * floorOrceil(-0.0) => -0.0
360 * floorOrceil(+0.0) => +0.0
361 */
362 return ((a == 0.0) ? a :
363 ( (a < 0.0) ? negativeBoundary : positiveBoundary) );
364 } else if (exponent >= 52) {
365 /*
366 * Infinity, NaN, or a value so large it must be integral.
367 */
368 return a;
369 }
370 // Else the argument is either an integral value already XOR it
371 // has to be rounded to one.
372 assert exponent >= 0 && exponent <= 51;
373
374 long doppel = Double.doubleToRawLongBits(a);
375 long mask = DoubleConsts.SIGNIF_BIT_MASK >> exponent;
376
377 if ( (mask & doppel) == 0L )
378 return a; // integral value
379 else {
380 double result = Double.longBitsToDouble(doppel & (~mask));
381 if (sign*a > 0.0)
382 result = result + sign;
383 return result;
384 }
385 }
386
387 /**
388 * Returns the {@code double} value that is closest in value
389 * to the argument and is equal to a mathematical integer. If two
390 * {@code double} values that are mathematical integers are
391 * equally close to the value of the argument, the result is the
392 * integer value that is even. Special cases:
393 * <ul><li>If the argument value is already equal to a mathematical
394 * integer, then the result is the same as the argument.
395 * <li>If the argument is NaN or an infinity or positive zero or negative
396 * zero, then the result is the same as the argument.</ul>
397 *
398 * @param a a value.
399 * @return the closest floating-point value to {@code a} that is
400 * equal to a mathematical integer.
401 * @author Joseph D. Darcy
402 */
403 public static double rint(double a) {
404 /*
405 * If the absolute value of a is not less than 2^52, it
406 * is either a finite integer (the double format does not have
407 * enough significand bits for a number that large to have any
408 * fractional portion), an infinity, or a NaN. In any of
409 * these cases, rint of the argument is the argument.
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
451 * zero.
452 * <li>If the first argument is negative zero and the second argument
453 * is positive, or the first argument is negative and finite and the
454 * second argument is positive infinity, then the result is negative zero.
455 * <li>If the first argument is positive zero and the second argument
456 * is negative, or the first argument is positive and finite and the
457 * second argument is negative infinity, then the result is the
458 * {@code double} value closest to <i>pi</i>.
459 * <li>If the first argument is negative zero and the second argument
460 * is negative, or the first argument is negative and finite and the
461 * second argument is negative infinity, then the result is the
462 * {@code double} value closest to -<i>pi</i>.
463 * <li>If the first argument is positive and the second argument is
464 * positive zero or negative zero, or the first argument is positive
465 * infinity and the second argument is finite, then the result is the
466 * {@code double} value closest to <i>pi</i>/2.
467 * <li>If the first argument is negative and the second argument is
468 * positive zero or negative zero, or the first argument is negative
469 * infinity and the second argument is finite, then the result is the
470 * {@code double} value closest to -<i>pi</i>/2.
471 * <li>If both arguments are positive infinity, then the result is the
472 * {@code double} value closest to <i>pi</i>/4.
473 * <li>If the first argument is positive infinity and the second argument
474 * is negative infinity, then the result is the {@code double}
475 * value closest to 3*<i>pi</i>/4.
476 * <li>If the first argument is negative infinity and the second argument
477 * is positive infinity, then the result is the {@code double} value
478 * closest to -<i>pi</i>/4.
479 * <li>If both arguments are negative infinity, then the result is the
480 * {@code double} value closest to -3*<i>pi</i>/4.</ul>
481 *
482 * @param y the ordinate coordinate
483 * @param x the abscissa coordinate
484 * @return the <i>theta</i> component of the point
485 * (<i>r</i>, <i>theta</i>)
486 * in polar coordinates that corresponds to the point
487 * (<i>x</i>, <i>y</i>) in Cartesian coordinates.
488 */
489 public static native double atan2(double y, double x);
490
491
492 /**
493 * Returns the value of the first argument raised to the power of the
494 * second argument. Special cases:
495 *
496 * <ul><li>If the second argument is positive or negative zero, then the
497 * result is 1.0.
498 * <li>If the second argument is 1.0, then the result is the same as the
499 * first argument.
500 * <li>If the second argument is NaN, then the result is NaN.
501 * <li>If the first argument is NaN and the second argument is nonzero,
502 * then the result is NaN.
503 *
504 * <li>If
505 * <ul>
506 * <li>the absolute value of the first argument is greater than 1
507 * and the second argument is positive infinity, or
508 * <li>the absolute value of the first argument is less than 1 and
509 * the second argument is negative infinity,
510 * </ul>
511 * then the result is positive infinity.
512 *
513 * <li>If
514 * <ul>
515 * <li>the absolute value of the first argument is greater than 1 and
516 * the second argument is negative infinity, or
517 * <li>the absolute value of the
518 * first argument is less than 1 and the second argument is positive
519 * infinity,
520 * </ul>
521 * then the result is positive zero.
522 *
523 * <li>If the absolute value of the first argument equals 1 and the
524 * second argument is infinite, then the result is NaN.
525 *
526 * <li>If
527 * <ul>
528 * <li>the first argument is positive zero and the second argument
529 * is greater than zero, or
530 * <li>the first argument is positive infinity and the second
531 * argument is less than zero,
532 * </ul>
533 * then the result is positive zero.
534 *
535 * <li>If
536 * <ul>
537 * <li>the first argument is positive zero and the second argument
538 * is less than zero, or
539 * <li>the first argument is positive infinity and the second
540 * argument is greater than zero,
541 * </ul>
542 * then the result is positive infinity.
543 *
544 * <li>If
545 * <ul>
546 * <li>the first argument is negative zero and the second argument
547 * is greater than zero but not a finite odd integer, or
548 * <li>the first argument is negative infinity and the second
549 * argument is less than zero but not a finite odd integer,
550 * </ul>
551 * then the result is positive zero.
552 *
553 * <li>If
554 * <ul>
555 * <li>the first argument is negative zero and the second argument
556 * is a positive finite odd integer, or
557 * <li>the first argument is negative infinity and the second
558 * argument is a negative finite odd integer,
559 * </ul>
560 * then the result is negative zero.
561 *
562 * <li>If
563 * <ul>
564 * <li>the first argument is negative zero and the second argument
565 * is less than zero but not a finite odd integer, or
566 * <li>the first argument is negative infinity and the second
567 * argument is greater than zero but not a finite odd integer,
568 * </ul>
569 * then the result is positive infinity.
570 *
571 * <li>If
572 * <ul>
573 * <li>the first argument is negative zero and the second argument
574 * is a negative finite odd integer, or
575 * <li>the first argument is negative infinity and the second
576 * argument is a positive finite odd integer,
577 * </ul>
578 * then the result is negative infinity.
579 *
580 * <li>If the first argument is finite and less than zero
581 * <ul>
582 * <li> if the second argument is a finite even integer, the
583 * result is equal to the result of raising the absolute value of
584 * the first argument to the power of the second argument
585 *
586 * <li>if the second argument is a finite odd integer, the result
587 * is equal to the negative of the result of raising the absolute
588 * value of the first argument to the power of the second
589 * argument
590 *
591 * <li>if the second argument is finite and not an integer, then
592 * the result is NaN.
593 * </ul>
594 *
595 * <li>If both arguments are integers, then the result is exactly equal
596 * to the mathematical result of raising the first argument to the power
597 * of the second argument if that result can in fact be represented
598 * exactly as a {@code double} value.</ul>
599 *
600 * <p>(In the foregoing descriptions, a floating-point value is
601 * considered to be an integer if and only if it is finite and a
602 * fixed point of the method {@link #ceil ceil} or,
603 * equivalently, a fixed point of the method {@link #floor
604 * floor}. A value is a fixed point of a one-argument
605 * method if and only if the result of applying the method to the
606 * value is equal to the value.)
607 *
608 * @param a base.
609 * @param b the exponent.
610 * @return the value {@code a}<sup>{@code b}</sup>.
611 */
612 public static native double pow(double a, double b);
613
614 /**
615 * Returns the closest {@code int} to the argument, with ties
616 * rounding up.
617 *
618 * <p>Special cases:
619 * <ul><li>If the argument is NaN, the result is 0.
620 * <li>If the argument is negative infinity or any value less than or
621 * equal to the value of {@code Integer.MIN_VALUE}, the result is
622 * equal to the value of {@code Integer.MIN_VALUE}.
623 * <li>If the argument is positive infinity or any value greater than or
624 * equal to the value of {@code Integer.MAX_VALUE}, the result is
625 * equal to the value of {@code Integer.MAX_VALUE}.</ul>
626 *
627 * @param a a floating-point value to be rounded to an integer.
628 * @return the value of the argument rounded to the nearest
629 * {@code int} value.
630 * @see java.lang.Integer#MAX_VALUE
631 * @see java.lang.Integer#MIN_VALUE
632 */
633 public static int round(float a) {
634 return Math.round(a);
635 }
636
637 /**
638 * Returns the closest {@code long} to the argument, with ties
639 * rounding up.
640 *
641 * <p>Special cases:
642 * <ul><li>If the argument is NaN, the result is 0.
643 * <li>If the argument is negative infinity or any value less than or
644 * equal to the value of {@code Long.MIN_VALUE}, the result is
645 * equal to the value of {@code Long.MIN_VALUE}.
646 * <li>If the argument is positive infinity or any value greater than or
647 * equal to the value of {@code Long.MAX_VALUE}, the result is
648 * equal to the value of {@code Long.MAX_VALUE}.</ul>
649 *
650 * @param a a floating-point value to be rounded to a
651 * {@code long}.
652 * @return the value of the argument rounded to the nearest
653 * {@code long} value.
654 * @see java.lang.Long#MAX_VALUE
655 * @see java.lang.Long#MIN_VALUE
656 */
657 public static long round(double a) {
658 return Math.round(a);
659 }
660
661 private static Random randomNumberGenerator;
662
663 private static synchronized Random initRNG() {
664 Random rnd = randomNumberGenerator;
665 return (rnd == null) ? (randomNumberGenerator = new Random()) : rnd;
666 }
667
668 /**
669 * Returns a {@code double} value with a positive sign, greater
670 * than or equal to {@code 0.0} and less than {@code 1.0}.
671 * Returned values are chosen pseudorandomly with (approximately)
672 * uniform distribution from that range.
673 *
674 * <p>When this method is first called, it creates a single new
675 * pseudorandom-number generator, exactly as if by the expression
676 *
677 * <blockquote>{@code new java.util.Random()}</blockquote>
678 *
679 * This new pseudorandom-number generator is used thereafter for
680 * all calls to this method and is used nowhere else.
681 *
682 * <p>This method is properly synchronized to allow correct use by
683 * more than one thread. However, if many threads need to generate
684 * pseudorandom numbers at a great rate, it may reduce contention
685 * for each thread to have its own pseudorandom number generator.
686 *
687 * @return a pseudorandom {@code double} greater than or equal
688 * to {@code 0.0} and less than {@code 1.0}.
689 * @see Random#nextDouble()
690 */
691 public static double random() {
692 Random rnd = randomNumberGenerator;
693 if (rnd == null) rnd = initRNG();
694 return rnd.nextDouble();
695 }
696
697 /**
698 * Returns the absolute value of an {@code int} value..
699 * If the argument is not negative, the argument is returned.
700 * If the argument is negative, the negation of the argument is returned.
701 *
702 * <p>Note that if the argument is equal to the value of
703 * {@link Integer#MIN_VALUE}, the most negative representable
704 * {@code int} value, the result is that same value, which is
705 * negative.
706 *
707 * @param a the argument whose absolute value is to be determined.
708 * @return the absolute value of the argument.
709 */
710 public static int abs(int a) {
711 return (a < 0) ? -a : a;
712 }
713
714 /**
715 * Returns the absolute value of a {@code long} value.
716 * If the argument is not negative, the argument is returned.
717 * If the argument is negative, the negation of the argument is returned.
718 *
719 * <p>Note that if the argument is equal to the value of
720 * {@link Long#MIN_VALUE}, the most negative representable
721 * {@code long} value, the result is that same value, which
722 * is negative.
723 *
724 * @param a the argument whose absolute value is to be determined.
725 * @return the absolute value of the argument.
726 */
727 public static long abs(long a) {
728 return (a < 0) ? -a : a;
729 }
730
731 /**
732 * Returns the absolute value of a {@code float} value.
733 * If the argument is not negative, the argument is returned.
734 * If the argument is negative, the negation of the argument is returned.
735 * Special cases:
736 * <ul><li>If the argument is positive zero or negative zero, the
737 * result is positive zero.
738 * <li>If the argument is infinite, the result is positive infinity.
739 * <li>If the argument is NaN, the result is NaN.</ul>
740 * In other words, the result is the same as the value of the expression:
741 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))}
742 *
743 * @param a the argument whose absolute value is to be determined
744 * @return the absolute value of the argument.
745 */
746 public static float abs(float a) {
747 return (a <= 0.0F) ? 0.0F - a : a;
748 }
749
750 /**
751 * Returns the absolute value of a {@code double} value.
752 * If the argument is not negative, the argument is returned.
753 * If the argument is negative, the negation of the argument is returned.
754 * Special cases:
755 * <ul><li>If the argument is positive zero or negative zero, the result
756 * is positive zero.
757 * <li>If the argument is infinite, the result is positive infinity.
758 * <li>If the argument is NaN, the result is NaN.</ul>
759 * In other words, the result is the same as the value of the expression:
760 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
761 *
762 * @param a the argument whose absolute value is to be determined
763 * @return the absolute value of the argument.
764 */
765 public static double abs(double a) {
766 return (a <= 0.0D) ? 0.0D - a : a;
767 }
768
769 /**
770 * Returns the greater of two {@code int} values. That is, the
771 * result is the argument closer to the value of
772 * {@link Integer#MAX_VALUE}. If the arguments have the same value,
773 * the result is that same value.
774 *
775 * @param a an argument.
776 * @param b another argument.
777 * @return the larger of {@code a} and {@code b}.
778 */
779 public static int max(int a, int b) {
780 return (a >= b) ? a : b;
781 }
782
783 /**
784 * Returns the greater of two {@code long} values. That is, the
785 * result is the argument closer to the value of
786 * {@link Long#MAX_VALUE}. If the arguments have the same value,
787 * the result is that same value.
788 *
789 * @param a an argument.
790 * @param b another argument.
791 * @return the larger of {@code a} and {@code b}.
792 */
793 public static long max(long a, long b) {
794 return (a >= b) ? a : b;
795 }
796
797 // Use raw bit-wise conversions on guaranteed non-NaN arguments.
798 private static long negativeZeroFloatBits = Float.floatToRawIntBits(-0.0f);
799 private static long negativeZeroDoubleBits = Double.doubleToRawLongBits(-0.0d);
800
801 /**
802 * Returns the greater of two {@code float} values. That is,
803 * the result is the argument closer to positive infinity. If the
804 * arguments have the same value, the result is that same
805 * value. If either value is NaN, then the result is NaN. Unlike
806 * the numerical comparison operators, this method considers
807 * negative zero to be strictly smaller than positive zero. If one
808 * argument is positive zero and the other negative zero, the
809 * result is positive zero.
810 *
811 * @param a an argument.
812 * @param b another argument.
813 * @return the larger of {@code a} and {@code b}.
814 */
815 public static float max(float a, float b) {
816 if (a != a)
817 return a; // a is NaN
818 if ((a == 0.0f) &&
819 (b == 0.0f) &&
820 (Float.floatToRawIntBits(a) == negativeZeroFloatBits)) {
821 // Raw conversion ok since NaN can't map to -0.0.
822 return b;
823 }
824 return (a >= b) ? a : b;
825 }
826
827 /**
828 * Returns the greater of two {@code double} values. That
829 * is, the result is the argument closer to positive infinity. If
830 * the arguments have the same value, the result is that same
831 * value. If either value is NaN, then the result is NaN. Unlike
832 * the numerical comparison operators, this method considers
833 * negative zero to be strictly smaller than positive zero. If one
834 * argument is positive zero and the other negative zero, the
835 * result is positive zero.
836 *
837 * @param a an argument.
838 * @param b another argument.
839 * @return the larger of {@code a} and {@code b}.
840 */
841 public static double max(double a, double b) {
842 if (a != a)
843 return a; // a is NaN
844 if ((a == 0.0d) &&
845 (b == 0.0d) &&
846 (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) {
847 // Raw conversion ok since NaN can't map to -0.0.
848 return b;
849 }
850 return (a >= b) ? a : b;
851 }
852
853 /**
854 * Returns the smaller of two {@code int} values. That is,
855 * the result the argument closer to the value of
856 * {@link Integer#MIN_VALUE}. If the arguments have the same
857 * value, the result is that same value.
858 *
859 * @param a an argument.
860 * @param b another argument.
861 * @return the smaller of {@code a} and {@code b}.
862 */
863 public static int min(int a, int b) {
864 return (a <= b) ? a : b;
865 }
866
867 /**
868 * Returns the smaller of two {@code long} values. That is,
869 * the result is the argument closer to the value of
870 * {@link Long#MIN_VALUE}. If the arguments have the same
871 * value, the result is that same value.
872 *
873 * @param a an argument.
874 * @param b another argument.
875 * @return the smaller of {@code a} and {@code b}.
876 */
877 public static long min(long a, long b) {
878 return (a <= b) ? a : b;
879 }
880
881 /**
882 * Returns the smaller of two {@code float} values. That is,
883 * the result is the value closer to negative infinity. If the
884 * arguments have the same value, the result is that same
885 * value. If either value is NaN, then the result is NaN. Unlike
886 * the numerical comparison operators, this method considers
887 * negative zero to be strictly smaller than positive zero. If
888 * one argument is positive zero and the other is negative zero,
889 * the result is negative zero.
890 *
891 * @param a an argument.
892 * @param b another argument.
893 * @return the smaller of {@code a} and {@code b.}
894 */
895 public static float min(float a, float b) {
896 if (a != a)
897 return a; // a is NaN
898 if ((a == 0.0f) &&
899 (b == 0.0f) &&
900 (Float.floatToRawIntBits(b) == negativeZeroFloatBits)) {
901 // Raw conversion ok since NaN can't map to -0.0.
902 return b;
903 }
904 return (a <= b) ? a : b;
905 }
906
907 /**
908 * Returns the smaller of two {@code double} values. That
909 * is, the result is the value closer to negative infinity. If the
910 * arguments have the same value, the result is that same
911 * value. If either value is NaN, then the result is NaN. Unlike
912 * the numerical comparison operators, this method considers
913 * negative zero to be strictly smaller than positive zero. If one
914 * argument is positive zero and the other is negative zero, the
915 * result is negative zero.
916 *
917 * @param a an argument.
918 * @param b another argument.
919 * @return the smaller of {@code a} and {@code b}.
920 */
921 public static double min(double a, double b) {
922 if (a != a)
923 return a; // a is NaN
924 if ((a == 0.0d) &&
925 (b == 0.0d) &&
926 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) {
927 // Raw conversion ok since NaN can't map to -0.0.
928 return b;
929 }
930 return (a <= b) ? a : b;
931 }
932
933 /**
934 * Returns the size of an ulp of the argument. An ulp, unit in
935 * the last place, of a {@code double} value is the positive
936 * distance between this floating-point value and the {@code
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>
1047 *
1048 * @param x The number whose hyperbolic sine is to be returned.
1049 * @return The hyperbolic sine of {@code x}.
1050 * @since 1.5
1051 */
1052 public static native double sinh(double x);
1053
1054 /**
1055 * Returns the hyperbolic cosine of a {@code double} value.
1056 * The hyperbolic cosine of <i>x</i> is defined to be
1057 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
1058 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1059 *
1060 * <p>Special cases:
1061 * <ul>
1062 *
1063 * <li>If the argument is NaN, then the result is NaN.
1064 *
1065 * <li>If the argument is infinite, then the result is positive
1066 * infinity.
1067 *
1068 * <li>If the argument is zero, then the result is {@code 1.0}.
1069 *
1070 * </ul>
1071 *
1072 * @param x The number whose hyperbolic cosine is to be returned.
1073 * @return The hyperbolic cosine of {@code x}.
1074 * @since 1.5
1075 */
1076 public static native double cosh(double x);
1077
1078 /**
1079 * Returns the hyperbolic tangent of a {@code double} value.
1080 * The hyperbolic tangent of <i>x</i> is defined to be
1081 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
1082 * in other words, {@linkplain Math#sinh
1083 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
1084 * that the absolute value of the exact tanh is always less than
1085 * 1.
1086 *
1087 * <p>Special cases:
1088 * <ul>
1089 *
1090 * <li>If the argument is NaN, then the result is NaN.
1091 *
1092 * <li>If the argument is zero, then the result is a zero with the
1093 * same sign as the argument.
1094 *
1095 * <li>If the argument is positive infinity, then the result is
1096 * {@code +1.0}.
1097 *
1098 * <li>If the argument is negative infinity, then the result is
1099 * {@code -1.0}.
1100 *
1101 * </ul>
1102 *
1103 * @param x The number whose hyperbolic tangent is to be returned.
1104 * @return The hyperbolic tangent of {@code x}.
1105 * @since 1.5
1106 */
1107 public static native double tanh(double x);
1108
1109 /**
1110 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1111 * without intermediate overflow or underflow.
1112 *
1113 * <p>Special cases:
1114 * <ul>
1115 *
1116 * <li> If either argument is infinite, then the result
1117 * is positive infinity.
1118 *
1119 * <li> If either argument is NaN and neither argument is infinite,
1120 * then the result is NaN.
1121 *
1122 * </ul>
1123 *
1124 * @param x a value
1125 * @param y a value
1126 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1127 * without intermediate overflow or underflow
1128 * @since 1.5
1129 */
1130 public static native double hypot(double x, double y);
1131
1132 /**
1133 * Returns <i>e</i><sup>x</sup> -1. Note that for values of
1134 * <i>x</i> near 0, the exact sum of
1135 * {@code expm1(x)} + 1 is much closer to the true
1136 * result of <i>e</i><sup>x</sup> than {@code exp(x)}.
1137 *
1138 * <p>Special cases:
1139 * <ul>
1140 * <li>If the argument is NaN, the result is NaN.
1141 *
1142 * <li>If the argument is positive infinity, then the result is
1143 * positive infinity.
1144 *
1145 * <li>If the argument is negative infinity, then the result is
1146 * -1.0.
1147 *
1148 * <li>If the argument is zero, then the result is a zero with the
1149 * same sign as the argument.
1150 *
1151 * </ul>
1152 *
1153 * @param x the exponent to raise <i>e</i> to in the computation of
1154 * <i>e</i><sup>{@code x}</sup> -1.
1155 * @return the value <i>e</i><sup>{@code x}</sup> - 1.
1156 * @since 1.5
1157 */
1158 public static native double expm1(double x);
1159
1160 /**
1161 * Returns the natural logarithm of the sum of the argument and 1.
1162 * Note that for small values {@code x}, the result of
1163 * {@code log1p(x)} is much closer to the true result of ln(1
1164 * + {@code x}) than the floating-point evaluation of
1165 * {@code log(1.0+x)}.
1166 *
1167 * <p>Special cases:
1168 * <ul>
1169 *
1170 * <li>If the argument is NaN or less than -1, then the result is
1171 * NaN.
1172 *
1173 * <li>If the argument is positive infinity, then the result is
1174 * positive infinity.
1175 *
1176 * <li>If the argument is negative one, then the result is
1177 * negative infinity.
1178 *
1179 * <li>If the argument is zero, then the result is a zero with the
1180 * same sign as the argument.
1181 *
1182 * </ul>
1183 *
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}
1274 * is returned.
1275 *
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.
1317 *
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 }