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 js;
021 
022 /**
023  * <p>An <b>opaque</b> interface representing JavaScript numbers.</p>
024  * <p>This interface must be implemented in JS Simulation Libraries.</p>
025  *
026  * @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>
027  * @see Js#number(String)
028  * @see js.core.JsNumber#JsNumber(js.core.JsObject)
029  * @see js.core.JsNumber#JsNumber(Number)
030  * @see js.core.JsNumber#JsNumber(Value)
031  * @see js.core.JsGlobal.Number#create(Object)
032  * @see jsx.core.NumberLikes
033  * 
034  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be 
035  * generated into the target codes. Re-compilers must exit with error on the operations of 
036  * accessing that kind of class objects.
037  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored 
038  * and <tt>instanceof</tt> to it always <tt>true</tt>.
039  */
040 public interface NumberLike<T extends Number>
041 {
042     /**
043      * <p>Converts the current number to a string using exponential notation.</p>
044      * @return A string representation of the current number, in exponential notation. The 
045      * fractional part of the number is rounded, or padded with zeros, as necessary, so that 
046      * it has the specified length.
047      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
048      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
049      * {@link js.core.JsTypeError} for JS Simulation.
050      * @see #toExponential(Object)
051      * @see #toFixed()
052      * @see #toFixed(Object)
053      * @see #toLocaleString()
054      * @see #toPrecision()
055      * @see #toPrecision(Object)
056      * @see #toString()
057      * @see #toString(Object)
058      * @see jsx.core.NumberLikes#toExponential(NumberLike)
059      * @see jsx.core.NumberLikes#toExponential(Number)
060      * @since 1.0
061      * @javascript Re-compilers must convert the interface invocation of this method directly 
062      * into a JavaScript invocation on its current number instance without changing the 
063      * method name, but expanding variable arguments, if any, into comma-separated values. 
064      */
065     public String toExponential();
066     /**
067      * <p>Converts the current number to a string using exponential notation with the 
068      * specified number of digits after the decimal place.</p>
069      * @param digits The number of digits that appears after the decimal point. This may be a 
070      * value between 0 and 20, inclusive, and implementations may optionally support a larger 
071      * range of values. If this argument is undefined, as many digits as necessary are used.
072      * @return A string representation of the current number, in exponential notation, 
073      * with one digit before the decimal place and <tt>digits</tt> digits after the 
074      * decimal place. The fractional part of the number is rounded, or padded with zeros, 
075      * as necessary, so that it has the specified length.
076      * @throws RuntimeException JavaScript throws a <tt>RangeError</tt> if 
077      * <tt>digits</tt> is too small or too large. See {@link Js#err(Object)} and 
078      * {@link js.core.JsRangeError} for JS Simulation. Values between 0 and 20, inclusive, 
079      * will not cause a <tt>RangeError</tt>. Implementations are allowed to support 
080      * larger and smaller values as well.
081      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
082      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
083      * {@link js.core.JsTypeError} for JS Simulation.
084      * @see #toExponential()
085      * @see #toFixed()
086      * @see #toFixed(Object)
087      * @see #toLocaleString()
088      * @see #toPrecision()
089      * @see #toPrecision(Object)
090      * @see #toString()
091      * @see #toString(Object)
092      * @see jsx.core.NumberLikes#toExponential(NumberLike, Object)
093      * @see jsx.core.NumberLikes#toExponential(Number, Object)
094      * @since 1.0
095      * @javascript Re-compilers must convert the interface invocation of this method directly 
096      * into a JavaScript invocation on its current number instance without changing the 
097      * method name, but expanding variable arguments, if any, into comma-separated values. 
098      */
099     public String toExponential(Object digits);
100     /**
101      * <p>Converts the current number to a string without digits after the decimal place.</p>
102      * @return A string representation of the current number that does not use exponential 
103      * notation and has no digits after the decimal place. The number is rounded if 
104      * necessary. If the current number is greater than 1e+21, this method simply calls 
105      * {@link #toString()} and returns a string in exponential notation.
106      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
107      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
108      * {@link js.core.JsTypeError} for JS Simulation.
109      * @see #toFixed(Object)
110      * @see #toExponential()
111      * @see #toExponential(Object)
112      * @see #toLocaleString()
113      * @see #toPrecision()
114      * @see #toPrecision(Object)
115      * @see #toString()
116      * @see #toString(Object)
117      * @see jsx.core.NumberLikes#toFixed(NumberLike)
118      * @see jsx.core.NumberLikes#toFixed(Number)
119      * @since 1.0
120      * @javascript Re-compilers must convert the interface invocation of this method directly 
121      * into a JavaScript invocation on its current number instance without changing the 
122      * method name, but expanding variable arguments, if any, into comma-separated values. 
123      */
124     public String toFixed();
125     /**
126      * <p>Converts the current number to a string that contains a specified number of 
127      * digits after the decimal place.</p>
128      * @param digits The number of digits to appear after the decimal point; this may be a 
129      * value between 0 and 20, inclusive, and implementations may optionally support a 
130      * larger range of values. If this argument is undefined, it is treated as 0.
131      * @return A string representation of the current number that does not use exponential 
132      * notation and has exactly <tt>digits</tt> digits after the decimal place. The number 
133      * is rounded if necessary, and the fractional part is padded with zeros if necessary so 
134      * that it has the specified length. If the current number is greater than 1e+21, this 
135      * method simply calls {@link #toString()} and returns a string in exponential 
136      * notation.
137      * @throws RuntimeException JavaScript throws a <tt>RangeError</tt> if 
138      * <tt>digits</tt> is too small or too large. See {@link Js#err(Object)} and 
139      * {@link js.core.JsRangeError} for JS Simulation. Values between 0 and 20, inclusive, 
140      * will not cause a <tt>RangeError</tt>. Implementations are allowed to support 
141      * larger and smaller values as well.
142      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
143      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
144      * {@link js.core.JsTypeError} for JS Simulation.
145      * @see #toFixed()
146      * @see #toExponential()
147      * @see #toExponential(Object)
148      * @see #toLocaleString()
149      * @see #toPrecision()
150      * @see #toPrecision(Object)
151      * @see #toString()
152      * @see #toString(Object)
153      * @see jsx.core.NumberLikes#toFixed(NumberLike, Object)
154      * @see jsx.core.NumberLikes#toFixed(Number, Object)
155      * @since 1.0
156      * @javascript Re-compilers must convert the interface invocation of this method directly 
157      * into a JavaScript invocation on its current number instance without changing the 
158      * method name, but expanding variable arguments, if any, into comma-separated values. 
159      */
160     public String toFixed(Object digits);
161     /**
162      * <p>Converts the current number to a string.</p>
163      * <p>This method simply calls {@link #toString()} to convert the number to a base-10 
164      * value.</p>
165      * @return A string representation of the current number. The number is rounded or 
166      * padded with zeros as necessary.
167      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
168      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
169      * {@link js.core.JsTypeError} for JS Simulation.
170      * @see #toPrecision(Object)
171      * @see #toExponential()
172      * @see #toExponential(Object)
173      * @see #toFixed()
174      * @see #toFixed(Object)
175      * @see #toLocaleString()
176      * @see #toString()
177      * @see #toString(Object)
178      * @see jsx.core.NumberLikes#toPrecision(NumberLike)
179      * @see jsx.core.NumberLikes#toPrecision(Number)
180      * @since 1.0
181      * @javascript Re-compilers must convert the interface invocation of this method directly 
182      * into a JavaScript invocation on its current number instance without changing the 
183      * method name, but expanding variable arguments, if any, into comma-separated values. 
184      */
185     public String toPrecision();
186     /**
187      * <p>Converts the current number to a string using the specified number of significant 
188      * digits. Uses exponential or fixed-point notation depending on the size of the number 
189      * and the number of significant digits specified.</p>
190      * @param precision The number of significant digits to appear in the returned string. 
191      * This may be a value between 1 and 21, inclusive. Implementations are allowed to 
192      * optionally support larger and smaller values of precision. If this argument is 
193      * undefined, the {@link #toString()} method is used instead to convert the number to 
194      * a base-10 value.
195      * @return A string representation of the current number that contains 
196      * <tt>precision</tt> significant digits. If <tt>precision</tt> is large 
197      * enough to include all the digits of the integer part of the number, the returned 
198      * string uses fixed-point notation. Otherwise, exponential notation is used with one 
199      * digit before the decimal place and <tt>precision - 1</tt> digits after the 
200      * decimal place. The number is rounded or padded with zeros as necessary.
201      * @throws RuntimeException JavaScript throws a <tt>RangeError</tt> if 
202      * <tt>digits</tt> is too small or too large. See {@link Js#err(Object)} and 
203      * {@link js.core.JsRangeError} for JS Simulation. Values between 1 and 20, inclusive, 
204      * will not cause a <tt>RangeError</tt>. Implementations are allowed to support 
205      * larger and smaller values as well.
206      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
207      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
208      * {@link js.core.JsTypeError} for JS Simulation.
209      * @see #toPrecision()
210      * @see #toExponential()
211      * @see #toExponential(Object)
212      * @see #toFixed()
213      * @see #toFixed(Object)
214      * @see #toLocaleString()
215      * @see #toString()
216      * @see #toString(Object)
217      * @see jsx.core.NumberLikes#toPrecision(NumberLike, Object)
218      * @see jsx.core.NumberLikes#toPrecision(Number, Object)
219      * @since 1.0
220      * @javascript Re-compilers must convert the interface invocation of this method directly 
221      * into a JavaScript invocation on its current number instance without changing the 
222      * method name, but expanding variable arguments, if any, into comma-separated values. 
223      */
224     public String toPrecision(Object precision);
225     /**
226      * <p>Converts the current number to a string using local number-formatting conventions.</p> 
227      * @return An implementation-dependent string representation of the current number, 
228      * formatted according to local conventions, which may affect such things as the 
229      * punctuation characters used for the decimal point and the thousands separator.
230      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
231      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
232      * {@link js.core.JsTypeError} for JS Simulation.
233      * @see #toString()
234      * @see #toString(Object)
235      * @see #toExponential()
236      * @see #toExponential(Object)
237      * @see #toFixed()
238      * @see #toFixed(Object)
239      * @see #toPrecision()
240      * @see #toPrecision(Object)
241      * @see jsx.core.NumberLikes#toLocaleString(NumberLike)
242      * @see jsx.core.NumberLikes#toLocaleString(Number)
243      * @since 1.0
244      * @javascript Re-compilers must convert the interface invocation of this method directly 
245      * into a JavaScript invocation on its current number instance without changing the 
246      * method name, but expanding variable arguments, if any, into comma-separated values. 
247      */
248     public String toLocaleString();
249     /**
250      * <p>Converts the current number to a base-10 string.</p> 
251      * @return A base-10 string representation of the current number.
252      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
253      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
254      * {@link js.core.JsTypeError} for JS Simulation.
255      * @see #toString(Object)
256      * @see #toExponential()
257      * @see #toExponential(Object)
258      * @see #toFixed()
259      * @see #toFixed(Object)
260      * @see #toPrecision()
261      * @see #toPrecision(Object)
262      * @see #toLocaleString()
263      * @see jsx.core.NumberLikes#toString(NumberLike)
264      * @see jsx.core.NumberLikes#toString(Number)
265      * @since 1.0
266      * @javascript Re-compilers must convert the interface invocation of this method directly 
267      * into a JavaScript invocation on its current number instance without changing the 
268      * method name, but expanding variable arguments, if any, into comma-separated values. 
269      */
270     public String toString();
271     /**
272      * <p>Converts the current number to a string. When the <tt>radix</tt> argument is 
273      * undefined or is specified as 10, the number is converted to a base-10 string.</p> 
274      * <p>Although the ECMAScript specification does not require implementations to honor 
275      * any other values for radix, all implementations in common use accept values between 
276      * 2 and 36.</p>
277      * @param radix An optional argument that specifies the radix, or base, between 2 and 36, 
278      * in which the number should be represented. If undefined, base 10 is used. Note, 
279      * however, that the ECMAScript specification allows an implementation to return any 
280      * value if this argument is specified as any value other than 10.
281      * @return A string representation of the current number, in the specified base.
282      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
283      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
284      * {@link js.core.JsTypeError} for JS Simulation.
285      * @see #toString()
286      * @see #toExponential()
287      * @see #toExponential(Object)
288      * @see #toFixed()
289      * @see #toFixed(Object)
290      * @see #toPrecision()
291      * @see #toPrecision(Object)
292      * @see #toLocaleString()
293      * @see jsx.core.NumberLikes#toString(NumberLike, Object)
294      * @see jsx.core.NumberLikes#toString(Number, Object)
295      * @since 1.0
296      * @javascript Re-compilers must convert the interface invocation of this method directly 
297      * into a JavaScript invocation on its current number instance without changing the 
298      * method name, but expanding variable arguments, if any, into comma-separated values. 
299      */
300     public String toString(Object radix);
301     /**
302      * <p>Returns a string indicating the data-type of the current instance.</p>
303      * <p>Simulating the JavaScript <tt>typeof</tt> operator and <tt>typeof()</tt> 
304      * function, this invocation evaluates to "number", "string", or "boolean" if the current 
305      * instance is a number, string, or boolean value. It evaluates to "object" for objects, 
306      * arrays. It evaluates to "function" for function instance and to "undefined" if the 
307      * current instance is undefined.</p>
308      * @return A string indicating the data-type of the instance.
309      * @see #valueOf()
310      * @see #undefined()
311      * @since 1.0
312      * @javascript Re-compilers must convert the interface invocation of this method into the 
313      * JavaScript expression: 
314      * <pre>typeof n</pre>
315      * where <tt>n</tt> is the current number instance of this invocation.
316      */
317     public String typeof();
318     /**
319      * <p>Checks if the current instance is undefined.</p>
320      * @return <tt>true</tt> if the current instance is undefined; <tt>false</tt> otherwise.
321      * @see #valueOf()
322      * @see #undefined()
323      * @since 1.0
324      * @javascript Re-compilers must convert the interface invocation of this method into the 
325      * JavaScript expression: 
326      * <pre>(n === undefined)</pre>
327      * where <tt>n</tt> is the current number instance of this invocation.
328      */
329     public boolean undefined();
330     /**
331      * <p>Returns the primitive value associated with the current instance, if there is one. 
332      * This invocation returns the primitive number value associated with the current instance.</p>
333      * @return The primitive number value associated with the current instance.
334      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
335      * is invoked on an instance that is not a number. See {@link Js#err(Object)} and 
336      * {@link js.core.JsTypeError} for JS Simulation.
337      * @see #toString()
338      * @since 1.0
339      * @javascript Re-compilers must convert the interface invocation of this method directly 
340      * into a JavaScript invocation on its current number instance without changing the 
341      * method name, but expanding variable arguments, if any, into comma-separated values. 
342      */
343     public T valueOf();
344 }