1 /* 2 * Copyright the original author or authors. 3 * 4 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.mozilla.org/MPL/MPL-1.1.html 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 import org.as2lib.core.BasicInterface; 18 import org.as2lib.data.holder.Iterator; 19 20 /** 21 * {@code List} holds values by index. Each value has its unique index. 22 * 23 * <p>Example: 24 * <code> 25 * var list:List = new MyList(); 26 * list.insert("myValue1"); 27 * list.insertFirst("myValue2"); 28 * list.insertLast("myValue3"); 29 * trace(list.contains("myValue2")); 30 * trace(list.remove(0)); 31 * trace(list.contains("myValue2")); 32 * trace(list.removeLast()); 33 * trace(list.get(0)); 34 * list.clear(); 35 * trace(list.size()); 36 * </code> 37 * 38 * <p>Output: 39 * <pre> 40 * true 41 * myValue2 42 * false 43 * myValue3 44 * myValue1 45 * 0 46 * </pre> 47 * 48 * @author Simon Wacker 49 */ 50 interface org.as2lib.data.holder.List extends BasicInterface { 51 52 /** 53 * @overload #insertByValue 54 * @overload #insertByIndexAndValue 55 */ 56 public function insert():Void; 57 58 /** 59 * Inserts {@code value} at the end of this list. 60 * 61 * @param value the value to insert 62 * @see #insertLast 63 */ 64 public function insertByValue(value):Void; 65 66 /** 67 * Inserts {@code value} at the given {@code index}. 68 * 69 * <p>The element that is currently at the given {@code index} is shifted by one to 70 * the right, as well as any subsequent elements. 71 * 72 * @param index the index at which to insert the {@code value} 73 * @param value the value to insert 74 * @throws IndexOutOfBoundsException if the given {@code index} is not in range, 75 * this is less than 0 or greater than this list's size 76 */ 77 public function insertByIndexAndValue(index:Number, value):Void; 78 79 /** 80 * Inserts {@code value} at the beginning of this list. 81 * 82 * @param value the value to insert 83 */ 84 public function insertFirst(value):Void; 85 86 /** 87 * Inserts {@code value} at the end of this list. 88 * 89 * @param value the value to insert 90 * @see #insert 91 */ 92 public function insertLast(value):Void; 93 94 /** 95 * @overload #insertAllByList 96 * @overload #insertAllByIndexAndList 97 */ 98 public function insertAll():Void; 99 100 /** 101 * Inserts all values contained in {@code list} to the end of this list. 102 * 103 * @param list the values to insert 104 */ 105 public function insertAllByList(list:List):Void; 106 107 /** 108 * Inserts all values contained in {@code list} to this list, starting at the 109 * specified {@code index}. 110 * 111 * <p>Elements that are at an affected index are shifted to the right by the size 112 * of the given {@code list}. 113 * 114 * @param index the index to start the insertion at 115 * @param list the values to insert 116 * @throws IndexOutOfBoundsException if the given {@code index} is not in range, 117 * this is less than 0 or greater than this list's size 118 */ 119 public function insertAllByIndexAndList(index:Number, list:List):Void; 120 121 /** 122 * @overload #removeByValue 123 * @overload #removeByIndex 124 */ 125 public function remove(); 126 127 /** 128 * Removes {@code value} from this list if it exists and returns the index of the 129 * removed element. 130 * 131 * @param value the value to remove 132 * @return the index of the removed element or {@code -1} if it did not exist on 133 * this list 134 */ 135 public function removeByValue(value):Number; 136 137 /** 138 * Removes the value at given {@code index} from this list and returns it. 139 * 140 * @param index the index of the value to remove 141 * @return the removed value that was originally at given {@code index} 142 * @throws IndexOutOfBoundsException if given {@code index} is less than 0 or 143 * equal to or greater than this list's size 144 */ 145 public function removeByIndex(index:Number); 146 147 /** 148 * Removes the value at the beginning of this list. 149 * 150 * @return the removed value 151 */ 152 public function removeFirst(Void); 153 154 /** 155 * Removes the value at the end of this list. 156 * 157 * @return the removed value 158 */ 159 public function removeLast(Void); 160 161 /** 162 * Removes all values contained in {@code list}. 163 * 164 * @param list the values to remove 165 */ 166 public function removeAll(list:List):Void; 167 168 /** 169 * Sets {@code value} to given {@code index} on this list. The value that was 170 * originally at the given {@code index} will be overwritten. 171 * 172 * @param index the index of {@code value} 173 * @param value the {@code value} to set to given {@code index} 174 * @return the value that was orignially at given {@code index} 175 * @throws IndexOutOfBoundsException if given {@code index} is less than 0 or 176 * equal to or greater than this list's size 177 */ 178 public function set(index:Number, value); 179 180 /** 181 * Sets all values contained in {@code list} to this list, starting from given 182 * {@code index}. They values that were originally at the given {@code index} 183 * and following indices will be overwritten. 184 * 185 * <p>This method only overwrites existing index-value pairs. If an affected index 186 * is equal to or greater than this list's size, which would mean that this list's 187 * size had to be expanded, an {@code IndexOutOfBoundsException} will be thrown. In 188 * such a case use the {@link #insertAll} method instead, which expands this list 189 * dynamically. 190 * 191 * @param index the index to start at 192 * @param list the values to set 193 * @throws IndexOutOfBoundsException if given {@code index} is less than 0 or if 194 * any affected index, that is the given {@code index} plus the index of the 195 * specific value in the given {@code list}, is equal to or greater than this list's 196 * size 197 */ 198 public function setAll(index:Number, list:List):Void; 199 200 /** 201 * Returns the value at given {@code index}. 202 * 203 * @param index the index to return the value of 204 * @return the value that is at given {@code index} 205 * @throws IndexOutOfBoundsException if given {@code index} is less than 0 or 206 * equal to or greater than this list's size 207 */ 208 public function get(index:Number); 209 210 /** 211 * Checks whether {@code value} is contained in this list. 212 * 213 * @param value the value to check whether it is contained 214 * @return {@code true} if {@code value} is contained else {@code false} 215 */ 216 public function contains(value):Boolean; 217 218 /** 219 * Checks whether all values of {@code list} are contained in this list. 220 * 221 * @param list the values to check whether they are contained 222 * @return {@code true} if all values of {@code list} are contained else 223 * {@code false} 224 */ 225 public function containsAll(list:List):Boolean; 226 227 /** 228 * Retains all values the are contained in {@code list} and removes all others. 229 * 230 * @param list the list of values to retain 231 */ 232 public function retainAll(list:List):Void; 233 234 /** 235 * Returns a view of the portion of this list between the specified {@code fromIndex}, 236 * inclusive, and {@code toIndex}, exclusive. 237 * 238 * <p>If {@code fromIndex} and {@code toIndex} are equal an empty list is returned. 239 * 240 * <p>The returned list is backed by this list, so changes in the returned list are 241 * reflected in this list, and vice-versa. 242 * 243 * @param fromIndex the index from which the sub-list starts (inclusive) 244 * @param toIndex the index specifying the end of the sub-list (exclusive) 245 * @return a view of the specified range within this list 246 * @throws IndexOutOfBoundsException if argument {@code fromIndex} is less than 0 247 * @throws IndexOutOfBoundsException if argument {@code toIndex} is greater than 248 * the size of this list 249 * @throws IndexOutOfBoundsException if argument {@code fromIndex} is greater than 250 * {@code toIndex} 251 */ 252 public function subList(fromIndex:Number, toIndex:Number):List; 253 254 /** 255 * Removes all values from this list. 256 */ 257 public function clear(Void):Void; 258 259 /** 260 * Returns the number of added values. 261 * 262 * @return the number of added values 263 */ 264 public function size(Void):Number; 265 266 /** 267 * Returns whether this list is empty. 268 * 269 * <p>This list is empty if it has no values assigned to it. 270 * 271 * @return {@code true} if this list is empty else {@code false} 272 */ 273 public function isEmpty(Void):Boolean; 274 275 /** 276 * Returns the iterator to iterate over this list. 277 * 278 * @return the iterator to iterate over this list 279 */ 280 public function iterator(Void):Iterator; 281 282 /** 283 * Returns the index of {@code value}. 284 * 285 * @param value the value to return the index of 286 * @return the index of {@code value} 287 */ 288 public function indexOf(value):Number; 289 290 /** 291 * Returns the array representation of this list. 292 * 293 * @return the array representation of this list 294 */ 295 public function toArray(Void):Array; 296 297 }