Added examples to map.dart

sdk/lib/core/map.dart

 // Copyright (c) 2011, 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 unordered collection of key-value pairs,
  * from which you retrieve a value by using its associated key.
  *

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

Please show a code snippet here at the top...minimally creating a Map from a
literal.

  * Each key can occur at most once in a map.
  */
 abstract class Map<K, V> {
   /**
    * Creates a Map instance with the default implementation.
    */
   factory Map() = LinkedHashMap<K, V>;
 
   /**
    * Creates a Map instance that contains all key-value pairs of [other].
    */
   factory Map.from(Map<K, V> other) = LinkedHashMap<K, V>.from;
 
   /**
    * Creates a Map instance
    * where the keys and values are computed from the [iterable].

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

where -> in which

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

Done.

    *
    * 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;
 
   /**
    * Creates a Map instance associating the given [keys] to [values].
    *
    * 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.
    *
    * It is an error if the two [Iterable]s don't have the same length.
    */
   factory Map.fromIterables(Iterable<K> keys, Iterable<V> values)
       = LinkedHashMap<K, V>.fromIterables;
 
   /**
    * Returns true if this map contains the given value.
@@ skipping 12 matching lines @@
    * value, or use the [putIfAbsent] method.
    */
   V operator [](Object key);
 
   /**
    * Associates the [key] with the given [value].
    */
   void operator []=(K key, V value);
 
   /**
    * If [key] is not associated to a value, calls [ifAbsent] and

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

to -> with

    * 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.

    */
   V putIfAbsent(K key, V ifAbsent());
 
   /**
    * Adds all key-value pairs of [other] to this map.
    *
    * If a key of [other] is already in this map, its value is overwritten.
    *
    * The operation is equivalent to doing `this[key] = value` for each key
    * and associated value in other. It iterates over [other], which must
@@ skipping 39 matching lines @@
   /**
    * Returns true if there is no {key, value} pair in the map.
    */
   bool get isEmpty;
 
   /**
    * Returns true if there is at least one {key, value} pair in the map.
    */
   bool get isNotEmpty;
 }