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 171 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.
+   *
+   * Throws an [ArgumentError] if [index] is not an [int].

[srdjan, 2013/03/04 00:53:47]

That is not correct for checked mode.

[Lasse Reichstein Nielsen, 2013/03/04 09:06:02]

I really prefer to just say "It's an error if ..." and then throw whatever Error
I think fits.
You don't need to know the exact error, and add special code to avoid throwing a
different error.
In this case, requiring a special error in case for something that is already a
bad type is overspecifying. Ofcourse it's an error if the "int" argument is not
assignable to int. No need to say that. You can say that "index" must not be
null.

[floitsch, 2013/03/05 17:51:58]

The documentation had been copied from removeAt.
done.

+   * Throws an [RangeError] if the [index] does not point inside

[srdjan, 2013/03/04 00:53:47]

s/an/a/

+   * the list, or at the position after the last element.
+   * Throws an [UnsupportedError], and doesn't remove the element,

[Lasse Reichstein Nielsen, 2013/03/04 09:06:02]

No need to say that. That's what throwing an UnsupportedError means: I don't
support that operation. We already stated in the List documentation that
fixed-length lists don't support operations that changes the length.

+   * if the length of the list cannot be changed.
+   */
+  void insertAt(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 45 matching lines @@
    * not extendable.
    * If [length] is 0, this method does not do anything.
    * If [start] is the length of the list, this method inserts the
    * range at the end of the list.
    * Throws an [ArgumentError] if [length] is negative.
    * Throws an [RangeError] if [start] is negative or if
    * [start] is greater than the length of the list.
    */
   void insertRange(int start, int length, [E fill]);
 }