• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *  Licensed to the Apache Software Foundation (ASF) under one or more
3  *  contributor license agreements.  See the NOTICE file distributed with
4  *  this work for additional information regarding copyright ownership.
5  *  The ASF licenses this file to You under the Apache License, Version 2.0
6  *  (the "License"); you may not use this file except in compliance with
7  *  the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  */
17 
18 package java.lang;
19 
20 /**
21  * Class StrictMath provides basic math constants and operations such as
22  * trigonometric functions, hyperbolic functions, exponential, logarithms, etc.
23  * <p>
24  * In contrast to class {@link Math}, the methods in this class return exactly
25  * the same results on all platforms. Algorithms based on these methods thus
26  * behave the same (e.g. regarding numerical convergence) on all platforms,
27  * complying with the slogan "write once, run everywhere". On the other side,
28  * the implementation of class StrictMath may be less efficient than that of
29  * class Math, as class StrictMath cannot utilize platform specific features
30  * such as an extended precision math co-processors.
31  * <p>
32  * The methods in this class are specified using the "Freely Distributable Math
33  * Library" (fdlibm), version 5.3.
34  * <p>
35  * <a href="http://www.netlib.org/fdlibm/">http://www.netlib.org/fdlibm/</a>
36  */
37 public final class StrictMath {
38     /**
39      * The double value closest to e, the base of the natural logarithm.
40      */
41     public static final double E = Math.E;
42 
43     /**
44      * The double value closest to pi, the ratio of a circle's circumference to
45      * its diameter.
46      */
47     public static final double PI = Math.PI;
48 
49     /**
50      * Prevents this class from being instantiated.
51      */
StrictMath()52     private StrictMath() {
53     }
54 
55     /**
56      * Returns the absolute value of the argument.
57      * <p>
58      * Special cases:
59      * <ul>
60      * <li>{@code abs(-0.0) = +0.0}</li>
61      * <li>{@code abs(+infinity) = +infinity}</li>
62      * <li>{@code abs(-infinity) = +infinity}</li>
63      * <li>{@code abs(NaN) = NaN}</li>
64      * </ul>
65      */
abs(double d)66     public static double abs(double d) {
67         return Math.abs(d);
68     }
69 
70     /**
71      * Returns the absolute value of the argument.
72      * <p>
73      * Special cases:
74      * <ul>
75      * <li>{@code abs(-0.0) = +0.0}</li>
76      * <li>{@code abs(+infinity) = +infinity}</li>
77      * <li>{@code abs(-infinity) = +infinity}</li>
78      * <li>{@code abs(NaN) = NaN}</li>
79      * </ul>
80      */
abs(float f)81     public static float abs(float f) {
82         return Math.abs(f);
83     }
84 
85     /**
86      * Returns the absolute value of the argument.
87      * <p>
88      * If the argument is {@code Integer.MIN_VALUE}, {@code Integer.MIN_VALUE}
89      * is returned.
90      */
abs(int i)91     public static int abs(int i) {
92         return Math.abs(i);
93     }
94 
95     /**
96      * Returns the absolute value of the argument.
97      * <p>
98      * If the argument is {@code Long.MIN_VALUE}, {@code Long.MIN_VALUE} is
99      * returned.
100      */
abs(long l)101     public static long abs(long l) {
102         return Math.abs(l);
103     }
104 
105     /**
106      * Returns the closest double approximation of the arc cosine of the
107      * argument within the range {@code [0..pi]}.
108      * <p>
109      * Special cases:
110      * <ul>
111      * <li>{@code acos((anything > 1) = NaN}</li>
112      * <li>{@code acos((anything < -1) = NaN}</li>
113      * <li>{@code acos(NaN) = NaN}</li>
114      * </ul>
115      *
116      * @param d
117      *            the value to compute arc cosine of.
118      * @return the arc cosine of the argument.
119      */
acos(double d)120     public static native double acos(double d);
121 
122     /**
123      * Returns the closest double approximation of the arc sine of the argument
124      * within the range {@code [-pi/2..pi/2]}.
125      * <p>
126      * Special cases:
127      * <ul>
128      * <li>{@code asin((anything > 1)) = NaN}</li>
129      * <li>{@code asin((anything < -1)) = NaN}</li>
130      * <li>{@code asin(NaN) = NaN}</li>
131      * </ul>
132      *
133      * @param d
134      *            the value whose arc sine has to be computed.
135      * @return the arc sine of the argument.
136      */
asin(double d)137     public static native double asin(double d);
138 
139     /**
140      * Returns the closest double approximation of the arc tangent of the
141      * argument within the range {@code [-pi/2..pi/2]}.
142      * <p>
143      * Special cases:
144      * <ul>
145      * <li>{@code atan(+0.0) = +0.0}</li>
146      * <li>{@code atan(-0.0) = -0.0}</li>
147      * <li>{@code atan(+infinity) = +pi/2}</li>
148      * <li>{@code atan(-infinity) = -pi/2}</li>
149      * <li>{@code atan(NaN) = NaN}</li>
150      * </ul>
151      *
152      * @param d
153      *            the value whose arc tangent has to be computed.
154      * @return the arc tangent of the argument.
155      */
atan(double d)156     public static native double atan(double d);
157 
158     /**
159      * Returns the closest double approximation of the arc tangent of
160      * {@code y/x} within the range {@code [-pi..pi]}. This is the angle of the
161      * polar representation of the rectangular coordinates (x,y).
162      * <p>
163      * Special cases:
164      * <ul>
165      * <li>{@code atan2((anything), NaN ) = NaN;}</li>
166      * <li>{@code atan2(NaN , (anything) ) = NaN;}</li>
167      * <li>{@code atan2(+0.0, +(anything but NaN)) = +0.0}</li>
168      * <li>{@code atan2(-0.0, +(anything but NaN)) = -0.0}</li>
169      * <li>{@code atan2(+0.0, -(anything but NaN)) = +pi}</li>
170      * <li>{@code atan2(-0.0, -(anything but NaN)) = -pi}</li>
171      * <li>{@code atan2(+(anything but 0 and NaN), 0) = +pi/2}</li>
172      * <li>{@code atan2(-(anything but 0 and NaN), 0) = -pi/2}</li>
173      * <li>{@code atan2(+(anything but infinity and NaN), +infinity)} {@code =}
174      * {@code +0.0}</li>
175      * <li>{@code atan2(-(anything but infinity and NaN), +infinity)} {@code =}
176      * {@code -0.0}</li>
177      * <li>{@code atan2(+(anything but infinity and NaN), -infinity) = +pi}</li>
178      * <li>{@code atan2(-(anything but infinity and NaN), -infinity) = -pi}</li>
179      * <li>{@code atan2(+infinity, +infinity ) = +pi/4}</li>
180      * <li>{@code atan2(-infinity, +infinity ) = -pi/4}</li>
181      * <li>{@code atan2(+infinity, -infinity ) = +3pi/4}</li>
182      * <li>{@code atan2(-infinity, -infinity ) = -3pi/4}</li>
183      * <li>{@code atan2(+infinity, (anything but,0, NaN, and infinity))}
184      * {@code =} {@code +pi/2}</li>
185      * <li>{@code atan2(-infinity, (anything but,0, NaN, and infinity))}
186      * {@code =} {@code -pi/2}</li>
187      * </ul>
188      *
189      * @param y
190      *            the numerator of the value whose atan has to be computed.
191      * @param x
192      *            the denominator of the value whose atan has to be computed.
193      * @return the arc tangent of {@code y/x}.
194      */
atan2(double y, double x)195     public static native double atan2(double y, double x);
196 
197     /**
198      * Returns the closest double approximation of the cube root of the
199      * argument.
200      * <p>
201      * Special cases:
202      * <ul>
203      * <li>{@code cbrt(+0.0) = +0.0}</li>
204      * <li>{@code cbrt(-0.0) = -0.0}</li>
205      * <li>{@code cbrt(+infinity) = +infinity}</li>
206      * <li>{@code cbrt(-infinity) = -infinity}</li>
207      * <li>{@code cbrt(NaN) = NaN}</li>
208      * </ul>
209      *
210      * @param d
211      *            the value whose cube root has to be computed.
212      * @return the cube root of the argument.
213      */
cbrt(double d)214     public static native double cbrt(double d);
215 
216     /**
217      * Returns the double conversion of the most negative (closest to negative
218      * infinity) integer value greater than or equal to the argument.
219      * <p>
220      * Special cases:
221      * <ul>
222      * <li>{@code ceil(+0.0) = +0.0}</li>
223      * <li>{@code ceil(-0.0) = -0.0}</li>
224      * <li>{@code ceil((anything in range (-1,0)) = -0.0}</li>
225      * <li>{@code ceil(+infinity) = +infinity}</li>
226      * <li>{@code ceil(-infinity) = -infinity}</li>
227      * <li>{@code ceil(NaN) = NaN}</li>
228      * </ul>
229      */
ceil(double d)230     public static native double ceil(double d);
231 
232 
233     /**
234      * Returns the closest double approximation of the hyperbolic cosine of the
235      * argument.
236      * <p>
237      * Special cases:
238      * <ul>
239      * <li>{@code cosh(+infinity) = +infinity}</li>
240      * <li>{@code cosh(-infinity) = +infinity}</li>
241      * <li>{@code cosh(NaN) = NaN}</li>
242      * </ul>
243      *
244      * @param d
245      *            the value whose hyperbolic cosine has to be computed.
246      * @return the hyperbolic cosine of the argument.
247      */
cosh(double d)248     public static native double cosh(double d);
249 
250     /**
251      * Returns the closest double approximation of the cosine of the argument.
252      * <p>
253      * Special cases:
254      * <ul>
255      * <li>{@code cos(+infinity) = NaN}</li>
256      * <li>{@code cos(-infinity) = NaN}</li>
257      * <li>{@code cos(NaN) = NaN}</li>
258      * </ul>
259      *
260      * @param d
261      *            the angle whose cosine has to be computed, in radians.
262      * @return the cosine of the argument.
263      */
cos(double d)264     public static native double cos(double d);
265 
266     /**
267      * Returns the closest double approximation of the raising "e" to the power
268      * of the argument.
269      * <p>
270      * Special cases:
271      * <ul>
272      * <li>{@code exp(+infinity) = +infinity}</li>
273      * <li>{@code exp(-infinity) = +0.0}</li>
274      * <li>{@code exp(NaN) = NaN}</li>
275      * </ul>
276      *
277      * @param d
278      *            the value whose exponential has to be computed.
279      * @return the exponential of the argument.
280      */
exp(double d)281     public static native double exp(double d);
282 
283     /**
284      * Returns the closest double approximation of <i>{@code e}</i><sup>
285      * {@code d}</sup>{@code - 1}. If the argument is very close to 0, it is
286      * much more accurate to use {@code expm1(d)+1} than {@code exp(d)} (due to
287      * cancellation of significant digits).
288      * <p>
289      * Special cases:
290      * <ul>
291      * <li>{@code expm1(+0.0) = +0.0}</li>
292      * <li>{@code expm1(-0.0) = -0.0}</li>
293      * <li>{@code expm1(+infinity) = +infinity}</li>
294      * <li>{@code expm1(-infinity) = -1.0}</li>
295      * <li>{@code expm1(NaN) = NaN}</li>
296      * </ul>
297      *
298      * @param d
299      *            the value to compute the <i>{@code e}</i><sup>{@code d}</sup>
300      *            {@code - 1} of.
301      * @return the <i>{@code e}</i><sup>{@code d}</sup>{@code - 1} value
302      *         of the argument.
303      */
expm1(double d)304     public static native double expm1(double d);
305 
306     /**
307      * Returns the double conversion of the most positive (closest to
308      * positive infinity) integer less than or equal to the argument.
309      * <p>
310      * Special cases:
311      * <ul>
312      * <li>{@code floor(+0.0) = +0.0}</li>
313      * <li>{@code floor(-0.0) = -0.0}</li>
314      * <li>{@code floor(+infinity) = +infinity}</li>
315      * <li>{@code floor(-infinity) = -infinity}</li>
316      * <li>{@code floor(NaN) = NaN}</li>
317      * </ul>
318      */
floor(double d)319     public static native double floor(double d);
320 
321     /**
322      * Returns {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +}
323      * <i> {@code y}</i><sup>{@code 2}</sup>{@code )}. The final result is
324      * without medium underflow or overflow.
325      * <p>
326      * Special cases:
327      * <ul>
328      * <li>{@code hypot(+infinity, (anything including NaN)) = +infinity}</li>
329      * <li>{@code hypot(-infinity, (anything including NaN)) = +infinity}</li>
330      * <li>{@code hypot((anything including NaN), +infinity) = +infinity}</li>
331      * <li>{@code hypot((anything including NaN), -infinity) = +infinity}</li>
332      * <li>{@code hypot(NaN, NaN) = NaN}</li>
333      * </ul>
334      *
335      * @param x
336      *            a double number.
337      * @param y
338      *            a double number.
339      * @return the {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +}
340      *         <i> {@code y}</i><sup>{@code 2}</sup>{@code )} value of the
341      *         arguments.
342      */
hypot(double x, double y)343     public static native double hypot(double x, double y);
344 
345     /**
346      * Returns the remainder of dividing {@code x} by {@code y} using the IEEE
347      * 754 rules. The result is {@code x-round(x/p)*p} where {@code round(x/p)}
348      * is the nearest integer (rounded to even), but without numerical
349      * cancellation problems.
350      * <p>
351      * Special cases:
352      * <ul>
353      * <li>{@code IEEEremainder((anything), 0) = NaN}</li>
354      * <li>{@code IEEEremainder(+infinity, (anything)) = NaN}</li>
355      * <li>{@code IEEEremainder(-infinity, (anything)) = NaN}</li>
356      * <li>{@code IEEEremainder(NaN, (anything)) = NaN}</li>
357      * <li>{@code IEEEremainder((anything), NaN) = NaN}</li>
358      * <li>{@code IEEEremainder(x, +infinity) = x } where x is anything but
359      * +/-infinity</li>
360      * <li>{@code IEEEremainder(x, -infinity) = x } where x is anything but
361      * +/-infinity</li>
362      * </ul>
363      *
364      * @param x
365      *            the numerator of the operation.
366      * @param y
367      *            the denominator of the operation.
368      * @return the IEEE754 floating point reminder of of {@code x/y}.
369      */
IEEEremainder(double x, double y)370     public static native double IEEEremainder(double x, double y);
371 
372     /**
373      * Returns the closest double approximation of the natural logarithm of the
374      * argument.
375      * <p>
376      * Special cases:
377      * <ul>
378      * <li>{@code log(+0.0) = -infinity}</li>
379      * <li>{@code log(-0.0) = -infinity}</li>
380      * <li>{@code log((anything < 0) = NaN}</li>
381      * <li>{@code log(+infinity) = +infinity}</li>
382      * <li>{@code log(-infinity) = NaN}</li>
383      * <li>{@code log(NaN) = NaN}</li>
384      * </ul>
385      *
386      * @param d
387      *            the value whose log has to be computed.
388      * @return the natural logarithm of the argument.
389      */
log(double d)390     public static native double log(double d);
391 
392     /**
393      * Returns the closest double approximation of the base 10 logarithm of the
394      * argument.
395      * <p>
396      * Special cases:
397      * <ul>
398      * <li>{@code log10(+0.0) = -infinity}</li>
399      * <li>{@code log10(-0.0) = -infinity}</li>
400      * <li>{@code log10((anything < 0) = NaN}</li>
401      * <li>{@code log10(+infinity) = +infinity}</li>
402      * <li>{@code log10(-infinity) = NaN}</li>
403      * <li>{@code log10(NaN) = NaN}</li>
404      * </ul>
405      *
406      * @param d
407      *            the value whose base 10 log has to be computed.
408      * @return the natural logarithm of the argument.
409      */
log10(double d)410     public static native double log10(double d);
411 
412     /**
413      * Returns the closest double approximation of the natural logarithm of the
414      * sum of the argument and 1. If the argument is very close to 0, it is much
415      * more accurate to use {@code log1p(d)} than {@code log(1.0+d)} (due to
416      * numerical cancellation).
417      * <p>
418      * Special cases:
419      * <ul>
420      * <li>{@code log1p(+0.0) = +0.0}</li>
421      * <li>{@code log1p(-0.0) = -0.0}</li>
422      * <li>{@code log1p((anything < 1)) = NaN}</li>
423      * <li>{@code log1p(-1.0) = -infinity}</li>
424      * <li>{@code log1p(+infinity) = +infinity}</li>
425      * <li>{@code log1p(-infinity) = NaN}</li>
426      * <li>{@code log1p(NaN) = NaN}</li>
427      * </ul>
428      *
429      * @param d
430      *            the value to compute the {@code ln(1+d)} of.
431      * @return the natural logarithm of the sum of the argument and 1.
432      */
log1p(double d)433     public static native double log1p(double d);
434 
435     /**
436      * Returns the most positive (closest to positive infinity) of the two
437      * arguments.
438      * <p>
439      * Special cases:
440      * <ul>
441      * <li>{@code max(NaN, (anything)) = NaN}</li>
442      * <li>{@code max((anything), NaN) = NaN}</li>
443      * <li>{@code max(+0.0, -0.0) = +0.0}</li>
444      * <li>{@code max(-0.0, +0.0) = +0.0}</li>
445      * </ul>
446      */
max(double d1, double d2)447     public static double max(double d1, double d2) {
448         if (d1 > d2)
449             return d1;
450         if (d1 < d2)
451             return d2;
452         /* if either arg is NaN, return NaN */
453         if (d1 != d2)
454             return Double.NaN;
455         /* max( +0.0,-0.0) == +0.0 */
456         if (d1 == 0.0
457                 && ((Double.doubleToLongBits(d1) & Double.doubleToLongBits(d2)) & 0x8000000000000000L) == 0)
458             return 0.0;
459         return d1;
460     }
461 
462     /**
463      * Returns the most positive (closest to positive infinity) of the two
464      * arguments.
465      * <p>
466      * Special cases:
467      * <ul>
468      * <li>{@code max(NaN, (anything)) = NaN}</li>
469      * <li>{@code max((anything), NaN) = NaN}</li>
470      * <li>{@code max(+0.0, -0.0) = +0.0}</li>
471      * <li>{@code max(-0.0, +0.0) = +0.0}</li>
472      * </ul>
473      */
max(float f1, float f2)474     public static float max(float f1, float f2) {
475         if (f1 > f2)
476             return f1;
477         if (f1 < f2)
478             return f2;
479         /* if either arg is NaN, return NaN */
480         if (f1 != f2)
481             return Float.NaN;
482         /* max( +0.0,-0.0) == +0.0 */
483         if (f1 == 0.0f
484                 && ((Float.floatToIntBits(f1) & Float.floatToIntBits(f2)) & 0x80000000) == 0)
485             return 0.0f;
486         return f1;
487     }
488 
489     /**
490      * Returns the most positive (closest to positive infinity) of the two
491      * arguments.
492      */
max(int i1, int i2)493     public static int max(int i1, int i2) {
494         return Math.max(i1, i2);
495     }
496 
497     /**
498      * Returns the most positive (closest to positive infinity) of the two
499      * arguments.
500      */
max(long l1, long l2)501     public static long max(long l1, long l2) {
502         return l1 > l2 ? l1 : l2;
503     }
504 
505     /**
506      * Returns the most negative (closest to negative infinity) of the two
507      * arguments.
508      * <p>
509      * Special cases:
510      * <ul>
511      * <li>{@code min(NaN, (anything)) = NaN}</li>
512      * <li>{@code min((anything), NaN) = NaN}</li>
513      * <li>{@code min(+0.0, -0.0) = -0.0}</li>
514      * <li>{@code min(-0.0, +0.0) = -0.0}</li>
515      * </ul>
516      */
min(double d1, double d2)517     public static double min(double d1, double d2) {
518         if (d1 > d2)
519             return d2;
520         if (d1 < d2)
521             return d1;
522         /* if either arg is NaN, return NaN */
523         if (d1 != d2)
524             return Double.NaN;
525         /* min( +0.0,-0.0) == -0.0 */
526         if (d1 == 0.0
527                 && ((Double.doubleToLongBits(d1) | Double.doubleToLongBits(d2)) & 0x8000000000000000l) != 0)
528             return 0.0 * (-1.0);
529         return d1;
530     }
531 
532     /**
533      * Returns the most negative (closest to negative infinity) of the two
534      * arguments.
535      * <p>
536      * Special cases:
537      * <ul>
538      * <li>{@code min(NaN, (anything)) = NaN}</li>
539      * <li>{@code min((anything), NaN) = NaN}</li>
540      * <li>{@code min(+0.0, -0.0) = -0.0}</li>
541      * <li>{@code min(-0.0, +0.0) = -0.0}</li>
542      * </ul>
543      */
min(float f1, float f2)544     public static float min(float f1, float f2) {
545         if (f1 > f2)
546             return f2;
547         if (f1 < f2)
548             return f1;
549         /* if either arg is NaN, return NaN */
550         if (f1 != f2)
551             return Float.NaN;
552         /* min( +0.0,-0.0) == -0.0 */
553         if (f1 == 0.0f
554                 && ((Float.floatToIntBits(f1) | Float.floatToIntBits(f2)) & 0x80000000) != 0)
555             return 0.0f * (-1.0f);
556         return f1;
557     }
558 
559     /**
560      * Returns the most negative (closest to negative infinity) of the two
561      * arguments.
562      */
min(int i1, int i2)563     public static int min(int i1, int i2) {
564         return Math.min(i1, i2);
565     }
566 
567     /**
568      * Returns the most negative (closest to negative infinity) of the two
569      * arguments.
570      */
min(long l1, long l2)571     public static long min(long l1, long l2) {
572         return l1 < l2 ? l1 : l2;
573     }
574 
575     /**
576      * Returns the closest double approximation of the result of raising
577      * {@code x} to the power of {@code y}.
578      * <p>
579      * Special cases:
580      * <ul>
581      * <li>{@code pow((anything), +0.0) = 1.0}</li>
582      * <li>{@code pow((anything), -0.0) = 1.0}</li>
583      * <li>{@code pow(x, 1.0) = x}</li>
584      * <li>{@code pow((anything), NaN) = NaN}</li>
585      * <li>{@code pow(NaN, (anything except 0)) = NaN}</li>
586      * <li>{@code pow(+/-(|x| > 1), +infinity) = +infinity}</li>
587      * <li>{@code pow(+/-(|x| > 1), -infinity) = +0.0}</li>
588      * <li>{@code pow(+/-(|x| < 1), +infinity) = +0.0}</li>
589      * <li>{@code pow(+/-(|x| < 1), -infinity) = +infinity}</li>
590      * <li>{@code pow(+/-1.0 , +infinity) = NaN}</li>
591      * <li>{@code pow(+/-1.0 , -infinity) = NaN}</li>
592      * <li>{@code pow(+0.0, (+anything except 0, NaN)) = +0.0}</li>
593      * <li>{@code pow(-0.0, (+anything except 0, NaN, odd integer)) = +0.0}</li>
594      * <li>{@code pow(+0.0, (-anything except 0, NaN)) = +infinity}</li>
595      * <li>{@code pow(-0.0, (-anything except 0, NAN, odd integer))} {@code =}
596      * {@code +infinity}</li>
597      * <li>{@code pow(-0.0, (odd integer)) = -pow( +0 , (odd integer) )}</li>
598      * <li>{@code pow(+infinity, (+anything except 0, NaN)) = +infinity}</li>
599      * <li>{@code pow(+infinity, (-anything except 0, NaN)) = +0.0}</li>
600      * <li>{@code pow(-infinity, (anything)) = -pow(0, (-anything))}</li>
601      * <li>{@code pow((-anything), (integer))} {@code =}
602      * {@code pow(-1,(integer))*pow(+anything,integer)}</li>
603      * <li>{@code pow((-anything except 0 and infinity), (non-integer))}
604      * {@code =} {@code NAN}</li>
605      * </ul>
606      *
607      * @param x
608      *            the base of the operation.
609      * @param y
610      *            the exponent of the operation.
611      * @return {@code x} to the power of {@code y}.
612      */
pow(double x, double y)613     public static native double pow(double x, double y);
614 
615     /**
616      * Returns a pseudo-random number between 0.0 (inclusive) and 1.0
617      * (exclusive).
618      *
619      * @return a pseudo-random number.
620      */
random()621     public static double random() {
622         return Math.random();
623     }
624 
625     /**
626      * Returns the double conversion of the result of rounding the argument to
627      * an integer. Tie breaks are rounded towards even.
628      * <p>
629      * Special cases:
630      * <ul>
631      * <li>{@code rint(+0.0) = +0.0}</li>
632      * <li>{@code rint(-0.0) = -0.0}</li>
633      * <li>{@code rint(+infinity) = +infinity}</li>
634      * <li>{@code rint(-infinity) = -infinity}</li>
635      * <li>{@code rint(NaN) = NaN}</li>
636      * </ul>
637      *
638      * @param d
639      *            the value to be rounded.
640      * @return the closest integer to the argument (as a double).
641      */
rint(double d)642     public static native double rint(double d);
643 
644     /**
645      * Returns the result of rounding the argument to an integer. The result is
646      * equivalent to {@code (long) Math.floor(d+0.5)}.
647      * <p>
648      * Special cases:
649      * <ul>
650      * <li>{@code round(+0.0) = +0.0}</li>
651      * <li>{@code round(-0.0) = +0.0}</li>
652      * <li>{@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}</li>
653      * <li>{@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}</li>
654      * <li>{@code round(+infinity) = Long.MAX_VALUE}</li>
655      * <li>{@code round(-infinity) = Long.MIN_VALUE}</li>
656      * <li>{@code round(NaN) = +0.0}</li>
657      * </ul>
658      *
659      * @param d
660      *            the value to be rounded.
661      * @return the closest integer to the argument.
662      */
round(double d)663     public static long round(double d) {
664         return Math.round(d);
665     }
666 
667     /**
668      * Returns the result of rounding the argument to an integer. The result is
669      * equivalent to {@code (int) Math.floor(f+0.5)}.
670      * <p>
671      * Special cases:
672      * <ul>
673      * <li>{@code round(+0.0) = +0.0}</li>
674      * <li>{@code round(-0.0) = +0.0}</li>
675      * <li>{@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}</li>
676      * <li>{@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}</li>
677      * <li>{@code round(+infinity) = Integer.MAX_VALUE}</li>
678      * <li>{@code round(-infinity) = Integer.MIN_VALUE}</li>
679      * <li>{@code round(NaN) = +0.0}</li>
680      * </ul>
681      *
682      * @param f
683      *            the value to be rounded.
684      * @return the closest integer to the argument.
685      */
round(float f)686     public static int round(float f) {
687         return Math.round(f);
688     }
689 
690     /**
691      * Returns the signum function of the argument. If the argument is less than
692      * zero, it returns -1.0. If the argument is greater than zero, 1.0 is
693      * returned. If the argument is either positive or negative zero, the
694      * argument is returned as result.
695      * <p>
696      * Special cases:
697      * <ul>
698      * <li>{@code signum(+0.0) = +0.0}</li>
699      * <li>{@code signum(-0.0) = -0.0}</li>
700      * <li>{@code signum(+infinity) = +1.0}</li>
701      * <li>{@code signum(-infinity) = -1.0}</li>
702      * <li>{@code signum(NaN) = NaN}</li>
703      * </ul>
704      *
705      * @param d
706      *            the value whose signum has to be computed.
707      * @return the value of the signum function.
708      */
signum(double d)709     public static double signum(double d){
710         return Math.signum(d);
711     }
712 
713     /**
714      * Returns the signum function of the argument. If the argument is less than
715      * zero, it returns -1.0. If the argument is greater than zero, 1.0 is
716      * returned. If the argument is either positive or negative zero, the
717      * argument is returned as result.
718      * <p>
719      * Special cases:
720      * <ul>
721      * <li>{@code signum(+0.0) = +0.0}</li>
722      * <li>{@code signum(-0.0) = -0.0}</li>
723      * <li>{@code signum(+infinity) = +1.0}</li>
724      * <li>{@code signum(-infinity) = -1.0}</li>
725      * <li>{@code signum(NaN) = NaN}</li>
726      * </ul>
727      *
728      * @param f
729      *            the value whose signum has to be computed.
730      * @return the value of the signum function.
731      */
signum(float f)732     public static float signum(float f){
733         return Math.signum(f);
734     }
735 
736     /**
737      * Returns the closest double approximation of the hyperbolic sine of the
738      * argument.
739      * <p>
740      * Special cases:
741      * <ul>
742      * <li>{@code sinh(+0.0) = +0.0}</li>
743      * <li>{@code sinh(-0.0) = -0.0}</li>
744      * <li>{@code sinh(+infinity) = +infinity}</li>
745      * <li>{@code sinh(-infinity) = -infinity}</li>
746      * <li>{@code sinh(NaN) = NaN}</li>
747      * </ul>
748      *
749      * @param d
750      *            the value whose hyperbolic sine has to be computed.
751      * @return the hyperbolic sine of the argument.
752      */
sinh(double d)753     public static native double sinh(double d);
754 
755     /**
756      * Returns the closest double approximation of the sine of the argument.
757      * <p>
758      * Special cases:
759      * <ul>
760      * <li>{@code sin(+0.0) = +0.0}</li>
761      * <li>{@code sin(-0.0) = -0.0}</li>
762      * <li>{@code sin(+infinity) = NaN}</li>
763      * <li>{@code sin(-infinity) = NaN}</li>
764      * <li>{@code sin(NaN) = NaN}</li>
765      * </ul>
766      *
767      * @param d
768      *            the angle whose sin has to be computed, in radians.
769      * @return the sine of the argument.
770      */
sin(double d)771     public static native double sin(double d);
772 
773     /**
774      * Returns the closest double approximation of the square root of the
775      * argument.
776      * <p>
777      * Special cases:
778      * <ul>
779      * <li>{@code sqrt(+0.0) = +0.0}</li>
780      * <li>{@code sqrt(-0.0) = -0.0}</li>
781      * <li>{@code sqrt( (anything < 0) ) = NaN}</li>
782      * <li>{@code sqrt(+infinity) = +infinity}</li>
783      * <li>{@code sqrt(NaN) = NaN}</li>
784      * </ul>
785      */
sqrt(double d)786     public static native double sqrt(double d);
787 
788     /**
789      * Returns the closest double approximation of the tangent of the argument.
790      * <p>
791      * Special cases:
792      * <ul>
793      * <li>{@code tan(+0.0) = +0.0}</li>
794      * <li>{@code tan(-0.0) = -0.0}</li>
795      * <li>{@code tan(+infinity) = NaN}</li>
796      * <li>{@code tan(-infinity) = NaN}</li>
797      * <li>{@code tan(NaN) = NaN}</li>
798      * </ul>
799      *
800      * @param d
801      *            the angle whose tangent has to be computed, in radians.
802      * @return the tangent of the argument.
803      */
tan(double d)804     public static native double tan(double d);
805 
806     /**
807      * Returns the closest double approximation of the hyperbolic tangent of the
808      * argument. The absolute value is always less than 1.
809      * <p>
810      * Special cases:
811      * <ul>
812      * <li>{@code tanh(+0.0) = +0.0}</li>
813      * <li>{@code tanh(-0.0) = -0.0}</li>
814      * <li>{@code tanh(+infinity) = +1.0}</li>
815      * <li>{@code tanh(-infinity) = -1.0}</li>
816      * <li>{@code tanh(NaN) = NaN}</li>
817      * </ul>
818      *
819      * @param d
820      *            the value whose hyperbolic tangent has to be computed.
821      * @return the hyperbolic tangent of the argument
822      */
tanh(double d)823     public static native double tanh(double d);
824 
825     /**
826      * Returns the measure in degrees of the supplied radian angle. The result
827      * is {@code angrad * 180 / pi}.
828      * <p>
829      * Special cases:
830      * <ul>
831      * <li>{@code toDegrees(+0.0) = +0.0}</li>
832      * <li>{@code toDegrees(-0.0) = -0.0}</li>
833      * <li>{@code toDegrees(+infinity) = +infinity}</li>
834      * <li>{@code toDegrees(-infinity) = -infinity}</li>
835      * <li>{@code toDegrees(NaN) = NaN}</li>
836      * </ul>
837      *
838      * @param angrad
839      *            an angle in radians.
840      * @return the degree measure of the angle.
841      */
toDegrees(double angrad)842     public static double toDegrees(double angrad) {
843         return Math.toDegrees(angrad);
844     }
845 
846     /**
847      * Returns the measure in radians of the supplied degree angle. The result
848      * is {@code angdeg / 180 * pi}.
849      * <p>
850      * Special cases:
851      * <ul>
852      * <li>{@code toRadians(+0.0) = +0.0}</li>
853      * <li>{@code toRadians(-0.0) = -0.0}</li>
854      * <li>{@code toRadians(+infinity) = +infinity}</li>
855      * <li>{@code toRadians(-infinity) = -infinity}</li>
856      * <li>{@code toRadians(NaN) = NaN}</li>
857      * </ul>
858      *
859      * @param angdeg
860      *            an angle in degrees.
861      * @return the radian measure of the angle.
862      */
toRadians(double angdeg)863     public static double toRadians(double angdeg) {
864         return Math.toRadians(angdeg);
865     }
866 
867     /**
868      * Returns the argument's ulp (unit in the last place). The size of a ulp of
869      * a double value is the positive distance between this value and the double
870      * value next larger in magnitude. For non-NaN {@code x},
871      * {@code ulp(-x) == ulp(x)}.
872      * <p>
873      * Special cases:
874      * <ul>
875      * <li>{@code ulp(+0.0) = Double.MIN_VALUE}</li>
876      * <li>{@code ulp(-0.0) = Double.MIN_VALUE}</li>
877      * <li>{@code ulp(+infinity) = infinity}</li>
878      * <li>{@code ulp(-infinity) = infinity}</li>
879      * <li>{@code ulp(NaN) = NaN}</li>
880      * </ul>
881      *
882      * @param d
883      *            the floating-point value to compute ulp of.
884      * @return the size of a ulp of the argument.
885      */
ulp(double d)886     public static double ulp(double d) {
887         // special cases
888         if (Double.isInfinite(d)) {
889             return Double.POSITIVE_INFINITY;
890         } else if (d == Double.MAX_VALUE || d == -Double.MAX_VALUE) {
891             return pow(2, 971);
892         }
893         d = Math.abs(d);
894         return nextafter(d, Double.MAX_VALUE) - d;
895     }
896 
897     /**
898      * Returns the argument's ulp (unit in the last place). The size of a ulp of
899      * a float value is the positive distance between this value and the float
900      * value next larger in magnitude. For non-NaN {@code x},
901      * {@code ulp(-x) == ulp(x)}.
902      * <p>
903      * Special cases:
904      * <ul>
905      * <li>{@code ulp(+0.0) = Float.MIN_VALUE}</li>
906      * <li>{@code ulp(-0.0) = Float.MIN_VALUE}</li>
907      * <li>{@code ulp(+infinity) = infinity}</li>
908      * <li>{@code ulp(-infinity) = infinity}</li>
909      * <li>{@code ulp(NaN) = NaN}</li>
910      * </ul>
911      *
912      * @param f
913      *            the floating-point value to compute ulp of.
914      * @return the size of a ulp of the argument.
915      */
ulp(float f)916     public static float ulp(float f) {
917         return Math.ulp(f);
918     }
919 
nextafter(double x, double y)920     private static native double nextafter(double x, double y);
921 
922     /**
923      * Returns a double with the given magnitude and the sign of {@code sign}.
924      * If {@code sign} is NaN, the sign of the result is positive.
925      * @since 1.6
926      */
copySign(double magnitude, double sign)927     public static double copySign(double magnitude, double sign) {
928         // We manually inline Double.isNaN here because the JIT can't do it yet.
929         // With Double.isNaN: 236.3ns
930         // With manual inline: 141.2ns
931         // With no check (i.e. Math's behavior): 110.0ns
932         // (Tested on a Nexus One.)
933         long magnitudeBits = Double.doubleToRawLongBits(magnitude);
934         long signBits = Double.doubleToRawLongBits((sign != sign) ? 1.0 : sign);
935         magnitudeBits = (magnitudeBits & ~Double.SIGN_MASK) | (signBits & Double.SIGN_MASK);
936         return Double.longBitsToDouble(magnitudeBits);
937     }
938 
939     /**
940      * Returns a float with the given magnitude and the sign of {@code sign}.
941      * If {@code sign} is NaN, the sign of the result is positive.
942      * @since 1.6
943      */
copySign(float magnitude, float sign)944     public static float copySign(float magnitude, float sign) {
945         // We manually inline Float.isNaN here because the JIT can't do it yet.
946         // With Float.isNaN: 214.7ns
947         // With manual inline: 112.3ns
948         // With no check (i.e. Math's behavior): 93.1ns
949         // (Tested on a Nexus One.)
950         int magnitudeBits = Float.floatToRawIntBits(magnitude);
951         int signBits = Float.floatToRawIntBits((sign != sign) ? 1.0f : sign);
952         magnitudeBits = (magnitudeBits & ~Float.SIGN_MASK) | (signBits & Float.SIGN_MASK);
953         return Float.intBitsToFloat(magnitudeBits);
954     }
955 
956     /**
957      * Returns the exponent of float {@code f}.
958      * @since 1.6
959      */
getExponent(float f)960     public static int getExponent(float f) {
961         return Math.getExponent(f);
962     }
963 
964     /**
965      * Returns the exponent of double {@code d}.
966      * @since 1.6
967      */
getExponent(double d)968     public static int getExponent(double d){
969         return Math.getExponent(d);
970     }
971 
972     /**
973      * Returns the next double after {@code start} in the given {@code direction}.
974      * @since 1.6
975      */
nextAfter(double start, double direction)976     public static double nextAfter(double start, double direction) {
977         if (start == 0 && direction == 0) {
978             return direction;
979         }
980         return nextafter(start, direction);
981     }
982 
983     /**
984      * Returns the next float after {@code start} in the given {@code direction}.
985      * @since 1.6
986      */
nextAfter(float start, double direction)987     public static float nextAfter(float start, double direction) {
988         return Math.nextAfter(start, direction);
989     }
990 
991     /**
992      * Returns the next double larger than {@code d}.
993      * @since 1.6
994      */
nextUp(double d)995     public static double nextUp(double d) {
996         return Math.nextUp(d);
997     }
998 
999     /**
1000      * Returns the next float larger than {@code f}.
1001      * @since 1.6
1002      */
nextUp(float f)1003     public static float nextUp(float f) {
1004         return Math.nextUp(f);
1005     }
1006 
1007     /**
1008      * Returns {@code d} * 2^{@code scaleFactor}. The result may be rounded.
1009      * @since 1.6
1010      */
scalb(double d, int scaleFactor)1011     public static double scalb(double d, int scaleFactor) {
1012         if (Double.isNaN(d) || Double.isInfinite(d) || d == 0) {
1013             return d;
1014         }
1015         // change double to long for calculation
1016         long bits = Double.doubleToLongBits(d);
1017         // the sign of the results must be the same of given d
1018         long sign = bits & Double.SIGN_MASK;
1019         // calculates the factor of the result
1020         long factor = (int) ((bits & Double.EXPONENT_MASK) >> Double.MANTISSA_BITS)
1021                 - Double.EXPONENT_BIAS + scaleFactor;
1022 
1023         // calculates the factor of sub-normal values
1024         int subNormalFactor = Long.numberOfLeadingZeros(bits & ~Double.SIGN_MASK)
1025                 - Double.EXPONENT_BITS;
1026         if (subNormalFactor < 0) {
1027             // not sub-normal values
1028             subNormalFactor = 0;
1029         }
1030         if (Math.abs(d) < Double.MIN_NORMAL) {
1031             factor = factor - subNormalFactor;
1032         }
1033         if (factor > Double.MAX_EXPONENT) {
1034             return (d > 0 ? Double.POSITIVE_INFINITY : Double.NEGATIVE_INFINITY);
1035         }
1036 
1037         long result;
1038         // if result is a sub-normal
1039         if (factor < -Double.EXPONENT_BIAS) {
1040             // the number of digits that shifts
1041             long digits = factor + Double.EXPONENT_BIAS + subNormalFactor;
1042             if (Math.abs(d) < Double.MIN_NORMAL) {
1043                 // origin d is already sub-normal
1044                 result = shiftLongBits(bits & Double.MANTISSA_MASK, digits);
1045             } else {
1046                 // origin d is not sub-normal, change mantissa to sub-normal
1047                 result = shiftLongBits(bits & Double.MANTISSA_MASK | 0x0010000000000000L, digits - 1);
1048             }
1049         } else {
1050             if (Math.abs(d) >= Double.MIN_NORMAL) {
1051                 // common situation
1052                 result = ((factor + Double.EXPONENT_BIAS) << Double.MANTISSA_BITS)
1053                         | (bits & Double.MANTISSA_MASK);
1054             } else {
1055                 // origin d is sub-normal, change mantissa to normal style
1056                 result = ((factor + Double.EXPONENT_BIAS) << Double.MANTISSA_BITS)
1057                         | ((bits << (subNormalFactor + 1)) & Double.MANTISSA_MASK);
1058             }
1059         }
1060         return Double.longBitsToDouble(result | sign);
1061     }
1062 
1063     /**
1064      * Returns {@code d} * 2^{@code scaleFactor}. The result may be rounded.
1065      * @since 1.6
1066      */
scalb(float d, int scaleFactor)1067     public static float scalb(float d, int scaleFactor) {
1068         if (Float.isNaN(d) || Float.isInfinite(d) || d == 0) {
1069             return d;
1070         }
1071         int bits = Float.floatToIntBits(d);
1072         int sign = bits & Float.SIGN_MASK;
1073         int factor = ((bits & Float.EXPONENT_MASK) >> Float.MANTISSA_BITS)
1074                 - Float.EXPONENT_BIAS + scaleFactor;
1075         // calculates the factor of sub-normal values
1076         int subNormalFactor = Integer.numberOfLeadingZeros(bits & ~Float.SIGN_MASK)
1077                 - Float.EXPONENT_BITS;
1078         if (subNormalFactor < 0) {
1079             // not sub-normal values
1080             subNormalFactor = 0;
1081         }
1082         if (Math.abs(d) < Float.MIN_NORMAL) {
1083             factor = factor - subNormalFactor;
1084         }
1085         if (factor > Float.MAX_EXPONENT) {
1086             return (d > 0 ? Float.POSITIVE_INFINITY : Float.NEGATIVE_INFINITY);
1087         }
1088 
1089         int result;
1090         // if result is a sub-normal
1091         if (factor < -Float.EXPONENT_BIAS) {
1092             // the number of digits that shifts
1093             int digits = factor + Float.EXPONENT_BIAS + subNormalFactor;
1094             if (Math.abs(d) < Float.MIN_NORMAL) {
1095                 // origin d is already sub-normal
1096                 result = shiftIntBits(bits & Float.MANTISSA_MASK, digits);
1097             } else {
1098                 // origin d is not sub-normal, change mantissa to sub-normal
1099                 result = shiftIntBits(bits & Float.MANTISSA_MASK | 0x00800000, digits - 1);
1100             }
1101         } else {
1102             if (Math.abs(d) >= Float.MIN_NORMAL) {
1103                 // common situation
1104                 result = ((factor + Float.EXPONENT_BIAS) << Float.MANTISSA_BITS)
1105                         | (bits & Float.MANTISSA_MASK);
1106             } else {
1107                 // origin d is sub-normal, change mantissa to normal style
1108                 result = ((factor + Float.EXPONENT_BIAS) << Float.MANTISSA_BITS)
1109                         | ((bits << (subNormalFactor + 1)) & Float.MANTISSA_MASK);
1110             }
1111         }
1112         return Float.intBitsToFloat(result | sign);
1113     }
1114 
1115     // Shifts integer bits as float, if the digits is positive, left-shift; if
1116     // not, shift to right and calculate its carry.
shiftIntBits(int bits, int digits)1117     private static int shiftIntBits(int bits, int digits) {
1118         if (digits > 0) {
1119             return bits << digits;
1120         }
1121         // change it to positive
1122         int absDigits = -digits;
1123         if (Integer.numberOfLeadingZeros(bits & ~Float.SIGN_MASK) <= (32 - absDigits)) {
1124             // some bits will remain after shifting, calculates its carry
1125             if ((((bits >> (absDigits - 1)) & 0x1) == 0)
1126                     || Integer.numberOfTrailingZeros(bits) == (absDigits - 1)) {
1127                 return bits >> absDigits;
1128             }
1129             return ((bits >> absDigits) + 1);
1130         }
1131         return 0;
1132     }
1133 
1134     // Shifts long bits as double, if the digits is positive, left-shift; if
1135     // not, shift to right and calculate its carry.
shiftLongBits(long bits, long digits)1136     private static long shiftLongBits(long bits, long digits) {
1137         if (digits > 0) {
1138             return bits << digits;
1139         }
1140         // change it to positive
1141         long absDigits = -digits;
1142         if (Long.numberOfLeadingZeros(bits & ~Double.SIGN_MASK) <= (64 - absDigits)) {
1143             // some bits will remain after shifting, calculates its carry
1144             if ((((bits >> (absDigits - 1)) & 0x1) == 0)
1145                     || Long.numberOfTrailingZeros(bits) == (absDigits - 1)) {
1146                 return bits >> absDigits;
1147             }
1148             return ((bits >> absDigits) + 1);
1149         }
1150         return 0;
1151     }
1152 }
1153