/interpreter/tags/at2-build270707/src/edu/vub/at/objects/ATNumeric.java

  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;
 32
 33/**
 34 * ATNumeric is the public interface common to numbers and fractions.
 35 * 
 36 * This interface extends ATExpression as a number or fraction can also be output by the parser as a literal.
 37 * 
 38 * @author tvc
 39 */
 40public interface ATNumeric extends ATExpression {
 41
 42	// base-level interface to both numbers and fractions
 43
 44	/**
 45	 * Returns the trigonometric cosine of the numeric data type representing an angle in radians.
 46	 *  
 47	 * @return the cosine of the receiver.
 48	 */
 49	public ATFraction base_cos() throws InterpreterException;
 50	
 51	/**
 52	 * Returns the trigonometric sine of the numeric data type representing an angle in radians.
 53	 *  
 54	 * @return the sine of the receiver.
 55	 */
 56	public ATFraction base_sin() throws InterpreterException;
 57	
 58	/**
 59	 * Returns the trigonometric tangent of the numeric data type representing an angle in radians.
 60	 *  
 61	 * @return the tangent of the receiver.
 62	 */
 63	public ATFraction base_tan() throws InterpreterException;
 64	
 65	/**
 66	 * Returns the natural logarithm (base e) of the numeric data type.
 67	 *   
 68	 * @return the natural logarithm of the receiver or NaN if the receiver is smaller than 0.0.
 69	 */
 70	public ATFraction base_log() throws InterpreterException;
 71	
 72	/**
 73	 * Returns the positive square root of the numeric data type.
 74	 * 
 75	 * @return the correctly rounded positive square root of a or NaN if the receiver is smaller than zero. 
 76	 */
 77	public ATFraction base_sqrt() throws InterpreterException;
 78	
 79	/**
 80	 * Returns the numeric data type raised to the power of the argument.
 81	 * 
 82	 * @param pow a ATNumeric data type representing the exponent.
 83	 * @return the receiver raised to the power of the argument.
 84	 * @throws XTypeMismatch if the exponent is not an {@link ATNumeric} object.
 85	 */
 86	public ATFraction base_expt(ATNumeric pow) throws InterpreterException;	
 87	
 88	// addition +
 89	/**
 90	 * Addition infix operator. Returns the value resulting of the sum of the receiver and 
 91	 * another numeric data type passed as argument.
 92	 * <p>
 93	 * More specifically, this operator actually calls:
 94	 * <ul>
 95	 * <li><code>other.addNumber(this) if the receiver is a {@link ATNumber}</code>
 96	 * <li><code>other.addFraction(this) if the receiver is a {@link ATFraction}</code>
 97	 * </ul>
 98	 *  
 99	 * @param other a numeric data type.
100	 * @return a ATNumeric resulting of the sum of the receiver and other. 
101	 */	
102	public ATNumeric base__oppls_(ATNumeric other) throws InterpreterException;
103	
104	/**
105	 * Returns the value resulting of the sum of the receiver and a number passed as argument.
106	 * <p>
107	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to sum are {@link ATNumber} objects.
108	 * Otherwise, an {@link ATFraction} is returned. 
109	 * <p>
110	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the addition operator.
111	 * 
112	 * @param other a number.
113	 * @return a ATNumeric resulting of the sum of the receiver and other. 
114	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
115	 */	
116	public ATNumeric base_addNumber(ATNumber other) throws InterpreterException;
117	
118	/**
119	 * Returns the value resulting of the sum of the receiver and a fraction passed as argument.
120	 * <p>
121	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the addition operator.
122	 * 
123	 * @param other a fraction.
124	 * @return a {@link ATFraction} resulting of the sum of the receiver and other. 
125	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
126	 */	
127	public ATNumeric base_addFraction(ATFraction other) throws InterpreterException;
128	
129	// subtraction -
130	/**
131	 * Subtraction infix operator. Returns the value resulting of subtracting 
132	 * a numeric data type passed as argument from the receiver.
133	 * <p>
134	 * More specifically, this operator actually calls:
135	 * <ul>
136	 * <li><code>other.subtractNumber(this) if the receiver is a {@link ATNumber}</code>
137	 * <li><code>other.subtractFraction(this) if the receiver is a {@link ATFraction}</code>
138	 * </ul>
139	 * 
140	 * @param other a numeric data type.
141	 * @return a ATNumeric resulting of subtracting other from the receiver. 
142	 */	
143	public ATNumeric base__opmns_(ATNumeric other) throws InterpreterException;
144	
145	/** 
146	 * Returns the value resulting of subtracting the receiver from a number passed as argument.
147	 * <p>
148	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to subtract are {@link ATNumber} objects.
149	 * Otherwise, an {@link ATFraction} is returned. 
150	 * <p>
151	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the subtraction operator.
152	 * 
153	 * @param other a number.
154	 * @return a ATNumeric resulting of subtracting other from the receiver.
155	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
156	 */	
157	public ATNumeric base_subtractNumber(ATNumber other) throws InterpreterException;
158	
159	/**
160	 * Returns the value resulting of the subtracting the receiver from a fraction passed as argument.
161	 * <p>
162	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the subtraction operator.
163	 *  
164	 * @param other a fraction.
165	 * @return a {@link ATFraction} resulting of subtracting other from the receiver. 
166	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
167	 */	
168	public ATNumeric base_subtractFraction(ATFraction other) throws InterpreterException;
169	
170	// multiplication *
171	/**
172	 * Multiplication infix operator. Returns the value resulting of multiplying the receiver by 
173	 * another numeric data type passed as argument.
174	 * <p>
175	 * More specifically, this operator actually calls:
176	 * <ul>
177	 * <li><code>other.timesNumber(this) if the receiver is a {@link ATNumber}</code>
178	 * <li><code>other.timesFraction(this) if the receiver is a {@link ATFraction}</code>
179	 * </ul>
180	 * 
181	 * @param other a numeric data type.
182	 * @return a ATNumeric resulting of multiplying the receiver by other. 
183	 */	
184	public ATNumeric base__optms_(ATNumeric other) throws InterpreterException;
185	
186	/**
187	 * Returns the value resulting of multiplying the receiver by a number passed as argument.
188	 * <p>
189	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to multiply are {@link ATNumber} objects.
190	 * Otherwise, an {@link ATFraction} is returned. 
191	 * <p>
192     * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the multiplication operator.
193     * 
194	 * @param other a number.
195	 * @return a ATNumeric resulting of multiplying the receiver by other. 
196	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
197	 */	
198	public ATNumeric base_timesNumber(ATNumber other) throws InterpreterException;
199	
200	/**
201	 * Returns the value resulting of multiplying the receiver by a fraction passed as argument.
202	 * <p>
203	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the multiplication operator.
204	 *  
205	 * @param other a fraction.
206	 * @return a {@link ATFraction} resulting of multiplying the receiver by other. 
207	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
208	 */	
209	public ATNumeric base_timesFraction(ATFraction other) throws InterpreterException;
210	
211	// division /
212	/**
213	 * Division infix operator ("/"). Returns the value resulting of dividing the receiver by 
214	 * another numeric data type passed as argument.
215	 * <p>
216	 * More specifically, this operator actually calls:
217	 * <ul>
218	 * <li><code>other.divideNumber(this) if the receiver is a {@link ATNumber}</code>
219	 * <li><code>other.divideFraction(this) if the receiver is a {@link ATFraction}</code>
220	 * </ul>
221	 * 
222	 * @param other a numeric data type.
223	 * @return a ATNumeric resulting of dividing the receiver by other. 
224	 */	
225	public ATNumeric base__opdiv_(ATNumeric other) throws InterpreterException;
226	
227	/**
228	 * Returns the value resulting of dividing a number passed as argument by the receiver.
229	 * <p>
230	 * More specifically, this method returns a {@link ATNumber} if both numeric data types to multiply are {@link ATNumber} objects.
231	 * Otherwise, an {@link ATFraction} is returned. 
232	 * <p>
233	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the division operator.
234	 * 
235	 * @param other a number.
236	 * @return a ATNumeric resulting of dividing a given number by the receiver. 
237	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
238	 * @throws XIllegalArgument if the receiver is 0.
239	 */	
240	public ATNumeric base_divideNumber(ATNumber other) throws InterpreterException;
241	
242	/**
243	 * Returns the value resulting of dividing a number passed as argument by the receiver.
244	 * <p>
245	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the division operator.
246	 * 
247	 * @param other a fraction.
248	 * @return a {@link ATFraction} resulting of dividing a given number by the receiver. 
249	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
250	 * @throws XIllegalArgument if the receiver is 0.
251	 */
252	public ATNumeric base_divideFraction(ATFraction other) throws InterpreterException;
253	
254	// comparison: generalized equality <=>
255	/**
256	 * Generalized equality infix operator. Returns:
257	 * <ul>
258	 * <li>-1 if the receiver is smaller than the numeric data type passed as argument.
259	 * <li>1 if the receiver is greater than the numeric data type passed as argument.
260	 * <li>0 if the receiver is equal to the numeric data type passed as argument.
261	 * </ul>
262	 * <p>
263	 * This method actually calls:
264	 * <ul>
265	 * <li><code>other.gequalsNumber(this) if the receiver is a {@link ATNumber}</code>
266	 * <li><code>other.gequalsFraction(this) if the receiver is a {@link ATFraction}</code>
267	 * </ul>
268	 * 
269	 * @param other a numeric data type.
270	 * @return a ATNumber resulting of evaluating the generalized equality between the receiver and other. 
271	 */	
272	public ATNumeric base__opltx__opeql__opgtx_(ATNumeric other) throws InterpreterException;
273	
274	/**
275	 * Returns the value of evaluating the generalized equality between the numeric data type and a number.
276	 * <p>
277	 * The generalized equality returns:
278	 * <ul>
279	 * <li>-1 if the receiver is greater than the number passed as argument.
280	 * <li>1 if the receiver is smaller than the number passed as argument.
281	 * <li>0 if the receiver is equal to the number passed as argument.
282	 * </ul>
283	 * <p>
284	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the generalized equality operator.
285	 *
286	 * @param other a number.
287	 * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other. 
288	 * @throws XTypeMismatch if other is not an {@link ATNumber} object.
289	 */	
290	public ATNumeric base_gequalsNumber(ATNumber other) throws InterpreterException;
291	
292	/**
293	 * Returns the value of evaluating the generalized equality between the numeric data type and a fraction.
294	 * <p>
295	 * The generalized equality returns:
296	 * <ul>
297	 * <li>-1 if the receiver is greater than the fraction passed as argument.
298	 * <li>1 if the receiver is smaller than the fraction passed as argument.
299	 * <li>0 if the receiver is equal to the fraction passed as argument.
300	 * </ul>
301	 * <p>
302	 * Note that this is a double-dispatch method used to determine the correct runtime type of both arguments of the generalized equality operator.
303	 * 
304	 * @param other a number.
305	 * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other. 
306	 * @throws XTypeMismatch if other is not an {@link ATFraction} object.
307	 */	
308	public ATNumeric base_gequalsFraction(ATFraction other) throws InterpreterException;
309	
310	// Comparable mixin based on <=>
311	/**
312	 * Returns true if the receiver is smaller than the numeric data type passed as argument.
313	 *
314	 * @param other a numeric data type.
315	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == -1</code> 
316	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
317	 */	
318	public ATBoolean base__opltx_(ATNumeric other) throws InterpreterException; // <
319	
320	/**
321	 * Returns true if the receiver is greater than the numeric data type passed as argument.
322	 *
323	 * @param other a numeric data type.
324	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == 1</code> 
325	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
326	 */	
327	public ATBoolean base__opgtx_(ATNumeric other) throws InterpreterException; // >
328	
329	/**
330	 * Returns true if the receiver is smaller than or equal to the numeric data type passed as argument.
331	 *
332	 * @param other a numeric data type.
333	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != 1</code> 
334	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
335	 */	
336	public ATBoolean base__opltx__opeql_(ATNumeric other) throws InterpreterException; // <=
337	
338	/**
339	 * Returns true if the receiver is greater than or equal to the numeric data type passed as argument.
340	 *
341	 * @param other a numeric data type.
342	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != -1</code> 
343	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
344	 */	
345	public ATBoolean base__opgtx__opeql_(ATNumeric other) throws InterpreterException; // >=
346	
347	/**
348	 * Returns true if the receiver is equal to the numeric data type passed as argument.
349	 *
350	 * @param other a numeric data type.
351	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) == 0</code> 
352	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
353	 */	
354	public ATBoolean base__opeql_(ATNumeric other) throws InterpreterException; // =
355	
356	/**
357	 * Returns true if the receiver is different than the numeric data type passed as argument.
358	 *
359	 * @param other a numeric data type.
360	 * @return a {@link ATBoolean} resulting of evaluating <code> (receiver <=> other) != 0</code> 
361	 * @throws XTypeMismatch if other is not an {@link ATNumeric} object.
362	 */	
363	public ATBoolean base__opnot__opeql_(ATNumeric other) throws InterpreterException; // !=
364
365}