Math


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