Add Map.unmodifiable constructor.

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 collection of key-value pairs, from which you retrieve a value
  * using its associated key.
  *
@@ skipping 27 matching lines @@
   factory Map() = LinkedHashMap<K, V>;
 
   /**
    * Creates a [LinkedHashMap] instance that contains all key-value pairs of
    * [other].
    *
    * The keys must all be assignable to [K] and the values to [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.
    * It iterates in key insertion order.
    */
   factory Map.identity() = LinkedHashMap<K, V>.identity;
 
   /**
    * Creates a Map instance in which the keys and values are computed from the
    * [iterable].
@@ skipping 181 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;
 }