001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package jsx.core;
021 
022 import js.*;
023 
024 /**
025  * <p>A utility class providing useful mathematical functions and constants with its 
026  * static methods.</p>
027  * <p>Users are encouraged to use the utilities provided by this class instead of the 
028  * <b>opaque</b> methods of {@link js.MathLike} or {@link js.core.JsGlobal.Math} in 
029  * consideration of the reuse benefit for re-compilation results.</p>
030  *
031  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
032  * @see js.MathLike
033  * @see js.core.JsGlobal.Math
034  */
035 
036 public final class Maths extends Disposable
037 {
038     private Maths() {}
039 
040     /**
041      * The constant e, the base of the natural logarithm.
042      * @see js.MathLike#E
043      * @since 1.0
044      */
045     public final static double E       = MathLike.E;
046     /**
047      * The natural logarithm of 2.
048      * @see js.MathLike#LN2
049      * @since 1.0
050      */
051     public final static double LN2     = MathLike.LN2;
052     /**
053      * The natural logarithm of 10.
054      * @see js.MathLike#LN10
055      * @since 1.0
056      */
057     public final static double LN10    = MathLike.LN10;
058     /**
059      * The base-2 logarithm of e.
060      * @see js.MathLike#LOG2E
061      * @since 1.0
062      */
063     public final static double LOG2E   = MathLike.LOG2E;
064     /**
065      * The base-10 logarithm of e.
066      * @see js.MathLike#LOG10E
067      * @since 1.0
068      */
069     public final static double LOG10E  = MathLike.LOG10E;
070     /**
071      * The constant pi, the ratio of the circumference of a circle to its diameter. 
072      * It has a value of approximately 3.14159265358979.
073      * @see js.MathLike#PI
074      * @since 1.0
075      */
076     public final static double PI      = MathLike.PI;
077     /**
078      * The square root of 2.
079      * @see js.MathLike#SQRT2
080      * @since 1.0
081      */
082     public final static double SQRT2   = MathLike.SQRT2;
083     /**
084      * The reciprocal of the square root of 2, that is, 
085      * the number 1 divided by the square root of 2.
086      * @see js.MathLike#SQRT1_2
087      * @since 1.0
088      */
089     public final static double SQRT1_2 = MathLike.SQRT1_2;
090 
091     /**
092      * <p>Computes an absolute value.</p>
093      * @param x Any number.
094      * @return The absolute value of <code>x</code>.
095      * @see js.MathLike#abs(Object)
096      * @see js.core.JsGlobal.Math#abs(Object)
097      * @since 1.0
098      */
099     public static final double abs(Object x) {
100         return Js.math().abs(x);
101     }
102     /**
103      * <p>Computes an arccosine.</p>
104      * @param x A number between -1.0 and 1.0.
105      * @return The arccosine, or inverse cosine, of the specified value <code>x</code>. 
106      * This return value is between 0 and pi radians.
107      * @see js.MathLike#acos(Object)
108      * @see js.core.JsGlobal.Math#acos(Object)
109      * @since 1.0
110      */
111     public static final double acos(Object x) {
112         return Js.math().acos(x);
113     }
114     /**
115      * <p>Computes an arcsine.</p>
116      * @param x A number between -1.0 and 1.0.
117      * @return The arcsine, or inverse cosine, of the specified value <code>x</code>. 
118      * This return value is between -pi/2 and pi/2 radians.
119      * @see js.MathLike#asin(Object)
120      * @see js.core.JsGlobal.Math#asin(Object)
121      * @since 1.0
122      */
123     public static final double asin(Object x) {
124         return Js.math().asin(x);
125     }
126     /**
127      * <p>Computes an arctangent.</p>
128      * @param x Any number.
129      * @return The arc tanget of the specified value <code>x</code>. This return value is 
130      * between -pi/2 and pi/2 radians.
131      * @see js.MathLike#atan(Object)
132      * @see js.core.JsGlobal.Math#atan(Object)
133      * @since 1.0
134      */
135     public static final double atan(Object x) {
136         return Js.math().atan(x);
137     }
138     /**
139      * <p>Computes the arc tangent of the ratio <code>y/x</code>. The <code>y</code> 
140      * argument can be considered the Y coordinate (or "rise") of a point, and the 
141      * <code>x</code> argument can be considered the X coordinate (or "run") of the point. 
142      * Note the unusual order of the arguments to this function: the Y coordinate is 
143      * passed before the X coordinate.</p>
144      * @param y The Y coordinate of the point.
145      * @param x The X coordinate of the point.
146      * @return A value between -pi and pi radians that specifies the counterclockwise angle 
147      * between the positive X axis and the point <code>(x, y)</code>.
148      * @see js.MathLike#atan2(Object, Object)
149      * @see js.core.JsGlobal.Math#atan2(Object, Object)
150      * @since 1.0
151      */
152     public static final double atan2(Object y, Object x) {
153         return Js.math().atan2(y, x);
154     }
155     /**
156      * <p>Rounds a number up.</p>
157      * @param x Any numeric value or expression.
158      * @return TThe closest integer greater than or equal to <code>x</code>.
159      * @see js.MathLike#ceil(Object)
160      * @see js.core.JsGlobal.Math#ceil(Object)
161      * @since 1.0
162      */
163     public static final double ceil(Object x) {
164         return Js.math().ceil(x);
165     }
166     /**
167      * <p>Computes a cosine.</p>
168      * @param x An angle, measured in radians. 
169      * To convert degrees to radians, multiply the degree value by 0.017453293 (2pi/360).
170      * @return The cosine of the specified value <code>x</code>. This return value is 
171      * between -1.0 and 1.0.
172      * @see js.MathLike#cos(Object)
173      * @see js.core.JsGlobal.Math#cos(Object)
174      * @since 1.0
175      */
176     public static final double cos(Object x) {
177         return Js.math().cos(x);
178     }
179     /**
180      * <p>Computes a power of e.</p>
181      * @param x A numeric value or expression to be used as the exponent.
182      * @return e raised to the power of the specified exponent <code>x</code>, where e 
183      * is the base of the natural logarithm, with a value of approximately 2.71828.
184      * @see js.MathLike#exp(Object)
185      * @see js.core.JsGlobal.Math#exp(Object)
186      * @since 1.0
187      */
188     public static final double exp(Object x) {
189         return Js.math().exp(x);
190     }
191     /**
192      * <p>Rounds a number down.</p>
193      * <p>This function computes the floor function. In other words, it returns the 
194      * nearest integer value that is less than or equal to the function argument.</p>
195      * <p>This function rounds a floating-point value down to the closest integer. 
196      * This behavior differs from that of {@link #round(Object)}, which rounds up or 
197      * down to the nearest integer. Also note that this function rounds negative 
198      * numbers down (that is, to be more negative), not up (that is, closer to zero).</p>
199      * @param x Any numeric value or expression.
200      * @return The closest integer less than or equal to <code>x</code>.
201      * @see js.MathLike#floor(Object)
202      * @see js.core.JsGlobal.Math#floor(Object)
203      * @since 1.0
204      */
205     public static final double floor(Object x) {
206         return Js.math().floor(x);
207     }
208     /**
209      * <p>Computes a natural logarithm.</p>
210      * @param x Any numeric value or expression greater than zero.
211      * @return The natural logarithm of <code>x</code>.
212      * @see js.MathLike#log(Object)
213      * @see js.core.JsGlobal.Math#log(Object)
214      * @since 1.0
215      */
216     public static final double log(Object x) {
217         return Js.math().log(x);
218     }
219     public static final double log2(Object x) {
220         return MathLike.LOG2E * log(x);
221     }
222     public static final double log10(Object x) {
223         return MathLike.LOG10E * log(x);
224     }
225     public static final Number constrain(Object v, Object min, Object max) {
226         return max(min(v, max), min);
227     }
228     /**
229      * <p>Returns the larger of two numbers.</p>
230      * @param x Any value.
231      * @param y Any value.
232      * @return The larger of the two arguments. Returns <code>-Infinity</code> if 
233      * the arguments are all undefined. Returns <code>NaN</code> if any of the arguments is 
234      * <code>NaN</code> or is a non-numeric value that cannot be converted to a number.
235      * @see js.MathLike#max(Object, Object)
236      * @see js.core.JsGlobal.Math#max(Object, Object)
237      * @since 1.0
238      */
239     public static final Number max(Object x, Object y) {
240         return Js.math().max(x, y);
241     }
242     /**
243      * <p>Returns the smaller of two numbers.</p>
244      * @param x Any value.
245      * @param y Any value.
246      * @return The smaller of the two arguments. Returns <code>-Infinity</code> if 
247      * the arguments are all undefined. Returns <code>NaN</code> if any of the arguments is 
248      * <code>NaN</code> or is a non-numeric value that cannot be converted to a number.
249      * @see js.MathLike#min(Object, Object)
250      * @see js.core.JsGlobal.Math#min(Object, Object)
251      * @since 1.0
252      */
253     public static final Number min(Object x, Object y) {
254         return Js.math().min(x, y);
255     }
256     /**
257      * <p>Computes <code>x</code> to the power of <code>y</code>.</p>
258      * <p>Any values of x and y may be passed to this function. However, if the result is 
259      * an imaginary or complex number, it returns <code>NaN</code>. In practice, this 
260      * means that if <code>x</code> is negative, <code>y</code> should be a positive or 
261      * negative integer. Also, bear in mind that large exponents can easily cause 
262      * floating-point overflow and return a value of <code>Infinity</code>.</p>
263      * @param x The number to be raised to a power.
264      * @param y The power that x is to be raised to.
265      * @return <code>x</code> to the power of <code>y</code>.
266      * @see js.MathLike#pow(Object, Object)
267      * @see js.core.JsGlobal.Math#pow(Object, Object)
268      * @since 1.0
269      */
270     public static final double pow(Object x, Object y) {
271         return Js.math().pow(x, y);
272     }
273     /**
274      * <p>Computes a random number.</p>
275      * @return A pseudo-random number between 0.0 and 1.0.
276      * @see js.MathLike#random()
277      * @see js.core.JsGlobal.Math#random()
278      * @since 1.0
279      */
280     public static final double random() {
281         return Js.math().random();
282     }
283     /**
284      * <p>Rounds to the nearest integer.</p>
285      * <p>This invocation rounds its argument up or down to the nearest integer. 
286      * It rounds .5 up. For example, it rounds 1.5 to 2 and rounds -1.5 to -1.</p>
287      * @param x Any number.
288      * @return The integer closest to <code>x</code>.
289      * @see js.MathLike#round(Object)
290      * @see js.core.JsGlobal.Math#round(Object)
291      * @since 1.0
292      */
293     public static final double round(Object x) {
294         return Js.math().round(x);
295     }
296     /**
297      * <p>Computes a sine.</p>
298      * @param x Any number.
299      * @return The sine of <code>x</code>. This return value is between -1.0 and 1.0.
300      * @see js.MathLike#sin(Object)
301      * @see js.core.JsGlobal.Math#sin(Object)
302      * @since 1.0
303      */
304     public static final double sin(Object x) {
305         return Js.math().sin(x);
306     }
307     /**
308      * <p>Computes a hyperbolic sine.</p>
309      * @param x Any number.
310      * @return The hyperbolic sine of <code>x</code>.
311      * @see js.MathLike#sinh(Object)
312      * @see js.core.JsGlobal.Math#sinh(Object)
313      * @since 1.0
314      */
315     public static final double sinh(Object x) {
316         return Js.math().sinh(x);
317     }
318     /**
319      * <p>Computes a square root.</p>
320      * <p>Note that you can compute arbitrary roots of a number with {@link #pow(Object, Object)}. </p>
321      * @param x A numeric value greater than or equal to zero.
322      * @return The square root of <code>x</code>. Returns <code>NaN</code> if 
323      * <code>x</code> is less than zero.
324      * @see js.MathLike#sqrt(Object)
325      * @see js.core.JsGlobal.Math#sqrt(Object)
326      * @since 1.0
327      */
328     public static final double sqrt(Object x) {
329         return Js.math().sqrt(x);
330     }
331     /**
332      * <p>Computes a tangent.</p>
333      * @param x An angle, measured in radians. To convert degrees to radians, 
334      * multiply the degree value by 0.017453293 (2pi/360).
335      * @return The tangent of the specified angle <code>x</code>.
336      * @see js.MathLike#tan(Object)
337      * @see js.core.JsGlobal.Math#tan(Object)
338      * @since 1.0
339      */
340     public static final double tan(Object x) {
341         return Js.math().tan(x);
342     }
343     /**
344      * <p>Computes a hyperbolic tangent.</p>
345      * @param x Any number.
346      * @return The hyperbolic tangent of <code>x</code>.
347      * @see js.MathLike#tanh(Object)
348      * @see js.core.JsGlobal.Math#tanh(Object)
349      * @since 1.0
350      */
351     public static final double tanh(Object x) {
352         return Js.math().tanh(x);
353     }
354 }