Switch Map.these to yield key-value pairs instead of just values

In chapel-lang#14718, it was proposed that iterating over a map should yield
key-value pairs as opposed to just values, so this PR implements
that change.

Signed-off-by: Ben McDonald <46734217+bmcdonald3@users.noreply.github.com>

modules/standard/Map.chpl

@@ -39,6 +39,14 @@ module Map {
   pragma "no doc"
   type _lockType = ChapelLocks.chpl_LocalSpinlock;
 
+  /* A compile-time parameter to control the behavior of map iteration
+     When ``false``, the deprecated behavior is used (i.e., iterating over
+     the map will yield references to values in the map).
+     When ``true``, the new behavior is used (i.e., iterating over the
+     map will yield (key, value) tuples in the map).
+  */
+  config param mapYieldTuple = false;
+
   pragma "no doc"
   class _LockWrapper {
     var lock$ = new _lockType();
@@ -528,11 +536,21 @@ module Map {
     }
 
     /*
-      Iterates over the keys of this map. This is a shortcut for :iter:`keys`.
+      Iterates over the key-value pairs of this map. This is a shortcut for :iter:`items`.
 
-      :yields: A reference to one of the keys contained in this map.
+      :yields: A tuple whose elements are a copy of one of the key-value
+               pairs contained in this map.
     */
-    iter these() const ref {
+    iter these()
+    where mapYieldTuple {
+      for kv in this.items() {
+        yield kv;
+      }
+    }
+
+    deprecated "yielding only keys when iterating over 'Map' is deprecated, please set the config param :param:`mapYieldTuple` to 'true' to opt into yielding tuple (key, value) pairs instead"
+    iter these() const ref
+    where !mapYieldTuple {
       for key in this.keys() {
         yield key;
       }