PageRenderTime 30ms CodeModel.GetById 12ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 0ms

/interpreter/tags/at2dist110511/src/edu/vub/at/objects/ATNumeric.java

http://ambienttalk.googlecode.com/
Java | 395 lines | 37 code | 35 blank | 323 comment | 0 complexity | 5a799932da082b6b20d8fd62949868df MD5 | raw file
  1/**
  2 * AmbientTalk/2 Project
  3 * ATNumeric.java created on 18-aug-2006 at 11:00:01
  4 * (c) Programming Technology Lab, 2006 - 2007
  5 * Authors: Tom Van Cutsem & Stijn Mostinckx
  6 * 
  7 * Permission is hereby granted, free of charge, to any person
  8 * obtaining a copy of this software and associated documentation
  9 * files (the "Software"), to deal in the Software without
 10 * restriction, including without limitation the rights to use,
 11 * copy, modify, merge, publish, distribute, sublicense, and/or
 12 * sell copies of the Software, and to permit persons to whom the
 13 * Software is furnished to do so, subject to the following
 14 * conditions:
 15 *
 16 * The above copyright notice and this permission notice shall be
 17 * included in all copies or substantial portions of the Software.
 18 *
 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 21 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 23 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 25 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 26 * OTHER DEALINGS IN THE SOFTWARE.
 27 */
 28package edu.vub.at.objects;
 29
 30import edu.vub.at.exceptions.InterpreterException;
 31import edu.vub.at.objects.grammar.ATExpression;
 32import edu.vub.at.objects.natives.NATText;
 33
 34/**
 35 * ATNumeric is the public interface common to numbers and fractions.
 36 * 
 37 * This interface extends ATExpression as a number or fraction can also be output by the parser as a literal.
 38 * 
 39 * @author tvc
 40 */
 41public interface ATNumeric extends ATExpression {
 42
 43	// base-level interface to both numbers and fractions
 44
 45	/**
 46	 * Returns the trigonometric cosine of the numeric data type representing an angle in radians.
 47	 *  
 48	 * @return the cosine of the receiver.
 49	 */
 50	public ATFraction base_cos() throws InterpreterException;
 51	
 52	/**
 53	 * Returns the trigonometric sine of the numeric data type representing an angle in radians.
 54	 *  
 55	 * @return the sine of the receiver.
 56	 */
 57	public ATFraction base_sin() throws InterpreterException;
 58	
 59	/**
 60	 * Returns the trigonometric tangent of the numeric data type representing an angle in radians.
 61	 *  
 62	 * @return the tangent of the receiver.
 63	 */
 64	public ATFraction base_tan() throws InterpreterException;
 65	
 66	/**
 67	 * Returns the natural logarithm (base e) of the numeric data type.
 68	 *   
 69	 * @return the natural logarithm of the receiver or NaN if the receiver is smaller than 0.0.
 70	 */
 71	public ATFraction base_log() throws InterpreterException;
 72	
 73	/**
 74	 * Returns the positive square root of the numeric data type.
 75	 * 
 76	 * @return the correctly rounded positive square root of a or NaN if the receiver is smaller than zero. 
 77	 */
 78	public ATFraction base_sqrt() throws InterpreterException;
 79	
 80	/**
 81	 * Returns the closest number to the fraction.
 82	 * <p>
 83	 * More specifically, rounding a number is equivalent to <code> (fraction + 0.5).floor() </code>
 84	 *
 85	 * @return an ATNumber resulting of rounding the receiver to the closest number value.
 86	 */	
 87	public ATNumber base_round() throws InterpreterException;
 88	
 89	/**
 90	 * Returns the closest number to positive infinity that is smaller than the fraction.
 91	 *
 92	 * @return the closest number to positive infinity that is smaller than the fraction.
 93	 */	
 94	public ATNumber base_floor() throws InterpreterException;
 95	
 96	/**
 97	 * Returns the closest number to negative infinity that is greater than the fraction.
 98	 *
 99	 * @return the closest number to negative infinity that is greater than the fraction.
100	 */	
101	public ATNumber base_ceiling() throws InterpreterException;
102	
103	/**
104	 * Returns the numeric data type raised to the power of the argument.
105	 * 
106	 * @param pow a ATNumeric data type representing the exponent.
107	 * @return the receiver raised to the power of the argument.
108	 * @throws XTypeMismatch if the exponent is not an {@link ATNumeric} object.
109	 */
110	public ATFraction base_expt(ATNumeric pow) throws InterpreterException;	
111	
112	// addition +
113	/**
114	 * Addition infix operator. Returns the value resulting of the sum of the receiver and 
115	 * another numeric data type passed as argument.
116	 * <p>
117	 * More specifically, this operator actually calls:
118	 * <ul>
119	 * <li><code>other.addNumber(this) if the receiver is a {@link ATNumber}</code>
120	 * <li><code>other.addFraction(this) if the receiver is a {@link ATFraction}</code>
121	 * </ul>
122	 *  
123	 * @param other a numeric data type.
124	 * @return a ATNumeric resulting of the sum of the receiver and other. 
125	 */	
126	public ATNumeric base__oppls_(ATNumeric other) throws InterpreterException;
127	
128	/**
129	 * Returns the value resulting of the sum of the receiver and a number passed as argument.
130	 * <p>
131	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to sum are {@link ATNumber} objects.
132	 * Otherwise, an {@link ATFraction} is returned. 
133	 * <p>
134	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the addition operator.
135	 * 
136	 * @param other a number.
137	 * @return a ATNumeric resulting of the sum of the receiver and other. 
138	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
139	 */	
140	public ATNumeric base_addNumber(ATNumber other) throws InterpreterException;
141	
142	/**
143	 * Returns the value resulting of the sum of the receiver and a fraction passed as argument.
144	 * <p>
145	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the addition operator.
146	 * 
147	 * @param other a fraction.
148	 * @return a {@link ATFraction} resulting of the sum of the receiver and other. 
149	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
150	 */	
151	public ATNumeric base_addFraction(ATFraction other) throws InterpreterException;
152	
153	// subtraction -
154	/**
155	 * Subtraction infix operator. Returns the value resulting of subtracting 
156	 * a numeric data type passed as argument from the receiver.
157	 * <p>
158	 * More specifically, this operator actually calls:
159	 * <ul>
160	 * <li><code>other.subtractNumber(this) if the receiver is a {@link ATNumber}</code>
161	 * <li><code>other.subtractFraction(this) if the receiver is a {@link ATFraction}</code>
162	 * </ul>
163	 * 
164	 * @param other a numeric data type.
165	 * @return a ATNumeric resulting of subtracting other from the receiver. 
166	 */	
167	public ATNumeric base__opmns_(ATNumeric other) throws InterpreterException;
168	
169	/** 
170	 * Returns the value resulting of subtracting the receiver from a number passed as argument.
171	 * <p>
172	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to subtract are {@link ATNumber} objects.
173	 * Otherwise, an {@link ATFraction} is returned. 
174	 * <p>
175	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the subtraction operator.
176	 * 
177	 * @param other a number.
178	 * @return a ATNumeric resulting of subtracting other from the receiver.
179	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
180	 */	
181	public ATNumeric base_subtractNumber(ATNumber other) throws InterpreterException;
182	
183	/**
184	 * Returns the value resulting of the subtracting the receiver from a fraction passed as argument.
185	 * <p>
186	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the subtraction operator.
187	 *  
188	 * @param other a fraction.
189	 * @return a {@link ATFraction} resulting of subtracting other from the receiver. 
190	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
191	 */	
192	public ATNumeric base_subtractFraction(ATFraction other) throws InterpreterException;
193	
194	// multiplication *
195	/**
196	 * Multiplication infix operator. Returns the value resulting of multiplying the receiver by 
197	 * another numeric data type passed as argument.
198	 * <p>
199	 * More specifically, this operator actually calls:
200	 * <ul>
201	 * <li><code>other.timesNumber(this) if the receiver is a {@link ATNumber}</code>
202	 * <li><code>other.timesFraction(this) if the receiver is a {@link ATFraction}</code>
203	 * </ul>
204	 * 
205	 * @param other a numeric data type.
206	 * @return a ATNumeric resulting of multiplying the receiver by other. 
207	 */	
208	public ATNumeric base__optms_(ATNumeric other) throws InterpreterException;
209	
210	/**
211	 * Returns the value resulting of multiplying the receiver by a number passed as argument.
212	 * <p>
213	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to multiply are {@link ATNumber} objects.
214	 * Otherwise, an {@link ATFraction} is returned. 
215	 * <p>
216     * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the multiplication operator.
217     * 
218	 * @param other a number.
219	 * @return a ATNumeric resulting of multiplying the receiver by other. 
220	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
221	 */	
222	public ATNumeric base_timesNumber(ATNumber other) throws InterpreterException;
223	
224	/**
225	 * Returns the value resulting of multiplying the receiver by a fraction passed as argument.
226	 * <p>
227	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the multiplication operator.
228	 *  
229	 * @param other a fraction.
230	 * @return a {@link ATFraction} resulting of multiplying the receiver by other. 
231	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
232	 */	
233	public ATNumeric base_timesFraction(ATFraction other) throws InterpreterException;
234	
235	// division /
236	/**
237	 * Division infix operator ("/"). Returns the value resulting of dividing the receiver by 
238	 * another numeric data type passed as argument.
239	 * <p>
240	 * More specifically, this operator actually calls:
241	 * <ul>
242	 * <li><code>other.divideNumber(this) if the receiver is a {@link ATNumber}</code>
243	 * <li><code>other.divideFraction(this) if the receiver is a {@link ATFraction}</code>
244	 * </ul>
245	 * 
246	 * @param other a numeric data type.
247	 * @return a ATNumeric resulting of dividing the receiver by other. 
248	 */	
249	public ATNumeric base__opdiv_(ATNumeric other) throws InterpreterException;
250	
251	/**
252	 * Returns the value resulting of dividing a number passed as argument by the receiver.
253	 * <p>
254	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to multiply are {@link ATNumber} objects.
255	 * Otherwise, an {@link ATFraction} is returned. 
256	 * <p>
257	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the division operator.
258	 * 
259	 * @param other a number.
260	 * @return a ATNumeric resulting of dividing a given number by the receiver. 
261	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
262	 * @throws XIllegalArgument if the receiver is 0.
263	 */	
264	public ATNumeric base_divideNumber(ATNumber other) throws InterpreterException;
265	
266	/**
267	 * Returns the value resulting of dividing a number passed as argument by the receiver.
268	 * <p>
269	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the division operator.
270	 * 
271	 * @param other a fraction.
272	 * @return a {@link ATFraction} resulting of dividing a given number by the receiver. 
273	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
274	 * @throws XIllegalArgument if the receiver is 0.
275	 */
276	public ATNumeric base_divideFraction(ATFraction other) throws InterpreterException;
277	
278	// comparison: generalized equality <=>
279	/**
280	 * Generalized equality infix operator. Returns:
281	 * <ul>
282	 * <li>-1 if the receiver is smaller than the numeric data type passed as argument.
283	 * <li>1 if the receiver is greater than the numeric data type passed as argument.
284	 * <li>0 if the receiver is equal to the numeric data type passed as argument.
285	 * </ul>
286	 * <p>
287	 * This method actually calls:
288	 * <ul>
289	 * <li><code>other.gequalsNumber(this) if the receiver is a {@link ATNumber}</code>
290	 * <li><code>other.gequalsFraction(this) if the receiver is a {@link ATFraction}</code>
291	 * </ul>
292	 * 
293	 * @param other a numeric data type.
294	 * @return a ATNumber resulting of evaluating the generalized equality between the receiver and other. 
295	 */	
296	public ATNumeric base__opltx__opeql__opgtx_(ATNumeric other) throws InterpreterException;
297	
298	/**
299	 * Returns the value of evaluating the generalized equality between the numeric data type and a number.
300	 * <p>
301	 * The generalized equality returns:
302	 * <ul>
303	 * <li>-1 if the receiver is greater than the number passed as argument.
304	 * <li>1 if the receiver is smaller than the number passed as argument.
305	 * <li>0 if the receiver is equal to the number passed as argument.
306	 * </ul>
307	 * <p>
308	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the generalized equality operator.
309	 *
310	 * @param other a number.
311	 * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other. 
312	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
313	 */	
314	public ATNumeric base_gequalsNumber(ATNumber other) throws InterpreterException;
315	
316	/**
317	 * Returns the value of evaluating the generalized equality between the numeric data type and a fraction.
318	 * <p>
319	 * The generalized equality returns:
320	 * <ul>
321	 * <li>-1 if the receiver is greater than the fraction passed as argument.
322	 * <li>1 if the receiver is smaller than the fraction passed as argument.
323	 * <li>0 if the receiver is equal to the fraction passed as argument.
324	 * </ul>
325	 * <p>
326	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the generalized equality operator.
327	 * 
328	 * @param other a number.
329	 * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other. 
330	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
331	 */	
332	public ATNumeric base_gequalsFraction(ATFraction other) throws InterpreterException;
333	
334	// Comparable mixin based on <=>
335	/**
336	 * Returns true if the receiver is smaller than the numeric data type passed as argument.
337	 *
338	 * @param other a numeric data type.
339	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == -1</code> 
340	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
341	 */	
342	public ATBoolean base__opltx_(ATNumeric other) throws InterpreterException; // <
343	
344	/**
345	 * Returns true if the receiver is greater than the numeric data type passed as argument.
346	 *
347	 * @param other a numeric data type.
348	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == 1</code> 
349	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
350	 */	
351	public ATBoolean base__opgtx_(ATNumeric other) throws InterpreterException; // >
352	
353	/**
354	 * Returns true if the receiver is smaller than or equal to the numeric data type passed as argument.
355	 *
356	 * @param other a numeric data type.
357	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != 1</code> 
358	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
359	 */	
360	public ATBoolean base__opltx__opeql_(ATNumeric other) throws InterpreterException; // <=
361	
362	/**
363	 * Returns true if the receiver is greater than or equal to the numeric data type passed as argument.
364	 *
365	 * @param other a numeric data type.
366	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != -1</code> 
367	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
368	 */	
369	public ATBoolean base__opgtx__opeql_(ATNumeric other) throws InterpreterException; // >=
370	
371	/**
372	 * Returns true if the receiver is equal to the numeric data type passed as argument.
373	 *
374	 * @param other a numeric data type.
375	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == 0</code> 
376	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
377	 */	
378	public ATBoolean base__opeql_(ATNumeric other) throws InterpreterException; // =
379	
380	/**
381	 * Returns true if the receiver is different than the numeric data type passed as argument.
382	 *
383	 * @param other an object which compared to this one only if it is a numeric data type.
384	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != 0</code> 
385	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
386	 */	
387	public ATBoolean base__opnot__opeql_(ATObject other) throws InterpreterException; // !=
388
389	/**
390	 * Converts the numeric value into a text string.
391	 * @return a text (an AmbientTalk string) encoding a decimal representation of the numeric value.
392	 */
393	public ATText base_toText() throws InterpreterException;
394	
395}