PageRenderTime 28ms CodeModel.GetById 14ms app.highlight 7ms RepoModel.GetById 2ms app.codeStats 0ms

/interpreter/tags/at2dist041108/src/edu/vub/at/objects/ATNumber.java

http://ambienttalk.googlecode.com/
Java | 172 lines | 15 code | 15 blank | 142 comment | 0 complexity | 2794c5e549d59946bcb87a274a9a29e1 MD5 | raw file
  1/**
  2 * AmbientTalk/2 Project
  3 * ATNumber.java created on 26-jul-2006 at 15:15:59
  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;
 31
 32/**
 33 * ATNumber is the public interface to an AmbientTalk native number (an integer value).
 34 * 
 35 * @author tvc
 36 */
 37public interface ATNumber extends ATNumeric {
 38
 39	// base-level interface
 40	
 41	//	Arithmetic operations
 42	/**
 43	 * Returns the number plus 1.
 44	 *
 45	 * @return an ATNumber resulting of adding 1 to the receiver.
 46	 */	
 47	public ATNumber base_inc() throws InterpreterException;
 48	
 49	/**
 50	 * Returns the number minus 1.
 51	 *
 52	 * @return an ATNumber resulting of subtracting 1 to the receiver.
 53	 */	
 54	public ATNumber base_dec() throws InterpreterException;
 55	
 56	/**
 57	 * Returns the absolute value of a number.
 58	 * <p>
 59	 * More specifically: 
 60	 * <ul>
 61	 * <li>If the receiver >= 0, the receiver is returned. 
 62	 * <li>If the receiver < 0, the negation of the receiver is returned. 
 63	 * </ul>
 64	 *  
 65	 * @return the absolute value of the receiver.
 66	 */	
 67	public ATNumber base_abs() throws InterpreterException;
 68	
 69	/**
 70	 * Iterates as many times as the value of the number applying a closure passed as argument. 
 71	 * <p>
 72	 * More specifically, the equivalent pseudo-code for this construct is:
 73	 * <code>for i = 1 to receiver do code.eval(i); nil </code>
 74	 * <p>
 75	 * Here comes an example about how the doTimes: construct can be used to calculate the factorial of a number.
 76	 * def fact(n) { 
 77	 *   def res := 1; 
 78	 *   n.doTimes: { |i| res := res * i}; 
 79	 *   res
 80	 * }
 81	 * 
 82	 * @param code a closure expected to take one argument to be applied in each iteration
 83	 * @return nil
 84	 * @throws InterpreterException if raised inside the iterator block.
 85	 */	
 86	public ATNil base_doTimes_(ATClosure code) throws InterpreterException;
 87	
 88	/**
 89	 * Iterates from the value of the receiver to the one passed as argument applying a closure. 
 90	 * <p>
 91	 * More specifically, this method calls:
 92	 * <code>receiver.to: end step: 1 do: { |i| code } </code> 
 93	 * <p>
 94	 * Note that if end is bigger than the receiver, the construct behaves as a down-to operation. 
 95	 * If receiver is equals to end, the code is not executed.
 96	 * 
 97	 * @param end a number representing the stop value of the loop.
 98	 * @param code a closure expected to take one argument to be applied in each iteration.
 99	 * @return nil
100	 * @throws InterpreterException if raised inside the iterator block.
101	 */	
102	public ATNil base_to_do_(ATNumber end, ATClosure code) throws InterpreterException;
103	
104	/**
105	 * Iterates from the value of the receiver to the one passed as argument applying a closure. 
106	 * <p>
107	 * More specifically, the equivalent pseudo-code for this method is:
108	 * <p>
109	 * <code>for (i = receiver; i < end ; i := i + inc) do code.eval(i); nil</code> 
110	 * <p>
111	 * Note that if end is bigger than the receiver, the construct behaves as a down-to operation. 
112	 * If receiver is equals to end, the code is not executed.
113	 *  
114	 * @param end a number representing the stop value of the loop.
115	 * @param inc a number representing the step value of the loop.
116	 * @param code a closure expected to take one argument to be applied in each iteration.
117	 * @return nil
118	 * @throws InterpreterException if raised inside the iterator block.
119	 */	
120	public ATNil base_to_step_do_(ATNumber end, ATNumber inc, ATClosure code) throws InterpreterException;
121	
122	/**
123	 * Returns a table containing the exclusive range from the number to a number passed as argument.
124	 * <p>
125	 * Usage example:
126	 * <p>
127	 * <code> 2 ** 5 => [ 2, 3, 4 ]</code> 
128	 * <code> 5 ** 2 => [ 5, 4, 3 ]</code> 
129	 *  
130	 * @param end a number representing the stop value of the range.
131	 * @return a {@link ATTable} representing [ receiver, ..., end [
132	 */
133	public ATTable base__optms__optms_(ATNumber end) throws InterpreterException;
134	
135	/**
136	 * Returns a table containing the inclusive range from the number to a number passed as argument.
137	 * <p>
138	 * Usage example:
139	 * <p>
140	 * <code> 2 *** 5 => [ 2, 3, 4, 5 ]</code> 
141	 * <code> 5 *** 2 => [ 5, 4, 3, 2 ]</code> 
142	 *  
143	 * @param end a number representing the stop value of the range.
144	 * @return a {@link ATTable} representing [ receiver, ..., end ]
145	 */
146	public ATTable base__optms__optms__optms_(ATNumber end) throws InterpreterException;
147	
148	/**
149	 * Returns a random fraction in the exclusive range from the number to a number passed as argument.
150	 * 
151	 * @param nbr a number representing the stop value of the range.
152	 * @return the {@link ATFraction} chosen randomly in [ receiver, ..., nbr [
153	 */
154	public ATFraction base__opque__opque_(ATNumber nbr) throws InterpreterException;
155	
156	/**
157	 * Returns the modular arithmetic between the number and another number passed as argument.
158	 * 
159	 * @param nbr a number.
160	 * @return an {@link ATNumber} resulting of the remainder of the division (of receiver by nbr) that truncates towards zero.
161	 */
162	public ATNumber base__oprem_(ATNumber nbr) throws InterpreterException;
163	
164	/**
165	 * Returns the floor division between the number and another number passed as argument.
166	 * 
167	 * @param nbr a number.
168	 * @return a {@link ATNumber} resulting of the floor division of receiver by nbr.
169	 */
170	public ATNumber base__opdiv__opmns_(ATNumber nbr) throws InterpreterException;
171	
172}