Add List.insert.

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;
 
 /**
  * A [List] is an indexable collection with a length.
  *
  * A `List` implementation can be choose not to support all methods
@@ skipping 174 matching lines @@
   /**
    * Removes all elements in the list.
    *
    * The length of the list becomes zero.
    * Throws an [UnsupportedError], and retains all elements, if the
    * length of the list cannot be changed.
    */
   void clear();
 
   /**
-   * Removes the element at position[index] from the list.
+   * Inserts the element at position [index] in the list.
+   *
+   * This increases the length of the list by one and moves all later elements
+   * up by one position.

[srdjan, 2013/03/06 17:08:37]

'up' is an interesting direction. I always though of lists in terms of left and
right :-).

[Lasse Reichstein Nielsen, 2013/03/07 09:57:53]

I'd expect "moving up" to move towards the start.
I can see this is consistent with removeAt, which says "moves ... down by one
position". Not too happy about that either (even though I wrote it).

I'd prefer switching up/down, or switching to ... something else. "forward/back"
won't work, it's just as unobvious which direction is which. "away from the
start of the list"/"towards the start of the list"? Not great.
Shifts elements to the right/left? 

[floitsch, 2013/03/07 12:53:53]

Changed to "shifts all later elements towards the end of the list.

+   *
+   * It is an error if the [index] is `null`, or if the [index] does not point

[Lasse Reichstein Nielsen, 2013/03/07 09:57:53]

Skip the null part. That's included in "not pointing inside the list".

[floitsch, 2013/03/07 12:53:53]

Done.

+   * inside the list or at the position after the last element.
+   */
+  void insert(int index, E element);
+
+  /**
+   * Removes the element at position [index] from the list.
    *
    * This reduces the length of the list by one and moves all later elements
    * down by one position.
    * Returns the removed element.
    * Throws an [ArgumentError] if [index] is not an [int].
    * Throws an [RangeError] if the [index] does not point inside
    * the list.
    * Throws an [UnsupportedError], and doesn't remove the element,
    * if the length of the list cannot be changed.
    */
@@ skipping 53 matching lines @@
   void insertRange(int start, int length, [E fill]);
 
   /**
    * Returns an unmodifiable [Map] view of `this`.
    *
    * It has the indices of this list as keys, and the corresponding elements
    * as values.
    */
   Map<int, E> asMap();
 }