OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 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 | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * A [List] is an indexable collection with a length. It can be of | 6 * A [List] is an indexable collection with a length. It can be of |
7 * fixed size or extendable. | 7 * fixed size or extendable. |
8 */ | 8 */ |
9 interface List<E> extends Collection<E>, Sequence<E> | 9 interface List<E> extends Collection<E>, Sequence<E> |
10 default ListImplementation<E> { | 10 default ListImplementation<E> { |
(...skipping 22 matching lines...) Expand all Loading... |
33 | 33 |
34 /** | 34 /** |
35 * Sets the entry at the given [index] in the list to [value]. | 35 * Sets the entry at the given [index] in the list to [value]. |
36 * Throws an [IndexOutOfRangeException] if [index] is out of bounds. | 36 * Throws an [IndexOutOfRangeException] if [index] is out of bounds. |
37 */ | 37 */ |
38 void operator []=(int index, E value); | 38 void operator []=(int index, E value); |
39 | 39 |
40 /** | 40 /** |
41 * Changes the length of the list. If [newLength] is greater than | 41 * Changes the length of the list. If [newLength] is greater than |
42 * the current [length], entries are initialized to [:null:]. Throws | 42 * the current [length], entries are initialized to [:null:]. Throws |
43 * an [UnsupportedOperationException] if the list is not extendable. | 43 * an [UnsupportedError] if the list is not extendable. |
44 */ | 44 */ |
45 void set length(int newLength); | 45 void set length(int newLength); |
46 | 46 |
47 /** | 47 /** |
48 * Adds [value] at the end of the list, extending the length by | 48 * Adds [value] at the end of the list, extending the length by |
49 * one. Throws an [UnsupportedOperationException] if the list is not | 49 * one. Throws an [UnsupportedError] if the list is not |
50 * extendable. | 50 * extendable. |
51 */ | 51 */ |
52 void add(E value); | 52 void add(E value); |
53 | 53 |
54 /** | 54 /** |
55 * Adds [value] at the end of the list, extending the length by | 55 * Adds [value] at the end of the list, extending the length by |
56 * one. Throws an [UnsupportedOperationException] if the list is not | 56 * one. Throws an [UnsupportedError] if the list is not |
57 * extendable. | 57 * extendable. |
58 */ | 58 */ |
59 void addLast(E value); | 59 void addLast(E value); |
60 | 60 |
61 /** | 61 /** |
62 * Appends all elements of the [collection] to the end of this list. | 62 * Appends all elements of the [collection] to the end of this list. |
63 * Extends the length of the list by the number of elements in [collection]. | 63 * Extends the length of the list by the number of elements in [collection]. |
64 * Throws an [UnsupportedOperationException] if this list is not | 64 * Throws an [UnsupportedError] if this list is not |
65 * extendable. | 65 * extendable. |
66 */ | 66 */ |
67 void addAll(Collection<E> collection); | 67 void addAll(Collection<E> collection); |
68 | 68 |
69 /** | 69 /** |
70 * Sorts the list according to the order specified by the [Comparator]. | 70 * Sorts the list according to the order specified by the [Comparator]. |
71 */ | 71 */ |
72 void sort([Comparator<E> compare = Comparable.compare]); | 72 void sort([Comparator<E> compare = Comparable.compare]); |
73 | 73 |
74 /** | 74 /** |
(...skipping 14 matching lines...) Expand all Loading... |
89 * the index of [:e:] is returned. | 89 * the index of [:e:] is returned. |
90 * If start is not provided, it defaults to [:this.length - 1:] . | 90 * If start is not provided, it defaults to [:this.length - 1:] . |
91 * Returns -1 if [element] is not found. | 91 * Returns -1 if [element] is not found. |
92 */ | 92 */ |
93 int lastIndexOf(E element, [int start]); | 93 int lastIndexOf(E element, [int start]); |
94 | 94 |
95 /** | 95 /** |
96 * Removes all elements in the list. | 96 * Removes all elements in the list. |
97 * | 97 * |
98 * The length of the list becomes zero. | 98 * The length of the list becomes zero. |
99 * Throws an [UnsupportedOperationException], and retains all elements, if the | 99 * Throws an [UnsupportedError], and retains all elements, if the |
100 * length of the list cannot be changed. | 100 * length of the list cannot be changed. |
101 */ | 101 */ |
102 void clear(); | 102 void clear(); |
103 | 103 |
104 /** | 104 /** |
105 * Removes the element at position[index] from the list. | 105 * Removes the element at position[index] from the list. |
106 * | 106 * |
107 * This reduces the length of the list by one and moves all later elements | 107 * This reduces the length of the list by one and moves all later elements |
108 * down by one position. | 108 * down by one position. |
109 * Returns the removed element. | 109 * Returns the removed element. |
110 * Throws an [ArgumentError] if [index] is not an [int]. | 110 * Throws an [ArgumentError] if [index] is not an [int]. |
111 * Throws an [IndexOutOfRangeException] if the [index] does not point inside | 111 * Throws an [IndexOutOfRangeException] if the [index] does not point inside |
112 * the list. | 112 * the list. |
113 * Throws an [UnsupportedOperationException], and doesn't remove the element, | 113 * Throws an [UnsupportedError], and doesn't remove the element, |
114 * if the length of the list cannot be changed. | 114 * if the length of the list cannot be changed. |
115 */ | 115 */ |
116 E removeAt(int index); | 116 E removeAt(int index); |
117 | 117 |
118 /** | 118 /** |
119 * Pops and returns the last element of the list. | 119 * Pops and returns the last element of the list. |
120 * Throws a [UnsupportedOperationException] if the length of the | 120 * Throws a [UnsupportedError] if the length of the |
121 * list cannot be changed. | 121 * list cannot be changed. |
122 */ | 122 */ |
123 E removeLast(); | 123 E removeLast(); |
124 | 124 |
125 /** | 125 /** |
126 * Returns the last element of the list, or throws an out of bounds | 126 * Returns the last element of the list, or throws an out of bounds |
127 * exception if the list is empty. | 127 * exception if the list is empty. |
128 */ | 128 */ |
129 E last(); | 129 E last(); |
130 | 130 |
(...skipping 13 matching lines...) Expand all Loading... |
144 * If [length] is 0, this method does not do anything. | 144 * If [length] is 0, this method does not do anything. |
145 * Throws an [ArgumentError] if [length] is negative. | 145 * Throws an [ArgumentError] if [length] is negative. |
146 * Throws an [IndexOutOfRangeException] if [start] or | 146 * Throws an [IndexOutOfRangeException] if [start] or |
147 * [:start + length - 1:] are out of range for [:this:], or if | 147 * [:start + length - 1:] are out of range for [:this:], or if |
148 * [startFrom] or [:startFrom + length - 1:] are out of range for [from]. | 148 * [startFrom] or [:startFrom + length - 1:] are out of range for [from]. |
149 */ | 149 */ |
150 void setRange(int start, int length, List<E> from, [int startFrom]); | 150 void setRange(int start, int length, List<E> from, [int startFrom]); |
151 | 151 |
152 /** | 152 /** |
153 * Removes [length] elements from the list, beginning at [start]. | 153 * Removes [length] elements from the list, beginning at [start]. |
154 * Throws an [UnsupportedOperationException] if the list is | 154 * Throws an [UnsupportedError] if the list is |
155 * not extendable. | 155 * not extendable. |
156 * If [length] is 0, this method does not do anything. | 156 * If [length] is 0, this method does not do anything. |
157 * Throws an [ArgumentError] if [length] is negative. | 157 * Throws an [ArgumentError] if [length] is negative. |
158 * Throws an [IndexOutOfRangeException] if [start] or | 158 * Throws an [IndexOutOfRangeException] if [start] or |
159 * [:start + length: - 1] are out of range. | 159 * [:start + length: - 1] are out of range. |
160 */ | 160 */ |
161 void removeRange(int start, int length); | 161 void removeRange(int start, int length); |
162 | 162 |
163 /** | 163 /** |
164 * Inserts a new range into the list, starting from [start] to | 164 * Inserts a new range into the list, starting from [start] to |
165 * [:start + length - 1:]. The entries are filled with [initialValue]. | 165 * [:start + length - 1:]. The entries are filled with [initialValue]. |
166 * Throws an [UnsupportedOperationException] if the list is | 166 * Throws an [UnsupportedError] if the list is |
167 * not extendable. | 167 * not extendable. |
168 * If [length] is 0, this method does not do anything. | 168 * If [length] is 0, this method does not do anything. |
169 * If [start] is the length of the list, this method inserts the | 169 * If [start] is the length of the list, this method inserts the |
170 * range at the end of the list. | 170 * range at the end of the list. |
171 * Throws an [ArgumentError] if [length] is negative. | 171 * Throws an [ArgumentError] if [length] is negative. |
172 * Throws an [IndexOutOfRangeException] if [start] is negative or if | 172 * Throws an [IndexOutOfRangeException] if [start] is negative or if |
173 * [start] is greater than the length of the list. | 173 * [start] is greater than the length of the list. |
174 */ | 174 */ |
175 void insertRange(int start, int length, [E initialValue]); | 175 void insertRange(int start, int length, [E initialValue]); |
176 } | 176 } |
OLD | NEW |