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 part of dart.collection; | 5 part of dart.collection; |
6 | 6 |
7 /** | 7 /** |
8 * This [Iterable] mixin implements all [Iterable] members except `iterator`. | 8 * This [Iterable] mixin implements all [Iterable] members except `iterator`. |
9 * | 9 * |
10 * All other methods are implemented in terms of `iterator`. | 10 * All other methods are implemented in terms of `iterator`. |
(...skipping 393 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
404 * [length] getter. | 404 * [length] getter. |
405 * | 405 * |
406 * An iterable implementing this interface should have an "efficient" | 406 * An iterable implementing this interface should have an "efficient" |
407 * implementation of `length` that doesn't trigger iteration of the | 407 * implementation of `length` that doesn't trigger iteration of the |
408 * iterable. Being efficient doesn't necessarily require being constant | 408 * iterable. Being efficient doesn't necessarily require being constant |
409 * time, but should at least attempt to have have execution time that is | 409 * time, but should at least attempt to have have execution time that is |
410 * better than linear in the elements of the iterable. | 410 * better than linear in the elements of the iterable. |
411 * | 411 * |
412 * Methods that worry about reading the length of an `Iterable` because it | 412 * Methods that worry about reading the length of an `Iterable` because it |
413 * may be inefficient or may trigger side-effects, or may even never complete, | 413 * may be inefficient or may trigger side-effects, or may even never complete, |
414 * can first check if the iterable `is EfficientLengthIterableIterable`, | 414 * can first check if the iterable `is EfficientLengthIterable`, |
415 * and if so, use [length] without those concerns. | 415 * and if so, use [length] without those concerns. |
416 * | 416 * |
417 * The `EfficientLengthIterable` type should never be used as an API type | 417 * The `EfficientLengthIterable` type should never be used as a type |
418 * assertion - neither as argument type or return type of a function. | 418 * assertion - neither as argument type or return type of a function. |
419 * Always use [Iterable] for the type and just document the performance if it | 419 * Always use [Iterable] for the type and just document the performance if it |
420 * is relevant. This avoids needlessly restricting the values that can be used. | 420 * is relevant. This avoids needlessly restricting the values that can be used. |
421 */ | 421 */ |
422 abstract class EfficientLengthIterable<T> implements Iterable<T> { | 422 abstract class EfficientLengthIterable<T> implements Iterable<T> { |
423 /** | 423 /** |
424 * Returns the number of elements in the iterable. | 424 * Returns the number of elements in the iterable. |
425 * | 425 * |
426 * This is an efficient operation that doesn't iterate through | 426 * This is an efficient operation that doesn't iterate through |
427 * the elements. | 427 * the elements. |
428 */ | 428 */ |
429 int get length; | 429 int get length; |
430 } | 430 } |
OLD | NEW |