/interpreter/tags/at2-build270707/src/edu/vub/at/objects/ATTable.java
Java | 198 lines | 19 code | 17 blank | 162 comment | 0 complexity | 6fc539e37d5075675cd083caa524f412 MD5 | raw file
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}