1 /* VMMath.java -- Common mathematical functions.
2 Copyright (C) 2006 Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
37
38
39 package java.lang;
40
41 import gnu.classpath.Configuration;
42
43 class VMMath
44 {
45
46 static
47 {
48 if (Configuration.INIT_LOAD_LIBRARY)
49 {
50 System.loadLibrary("javalang");
51 }
52 }
53
54 /**
55 * The trigonometric function <em>sin</em>. The sine of NaN or infinity is
56 * NaN, and the sine of 0 retains its sign. This is accurate within 1 ulp,
57 * and is semi-monotonic.
58 *
59 * @param a the angle (in radians)
60 * @return sin(a)
61 */
62 public static native double sin(double a);
63
64 /**
65 * The trigonometric function <em>cos</em>. The cosine of NaN or infinity is
66 * NaN. This is accurate within 1 ulp, and is semi-monotonic.
67 *
68 * @param a the angle (in radians)
69 * @return cos(a)
70 */
71 public static native double cos(double a);
72
73 /**
74 * The trigonometric function <em>tan</em>. The tangent of NaN or infinity
75 * is NaN, and the tangent of 0 retains its sign. This is accurate within 1
76 * ulp, and is semi-monotonic.
77 *
78 * @param a the angle (in radians)
79 * @return tan(a)
80 */
81 public static native double tan(double a);
82
83 /**
84 * The trigonometric function <em>arcsin</em>. The range of angles returned
85 * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN or
86 * its absolute value is beyond 1, the result is NaN; and the arcsine of
87 * 0 retains its sign. This is accurate within 1 ulp, and is semi-monotonic.
88 *
89 * @param a the sin to turn back into an angle
90 * @return arcsin(a)
91 */
92 public static native double asin(double a);
93
94 /**
95 * The trigonometric function <em>arccos</em>. The range of angles returned
96 * is 0 to pi radians (0 to 180 degrees). If the argument is NaN or
97 * its absolute value is beyond 1, the result is NaN. This is accurate
98 * within 1 ulp, and is semi-monotonic.
99 *
100 * @param a the cos to turn back into an angle
101 * @return arccos(a)
102 */
103 public static native double acos(double a);
104
105 /**
106 * The trigonometric function <em>arcsin</em>. The range of angles returned
107 * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN, the
108 * result is NaN; and the arctangent of 0 retains its sign. This is accurate
109 * within 1 ulp, and is semi-monotonic.
110 *
111 * @param a the tan to turn back into an angle
112 * @return arcsin(a)
113 * @see #atan2(double, double)
114 */
115 public static native double atan(double a);
116
117 /**
118 * A special version of the trigonometric function <em>arctan</em>, for
119 * converting rectangular coordinates <em>(x, y)</em> to polar
120 * <em>(r, theta)</em>. This computes the arctangent of x/y in the range
121 * of -pi to pi radians (-180 to 180 degrees). Special cases:<ul>
122 * <li>If either argument is NaN, the result is NaN.</li>
123 * <li>If the first argument is positive zero and the second argument is
124 * positive, or the first argument is positive and finite and the second
125 * argument is positive infinity, then the result is positive zero.</li>
126 * <li>If the first argument is negative zero and the second argument is
127 * positive, or the first argument is negative and finite and the second
128 * argument is positive infinity, then the result is negative zero.</li>
129 * <li>If the first argument is positive zero and the second argument is
130 * negative, or the first argument is positive and finite and the second
131 * argument is negative infinity, then the result is the double value
132 * closest to pi.</li>
133 * <li>If the first argument is negative zero and the second argument is
134 * negative, or the first argument is negative and finite and the second
135 * argument is negative infinity, then the result is the double value
136 * closest to -pi.</li>
137 * <li>If the first argument is positive and the second argument is
138 * positive zero or negative zero, or the first argument is positive
139 * infinity and the second argument is finite, then the result is the
140 * double value closest to pi/2.</li>
141 * <li>If the first argument is negative and the second argument is
142 * positive zero or negative zero, or the first argument is negative
143 * infinity and the second argument is finite, then the result is the
144 * double value closest to -pi/2.</li>
145 * <li>If both arguments are positive infinity, then the result is the
146 * double value closest to pi/4.</li>
147 * <li>If the first argument is positive infinity and the second argument
148 * is negative infinity, then the result is the double value closest to
149 * 3*pi/4.</li>
150 * <li>If the first argument is negative infinity and the second argument
151 * is positive infinity, then the result is the double value closest to
152 * -pi/4.</li>
153 * <li>If both arguments are negative infinity, then the result is the
154 * double value closest to -3*pi/4.</li>
155 *
156 * </ul><p>This is accurate within 2 ulps, and is semi-monotonic. To get r,
157 * use sqrt(x*x+y*y).
158 *
159 * @param y the y position
160 * @param x the x position
161 * @return <em>theta</em> in the conversion of (x, y) to (r, theta)
162 * @see #atan(double)
163 */
164 public static native double atan2(double y, double x);
165
166 /**
167 * Take <em>e</em><sup>a</sup>. The opposite of <code>log()</code>. If the
168 * argument is NaN, the result is NaN; if the argument is positive infinity,
169 * the result is positive infinity; and if the argument is negative
170 * infinity, the result is positive zero. This is accurate within 1 ulp,
171 * and is semi-monotonic.
172 *
173 * @param a the number to raise to the power
174 * @return the number raised to the power of <em>e</em>
175 * @see #log(double)
176 * @see #pow(double, double)
177 */
178 public static native double exp(double a);
179
180 /**
181 * Take ln(a) (the natural log). The opposite of <code>exp()</code>. If the
182 * argument is NaN or negative, the result is NaN; if the argument is
183 * positive infinity, the result is positive infinity; and if the argument
184 * is either zero, the result is negative infinity. This is accurate within
185 * 1 ulp, and is semi-monotonic.
186 *
187 * <p>Note that the way to get log<sub>b</sub>(a) is to do this:
188 * <code>ln(a) / ln(b)</code>.
189 *
190 * @param a the number to take the natural log of
191 * @return the natural log of <code>a</code>
192 * @see #exp(double)
193 */
194 public static native double log(double a);
195
196 /**
197 * Take a square root. If the argument is NaN or negative, the result is
198 * NaN; if the argument is positive infinity, the result is positive
199 * infinity; and if the result is either zero, the result is the same.
200 * This is accurate within the limits of doubles.
201 *
202 * <p>For other roots, use pow(a, 1 / rootNumber).
203 *
204 * @param a the numeric argument
205 * @return the square root of the argument
206 * @see #pow(double, double)
207 */
208 public static native double sqrt(double a);
209
210 /**
211 * Raise a number to a power. Special cases:<ul>
212 * <li>If the second argument is positive or negative zero, then the result
213 * is 1.0.</li>
214 * <li>If the second argument is 1.0, then the result is the same as the
215 * first argument.</li>
216 * <li>If the second argument is NaN, then the result is NaN.</li>
217 * <li>If the first argument is NaN and the second argument is nonzero,
218 * then the result is NaN.</li>
219 * <li>If the absolute value of the first argument is greater than 1 and
220 * the second argument is positive infinity, or the absolute value of the
221 * first argument is less than 1 and the second argument is negative
222 * infinity, then the result is positive infinity.</li>
223 * <li>If the absolute value of the first argument is greater than 1 and
224 * the second argument is negative infinity, or the absolute value of the
225 * first argument is less than 1 and the second argument is positive
226 * infinity, then the result is positive zero.</li>
227 * <li>If the absolute value of the first argument equals 1 and the second
228 * argument is infinite, then the result is NaN.</li>
229 * <li>If the first argument is positive zero and the second argument is
230 * greater than zero, or the first argument is positive infinity and the
231 * second argument is less than zero, then the result is positive zero.</li>
232 * <li>If the first argument is positive zero and the second argument is
233 * less than zero, or the first argument is positive infinity and the
234 * second argument is greater than zero, then the result is positive
235 * infinity.</li>
236 * <li>If the first argument is negative zero and the second argument is
237 * greater than zero but not a finite odd integer, or the first argument is
238 * negative infinity and the second argument is less than zero but not a
239 * finite odd integer, then the result is positive zero.</li>
240 * <li>If the first argument is negative zero and the second argument is a
241 * positive finite odd integer, or the first argument is negative infinity
242 * and the second argument is a negative finite odd integer, then the result
243 * is negative zero.</li>
244 * <li>If the first argument is negative zero and the second argument is
245 * less than zero but not a finite odd integer, or the first argument is
246 * negative infinity and the second argument is greater than zero but not a
247 * finite odd integer, then the result is positive infinity.</li>
248 * <li>If the first argument is negative zero and the second argument is a
249 * negative finite odd integer, or the first argument is negative infinity
250 * and the second argument is a positive finite odd integer, then the result
251 * is negative infinity.</li>
252 * <li>If the first argument is less than zero and the second argument is a
253 * finite even integer, then the result is equal to the result of raising
254 * the absolute value of the first argument to the power of the second
255 * argument.</li>
256 * <li>If the first argument is less than zero and the second argument is a
257 * finite odd integer, then the result is equal to the negative of the
258 * result of raising the absolute value of the first argument to the power
259 * of the second argument.</li>
260 * <li>If the first argument is finite and less than zero and the second
261 * argument is finite and not an integer, then the result is NaN.</li>
262 * <li>If both arguments are integers, then the result is exactly equal to
263 * the mathematical result of raising the first argument to the power of
264 * the second argument if that result can in fact be represented exactly as
265 * a double value.</li>
266 *
267 * </ul><p>(In the foregoing descriptions, a floating-point value is
268 * considered to be an integer if and only if it is a fixed point of the
269 * method {@link #ceil(double)} or, equivalently, a fixed point of the
270 * method {@link #floor(double)}. A value is a fixed point of a one-argument
271 * method if and only if the result of applying the method to the value is
272 * equal to the value.) This is accurate within 1 ulp, and is semi-monotonic.
273 *
274 * @param a the number to raise
275 * @param b the power to raise it to
276 * @return a<sup>b</sup>
277 */
278 public static native double pow(double a, double b);
279
280 /**
281 * Get the IEEE 754 floating point remainder on two numbers. This is the
282 * value of <code>x - y * <em>n</em></code>, where <em>n</em> is the closest
283 * double to <code>x / y</code> (ties go to the even n); for a zero
284 * remainder, the sign is that of <code>x</code>. If either argument is NaN,
285 * the first argument is infinite, or the second argument is zero, the result
286 * is NaN; if x is finite but y is infinite, the result is x. This is
287 * accurate within the limits of doubles.
288 *
289 * @param x the dividend (the top half)
290 * @param y the divisor (the bottom half)
291 * @return the IEEE 754-defined floating point remainder of x/y
292 * @see #rint(double)
293 */
294 public static native double IEEEremainder(double x, double y);
295
296 /**
297 * Take the nearest integer that is that is greater than or equal to the
298 * argument. If the argument is NaN, infinite, or zero, the result is the
299 * same; if the argument is between -1 and 0, the result is negative zero.
300 * Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
301 *
302 * @param a the value to act upon
303 * @return the nearest integer >= <code>a</code>
304 */
305 public static native double ceil(double a);
306
307 /**
308 * Take the nearest integer that is that is less than or equal to the
309 * argument. If the argument is NaN, infinite, or zero, the result is the
310 * same. Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
311 *
312 * @param a the value to act upon
313 * @return the nearest integer <= <code>a</code>
314 */
315 public static native double floor(double a);
316
317 /**
318 * Take the nearest integer to the argument. If it is exactly between
319 * two integers, the even integer is taken. If the argument is NaN,
320 * infinite, or zero, the result is the same.
321 *
322 * @param a the value to act upon
323 * @return the nearest integer to <code>a</code>
324 */
325 public static native double rint(double a);
326
327 /**
328 * <p>
329 * Take a cube root. If the argument is NaN, an infinity or zero, then
330 * the original value is returned. The returned result must be within 1 ulp
331 * of the exact result. For a finite value, <code>x</code>, the cube root
332 * of <code>-x</code> is equal to the negation of the cube root
333 * of <code>x</code>.
334 * </p>
335 * <p>
336 * For a square root, use <code>sqrt</code>. For other roots, use
337 * <code>pow(a, 1 / rootNumber)</code>.
338 * </p>
339 *
340 * @param a the numeric argument
341 * @return the cube root of the argument
342 * @see #sqrt(double)
343 * @see #pow(double, double)
344 */
345 public static native double cbrt(double a);
346
347 /**
348 * <p>
349 * Returns the hyperbolic cosine of the given value. For a value,
350 * <code>x</code>, the hyperbolic cosine is <code>(e<sup>x</sup> +
351 * e<sup>-x</sup>)/2</code>
352 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
353 * result must be within 2.5 ulps of the exact result.
354 * </p>
355 * <p>
356 * If the supplied value is <code>NaN</code>, then the original value is
357 * returned. For either infinity, positive infinity is returned.
358 * The hyperbolic cosine of zero must be 1.0.
359 * </p>
360 *
361 * @param a the numeric argument
362 * @return the hyperbolic cosine of <code>a</code>.
363 * @since 1.5
364 */
365 public static native double cosh(double a);
366
367 /**
368 * <p>
369 * Returns <code>e<sup>a</sup> - 1. For values close to 0, the
370 * result of <code>expm1(a) + 1</code> tend to be much closer to the
371 * exact result than simply <code>exp(x)</code>. The result must be within
372 * 1 ulp of the exact result, and results must be semi-monotonic. For finite
373 * inputs, the returned value must be greater than or equal to -1.0. Once
374 * a result enters within half a ulp of this limit, the limit is returned.
375 * </p>
376 * <p>
377 * For <code>NaN</code>, positive infinity and zero, the original value
378 * is returned. Negative infinity returns a result of -1.0 (the limit).
379 * </p>
380 *
381 * @param a the numeric argument
382 * @return <code>e<sup>a</sup> - 1</code>
383 * @since 1.5
384 */
385 public static native double expm1(double a);
386
387 /**
388 * <p>
389 * Returns the hypotenuse, <code>a<sup>2</sup> + b<sup>2</sup></code>,
390 * without intermediate overflow or underflow. The returned result must be
391 * within 1 ulp of the exact result. If one parameter is held constant,
392 * then the result in the other parameter must be semi-monotonic.
393 * </p>
394 * <p>
395 * If either of the arguments is an infinity, then the returned result
396 * is positive infinity. Otherwise, if either argument is <code>NaN</code>,
397 * then <code>NaN</code> is returned.
398 * </p>
399 *
400 * @param a the first parameter.
401 * @param b the second parameter.
402 * @return the hypotenuse matching the supplied parameters.
403 * @since 1.5
404 */
405 public static native double hypot(double a, double b);
406
407 /**
408 * <p>
409 * Returns the base 10 logarithm of the supplied value. The returned
410 * result must within 1 ulp of the exact result, and the results must be
411 * semi-monotonic.
412 * </p>
413 * <p>
414 * Arguments of either <code>NaN</code> or less than zero return
415 * <code>NaN</code>. An argument of positive infinity returns positive
416 * infinity. Negative infinity is returned if either positive or negative
417 * zero is supplied. Where the argument is the result of
418 * <code>10<sup>n</sup</code>, then <code>n</code> is returned.
419 * </p>
420 *
421 * @param a the numeric argument.
422 * @return the base 10 logarithm of <code>a</code>.
423 * @since 1.5
424 */
425 public static native double log10(double a);
426
427 /**
428 * <p>
429 * Returns the natural logarithm resulting from the sum of the argument,
430 * <code>a</code> and 1. For values close to 0, the
431 * result of <code>log1p(a)</code> tend to be much closer to the
432 * exact result than simply <code>log(1.0+a)</code>. The returned
433 * result must be within 1 ulp of the exact result, and the results must be
434 * semi-monotonic.
435 * </p>
436 * <p>
437 * Arguments of either <code>NaN</code> or less than -1 return
438 * <code>NaN</code>. An argument of positive infinity or zero
439 * returns the original argument. Negative infinity is returned from an
440 * argument of -1.
441 * </p>
442 *
443 * @param a the numeric argument.
444 * @return the natural logarithm of <code>a</code> + 1.
445 * @since 1.5
446 */
447 public static native double log1p(double a);
448
449 /**
450 * <p>
451 * Returns the hyperbolic sine of the given value. For a value,
452 * <code>x</code>, the hyperbolic sine is <code>(e<sup>x</sup> -
453 * e<sup>-x</sup>)/2</code>
454 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
455 * result must be within 2.5 ulps of the exact result.
456 * </p>
457 * <p>
458 * If the supplied value is <code>NaN</code>, an infinity or a zero, then the
459 * original value is returned.
460 * </p>
461 *
462 * @param a the numeric argument
463 * @return the hyperbolic sine of <code>a</code>.
464 * @since 1.5
465 */
466 public static native double sinh(double a);
467
468 /**
469 * <p>
470 * Returns the hyperbolic tangent of the given value. For a value,
471 * <code>x</code>, the hyperbolic tangent is <code>(e<sup>x</sup> -
472 * e<sup>-x</sup>)/(e<sup>x</sup> + e<sup>-x</sup>)</code>
473 * (i.e. <code>sinh(a)/cosh(a)</code>)
474 * with <code>e</code> being <a href="#E">Euler's number</a>. The returned
475 * result must be within 2.5 ulps of the exact result. The absolute value
476 * of the exact result is always less than 1. Computed results are thus
477 * less than or equal to 1 for finite arguments, with results within
478 * half a ulp of either positive or negative 1 returning the appropriate
479 * limit value (i.e. as if the argument was an infinity).
480 * </p>
481 * <p>
482 * If the supplied value is <code>NaN</code> or zero, then the original
483 * value is returned. Positive infinity returns +1.0 and negative infinity
484 * returns -1.0.
485 * </p>
486 *
487 * @param a the numeric argument
488 * @return the hyperbolic tangent of <code>a</code>.
489 * @since 1.5
490 */
491 public static native double tanh(double a);
492
493 }
Save This Page