001 /* java.lang.Math -- common mathematical functions, native allowed
002 Copyright (C) 1998, 2001, 2002, 2003, 2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.lang;
040
041 import gnu.classpath.Configuration;
042
043 import java.util.Random;
044
045 /**
046 * Helper class containing useful mathematical functions and constants.
047 * <P>
048 *
049 * Note that angles are specified in radians. Conversion functions are
050 * provided for your convenience.
051 *
052 * @author Paul Fisher
053 * @author John Keiser
054 * @author Eric Blake (ebb9@email.byu.edu)
055 * @since 1.0
056 */
057 public final class Math
058 {
059 /**
060 * Math is non-instantiable
061 */
062 private Math()
063 {
064 }
065
066 static
067 {
068 if (Configuration.INIT_LOAD_LIBRARY)
069 {
070 System.loadLibrary("javalang");
071 }
072 }
073
074 /**
075 * A random number generator, initialized on first use.
076 */
077 private static Random rand;
078
079 /**
080 * The most accurate approximation to the mathematical constant <em>e</em>:
081 * <code>2.718281828459045</code>. Used in natural log and exp.
082 *
083 * @see #log(double)
084 * @see #exp(double)
085 */
086 public static final double E = 2.718281828459045;
087
088 /**
089 * The most accurate approximation to the mathematical constant <em>pi</em>:
090 * <code>3.141592653589793</code>. This is the ratio of a circle's diameter
091 * to its circumference.
092 */
093 public static final double PI = 3.141592653589793;
094
095 /**
096 * Take the absolute value of the argument.
097 * (Absolute value means make it positive.)
098 * <P>
099 *
100 * Note that the the largest negative value (Integer.MIN_VALUE) cannot
101 * be made positive. In this case, because of the rules of negation in
102 * a computer, MIN_VALUE is what will be returned.
103 * This is a <em>negative</em> value. You have been warned.
104 *
105 * @param i the number to take the absolute value of
106 * @return the absolute value
107 * @see Integer#MIN_VALUE
108 */
109 public static int abs(int i)
110 {
111 return (i < 0) ? -i : i;
112 }
113
114 /**
115 * Take the absolute value of the argument.
116 * (Absolute value means make it positive.)
117 * <P>
118 *
119 * Note that the the largest negative value (Long.MIN_VALUE) cannot
120 * be made positive. In this case, because of the rules of negation in
121 * a computer, MIN_VALUE is what will be returned.
122 * This is a <em>negative</em> value. You have been warned.
123 *
124 * @param l the number to take the absolute value of
125 * @return the absolute value
126 * @see Long#MIN_VALUE
127 */
128 public static long abs(long l)
129 {
130 return (l < 0) ? -l : l;
131 }
132
133 /**
134 * Take the absolute value of the argument.
135 * (Absolute value means make it positive.)
136 * <P>
137 *
138 * This is equivalent, but faster than, calling
139 * <code>Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))</code>.
140 *
141 * @param f the number to take the absolute value of
142 * @return the absolute value
143 */
144 public static float abs(float f)
145 {
146 return (f <= 0) ? 0 - f : f;
147 }
148
149 /**
150 * Take the absolute value of the argument.
151 * (Absolute value means make it positive.)
152 *
153 * This is equivalent, but faster than, calling
154 * <code>Double.longBitsToDouble(Double.doubleToLongBits(a)
155 * << 1) >>> 1);</code>.
156 *
157 * @param d the number to take the absolute value of
158 * @return the absolute value
159 */
160 public static double abs(double d)
161 {
162 return (d <= 0) ? 0 - d : d;
163 }
164
165 /**
166 * Return whichever argument is smaller.
167 *
168 * @param a the first number
169 * @param b a second number
170 * @return the smaller of the two numbers
171 */
172 public static int min(int a, int b)
173 {
174 return (a < b) ? a : b;
175 }
176
177 /**
178 * Return whichever argument is smaller.
179 *
180 * @param a the first number
181 * @param b a second number
182 * @return the smaller of the two numbers
183 */
184 public static long min(long a, long b)
185 {
186 return (a < b) ? a : b;
187 }
188
189 /**
190 * Return whichever argument is smaller. If either argument is NaN, the
191 * result is NaN, and when comparing 0 and -0, -0 is always smaller.
192 *
193 * @param a the first number
194 * @param b a second number
195 * @return the smaller of the two numbers
196 */
197 public static float min(float a, float b)
198 {
199 // this check for NaN, from JLS 15.21.1, saves a method call
200 if (a != a)
201 return a;
202 // no need to check if b is NaN; < will work correctly
203 // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
204 if (a == 0 && b == 0)
205 return -(-a - b);
206 return (a < b) ? a : b;
207 }
208
209 /**
210 * Return whichever argument is smaller. If either argument is NaN, the
211 * result is NaN, and when comparing 0 and -0, -0 is always smaller.
212 *
213 * @param a the first number
214 * @param b a second number
215 * @return the smaller of the two numbers
216 */
217 public static double min(double a, double b)
218 {
219 // this check for NaN, from JLS 15.21.1, saves a method call
220 if (a != a)
221 return a;
222 // no need to check if b is NaN; < will work correctly
223 // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
224 if (a == 0 && b == 0)
225 return -(-a - b);
226 return (a < b) ? a : b;
227 }
228
229 /**
230 * Return whichever argument is larger.
231 *
232 * @param a the first number
233 * @param b a second number
234 * @return the larger of the two numbers
235 */
236 public static int max(int a, int b)
237 {
238 return (a > b) ? a : b;
239 }
240
241 /**
242 * Return whichever argument is larger.
243 *
244 * @param a the first number
245 * @param b a second number
246 * @return the larger of the two numbers
247 */
248 public static long max(long a, long b)
249 {
250 return (a > b) ? a : b;
251 }
252
253 /**
254 * Return whichever argument is larger. If either argument is NaN, the
255 * result is NaN, and when comparing 0 and -0, 0 is always larger.
256 *
257 * @param a the first number
258 * @param b a second number
259 * @return the larger of the two numbers
260 */
261 public static float max(float a, float b)
262 {
263 // this check for NaN, from JLS 15.21.1, saves a method call
264 if (a != a)
265 return a;
266 // no need to check if b is NaN; > will work correctly
267 // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
268 if (a == 0 && b == 0)
269 return a - -b;
270 return (a > b) ? a : b;
271 }
272
273 /**
274 * Return whichever argument is larger. If either argument is NaN, the
275 * result is NaN, and when comparing 0 and -0, 0 is always larger.
276 *
277 * @param a the first number
278 * @param b a second number
279 * @return the larger of the two numbers
280 */
281 public static double max(double a, double b)
282 {
283 // this check for NaN, from JLS 15.21.1, saves a method call
284 if (a != a)
285 return a;
286 // no need to check if b is NaN; > will work correctly
287 // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
288 if (a == 0 && b == 0)
289 return a - -b;
290 return (a > b) ? a : b;
291 }
292
293 /**
294 * The trigonometric function <em>sin</em>. The sine of NaN or infinity is
295 * NaN, and the sine of 0 retains its sign. This is accurate within 1 ulp,
296 * and is semi-monotonic.
297 *
298 * @param a the angle (in radians)
299 * @return sin(a)
300 */
301 public static native double sin(double a);
302
303 /**
304 * The trigonometric function <em>cos</em>. The cosine of NaN or infinity is
305 * NaN. This is accurate within 1 ulp, and is semi-monotonic.
306 *
307 * @param a the angle (in radians)
308 * @return cos(a)
309 */
310 public static native double cos(double a);
311
312 /**
313 * The trigonometric function <em>tan</em>. The tangent of NaN or infinity
314 * is NaN, and the tangent of 0 retains its sign. This is accurate within 1
315 * ulp, and is semi-monotonic.
316 *
317 * @param a the angle (in radians)
318 * @return tan(a)
319 */
320 public static native double tan(double a);
321
322 /**
323 * The trigonometric function <em>arcsin</em>. The range of angles returned
324 * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN or
325 * its absolute value is beyond 1, the result is NaN; and the arcsine of
326 * 0 retains its sign. This is accurate within 1 ulp, and is semi-monotonic.
327 *
328 * @param a the sin to turn back into an angle
329 * @return arcsin(a)
330 */
331 public static native double asin(double a);
332
333 /**
334 * The trigonometric function <em>arccos</em>. The range of angles returned
335 * is 0 to pi radians (0 to 180 degrees). If the argument is NaN or
336 * its absolute value is beyond 1, the result is NaN. This is accurate
337 * within 1 ulp, and is semi-monotonic.
338 *
339 * @param a the cos to turn back into an angle
340 * @return arccos(a)
341 */
342 public static native double acos(double a);
343
344 /**
345 * The trigonometric function <em>arcsin</em>. The range of angles returned
346 * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN, the
347 * result is NaN; and the arctangent of 0 retains its sign. This is accurate
348 * within 1 ulp, and is semi-monotonic.
349 *
350 * @param a the tan to turn back into an angle
351 * @return arcsin(a)
352 * @see #atan2(double, double)
353 */
354 public static native double atan(double a);
355
356 /**
357 * A special version of the trigonometric function <em>arctan</em>, for
358 * converting rectangular coordinates <em>(x, y)</em> to polar
359 * <em>(r, theta)</em>. This computes the arctangent of x/y in the range
360 * of -pi to pi radians (-180 to 180 degrees). Special cases:<ul>
361 * <li>If either argument is NaN, the result is NaN.</li>
362 * <li>If the first argument is positive zero and the second argument is
363 * positive, or the first argument is positive and finite and the second
364 * argument is positive infinity, then the result is positive zero.</li>
365 * <li>If the first argument is negative zero and the second argument is
366 * positive, or the first argument is negative and finite and the second
367 * argument is positive infinity, then the result is negative zero.</li>
368 * <li>If the first argument is positive zero and the second argument is
369 * negative, or the first argument is positive and finite and the second
370 * argument is negative infinity, then the result is the double value
371 * closest to pi.</li>
372 * <li>If the first argument is negative zero and the second argument is
373 * negative, or the first argument is negative and finite and the second
374 * argument is negative infinity, then the result is the double value
375 * closest to -pi.</li>
376 * <li>If the first argument is positive and the second argument is
377 * positive zero or negative zero, or the first argument is positive
378 * infinity and the second argument is finite, then the result is the
379 * double value closest to pi/2.</li>
380 * <li>If the first argument is negative and the second argument is
381 * positive zero or negative zero, or the first argument is negative
382 * infinity and the second argument is finite, then the result is the
383 * double value closest to -pi/2.</li>
384 * <li>If both arguments are positive infinity, then the result is the
385 * double value closest to pi/4.</li>
386 * <li>If the first argument is positive infinity and the second argument
387 * is negative infinity, then the result is the double value closest to
388 * 3*pi/4.</li>
389 * <li>If the first argument is negative infinity and the second argument
390 * is positive infinity, then the result is the double value closest to
391 * -pi/4.</li>
392 * <li>If both arguments are negative infinity, then the result is the
393 * double value closest to -3*pi/4.</li>
394 *
395 * </ul><p>This is accurate within 2 ulps, and is semi-monotonic. To get r,
396 * use sqrt(x*x+y*y).
397 *
398 * @param y the y position
399 * @param x the x position
400 * @return <em>theta</em> in the conversion of (x, y) to (r, theta)
401 * @see #atan(double)
402 */
403 public static native double atan2(double y, double x);
404
405 /**
406 * Take <em>e</em><sup>a</sup>. The opposite of <code>log()</code>. If the
407 * argument is NaN, the result is NaN; if the argument is positive infinity,
408 * the result is positive infinity; and if the argument is negative
409 * infinity, the result is positive zero. This is accurate within 1 ulp,
410 * and is semi-monotonic.
411 *
412 * @param a the number to raise to the power
413 * @return the number raised to the power of <em>e</em>
414 * @see #log(double)
415 * @see #pow(double, double)
416 */
417 public static native double exp(double a);
418
419 /**
420 * Take ln(a) (the natural log). The opposite of <code>exp()</code>. If the
421 * argument is NaN or negative, the result is NaN; if the argument is
422 * positive infinity, the result is positive infinity; and if the argument
423 * is either zero, the result is negative infinity. This is accurate within
424 * 1 ulp, and is semi-monotonic.
425 *
426 * <p>Note that the way to get log<sub>b</sub>(a) is to do this:
427 * <code>ln(a) / ln(b)</code>.
428 *
429 * @param a the number to take the natural log of
430 * @return the natural log of <code>a</code>
431 * @see #exp(double)
432 */
433 public static native double log(double a);
434
435 /**
436 * Take a square root. If the argument is NaN or negative, the result is
437 * NaN; if the argument is positive infinity, the result is positive
438 * infinity; and if the result is either zero, the result is the same.
439 * This is accurate within the limits of doubles.
440 *
441 * <p>For other roots, use pow(a, 1 / rootNumber).
442 *
443 * @param a the numeric argument
444 * @return the square root of the argument
445 * @see #pow(double, double)
446 */
447 public static native double sqrt(double a);
448
449 /**
450 * Raise a number to a power. Special cases:<ul>
451 * <li>If the second argument is positive or negative zero, then the result
452 * is 1.0.</li>
453 * <li>If the second argument is 1.0, then the result is the same as the
454 * first argument.</li>
455 * <li>If the second argument is NaN, then the result is NaN.</li>
456 * <li>If the first argument is NaN and the second argument is nonzero,
457 * then the result is NaN.</li>
458 * <li>If the absolute value of the first argument is greater than 1 and
459 * the second argument is positive infinity, or the absolute value of the
460 * first argument is less than 1 and the second argument is negative
461 * infinity, then the result is positive infinity.</li>
462 * <li>If the absolute value of the first argument is greater than 1 and
463 * the second argument is negative infinity, or the absolute value of the
464 * first argument is less than 1 and the second argument is positive
465 * infinity, then the result is positive zero.</li>
466 * <li>If the absolute value of the first argument equals 1 and the second
467 * argument is infinite, then the result is NaN.</li>
468 * <li>If the first argument is positive zero and the second argument is
469 * greater than zero, or the first argument is positive infinity and the
470 * second argument is less than zero, then the result is positive zero.</li>
471 * <li>If the first argument is positive zero and the second argument is
472 * less than zero, or the first argument is positive infinity and the
473 * second argument is greater than zero, then the result is positive
474 * infinity.</li>
475 * <li>If the first argument is negative zero and the second argument is
476 * greater than zero but not a finite odd integer, or the first argument is
477 * negative infinity and the second argument is less than zero but not a
478 * finite odd integer, then the result is positive zero.</li>
479 * <li>If the first argument is negative zero and the second argument is a
480 * positive finite odd integer, or the first argument is negative infinity
481 * and the second argument is a negative finite odd integer, then the result
482 * is negative zero.</li>
483 * <li>If the first argument is negative zero and the second argument is
484 * less than zero but not a finite odd integer, or the first argument is
485 * negative infinity and the second argument is greater than zero but not a
486 * finite odd integer, then the result is positive infinity.</li>
487 * <li>If the first argument is negative zero and the second argument is a
488 * negative finite odd integer, or the first argument is negative infinity
489 * and the second argument is a positive finite odd integer, then the result
490 * is negative infinity.</li>
491 * <li>If the first argument is less than zero and the second argument is a
492 * finite even integer, then the result is equal to the result of raising
493 * the absolute value of the first argument to the power of the second
494 * argument.</li>
495 * <li>If the first argument is less than zero and the second argument is a
496 * finite odd integer, then the result is equal to the negative of the
497 * result of raising the absolute value of the first argument to the power
498 * of the second argument.</li>
499 * <li>If the first argument is finite and less than zero and the second
500 * argument is finite and not an integer, then the result is NaN.</li>
501 * <li>If both arguments are integers, then the result is exactly equal to
502 * the mathematical result of raising the first argument to the power of
503 * the second argument if that result can in fact be represented exactly as
504 * a double value.</li>
505 *
506 * </ul><p>(In the foregoing descriptions, a floating-point value is
507 * considered to be an integer if and only if it is a fixed point of the
508 * method {@link #ceil(double)} or, equivalently, a fixed point of the
509 * method {@link #floor(double)}. A value is a fixed point of a one-argument
510 * method if and only if the result of applying the method to the value is
511 * equal to the value.) This is accurate within 1 ulp, and is semi-monotonic.
512 *
513 * @param a the number to raise
514 * @param b the power to raise it to
515 * @return a<sup>b</sup>
516 */
517 public static native double pow(double a, double b);
518
519 /**
520 * Get the IEEE 754 floating point remainder on two numbers. This is the
521 * value of <code>x - y * <em>n</em></code>, where <em>n</em> is the closest
522 * double to <code>x / y</code> (ties go to the even n); for a zero
523 * remainder, the sign is that of <code>x</code>. If either argument is NaN,
524 * the first argument is infinite, or the second argument is zero, the result
525 * is NaN; if x is finite but y is infinite, the result is x. This is
526 * accurate within the limits of doubles.
527 *
528 * @param x the dividend (the top half)
529 * @param y the divisor (the bottom half)
530 * @return the IEEE 754-defined floating point remainder of x/y
531 * @see #rint(double)
532 */
533 public static native double IEEEremainder(double x, double y);
534
535 /**
536 * Take the nearest integer that is that is greater than or equal to the
537 * argument. If the argument is NaN, infinite, or zero, the result is the
538 * same; if the argument is between -1 and 0, the result is negative zero.
539 * Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
540 *
541 * @param a the value to act upon
542 * @return the nearest integer >= <code>a</code>
543 */
544 public static native double ceil(double a);
545
546 /**
547 * Take the nearest integer that is that is less than or equal to the
548 * argument. If the argument is NaN, infinite, or zero, the result is the
549 * same. Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
550 *
551 * @param a the value to act upon
552 * @return the nearest integer <= <code>a</code>
553 */
554 public static native double floor(double a);
555
556 /**
557 * Take the nearest integer to the argument. If it is exactly between
558 * two integers, the even integer is taken. If the argument is NaN,
559 * infinite, or zero, the result is the same.
560 *
561 * @param a the value to act upon
562 * @return the nearest integer to <code>a</code>
563 */
564 public static native double rint(double a);
565
566 /**
567 * Take the nearest integer to the argument. This is equivalent to
568 * <code>(int) Math.floor(a + 0.5f)</code>. If the argument is NaN, the result
569 * is 0; otherwise if the argument is outside the range of int, the result
570 * will be Integer.MIN_VALUE or Integer.MAX_VALUE, as appropriate.
571 *
572 * @param a the argument to round
573 * @return the nearest integer to the argument
574 * @see Integer#MIN_VALUE
575 * @see Integer#MAX_VALUE
576 */
577 public static int round(float a)
578 {
579 // this check for NaN, from JLS 15.21.1, saves a method call
580 if (a != a)
581 return 0;
582 return (int) floor(a + 0.5f);
583 }
584
585 /**
586 * Take the nearest long to the argument. This is equivalent to
587 * <code>(long) Math.floor(a + 0.5)</code>. If the argument is NaN, the
588 * result is 0; otherwise if the argument is outside the range of long, the
589 * result will be Long.MIN_VALUE or Long.MAX_VALUE, as appropriate.
590 *
591 * @param a the argument to round
592 * @return the nearest long to the argument
593 * @see Long#MIN_VALUE
594 * @see Long#MAX_VALUE
595 */
596 public static long round(double a)
597 {
598 // this check for NaN, from JLS 15.21.1, saves a method call
599 if (a != a)
600 return 0;
601 return (long) floor(a + 0.5d);
602 }
603
604 /**
605 * Get a random number. This behaves like Random.nextDouble(), seeded by
606 * System.currentTimeMillis() when first called. In other words, the number
607 * is from a pseudorandom sequence, and lies in the range [+0.0, 1.0).
608 * This random sequence is only used by this method, and is threadsafe,
609 * although you may want your own random number generator if it is shared
610 * among threads.
611 *
612 * @return a random number
613 * @see Random#nextDouble()
614 * @see System#currentTimeMillis()
615 */
616 public static synchronized double random()
617 {
618 if (rand == null)
619 rand = new Random();
620 return rand.nextDouble();
621 }
622
623 /**
624 * Convert from degrees to radians. The formula for this is
625 * radians = degrees * (pi/180); however it is not always exact given the
626 * limitations of floating point numbers.
627 *
628 * @param degrees an angle in degrees
629 * @return the angle in radians
630 * @since 1.2
631 */
632 public static double toRadians(double degrees)
633 {
634 return (degrees * PI) / 180;
635 }
636
637 /**
638 * Convert from radians to degrees. The formula for this is
639 * degrees = radians * (180/pi); however it is not always exact given the
640 * limitations of floating point numbers.
641 *
642 * @param rads an angle in radians
643 * @return the angle in degrees
644 * @since 1.2
645 */
646 public static double toDegrees(double rads)
647 {
648 return (rads * 180) / PI;
649 }
650
651 /**
652 * <p>
653 * Take a cube root. If the argument is <code>NaN</code>, an infinity or
654 * zero, then the original value is returned. The returned result is
655 * within 1 ulp of the exact result. For a finite value, <code>x</code>,
656 * the cube root of <code>-x</code> is equal to the negation of the cube root
657 * of <code>x</code>.
658 * </p>
659 * <p>
660 * For a square root, use <code>sqrt</code>. For other roots, use
661 * <code>pow(a, 1 / rootNumber)</code>.
662 * </p>
663 *
664 * @param a the numeric argument
665 * @return the cube root of the argument
666 * @see #sqrt(double)
667 * @see #pow(double, double)
668 * @since 1.5
669 */
670 public static native double cbrt(double a);
671
672 /**
673 * <p>
674 * Returns the hyperbolic cosine of the given value. For a value,
675 * <code>x</code>, the hyperbolic cosine is <code>(e<sup>x</sup> +
676 * e<sup>-x</sup>)/2</code>
677 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
678 * result is within 2.5 ulps of the exact result.
679 * </p>
680 * <p>
681 * If the supplied value is <code>NaN</code>, then the original value is
682 * returned. For either infinity, positive infinity is returned.
683 * The hyperbolic cosine of zero is 1.0.
684 * </p>
685 *
686 * @param a the numeric argument
687 * @return the hyperbolic cosine of <code>a</code>.
688 * @since 1.5
689 */
690 public static native double cosh(double a);
691
692 /**
693 * <p>
694 * Returns <code>e<sup>a</sup> - 1. For values close to 0, the
695 * result of <code>expm1(a) + 1</code> tend to be much closer to the
696 * exact result than simply <code>exp(x)</code>. The result is within
697 * 1 ulp of the exact result, and results are semi-monotonic. For finite
698 * inputs, the returned value is greater than or equal to -1.0. Once
699 * a result enters within half a ulp of this limit, the limit is returned.
700 * </p>
701 * <p>
702 * For <code>NaN</code>, positive infinity and zero, the original value
703 * is returned. Negative infinity returns a result of -1.0 (the limit).
704 * </p>
705 *
706 * @param a the numeric argument
707 * @return <code>e<sup>a</sup> - 1</code>
708 * @since 1.5
709 */
710 public static native double expm1(double a);
711
712 /**
713 * <p>
714 * Returns the hypotenuse, <code>a<sup>2</sup> + b<sup>2</sup></code>,
715 * without intermediate overflow or underflow. The returned result is
716 * within 1 ulp of the exact result. If one parameter is held constant,
717 * then the result in the other parameter is semi-monotonic.
718 * </p>
719 * <p>
720 * If either of the arguments is an infinity, then the returned result
721 * is positive infinity. Otherwise, if either argument is <code>NaN</code>,
722 * then <code>NaN</code> is returned.
723 * </p>
724 *
725 * @param a the first parameter.
726 * @param b the second parameter.
727 * @return the hypotenuse matching the supplied parameters.
728 * @since 1.5
729 */
730 public static native double hypot(double a, double b);
731
732 /**
733 * <p>
734 * Returns the base 10 logarithm of the supplied value. The returned
735 * result is within 1 ulp of the exact result, and the results are
736 * semi-monotonic.
737 * </p>
738 * <p>
739 * Arguments of either <code>NaN</code> or less than zero return
740 * <code>NaN</code>. An argument of positive infinity returns positive
741 * infinity. Negative infinity is returned if either positive or negative
742 * zero is supplied. Where the argument is the result of
743 * <code>10<sup>n</sup</code>, then <code>n</code> is returned.
744 * </p>
745 *
746 * @param a the numeric argument.
747 * @return the base 10 logarithm of <code>a</code>.
748 * @since 1.5
749 */
750 public static native double log10(double a);
751
752 /**
753 * <p>
754 * Returns the natural logarithm resulting from the sum of the argument,
755 * <code>a</code> and 1. For values close to 0, the
756 * result of <code>log1p(a)</code> tend to be much closer to the
757 * exact result than simply <code>log(1.0+a)</code>. The returned
758 * result is within 1 ulp of the exact result, and the results are
759 * semi-monotonic.
760 * </p>
761 * <p>
762 * Arguments of either <code>NaN</code> or less than -1 return
763 * <code>NaN</code>. An argument of positive infinity or zero
764 * returns the original argument. Negative infinity is returned from an
765 * argument of -1.
766 * </p>
767 *
768 * @param a the numeric argument.
769 * @return the natural logarithm of <code>a</code> + 1.
770 * @since 1.5
771 */
772 public static native double log1p(double a);
773
774 /**
775 * <p>
776 * Returns the sign of the argument as follows:
777 * </p>
778 * <ul>
779 * <li>If <code>a</code> is greater than zero, the result is 1.0.</li>
780 * <li>If <code>a</code> is less than zero, the result is -1.0.</li>
781 * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>.
782 * <li>If <code>a</code> is positive or negative zero, the result is the
783 * same.</li>
784 * </ul>
785 *
786 * @param a the numeric argument.
787 * @return the sign of the argument.
788 * @since 1.5.
789 */
790 public static double signum(double a)
791 {
792 if (Double.isNaN(a))
793 return Double.NaN;
794 if (a > 0)
795 return 1.0;
796 if (a < 0)
797 return -1.0;
798 return a;
799 }
800
801 /**
802 * <p>
803 * Returns the sign of the argument as follows:
804 * </p>
805 * <ul>
806 * <li>If <code>a</code> is greater than zero, the result is 1.0f.</li>
807 * <li>If <code>a</code> is less than zero, the result is -1.0f.</li>
808 * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>.
809 * <li>If <code>a</code> is positive or negative zero, the result is the
810 * same.</li>
811 * </ul>
812 *
813 * @param a the numeric argument.
814 * @return the sign of the argument.
815 * @since 1.5.
816 */
817 public static float signum(float a)
818 {
819 if (Float.isNaN(a))
820 return Float.NaN;
821 if (a > 0)
822 return 1.0f;
823 if (a < 0)
824 return -1.0f;
825 return a;
826 }
827
828 /**
829 * <p>
830 * Returns the hyperbolic sine of the given value. For a value,
831 * <code>x</code>, the hyperbolic sine is <code>(e<sup>x</sup> -
832 * e<sup>-x</sup>)/2</code>
833 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
834 * result is within 2.5 ulps of the exact result.
835 * </p>
836 * <p>
837 * If the supplied value is <code>NaN</code>, an infinity or a zero, then the
838 * original value is returned.
839 * </p>
840 *
841 * @param a the numeric argument
842 * @return the hyperbolic sine of <code>a</code>.
843 * @since 1.5
844 */
845 public static native double sinh(double a);
846
847 /**
848 * <p>
849 * Returns the hyperbolic tangent of the given value. For a value,
850 * <code>x</code>, the hyperbolic tangent is <code>(e<sup>x</sup> -
851 * e<sup>-x</sup>)/(e<sup>x</sup> + e<sup>-x</sup>)</code>
852 * (i.e. <code>sinh(a)/cosh(a)</code>)
853 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
854 * result is within 2.5 ulps of the exact result. The absolute value
855 * of the exact result is always less than 1. Computed results are thus
856 * less than or equal to 1 for finite arguments, with results within
857 * half a ulp of either positive or negative 1 returning the appropriate
858 * limit value (i.e. as if the argument was an infinity).
859 * </p>
860 * <p>
861 * If the supplied value is <code>NaN</code> or zero, then the original
862 * value is returned. Positive infinity returns +1.0 and negative infinity
863 * returns -1.0.
864 * </p>
865 *
866 * @param a the numeric argument
867 * @return the hyperbolic tangent of <code>a</code>.
868 * @since 1.5
869 */
870 public static native double tanh(double a);
871
872 /**
873 * Return the ulp for the given double argument. The ulp is the
874 * difference between the argument and the next larger double. Note
875 * that the sign of the double argument is ignored, that is,
876 * ulp(x) == ulp(-x). If the argument is a NaN, then NaN is returned.
877 * If the argument is an infinity, then +Inf is returned. If the
878 * argument is zero (either positive or negative), then
879 * {@link Double#MIN_VALUE} is returned.
880 * @param d the double whose ulp should be returned
881 * @return the difference between the argument and the next larger double
882 * @since 1.5
883 */
884 public static double ulp(double d)
885 {
886 if (Double.isNaN(d))
887 return d;
888 if (Double.isInfinite(d))
889 return Double.POSITIVE_INFINITY;
890 // This handles both +0.0 and -0.0.
891 if (d == 0.0)
892 return Double.MIN_VALUE;
893 long bits = Double.doubleToLongBits(d);
894 final int mantissaBits = 52;
895 final int exponentBits = 11;
896 final long mantMask = (1L << mantissaBits) - 1;
897 long mantissa = bits & mantMask;
898 final long expMask = (1L << exponentBits) - 1;
899 long exponent = (bits >>> mantissaBits) & expMask;
900
901 // Denormal number, so the answer is easy.
902 if (exponent == 0)
903 {
904 long result = (exponent << mantissaBits) | 1L;
905 return Double.longBitsToDouble(result);
906 }
907
908 // Conceptually we want to have '1' as the mantissa. Then we would
909 // shift the mantissa over to make a normal number. If this underflows
910 // the exponent, we will make a denormal result.
911 long newExponent = exponent - mantissaBits;
912 long newMantissa;
913 if (newExponent > 0)
914 newMantissa = 0;
915 else
916 {
917 newMantissa = 1L << -(newExponent - 1);
918 newExponent = 0;
919 }
920 return Double.longBitsToDouble((newExponent << mantissaBits) | newMantissa);
921 }
922
923 /**
924 * Return the ulp for the given float argument. The ulp is the
925 * difference between the argument and the next larger float. Note
926 * that the sign of the float argument is ignored, that is,
927 * ulp(x) == ulp(-x). If the argument is a NaN, then NaN is returned.
928 * If the argument is an infinity, then +Inf is returned. If the
929 * argument is zero (either positive or negative), then
930 * {@link Float#MIN_VALUE} is returned.
931 * @param f the float whose ulp should be returned
932 * @return the difference between the argument and the next larger float
933 * @since 1.5
934 */
935 public static float ulp(float f)
936 {
937 if (Float.isNaN(f))
938 return f;
939 if (Float.isInfinite(f))
940 return Float.POSITIVE_INFINITY;
941 // This handles both +0.0 and -0.0.
942 if (f == 0.0)
943 return Float.MIN_VALUE;
944 int bits = Float.floatToIntBits(f);
945 final int mantissaBits = 23;
946 final int exponentBits = 8;
947 final int mantMask = (1 << mantissaBits) - 1;
948 int mantissa = bits & mantMask;
949 final int expMask = (1 << exponentBits) - 1;
950 int exponent = (bits >>> mantissaBits) & expMask;
951
952 // Denormal number, so the answer is easy.
953 if (exponent == 0)
954 {
955 int result = (exponent << mantissaBits) | 1;
956 return Float.intBitsToFloat(result);
957 }
958
959 // Conceptually we want to have '1' as the mantissa. Then we would
960 // shift the mantissa over to make a normal number. If this underflows
961 // the exponent, we will make a denormal result.
962 int newExponent = exponent - mantissaBits;
963 int newMantissa;
964 if (newExponent > 0)
965 newMantissa = 0;
966 else
967 {
968 newMantissa = 1 << -(newExponent - 1);
969 newExponent = 0;
970 }
971 return Float.intBitsToFloat((newExponent << mantissaBits) | newMantissa);
972 }
973 }