StrictMath


1   /*
2    * @(#)StrictMath.java  1.26 04/06/14
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.lang;
9   import java.util.Random  ;
10  import sun.misc.FpUtils;
11  
12  /**
13   * The class <code>StrictMath</code> contains methods for performing basic 
14   * numeric operations such as the elementary exponential, logarithm, 
15   * square root, and trigonometric functions. 
16   * 
17   * <p>To help ensure portability of Java programs, the definitions of
18   * some of the numeric functions in this package require that they
19   * produce the same results as certain published algorithms. These
20   * algorithms are available from the well-known network library
21   * <code>netlib</code> as the package "Freely Distributable Math
22   * Library," <a
23   * HREF="ftp://ftp.netlib.org/fdlibm.tar"><code>fdlibm</code></a>. These
24   * algorithms, which are written in the C programming language, are
25   * then to be understood as executed with all floating-point
26   * operations following the rules of Java floating-point arithmetic.
27   * 
28   * <p>The Java math library is defined with respect to
29   * <code>fdlibm</code> version 5.3. Where <code>fdlibm</code> provides
30   * more than one definition for a function (such as
31   * <code>acos</code>), use the "IEEE 754 core function" version
32   * (residing in a file whose name begins with the letter
33   * <code>e</code>).  The methods which require <code>fdlibm</code>
34   * semantics are <code>sin</code>, <code>cos</code>, <code>tan</code>,
35   * <code>asin</code>, <code>acos</code>, <code>atan</code>,
36   * <code>exp</code>, <code>log</code>, <code>log10</code>,
37   * <code>cbrt</code>, <code>atan2</code>, <code>pow</code>,
38   * <code>sinh</code>, <code>cosh</code>, <code>tanh</code>,
39   * <code>hypot</code>, <code>expm1</code>, and <code>log1p</code>.
40   *
41   * @author  unascribed
42   * @author  Joseph D. Darcy
43   * @version 1.26, 06/14/04
44   * @since   1.3
45   */
46  
47  public final class StrictMath {
48  
49      /**
50       * Don't let anyone instantiate this class.
51       */
52      private StrictMath() {}
53  
54      /**
55       * The <code>double</code> value that is closer than any other to
56       * <i>e</i>, the base of the natural logarithms.
57       */
58      public static final double E = 2.7182818284590452354;
59  
60      /**
61       * The <code>double</code> value that is closer than any other to
62       * <i>pi</i>, the ratio of the circumference of a circle to its
63       * diameter.
64       */
65      public static final double PI = 3.14159265358979323846;
66  
67      /**
68       * Returns the trigonometric sine of an angle. Special cases:
69       * <ul><li>If the argument is NaN or an infinity, then the 
70       * result is NaN.
71       * <li>If the argument is zero, then the result is a zero with the
72       * same sign as the argument.</ul>
73       *
74       * @param   a   an angle, in radians.
75       * @return  the sine of the argument.
76       */
77      public static native double sin(double a);
78      
79      /**
80       * Returns the trigonometric cosine of an angle. Special cases:
81       * <ul><li>If the argument is NaN or an infinity, then the 
82       * result is NaN.</ul>
83       *
84       * @param   a   an angle, in radians.
85       * @return  the cosine of the argument.
86       */
87      public static native double cos(double a);
88     
89      /**
90       * Returns the trigonometric tangent of an angle. Special cases:
91       * <ul><li>If the argument is NaN or an infinity, then the result 
92       * is NaN.
93       * <li>If the argument is zero, then the result is a zero with the
94       * same sign as the argument.</ul>
95       *
96       * @param   a   an angle, in radians.
97       * @return  the tangent of the argument.
98       */
99      public static native double tan(double a);
100 
101     /**
102      * Returns the arc sine of an angle, in the range of -<i>pi</i>/2 through
103      * <i>pi</i>/2. Special cases: 
104      * <ul><li>If the argument is NaN or its absolute value is greater 
105      * than 1, then the result is NaN.
106      * <li>If the argument is zero, then the result is a zero with the
107      * same sign as the argument.</ul>
108      *
109      * @param   a   the value whose arc sine is to be returned.
110      * @return  the arc sine of the argument.
111      */
112     public static native double asin(double a);
113 
114     /**
115      * Returns the arc cosine of an angle, in the range of 0.0 through
116      * <i>pi</i>. Special case:
117      * <ul><li>If the argument is NaN or its absolute value is greater 
118      * than 1, then the result is NaN.</ul>
119      *
120      * @param   a   the value whose arc cosine is to be returned.
121      * @return  the arc cosine of the argument.
122      */
123     public static native double acos(double a); 
124 
125     /**
126      * Returns the arc tangent of an angle, in the range of -<i>pi</i>/2
127      * through <i>pi</i>/2. Special cases: 
128      * <ul><li>If the argument is NaN, then the result is NaN.
129      * <li>If the argument is zero, then the result is a zero with the
130      * same sign as the argument.</ul>
131      *
132      * @param   a   the value whose arc tangent is to be returned.
133      * @return  the arc tangent of the argument.
134      */
135     public static native double atan(double a);
136 
137     /**
138      * Converts an angle measured in degrees to an approximately
139      * equivalent angle measured in radians.  The conversion from
140      * degrees to radians is generally inexact.
141      *
142      * @param   angdeg   an angle, in degrees
143      * @return  the measurement of the angle <code>angdeg</code>
144      *          in radians.
145      */
146     public static strictfp double toRadians(double angdeg) {
147     return angdeg / 180.0 * PI;
148     }
149 
150     /**
151      * Converts an angle measured in radians to an approximately
152      * equivalent angle measured in degrees.  The conversion from
153      * radians to degrees is generally inexact; users should
154      * <i>not</i> expect <code>cos(toRadians(90.0))</code> to exactly
155      * equal <code>0.0</code>.
156      *
157      * @param   angrad   an angle, in radians
158      * @return  the measurement of the angle <code>angrad</code>
159      *          in degrees.
160      */
161     public static strictfp double toDegrees(double angrad) {
162     return angrad * 180.0 / PI;
163     }
164 
165     /**
166      * Returns Euler's number <i>e</i> raised to the power of a
167      * <code>double</code> value. Special cases:
168      * <ul><li>If the argument is NaN, the result is NaN.
169      * <li>If the argument is positive infinity, then the result is 
170      * positive infinity.
171      * <li>If the argument is negative infinity, then the result is 
172      * positive zero.</ul>
173      *
174      * @param   a   the exponent to raise <i>e</i> to.
175      * @return  the value <i>e</i><sup><code>a</code></sup>, 
176      *      where <i>e</i> is the base of the natural logarithms.
177      */
178     public static native double exp(double a);
179 
180     /**
181      * Returns the natural logarithm (base <i>e</i>) of a <code>double</code>
182      * value. Special cases:
183      * <ul><li>If the argument is NaN or less than zero, then the result 
184      * is NaN.
185      * <li>If the argument is positive infinity, then the result is 
186      * positive infinity.
187      * <li>If the argument is positive zero or negative zero, then the 
188      * result is negative infinity.</ul>
189      *
190      * @param   a   a value
191      * @return  the value ln&nbsp;<code>a</code>, the natural logarithm of
192      *          <code>a</code>.
193      */
194     public static native double log(double a);
195 
196 
197     /**
198      * Returns the base 10 logarithm of a <code>double</code> value.
199      * Special cases:
200      *
201      * <ul><li>If the argument is NaN or less than zero, then the result 
202      * is NaN.
203      * <li>If the argument is positive infinity, then the result is 
204      * positive infinity.
205      * <li>If the argument is positive zero or negative zero, then the 
206      * result is negative infinity.
207      * <li> If the argument is equal to 10<sup><i>n</i></sup> for
208      * integer <i>n</i>, then the result is <i>n</i>.
209      * </ul>
210      *
211      * @param   a   a value
212      * @return  the base 10 logarithm of  <code>a</code>.
213      * @since 1.5
214      */
215     public static native double log10(double a);
216 
217     /**
218      * Returns the correctly rounded positive square root of a
219      * <code>double</code> value.
220      * Special cases:
221      * <ul><li>If the argument is NaN or less than zero, then the result 
222      * is NaN. 
223      * <li>If the argument is positive infinity, then the result is positive 
224      * infinity. 
225      * <li>If the argument is positive zero or negative zero, then the 
226      * result is the same as the argument.</ul>
227      * Otherwise, the result is the <code>double</code> value closest to 
228      * the true mathematical square root of the argument value.
229      *
230      * @param   a   a value.
231      * @return  the positive square root of <code>a</code>.
232      */
233     public static native double sqrt(double a);
234 
235     /**
236      * Returns the cube root of a <code>double</code> value.  For
237      * positive finite <code>x</code>, <code>cbrt(-x) ==
238      * -cbrt(x)</code>; that is, the cube root of a negative value is
239      * the negative of the cube root of that value's magnitude.
240      * Special cases: 
241      *
242      * <ul>
243      *
244      * <li>If the argument is NaN, then the result is NaN.
245      *
246      * <li>If the argument is infinite, then the result is an infinity
247      * with the same sign as the argument.
248      *
249      * <li>If the argument is zero, then the result is a zero with the
250      * same sign as the argument.
251      * 
252      * </ul>
253      *
254      * @param   a   a value.
255      * @return  the cube root of <code>a</code>.
256      * @since 1.5
257      */
258     public static native double cbrt(double a);
259 
260     /**
261      * Computes the remainder operation on two arguments as prescribed 
262      * by the IEEE 754 standard.
263      * The remainder value is mathematically equal to 
264      * <code>f1&nbsp;-&nbsp;f2</code>&nbsp;&times;&nbsp;<i>n</i>,
265      * where <i>n</i> is the mathematical integer closest to the exact 
266      * mathematical value of the quotient <code>f1/f2</code>, and if two 
267      * mathematical integers are equally close to <code>f1/f2</code>, 
268      * then <i>n</i> is the integer that is even. If the remainder is 
269      * zero, its sign is the same as the sign of the first argument. 
270      * Special cases:
271      * <ul><li>If either argument is NaN, or the first argument is infinite, 
272      * or the second argument is positive zero or negative zero, then the 
273      * result is NaN.
274      * <li>If the first argument is finite and the second argument is 
275      * infinite, then the result is the same as the first argument.</ul>
276      *
277      * @param   f1   the dividend.
278      * @param   f2   the divisor.
279      * @return  the remainder when <code>f1</code> is divided by
280      *          <code>f2</code>.
281      */
282     public static native double IEEEremainder(double f1, double f2);
283 
284     /**
285      * Returns the smallest (closest to negative infinity)
286      * <code>double</code> value that is greater than or equal to the
287      * argument and is equal to a mathematical integer. Special cases:
288      * <ul><li>If the argument value is already equal to a
289      * mathematical integer, then the result is the same as the
290      * argument.  <li>If the argument is NaN or an infinity or
291      * positive zero or negative zero, then the result is the same as
292      * the argument.  <li>If the argument value is less than zero but
293      * greater than -1.0, then the result is negative zero.</ul> Note
294      * that the value of <code>StrictMath.ceil(x)</code> is exactly the
295      * value of <code>-StrictMath.floor(-x)</code>.
296      *
297      * @param   a   a value.
298      * @return  the smallest (closest to negative infinity) 
299      *          floating-point value that is greater than or equal to
300      *          the argument and is equal to a mathematical integer. 
301      */
302     public static native double ceil(double a);
303 
304     /**
305      * Returns the largest (closest to positive infinity)
306      * <code>double</code> value that is less than or equal to the
307      * argument and is equal to a mathematical integer. Special cases:
308      * <ul><li>If the argument value is already equal to a
309      * mathematical integer, then the result is the same as the
310      * argument.  <li>If the argument is NaN or an infinity or
311      * positive zero or negative zero, then the result is the same as
312      * the argument.</ul>
313      *
314      * @param   a   a value.
315      * @return  the largest (closest to positive infinity) 
316      *          floating-point value that less than or equal to the argument
317      *          and is equal to a mathematical integer. 
318      */
319     public static native double floor(double a);
320 
321     /**
322      * Returns the <code>double</code> value that is closest in value
323      * to the argument and is equal to a mathematical integer. If two
324      * <code>double</code> values that are mathematical integers are
325      * equally close to the value of the argument, the result is the
326      * integer value that is even. Special cases:
327      * <ul><li>If the argument value is already equal to a mathematical 
328      * integer, then the result is the same as the argument. 
329      * <li>If the argument is NaN or an infinity or positive zero or negative 
330      * zero, then the result is the same as the argument.</ul>
331      *
332      * @param   a   a value.
333      * @return  the closest floating-point value to <code>a</code> that is
334      *          equal to a mathematical integer.
335      * @author Joseph D. Darcy
336      */
337     public static double rint(double a) {
338     /*
339      * If the absolute value of a is not less than 2^52, it
340      * is either a finite integer (the double format does not have
341      * enough significand bits for a number that large to have any
342      * fractional portion), an infinity, or a NaN.  In any of
343      * these cases, rint of the argument is the argument.
344      *
345      * Otherwise, the sum (twoToThe52 + a ) will properly round
346      * away any fractional portion of a since ulp(twoToThe52) ==
347      * 1.0; subtracting out twoToThe52 from this sum will then be
348      * exact and leave the rounded integer portion of a.
349      *
350      * This method does *not* need to be declared strictfp to get
351      * fully reproducible results.  Whether or not a method is
352      * declared strictfp can only make a difference in the
353      * returned result if some operation would overflow or
354      * underflow with strictfp semantics.  The operation
355      * (twoToThe52 + a ) cannot overflow since large values of a
356      * are screened out; the add cannot underflow since twoToThe52
357      * is too large.  The subtraction ((twoToThe52 + a ) -
358      * twoToThe52) will be exact as discussed above and thus
359      * cannot overflow or meaningfully underflow.  Finally, the
360      * last multiply in the return statement is by plus or minus
361      * 1.0, which is exact too.
362      */
363     double twoToThe52 = (double)(1L << 52); // 2^52
364     double sign = FpUtils.rawCopySign(1.0, a); // preserve sign info
365     a = Math.abs(a);
366     
367     if (a < twoToThe52) { // E_min <= ilogb(a) <= 51
368         a = ((twoToThe52 + a ) - twoToThe52);
369     } 
370     
371     return sign * a; // restore original sign
372     }
373 
374     /**
375      * Converts rectangular coordinates (<code>x</code>,&nbsp;<code>y</code>)
376      * to polar (r,&nbsp;<i>theta</i>).
377      * This method computes the phase <i>theta</i> by computing an arc tangent
378      * of <code>y/x</code> in the range of -<i>pi</i> to <i>pi</i>. Special 
379      * cases:
380      * <ul><li>If either argument is NaN, then the result is NaN. 
381      * <li>If the first argument is positive zero and the second argument 
382      * is positive, or the first argument is positive and finite and the 
383      * second argument is positive infinity, then the result is positive 
384      * zero. 
385      * <li>If the first argument is negative zero and the second argument 
386      * is positive, or the first argument is negative and finite and the 
387      * second argument is positive infinity, then the result is negative zero. 
388      * <li>If the first argument is positive zero and the second argument 
389      * is negative, or the first argument is positive and finite and the 
390      * second argument is negative infinity, then the result is the 
391      * <code>double</code> value closest to <i>pi</i>. 
392      * <li>If the first argument is negative zero and the second argument 
393      * is negative, or the first argument is negative and finite and the 
394      * second argument is negative infinity, then the result is the 
395      * <code>double</code> value closest to -<i>pi</i>. 
396      * <li>If the first argument is positive and the second argument is 
397      * positive zero or negative zero, or the first argument is positive 
398      * infinity and the second argument is finite, then the result is the 
399      * <code>double</code> value closest to <i>pi</i>/2. 
400      * <li>If the first argument is negative and the second argument is 
401      * positive zero or negative zero, or the first argument is negative 
402      * infinity and the second argument is finite, then the result is the 
403      * <code>double</code> value closest to -<i>pi</i>/2. 
404      * <li>If both arguments are positive infinity, then the result is the 
405      * <code>double</code> value closest to <i>pi</i>/4. 
406      * <li>If the first argument is positive infinity and the second argument 
407      * is negative infinity, then the result is the <code>double</code> 
408      * value closest to 3*<i>pi</i>/4. 
409      * <li>If the first argument is negative infinity and the second argument 
410      * is positive infinity, then the result is the <code>double</code> value 
411      * closest to -<i>pi</i>/4. 
412      * <li>If both arguments are negative infinity, then the result is the 
413      * <code>double</code> value closest to -3*<i>pi</i>/4.</ul>
414      *
415      * @param   y   the ordinate coordinate
416      * @param   x   the abscissa coordinate
417      * @return  the <i>theta</i> component of the point
418      *          (<i>r</i>,&nbsp;<i>theta</i>)
419      *          in polar coordinates that corresponds to the point
420      *          (<i>x</i>,&nbsp;<i>y</i>) in Cartesian coordinates.
421      */
422     public static native double atan2(double y, double x);
423 
424 
425     /**
426      * Returns the value of the first argument raised to the power of the
427      * second argument. Special cases:
428      *
429      * <ul><li>If the second argument is positive or negative zero, then the 
430      * result is 1.0. 
431      * <li>If the second argument is 1.0, then the result is the same as the 
432      * first argument.
433      * <li>If the second argument is NaN, then the result is NaN. 
434      * <li>If the first argument is NaN and the second argument is nonzero, 
435      * then the result is NaN. 
436      *
437      * <li>If
438      * <ul>
439      * <li>the absolute value of the first argument is greater than 1
440      * and the second argument is positive infinity, or
441      * <li>the absolute value of the first argument is less than 1 and
442      * the second argument is negative infinity,
443      * </ul>
444      * then the result is positive infinity. 
445      *
446      * <li>If 
447      * <ul>
448      * <li>the absolute value of the first argument is greater than 1 and 
449      * the second argument is negative infinity, or 
450      * <li>the absolute value of the 
451      * first argument is less than 1 and the second argument is positive 
452      * infinity,
453      * </ul>
454      * then the result is positive zero. 
455      *
456      * <li>If the absolute value of the first argument equals 1 and the 
457      * second argument is infinite, then the result is NaN. 
458      *
459      * <li>If 
460      * <ul>
461      * <li>the first argument is positive zero and the second argument
462      * is greater than zero, or
463      * <li>the first argument is positive infinity and the second
464      * argument is less than zero,
465      * </ul>
466      * then the result is positive zero. 
467      *
468      * <li>If 
469      * <ul>
470      * <li>the first argument is positive zero and the second argument
471      * is less than zero, or
472      * <li>the first argument is positive infinity and the second
473      * argument is greater than zero,
474      * </ul>
475      * then the result is positive infinity.
476      *
477      * <li>If 
478      * <ul>
479      * <li>the first argument is negative zero and the second argument
480      * is greater than zero but not a finite odd integer, or
481      * <li>the first argument is negative infinity and the second
482      * argument is less than zero but not a finite odd integer,
483      * </ul>
484      * then the result is positive zero. 
485      *
486      * <li>If 
487      * <ul>
488      * <li>the first argument is negative zero and the second argument
489      * is a positive finite odd integer, or
490      * <li>the first argument is negative infinity and the second
491      * argument is a negative finite odd integer,
492      * </ul>
493      * then the result is negative zero. 
494      *
495      * <li>If
496      * <ul>
497      * <li>the first argument is negative zero and the second argument
498      * is less than zero but not a finite odd integer, or
499      * <li>the first argument is negative infinity and the second
500      * argument is greater than zero but not a finite odd integer,
501      * </ul>
502      * then the result is positive infinity. 
503      *
504      * <li>If 
505      * <ul>
506      * <li>the first argument is negative zero and the second argument
507      * is a negative finite odd integer, or
508      * <li>the first argument is negative infinity and the second
509      * argument is a positive finite odd integer,
510      * </ul>
511      * then the result is negative infinity. 
512      *
513      * <li>If the first argument is finite and less than zero
514      * <ul>
515      * <li> if the second argument is a finite even integer, the
516      * result is equal to the result of raising the absolute value of
517      * the first argument to the power of the second argument
518      *
519      * <li>if the second argument is a finite odd integer, the result
520      * is equal to the negative of the result of raising the absolute
521      * value of the first argument to the power of the second
522      * argument
523      *
524      * <li>if the second argument is finite and not an integer, then
525      * the result is NaN.
526      * </ul>
527      *
528      * <li>If both arguments are integers, then the result is exactly equal 
529      * to the mathematical result of raising the first argument to the power 
530      * of the second argument if that result can in fact be represented 
531      * exactly as a <code>double</code> value.</ul>
532      * 
533      * <p>(In the foregoing descriptions, a floating-point value is
534      * considered to be an integer if and only if it is finite and a
535      * fixed point of the method {@link #ceil <tt>ceil</tt>} or,
536      * equivalently, a fixed point of the method {@link #floor
537      * <tt>floor</tt>}. A value is a fixed point of a one-argument
538      * method if and only if the result of applying the method to the
539      * value is equal to the value.)
540      *
541      * @param   a   base.
542      * @param   b   the exponent.
543      * @return  the value <code>a<sup>b</sup></code>.
544      */
545     public static native double pow(double a, double b);
546 
547     /**
548      * Returns the closest <code>int</code> to the argument. The 
549      * result is rounded to an integer by adding 1/2, taking the 
550      * floor of the result, and casting the result to type <code>int</code>. 
551      * In other words, the result is equal to the value of the expression:
552      * <p><pre>(int)Math.floor(a + 0.5f)</pre>
553      * <p>
554      * Special cases:
555      * <ul><li>If the argument is NaN, the result is 0.
556      * <li>If the argument is negative infinity or any value less than or 
557      * equal to the value of <code>Integer.MIN_VALUE</code>, the result is 
558      * equal to the value of <code>Integer.MIN_VALUE</code>. 
559      * <li>If the argument is positive infinity or any value greater than or 
560      * equal to the value of <code>Integer.MAX_VALUE</code>, the result is 
561      * equal to the value of <code>Integer.MAX_VALUE</code>.</ul> 
562      *
563      * @param   a   a floating-point value to be rounded to an integer.
564      * @return  the value of the argument rounded to the nearest
565      *          <code>int</code> value.
566      * @see     java.lang.Integer#MAX_VALUE
567      * @see     java.lang.Integer#MIN_VALUE
568      */
569     public static int round(float a) {
570     return (int)floor(a + 0.5f);
571     }
572 
573     /**
574      * Returns the closest <code>long</code> to the argument. The result 
575      * is rounded to an integer by adding 1/2, taking the floor of the 
576      * result, and casting the result to type <code>long</code>. In other 
577      * words, the result is equal to the value of the expression:
578      * <p><pre>(long)Math.floor(a + 0.5d)</pre>
579      * <p>
580      * Special cases:
581      * <ul><li>If the argument is NaN, the result is 0.
582      * <li>If the argument is negative infinity or any value less than or 
583      * equal to the value of <code>Long.MIN_VALUE</code>, the result is 
584      * equal to the value of <code>Long.MIN_VALUE</code>. 
585      * <li>If the argument is positive infinity or any value greater than or 
586      * equal to the value of <code>Long.MAX_VALUE</code>, the result is 
587      * equal to the value of <code>Long.MAX_VALUE</code>.</ul> 
588      *
589      * @param   a  a floating-point value to be rounded to a
590      *      <code>long</code>. 
591      * @return  the value of the argument rounded to the nearest
592      *          <code>long</code> value.
593      * @see     java.lang.Long#MAX_VALUE
594      * @see     java.lang.Long#MIN_VALUE
595      */
596     public static long round(double a) {
597     return (long)floor(a + 0.5d);
598     }
599 
600     private static Random   randomNumberGenerator;
601 
602     private static synchronized void initRNG() {
603         if (randomNumberGenerator == null) 
604             randomNumberGenerator = new Random  ();
605     }
606 
607     /**
608      * Returns a <code>double</code> value with a positive sign, greater 
609      * than or equal to <code>0.0</code> and less than <code>1.0</code>. 
610      * Returned values are chosen pseudorandomly with (approximately) 
611      * uniform distribution from that range. 
612      * 
613      * <p>When this method is first called, it creates a single new
614      * pseudorandom-number generator, exactly as if by the expression
615      * <blockquote><pre>new java.util.Random</pre></blockquote> This
616      * new pseudorandom-number generator is used thereafter for all
617      * calls to this method and is used nowhere else.
618      * 
619      * <p>This method is properly synchronized to allow correct use by
620      * more than one thread. However, if many threads need to generate
621      * pseudorandom numbers at a great rate, it may reduce contention
622      * for each thread to have its own pseudorandom number generator.
623      *  
624      * @return  a pseudorandom <code>double</code> greater than or equal 
625      * to <code>0.0</code> and less than <code>1.0</code>.
626      * @see     java.util.Random#nextDouble()
627      */
628     public static double random() {
629         if (randomNumberGenerator == null) initRNG();
630         return randomNumberGenerator.nextDouble();
631     }
632 
633     /**
634      * Returns the absolute value of an <code>int</code> value..
635      * If the argument is not negative, the argument is returned.
636      * If the argument is negative, the negation of the argument is returned. 
637      * 
638      * <p>Note that if the argument is equal to the value of
639      * <code>Integer.MIN_VALUE</code>, the most negative representable
640      * <code>int</code> value, the result is that same value, which is
641      * negative.
642      *
643      * @param   a   the  argument whose absolute value is to be determined.
644      * @return  the absolute value of the argument.
645      * @see     java.lang.Integer#MIN_VALUE
646      */
647     public static int abs(int a) {
648     return (a < 0) ? -a : a;
649     }
650 
651     /**
652      * Returns the absolute value of a <code>long</code> 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      * <code>Long.MIN_VALUE</code>, the most negative representable
658      * <code>long</code> value, the result is that same value, which
659      * is negative.
660      *
661      * @param   a   the  argument whose absolute value is to be determined.
662      * @return  the absolute value of the argument.
663      * @see     java.lang.Long#MIN_VALUE
664      */
665     public static long abs(long a) {
666     return (a < 0) ? -a : a;
667     }
668 
669     /**
670      * Returns the absolute value of a <code>float</code> value. 
671      * If the argument is not negative, the argument is returned.
672      * If the argument is negative, the negation of the argument is returned. 
673      * Special cases:
674      * <ul><li>If the argument is positive zero or negative zero, the 
675      * result is positive zero. 
676      * <li>If the argument is infinite, the result is positive infinity. 
677      * <li>If the argument is NaN, the result is NaN.</ul>
678      * In other words, the result is the same as the value of the expression: 
679      * <p><pre>Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))</pre>
680      *
681      * @param   a   the argument whose absolute value is to be determined
682      * @return  the absolute value of the argument.
683      */
684     public static float abs(float a) {
685         return (a <= 0.0F) ? 0.0F - a : a;
686     }
687   
688     /**
689      * Returns the absolute value of a <code>double</code> value.
690      * If the argument is not negative, the argument is returned.
691      * If the argument is negative, the negation of the argument is returned. 
692      * Special cases:
693      * <ul><li>If the argument is positive zero or negative zero, the result 
694      * is positive zero. 
695      * <li>If the argument is infinite, the result is positive infinity. 
696      * <li>If the argument is NaN, the result is NaN.</ul>
697      * In other words, the result is the same as the value of the expression: 
698      * <p><code>Double.longBitsToDouble((Double.doubleToLongBits(a)&lt;&lt;1)&gt;&gt;&gt;1)</code>
699      *
700      * @param   a   the argument whose absolute value is to be determined
701      * @return  the absolute value of the argument.
702      */
703     public static double abs(double a) {
704         return (a <= 0.0D) ? 0.0D - a : a;
705     }
706 
707     /**
708      * Returns the greater of two <code>int</code> values. That is, the 
709      * result is the argument closer to the value of 
710      * <code>Integer.MAX_VALUE</code>. If the arguments have the same value, 
711      * the result is that same value.
712      *
713      * @param   a   an argument.
714      * @param   b   another argument.
715      * @return  the larger of <code>a</code> and <code>b</code>.
716      * @see     java.lang.Long#MAX_VALUE
717      */
718     public static int max(int a, int b) {
719     return (a >= b) ? a : b;
720     }
721 
722     /**
723      * Returns the greater of two <code>long</code> values. That is, the 
724      * result is the argument closer to the value of 
725      * <code>Long.MAX_VALUE</code>. If the arguments have the same value, 
726      * the result is that same value. 
727      *
728      * @param   a   an argument.
729      * @param   b   another argument.
730      * @return  the larger of <code>a</code> and <code>b</code>.
731      * @see     java.lang.Long#MAX_VALUE
732      */
733     public static long max(long a, long b) {
734     return (a >= b) ? a : b;
735     }
736 
737     private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
738     private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
739 
740     /**
741      * Returns the greater of two <code>float</code> values.  That is,
742      * the result is the argument closer to positive infinity. If the
743      * arguments have the same value, the result is that same
744      * value. If either value is NaN, then the result is NaN.  Unlike
745      * the numerical comparison operators, this method considers
746      * negative zero to be strictly smaller than positive zero. If one
747      * argument is positive zero and the other negative zero, the
748      * result is positive zero.
749      *
750      * @param   a   an argument.
751      * @param   b   another argument.
752      * @return  the larger of <code>a</code> and <code>b</code>.
753      */
754     public static float max(float a, float b) {
755         if (a != a) return a;   // a is NaN
756     if ((a == 0.0f) && (b == 0.0f)
757         && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
758         return b;
759     }
760     return (a >= b) ? a : b;
761     }
762 
763     /**
764      * Returns the greater of two <code>double</code> values.  That
765      * is, the result is the argument closer to positive infinity. If
766      * the arguments have the same value, the result is that same
767      * value. If either value is NaN, then the result is NaN.  Unlike
768      * the numerical comparison operators, this method considers
769      * negative zero to be strictly smaller than positive zero. If one
770      * argument is positive zero and the other negative zero, the
771      * result is positive zero.
772      *
773      * @param   a   an argument.
774      * @param   b   another argument.
775      * @return  the larger of <code>a</code> and <code>b</code>.
776      */
777     public static double max(double a, double b) {
778         if (a != a) return a;   // a is NaN
779     if ((a == 0.0d) && (b == 0.0d)
780         && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
781         return b;
782     }
783     return (a >= b) ? a : b;
784     }
785 
786     /**
787      * Returns the smaller of two <code>int</code> values. That is,
788      * the result the argument closer to the value of
789      * <code>Integer.MIN_VALUE</code>.  If the arguments have the same
790      * value, the result is that same value.
791      *
792      * @param   a   an argument.
793      * @param   b   another argument.
794      * @return  the smaller of <code>a</code> and <code>b</code>.
795      * @see     java.lang.Long#MIN_VALUE
796      */
797     public static int min(int a, int b) {
798     return (a <= b) ? a : b;
799     }
800 
801     /**
802      * Returns the smaller of two <code>long</code> values. That is,
803      * the result is the argument closer to the value of
804      * <code>Long.MIN_VALUE</code>. If the arguments have the same
805      * value, the result is that same value.
806      *
807      * @param   a   an argument.
808      * @param   b   another argument.
809      * @return  the smaller of <code>a</code> and <code>b</code>.
810      * @see     java.lang.Long#MIN_VALUE
811      */
812     public static long min(long a, long b) {
813     return (a <= b) ? a : b;
814     }
815 
816     /**
817      * Returns the smaller of two <code>float</code> values.  That is,
818      * the result is the value closer to negative infinity. If the
819      * arguments have the same value, the result is that same
820      * value. If either value is NaN, then the result is NaN.  Unlike
821      * the numerical comparison operators, this method considers
822      * negative zero to be strictly smaller than positive zero.  If
823      * one argument is positive zero and the other is negative zero,
824      * the result is negative zero.
825      *
826      * @param   a   an argument.
827      * @param   b   another argument.
828      * @return  the smaller of <code>a</code> and <code>b.</code>
829      */
830     public static float min(float a, float b) {
831         if (a != a) return a;   // a is NaN
832     if ((a == 0.0f) && (b == 0.0f)
833         && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
834         return b;
835     }
836     return (a <= b) ? a : b;
837     }
838 
839     /**
840      * Returns the smaller of two <code>double</code> values.  That
841      * is, the result is the value closer to negative infinity. If the
842      * arguments have the same value, the result is that same
843      * value. If either value is NaN, then the result is NaN.  Unlike
844      * the numerical comparison operators, this method considers
845      * negative zero to be strictly smaller than positive zero. If one
846      * argument is positive zero and the other is negative zero, the
847      * result is negative zero.
848      *
849      * @param   a   an argument.
850      * @param   b   another argument.
851      * @return  the smaller of <code>a</code> and <code>b</code>.
852      */
853     public static double min(double a, double b) {
854         if (a != a) return a;   // a is NaN
855     if ((a == 0.0d) && (b == 0.0d)
856         && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
857         return b;
858     }
859     return (a <= b) ? a : b;
860     }
861 
862     /**
863      * Returns the size of an ulp of the argument.  An ulp of a
864      * <code>double</code> value is the positive distance between this
865      * floating-point value and the <code>double</code> value next
866      * larger in magnitude.  Note that for non-NaN <i>x</i>,
867      * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
868      * 
869      * <p>Special Cases:
870      * <ul>
871      * <li> If the argument is NaN, then the result is NaN.
872      * <li> If the argument is positive or negative infinity, then the
873      * result is positive infinity.
874      * <li> If the argument is positive or negative zero, then the result is
875      * <code>Double.MIN_VALUE</code>.
876      * <li> If the argument is &plusmn;<code>Double.MAX_VALUE</code>, then
877      * the result is equal to 2<sup>971</sup>.
878      * </ul>
879      *
880      * @param d the floating-point value whose ulp is to be returned
881      * @return the size of an ulp of the argument
882      * @author Joseph D. Darcy
883      * @since 1.5
884      */
885     public static double ulp(double d) {
886     return sun.misc.FpUtils.ulp(d);
887     }
888 
889     /**
890      * Returns the size of an ulp of the argument.  An ulp of a
891      * <code>float</code> value is the positive distance between this
892      * floating-point value and the <code>float</code> value next
893      * larger in magnitude.  Note that for non-NaN <i>x</i>,
894      * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
895      * 
896      * <p>Special Cases:
897      * <ul>
898      * <li> If the argument is NaN, then the result is NaN.
899      * <li> If the argument is positive or negative infinity, then the
900      * result is positive infinity.
901      * <li> If the argument is positive or negative zero, then the result is
902      * <code>Float.MIN_VALUE</code>.
903      * <li> If the argument is &plusmn;<code>Float.MAX_VALUE</code>, then
904      * the result is equal to 2<sup>104</sup>.
905      * </ul>
906      *
907      * @param f the floating-point value whose ulp is to be returned
908      * @return the size of an ulp of the argument
909      * @author Joseph D. Darcy
910      * @since 1.5
911      */
912     public static float ulp(float f) {
913     return sun.misc.FpUtils.ulp(f);
914     }
915 
916     /**
917      * Returns the signum function of the argument; zero if the argument
918      * is zero, 1.0 if the argument is greater than zero, -1.0 if the
919      * argument is less than zero.
920      *
921      * <p>Special Cases:
922      * <ul>
923      * <li> If the argument is NaN, then the result is NaN.
924      * <li> If the argument is positive zero or negative zero, then the
925      *      result is the same as the argument.
926      * </ul>
927      *
928      * @param d the floating-point value whose signum is to be returned
929      * @return the signum function of the argument
930      * @author Joseph D. Darcy
931      * @since 1.5
932      */
933     public static double signum(double d) {
934     return sun.misc.FpUtils.signum(d);
935     }
936 
937     /**
938      * Returns the signum function of the argument; zero if the argument
939      * is zero, 1.0f if the argument is greater than zero, -1.0f if the
940      * argument is less than zero.
941      *
942      * <p>Special Cases:
943      * <ul>
944      * <li> If the argument is NaN, then the result is NaN.
945      * <li> If the argument is positive zero or negative zero, then the
946      *      result is the same as the argument.
947      * </ul>
948      *
949      * @param f the floating-point value whose signum is to be returned
950      * @return the signum function of the argument
951      * @author Joseph D. Darcy
952      * @since 1.5
953      */
954     public static float signum(float f) {
955     return sun.misc.FpUtils.signum(f);
956     }
957 
958     /**
959      * Returns the hyperbolic sine of a <code>double</code> value.
960      * The hyperbolic sine of <i>x</i> is defined to be
961      * (<i>e<sup>x</sup>&nbsp;-&nbsp;e<sup>-x</sup></i>)/2
962      * where <i>e</i> is {@linkplain Math#E Euler's number}.
963      *
964      * <p>Special cases:
965      * <ul>
966      *
967      * <li>If the argument is NaN, then the result is NaN.
968      *
969      * <li>If the argument is infinite, then the result is an infinity
970      * with the same sign as the argument.
971      *
972      * <li>If the argument is zero, then the result is a zero with the
973      * same sign as the argument.
974      *
975      * </ul>
976      *
977      * @param   x The number whose hyperbolic sine is to be returned.
978      * @return  The hyperbolic sine of <code>x</code>.
979      * @since 1.5
980      */
981     public static native double sinh(double x);
982 
983     /**
984      * Returns the hyperbolic cosine of a <code>double</code> value.
985      * The hyperbolic cosine of <i>x</i> is defined to be
986      * (<i>e<sup>x</sup>&nbsp;+&nbsp;e<sup>-x</sup></i>)/2
987      * where <i>e</i> is {@linkplain Math#E Euler's number}.
988      *
989      * <p>Special cases:
990      * <ul>
991      *
992      * <li>If the argument is NaN, then the result is NaN.
993      *
994      * <li>If the argument is infinite, then the result is positive
995      * infinity.
996      *
997      * <li>If the argument is zero, then the result is <code>1.0</code>.
998      *
999      * </ul>
1000     *
1001     * @param   x The number whose hyperbolic cosine is to be returned.
1002     * @return  The hyperbolic cosine of <code>x</code>.
1003     * @since 1.5
1004     */
1005    public static native double cosh(double x);
1006
1007    /**
1008     * Returns the hyperbolic tangent of a <code>double</code> value.
1009     * The hyperbolic tangent of <i>x</i> is defined to be
1010     * (<i>e<sup>x</sup>&nbsp;-&nbsp;e<sup>-x</sup></i>)/(<i>e<sup>x</sup>&nbsp;+&nbsp;e<sup>-x</sup></i>),
1011     * in other words, {@linkplain Math#sinh
1012     * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}.  Note
1013     * that the absolute value of the exact tanh is always less than
1014     * 1.
1015     *
1016     * <p>Special cases:
1017     * <ul>
1018     *
1019     * <li>If the argument is NaN, then the result is NaN.
1020     *
1021     * <li>If the argument is zero, then the result is a zero with the
1022     * same sign as the argument.
1023     *
1024     * <li>If the argument is positive infinity, then the result is
1025     * <code>+1.0</code>.
1026     *
1027     * <li>If the argument is negative infinity, then the result is
1028     * <code>-1.0</code>.
1029     *  
1030     * </ul>
1031     *
1032     * @param   x The number whose hyperbolic tangent is to be returned.
1033     * @return  The hyperbolic tangent of <code>x</code>.
1034     * @since 1.5
1035     */
1036    public static native double tanh(double x);
1037
1038    /**
1039     * Returns sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
1040     * without intermediate overflow or underflow.
1041     *
1042     * <p>Special cases:
1043     * <ul>
1044     *
1045     * <li> If either argument is infinite, then the result
1046     * is positive infinity.
1047     *
1048     * <li> If either argument is NaN and neither argument is infinite,
1049     * then the result is NaN.
1050     *
1051     * </ul>
1052     *
1053     * @param x a value
1054     * @param y a value
1055     * @return sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
1056     * without intermediate overflow or underflow
1057     * @since 1.5
1058     */
1059    public static native double hypot(double x, double y);
1060
1061    /**
1062     * Returns <i>e</i><sup>x</sup>&nbsp;-1.  Note that for values of
1063     * <i>x</i> near 0, the exact sum of
1064     * <code>expm1(x)</code>&nbsp;+&nbsp;1 is much closer to the true
1065     * result of <i>e</i><sup>x</sup> than <code>exp(x)</code>.
1066     *
1067     * <p>Special cases:
1068     * <ul>
1069     * <li>If the argument is NaN, the result is NaN.
1070     *
1071     * <li>If the argument is positive infinity, then the result is
1072     * positive infinity.
1073     *
1074     * <li>If the argument is negative infinity, then the result is
1075     * -1.0.
1076     *
1077     * <li>If the argument is zero, then the result is a zero with the
1078     * same sign as the argument.
1079     *
1080     * </ul>
1081     *
1082     * @param   x   the exponent to raise <i>e</i> to in the computation of
1083     *              <i>e</i><sup><code>x</code></sup>&nbsp;-1.
1084     * @return  the value <i>e</i><sup><code>x</code></sup>&nbsp;-&nbsp;1.
1085     */
1086    public static native double expm1(double x);
1087
1088    /**
1089     * Returns the natural logarithm of the sum of the argument and 1.
1090     * Note that for small values <code>x</code>, the result of
1091     * <code>log1p(x)</code> is much closer to the true result of ln(1
1092     * + <code>x</code>) than the floating-point evaluation of
1093     * <code>log(1.0+x)</code>.
1094     *
1095     * <p>Special cases:
1096     *
1097     * <ul>
1098     *
1099     * <li>If the argument is NaN or less than -1, then the result is
1100     * NaN.
1101     *
1102     * <li>If the argument is positive infinity, then the result is
1103     * positive infinity.
1104     *
1105     * <li>If the argument is negative one, then the result is
1106     * negative infinity.
1107     *
1108     * <li>If the argument is zero, then the result is a zero with the
1109     * same sign as the argument.
1110     *
1111     * </ul>
1112     *
1113     * @param   x   a value
1114     * @return the value ln(<code>x</code>&nbsp;+&nbsp;1), the natural
1115     * log of <code>x</code>&nbsp;+&nbsp;1
1116     */
1117    public static native double log1p(double x);
1118}
1119
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags