Improve range-operation documentation for lists.

sdk/lib/core/list.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * An indexable collection of objects with a length.
  *
  * Subclasses of this class implement different kinds of lists.
@@ skipping 397 matching lines @@
    *
    * An error occurs if [start] is outside the range `0` .. `length` or if
    * [end] is outside the range `start` .. `length`.
    */
   List<E> sublist(int start, [int end]);
 
   /**
    * Returns an [Iterable] that iterates over the objects in the range
    * [start] inclusive to [end] exclusive.
    *
-   * An error occurs if [end] is before [start].
+   * The provide range, given by [start] and [end], must be valid at the time
+   * of the call.
    *
-   * An error occurs if the [start] and [end] are not valid ranges at the time
-   * of the call to this method. The returned [Iterable] behaves like
-   * `skip(start).take(end - start)`. That is, it does not throw exceptions
-   * if `this` changes size.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
+   *
+   * The returned [Iterable] behaves like `skip(start).take(end - start)`.
+   * That is, it does *not* throw exceptions if this list changes size.

[Lasse Reichstein Nielsen, 2017/01/17 15:56:59]

Drop "exceptions" (it's errors if it's anything).

[floitsch, 2017/01/18 12:54:18]

Done.

    *
    *     List<String> colors = ['red', 'green', 'blue', 'orange', 'pink'];
    *     Iterable<String> range = colors.getRange(1, 4);
    *     range.join(', ');  // 'green, blue, orange'
    *     colors.length = 3;
    *     range.join(', ');  // 'green, blue'
    */
   Iterable<E> getRange(int start, int end);
 
   /**
    * Copies the objects of [iterable], skipping [skipCount] objects first,
    * into the range [start], inclusive, to [end], exclusive, of the list.
    *
    *     List<int> list1 = [1, 2, 3, 4];
    *     List<int> list2 = [5, 6, 7, 8, 9];
    *     // Copies the 4th and 5th items in list2 as the 2nd and 3rd items
    *     // of list1.
    *     list1.setRange(1, 3, list2, 3);
    *     list1.join(', '); // '1, 8, 9, 4'
    *
-   * The [start] and [end] indices must satisfy `0 ≤ start ≤ end ≤ length`.
-   * If [start] equals [end], this method has no effect.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * The [iterable] must have enough objects to fill the range from `start`
    * to `end` after skipping [skipCount] objects.
    *
-   * If `iterable` is this list, the operation will copy the elements originally
-   * in the range from `skipCount` to `skipCount + (end - start)` to the
-   * range `start` to `end`, even if the two ranges overlap.
+   * If `iterable` is this list, the operation will copies the elements

[Lasse Reichstein Nielsen, 2017/01/17 15:56:58]

drop "will"

[floitsch, 2017/01/18 12:54:18]

Done.

+   * originally in the range from `skipCount` to `skipCount + (end - start)` to
+   * the range `start` to `end`, even if the two ranges overlap.
    *
    * If `iterable` depends on this list in some other way, no guarantees are
    * made.
    */
   void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]);
 
   /**
    * Removes the objects in the range [start] inclusive to [end] exclusive.
    *
-   * The [start] and [end] indices must be in the range
-   * `0 ≤ index ≤ length`, and `start ≤ end`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * Throws an [UnsupportedError] if this is a fixed-length list. In that case
    * the list is not modified.
    */
   void removeRange(int start, int end);
 
   /**
    * Sets the objects in the range [start] inclusive to [end] exclusive
    * to the given [fillValue].
    *
-   * An error occurs if [start]..[end] is not a valid range for `this`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    */
   void fillRange(int start, int end, [E fillValue]);
 
   /**
    * Removes the objects in the range [start] inclusive to [end] exclusive
    * and inserts the contents of [replacement] in its place.
    *
    *     List<int> list = [1, 2, 3, 4, 5];
    *     list.replaceRange(1, 4, [6, 7]);
    *     list.join(', '); // '1, 6, 7, 5'
    *
-   * An error occurs if [start]..[end] is not a valid range for `this`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * This method does not work on fixed-length lists, even when [replacement]
    * has the same number of elements as the replaced range. In that case use
    * [setRange] instead.
    */
   void replaceRange(int start, int end, Iterable<E> replacement);
 
   /**
    * Returns an unmodifiable [Map] view of `this`.
    *
    * The map uses the indices of this list as keys and the corresponding objects
    * as values. The `Map.keys` [Iterable] iterates the indices of this list
    * in numerical order.
    *
    *     List<String> words = ['fee', 'fi', 'fo', 'fum'];
    *     Map<int, String> map = words.asMap();
    *     map[0] + map[1];   // 'feefi';
    *     map.keys.toList(); // [0, 1, 2, 3]
    */
   Map<int, E> asMap();
 }