From 3bf207b9a2d26d340ef96f9aa853157f2ca42714 Mon Sep 17 00:00:00 2001 From: Lukas Rytz Date: Wed, 20 Apr 2016 22:29:28 +0200 Subject: Cleaned up Scaladoc for JavaConverters and non-deprecated friends --- src/library/scala/collection/JavaConversions.scala | 2 +- .../collection/convert/AsJavaConverters.scala | 230 +++++++-------- .../collection/convert/AsScalaConverters.scala | 162 +++++----- .../scala/collection/convert/DecorateAsJava.scala | 247 ++-------------- .../scala/collection/convert/DecorateAsScala.scala | 152 ++-------- .../collection/convert/ImplicitConversions.scala | 328 ++------------------- .../scala/collection/convert/Wrappers.scala | 12 +- 7 files changed, 261 insertions(+), 872 deletions(-) diff --git a/src/library/scala/collection/JavaConversions.scala b/src/library/scala/collection/JavaConversions.scala index f6c7dfe420..960e452cdf 100644 --- a/src/library/scala/collection/JavaConversions.scala +++ b/src/library/scala/collection/JavaConversions.scala @@ -11,7 +11,7 @@ package collection import convert._ -/** A collection of implicit conversions supporting interoperability between +/** A variety of implicit conversions supporting interoperability between * Scala and Java collections. * * The following conversions are supported: diff --git a/src/library/scala/collection/convert/AsJavaConverters.scala b/src/library/scala/collection/convert/AsJavaConverters.scala index 0fd98273ec..c7c1fb9c74 100644 --- a/src/library/scala/collection/convert/AsJavaConverters.scala +++ b/src/library/scala/collection/convert/AsJavaConverters.scala @@ -1,6 +1,6 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** -** / __/ __// _ | / / / _ | (c) 2006-2013, LAMP/EPFL ** +** / __/ __// _ | / / / _ | (c) 2006-2016, LAMP/EPFL ** ** __\ \/ /__/ __ |/ /__/ __ | http://www.scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** @@ -17,58 +17,55 @@ trait AsJavaConverters { import Wrappers._ /** - * Converts a Scala Iterator to a Java Iterator. + * Converts a Scala `Iterator` to a Java `Iterator`. * - * The returned Java Iterator is backed by the provided Scala - * Iterator and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Iterator` is backed by the provided Scala `Iterator` and any side-effects of + * using it via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Iterator was previously obtained from an implicit or - * explicit call of `asScalaIterator(java.util.Iterator)` then the original - * Java Iterator will be returned. + * If the Scala `Iterator` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaIterator]](java.util.Iterator)` then the original Java `Iterator` will + * be returned. * - * @param it The Iterator to be converted. - * @return A Java Iterator view of the argument. + * @param i The Scala `Iterator` to be converted. + * @return A Java `Iterator` view of the argument. */ - def asJavaIterator[A](it: Iterator[A]): ju.Iterator[A] = it match { + def asJavaIterator[A](i: Iterator[A]): ju.Iterator[A] = i match { case null => null case JIteratorWrapper(wrapped) => wrapped.asInstanceOf[ju.Iterator[A]] - case _ => IteratorWrapper(it) + case _ => IteratorWrapper(i) } /** - * Converts a Scala Iterator to a Java Enumeration. + * Converts a Scala `Iterator` to a Java `Enumeration`. * - * The returned Java Enumeration is backed by the provided Scala - * Iterator and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Enumeration` is backed by the provided Scala `Iterator` and any side-effects + * of using it via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Iterator was previously obtained from an implicit or - * explicit call of `enumerationAsScalaIterator(java.util.Enumeration)` then the - * original Java Enumeration will be returned. + * If the Scala `Iterator` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.enumerationAsScalaIterator]](java.util.Enumeration)` then the original Java + * `Enumeration` will be returned. * - * @param it The Iterator to be converted. - * @return A Java Enumeration view of the argument. + * @param i The Scala `Iterator` to be converted. + * @return A Java `Enumeration` view of the argument. */ - def asJavaEnumeration[A](it: Iterator[A]): ju.Enumeration[A] = it match { + def asJavaEnumeration[A](i: Iterator[A]): ju.Enumeration[A] = i match { case null => null case JEnumerationWrapper(wrapped) => wrapped.asInstanceOf[ju.Enumeration[A]] - case _ => IteratorWrapper(it) + case _ => IteratorWrapper(i) } /** - * Converts a Scala Iterable to a Java Iterable. + * Converts a Scala `Iterable` to a Java `Iterable`. * - * The returned Java Iterable is backed by the provided Scala - * Iterable and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Iterable` is backed by the provided Scala `Iterable` and any side-effects of + * using it via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Iterable was previously obtained from an implicit or - * explicit call of `iterableasScalaIterable(java.lang.Iterable)` then the original - * Java Iterable will be returned. + * If the Scala `Iterable` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.iterableAsScalaIterable]](java.lang.Iterable)` then the original Java + * `Iterable` will be returned. * - * @param i The Iterable to be converted. - * @return A Java Iterable view of the argument. + * @param i The Scala `Iterable` to be converted. + * @return A Java `Iterable` view of the argument. */ def asJavaIterable[A](i: Iterable[A]): jl.Iterable[A] = i match { case null => null @@ -77,34 +74,33 @@ trait AsJavaConverters { } /** - * Converts a Scala Iterable to an immutable Java Collection. + * Converts a Scala `Iterable` to an immutable Java `Collection`. * - * If the Scala Iterable was previously obtained from an implicit or - * explicit call of `collectionAsScalaIterable(java.util.Collection)` then the original - * Java Collection will be returned. + * If the Scala `Iterable` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.collectionAsScalaIterable]](java.util.Collection)` then the original Java + * `Collection` will be returned. * - * @param it The SizedIterable to be converted. - * @return A Java Collection view of the argument. + * @param i The Scala `Iterable` to be converted. + * @return A Java `Collection` view of the argument. */ - def asJavaCollection[A](it: Iterable[A]): ju.Collection[A] = it match { + def asJavaCollection[A](i: Iterable[A]): ju.Collection[A] = i match { case null => null case JCollectionWrapper(wrapped) => wrapped.asInstanceOf[ju.Collection[A]] - case _ => new IterableWrapper(it) + case _ => new IterableWrapper(i) } /** - * Converts a Scala mutable Buffer to a Java List. + * Converts a Scala mutable `Buffer` to a Java List. * - * The returned Java List is backed by the provided Scala - * Buffer and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java List is backed by the provided Scala `Buffer` and any side-effects of using + * it via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Buffer was previously obtained from an implicit or - * explicit call of `asScalaBuffer(java.util.List)` then the original - * Java List will be returned. + * If the Scala `Buffer` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaBuffer]](java.util.List)` then the original Java `List` will be + * returned. * - * @param b The Buffer to be converted. - * @return A Java List view of the argument. + * @param b The Scala `Buffer` to be converted. + * @return A Java `List` view of the argument. */ def bufferAsJavaList[A](b: mutable.Buffer[A]): ju.List[A] = b match { case null => null @@ -113,58 +109,54 @@ trait AsJavaConverters { } /** - * Converts a Scala mutable Seq to a Java List. + * Converts a Scala mutable `Seq` to a Java `List`. * - * The returned Java List is backed by the provided Scala - * Seq and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `List` is backed by the provided Scala `Seq` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Seq was previously obtained from an implicit or - * explicit call of `asScalaBuffer(java.util.List)` then the original - * Java List will be returned. + * If the Scala `Seq` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaBuffer]](java.util.List)` then the original Java `List` will be + * returned. * - * @param seq The Seq to be converted. - * @return A Java List view of the argument. + * @param s The Scala `Seq` to be converted. + * @return A Java `List` view of the argument. */ - def mutableSeqAsJavaList[A](seq: mutable.Seq[A]): ju.List[A] = seq match { + def mutableSeqAsJavaList[A](s: mutable.Seq[A]): ju.List[A] = s match { case null => null case JListWrapper(wrapped) => wrapped - case _ => new MutableSeqWrapper(seq) + case _ => new MutableSeqWrapper(s) } /** - * Converts a Scala Seq to a Java List. + * Converts a Scala `Seq` to a Java `List`. * - * The returned Java List is backed by the provided Scala - * Seq and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `List` is backed by the provided Scala `Seq` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Seq was previously obtained from an implicit or - * explicit call of `asScalaBuffer(java.util.List)` then the original - * Java List will be returned. + * If the Scala `Seq` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaBuffer]](java.util.List)` then the original Java `List` will be + * returned. * - * @param seq The Seq to be converted. - * @return A Java List view of the argument. + * @param s The Scala `Seq` to be converted. + * @return A Java `List` view of the argument. */ - def seqAsJavaList[A](seq: Seq[A]): ju.List[A] = seq match { + def seqAsJavaList[A](s: Seq[A]): ju.List[A] = s match { case null => null case JListWrapper(wrapped) => wrapped.asInstanceOf[ju.List[A]] - case _ => new SeqWrapper(seq) + case _ => new SeqWrapper(s) } /** - * Converts a Scala mutable Set to a Java Set. + * Converts a Scala mutable `Set` to a Java `Set`. * - * The returned Java Set is backed by the provided Scala - * Set and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Set` is backed by the provided Scala `Set` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Set was previously obtained from an implicit or - * explicit call of `asSet(java.util.Set)` then the original - * Java Set will be returned. + * If the Scala `Set` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaSet]](java.util.Set)` then the original Java `Set` will be returned. * - * @param s The Set to be converted. - * @return A Java Set view of the argument. + * @param s The Scala mutable `Set` to be converted. + * @return A Java `Set` view of the argument. */ def mutableSetAsJavaSet[A](s: mutable.Set[A]): ju.Set[A] = s match { case null => null @@ -173,18 +165,16 @@ trait AsJavaConverters { } /** - * Converts a Scala Set to a Java Set. + * Converts a Scala `Set` to a Java `Set`. * - * The returned Java Set is backed by the provided Scala - * Set and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Set` is backed by the provided Scala `Set` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Set was previously obtained from an implicit or - * explicit call of `asScalaSet(java.util.Set)` then the original - * Java Set will be returned. + * If the Scala `Set` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asScalaSet]](java.util.Set)` then the original Java `Set` will be returned. * - * @param s The Set to be converted. - * @return A Java Set view of the argument. + * @param s The Scala `Set` to be converted. + * @return A Java `Set` view of the argument. */ def setAsJavaSet[A](s: Set[A]): ju.Set[A] = s match { case null => null @@ -193,18 +183,17 @@ trait AsJavaConverters { } /** - * Converts a Scala mutable Map to a Java Map. + * Converts a Scala mutable `Map` to a Java `Map`. * - * The returned Java Map is backed by the provided Scala - * Map and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * The returned Java `Map` is backed by the provided Scala `Map` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala Map was previously obtained from an implicit or - * explicit call of `mapAsScalaMap(java.util.Map)` then the original - * Java Map will be returned. + * If the Scala `Map` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mapAsScalaMap]](java.util.Map)` then the original Java `Map` will be + * returned. * - * @param m The Map to be converted. - * @return A Java Map view of the argument. + * @param m The Scala mutable `Map` to be converted. + * @return A Java `Map` view of the argument. */ def mutableMapAsJavaMap[A, B](m: mutable.Map[A, B]): ju.Map[A, B] = m match { case null => null @@ -215,16 +204,16 @@ trait AsJavaConverters { /** * Converts a Scala mutable `Map` to a Java `Dictionary`. * - * The returned Java `Dictionary` is backed by the provided Scala - * `Dictionary` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. + * The returned Java `Dictionary` is backed by the provided Scala `Dictionary` and any + * side-effects of using it via the Java interface will be visible via the Scala interface and + * vice versa. * - * If the Scala `Dictionary` was previously obtained from an implicit or - * explicit call of `dictionaryAsScalaMap(java.util.Dictionary)` then the original - * Java Dictionary will be returned. + * If the Scala `Dictionary` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.dictionaryAsScalaMap]](java.util.Dictionary)` then the original Java + * `Dictionary` will be returned. * - * @param m The `Map` to be converted. - * @return A Java `Dictionary` view of the argument. + * @param m The Scala `Map` to be converted. + * @return A Java `Dictionary` view of the argument. */ def asJavaDictionary[A, B](m: mutable.Map[A, B]): ju.Dictionary[A, B] = m match { case null => null @@ -235,16 +224,15 @@ trait AsJavaConverters { /** * Converts a Scala `Map` to a Java `Map`. * - * The returned Java `Map` is backed by the provided Scala `Map` and - * any side-effects of using it via the Java interface will be visible - * via the Scala interface and vice versa. + * The returned Java `Map` is backed by the provided Scala `Map` and any side-effects of using it + * via the Java interface will be visible via the Scala interface and vice versa. * - * If the Scala `Map` was previously obtained from an implicit or - * explicit call of `mapAsScalaMap(java.util.Map)` then the original - * Java `Map` will be returned. + * If the Scala `Map` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mapAsScalaMap]](java.util.Map)` then the original Java `Map` will be + * returned. * - * @param m The `Map` to be converted. - * @return A Java `Map` view of the argument. + * @param m The Scala `Map` to be converted. + * @return A Java `Map` view of the argument. */ def mapAsJavaMap[A, B](m: Map[A, B]): ju.Map[A, B] = m match { case null => null @@ -255,16 +243,16 @@ trait AsJavaConverters { /** * Converts a Scala mutable `concurrent.Map` to a Java `ConcurrentMap`. * - * The returned Java `ConcurrentMap` is backed by the provided Scala - * `concurrent.Map` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. + * The returned Java `ConcurrentMap` is backed by the provided Scala `concurrent.Map` and any + * side-effects of using it via the Java interface will be visible via the Scala interface and + * vice versa. * - * If the Scala `concurrent.Map` was previously obtained from an implicit or - * explicit call of `mapAsScalaConcurrentMap(java.util.concurrent.ConcurrentMap)` - * then the original Java ConcurrentMap will be returned. + * If the Scala `concurrent.Map` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mapAsScalaConcurrentMap]](java.util.concurrent.ConcurrentMap)` then the + * original Java `ConcurrentMap` will be returned. * * @param m The Scala `concurrent.Map` to be converted. - * @return A Java `ConcurrentMap` view of the argument. + * @return A Java `ConcurrentMap` view of the argument. */ def mapAsJavaConcurrentMap[A, B](m: concurrent.Map[A, B]): juc.ConcurrentMap[A, B] = m match { case null => null diff --git a/src/library/scala/collection/convert/AsScalaConverters.scala b/src/library/scala/collection/convert/AsScalaConverters.scala index 413292fbfc..f9e38797e1 100644 --- a/src/library/scala/collection/convert/AsScalaConverters.scala +++ b/src/library/scala/collection/convert/AsScalaConverters.scala @@ -1,6 +1,6 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** -** / __/ __// _ | / / / _ | (c) 2006-2013, LAMP/EPFL ** +** / __/ __// _ | / / / _ | (c) 2006-2016, LAMP/EPFL ** ** __\ \/ /__/ __ |/ /__/ __ | http://www.scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** @@ -19,36 +19,34 @@ trait AsScalaConverters { /** * Converts a Java `Iterator` to a Scala `Iterator`. * - * The returned Scala `Iterator` is backed by the provided Java `Iterator` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. + * The returned Scala `Iterator` is backed by the provided Java `Iterator` and any side-effects of + * using it via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java `Iterator` was previously obtained from an implicit or - * explicit call of `asJavaIterator(scala.collection.Iterator)` then the - * original Scala `Iterator` will be returned. + * If the Java `Iterator` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asJavaIterator]](scala.collection.Iterator)` then the original Scala + * `Iterator` will be returned. * - * @param it The `Iterator` to be converted. - * @return A Scala `Iterator` view of the argument. + * @param i The Java `Iterator` to be converted. + * @return A Scala `Iterator` view of the argument. */ - def asScalaIterator[A](it: ju.Iterator[A]): Iterator[A] = it match { + def asScalaIterator[A](i: ju.Iterator[A]): Iterator[A] = i match { case null => null case IteratorWrapper(wrapped) => wrapped - case _ => JIteratorWrapper(it) + case _ => JIteratorWrapper(i) } /** - * Converts a Java Enumeration to a Scala Iterator. + * Converts a Java `Enumeration` to a Scala `Iterator`. * - * The returned Scala Iterator is backed by the provided Java - * Enumeration and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * The returned Scala `Iterator` is backed by the provided Java `Enumeration` and any side-effects + * of using it via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java Enumeration was previously obtained from an implicit or - * explicit call of `asJavaEnumeration(scala.collection.Iterator)` - * then the original Scala Iterator will be returned. + * If the Java `Enumeration` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asJavaEnumeration]](scala.collection.Iterator)` then the original Scala + * `Iterator` will be returned. * - * @param i The Enumeration to be converted. - * @return A Scala Iterator view of the argument. + * @param i The Java `Enumeration` to be converted. + * @return A Scala `Iterator` view of the argument. */ def enumerationAsScalaIterator[A](i: ju.Enumeration[A]): Iterator[A] = i match { case null => null @@ -59,16 +57,15 @@ trait AsScalaConverters { /** * Converts a Java `Iterable` to a Scala `Iterable`. * - * The returned Scala `Iterable` is backed by the provided Java `Iterable` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. + * The returned Scala `Iterable` is backed by the provided Java `Iterable` and any side-effects of + * using it via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java `Iterable` was previously obtained from an implicit or - * explicit call of `asJavaIterable(scala.collection.Iterable)` - * then the original Scala Iterable will be returned. + * If the Java `Iterable` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asJavaIterable]](scala.collection.Iterable) then the original Scala + * `Iterable` will be returned. * - * @param i The Iterable to be converted. - * @return A Scala Iterable view of the argument. + * @param i The Java `Iterable` to be converted. + * @return A Scala `Iterable` view of the argument. */ def iterableAsScalaIterable[A](i: jl.Iterable[A]): Iterable[A] = i match { case null => null @@ -79,12 +76,12 @@ trait AsScalaConverters { /** * Converts a Java `Collection` to an Scala `Iterable`. * - * If the Java `Collection` was previously obtained from an implicit or - * explicit call of `asJavaCollection(scala.collection.Iterable)` - * then the original Scala `Iterable` will be returned. + * If the Java `Collection` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asJavaCollection]](scala.collection.Iterable)` then the original Scala + * `Iterable` will be returned. * - * @param i The Collection to be converted. - * @return A Scala Iterable view of the argument. + * @param i The Java `Collection` to be converted. + * @return A Scala `Iterable` view of the argument. */ def collectionAsScalaIterable[A](i: ju.Collection[A]): Iterable[A] = i match { case null => null @@ -95,15 +92,14 @@ trait AsScalaConverters { /** * Converts a Java `List` to a Scala mutable `Buffer`. * - * The returned Scala `Buffer` is backed by the provided Java `List` - * and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * The returned Scala `Buffer` is backed by the provided Java `List` and any side-effects of using + * it via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java `List` was previously obtained from an implicit or - * explicit call of `bufferAsJavaList(scala.collection.mutable.Buffer)` - * then the original Scala `Buffer` will be returned. + * If the Java `List` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.bufferAsJavaList]](scala.collection.mutable.Buffer)` then the original Scala + * `Buffer` will be returned. * - * @param l The `List` to be converted. + * @param l The Java `List` to be converted. * @return A Scala mutable `Buffer` view of the argument. */ def asScalaBuffer[A](l: ju.List[A]): mutable.Buffer[A] = l match { @@ -113,18 +109,17 @@ trait AsScalaConverters { } /** - * Converts a Java Set to a Scala mutable Set. + * Converts a Java `Set` to a Scala mutable `Set`. * - * The returned Scala Set is backed by the provided Java - * Set and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * The returned Scala `Set` is backed by the provided Java `Set` and any side-effects of using it + * via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java Set was previously obtained from an implicit or - * explicit call of `mutableSetAsJavaSet(scala.collection.mutable.Set)` then - * the original Scala Set will be returned. + * If the Java `Set` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mutableSetAsJavaSet]](scala.collection.mutable.Set)` then the original Scala + * `Set` will be returned. * - * @param s The Set to be converted. - * @return A Scala mutable Set view of the argument. + * @param s The Java `Set` to be converted. + * @return A Scala mutable `Set` view of the argument. */ def asScalaSet[A](s: ju.Set[A]): mutable.Set[A] = s match { case null => null @@ -135,22 +130,20 @@ trait AsScalaConverters { /** * Converts a Java `Map` to a Scala mutable `Map`. * - * The returned Scala `Map` is backed by the provided Java `Map` and any - * side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. + * The returned Scala `Map` is backed by the provided Java `Map` and any side-effects of using it + * via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java `Map` was previously obtained from an implicit or - * explicit call of `mutableMapAsJavaMap(scala.collection.mutable.Map)` then - * the original Scala Map will be returned. + * If the Java `Map` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mutableMapAsJavaMap]](scala.collection.mutable.Map)` then the original Scala + * `Map` will be returned. * - * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`), - * it is your responsibility to wrap all - * non-atomic operations with `underlying.synchronized`. - * This includes `get`, as `java.util.Map`'s API does not allow for an - * atomic `get` when `null` values may be present. + * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`), it is + * your responsibility to wrap all non-atomic operations with `underlying.synchronized`. + * This includes `get`, as `java.util.Map`'s API does not allow for an atomic `get` when `null` + * values may be present. * - * @param m The Map to be converted. - * @return A Scala mutable Map view of the argument. + * @param m The Java `Map` to be converted. + * @return A Scala mutable `Map` view of the argument. */ def mapAsScalaMap[A, B](m: ju.Map[A, B]): mutable.Map[A, B] = m match { case null => null @@ -159,18 +152,18 @@ trait AsScalaConverters { } /** - * Converts a Java ConcurrentMap to a Scala mutable ConcurrentMap. + * Converts a Java `ConcurrentMap` to a Scala mutable `ConcurrentMap`. * - * The returned Scala ConcurrentMap is backed by the provided Java - * ConcurrentMap and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * The returned Scala `ConcurrentMap` is backed by the provided Java `ConcurrentMap` and any + * side-effects of using it via the Scala interface will be visible via the Java interface and + * vice versa. * - * If the Java ConcurrentMap was previously obtained from an implicit or - * explicit call of `mapAsJavaConcurrentMap(scala.collection.mutable.ConcurrentMap)` - * then the original Scala ConcurrentMap will be returned. + * If the Java `ConcurrentMap` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.mapAsJavaConcurrentMap]](scala.collection.mutable.ConcurrentMap)` + * then the original Scala `ConcurrentMap` will be returned. * - * @param m The ConcurrentMap to be converted. - * @return A Scala mutable ConcurrentMap view of the argument. + * @param m The Java `ConcurrentMap` to be converted. + * @return A Scala mutable `ConcurrentMap` view of the argument. */ def mapAsScalaConcurrentMap[A, B](m: juc.ConcurrentMap[A, B]): concurrent.Map[A, B] = m match { case null => null @@ -181,16 +174,15 @@ trait AsScalaConverters { /** * Converts a Java `Dictionary` to a Scala mutable `Map`. * - * The returned Scala `Map` is backed by the provided Java - * `Dictionary` and any side-effects of using it via the Scala interface - * will be visible via the Java interface and vice versa. + * The returned Scala `Map` is backed by the provided Java `Dictionary` and any side-effects of + * using it via the Scala interface will be visible via the Java interface and vice versa. * - * If the Java `Dictionary` was previously obtained from an implicit or - * explicit call of `asJavaDictionary(scala.collection.mutable.Map)` then the original - * Scala Map will be returned. + * If the Java `Dictionary` was previously obtained from an implicit or explicit call of + * `[[JavaConverters.asJavaDictionary]](scala.collection.mutable.Map)` then the original + * Scala `Map` will be returned. * - * @param p The Dictionary to be converted. - * @return A Scala mutable Map view of the argument. + * @param p The Java `Dictionary` to be converted. + * @return A Scala mutable `Map` view of the argument. */ def dictionaryAsScalaMap[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = p match { case null => null @@ -199,14 +191,14 @@ trait AsScalaConverters { } /** - * Converts a Java `Properties` to a Scala `mutable Map[String, String]`. + * Converts a Java `Properties` to a Scala mutable `Map[String, String]`. * - * The returned Scala `Map[String, String]` is backed by the provided Java - * `Properties` and any side-effects of using it via the Scala interface - * will be visible via the Java interface and vice versa. + * The returned Scala `Map[String, String]` is backed by the provided Java `Properties` and any + * side-effects of using it via the Scala interface will be visible via the Java interface and + * vice versa. * - * @param p The Properties to be converted. - * @return A Scala mutable Map[String, String] view of the argument. + * @param p The Java `Properties` to be converted. + * @return A Scala mutable `Map[String, String]` view of the argument. */ def propertiesAsScalaMap(p: ju.Properties): mutable.Map[String, String] = p match { case null => null diff --git a/src/library/scala/collection/convert/DecorateAsJava.scala b/src/library/scala/collection/convert/DecorateAsJava.scala index 6088bce63f..8371804b91 100644 --- a/src/library/scala/collection/convert/DecorateAsJava.scala +++ b/src/library/scala/collection/convert/DecorateAsJava.scala @@ -1,6 +1,6 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** -** / __/ __// _ | / / / _ | (c) 2006-2013, LAMP/EPFL ** +** / __/ __// _ | / / / _ | (c) 2006-2016, LAMP/EPFL ** ** __\ \/ /__/ __ |/ /__/ __ | http://www.scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** @@ -14,286 +14,95 @@ import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc } import Decorators._ import scala.language.implicitConversions -/** A collection of decorators that allow converting between - * Scala and Java collections using `asScala` and `asJava` methods. - * - * The following conversions are supported via `asJava`, `asScala` - *{{{ - * scala.collection.Iterable <=> java.lang.Iterable - * scala.collection.Iterator <=> java.util.Iterator - * scala.collection.mutable.Buffer <=> java.util.List - * scala.collection.mutable.Set <=> java.util.Set - * scala.collection.mutable.Map <=> java.util.Map - * scala.collection.mutable.concurrent.Map <=> java.util.concurrent.ConcurrentMap - *}}} - * In all cases, converting from a source type to a target type and back - * again will return the original source object, e.g. - * {{{ - * import scala.collection.JavaConverters._ - * - * val sl = new scala.collection.mutable.ListBuffer[Int] - * val jl : java.util.List[Int] = sl.asJava - * val sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala - * assert(sl eq sl2) - * }}} - * The following conversions are also supported, but the - * direction from Scala to Java is done by the more specifically named methods: - * `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`. - *{{{ - * scala.collection.Iterable <=> java.util.Collection - * scala.collection.Iterator <=> java.util.Enumeration - * scala.collection.mutable.Map <=> java.util.Dictionary - *}}} - * In addition, the following one way conversions are provided via `asJava`: - *{{{ - * scala.collection.Seq => java.util.List - * scala.collection.mutable.Seq => java.util.List - * scala.collection.Set => java.util.Set - * scala.collection.Map => java.util.Map - *}}} - * The following one way conversion is provided via `asScala`: - *{{{ - * java.util.Properties => scala.collection.mutable.Map - *}}} - * - * @since 2.8.1 - */ +/** Defines `asJava` extension methods for [[JavaConverters]]. */ trait DecorateAsJava extends AsJavaConverters { /** - * Adds an `asJava` method that implicitly converts a Scala `Iterator` to a - * Java `Iterator`. The returned Java `Iterator` is backed by the provided Scala - * `Iterator` and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala `Iterator` was previously obtained from an implicit or explicit - * call of `asIterator(java.util.Iterator)` then the original Java `Iterator` - * will be returned by the `asJava` method. - * - * @param i The `Iterator` to be converted. - * @return An object with an `asJava` method that returns a Java `Iterator` view of the argument. + * Adds an `asJava` method that implicitly converts a Scala `Iterator` to a Java `Iterator`. + * See [[asJavaIterator]]. */ implicit def asJavaIteratorConverter[A](i : Iterator[A]): AsJava[ju.Iterator[A]] = new AsJava(asJavaIterator(i)) /** - * Adds an `asJavaEnumeration` method that implicitly converts a Scala - * `Iterator` to a Java `Enumeration`. The returned Java `Enumeration` is - * backed by the provided Scala `Iterator` and any side-effects of using - * it via the Java interface will be visible via the Scala interface and - * vice versa. - * - * If the Scala `Iterator` was previously obtained from an implicit or - * explicit call of `asIterator(java.util.Enumeration)` then the - * original Java `Enumeration` will be returned. - * - * @param i The `Iterator` to be converted. - * @return An object with an `asJavaEnumeration` method that returns a Java - * `Enumeration` view of the argument. + * Adds an `asJavaEnumeration` method that implicitly converts a Scala `Iterator` to a Java + * `Enumeration`. See [[asJavaEnumeration]]. */ implicit def asJavaEnumerationConverter[A](i : Iterator[A]): AsJavaEnumeration[A] = new AsJavaEnumeration(i) /** - * Adds an `asJava` method that implicitly converts a Scala `Iterable` to - * a Java `Iterable`. - * - * The returned Java `Iterable` is backed by the provided Scala `Iterable` - * and any side-effects of using it via the Java interface will be visible - * via the Scala interface and vice versa. - * - * If the Scala `Iterable` was previously obtained from an implicit or - * explicit call of `asIterable(java.lang.Iterable)` then the original - * Java `Iterable` will be returned. - * - * @param i The `Iterable` to be converted. - * @return An object with an `asJavaCollection` method that returns a Java - * `Iterable` view of the argument. + * Adds an `asJava` method that implicitly converts a Scala `Iterable` to a Java `Iterable`. + * See [[asJavaIterable]]. */ implicit def asJavaIterableConverter[A](i : Iterable[A]): AsJava[jl.Iterable[A]] = new AsJava(asJavaIterable(i)) /** - * Adds an `asJavaCollection` method that implicitly converts a Scala - * `Iterable` to an immutable Java `Collection`. - * - * If the Scala `Iterable` was previously obtained from an implicit or - * explicit call of `asSizedIterable(java.util.Collection)` then the - * original Java `Collection` will be returned. - * - * @param i The `SizedIterable` to be converted. - * @return An object with an `asJava` method that returns a Java - * `Collection` view of the argument. + * Adds an `asJavaCollection` method that implicitly converts a Scala `Iterable` to an immutable + * Java `Collection`. See [[asJavaCollection]]. */ implicit def asJavaCollectionConverter[A](i : Iterable[A]): AsJavaCollection[A] = new AsJavaCollection(i) /** - * Adds an `asJava` method that implicitly converts a Scala mutable `Buffer` - * to a Java `List`. - * - * The returned Java `List` is backed by the provided Scala `Buffer` and any - * side-effects of using it via the Java interface will be visible via the - * Scala interface and vice versa. - * - * If the Scala `Buffer` was previously obtained from an implicit or explicit - * call of `asBuffer(java.util.List)` then the original Java `List` will be - * returned. - * - * @param b The `Buffer` to be converted. - * @return An object with an `asJava` method that returns a Java `List` view - * of the argument. + * Adds an `asJava` method that implicitly converts a Scala mutable `Buffer` to a Java `List`. + * See [[bufferAsJavaList]]. */ implicit def bufferAsJavaListConverter[A](b : mutable.Buffer[A]): AsJava[ju.List[A]] = new AsJava(bufferAsJavaList(b)) /** - * Adds an `asJava` method that implicitly converts a Scala mutable `Seq` - * to a Java `List`. - * - * The returned Java `List` is backed by the provided Scala `Seq` and any - * side-effects of using it via the Java interface will be visible via the - * Scala interface and vice versa. - * - * If the Scala `Seq` was previously obtained from an implicit or explicit - * call of `asSeq(java.util.List)` then the original Java `List` will be - * returned. - * - * @param b The `Seq` to be converted. - * @return An object with an `asJava` method that returns a Java `List` - * view of the argument. + * Adds an `asJava` method that implicitly converts a Scala mutable `Seq` to a Java `List`. + * See [[mutableSeqAsJavaList]]. */ implicit def mutableSeqAsJavaListConverter[A](b : mutable.Seq[A]): AsJava[ju.List[A]] = new AsJava(mutableSeqAsJavaList(b)) /** - * Adds an `asJava` method that implicitly converts a Scala `Seq` to a - * Java `List`. - * - * The returned Java `List` is backed by the provided Scala `Seq` and any - * side-effects of using it via the Java interface will be visible via the - * Scala interface and vice versa. - * - * If the Scala `Seq` was previously obtained from an implicit or explicit - * call of `asSeq(java.util.List)` then the original Java `List` will be - * returned. - * - * @param b The `Seq` to be converted. - * @return An object with an `asJava` method that returns a Java `List` - * view of the argument. + * Adds an `asJava` method that implicitly converts a Scala `Seq` to a Java `List`. + * See [[seqAsJavaList]]. */ implicit def seqAsJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] = new AsJava(seqAsJavaList(b)) /** - * Adds an `asJava` method that implicitly converts a Scala mutable `Set`> - * to a Java `Set`. - * - * The returned Java `Set` is backed by the provided Scala `Set` and any - * side-effects of using it via the Java interface will be visible via - * the Scala interface and vice versa. - * - * If the Scala `Set` was previously obtained from an implicit or explicit - * call of `asSet(java.util.Set)` then the original Java `Set` will be - * returned. - * - * @param s The `Set` to be converted. - * @return An object with an `asJava` method that returns a Java `Set` view - * of the argument. + * Adds an `asJava` method that implicitly converts a Scala mutable `Set` to a Java `Set`. + * See [[mutableSetAsJavaSet]]. */ implicit def mutableSetAsJavaSetConverter[A](s : mutable.Set[A]): AsJava[ju.Set[A]] = new AsJava(mutableSetAsJavaSet(s)) /** - * Adds an `asJava` method that implicitly converts a Scala `Set` to a - * Java `Set`. - * - * The returned Java `Set` is backed by the provided Scala `Set` and any - * side-effects of using it via the Java interface will be visible via - * the Scala interface and vice versa. - * - * If the Scala `Set` was previously obtained from an implicit or explicit - * call of `asSet(java.util.Set)` then the original Java `Set` will be - * returned. - * - * @param s The `Set` to be converted. - * @return An object with an `asJava` method that returns a Java `Set` view - * of the argument. + * Adds an `asJava` method that implicitly converts a Scala `Set` to a Java `Set`. + * See [[setAsJavaSet]]. */ implicit def setAsJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] = new AsJava(setAsJavaSet(s)) /** - * Adds an `asJava` method that implicitly converts a Scala mutable `Map` - * to a Java `Map`. - * - * The returned Java `Map` is backed by the provided Scala `Map` and any - * side-effects of using it via the Java interface will be visible via the - * Scala interface and vice versa. - * - * If the Scala `Map` was previously obtained from an implicit or explicit - * call of `asMap(java.util.Map)` then the original Java `Map` will be - * returned. - * - * @param m The `Map` to be converted. - * @return An object with an `asJava` method that returns a Java `Map` view - * of the argument. + * Adds an `asJava` method that implicitly converts a Scala mutable `Map` to a Java `Map`. + * See [[mutableMapAsJavaMap]]. */ implicit def mutableMapAsJavaMapConverter[A, B](m : mutable.Map[A, B]): AsJava[ju.Map[A, B]] = new AsJava(mutableMapAsJavaMap(m)) /** - * Adds an `asJavaDictionary` method that implicitly converts a Scala - * mutable `Map` to a Java `Dictionary`. - * - * The returned Java `Dictionary` is backed by the provided Scala - * `Dictionary` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. - * - * If the Scala `Dictionary` was previously obtained from an implicit or - * explicit call of `asMap(java.util.Dictionary)` then the original - * Java `Dictionary` will be returned. - * - * @param m The `Map` to be converted. - * @return An object with an `asJavaDictionary` method that returns a - * Java `Dictionary` view of the argument. + * Adds an `asJavaDictionary` method that implicitly converts a Scala mutable `Map` to a Java + * `Dictionary`. See [[asJavaDictionary]]. */ implicit def asJavaDictionaryConverter[A, B](m : mutable.Map[A, B]): AsJavaDictionary[A, B] = new AsJavaDictionary(m) /** - * Adds an `asJava` method that implicitly converts a Scala `Map` to - * a Java `Map`. - * - * The returned Java `Map` is backed by the provided Scala `Map` and any - * side-effects of using it via the Java interface will be visible via - * the Scala interface and vice versa. - * - * If the Scala `Map` was previously obtained from an implicit or explicit - * call of `asMap(java.util.Map)` then the original Java `Map` will be - * returned. - * - * @param m The `Map` to be converted. - * @return An object with an `asJava` method that returns a Java `Map` view - * of the argument. + * Adds an `asJava` method that implicitly converts a Scala `Map` to a Java `Map`. + * See [[mapAsJavaMap]]. */ implicit def mapAsJavaMapConverter[A, B](m : Map[A, B]): AsJava[ju.Map[A, B]] = new AsJava(mapAsJavaMap(m)) /** - * Adds an `asJava` method that implicitly converts a Scala mutable - * `concurrent.Map` to a Java `ConcurrentMap`. - * - * The returned Java `ConcurrentMap` is backed by the provided Scala - * `concurrent.Map` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. - * - * If the Scala `concurrent.Map` was previously obtained from an implicit or - * explicit call of `asConcurrentMap(java.util.concurrent.ConcurrentMap)` - * then the original Java `ConcurrentMap` will be returned. - * - * @param m The Scala `concurrent.Map` to be converted. - * @return An object with an `asJava` method that returns a Java - * `ConcurrentMap` view of the argument. + * Adds an `asJava` method that implicitly converts a Scala mutable `concurrent.Map` to a Java + * `ConcurrentMap`. See [[mapAsJavaConcurrentMap]]. */ implicit def mapAsJavaConcurrentMapConverter[A, B](m: concurrent.Map[A, B]): AsJava[juc.ConcurrentMap[A, B]] = new AsJava(mapAsJavaConcurrentMap(m)) diff --git a/src/library/scala/collection/convert/DecorateAsScala.scala b/src/library/scala/collection/convert/DecorateAsScala.scala index cbd37fa504..b74a06ece5 100644 --- a/src/library/scala/collection/convert/DecorateAsScala.scala +++ b/src/library/scala/collection/convert/DecorateAsScala.scala @@ -1,6 +1,6 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** -** / __/ __// _ | / / / _ | (c) 2006-2013, LAMP/EPFL ** +** / __/ __// _ | / / / _ | (c) 2006-2016, LAMP/EPFL ** ** __\ \/ /__/ __ |/ /__/ __ | http://www.scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** @@ -14,182 +14,74 @@ import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc } import Decorators._ import scala.language.implicitConversions +/** Defines `asScala` extension methods for [[JavaConverters]]. */ trait DecorateAsScala extends AsScalaConverters { /** - * Adds an `asScala` method that implicitly converts a Java `Iterator` to - * a Scala `Iterator`. - * - * The returned Scala `Iterator` is backed by the provided Java `Iterator` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. - * - * If the Java `Iterator` was previously obtained from an implicit or - * explicit call of `asIterator(scala.collection.Iterator)` then the - * original Scala `Iterator` will be returned. - * - * @param i The `Iterator` to be converted. - * @return An object with an `asScala` method that returns a Scala - * `Iterator` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Iterator` to a Scala `Iterator`. + * See [[asScalaIterator]]. */ implicit def asScalaIteratorConverter[A](i : ju.Iterator[A]): AsScala[Iterator[A]] = new AsScala(asScalaIterator(i)) /** - * Adds an `asScala` method that implicitly converts a Java `Enumeration` - * to a Scala `Iterator`. - * - * The returned Scala `Iterator` is backed by the provided Java - * `Enumeration` and any side-effects of using it via the Scala interface - * will be visible via the Java interface and vice versa. - * - * If the Java `Enumeration` was previously obtained from an implicit or - * explicit call of `asEnumeration(scala.collection.Iterator)` then the - * original Scala `Iterator` will be returned. - * - * @param i The `Enumeration` to be converted. - * @return An object with an `asScala` method that returns a Scala - * `Iterator` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Enumeration` to a Scala `Iterator`. + * See [[enumerationAsScalaIterator]]. */ implicit def enumerationAsScalaIteratorConverter[A](i : ju.Enumeration[A]): AsScala[Iterator[A]] = new AsScala(enumerationAsScalaIterator(i)) /** - * Adds an `asScala` method that implicitly converts a Java `Iterable` to - * a Scala `Iterable`. - * - * The returned Scala `Iterable` is backed by the provided Java `Iterable` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. - * - * If the Java `Iterable` was previously obtained from an implicit or - * explicit call of `asIterable(scala.collection.Iterable)` then the original - * Scala `Iterable` will be returned. - * - * @param i The `Iterable` to be converted. - * @return An object with an `asScala` method that returns a Scala `Iterable` - * view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Iterable` to a Scala `Iterable`. + * See [[iterableAsScalaIterable]]. */ implicit def iterableAsScalaIterableConverter[A](i : jl.Iterable[A]): AsScala[Iterable[A]] = new AsScala(iterableAsScalaIterable(i)) /** - * Adds an `asScala` method that implicitly converts a Java `Collection` to - * an Scala `Iterable`. - * - * If the Java `Collection` was previously obtained from an implicit or - * explicit call of `asCollection(scala.collection.SizedIterable)` then - * the original Scala `SizedIterable` will be returned. - * - * @param i The `Collection` to be converted. - * @return An object with an `asScala` method that returns a Scala - * `SizedIterable` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Collection` to an Scala `Iterable`. + * See [[collectionAsScalaIterable]]. */ implicit def collectionAsScalaIterableConverter[A](i : ju.Collection[A]): AsScala[Iterable[A]] = new AsScala(collectionAsScalaIterable(i)) /** - * Adds an `asScala` method that implicitly converts a Java `List` to a - * Scala mutable `Buffer`. - * - * The returned Scala `Buffer` is backed by the provided Java `List` and - * any side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. - * - * If the Java `List` was previously obtained from an implicit or explicit - * call of `asList(scala.collection.mutable.Buffer)` then the original - * Scala `Buffer` will be returned. - * - * @param l The `List` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `Buffer` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `List` to a Scala mutable `Buffer`. + * See [[asScalaBuffer]]. */ implicit def asScalaBufferConverter[A](l : ju.List[A]): AsScala[mutable.Buffer[A]] = new AsScala(asScalaBuffer(l)) /** - * Adds an `asScala` method that implicitly converts a Java `Set` to a - * Scala mutable `Set`. - * - * The returned Scala `Set` is backed by the provided Java `Set` and any - * side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. - * - * If the Java `Set` was previously obtained from an implicit or explicit - * call of `asSet(scala.collection.mutable.Set)` then the original - * Scala `Set` will be returned. - * - * @param s The `Set` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `Set` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Set` to a Scala mutable `Set`. + * See [[asScalaSet]]. */ implicit def asScalaSetConverter[A](s : ju.Set[A]): AsScala[mutable.Set[A]] = new AsScala(asScalaSet(s)) /** - * Adds an `asScala` method that implicitly converts a Java `Map` to a Scala - * mutable `Map`. The returned Scala `Map` is backed by the provided Java - * `Map` and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * - * If the Java `Map` was previously obtained from an implicit or explicit - * call of `asMap(scala.collection.mutable.Map)` then the original - * Scala `Map` will be returned. - * - * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`), - * it is your responsibility to wrap all - * non-atomic operations with `underlying.synchronized`. - * This includes `get`, as `java.util.Map`'s API does not allow for an - * atomic `get` when `null` values may be present. - * - * @param m The `Map` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `Map` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Map` to a Scala mutable `Map`. + * See [[mapAsScalaMap]]. */ implicit def mapAsScalaMapConverter[A, B](m : ju.Map[A, B]): AsScala[mutable.Map[A, B]] = new AsScala(mapAsScalaMap(m)) /** - * Adds an `asScala` method that implicitly converts a Java `ConcurrentMap` - * to a Scala mutable `concurrent.Map`. The returned Scala `concurrent.Map` is - * backed by the provided Java `ConcurrentMap` and any side-effects of using - * it via the Scala interface will be visible via the Java interface and - * vice versa. - * - * If the Java `ConcurrentMap` was previously obtained from an implicit or - * explicit call of `mapAsScalaConcurrentMap(scala.collection.mutable.ConcurrentMap)` - * then the original Scala `concurrent.Map` will be returned. - * - * @param m The `ConcurrentMap` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `concurrent.Map` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `ConcurrentMap` to a Scala mutable + * `concurrent.Map`. See [[mapAsScalaConcurrentMap]]. */ implicit def mapAsScalaConcurrentMapConverter[A, B](m: juc.ConcurrentMap[A, B]): AsScala[concurrent.Map[A, B]] = new AsScala(mapAsScalaConcurrentMap(m)) /** - * Adds an `asScala` method that implicitly converts a Java `Dictionary` - * to a Scala mutable `Map[String, String]`. The returned Scala - * `Map[String, String]` is backed by the provided Java `Dictionary` and - * any side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. - * - * @param p The `Dictionary` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `Map[String, String]` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Dictionary` to a Scala mutable `Map`. + * See [[dictionaryAsScalaMap]]. */ implicit def dictionaryAsScalaMapConverter[A, B](p: ju.Dictionary[A, B]): AsScala[mutable.Map[A, B]] = new AsScala(dictionaryAsScalaMap(p)) /** - * Adds an `asScala` method that implicitly converts a Java `Properties` - * to a Scala mutable `Map[String, String]`. The returned Scala - * `Map[String, String]` is backed by the provided Java `Properties` and - * any side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. - * - * @param p The `Properties` to be converted. - * @return An object with an `asScala` method that returns a Scala mutable - * `Map[String, String]` view of the argument. + * Adds an `asScala` method that implicitly converts a Java `Properties` to a Scala mutable + * `Map[String, String]`. See [[propertiesAsScalaMap]]. */ implicit def propertiesAsScalaMapConverter(p: ju.Properties): AsScala[mutable.Map[String, String]] = new AsScala(propertiesAsScalaMap(p)) diff --git a/src/library/scala/collection/convert/ImplicitConversions.scala b/src/library/scala/collection/convert/ImplicitConversions.scala index 2ddb16ec56..747e0606c8 100644 --- a/src/library/scala/collection/convert/ImplicitConversions.scala +++ b/src/library/scala/collection/convert/ImplicitConversions.scala @@ -17,358 +17,76 @@ import JavaConverters._ /** Defines implicit converter methods from Java to Scala collections. */ trait ToScalaImplicits { - - /** - * Implicitly converts a Java `Iterator` to a Scala `Iterator`. - * - * The returned Scala `Iterator` is backed by the provided Java `Iterator` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. - * - * If the Java `Iterator` was previously obtained from an implicit or - * explicit call of `asIterator(scala.collection.Iterator)` then the - * original Scala `Iterator` will be returned. - * - * @param it The `Iterator` to be converted. - * @return A Scala `Iterator` view of the argument. - */ + /** Implicitly converts a Java `Iterator` to a Scala `Iterator`. See [[asScalaIterator]]. */ implicit def `iterator asScala`[A](it: ju.Iterator[A]): Iterator[A] = asScalaIterator(it) - /** - * Implicitly converts a Java Enumeration to a Scala Iterator. - * The returned Scala Iterator is backed by the provided Java - * Enumeration and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * - * If the Java Enumeration was previously obtained from an implicit or - * explicit call of `enumerationAsScalaIterator(scala.collection.Iterator)` - * then the original Scala Iterator will be returned. - * - * @param i The Enumeration to be converted. - * @return A Scala Iterator view of the argument. - */ + /** Implicitly converts a Java `Enumeration` to a Scala `Iterator`. See [[enumerationAsScalaIterator]]. */ implicit def `enumeration AsScalaIterator`[A](i: ju.Enumeration[A]): Iterator[A] = enumerationAsScalaIterator(i) - /** - * Implicitly converts a Java `Iterable` to a Scala `Iterable`. - * - * The returned Scala `Iterable` is backed by the provided Java `Iterable` - * and any side-effects of using it via the Scala interface will be visible - * via the Java interface and vice versa. - * - * If the Java `Iterable` was previously obtained from an implicit or - * explicit call of `iterableAsScalaIterable(scala.collection.Iterable)` - * then the original Scala Iterable will be returned. - * - * @param i The Iterable to be converted. - * @return A Scala Iterable view of the argument. - */ + /** Implicitly converts a Java `Iterable` to a Scala `Iterable`. See [[iterableAsScalaIterable]]. */ implicit def `iterable AsScalaIterable`[A](i: jl.Iterable[A]): Iterable[A] = iterableAsScalaIterable(i) - /** - * Implicitly converts a Java `Collection` to an Scala `Iterable`. - * - * If the Java `Collection` was previously obtained from an implicit or - * explicit call of `collectionAsScalaIterable(scala.collection.SizedIterable)` - * then the original Scala `Iterable` will be returned. - * - * @param i The Collection to be converted. - * @return A Scala Iterable view of the argument. - */ + /** Implicitly converts a Java `Collection` to an Scala `Iterable`. See [[collectionAsScalaIterable]]. */ implicit def `collection AsScalaIterable`[A](i: ju.Collection[A]): Iterable[A] = collectionAsScalaIterable(i) - /** - * Implicitly converts a Java `List` to a Scala mutable `Buffer`. - * - * The returned Scala `Buffer` is backed by the provided Java `List` - * and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * - * If the Java `List` was previously obtained from an implicit or - * explicit call of `asScalaBuffer(scala.collection.mutable.Buffer)` - * then the original Scala `Buffer` will be returned. - * - * @param l The `List` to be converted. - * @return A Scala mutable `Buffer` view of the argument. - */ + /** Implicitly converts a Java `List` to a Scala mutable `Buffer`. See [[asScalaBuffer]]. */ implicit def `list asScalaBuffer`[A](l: ju.List[A]): mutable.Buffer[A] = asScalaBuffer(l) - /** - * Implicitly converts a Java Set to a Scala mutable Set. - * The returned Scala Set is backed by the provided Java - * Set and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * - * If the Java Set was previously obtained from an implicit or - * explicit call of `asScalaSet(scala.collection.mutable.Set)` then - * the original Scala Set will be returned. - * - * @param s The Set to be converted. - * @return A Scala mutable Set view of the argument. - */ + /** Implicitly converts a Java `Set` to a Scala mutable `Set`. See [[asScalaSet]]. */ implicit def `set asScala`[A](s: ju.Set[A]): mutable.Set[A] = asScalaSet(s) - /** - * Implicitly converts a Java `Map` to a Scala mutable `Map`. - * - * The returned Scala `Map` is backed by the provided Java `Map` and any - * side-effects of using it via the Scala interface will be visible via - * the Java interface and vice versa. - * - * If the Java `Map` was previously obtained from an implicit or - * explicit call of `mapAsScalaMap(scala.collection.mutable.Map)` then - * the original Scala Map will be returned. - * - * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`), - * it is your responsibility to wrap all - * non-atomic operations with `underlying.synchronized`. - * This includes `get`, as `java.util.Map`'s API does not allow for an - * atomic `get` when `null` values may be present. - * - * @param m The Map to be converted. - * @return A Scala mutable Map view of the argument. - */ + /** Implicitly converts a Java `Map` to a Scala mutable `Map`. See [[mapAsScalaMap]]. */ implicit def `map AsScala`[A, B](m: ju.Map[A, B]): mutable.Map[A, B] = mapAsScalaMap(m) - /** - * Implicitly converts a Java ConcurrentMap to a Scala mutable ConcurrentMap. - * The returned Scala ConcurrentMap is backed by the provided Java - * ConcurrentMap and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * - * If the Java ConcurrentMap was previously obtained from an implicit or - * explicit call of `asConcurrentMap(scala.collection.mutable.ConcurrentMap)` - * then the original Scala ConcurrentMap will be returned. - * - * @param m The ConcurrentMap to be converted. - * @return A Scala mutable ConcurrentMap view of the argument. - */ + /** Implicitly converts a Java `ConcurrentMap` to a Scala mutable `ConcurrentMap`. See [[mapAsScalaConcurrentMap]]. */ implicit def `map AsScalaConcurrentMap`[A, B](m: juc.ConcurrentMap[A, B]): concurrent.Map[A, B] = mapAsScalaConcurrentMap(m) - /** - * Implicitly converts a Java `Dictionary` to a Scala mutable - * `Map`. - * - * The returned Scala `Map` is backed by the provided Java - * `Dictionary` and any side-effects of using it via the Scala interface - * will be visible via the Java interface and vice versa. - * - * @param p The Dictionary to be converted. - * @return A Scala mutable Map view of the argument. - */ + /** Implicitly converts a Java `Dictionary` to a Scala mutable `Map`. See [[dictionaryAsScalaMap]]. */ implicit def `dictionary AsScalaMap`[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = dictionaryAsScalaMap(p) - /** - * Implicitly converts a Java `Properties` to a Scala `mutable Map[String, String]`. - * - * The returned Scala `Map[String, String]` is backed by the provided Java - * `Properties` and any side-effects of using it via the Scala interface - * will be visible via the Java interface and vice versa. - * - * @param p The Properties to be converted. - * @return A Scala mutable Map[String, String] view of the argument. - */ + /** Implicitly converts a Java `Properties` to a Scala `mutable Map[String, String]`. See [[propertiesAsScalaMap]]. */ implicit def `properties AsScalaMap`(p: ju.Properties): mutable.Map[String, String] = propertiesAsScalaMap(p) } /** Defines implicit conversions from Scala to Java collections. */ trait ToJavaImplicits { - - /** - * Implicitly converts a Scala Iterator to a Java Iterator. - * The returned Java Iterator is backed by the provided Scala - * Iterator and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Iterator was previously obtained from an implicit or - * explicit call of `asIterator(java.util.Iterator)` then the original - * Java Iterator will be returned. - * - * @param it The Iterator to be converted. - * @return A Java Iterator view of the argument. - */ + /** Implicitly converts a Scala `Iterator` to a Java `Iterator`. See [[asJavaIterator]]. */ implicit def `iterator asJava`[A](it: Iterator[A]): ju.Iterator[A] = asJavaIterator(it) - /** - * Implicitly converts a Scala Iterator to a Java Enumeration. - * The returned Java Enumeration is backed by the provided Scala - * Iterator and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Iterator was previously obtained from an implicit or - * explicit call of `asIterator(java.util.Enumeration)` then the - * original Java Enumeration will be returned. - * - * @param it The Iterator to be converted. - * @return A Java Enumeration view of the argument. - */ + /** Implicitly converts a Scala `Iterator` to a Java `Enumeration`. See [[asJavaEnumeration]]. */ implicit def `enumeration asJava`[A](it: Iterator[A]): ju.Enumeration[A] = asJavaEnumeration(it) - /** - * Implicitly converts a Scala Iterable to a Java Iterable. - * The returned Java Iterable is backed by the provided Scala - * Iterable and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Iterable was previously obtained from an implicit or - * explicit call of `asIterable(java.lang.Iterable)` then the original - * Java Iterable will be returned. - * - * @param i The Iterable to be converted. - * @return A Java Iterable view of the argument. - */ + /** Implicitly converts a Scala `Iterable` to a Java `Iterable`. See [[asJavaIterable]]. */ implicit def `iterable asJava`[A](i: Iterable[A]): jl.Iterable[A] = asJavaIterable(i) - /** - * Implicitly converts a Scala Iterable to an immutable Java - * Collection. - * - * If the Scala Iterable was previously obtained from an implicit or - * explicit call of `asSizedIterable(java.util.Collection)` then the original - * Java Collection will be returned. - * - * @param it The SizedIterable to be converted. - * @return A Java Collection view of the argument. - */ + /** Implicitly converts a Scala `Iterable` to an immutable Java `Collection`. See [[asJavaCollection]]. */ implicit def `collection asJava`[A](it: Iterable[A]): ju.Collection[A] = asJavaCollection(it) - /** - * Implicitly converts a Scala mutable Buffer to a Java List. - * The returned Java List is backed by the provided Scala - * Buffer and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Buffer was previously obtained from an implicit or - * explicit call of `asBuffer(java.util.List)` then the original - * Java List will be returned. - * - * @param b The Buffer to be converted. - * @return A Java List view of the argument. - */ + /** Implicitly converts a Scala mutable `Buffer` to a Java `List`. See [[bufferAsJavaList]]. */ implicit def `buffer AsJavaList`[A](b: mutable.Buffer[A]): ju.List[A] = bufferAsJavaList(b) - /** - * Implicitly converts a Scala mutable Seq to a Java List. - * The returned Java List is backed by the provided Scala - * Seq and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Seq was previously obtained from an implicit or - * explicit call of `asSeq(java.util.List)` then the original - * Java List will be returned. - * - * @param seq The Seq to be converted. - * @return A Java List view of the argument. - */ + /** Implicitly converts a Scala mutable `Seq` to a Java `List`. See [[mutableSeqAsJavaList]]. */ implicit def `mutableSeq AsJavaList`[A](seq: mutable.Seq[A]): ju.List[A] = mutableSeqAsJavaList(seq) - /** - * Implicitly converts a Scala Seq to a Java List. - * The returned Java List is backed by the provided Scala - * Seq and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Seq was previously obtained from an implicit or - * explicit call of `asSeq(java.util.List)` then the original - * Java List will be returned. - * - * @param seq The Seq to be converted. - * @return A Java List view of the argument. - */ + /** Implicitly converts a Scala `Seq` to a Java `List`. See [[seqAsJavaList]]. */ implicit def `seq AsJavaList`[A](seq: Seq[A]): ju.List[A] = seqAsJavaList(seq) - /** - * Implicitly converts a Scala mutable Set to a Java Set. - * The returned Java Set is backed by the provided Scala - * Set and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Set was previously obtained from an implicit or - * explicit call of `asSet(java.util.Set)` then the original - * Java Set will be returned. - * - * @param s The Set to be converted. - * @return A Java Set view of the argument. - */ + /** Implicitly converts a Scala mutable `Set` to a Java `Set`. See [[mutableSetAsJavaSet]]. */ implicit def `mutableSet AsJavaSet`[A](s: mutable.Set[A]): ju.Set[A] = mutableSetAsJavaSet(s) - /** - * Implicitly converts a Scala Set to a Java Set. - * The returned Java Set is backed by the provided Scala - * Set and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Set was previously obtained from an implicit or - * explicit call of asSet(java.util.Set) then the original - * Java Set will be returned. - * - * @param s The Set to be converted. - * @return A Java Set view of the argument. - */ + /** Implicitly converts a Scala `Set` to a Java `Set`. See [[setAsJavaSet]]. */ implicit def `set AsJavaSet`[A](s: Set[A]): ju.Set[A] = setAsJavaSet(s) - /** - * Implicitly converts a Scala mutable Map to a Java Map. - * The returned Java Map is backed by the provided Scala - * Map and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * - * If the Scala Map was previously obtained from an implicit or - * explicit call of `asMap(java.util.Map)` then the original - * Java Map will be returned. - * - * @param m The Map to be converted. - * @return A Java Map view of the argument. - */ + /** Implicitly converts a Scala mutable `Map` to a Java `Map`. See [[mutableMapAsJavaMap]]. */ implicit def `mutableMap AsJavaMap`[A, B](m: mutable.Map[A, B]): ju.Map[A, B] = mutableMapAsJavaMap(m) - /** - * Implicitly converts a Scala mutable `Map` to a Java `Dictionary`. - * - * The returned Java `Dictionary` is backed by the provided Scala - * `Dictionary` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. - * - * If the Scala `Dictionary` was previously obtained from an implicit or - * explicit call of `asMap(java.util.Dictionary)` then the original - * Java Dictionary will be returned. - * - * @param m The `Map` to be converted. - * @return A Java `Dictionary` view of the argument. - */ + /** Implicitly converts a Scala mutable `Map` to a Java `Dictionary`. See [[asJavaDictionary]]. */ implicit def `dictionary asJava`[A, B](m: mutable.Map[A, B]): ju.Dictionary[A, B] = asJavaDictionary(m) - /** - * Implicitly converts a Scala `Map` to a Java `Map`. - * - * The returned Java `Map` is backed by the provided Scala `Map` and - * any side-effects of using it via the Java interface will be visible - * via the Scala interface and vice versa. - * - * If the Scala `Map` was previously obtained from an implicit or - * explicit call of `asMap(java.util.Map)` then the original - * Java `Map` will be returned. - * - * @param m The `Map` to be converted. - * @return A Java `Map` view of the argument. - */ + /** Implicitly converts a Scala `Map` to a Java `Map`. See [[mapAsJavaMap]]. */ implicit def `map AsJavaMap`[A, B](m: Map[A, B]): ju.Map[A, B] = mapAsJavaMap(m) - /** - * Implicitly converts a Scala mutable `concurrent.Map` to a Java - * `ConcurrentMap`. - * - * The returned Java `ConcurrentMap` is backed by the provided Scala - * `concurrent.Map` and any side-effects of using it via the Java interface - * will be visible via the Scala interface and vice versa. - * - * If the Scala `concurrent.Map` was previously obtained from an implicit or - * explicit call of `mapAsScalaConcurrentMap(java.util.concurrent.ConcurrentMap)` - * then the original Java ConcurrentMap will be returned. - * - * @param m The Scala `concurrent.Map` to be converted. - * @return A Java `ConcurrentMap` view of the argument. - */ + /** Implicitly converts a Scala mutable `concurrent.Map` to a Java `ConcurrentMap`. See [[mapAsJavaConcurrentMap]]. */ implicit def `map AsJavaConcurrentMap`[A, B](m: concurrent.Map[A, B]): juc.ConcurrentMap[A, B] = mapAsJavaConcurrentMap(m) } diff --git a/src/library/scala/collection/convert/Wrappers.scala b/src/library/scala/collection/convert/Wrappers.scala index 7fd105c24a..6d745bc6b0 100644 --- a/src/library/scala/collection/convert/Wrappers.scala +++ b/src/library/scala/collection/convert/Wrappers.scala @@ -14,17 +14,7 @@ import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc } import WrapAsScala._ import WrapAsJava._ -/** Adapters for Java/Scala collections API. - * - * The implicit scope of these wrappers includes the current - * lexical scope as well as enclosing package scopes, so the - * implicit conversions provided by `AsScalaImplicits` and - * `AsJavaImplicits` must not be installed in those enclosing - * scopes. - * - * In particular, the implicit scope of classes extending these - * wrappers also includes those contexts. See SI-5580. - */ +/** Adapters for Java/Scala collections API. */ private[collection] trait Wrappers { trait IterableWrapperTrait[A] extends ju.AbstractCollection[A] { val underlying: Iterable[A] -- cgit v1.2.3