diff options
-rw-r--r-- | src/library/scala/collection/mutable/BufferLike.scala | 23 | ||||
-rw-r--r-- | src/library/scala/collection/mutable/MapLike.scala | 43 | ||||
-rw-r--r-- | src/library/scala/collection/mutable/SetLike.scala | 45 |
3 files changed, 74 insertions, 37 deletions
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala index 9cbc6c0f05..a12ac1a1e6 100644 --- a/src/library/scala/collection/mutable/BufferLike.scala +++ b/src/library/scala/collection/mutable/BufferLike.scala @@ -268,10 +268,11 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]] repr } - /** Adds a number of elements provided by a traversable object and returns - * either the collection itself. + /** Creates a new collection containing both the elements of this collection and the provided + * traversable object. * * @param xs the traversable object. + * @return a new collection consisting of all the elements of this collection and `xs`. */ @migration(2, 8, "As of 2.8, ++ always creates a new collection, even on Buffers.\n"+ @@ -279,10 +280,10 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]] ) def ++(xs: TraversableOnce[A]): This = clone() ++= xs - /** Removes a single element from this collection and returns - * the collection itself. + /** Creates a new collection with all the elements of this collection except `elem`. * * @param elem the element to remove. + * @return a new collection consisting of all the elements of this collection except `elem`. */ @migration(2, 8, "As of 2.8, - always creates a new collection, even on Buffers.\n"+ @@ -290,12 +291,14 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]] ) override def -(elem: A): This = clone() -= elem - /** Removes two or more elements from this collection and returns - * the collection itself. + /** Creates a new collection with all the elements of this collection except the two + * or more specified elements. * * @param elem1 the first element to remove. * @param elem2 the second element to remove. * @param elems the remaining elements to remove. + * @return a new collection consisting of all the elements of this collection except + * `elem1`, `elem2` and those in `elems`. */ @migration(2, 8, "As of 2.8, - always creates a new collection, even on Buffers.\n"+ @@ -303,10 +306,12 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]] ) override def -(elem1: A, elem2: A, elems: A*): This = clone() -= elem1 -= elem2 --= elems - /** Removes a number of elements provided by a Traversable object and returns - * the collection itself. + /** Creates a new collection with all the elements of this collection except those + * provided by the specified traversable object. * - * @param iter the Traversable object. + * @param xs the traversable object. + * @return a new collection with all the elements of this collection except + * those in `xs` */ @migration(2, 8, "As of 2.8, -- always creates a new collection, even on Buffers.\n"+ diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala index 4c05cdd5c6..11677aca43 100644 --- a/src/library/scala/collection/mutable/MapLike.scala +++ b/src/library/scala/collection/mutable/MapLike.scala @@ -79,9 +79,13 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] */ override def updated[B1 >: B](key: A, value: B1): Map[A, B1] = this + ((key, value)) - /** Add a new key/value mapping and return the map itself. + /** Creates a new map containing a new key/value mapping and all the key/value mappings + * of this map. + * + * Mapping `kv` will override existing mappings from this map with the same key. * * @param kv the key/value mapping to be added + * @return a new map containing mappings of this map and the mapping `kv`. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To add an element as a\n"+ @@ -89,12 +93,15 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] ) def + [B1 >: B] (kv: (A, B1)): Map[A, B1] = clone().asInstanceOf[Map[A, B1]] += kv - /** Adds two or more key/value mappings and return the map itself. - * with the added elements. + /** Creates a new map containing two or more key/value mappings and all the key/value + * mappings of this map. + * + * Specified mappings will override existing mappings from this map with the same keys. * * @param elem1 the first element to add. * @param elem2 the second element to add. * @param elems the remaining elements to add. + * @return a new map containing mappings of this map and two or more specified mappings. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To add an element as a\n"+ @@ -103,12 +110,13 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): Map[A, B1] = clone().asInstanceOf[Map[A, B1]] += elem1 += elem2 ++= elems - /** Adds a number of elements provided by a traversable object - * via its `iterator` method and returns - * either the collection itself (if it is mutable), or a new collection - * with the added elements. + /** Creates a new map containing the key/value mappings provided by the specified traversable object + * and all the key/value mappings of this map. * - * @param iter the traversable object. + * Note that existing mappings from this map with the same key as those in `xs` will be overriden. + * + * @param xs the traversable object. + * @return a new map containing mappings of this map and those provided by `xs`. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To add the elements as a\n"+ @@ -135,8 +143,11 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] */ def -= (key: A): this.type - /** Delete a key from this map if it is present and return the map itself. + /** Creates a new map with all the key/value mappings of this map except the key/value mapping + * with the specified key. + * * @param key the key to be removed + * @return a new map with all the mappings of this map except that with a key `key`. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To remove an element as a\n"+ @@ -204,12 +215,14 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] */ def result: This = repr - /** Removes two or more elements from this collection and returns - * the collection itself. + /** Creates a new map with all the key/value mappings of this map except mappings with keys + * equal to any of the two or more specified keys. * * @param elem1 the first element to remove. * @param elem2 the second element to remove. * @param elems the remaining elements to remove. + * @return a new map containing all the mappings of this map except mappings + * with a key equal to `elem1`, `elem2` or any of `elems`. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To remove an element as a\n"+ @@ -218,10 +231,12 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]] override def -(elem1: A, elem2: A, elems: A*): This = clone() -= elem1 -= elem2 --= elems - /** Removes a number of elements provided by a Traversable object and returns - * the collection itself. + /** Creates a new map with all the key/value mappings of this map except mappings with keys + * equal to any of those provided by the specified traversable object. * - * @param iter the Traversable object. + * @param xs the traversable object. + * @return a new map with all the key/value mappings of this map except mappings + * with a key equal to a key from `xs`. */ @migration(2, 8, "As of 2.8, this operation creates a new map. To remove the elements as a\n"+ diff --git a/src/library/scala/collection/mutable/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala index 6f91997b83..78e82eb06b 100644 --- a/src/library/scala/collection/mutable/SetLike.scala +++ b/src/library/scala/collection/mutable/SetLike.scala @@ -46,6 +46,10 @@ import scala.annotation.migration * }}} * It is also good idea to override methods `foreach` and * `size` for efficiency. + * @define addDuplicates + * Note that duplicates (elements for which `equals` yields true) will be + * removed, but it is not specified whether it will be an element of this + * set or a newly added element. * @define coll mutable set * @define Coll mutable.Set */ @@ -131,10 +135,12 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] */ def result: This = repr - /** Adds a single element to this collection and returns - * the collection itself. + /** Creates a new set consisting of all the elements of this set and `elem`. + * + * $addDuplicates * * @param elem the element to add. + * @return a new set consisting of elements of this set and `elem`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To add an element as a\n"+ @@ -142,12 +148,16 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] ) override def + (elem: A): This = clone() += elem - /** Adds two or more elements to this collection and returns - * the collection itself. + /** Creates a new set consisting of all the elements of this set and two or more + * specified elements. + * + * $addDuplicates * * @param elem1 the first element to add. * @param elem2 the second element to add. * @param elems the remaining elements to add. + * @return a new set consisting of all the elements of this set, `elem1`, + * `elem2` and those in `elems`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To add the elements as a\n"+ @@ -156,10 +166,13 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] override def + (elem1: A, elem2: A, elems: A*): This = clone() += elem1 += elem2 ++= elems - /** Adds a number of elements provided by a traversable object and returns - * either the collection itself. + /** Creates a new set consisting of all the elements of this set and those + * provided by the specified traversable object. + * + * $addDuplicates * - * @param iter the iterable object. + * @param xs the traversable object. + * @return a new set cconsisting of elements of this set and those in `xs`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To add the elements as a\n"+ @@ -167,10 +180,10 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] ) override def ++(xs: TraversableOnce[A]): This = clone() ++= xs - /** Removes a single element from this collection and returns - * the collection itself. + /** Creates a new set consisting of all the elements of this set except `elem`. * * @param elem the element to remove. + * @return a new set consisting of all the elements of this set except `elem`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To remove the element as a\n"+ @@ -178,12 +191,14 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] ) override def -(elem: A): This = clone() -= elem - /** Removes two or more elements from this collection and returns - * the collection itself. + /** Creates a new set consisting of all the elements of this set except the two + * or more specified elements. * * @param elem1 the first element to remove. * @param elem2 the second element to remove. * @param elems the remaining elements to remove. + * @return a new set consisting of all the elements of this set except + * `elem1`, `elem2` and `elems`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To remove the elements as a\n"+ @@ -192,10 +207,12 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]] override def -(elem1: A, elem2: A, elems: A*): This = clone() -= elem1 -= elem2 --= elems - /** Removes a number of elements provided by a Traversable object and returns - * the collection itself. + /** Creates a new set consisting of all the elements of this set except those + * provided by the specified traversable object. * - * @param iter the Traversable object. + * @param xs the traversable object. + * @return a new set consisting of all the elements of this set except + * elements from `xs`. */ @migration(2, 8, "As of 2.8, this operation creates a new set. To remove the elements as a\n"+ |