/interpreter/tags/at2dist110511/src/edu/vub/at/objects/ATNumeric.java
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}