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

  1/**
  2 * AmbientTalk/2 Project
  3 * ATTable.java created on 26-jul-2006 at 15:19:44
  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 * ATTable is the public interface to a native AmtientTalk table (an array).
 35 * Extends the ATExpression interface as a Table may also be output by the parser as a literal.
 36 * 
 37 * An important distinction between ATTables and other languages such as Java is that
 38 * ATTable objects are indexed from [1..size] 
 39 * 
 40 * @author tvcutsem
 41 */
 42public interface ATTable extends ATExpression {
 43
 44	// base-level interface
 45	
 46	/**
 47	 * Returns the length of the table
 48	 *
 49	 * @return the length of the table as an {@link ATNumber}.
 50	 */	
 51	public ATNumber base_length() throws InterpreterException;
 52	
 53	/**
 54	 * Returns the value of the element at the index passed as argument. 
 55	 *
 56	 * @param index a position in the table.
 57	 * @return ATObject representing the value of the element at the specified index.
 58	 * @throws XTypeMismatch if the index is not an {@link ATNumber}.
 59	 * @throws XIndexOutOfBounds if the index is negative or if it is greater than the length of the table.
 60	 */	
 61	public ATObject base_at(ATNumber index) throws InterpreterException;
 62	/**
 63	 * Sets the value of the element at the specified index to the new value passed as argument.
 64	 * 
 65	 * @param index a position in the table at which the given element is to be stored.
 66	 * @param value the element to be stored.
 67	 * @return value an {@link ATObject} representing the value stored in the table at the given index - i.e. the value argument.
 68	 * @throws XTypeMismatch if the index is not an {@link ATNumber} or if the value is not an {@link ATObject}.
 69	 * @throws XIndexOutOfBounds if the index is negative or if it is greater than to the length of the table
 70	 */	
 71	public ATObject base_atPut(ATNumber index, ATObject value) throws InterpreterException;
 72	
 73	/**
 74	 * Checks if the table is empty
 75	 *
 76	 * @return true if the size of the table is zero. Otherwise, false.
 77	 */	
 78	public ATBoolean base_isEmpty() throws InterpreterException;
 79	
 80	/**
 81	 * Applies a closure to each element of the table.
 82	 * <p>
 83	 * Usage example:
 84	 * <code>[1,2,3].each: { |i| system.println(i) }</code>
 85	 * 
 86	 * @param code a closure that takes one argument and is applied to each element of the table.
 87	 * @return nil
 88	 * @throws InterpreterException if raised inside the code closure.
 89	 */
 90	public ATNil base_each_(ATClosure code) throws InterpreterException;
 91	
 92	/**
 93	 * Maps a closure over each element of the table, resulting in a new table.
 94	 * <p>
 95	 * Usage example:
 96	 * <code>[1,2,3].map: { |i| i + 1 } </code> returns <code>"[2, 3, 4]"</code> 
 97	 * 
 98	 * @param code a closure that takes one argument and is applied to each element of the table.
 99	 * @return nil
100	 * @throws InterpreterException if raised inside the code closure.
101	 */
102	public ATTable base_map_(ATClosure code) throws InterpreterException;
103
104	/**
105	 * Collects all elements of the table by combining them using the given closure.
106	 * The first time closure is called, the given initializing element is passed as first argument.
107	 * <p>
108	 * Usage example:
109	 * <code>result := [1,2,3].inject: 0 into: { |total, next| total + next }</code> where the value of <code>result</code> is 6.
110	 *
111	 * @param init an {@link ATObject} passed as first argument the first time the closure is called.
112	 * @param code a closure that takes one argument and is applied to each element of the table.
113	 * @return {@link ATObject} representing the value of the last applied closure.
114	 * @throws XIndexOutOfBounds if the index is negative or if it is greater than the length of the table
115	 * @throws InterpreterException if raised inside the code closure.
116	 */
117	public ATObject base_inject_into_(ATObject init, ATClosure code) throws InterpreterException;
118	//result := [ tabl ].filter: { |elt| booleanCondition(elt) }
119	
120	/**
121	 * Returns a new table containing only those elements of the table for which the closure evaluates to true.
122	 * <p>
123	 * Usage example:
124	 * <code>[1,2,3].filter: {|e| e != 2 }</code> returns <code>[1, 3]</code>
125	 * 
126	 * @param code a closure that takes one argument and is applied to each element of the table.
127	 * @return ATTable containing those elements of the table for which the closure evaluates to true.
128	 * @throws InterpreterException if raised inside the code closure.
129	 */
130	public ATTable base_filter_(ATClosure code) throws InterpreterException;
131	//result := [ tabl ].find: { |elt| booleanCondition(elt) }
132	
133	/**
134	 * Returns the index of the first element for which the given predicate returns true.
135	 * <p>
136	 * Returns nil if no element satisfying the closure can be found.
137	 * <p>
138	 * Usage example:
139	 * <code>[`a, `b, `c].find: { |e| e == `d }</code> returns <code>nil</code>
140	 * 
141	 * @param code a closure that takes one argument and is applied to each element of the table.
142	 * @return {@link ATNumber} representing the index of the first element for which the given closure evaluates to true. Otherwise, nil. 
143	 * @throws InterpreterException if raised inside the code closure.
144	 */
145	public ATObject base_find_(ATClosure code) throws InterpreterException;
146
147	/**
148	 * Returns true if and only if there exists an element e in the table for which
149	 *  'obj == e' evaluates to true.
150	 * <p>
151	 * Usage example:
152	 * <code>[`a, `b, `c].contains(`d)</code> returns <code>false</code>
153	 * 
154	 * @param obj the element to find in the table
155	 * @return true if exists an element in the table for which 'obj == e' evaluates to true. Otherwise, false.
156	 */
157	public ATBoolean base_contains(ATObject obj) throws InterpreterException;
158	
159	/**
160	 * Implodes the receiver table of characters into a text string.
161	 * 
162	 * @return the {@link ATText} resulting of the implosion of the table.
163	 */
164	public ATText base_implode() throws InterpreterException;
165	
166	/**
167	 * Joins all the text elements of the receiver table into a text string where the given text is used as a separator.
168	 *
169	 * @param sep a text used as separator in the resulting text string.
170	 * @return an {@link ATText} resulting of the join of all the text elements of the receiver using the sep text as separator.
171	 *
172	 */
173	public ATText base_join(ATText sep) throws InterpreterException;
174	
175	/**
176	 * Selects the subrange of the table specified by the given limits.
177	 * <p>
178	 * Usage example:
179	 * <code>[a, b, c, d, e].select(2,4)</code> returns <code>[b, c, d]</code>
180	 * 
181	 * @param start a number representing the lower limit of the range.
182	 * @param stop a number representing the upper limit of the range.
183	 * @return an ATTable resulting of the selection.
184	 */
185	public ATTable base_select(ATNumber start, ATNumber stop) throws InterpreterException;
186	
187	/**
188	 * Concatenation infix operator. Returns the concatenation of the receiver table and the given table.
189	 * <p>
190	 * Usage example:
191	 * <code>[1,2,3] + [4,5] </code> returns <code>[1,2,3,4,5]</code>
192	 * 
193	 * @param other a table to concatenate to the receiver table.
194	 * @return an ATTable containing the elements of the receiver table and then the elements of the other table.
195	 */
196	public ATTable base__oppls_(ATTable other) throws InterpreterException;
197	
198}