OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 part of dart.core; | |
6 | |
7 /** | |
8 * An indexable collection of objects with a length. | |
9 * | |
10 * Subclasses of this class implement different kinds of lists. | |
11 * The most common kinds of lists are: | |
12 * | |
13 * * Fixed-length list. | |
14 * An error occurs when attempting to use operations | |
15 * that can change the length of the list. | |
16 * | |
17 * * Growable list. Full implementation of the API defined in this class. | |
18 * | |
19 * The default growable list, as returned by `new List()` or `[]`, keeps | |
20 * an internal buffer, and grows that buffer when necessary. This guarantees | |
21 * that a sequence of [add] operations will each execute in amortized constant | |
22 * time. Setting the length directly may take time proportional to the new | |
23 * length, and may change the internal capacity so that a following add | |
24 * operation will need to immediately increase the buffer capacity. | |
25 * Other list implementations may have different performance behavior. | |
26 * | |
27 * The following code illustrates that some List implementations support | |
28 * only a subset of the API. | |
29 * | |
30 * List<int> fixedLengthList = new List(5); | |
31 * fixedLengthList.length = 0; // Error | |
32 * fixedLengthList.add(499); // Error | |
33 * fixedLengthList[0] = 87; | |
34 * List<int> growableList = [1, 2]; | |
35 * growableList.length = 0; | |
36 * growableList.add(499); | |
37 * growableList[0] = 87; | |
38 * | |
39 * Lists are [Iterable]. Iteration occurs over values in index order. Changing | |
40 * the values does not affect iteration, but changing the valid | |
41 * indices—that is, changing the list's length—between iteration | |
42 * steps causes a [ConcurrentModificationError]. This means that only growable | |
43 * lists can throw ConcurrentModificationError. If the length changes | |
44 * temporarily and is restored before continuing the iteration, the iterator | |
45 * does not detect it. | |
46 * | |
47 * It is generally not allowed to modify the list's length (adding or removing | |
48 * elements) while an operation on the list is being performed, | |
49 * for example during a call to [forEach] or [sort]. | |
50 * Changing the list's length while it is being iterated, either by iterating it | |
51 * directly or through iterating an [Iterable] that is backed by the list, will | |
52 * break the iteration. | |
53 */ | |
54 abstract class List<E> implements Iterable<E>, EfficientLength { | |
55 /** | |
56 * Creates a list of the given length. | |
57 * | |
58 * The created list is fixed-length if [length] is provided. | |
59 * | |
60 * List fixedLengthList = new List(3); | |
61 * fixedLengthList.length; // 3 | |
62 * fixedLengthList.length = 1; // Error | |
63 * | |
64 * The list has length 0 and is growable if [length] is omitted. | |
65 * | |
66 * List growableList = new List(); | |
67 * growableList.length; // 0; | |
68 * growableList.length = 3; | |
69 * | |
70 * To create a growable list with a given length, just assign the length | |
71 * right after creation: | |
72 * | |
73 * List growableList = new List()..length = 500; | |
74 * | |
75 * The [length] must not be negative or null, if it is provided. | |
76 */ | |
77 external factory List([int length]); | |
78 | |
79 /** | |
80 * Creates a fixed-length list of the given length, and initializes the | |
81 * value at each position with [fill]: | |
82 * | |
83 * new List<int>.filled(3, 0); // [0, 0, 0] | |
84 * | |
85 * The [length] must be a non-negative integer. | |
86 * | |
87 * If the list is growable, changing its length will not initialize new | |
88 * entries with [fill]. After being created and filled, the list is | |
89 * no different from any other growable or fixed-length list | |
90 * created using [List]. | |
91 */ | |
92 external factory List.filled(int length, E fill, {bool growable: false}); | |
93 | |
94 /** | |
95 * Creates a list containing all [elements]. | |
96 * | |
97 * The [Iterator] of [elements] provides the order of the elements. | |
98 * | |
99 * This constructor returns a growable list when [growable] is true; | |
100 * otherwise, it returns a fixed-length list. | |
101 */ | |
102 external factory List.from(Iterable elements, { bool growable: true }); | |
103 | |
104 /** | |
105 * Generates a list of values. | |
106 * | |
107 * Creates a list with [length] positions and fills it with values created by | |
108 * calling [generator] for each index in the range `0` .. `length - 1` | |
109 * in increasing order. | |
110 * | |
111 * new List<int>.generate(3, (int index) => index * index); // [0, 1, 4] | |
112 * | |
113 * The created list is fixed-length unless [growable] is true. | |
114 */ | |
115 factory List.generate(int length, E generator(int index), | |
116 { bool growable: true }) { | |
117 List<E> result; | |
118 if (growable) { | |
119 result = <E>[]..length = length; | |
120 } else { | |
121 result = new List<E>(length); | |
122 } | |
123 for (int i = 0; i < length; i++) { | |
124 result[i] = generator(i); | |
125 } | |
126 return result; | |
127 } | |
128 | |
129 /** | |
130 * Creates an unmodifiable list containing all [elements]. | |
131 * | |
132 * The [Iterator] of [elements] provides the order of the elements. | |
133 * | |
134 * An unmodifiable list cannot have its length or elements changed. | |
135 * If the elements are themselves immutable, then the resulting list | |
136 * is also immutable. | |
137 */ | |
138 external factory List.unmodifiable(Iterable elements); | |
139 | |
140 /** | |
141 * Returns the object at the given [index] in the list | |
142 * or throws a [RangeError] if [index] is out of bounds. | |
143 */ | |
144 E operator [](int index); | |
145 | |
146 /** | |
147 * Sets the value at the given [index] in the list to [value] | |
148 * or throws a [RangeError] if [index] is out of bounds. | |
149 */ | |
150 void operator []=(int index, E value); | |
151 | |
152 /** | |
153 * Returns the number of objects in this list. | |
154 * | |
155 * The valid indices for a list are `0` through `length - 1`. | |
156 */ | |
157 int get length; | |
158 | |
159 /** | |
160 * Changes the length of this list. | |
161 * | |
162 * If [newLength] is greater than | |
163 * the current length, entries are initialized to [:null:]. | |
164 * | |
165 * Throws an [UnsupportedError] if the list is fixed-length. | |
166 */ | |
167 void set length(int newLength); | |
168 | |
169 /** | |
170 * Adds [value] to the end of this list, | |
171 * extending the length by one. | |
172 * | |
173 * Throws an [UnsupportedError] if the list is fixed-length. | |
174 */ | |
175 void add(E value); | |
176 | |
177 /** | |
178 * Appends all objects of [iterable] to the end of this list. | |
179 * | |
180 * Extends the length of the list by the number of objects in [iterable]. | |
181 * Throws an [UnsupportedError] if this list is fixed-length. | |
182 */ | |
183 void addAll(Iterable<E> iterable); | |
184 | |
185 /** | |
186 * Returns an [Iterable] of the objects in this list in reverse order. | |
187 */ | |
188 Iterable<E> get reversed; | |
189 | |
190 /** | |
191 * Sorts this list according to the order specified by the [compare] function. | |
192 * | |
193 * The [compare] function must act as a [Comparator]. | |
194 * | |
195 * List<String> numbers = ['two', 'three', 'four']; | |
196 * // Sort from shortest to longest. | |
197 * numbers.sort((a, b) => a.length.compareTo(b.length)); | |
198 * print(numbers); // [two, four, three] | |
199 * | |
200 * The default List implementations use [Comparable.compare] if | |
201 * [compare] is omitted. | |
202 * | |
203 * List<int> nums = [13, 2, -11]; | |
204 * nums.sort(); | |
205 * print(nums); // [-11, 2, 13] | |
206 * | |
207 * A [Comparator] may compare objects as equal (return zero), even if they | |
208 * are distinct objects. | |
209 * The sort function is not guaranteed to be stable, so distinct objects | |
210 * that compare as equal may occur in any order in the result: | |
211 * | |
212 * List<String> numbers = ['one', 'two', 'three', 'four']; | |
213 * numbers.sort((a, b) => a.length.compareTo(b.length)); | |
214 * print(numbers); // [one, two, four, three] OR [two, one, four, three] | |
215 */ | |
216 void sort([int compare(E a, E b)]); | |
217 | |
218 /** | |
219 * Shuffles the elements of this list randomly. | |
220 */ | |
221 void shuffle([Random random]); | |
222 | |
223 /** | |
224 * Returns the first index of [element] in this list. | |
225 * | |
226 * Searches the list from index [start] to the end of the list. | |
227 * The first time an object [:o:] is encountered so that [:o == element:], | |
228 * the index of [:o:] is returned. | |
229 * | |
230 * List<String> notes = ['do', 're', 'mi', 're']; | |
231 * notes.indexOf('re'); // 1 | |
232 * notes.indexOf('re', 2); // 3 | |
233 * | |
234 * Returns -1 if [element] is not found. | |
235 * | |
236 * notes.indexOf('fa'); // -1 | |
237 */ | |
238 int indexOf(E element, [int start = 0]); | |
239 | |
240 /** | |
241 * Returns the last index of [element] in this list. | |
242 * | |
243 * Searches the list backwards from index [start] to 0. | |
244 * | |
245 * The first time an object [:o:] is encountered so that [:o == element:], | |
246 * the index of [:o:] is returned. | |
247 * | |
248 * List<String> notes = ['do', 're', 'mi', 're']; | |
249 * notes.lastIndexOf('re', 2); // 1 | |
250 * | |
251 * If [start] is not provided, this method searches from the end of the | |
252 * list./Returns | |
253 * | |
254 * notes.lastIndexOf('re'); // 3 | |
255 * | |
256 * Returns -1 if [element] is not found. | |
257 * | |
258 * notes.lastIndexOf('fa'); // -1 | |
259 */ | |
260 int lastIndexOf(E element, [int start]); | |
261 | |
262 /** | |
263 * Removes all objects from this list; | |
264 * the length of the list becomes zero. | |
265 * | |
266 * Throws an [UnsupportedError], and retains all objects, if this | |
267 * is a fixed-length list. | |
268 */ | |
269 void clear(); | |
270 | |
271 /** | |
272 * Inserts the object at position [index] in this list. | |
273 * | |
274 * This increases the length of the list by one and shifts all objects | |
275 * at or after the index towards the end of the list. | |
276 * | |
277 * An error occurs if the [index] is less than 0 or greater than length. | |
278 * An [UnsupportedError] occurs if the list is fixed-length. | |
279 */ | |
280 void insert(int index, E element); | |
281 | |
282 /** | |
283 * Inserts all objects of [iterable] at position [index] in this list. | |
284 * | |
285 * This increases the length of the list by the length of [iterable] and | |
286 * shifts all later objects towards the end of the list. | |
287 * | |
288 * An error occurs if the [index] is less than 0 or greater than length. | |
289 * An [UnsupportedError] occurs if the list is fixed-length. | |
290 */ | |
291 void insertAll(int index, Iterable<E> iterable); | |
292 | |
293 /** | |
294 * Overwrites objects of `this` with the objects of [iterable], starting | |
295 * at position [index] in this list. | |
296 * | |
297 * List<String> list = ['a', 'b', 'c']; | |
298 * list.setAll(1, ['bee', 'sea']); | |
299 * list.join(', '); // 'a, bee, sea' | |
300 * | |
301 * This operation does not increase the length of `this`. | |
302 * | |
303 * The [index] must be non-negative and no greater than [length]. | |
304 * | |
305 * The [iterable] must not have more elements than what can fit from [index] | |
306 * to [length]. | |
307 * | |
308 * If `iterable` is based on this list, its values may change /during/ the | |
309 * `setAll` operation. | |
310 */ | |
311 void setAll(int index, Iterable<E> iterable); | |
312 | |
313 /** | |
314 * Removes the first occurence of [value] from this list. | |
315 * | |
316 * Returns true if [value] was in the list, false otherwise. | |
317 * | |
318 * List<String> parts = ['head', 'shoulders', 'knees', 'toes']; | |
319 * parts.remove('head'); // true | |
320 * parts.join(', '); // 'shoulders, knees, toes' | |
321 * | |
322 * The method has no effect if [value] was not in the list. | |
323 * | |
324 * // Note: 'head' has already been removed. | |
325 * parts.remove('head'); // false | |
326 * parts.join(', '); // 'shoulders, knees, toes' | |
327 * | |
328 * An [UnsupportedError] occurs if the list is fixed-length. | |
329 */ | |
330 bool remove(Object value); | |
331 | |
332 /** | |
333 * Removes the object at position [index] from this list. | |
334 * | |
335 * This method reduces the length of `this` by one and moves all later objects | |
336 * down by one position. | |
337 * | |
338 * Returns the removed object. | |
339 * | |
340 * The [index] must be in the range `0 ≤ index < length`. | |
341 * | |
342 * Throws an [UnsupportedError] if this is a fixed-length list. In that case | |
343 * the list is not modified. | |
344 */ | |
345 E removeAt(int index); | |
346 | |
347 /** | |
348 * Pops and returns the last object in this list. | |
349 * | |
350 * Throws an [UnsupportedError] if this is a fixed-length list. | |
351 */ | |
352 E removeLast(); | |
353 | |
354 /** | |
355 * Removes all objects from this list that satisfy [test]. | |
356 * | |
357 * An object [:o:] satisfies [test] if [:test(o):] is true. | |
358 * | |
359 * List<String> numbers = ['one', 'two', 'three', 'four']; | |
360 * numbers.removeWhere((item) => item.length == 3); | |
361 * numbers.join(', '); // 'three, four' | |
362 * | |
363 * Throws an [UnsupportedError] if this is a fixed-length list. | |
364 */ | |
365 void removeWhere(bool test(E element)); | |
366 | |
367 /** | |
368 * Removes all objects from this list that fail to satisfy [test]. | |
369 * | |
370 * An object [:o:] satisfies [test] if [:test(o):] is true. | |
371 * | |
372 * List<String> numbers = ['one', 'two', 'three', 'four']; | |
373 * numbers.retainWhere((item) => item.length == 3); | |
374 * numbers.join(', '); // 'one, two' | |
375 * | |
376 * Throws an [UnsupportedError] if this is a fixed-length list. | |
377 */ | |
378 void retainWhere(bool test(E element)); | |
379 | |
380 /** | |
381 * Returns a new list containing the objects from [start] inclusive to [end] | |
382 * exclusive. | |
383 * | |
384 * List<String> colors = ['red', 'green', 'blue', 'orange', 'pink']; | |
385 * colors.sublist(1, 3); // ['green', 'blue'] | |
386 * | |
387 * If [end] is omitted, the [length] of `this` is used. | |
388 * | |
389 * colors.sublist(1); // ['green', 'blue', 'orange', 'pink'] | |
390 * | |
391 * An error occurs if [start] is outside the range `0` .. `length` or if | |
392 * [end] is outside the range `start` .. `length`. | |
393 */ | |
394 List<E> sublist(int start, [int end]); | |
395 | |
396 /** | |
397 * Returns an [Iterable] that iterates over the objects in the range | |
398 * [start] inclusive to [end] exclusive. | |
399 * | |
400 * An error occurs if [end] is before [start]. | |
401 * | |
402 * An error occurs if the [start] and [end] are not valid ranges at the time | |
403 * of the call to this method. The returned [Iterable] behaves like | |
404 * `skip(start).take(end - start)`. That is, it does not throw exceptions | |
405 * if `this` changes size. | |
406 * | |
407 * List<String> colors = ['red', 'green', 'blue', 'orange', 'pink']; | |
408 * Iterable<String> range = colors.getRange(1, 4); | |
409 * range.join(', '); // 'green, blue, orange' | |
410 * colors.length = 3; | |
411 * range.join(', '); // 'green, blue' | |
412 */ | |
413 Iterable<E> getRange(int start, int end); | |
414 | |
415 /** | |
416 * Copies the objects of [iterable], skipping [skipCount] objects first, | |
417 * into the range [start], inclusive, to [end], exclusive, of the list. | |
418 * | |
419 * List<int> list1 = [1, 2, 3, 4]; | |
420 * List<int> list2 = [5, 6, 7, 8, 9]; | |
421 * // Copies the 4th and 5th items in list2 as the 2nd and 3rd items | |
422 * // of list1. | |
423 * list1.setRange(1, 3, list2, 3); | |
424 * list1.join(', '); // '1, 8, 9, 4' | |
425 * | |
426 * The [start] and [end] indices must satisfy `0 ≤ start ≤ end ≤ length`. | |
427 * If [start] equals [end], this method has no effect. | |
428 * | |
429 * The [iterable] must have enough objects to fill the range from `start` | |
430 * to `end` after skipping [skipCount] objects. | |
431 * | |
432 * If `iterable` is this list, the operation will copy the elements originally | |
433 * in the range from `skipCount` to `skipCount + (end - start)` to the | |
434 * range `start` to `end`, even if the two ranges overlap. | |
435 * | |
436 * If `iterable` depends on this list in some other way, no guarantees are | |
437 * made. | |
438 */ | |
439 void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]); | |
440 | |
441 /** | |
442 * Removes the objects in the range [start] inclusive to [end] exclusive. | |
443 * | |
444 * The [start] and [end] indices must be in the range | |
445 * `0 ≤ index ≤ length`, and `start ≤ end`. | |
446 * | |
447 * Throws an [UnsupportedError] if this is a fixed-length list. In that case | |
448 * the list is not modified. | |
449 */ | |
450 void removeRange(int start, int end); | |
451 | |
452 /** | |
453 * Sets the objects in the range [start] inclusive to [end] exclusive | |
454 * to the given [fillValue]. | |
455 * | |
456 * An error occurs if [start]..[end] is not a valid range for `this`. | |
457 */ | |
458 void fillRange(int start, int end, [E fillValue]); | |
459 | |
460 /** | |
461 * Removes the objects in the range [start] inclusive to [end] exclusive | |
462 * and inserts the contents of [replacement] in its place. | |
463 * | |
464 * List<int> list = [1, 2, 3, 4, 5]; | |
465 * list.replaceRange(1, 4, [6, 7]); | |
466 * list.join(', '); // '1, 6, 7, 5' | |
467 * | |
468 * An error occurs if [start]..[end] is not a valid range for `this`. | |
469 * | |
470 * This method does not work on fixed-length lists, even when [replacement] | |
471 * has the same number of elements as the replaced range. In that case use | |
472 * [setRange] instead. | |
473 */ | |
474 void replaceRange(int start, int end, Iterable<E> replacement); | |
475 | |
476 /** | |
477 * Returns an unmodifiable [Map] view of `this`. | |
478 * | |
479 * The map uses the indices of this list as keys and the corresponding objects | |
480 * as values. The `Map.keys` [Iterable] iterates the indices of this list | |
481 * in numerical order. | |
482 * | |
483 * List<String> words = ['fee', 'fi', 'fo', 'fum']; | |
484 * Map<int, String> map = words.asMap(); | |
485 * map[0] + map[1]; // 'feefi'; | |
486 * map.keys.toList(); // [0, 1, 2, 3] | |
487 */ | |
488 Map<int, E> asMap(); | |
489 } | |
OLD | NEW |