Added examples to map.dart

sdk/lib/core/map.dart

Index: sdk/lib/core/map.dart
diff --git a/sdk/lib/core/map.dart b/sdk/lib/core/map.dart
index fd3fd01560a67956f5ca7591dc2e2d318d6c01ea..3df0a0ed59c0657efa6f1a8104129fa029e4c574 100644
--- a/sdk/lib/core/map.dart
+++ b/sdk/lib/core/map.dart
@@ -28,12 +28,25 @@ abstract class Map<K, V> {
    * For each element of the [iterable] this constructor computes a key-value
    * pair, by applying [key] and [value] respectively.
    *
+   *     List<int> list = [1, 2, 3, 4];
+   *     // The map keys are the list elements converted to Strings.
+   *     // The map values are the squares of the list elements.
+   *     Map<String, int> newMap = new Map.fromIterable(list,
+   *         key: (item) => item.toString(),
+   *         value: (item) => item * item));
+   *
+   *     list.map((key) => newMap[key.toString()]).join(', '); // '1, 4, 9, 16'

[mem, 2013/09/06 16:42:22]

the last line of this code snippet makes this sample too complex. I just want to
see the results of the constructor in question (that is, I want to see the what
the map looks like with keys and values) and not have to figure out the
complexity of the final line

[shailentuli, 2013/09/23 11:49:46]

Agreed. Simplified.

+   *
+   *
    * The keys computed by the source [iterable]
    * do not need to be unique. The last
    * occurrence of a key will simply overwrite any previous value.
    *
    * If no values are specified for [key] and [value] the default is the
    * identity function.
+   *
+   *     newMap = new Map.fromIterable(list);
+   *     list.map((key) => newMap[key]).join(', '); // '1, 2, 3, 4'

[mem, 2013/09/06 16:42:22]

same as above.

[shailentuli, 2013/09/23 11:49:46]

Also simplified.

    */
   factory Map.fromIterable(Iterable iterable,
       {K key(element), V value(element)}) = LinkedHashMap<K, V>.fromIterable;
@@ -44,6 +57,11 @@ abstract class Map<K, V> {
    * This constructor iterates over [keys] and [values] and maps each element of
    * [keys] to the corresponding element of [values].
    *
+   *     List<String> letters = ['a', 'b', 'c'];
+   *     List<String> things = ['axe', 'ball', 'cat'];
+   *     Map<String, String> newMap = new Map.fromIterables(letters, things);
+   *     letters.map((letter) => newMap[letter]).join(', '); // 'axe, ball, cat'

[mem, 2013/09/06 16:42:22]

same as above.

[shailentuli, 2013/09/23 11:49:46]

Also simplified.

+   *
    * If [keys] contains the same object multiple times, the last occurrence
    * overwrites the previous value.
    *
@@ -80,6 +98,14 @@ abstract class Map<K, V> {
    * updates the map by mapping [key] to the value returned by
    * [ifAbsent]. Returns the value in the map.
    *
+   *     Map<String, int> scores = {'Bob': 36};
+   *     for (var key in ['Bob', 'Rohan', 'Jose']) {
+   *       scores.putIfAbsent(key, () => 0);
+   *     }
+   *     scores['Bob'];   // 36
+   *     scores['Rohan']; // 0
+   *     scores['Jose'];  // 0

[mem, 2013/09/06 16:42:22]

where's sophena?

Also, use a value that is not 0 to highlight that it's not just defaulting to 0.

[shailentuli, 2013/09/23 11:49:46]

She's there now. Done.

+   *
    * It is an error to add or remove keys from the map during the call to
    * [ifAbsent].

[mem, 2013/09/06 16:42:22]

An error occurs if you try to add or remove keys...

[shailentuli, 2013/09/23 11:49:46]

Done.

[shailentuli, 2013/09/23 11:49:46]

Done.

    */