diff options
author | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 10:29:58 +0000 |
---|---|---|
committer | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 10:29:58 +0000 |
commit | 628b2edf7363265748e0d345298d6e3663d8133b (patch) | |
tree | ec5c5f7b96a164e5aa6fdd8aedd6a16794803620 /src/library | |
parent | e8c80f152fd2c0058689dff49cf013c9bf7eb2c1 (diff) | |
download | scala-628b2edf7363265748e0d345298d6e3663d8133b.tar.gz scala-628b2edf7363265748e0d345298d6e3663d8133b.tar.bz2 scala-628b2edf7363265748e0d345298d6e3663d8133b.zip |
docs for immutable.A-L*. no review
Diffstat (limited to 'src/library')
14 files changed, 133 insertions, 73 deletions
diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala index 2fd22e7f02..494036467f 100644 --- a/src/library/scala/collection/generic/ImmutableMapFactory.scala +++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala @@ -11,9 +11,15 @@ package scala.collection package generic -/** A template for companion objects of <code>immutable.Map</code> and +/** A template for companion objects of `immutable.Map` and * subclasses thereof. * * @since 2.8 + * @define Coll immutable.Map + * @define coll immutable map + * @define factoryInfo + * This object provides a set of operations needed to create immutable maps of type `$Coll`. + * @author Martin Odersky + * @version 2.8 */ abstract class ImmutableMapFactory[CC[A, +B] <: immutable.Map[A, B] with immutable.MapLike[A, B, CC[A, B]]] extends MapFactory[CC] diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 857b537904..4c90a89104 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -17,6 +17,8 @@ import BitSetLike.{LogWL, updateArray} /** A class for immutable bitsets. * $bitsetinfo + * @define Coll immutable.BitSet + * @define coll immutable bitset */ @serializable @SerialVersionUID(1611436763290191562L) abstract class BitSet extends Set[Int] @@ -53,12 +55,14 @@ abstract class BitSet extends Set[Int] } } -/** A factory object for bitsets */ +/** $factoryInfo + */ object BitSet extends BitSetFactory[BitSet] { /** The empty bitset */ val empty: BitSet = new BitSet1(0L) + /** $bitsetCanBuildFrom */ implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom /** A bitset containing all the bits in an array */ diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala index a19b35aff0..667d86d352 100755 --- a/src/library/scala/collection/immutable/DefaultMap.scala +++ b/src/library/scala/collection/immutable/DefaultMap.scala @@ -14,22 +14,24 @@ package immutable import generic._ -/** <p> - * A default map which implements the <code>updated</code> and <code>-</code> - * methods of maps.<br/> - * Instances that inherit from <code>DefaultMap[A, B]</code> still have to - * define: - * </p> - * <pre> - * <b>def</b> get(key: A): Option[B] - * <b>def</b> iterator: Iterator[(A, B)]</pre> - * <p> - * It refers back to the original map. - * </p> - * <p> - * It might also be advisable to override <code>foreach</code> or - * <code>size</code> if efficient implementations can be found. - * </p> +/** A default map which implements the `+` and `-` + * methods of maps. It does so using the default builder for + * maps defined in the `Map` object. + * Instances that inherit from `DefaultMap[A, B]` still have to + * define: + * + * {{{ + * def get(key: A): Option[B] + * def iterator: Iterator[(A, B)] + * }}} + * + * It refers back to the original map. + * + * It might also be advisable to override `foreach` or + * `size` if efficient implementations can be found. + * + * @tparam A the type of the keys contained in this map. + * @tparam B the type of the values associated with the keys. * * @since 2.8 */ @@ -52,3 +54,13 @@ trait DefaultMap[A, +B] extends Map[A, B] { self => b.result } } + + + + + + + + + + diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala index e0f801546c..c83a5ffcb8 100644 --- a/src/library/scala/collection/immutable/HashMap.scala +++ b/src/library/scala/collection/immutable/HashMap.scala @@ -15,17 +15,22 @@ package immutable import generic._ import annotation.unchecked.uncheckedVariance -/** <p> - * This class implements immutable maps using a hash trie. - * </p> +/** This class implements immutable maps using a hash trie. * - * @note the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4 - * for maps of size <= 4. + * <b>Note:</b> the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4 + * for maps of size <= 4. + * + * @tparam A the type of the keys contained in this hash map. + * @tparam B the type of the values associated with the keys. * * @author Martin Odersky * @author Tiark Rompf * @version 2.8 * @since 2.3 + * @define Coll immutable.HashMap + * @define coll immutable hash map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(2L) class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] { @@ -76,11 +81,11 @@ class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] { } -/** A factory object for immutable HashMaps. +/** $factoryInfo + * @define Coll immutable.HashMap + * @define coll immutable hash map * - * @author Martin Odersky * @author Tiark Rompf - * @version 2.8 * @since 2.3 */ object HashMap extends ImmutableMapFactory[HashMap] { diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala index e79b456a2f..4779702ea7 100644 --- a/src/library/scala/collection/immutable/HashSet.scala +++ b/src/library/scala/collection/immutable/HashSet.scala @@ -15,16 +15,19 @@ package immutable import generic._ import annotation.unchecked.uncheckedVariance -/** - * This class implements immutable sets using a hash trie. +/** This class implements immutable sets using a hash trie. * - * @note the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4` - * for sets of `size <= 4`. + * <b>Note:</b> the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4` + * for sets of `size <= 4`. + * + * @tparam A the type of the elements contained in this hash set. * * @author Martin Odersky * @author Tiark Rompf * @version 2.8 * @since 2.3 + * @define Coll immutable.HashSet + * @define coll immutable hash set */ @serializable @SerialVersionUID(2L) class HashSet[A] extends Set[A] @@ -83,14 +86,19 @@ object HashSet extends SetFactory[HashSet] { */ -/** A factory object for immutable HashSets. +/** $factoryInfo + * @define Coll immutable.HashSet + * @define coll immutable hash set * - * @author Martin Odersky * @author Tiark Rompf - * @version 2.8 * @since 2.3 + * @define Coll immutable.HashSet + * @define coll immutable hash set + * @define mayNotTerminateInf + * @define willNotTerminateInf */ object HashSet extends SetFactory[HashSet] { + /** $setCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, HashSet[A]] = setCanBuildFrom[A] override def empty[A]: HashSet[A] = EmptyHashSet.asInstanceOf[HashSet[A]] diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala index 268bd56a85..4064e9e3a9 100644 --- a/src/library/scala/collection/immutable/IndexedSeq.scala +++ b/src/library/scala/collection/immutable/IndexedSeq.scala @@ -14,7 +14,7 @@ package immutable import generic._ import mutable.{ArrayBuffer, Builder} -/** A subtrait of <code>collection.IndexedSeq</code> which represents indexed sequences +/** A subtrait of `collection.IndexedSeq` which represents indexed sequences * that are guaranteed immutable. * $indexedSeqInfo */ diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala index 75a25e0223..90dfa541e3 100644 --- a/src/library/scala/collection/immutable/IntMap.scala +++ b/src/library/scala/collection/immutable/IntMap.scala @@ -12,8 +12,8 @@ package scala.collection package immutable; -/** - * @author David MacIver +/** Utility class for integer maps. + * @author David MacIver */ private[immutable] object IntMapUtils { def zero(i : Int, mask : Int) = (i & mask) == 0; @@ -50,8 +50,8 @@ private[immutable] object IntMapUtils { import IntMapUtils._ -/** - * @since 2.7 +/** A companion object for integer maps. + * @since 2.7 */ object IntMap { def empty[T] : IntMap[T] = IntMap.Nil; @@ -146,15 +146,19 @@ private[immutable] class IntMapKeyIterator[V](it : IntMap[V]) extends IntMapIter import IntMap._ -/** - * Specialised immutable map structure for integer keys, based on - * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Integer Maps</a> - * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. +/** Specialised immutable map structure for integer keys, based on + * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Integer Maps</a> + * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. * - * Note: This class is as of 2.8 largely superseded by HashMap. + * Note: This class is as of 2.8 largely superseded by HashMap. * - * @since 2.7 + * @tparam T type of the values associated with integer keys. * + * @since 2.7 + * @define Coll immutable.IntMap + * @define coll immutable integer map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap[T]] { override def empty: IntMap[T] = IntMap.Nil; diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala index 795fc2fa92..e0ef5ffcc1 100644 --- a/src/library/scala/collection/immutable/Iterable.scala +++ b/src/library/scala/collection/immutable/Iterable.scala @@ -17,6 +17,9 @@ import mutable.Builder /** A base trait for iterable collections that are guaranteed immutable. * $iterableInfo + * + * @define Coll immutable.Iterable + * @define coll immutable iterable collection */ trait Iterable[+A] extends Traversable[A] with scala.collection.Iterable[A] @@ -25,14 +28,11 @@ trait Iterable[+A] extends Traversable[A] override def companion: GenericCompanion[Iterable] = Iterable } -/** A factory object for the trait <code>Iterable</code>. - * - * @author Martin Odersky - * @version 2.8 - * @since 2.8 +/** $factoryInfo + * @define Coll immutable.Iterable + * @define coll immutable iterable collection */ object Iterable extends TraversableFactory[Iterable] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A] def newBuilder[A]: Builder[A, Iterable[A]] = new mutable.ListBuffer } - diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala index 9cb35dced5..1ffe96310e 100644 --- a/src/library/scala/collection/immutable/LinearSeq.scala +++ b/src/library/scala/collection/immutable/LinearSeq.scala @@ -15,7 +15,7 @@ package immutable import generic._ import mutable.Builder -/** A subtrait of <code>collection.LinearSeq</code> which represents sequences that +/** A subtrait of `collection.LinearSeq` which represents sequences that * are guaranteed immutable. * $linearSeqInfo */ diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala index 4342e54a9d..13d5bbe2ac 100644 --- a/src/library/scala/collection/immutable/ListMap.scala +++ b/src/library/scala/collection/immutable/ListMap.scala @@ -14,9 +14,10 @@ package immutable import generic._ -/** The canonical factory of <a href="ListMap.html">ListMap</a>'s. - * +/** $factoryInfo * @since 1 + * @define Coll immutable.ListMap + * @define coll immutable list map */ object ListMap extends ImmutableMapFactory[ListMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = @@ -25,14 +26,21 @@ object ListMap extends ImmutableMapFactory[ListMap] { } /** This class implements immutable maps using a list-based data - * structure. Instances of <code>ListMap</code> represent + * structure. Instances of `ListMap` represent * empty maps; they can be either created by calling the constructor - * directly, or by applying the function <code>ListMap.empty</code>. + * directly, or by applying the function `ListMap.empty`. + * + * @tparam A the type of the keys in this list map. + * @tparam B the type of the values associated with the keys. * * @author Matthias Zenger * @author Martin Odersky * @version 2.0, 01/01/2007 * @since 1 + * @define Coll immutable.ListMap + * @define coll immutable list map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(301002838095710379L) class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { @@ -45,7 +53,7 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { */ override def size: Int = 0 - /** Checks if this map maps <code>key</code> to a value and return the + /** Checks if this map maps `key` to a value and return the * value if it exists. * * @param key the key of the mapping of interest diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala index f7b76d2317..2a202df9ef 100644 --- a/src/library/scala/collection/immutable/ListSet.scala +++ b/src/library/scala/collection/immutable/ListSet.scala @@ -14,24 +14,32 @@ package immutable import generic._ -/** The canonical factory of <a href="ListSet.html">ListSet</a>'s - * +/** $factoryInfo + * @define Coll immutable.ListSet + * @define coll immutable list set * @since 1 */ object ListSet extends SetFactory[ListSet] { + /** setCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListSet[A]] = setCanBuildFrom[A] override def empty[A] = new ListSet[A] } /** This class implements immutable sets using a list-based data - * structure. Instances of <code>ListSet</code> represent + * structure. Instances of `ListSet` represent * empty sets; they can be either created by calling the constructor - * directly, or by applying the function <code>ListSet.empty</code>. + * directly, or by applying the function `ListSet.empty`. + * + * @tparam A the type of the elements contained in this list set. * * @author Matthias Zenger * @version 1.0, 09/07/2003 * @since 1 + * @define Coll immutable.ListSet + * @define coll immutable list set + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable class ListSet[A] extends Set[A] diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala index 24afb65b99..f31089d24c 100644 --- a/src/library/scala/collection/immutable/LongMap.scala +++ b/src/library/scala/collection/immutable/LongMap.scala @@ -1,8 +1,8 @@ package scala.collection package immutable -/** - * @author David MacIver +/** Utility class for long maps. + * @author David MacIver */ private[immutable] object LongMapUtils{ def zero(i : Long, mask : Long) = (i & mask) == 0L; @@ -40,8 +40,8 @@ private[immutable] object LongMapUtils{ import LongMapUtils._ -/** - * @since 2.7 +/** A companion object for long maps. + * @since 2.7 */ object LongMap{ def empty[T] : LongMap[T] = LongMap.Nil; @@ -134,13 +134,19 @@ private[immutable] class LongMapKeyIterator[V](it : LongMap[V]) extends LongMapI import LongMap._; /** - * Specialised immutable map structure for long keys, based on - * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Long Maps</a> - * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. + * Specialised immutable map structure for long keys, based on + * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Long Maps</a> + * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. + * + * Note: This class is as of 2.8 largely superseded by HashMap. * - * Note: This class is as of 2.8 largely superseded by HashMap. + * @tparam T type of the values associated with the long keys. * - * @since 2.7 + * @since 2.7 + * @define Coll immutable.LongMap + * @define coll immutable long integer map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, LongMap[T]] { override def empty: LongMap[T] = LongMap.Nil; @@ -185,7 +191,7 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon case LongMap.Bin(_, _, left, right) => {left.foreachKey(f); right.foreachKey(f); } case LongMap.Tip(key, _) => f(key); case LongMap.Nil => {} - } + override def valuesIterator : Iterator[T] = this match { case LongMap.Nil => Iterator.empty; diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala index 14ee5afc9b..a0b90f63df 100644 --- a/src/library/scala/collection/mutable/IndexedSeq.scala +++ b/src/library/scala/collection/mutable/IndexedSeq.scala @@ -16,7 +16,6 @@ import generic._ /** A subtrait of `collection.IndexedSeq` which represents sequences * that can be mutated. - * * $indexedSeqInfo */ trait IndexedSeq[A] extends Seq[A] diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala index a4321d3818..09b0c6459b 100644 --- a/src/library/scala/collection/mutable/ListMap.scala +++ b/src/library/scala/collection/mutable/ListMap.scala @@ -59,8 +59,8 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { } /** $factoryInfo - * @define Coll ListMap - * @define coll list map + * @define Coll mutable.ListMap + * @define coll mutable list map */ object ListMap extends MutableMapFactory[ListMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B] |