Add Map.unmodifiable constructor.

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 c011a2044a5ade009120ebda2ec5379815b91210..962cfe74ee3b8e8fbed3b57bb6555e949c5d7431 100644
--- a/sdk/lib/core/map.dart
+++ b/sdk/lib/core/map.dart
@@ -45,12 +45,27 @@ abstract class Map<K, V> {
    * The [other] map itself can have any type.
    *
    * A `LinkedHashMap` requires the keys to implement compatible
-   * `operator==` and `hashCode`, and it allows null as a key.
+   * `operator==` and `hashCode`, and it allows `null` as a key.
    * It iterates in key insertion order.
    */
   factory Map.from(Map other) = LinkedHashMap<K, V>.from;
 
   /**
+   * Creates an unmodifiable hash based map containing the entries of [other].
+   *
+   * The keys must all be assignable to [K] and the values to [V].
+   * The [other] map itself can have any type.
+   *
+   * The map requires the keys to implement compatible
+   * `operator==` and `hashCode`, and it allows `null` as a key.
+   * The created map iterates keys in the same order as [other].

[Ivan Posva, 2015/05/11 18:16:54]

This is a strong statement to make. If other iterates in random order every time
we iterate, then it will be hard to preserve this behaviour. I strongly suggest
you just drop this line/requirement.

[Anders Johnsen, 2015/05/11 18:51:08]

From
https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:core.Ite...

"The iterators of the same iterable should provide the same values in the same
order (unless the underlying collection is modified between the iterations,
which some collections allow)."

[Lasse Reichstein Nielsen, 2015/05/13 11:18:59]

This can probably still be written a little better, just to be on the safe side.

The intend is that:
- the created map has a fixed iteration order.
- that iteration order matches an iteration order of the input map.
We only iterate the input map once, so if it changes iteration order, that's not
being tracked. It shouldn't change, but then, a lot of things shouldn't happen.

+   *
+   * The resulting map behaves like the result of [Map.from],
+   * except that the map returned by this constructor diallows modification.

[sra1, 2015/05/07 19:24:42]

disallows
or
does not allow
or
is not modifiable.

[Lasse Reichstein Nielsen, 2015/05/13 11:18:59]

Done.

+   */
+  external factory Map.unmodifiable(Map other);

[Søren Gjesse, 2015/05/05 01:51:12]

Is UnmodifiableMapView used that much that it warrants this instead of just
writing

var someMap = ...;
new UnmodifiableMapView<K, V>(new Map.from(someMap))

Another option could be a .from constructor on UnmodifiableMapView.

[Lasse Reichstein Nielsen, 2015/05/05 05:09:40]

This constructor, like List.unmodifable, is intended to support Fletch's deeply
immutable data structures.
It needs a way to create immutable maps as well.

+
+  /**
    * Creates an identity map with the default implementation, [LinkedHashMap].
    *
    * The returned map allows `null` as a key.