Add List.insert.

sdk/lib/core/list.dart

Index: sdk/lib/core/list.dart
diff --git a/sdk/lib/core/list.dart b/sdk/lib/core/list.dart
index 560f08fe0766941312f5522f11ed53d6a4e1e570..4a4b1c08e659d8742a5eb75f194f2926f04e1260 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -192,7 +192,18 @@ abstract class List<E> implements Collection<E> {
   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.