1 /*
2 * Copyright 1999-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.lang;
27 import java.util.Random;
28 import sun.misc.FpUtils;
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 native double ceil(double a);
320
321 /**
322 * Returns the largest (closest to positive infinity)
323 * {@code double} value that is less 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.</ul>
330 *
331 * @param a a value.
332 * @return the largest (closest to positive infinity)
333 * floating-point value that less than or equal to the argument
334 * and is equal to a mathematical integer.
335 */
336 public static native double floor(double a);
337
338 /**
339 * Returns the {@code double} value that is closest in value
340 * to the argument and is equal to a mathematical integer. If two
341 * {@code double} values that are mathematical integers are
342 * equally close to the value of the argument, the result is the
343 * integer value that is even. Special cases:
344 * <ul><li>If the argument value is already equal to a mathematical
345 * integer, then the result is the same as the argument.
346 * <li>If the argument is NaN or an infinity or positive zero or negative
347 * zero, then the result is the same as the argument.</ul>
348 *
349 * @param a a value.
350 * @return the closest floating-point value to {@code a} that is
351 * equal to a mathematical integer.
352 * @author Joseph D. Darcy
353 */
354 public static double rint(double a) {
355 /*
356 * If the absolute value of a is not less than 2^52, it
357 * is either a finite integer (the double format does not have
358 * enough significand bits for a number that large to have any
359 * fractional portion), an infinity, or a NaN. In any of
360 * these cases, rint of the argument is the argument.
361 *
362 * Otherwise, the sum (twoToThe52 + a ) will properly round
363 * away any fractional portion of a since ulp(twoToThe52) ==
364 * 1.0; subtracting out twoToThe52 from this sum will then be
365 * exact and leave the rounded integer portion of a.
366 *
367 * This method does *not* need to be declared strictfp to get
368 * fully reproducible results. Whether or not a method is
369 * declared strictfp can only make a difference in the
370 * returned result if some operation would overflow or
371 * underflow with strictfp semantics. The operation
372 * (twoToThe52 + a ) cannot overflow since large values of a
373 * are screened out; the add cannot underflow since twoToThe52
374 * is too large. The subtraction ((twoToThe52 + a ) -
375 * twoToThe52) will be exact as discussed above and thus
376 * cannot overflow or meaningfully underflow. Finally, the
377 * last multiply in the return statement is by plus or minus
378 * 1.0, which is exact too.
379 */
380 double twoToThe52 = (double)(1L << 52); // 2^52
381 double sign = FpUtils.rawCopySign(1.0, a); // preserve sign info
382 a = Math.abs(a);
383
384 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51
385 a = ((twoToThe52 + a ) - twoToThe52);
386 }
387
388 return sign * a; // restore original sign
389 }
390
391 /**
392 * Returns the angle <i>theta</i> from the conversion of rectangular
393 * coordinates ({@code x}, {@code y}) to polar
394 * coordinates (r, <i>theta</i>).
395 * This method computes the phase <i>theta</i> by computing an arc tangent
396 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
397 * cases:
398 * <ul><li>If either argument is NaN, then the result is NaN.
399 * <li>If the first argument is positive zero and the second argument
400 * is positive, or the first argument is positive and finite and the
401 * second argument is positive infinity, then the result is positive
402 * zero.
403 * <li>If the first argument is negative zero and the second argument
404 * is positive, or the first argument is negative and finite and the
405 * second argument is positive infinity, then the result is negative zero.
406 * <li>If the first argument is positive zero and the second argument
407 * is negative, or the first argument is positive and finite and the
408 * second argument is negative infinity, then the result is the
409 * {@code double} value closest to <i>pi</i>.
410 * <li>If the first argument is negative zero and the second argument
411 * is negative, or the first argument is negative and finite and the
412 * second argument is negative infinity, then the result is the
413 * {@code double} value closest to -<i>pi</i>.
414 * <li>If the first argument is positive and the second argument is
415 * positive zero or negative zero, or the first argument is positive
416 * infinity and the second argument is finite, then the result is the
417 * {@code double} value closest to <i>pi</i>/2.
418 * <li>If the first argument is negative and the second argument is
419 * positive zero or negative zero, or the first argument is negative
420 * infinity and the second argument is finite, then the result is the
421 * {@code double} value closest to -<i>pi</i>/2.
422 * <li>If both arguments are positive infinity, then the result is the
423 * {@code double} value closest to <i>pi</i>/4.
424 * <li>If the first argument is positive infinity and the second argument
425 * is negative infinity, then the result is the {@code double}
426 * value closest to 3*<i>pi</i>/4.
427 * <li>If the first argument is negative infinity and the second argument
428 * is positive infinity, then the result is the {@code double} value
429 * closest to -<i>pi</i>/4.
430 * <li>If both arguments are negative infinity, then the result is the
431 * {@code double} value closest to -3*<i>pi</i>/4.</ul>
432 *
433 * @param y the ordinate coordinate
434 * @param x the abscissa coordinate
435 * @return the <i>theta</i> component of the point
436 * (<i>r</i>, <i>theta</i>)
437 * in polar coordinates that corresponds to the point
438 * (<i>x</i>, <i>y</i>) in Cartesian coordinates.
439 */
440 public static native double atan2(double y, double x);
441
442
443 /**
444 * Returns the value of the first argument raised to the power of the
445 * second argument. Special cases:
446 *
447 * <ul><li>If the second argument is positive or negative zero, then the
448 * result is 1.0.
449 * <li>If the second argument is 1.0, then the result is the same as the
450 * first argument.
451 * <li>If the second argument is NaN, then the result is NaN.
452 * <li>If the first argument is NaN and the second argument is nonzero,
453 * then the result is NaN.
454 *
455 * <li>If
456 * <ul>
457 * <li>the absolute value of the first argument is greater than 1
458 * and the second argument is positive infinity, or
459 * <li>the absolute value of the first argument is less than 1 and
460 * the second argument is negative infinity,
461 * </ul>
462 * then the result is positive infinity.
463 *
464 * <li>If
465 * <ul>
466 * <li>the absolute value of the first argument is greater than 1 and
467 * the second argument is negative infinity, or
468 * <li>the absolute value of the
469 * first argument is less than 1 and the second argument is positive
470 * infinity,
471 * </ul>
472 * then the result is positive zero.
473 *
474 * <li>If the absolute value of the first argument equals 1 and the
475 * second argument is infinite, then the result is NaN.
476 *
477 * <li>If
478 * <ul>
479 * <li>the first argument is positive zero and the second argument
480 * is greater than zero, or
481 * <li>the first argument is positive infinity and the second
482 * argument is less than zero,
483 * </ul>
484 * then the result is positive zero.
485 *
486 * <li>If
487 * <ul>
488 * <li>the first argument is positive zero and the second argument
489 * is less than zero, or
490 * <li>the first argument is positive infinity and the second
491 * argument is greater than zero,
492 * </ul>
493 * then the result is positive infinity.
494 *
495 * <li>If
496 * <ul>
497 * <li>the first argument is negative zero and the second argument
498 * is greater than zero but not a finite odd integer, or
499 * <li>the first argument is negative infinity and the second
500 * argument is less than zero but not a finite odd integer,
501 * </ul>
502 * then the result is positive zero.
503 *
504 * <li>If
505 * <ul>
506 * <li>the first argument is negative zero and the second argument
507 * is a positive finite odd integer, or
508 * <li>the first argument is negative infinity and the second
509 * argument is a negative finite odd integer,
510 * </ul>
511 * then the result is negative zero.
512 *
513 * <li>If
514 * <ul>
515 * <li>the first argument is negative zero and the second argument
516 * is less than zero but not a finite odd integer, or
517 * <li>the first argument is negative infinity and the second
518 * argument is greater than zero but not a finite odd integer,
519 * </ul>
520 * then the result is positive infinity.
521 *
522 * <li>If
523 * <ul>
524 * <li>the first argument is negative zero and the second argument
525 * is a negative finite odd integer, or
526 * <li>the first argument is negative infinity and the second
527 * argument is a positive finite odd integer,
528 * </ul>
529 * then the result is negative infinity.
530 *
531 * <li>If the first argument is finite and less than zero
532 * <ul>
533 * <li> if the second argument is a finite even integer, the
534 * result is equal to the result of raising the absolute value of
535 * the first argument to the power of the second argument
536 *
537 * <li>if the second argument is a finite odd integer, the result
538 * is equal to the negative of the result of raising the absolute
539 * value of the first argument to the power of the second
540 * argument
541 *
542 * <li>if the second argument is finite and not an integer, then
543 * the result is NaN.
544 * </ul>
545 *
546 * <li>If both arguments are integers, then the result is exactly equal
547 * to the mathematical result of raising the first argument to the power
548 * of the second argument if that result can in fact be represented
549 * exactly as a {@code double} value.</ul>
550 *
551 * <p>(In the foregoing descriptions, a floating-point value is
552 * considered to be an integer if and only if it is finite and a
553 * fixed point of the method {@link #ceil ceil} or,
554 * equivalently, a fixed point of the method {@link #floor
555 * floor}. A value is a fixed point of a one-argument
556 * method if and only if the result of applying the method to the
557 * value is equal to the value.)
558 *
559 * @param a base.
560 * @param b the exponent.
561 * @return the value {@code a}<sup>{@code b}</sup>.
562 */
563 public static native double pow(double a, double b);
564
565 /**
566 * Returns the closest {@code int} to the argument. The
567 * result is rounded to an integer by adding 1/2, taking the
568 * floor of the result, and casting the result to type {@code int}.
569 * In other words, the result is equal to the value of the expression:
570 * <p>{@code (int)Math.floor(a + 0.5f)}
571 *
572 * <p>Special cases:
573 * <ul><li>If the argument is NaN, the result is 0.
574 * <li>If the argument is negative infinity or any value less than or
575 * equal to the value of {@code Integer.MIN_VALUE}, the result is
576 * equal to the value of {@code Integer.MIN_VALUE}.
577 * <li>If the argument is positive infinity or any value greater than or
578 * equal to the value of {@code Integer.MAX_VALUE}, the result is
579 * equal to the value of {@code Integer.MAX_VALUE}.</ul>
580 *
581 * @param a a floating-point value to be rounded to an integer.
582 * @return the value of the argument rounded to the nearest
583 * {@code int} value.
584 * @see java.lang.Integer#MAX_VALUE
585 * @see java.lang.Integer#MIN_VALUE
586 */
587 public static int round(float a) {
588 return (int)floor(a + 0.5f);
589 }
590
591 /**
592 * Returns the closest {@code long} to the argument. The result
593 * is rounded to an integer by adding 1/2, taking the floor of the
594 * result, and casting the result to type {@code long}. In other
595 * words, the result is equal to the value of the expression:
596 * <p>{@code (long)Math.floor(a + 0.5d)}
597 *
598 * <p>Special cases:
599 * <ul><li>If the argument is NaN, the result is 0.
600 * <li>If the argument is negative infinity or any value less than or
601 * equal to the value of {@code Long.MIN_VALUE}, the result is
602 * equal to the value of {@code Long.MIN_VALUE}.
603 * <li>If the argument is positive infinity or any value greater than or
604 * equal to the value of {@code Long.MAX_VALUE}, the result is
605 * equal to the value of {@code Long.MAX_VALUE}.</ul>
606 *
607 * @param a a floating-point value to be rounded to a
608 * {@code long}.
609 * @return the value of the argument rounded to the nearest
610 * {@code long} value.
611 * @see java.lang.Long#MAX_VALUE
612 * @see java.lang.Long#MIN_VALUE
613 */
614 public static long round(double a) {
615 return (long)floor(a + 0.5d);
616 }
617
618 private static Random randomNumberGenerator;
619
620 private static synchronized void initRNG() {
621 if (randomNumberGenerator == null)
622 randomNumberGenerator = new Random();
623 }
624
625 /**
626 * Returns a {@code double} value with a positive sign, greater
627 * than or equal to {@code 0.0} and less than {@code 1.0}.
628 * Returned values are chosen pseudorandomly with (approximately)
629 * uniform distribution from that range.
630 *
631 * <p>When this method is first called, it creates a single new
632 * pseudorandom-number generator, exactly as if by the expression
633 * <blockquote>{@code new java.util.Random}</blockquote> This
634 * new pseudorandom-number generator is used thereafter for all
635 * calls to this method and is used nowhere else.
636 *
637 * <p>This method is properly synchronized to allow correct use by
638 * more than one thread. However, if many threads need to generate
639 * pseudorandom numbers at a great rate, it may reduce contention
640 * for each thread to have its own pseudorandom number generator.
641 *
642 * @return a pseudorandom {@code double} greater than or equal
643 * to {@code 0.0} and less than {@code 1.0}.
644 * @see java.util.Random#nextDouble()
645 */
646 public static double random() {
647 if (randomNumberGenerator == null) initRNG();
648 return randomNumberGenerator.nextDouble();
649 }
650
651 /**
652 * Returns the absolute value of an {@code int} value..
653 * If the argument is not negative, the argument is returned.
654 * If the argument is negative, the negation of the argument is returned.
655 *
656 * <p>Note that if the argument is equal to the value of
657 * {@link Integer#MIN_VALUE}, the most negative representable
658 * {@code int} value, the result is that same value, which is
659 * negative.
660 *
661 * @param a the argument whose absolute value is to be determined.
662 * @return the absolute value of the argument.
663 */
664 public static int abs(int a) {
665 return (a < 0) ? -a : a;
666 }
667
668 /**
669 * Returns the absolute value of a {@code long} value.
670 * If the argument is not negative, the argument is returned.
671 * If the argument is negative, the negation of the argument is returned.
672 *
673 * <p>Note that if the argument is equal to the value of
674 * {@link Long#MIN_VALUE}, the most negative representable
675 * {@code long} value, the result is that same value, which
676 * is negative.
677 *
678 * @param a the argument whose absolute value is to be determined.
679 * @return the absolute value of the argument.
680 */
681 public static long abs(long a) {
682 return (a < 0) ? -a : a;
683 }
684
685 /**
686 * Returns the absolute value of a {@code float} value.
687 * If the argument is not negative, the argument is returned.
688 * If the argument is negative, the negation of the argument is returned.
689 * Special cases:
690 * <ul><li>If the argument is positive zero or negative zero, the
691 * result is positive zero.
692 * <li>If the argument is infinite, the result is positive infinity.
693 * <li>If the argument is NaN, the result is NaN.</ul>
694 * In other words, the result is the same as the value of the expression:
695 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))}
696 *
697 * @param a the argument whose absolute value is to be determined
698 * @return the absolute value of the argument.
699 */
700 public static float abs(float a) {
701 return (a <= 0.0F) ? 0.0F - a : a;
702 }
703
704 /**
705 * Returns the absolute value of a {@code double} value.
706 * If the argument is not negative, the argument is returned.
707 * If the argument is negative, the negation of the argument is returned.
708 * Special cases:
709 * <ul><li>If the argument is positive zero or negative zero, the result
710 * is positive zero.
711 * <li>If the argument is infinite, the result is positive infinity.
712 * <li>If the argument is NaN, the result is NaN.</ul>
713 * In other words, the result is the same as the value of the expression:
714 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
715 *
716 * @param a the argument whose absolute value is to be determined
717 * @return the absolute value of the argument.
718 */
719 public static double abs(double a) {
720 return (a <= 0.0D) ? 0.0D - a : a;
721 }
722
723 /**
724 * Returns the greater of two {@code int} values. That is, the
725 * result is the argument closer to the value of
726 * {@link Integer#MAX_VALUE}. If the arguments have the same value,
727 * the result is that same value.
728 *
729 * @param a an argument.
730 * @param b another argument.
731 * @return the larger of {@code a} and {@code b}.
732 */
733 public static int max(int a, int b) {
734 return (a >= b) ? a : b;
735 }
736
737 /**
738 * Returns the greater of two {@code long} values. That is, the
739 * result is the argument closer to the value of
740 * {@link Long#MAX_VALUE}. If the arguments have the same value,
741 * the result is that same value.
742 *
743 * @param a an argument.
744 * @param b another argument.
745 * @return the larger of {@code a} and {@code b}.
746 */
747 public static long max(long a, long b) {
748 return (a >= b) ? a : b;
749 }
750
751 private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
752 private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
753
754 /**
755 * Returns the greater of two {@code float} values. That is,
756 * the result is the argument closer to positive infinity. If the
757 * arguments have the same value, the result is that same
758 * value. If either value is NaN, then the result is NaN. Unlike
759 * the numerical comparison operators, this method considers
760 * negative zero to be strictly smaller than positive zero. If one
761 * argument is positive zero and the other negative zero, the
762 * result is positive zero.
763 *
764 * @param a an argument.
765 * @param b another argument.
766 * @return the larger of {@code a} and {@code b}.
767 */
768 public static float max(float a, float b) {
769 if (a != a) return a; // a is NaN
770 if ((a == 0.0f) && (b == 0.0f)
771 && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
772 return b;
773 }
774 return (a >= b) ? a : b;
775 }
776
777 /**
778 * Returns the greater of two {@code double} values. That
779 * is, the result is the argument closer to positive infinity. If
780 * the arguments have the same value, the result is that same
781 * value. If either value is NaN, then the result is NaN. Unlike
782 * the numerical comparison operators, this method considers
783 * negative zero to be strictly smaller than positive zero. If one
784 * argument is positive zero and the other negative zero, the
785 * result is positive zero.
786 *
787 * @param a an argument.
788 * @param b another argument.
789 * @return the larger of {@code a} and {@code b}.
790 */
791 public static double max(double a, double b) {
792 if (a != a) return a; // a is NaN
793 if ((a == 0.0d) && (b == 0.0d)
794 && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
795 return b;
796 }
797 return (a >= b) ? a : b;
798 }
799
800 /**
801 * Returns the smaller of two {@code int} values. That is,
802 * the result the argument closer to the value of
803 * {@link Integer#MIN_VALUE}. If the arguments have the same
804 * value, the result is that same value.
805 *
806 * @param a an argument.
807 * @param b another argument.
808 * @return the smaller of {@code a} and {@code b}.
809 */
810 public static int min(int a, int b) {
811 return (a <= b) ? a : b;
812 }
813
814 /**
815 * Returns the smaller of two {@code long} values. That is,
816 * the result is the argument closer to the value of
817 * {@link Long#MIN_VALUE}. If the arguments have the same
818 * value, the result is that same value.
819 *
820 * @param a an argument.
821 * @param b another argument.
822 * @return the smaller of {@code a} and {@code b}.
823 */
824 public static long min(long a, long b) {
825 return (a <= b) ? a : b;
826 }
827
828 /**
829 * Returns the smaller of two {@code float} values. That is,
830 * the result is the value closer to negative infinity. If the
831 * arguments have the same value, the result is that same
832 * value. If either value is NaN, then the result is NaN. Unlike
833 * the numerical comparison operators, this method considers
834 * negative zero to be strictly smaller than positive zero. If
835 * one argument is positive zero and the other is negative zero,
836 * the result is negative zero.
837 *
838 * @param a an argument.
839 * @param b another argument.
840 * @return the smaller of {@code a} and {@code b.}
841 */
842 public static float min(float a, float b) {
843 if (a != a) return a; // a is NaN
844 if ((a == 0.0f) && (b == 0.0f)
845 && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
846 return b;
847 }
848 return (a <= b) ? a : b;
849 }
850
851 /**
852 * Returns the smaller of two {@code double} values. That
853 * is, the result is the value closer to negative infinity. If the
854 * arguments have the same value, the result is that same
855 * value. If either value is NaN, then the result is NaN. Unlike
856 * the numerical comparison operators, this method considers
857 * negative zero to be strictly smaller than positive zero. If one
858 * argument is positive zero and the other is negative zero, the
859 * result is negative zero.
860 *
861 * @param a an argument.
862 * @param b another argument.
863 * @return the smaller of {@code a} and {@code b}.
864 */
865 public static double min(double a, double b) {
866 if (a != a) return a; // a is NaN
867 if ((a == 0.0d) && (b == 0.0d)
868 && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
869 return b;
870 }
871 return (a <= b) ? a : b;
872 }
873
874 /**
875 * Returns the size of an ulp of the argument. An ulp of a
876 * {@code double} value is the positive distance between this
877 * floating-point value and the {@code double} value next
878 * larger in magnitude. Note that for non-NaN <i>x</i>,
879 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
880 *
881 * <p>Special Cases:
882 * <ul>
883 * <li> If the argument is NaN, then the result is NaN.
884 * <li> If the argument is positive or negative infinity, then the
885 * result is positive infinity.
886 * <li> If the argument is positive or negative zero, then the result is
887 * {@code Double.MIN_VALUE}.
888 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
889 * the result is equal to 2<sup>971</sup>.
890 * </ul>
891 *
892 * @param d the floating-point value whose ulp is to be returned
893 * @return the size of an ulp of the argument
894 * @author Joseph D. Darcy
895 * @since 1.5
896 */
897 public static double ulp(double d) {
898 return sun.misc.FpUtils.ulp(d);
899 }
900
901 /**
902 * Returns the size of an ulp of the argument. An ulp of a
903 * {@code float} value is the positive distance between this
904 * floating-point value and the {@code float} value next
905 * larger in magnitude. Note that for non-NaN <i>x</i>,
906 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
907 *
908 * <p>Special Cases:
909 * <ul>
910 * <li> If the argument is NaN, then the result is NaN.
911 * <li> If the argument is positive or negative infinity, then the
912 * result is positive infinity.
913 * <li> If the argument is positive or negative zero, then the result is
914 * {@code Float.MIN_VALUE}.
915 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
916 * the result is equal to 2<sup>104</sup>.
917 * </ul>
918 *
919 * @param f the floating-point value whose ulp is to be returned
920 * @return the size of an ulp of the argument
921 * @author Joseph D. Darcy
922 * @since 1.5
923 */
924 public static float ulp(float f) {
925 return sun.misc.FpUtils.ulp(f);
926 }
927
928 /**
929 * Returns the signum function of the argument; zero if the argument
930 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
931 * argument is less than zero.
932 *
933 * <p>Special Cases:
934 * <ul>
935 * <li> If the argument is NaN, then the result is NaN.
936 * <li> If the argument is positive zero or negative zero, then the
937 * result is the same as the argument.
938 * </ul>
939 *
940 * @param d the floating-point value whose signum is to be returned
941 * @return the signum function of the argument
942 * @author Joseph D. Darcy
943 * @since 1.5
944 */
945 public static double signum(double d) {
946 return sun.misc.FpUtils.signum(d);
947 }
948
949 /**
950 * Returns the signum function of the argument; zero if the argument
951 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
952 * argument is less than zero.
953 *
954 * <p>Special Cases:
955 * <ul>
956 * <li> If the argument is NaN, then the result is NaN.
957 * <li> If the argument is positive zero or negative zero, then the
958 * result is the same as the argument.
959 * </ul>
960 *
961 * @param f the floating-point value whose signum is to be returned
962 * @return the signum function of the argument
963 * @author Joseph D. Darcy
964 * @since 1.5
965 */
966 public static float signum(float f) {
967 return sun.misc.FpUtils.signum(f);
968 }
969
970 /**
971 * Returns the hyperbolic sine of a {@code double} value.
972 * The hyperbolic sine of <i>x</i> is defined to be
973 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
974 * where <i>e</i> is {@linkplain Math#E Euler's number}.
975 *
976 * <p>Special cases:
977 * <ul>
978 *
979 * <li>If the argument is NaN, then the result is NaN.
980 *
981 * <li>If the argument is infinite, then the result is an infinity
982 * with the same sign as the argument.
983 *
984 * <li>If the argument is zero, then the result is a zero with the
985 * same sign as the argument.
986 *
987 * </ul>
988 *
989 * @param x The number whose hyperbolic sine is to be returned.
990 * @return The hyperbolic sine of {@code x}.
991 * @since 1.5
992 */
993 public static native double sinh(double x);
994
995 /**
996 * Returns the hyperbolic cosine of a {@code double} value.
997 * The hyperbolic cosine of <i>x</i> is defined to be
998 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
999 * where <i>e</i> is {@linkplain Math#E Euler's number}.
1000 *
1001 * <p>Special cases:
1002 * <ul>
1003 *
1004 * <li>If the argument is NaN, then the result is NaN.
1005 *
1006 * <li>If the argument is infinite, then the result is positive
1007 * infinity.
1008 *
1009 * <li>If the argument is zero, then the result is {@code 1.0}.
1010 *
1011 * </ul>
1012 *
1013 * @param x The number whose hyperbolic cosine is to be returned.
1014 * @return The hyperbolic cosine of {@code x}.
1015 * @since 1.5
1016 */
1017 public static native double cosh(double x);
1018
1019 /**
1020 * Returns the hyperbolic tangent of a {@code double} value.
1021 * The hyperbolic tangent of <i>x</i> is defined to be
1022 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
1023 * in other words, {@linkplain Math#sinh
1024 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
1025 * that the absolute value of the exact tanh is always less than
1026 * 1.
1027 *
1028 * <p>Special cases:
1029 * <ul>
1030 *
1031 * <li>If the argument is NaN, then the result is NaN.
1032 *
1033 * <li>If the argument is zero, then the result is a zero with the
1034 * same sign as the argument.
1035 *
1036 * <li>If the argument is positive infinity, then the result is
1037 * {@code +1.0}.
1038 *
1039 * <li>If the argument is negative infinity, then the result is
1040 * {@code -1.0}.
1041 *
1042 * </ul>
1043 *
1044 * @param x The number whose hyperbolic tangent is to be returned.
1045 * @return The hyperbolic tangent of {@code x}.
1046 * @since 1.5
1047 */
1048 public static native double tanh(double x);
1049
1050 /**
1051 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1052 * without intermediate overflow or underflow.
1053 *
1054 * <p>Special cases:
1055 * <ul>
1056 *
1057 * <li> If either argument is infinite, then the result
1058 * is positive infinity.
1059 *
1060 * <li> If either argument is NaN and neither argument is infinite,
1061 * then the result is NaN.
1062 *
1063 * </ul>
1064 *
1065 * @param x a value
1066 * @param y a value
1067 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)
1068 * without intermediate overflow or underflow
1069 * @since 1.5
1070 */
1071 public static native double hypot(double x, double y);
1072
1073 /**
1074 * Returns <i>e</i><sup>x</sup> -1. Note that for values of
1075 * <i>x</i> near 0, the exact sum of
1076 * {@code expm1(x)} + 1 is much closer to the true
1077 * result of <i>e</i><sup>x</sup> than {@code exp(x)}.
1078 *
1079 * <p>Special cases:
1080 * <ul>
1081 * <li>If the argument is NaN, the result is NaN.
1082 *
1083 * <li>If the argument is positive infinity, then the result is
1084 * positive infinity.
1085 *
1086 * <li>If the argument is negative infinity, then the result is
1087 * -1.0.
1088 *
1089 * <li>If the argument is zero, then the result is a zero with the
1090 * same sign as the argument.
1091 *
1092 * </ul>
1093 *
1094 * @param x the exponent to raise <i>e</i> to in the computation of
1095 * <i>e</i><sup>{@code x}</sup> -1.
1096 * @return the value <i>e</i><sup>{@code x}</sup> - 1.
1097 * @since 1.5
1098 */
1099 public static native double expm1(double x);
1100
1101 /**
1102 * Returns the natural logarithm of the sum of the argument and 1.
1103 * Note that for small values {@code x}, the result of
1104 * {@code log1p(x)} is much closer to the true result of ln(1
1105 * + {@code x}) than the floating-point evaluation of
1106 * {@code log(1.0+x)}.
1107 *
1108 * <p>Special cases:
1109 * <ul>
1110 *
1111 * <li>If the argument is NaN or less than -1, then the result is
1112 * NaN.
1113 *
1114 * <li>If the argument is positive infinity, then the result is
1115 * positive infinity.
1116 *
1117 * <li>If the argument is negative one, then the result is
1118 * negative infinity.
1119 *
1120 * <li>If the argument is zero, then the result is a zero with the
1121 * same sign as the argument.
1122 *
1123 * </ul>
1124 *
1125 * @param x a value
1126 * @return the value ln({@code x} + 1), the natural
1127 * log of {@code x} + 1
1128 * @since 1.5
1129 */
1130 public static native double log1p(double x);
1131
1132 /**
1133 * Returns the first floating-point argument with the sign of the
1134 * second floating-point argument. For this method, a NaN
1135 * {@code sign} argument is always treated as if it were
1136 * positive.
1137 *
1138 * @param magnitude the parameter providing the magnitude of the result
1139 * @param sign the parameter providing the sign of the result
1140 * @return a value with the magnitude of {@code magnitude}
1141 * and the sign of {@code sign}.
1142 * @since 1.6
1143 */
1144 public static double copySign(double magnitude, double sign) {
1145 return sun.misc.FpUtils.copySign(magnitude, sign);
1146 }
1147
1148 /**
1149 * Returns the first floating-point argument with the sign of the
1150 * second floating-point argument. For this method, a NaN
1151 * {@code sign} argument is always treated as if it were
1152 * positive.
1153 *
1154 * @param magnitude the parameter providing the magnitude of the result
1155 * @param sign the parameter providing the sign of the result
1156 * @return a value with the magnitude of {@code magnitude}
1157 * and the sign of {@code sign}.
1158 * @since 1.6
1159 */
1160 public static float copySign(float magnitude, float sign) {
1161 return sun.misc.FpUtils.copySign(magnitude, sign);
1162 }
1163 /**
1164 * Returns the unbiased exponent used in the representation of a
1165 * {@code float}. Special cases:
1166 *
1167 * <ul>
1168 * <li>If the argument is NaN or infinite, then the result is
1169 * {@link Float#MAX_EXPONENT} + 1.
1170 * <li>If the argument is zero or subnormal, then the result is
1171 * {@link Float#MIN_EXPONENT} -1.
1172 * </ul>
1173 * @param f a {@code float} value
1174 * @since 1.6
1175 */
1176 public static int getExponent(float f) {
1177 return sun.misc.FpUtils.getExponent(f);
1178 }
1179
1180 /**
1181 * Returns the unbiased exponent used in the representation of a
1182 * {@code double}. Special cases:
1183 *
1184 * <ul>
1185 * <li>If the argument is NaN or infinite, then the result is
1186 * {@link Double#MAX_EXPONENT} + 1.
1187 * <li>If the argument is zero or subnormal, then the result is
1188 * {@link Double#MIN_EXPONENT} -1.
1189 * </ul>
1190 * @param d a {@code double} value
1191 * @since 1.6
1192 */
1193 public static int getExponent(double d) {
1194 return sun.misc.FpUtils.getExponent(d);
1195 }
1196
1197 /**
1198 * Returns the floating-point number adjacent to the first
1199 * argument in the direction of the second argument. If both
1200 * arguments compare as equal the second argument is returned.
1201 *
1202 * <p>Special cases:
1203 * <ul>
1204 * <li> If either argument is a NaN, then NaN is returned.
1205 *
1206 * <li> If both arguments are signed zeros, {@code direction}
1207 * is returned unchanged (as implied by the requirement of
1208 * returning the second argument if the arguments compare as
1209 * equal).
1210 *
1211 * <li> If {@code start} is
1212 * ±{@link Double#MIN_VALUE} and {@code direction}
1213 * has a value such that the result should have a smaller
1214 * magnitude, then a zero with the same sign as {@code start}
1215 * is returned.
1216 *
1217 * <li> If {@code start} is infinite and
1218 * {@code direction} has a value such that the result should
1219 * have a smaller magnitude, {@link Double#MAX_VALUE} with the
1220 * same sign as {@code start} is returned.
1221 *
1222 * <li> If {@code start} is equal to ±
1223 * {@link Double#MAX_VALUE} and {@code direction} has a
1224 * value such that the result should have a larger magnitude, an
1225 * infinity with same sign as {@code start} is returned.
1226 * </ul>
1227 *
1228 * @param start starting floating-point value
1229 * @param direction value indicating which of
1230 * {@code start}'s neighbors or {@code start} should
1231 * be returned
1232 * @return The floating-point number adjacent to {@code start} in the
1233 * direction of {@code direction}.
1234 * @since 1.6
1235 */
1236 public static double nextAfter(double start, double direction) {
1237 return sun.misc.FpUtils.nextAfter(start, direction);
1238 }
1239
1240 /**
1241 * Returns the floating-point number adjacent to the first
1242 * argument in the direction of the second argument. If both
1243 * arguments compare as equal a value equivalent to the second argument
1244 * is returned.
1245 *
1246 * <p>Special cases:
1247 * <ul>
1248 * <li> If either argument is a NaN, then NaN is returned.
1249 *
1250 * <li> If both arguments are signed zeros, a value equivalent
1251 * to {@code direction} is returned.
1252 *
1253 * <li> If {@code start} is
1254 * ±{@link Float#MIN_VALUE} and {@code direction}
1255 * has a value such that the result should have a smaller
1256 * magnitude, then a zero with the same sign as {@code start}
1257 * is returned.
1258 *
1259 * <li> If {@code start} is infinite and
1260 * {@code direction} has a value such that the result should
1261 * have a smaller magnitude, {@link Float#MAX_VALUE} with the
1262 * same sign as {@code start} is returned.
1263 *
1264 * <li> If {@code start} is equal to ±
1265 * {@link Float#MAX_VALUE} and {@code direction} has a
1266 * value such that the result should have a larger magnitude, an
1267 * infinity with same sign as {@code start} is returned.
1268 * </ul>
1269 *
1270 * @param start starting floating-point value
1271 * @param direction value indicating which of
1272 * {@code start}'s neighbors or {@code start} should
1273 * be returned
1274 * @return The floating-point number adjacent to {@code start} in the
1275 * direction of {@code direction}.
1276 * @since 1.6
1277 */
1278 public static float nextAfter(float start, double direction) {
1279 return sun.misc.FpUtils.nextAfter(start, direction);
1280 }
1281
1282 /**
1283 * Returns the floating-point value adjacent to {@code d} in
1284 * the direction of positive infinity. This method is
1285 * semantically equivalent to {@code nextAfter(d,
1286 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
1287 * implementation may run faster than its equivalent
1288 * {@code nextAfter} call.
1289 *
1290 * <p>Special Cases:
1291 * <ul>
1292 * <li> If the argument is NaN, the result is NaN.
1293 *
1294 * <li> If the argument is positive infinity, the result is
1295 * positive infinity.
1296 *
1297 * <li> If the argument is zero, the result is
1298 * {@link Double#MIN_VALUE}
1299 *
1300 * </ul>
1301 *
1302 * @param d starting floating-point value
1303 * @return The adjacent floating-point value closer to positive
1304 * infinity.
1305 * @since 1.6
1306 */
1307 public static double nextUp(double d) {
1308 return sun.misc.FpUtils.nextUp(d);
1309 }
1310
1311 /**
1312 * Returns the floating-point value adjacent to {@code f} in
1313 * the direction of positive infinity. This method is
1314 * semantically equivalent to {@code nextAfter(f,
1315 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
1316 * implementation may run faster than its equivalent
1317 * {@code nextAfter} call.
1318 *
1319 * <p>Special Cases:
1320 * <ul>
1321 * <li> If the argument is NaN, the result is NaN.
1322 *
1323 * <li> If the argument is positive infinity, the result is
1324 * positive infinity.
1325 *
1326 * <li> If the argument is zero, the result is
1327 * {@link Float#MIN_VALUE}
1328 *
1329 * </ul>
1330 *
1331 * @param f starting floating-point value
1332 * @return The adjacent floating-point value closer to positive
1333 * infinity.
1334 * @since 1.6
1335 */
1336 public static float nextUp(float f) {
1337 return sun.misc.FpUtils.nextUp(f);
1338 }
1339
1340
1341 /**
1342 * Return {@code d} ×
1343 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1344 * by a single correctly rounded floating-point multiply to a
1345 * member of the double value set. See the Java
1346 * Language Specification for a discussion of floating-point
1347 * value sets. If the exponent of the result is between {@link
1348 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
1349 * answer is calculated exactly. If the exponent of the result
1350 * would be larger than {@code Double.MAX_EXPONENT}, an
1351 * infinity is returned. Note that if the result is subnormal,
1352 * precision may be lost; that is, when {@code scalb(x, n)}
1353 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1354 * <i>x</i>. When the result is non-NaN, the result has the same
1355 * sign as {@code d}.
1356 *
1357 * <p>Special cases:
1358 * <ul>
1359 * <li> If the first argument is NaN, NaN is returned.
1360 * <li> If the first argument is infinite, then an infinity of the
1361 * same sign is returned.
1362 * <li> If the first argument is zero, then a zero of the same
1363 * sign is returned.
1364 * </ul>
1365 *
1366 * @param d number to be scaled by a power of two.
1367 * @param scaleFactor power of 2 used to scale {@code d}
1368 * @return {@code d} × 2<sup>{@code scaleFactor}</sup>
1369 * @since 1.6
1370 */
1371 public static double scalb(double d, int scaleFactor) {
1372 return sun.misc.FpUtils.scalb(d, scaleFactor);
1373 }
1374
1375 /**
1376 * Return {@code f} ×
1377 * 2<sup>{@code scaleFactor}</sup> rounded as if performed
1378 * by a single correctly rounded floating-point multiply to a
1379 * member of the float value set. See the Java
1380 * Language Specification for a discussion of floating-point
1381 * value sets. If the exponent of the result is between {@link
1382 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
1383 * answer is calculated exactly. If the exponent of the result
1384 * would be larger than {@code Float.MAX_EXPONENT}, an
1385 * infinity is returned. Note that if the result is subnormal,
1386 * precision may be lost; that is, when {@code scalb(x, n)}
1387 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
1388 * <i>x</i>. When the result is non-NaN, the result has the same
1389 * sign as {@code f}.
1390 *
1391 * <p>Special cases:
1392 * <ul>
1393 * <li> If the first argument is NaN, NaN is returned.
1394 * <li> If the first argument is infinite, then an infinity of the
1395 * same sign is returned.
1396 * <li> If the first argument is zero, then a zero of the same
1397 * sign is returned.
1398 * </ul>
1399 *
1400 * @param f number to be scaled by a power of two.
1401 * @param scaleFactor power of 2 used to scale {@code f}
1402 * @return {@code f} × 2<sup>{@code scaleFactor}</sup>
1403 * @since 1.6
1404 */
1405 public static float scalb(float f, int scaleFactor) {
1406 return sun.misc.FpUtils.scalb(f, scaleFactor);
1407 }
1408 }