Map#keys is alias of keySet and may be a view

Co-authored-by: Lukas Rytz <[email protected]>

Author: som-snytt

library/src/scala/collection/Map.scala

@@ -179,9 +179,16 @@ trait MapOps[K, +V, +CC[_, _] <: IterableOps[_, AnyConstr, _], +C]
 
   override /*PartialFunction*/ def applyOrElse[K1 <: K, V1 >: V](x: K1, default: K1 => V1): V1 = getOrElse(x, default(x))
 
-  /** Collects all keys of this map in a set.
-    * @return  a set containing all keys of this map.
-    */
+  /** A set representing the keys contained by this map.
+   *
+   *  For efficiency the resulting set may be a view (maintaining a reference to the map and reflecting modifications
+   *  to the map), but it may also be a strict collection without reference to the map.
+   *
+   *   - To ensure an independent strict collection, use `m.keysIterator.toSet`
+   *   - To obtain a view on the keys, use `scala.collection.View.fromIteratorProvider(m.keysIterator)`
+   *
+   *  @return a set representing the keys contained by this map
+   */
   def keySet: Set[K] = new KeySet
 
   /** The implementation class of the set returned by `keySet`.
@@ -199,25 +206,32 @@ trait MapOps[K, +V, +CC[_, _] <: IterableOps[_, AnyConstr, _], +C]
     override def isEmpty: Boolean = MapOps.this.isEmpty
   }
 
-  /** Collects all keys of this map in an iterable collection.
-    *
-    *  @return the keys of this map as an iterable.
-    */
+  /** An [[Iterable]] collection of the keys contained by this map.
+   *
+   *  For efficiency the resulting collection may be a view (maintaining a reference to the map and reflecting
+   *  modifications to the map), but it may also be a strict collection without reference to the map.
+   *
+   *   - To ensure an independent strict collection, use `m.keysIterator.toSet`
+   *   - To obtain a view on the keys, use `scala.collection.View.fromIteratorProvider(m.keysIterator)`
+   *
+   *  @return an [[Iterable]] collection of the keys contained by this map
+   */
+  @deprecatedOverriding("This method should be an alias for keySet", since="2.13.13")
   def keys: Iterable[K] = keySet
 
   /** Collects all values of this map in an iterable collection.
-    *
-    *  @return the values of this map as an iterable.
-    */
+   *
+   *  @return the values of this map as an iterable.
+   */
   def values: Iterable[V] = new AbstractIterable[V] with DefaultSerializable {
     override def knownSize: Int = MapOps.this.knownSize
     override def iterator: Iterator[V] = valuesIterator
   }
 
-  /** Creates an iterator for all keys.
-    *
-    *  @return an iterator over all keys.
-    */
+  /** An [[Iterator]] of the keys contained by this map.
+   *
+   *  @return an [[Iterator]] of the keys contained by this map
+   */
   def keysIterator: Iterator[K] = new AbstractIterator[K] {
     val iter = MapOps.this.iterator
     def hasNext = iter.hasNext

library/src/scala/collection/MapView.scala

@@ -27,6 +27,7 @@ trait MapView[K, +V]
    *
    *  @return the keys of this map as a view.
    */
+  @nowarn("msg=overriding method keys")
   override def keys: Iterable[K] = new MapView.Keys(this)
 
   // Ideally this returns a `View`, but bincompat

library/src/scala/collection/immutable/ListMap.scala

@@ -14,7 +14,7 @@ package scala
 package collection
 package immutable
 
-import scala.annotation.tailrec
+import scala.annotation.{nowarn, tailrec}
 import scala.collection.mutable.ReusableBuilder
 import scala.collection.generic.DefaultSerializable
 import scala.runtime.Statics.releaseFence
@@ -70,6 +70,7 @@ sealed class ListMap[K, +V]
     res.iterator
   }
 
+  @nowarn("msg=overriding method keys")
   override def keys: Iterable[K] = {
     var curr: ListMap[K, V] = this
     var res: List[K] = Nil

library/src/scala/collection/immutable/VectorMap.scala

@@ -14,7 +14,7 @@ package scala
 package collection
 package immutable
 
-import scala.annotation.tailrec
+import scala.annotation.{nowarn, tailrec}
 
 /** This class implements immutable maps using a vector/map-based data structure, which preserves insertion order.
   *
@@ -28,8 +28,9 @@ import scala.annotation.tailrec
   * @define Coll `immutable.VectorMap`
   */
 final class VectorMap[K, +V] private (
-    private[immutable] val fields: Vector[Any],
-    private[immutable] val underlying: Map[K, (Int, V)], dropped: Int)
+    private[immutable] val fields: Vector[Any], // K | Tombstone | Null
+    private[immutable] val underlying: Map[K, (Int, V)],
+    dropped: Int)
   extends AbstractMap[K, V]
     with SeqMap[K, V]
     with StrictOptimizedMapOps[K, V, VectorMap, VectorMap[K, V]]
@@ -39,9 +40,7 @@ final class VectorMap[K, +V] private (
 
   override protected[this] def className: String = "VectorMap"
 
-  private[immutable] def this(fields: Vector[K], underlying: Map[K, (Int, V)]) = {
-    this(fields, underlying, 0)
-  }
+  private[immutable] def this(fields: Vector[K], underlying: Map[K, (Int, V)]) = this(fields, underlying, 0)
 
   override val size = underlying.size
 
@@ -73,10 +72,8 @@ final class VectorMap[K, +V] private (
   private def nextValidField(slot: Int): (Int, K) = {
     if (slot >= fields.size) (-1, null.asInstanceOf[K])
     else fields(slot) match {
-      case Tombstone(distance) =>
-        nextValidField(slot + distance)
-      case k =>
-        (slot, k.asInstanceOf[K])
+      case Tombstone(distance) => nextValidField(slot + distance)
+      case k /*: K | Null */   => (slot, k.asInstanceOf[K])
     }
   }
 
@@ -106,12 +103,13 @@ final class VectorMap[K, +V] private (
 
     override def hasNext: Boolean = slot < fieldsLength
 
-    override def next(): (K, V) = {
-      if (!hasNext) throw new NoSuchElementException("next called on depleted iterator")
-      val result = (key, underlying(key)._2)
-      advance()
-      result
-    }
+    override def next(): (K, V) =
+      if (!hasNext) Iterator.empty.next()
+      else {
+        val result = (key, underlying(key)._2)
+        advance()
+        result
+      }
   }
 
   // No-Op overrides to allow for more efficient steppers in a minor release.
@@ -208,6 +206,11 @@ final class VectorMap[K, +V] private (
     new VectorMap(fields.dropRight(fields.size - slot), underlying - key, dropped)
   }
 
+  /** A [[Vector]] of the keys contained by this map.
+   *
+   *  @return  a [[Vector]] of the keys contained by this map.
+   */
+  @nowarn("msg=overriding method keys")
   override def keys: Vector[K] = keysIterator.toVector
 
   override def values: Iterable[V] = new Iterable[V] with IterableFactoryDefaults[V, Iterable] {
@@ -251,7 +254,7 @@ private[immutable] final class VectorMapBuilder[K, V] extends mutable.Builder[(K
 
   override def result(): VectorMap[K, V] = {
     if (aliased eq null) {
-        aliased = new VectorMap(vectorBuilder.result(), mapBuilder.result())
+      aliased = new VectorMap(vectorBuilder.result(), mapBuilder.result())
     }
     aliased
   }