diff options
author | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 16:32:09 +0000 |
---|---|---|
committer | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 16:32:09 +0000 |
commit | 174c1721ff3b1b581142ad0ed80a655d2d0b4aba (patch) | |
tree | 9cf579b1d564dcd0f5d920b94a83663229986b06 /src/library | |
parent | bf0921a072c4761824365105c785dd5f2cf97588 (diff) | |
download | scala-174c1721ff3b1b581142ad0ed80a655d2d0b4aba.tar.gz scala-174c1721ff3b1b581142ad0ed80a655d2d0b4aba.tar.bz2 scala-174c1721ff3b1b581142ad0ed80a655d2d0b4aba.zip |
Documented immutable.*. no review
Diffstat (limited to 'src/library')
10 files changed, 152 insertions, 82 deletions
diff --git a/src/library/scala/collection/generic/SetFactory.scala b/src/library/scala/collection/generic/SetFactory.scala index 6a237d453c..87de1cec32 100644 --- a/src/library/scala/collection/generic/SetFactory.scala +++ b/src/library/scala/collection/generic/SetFactory.scala @@ -14,7 +14,7 @@ package generic import mutable.{Builder, AddingBuilder} -/** A template for companion objects of <code>Set</code> and subclasses +/** A template for companion objects of `Set` and subclasses * thereof. * * @define coll set diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 4c90a89104..9b801f26cb 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -56,6 +56,8 @@ abstract class BitSet extends Set[Int] } /** $factoryInfo + * @define Coll immutable.BitSet + * @define coll immutable bitset */ object BitSet extends BitSetFactory[BitSet] { diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala index aa7ee908d6..0323db7211 100644 --- a/src/library/scala/collection/immutable/Stack.scala +++ b/src/library/scala/collection/immutable/Stack.scala @@ -42,6 +42,10 @@ object Stack extends SeqFactory[Stack] { * @since 1 * @define Coll immutable.Stack * @define coll immutable stack + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(1976480595012942526L) class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A] diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala index 7f0b21050a..50fa07c2cf 100644 --- a/src/library/scala/collection/immutable/Stream.scala +++ b/src/library/scala/collection/immutable/Stream.scala @@ -16,27 +16,33 @@ import generic._ import mutable.{Builder, StringBuilder, LazyBuilder, ListBuffer} import scala.annotation.tailrec -/** - * <p>The class <code>Stream</code> implements lazy lists where elements - * are only evaluated when they are needed. Here is an example:</p> - * <pre> - * <b>object</b> Main <b>extends</b> Application { +/** The class `Stream` implements lazy lists where elements + * are only evaluated when they are needed. Here is an example: * - * <b>def</b> from(n: Int): Stream[Int] = - * Stream.cons(n, from(n + 1)) + * {{{ + * object Main extends Application { * - * <b>def</b> sieve(s: Stream[Int]): Stream[Int] = - * Stream.cons(s.head, sieve(s.tail filter { _ % s.head != 0 })) + * def from(n: Int): Stream[Int] = + * Stream.cons(n, from(n + 1)) * - * <b>def</b> primes = sieve(from(2)) + * def sieve(s: Stream[Int]): Stream[Int] = + * Stream.cons(s.head, sieve(s.tail filter { _ % s.head != 0 })) * - * primes take 10 print - * } - * </pre> + * def primes = sieve(from(2)) * - * @author Martin Odersky, Matthias Zenger - * @version 1.1 08/08/03 - * @since 2.8 + * primes take 10 print + * } + * }}} + * + * @tparam A the type of the elements contained in this stream. + * + * @author Martin Odersky, Matthias Zenger + * @version 1.1 08/08/03 + * @since 2.8 + * @define Coll Stream + * @define coll stream + * @define orderDependent + * @define orderDependentFold */ abstract class Stream[+A] extends LinearSeq[A] with GenericTraversableTemplate[A, Stream] @@ -68,6 +74,7 @@ self => /** The stream resulting from the concatenation of this stream with the argument stream. * @param rest The stream that gets appended to this stream + * @return The stream containing elements of this stream and the traversable object. */ def append[B >: A](rest: => Traversable[B]): Stream[B] = if (isEmpty) rest.toStream else new Stream.Cons(head, tail append rest) @@ -82,7 +89,7 @@ self => /** Prints elements of this stream one by one, separated by commas. */ def print() { print(", ") } - /** Prints elements of this stream one by one, separated by <code>sep</code>. + /** Prints elements of this stream one by one, separated by `sep`. * @param sep The separator string printed between consecutive elements. */ def print(sep: String) { @@ -138,7 +145,7 @@ self => ) /** Returns the stream resulting from applying the given function - * <code>f</code> to each element of this stream. + * `f` to each element of this stream. * * @param f function to apply to each element. * @return <code>f(a<sub>0</sub>), ..., f(a<sub>n</sub>)</code> if this @@ -150,10 +157,11 @@ self => else new Stream.Cons(f(head), asStream[B](tail map f)) ) - /** Applies the given function <code>f</code> to each element of + /** Applies the given function `f` to each element of * this stream, then concatenates the results. * - * @param f the function to apply on each element. + * @param f the function to apply on each element. + * @param bf $bfinfo * @return <code>f(a<sub>0</sub>) ::: ... ::: f(a<sub>n</sub>)</code> if * this stream is <code>[a<sub>0</sub>, ..., a<sub>n</sub>]</code>. */ diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala index 8068267dd2..f12ddebd08 100644 --- a/src/library/scala/collection/immutable/StringLike.scala +++ b/src/library/scala/collection/immutable/StringLike.scala @@ -17,8 +17,8 @@ import mutable.Builder import scala.util.matching.Regex import scala.math.ScalaNumber -/** - * @since 2.8 +/** A companion object for the `StringLike` containing some constants. + * @since 2.8 */ object StringLike { @@ -31,8 +31,17 @@ object StringLike { import StringLike._ -/** - * @since 2.8 +/** A trait describing stringlike collections. + * + * @tparam Repr The type of the actual collection inheriting `StringLike`. + * + * @since 2.8 + * @define Coll String + * @define coll string + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ trait StringLike[+Repr] extends IndexedSeqOptimized[Char, Repr] with Ordered[String] { self => @@ -62,15 +71,15 @@ self => private def isLineBreak(c: Char) = c == LF || c == FF /** - * Strip trailing line end character from this string if it has one. + * Strip trailing line end character from this string if it has one. * - * A line end character is one of - * <ul style="list-style-type: none;"> - * <li>LF - line feed (0x0A hex)</li> - * <li>FF - form feed (0x0C hex)</li> - * </ul> - * If a line feed character LF is preceded by a carriage return CR - * (0x0D hex), the CR character is also stripped (Windows convention). + * A line end character is one of + * <ul style="list-style-type: none;"> + * <li>LF - line feed (0x0A hex)</li> + * <li>FF - form feed (0x0C hex)</li> + * </ul> + * If a line feed character LF is preceded by a carriage return CR + * (0x0D hex), the CR character is also stripped (Windows convention). */ def stripLineEnd: String = { val len = toString.length @@ -112,15 +121,15 @@ self => } /** Return all lines in this string in an iterator, excluding trailing line - * end characters, i.e. apply <code>.stripLineEnd</code> to all lines - * returned by <code>linesWithSeparators</code>. + * end characters, i.e. apply `.stripLineEnd` to all lines + * returned by `linesWithSeparators`. */ def lines: Iterator[String] = linesWithSeparators map (line => new WrappedString(line).stripLineEnd) /** Return all lines in this string in an iterator, excluding trailing line - * end characters, i.e. apply <code>.stripLineEnd</code> to all lines - * returned by <code>linesWithSeparators</code>. + * end characters, i.e. apply `.stripLineEnd` to all lines + * returned by `linesWithSeparators`. */ def linesIterator: Iterator[String] = linesWithSeparators map (line => new WrappedString(line).stripLineEnd) @@ -135,12 +144,12 @@ self => new String(chars) } - /** Returns this string with the given <code>prefix</code> stripped. */ + /** Returns this string with the given `prefix` stripped. */ def stripPrefix(prefix: String) = if (toString.startsWith(prefix)) toString.substring(prefix.length) else toString - /** Returns this string with the given <code>suffix</code> stripped. */ + /** Returns this string with the given `suffix` stripped. */ def stripSuffix(suffix: String) = if (toString.endsWith(suffix)) toString.substring(0, toString.length() - suffix.length) else toString @@ -150,7 +159,7 @@ self => * * <blockquote> * Strip a leading prefix consisting of blanks or control characters - * followed by <code>marginChar</code> from the line. + * followed by `marginChar` from the line. * </blockquote> */ def stripMargin(marginChar: Char): String = { @@ -170,7 +179,7 @@ self => * * <blockquote> * Strip a leading prefix consisting of blanks or control characters - * followed by <code>|</code> from the line. + * followed by `|` from the line. * </blockquote> */ def stripMargin: String = stripMargin('|') @@ -230,7 +239,7 @@ self => * * The interpretation of the formatting patterns is described in * <a href="" target="contentFrame" class="java/util/Formatter"> - * <code>java.util.Formatter</code></a>, with the addition that + * `java.util.Formatter`</a>, with the addition that * classes deriving from `ScalaNumber` (such as `scala.BigInt` and * `scala.BigDecimal`) are unwrapped to pass a type which `Formatter` * understands. @@ -249,7 +258,7 @@ self => * * The interpretation of the formatting patterns is described in * <a href="" target="contentFrame" class="java/util/Formatter"> - * <code>java.util.Formatter</code></a>, with the addition that + * `java.util.Formatter`</a>, with the addition that * classes deriving from `ScalaNumber` (such as `scala.BigInt` and * `scala.BigDecimal`) are unwrapped to pass a type which `Formatter` * understands. diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala index 4949eb7056..2bdbf672cd 100644 --- a/src/library/scala/collection/immutable/StringOps.scala +++ b/src/library/scala/collection/immutable/StringOps.scala @@ -15,15 +15,19 @@ package immutable import mutable.StringBuilder /** - * This class serves as a wrapper providing `String`s with all the operations - * found in indexed sequences. Where needed, instances of `String` object - * are implicitly converted into this class. + * This class serves as a wrapper providing `String`s with all the operations + * found in indexed sequences. Where needed, instances of `String` object + * are implicitly converted into this class. * - * The difference between this class and `WrappedString` is that calling transformer - * methods such as `filter` and `map` will yield a `String` object, whereas a - * `WrappedString` will remain a `WrappedString`. + * The difference between this class and `WrappedString` is that calling transformer + * methods such as `filter` and `map` will yield a `String` object, whereas a + * `WrappedString` will remain a `WrappedString`. * - * @since 2.8 + * @param repr the actual representation of this string operations object. + * + * @since 2.8 + * @define Coll StringOps + * @define coll string */ final class StringOps(override val repr: String) extends StringLike[String] { diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala index af7f6979c9..61a7f3ebd1 100644 --- a/src/library/scala/collection/immutable/Traversable.scala +++ b/src/library/scala/collection/immutable/Traversable.scala @@ -26,11 +26,9 @@ trait Traversable[+A] extends scala.collection.Traversable[A] override def companion: GenericCompanion[Traversable] = Traversable } -/** A factory object for the trait <code>Traversable</code>. - * - * @author Martin Odersky - * @version 2.8 - * @since 2.8 +/** $factoryInfo + * @define Coll immutable.Travesable + * @define coll immutable traversable object */ object Traversable extends TraversableFactory[Traversable] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A] diff --git a/src/library/scala/collection/immutable/TreeMap.scala b/src/library/scala/collection/immutable/TreeMap.scala index bd04b8d2e2..61cfe2e13b 100644 --- a/src/library/scala/collection/immutable/TreeMap.scala +++ b/src/library/scala/collection/immutable/TreeMap.scala @@ -15,22 +15,33 @@ package immutable import generic._ import mutable.Builder -/** The canonical factory of <a href="TreeMap.html">TreeMap</a>'s. - * - * @since 1 +/** $factoryInfo + * @define Coll immutable.TreeMap + * @define coll immutable tree map */ object TreeMap extends ImmutableSortedMapFactory[TreeMap] { def empty[A, B](implicit ord: Ordering[A]) = new TreeMap[A, B]()(ord) + /** $sortedMapCanBuildFromInfo */ implicit def canBuildFrom[A, B](implicit ord: Ordering[A]): CanBuildFrom[Coll, (A, B), TreeMap[A, B]] = new SortedMapCanBuildFrom[A, B] private def make[A, B](s: Int, t: RedBlack[A]#Tree[B])(implicit ord: Ordering[A]) = new TreeMap[A, B](s, t)(ord) } /** This class implements immutable maps using a tree. * + * @tparam A the type of the keys contained in this tree map. + * @tparam B the type of the values associated with the keys. + * @param ordering the implicit ordering used to compare objects of type `A`. + * * @author Erik Stenman * @author Matthias Zenger * @version 1.1, 03/05/2004 * @since 1 + * @define Coll immutable.TreeMap + * @define coll immutable tree map + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit val ordering: Ordering[A]) @@ -65,18 +76,20 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va * if key is <em>not</em> in the TreeMap, otherwise * the key is updated with the new entry. * - * @param key ... - * @param value ... - * @return ... + * @tparam B1 type of the value of the new binding which is a supertype of `B` + * @param key the key that should be updated + * @param value the value to be associated with `key` + * @return a new $coll with the updated binding */ override def updated [B1 >: B](key: A, value: B1): TreeMap[A, B1] = { val newsize = if (tree.lookup(key).isEmpty) size + 1 else size TreeMap.make(newsize, tree.update(key, value)) } - /** Add a key/value pair to this map. - * @param kv the key/value pair - * @return A new map with the new binding added to this map + /** Add a key/value pair to this map. + * @tparam B1 type of the value of the new binding, a supertype of `B` + * @param kv the key/value pair + * @return A new $coll with the new binding added to this map */ override def + [B1 >: B] (kv: (A, B1)): TreeMap[A, B1] = updated(kv._1, kv._2) @@ -84,15 +97,22 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va * either the collection itself (if it is mutable), or a new collection * with the added elements. * + * @tparam B1 type of the values of the new bindings, a supertype of `B` * @param elem1 the first element to add. * @param elem2 the second element to add. * @param elems the remaining elements to add. + * @return a new $coll with the updated bindings */ override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): TreeMap[A, B1] = this + elem1 + elem2 ++ elems /** A new TreeMap with the entry added is returned, * assuming that key is <em>not</em> in the TreeMap. + * + * @tparam B1 type of the values of the new bindings, a supertype of `B` + * @param key the key to be inserted + * @param value the value to be associated with `key` + * @return a new $coll with the inserted binding, if it wasn't present in the map */ def insert [B1 >: B](key: A, value: B1): TreeMap[A, B1] = { assert(tree.lookup(key).isEmpty) @@ -103,11 +123,11 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va if (tree.lookup(key).isEmpty) this else TreeMap.make(size - 1, tree.delete(key)) - /** Check if this map maps <code>key</code> to a value and return the + /** Check if this map maps `key` to a value and return the * value if it exists. * * @param key the key of the mapping of interest - * @return the value of the mapping, if it exists + * @return the value of the mapping, if it exists */ override def get(key: A): Option[B] = tree.lookup(key) match { case n: NonEmpty[b] => Some(n.value) diff --git a/src/library/scala/collection/immutable/TreeSet.scala b/src/library/scala/collection/immutable/TreeSet.scala index 79e1a6b00b..7b1f71df5b 100644 --- a/src/library/scala/collection/immutable/TreeSet.scala +++ b/src/library/scala/collection/immutable/TreeSet.scala @@ -15,11 +15,11 @@ package immutable import generic._ import mutable.{Builder, AddingBuilder} -/** The canonical factory of <a href="TreeSet.html">TreeSet</a>'s. - * - * @since 1 +/** $factoryInfo + * @define Coll immutable.TreeSet + * @define coll immutable tree set */ -object TreeSet extends SortedSetFactory[TreeSet] { +object TreeSet extends ImmutableSortedSetFactory[TreeSet] { implicit def implicitBuilder[A](implicit ordering: Ordering[A]): Builder[A, TreeSet[A]] = newBuilder[A](ordering) override def newBuilder[A](implicit ordering: Ordering[A]): Builder[A, TreeSet[A]] = new AddingBuilder(empty[A](ordering)) @@ -31,9 +31,18 @@ object TreeSet extends SortedSetFactory[TreeSet] { /** This class implements immutable sets using a tree. * + * @tparam A the type of the elements contained in this tree set + * @param ordering the implicit ordering used to compare objects of type `A` + * * @author Martin Odersky * @version 2.0, 02/01/2007 * @since 1 + * @define Coll immutable.TreeSet + * @define coll immutable tree set + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(-234066569443569402L) class TreeSet[A](override val size: Int, t: RedBlack[A]#Tree[Unit]) @@ -54,29 +63,40 @@ class TreeSet[A](override val size: Int, t: RedBlack[A]#Tree[Unit]) */ override def empty = TreeSet.empty - /** A new TreeSet with the entry added is returned, + /** Creates a new `TreeSet` with the entry added. + * + * @param elem a new element to add. + * @return a new $coll containing `elem` and all the elements of this $coll. */ def + (elem: A): TreeSet[A] = { val newsize = if (tree.lookup(elem).isEmpty) size + 1 else size newSet(newsize, tree.update(elem, ())) } - /** A new TreeSet with the entry added is returned, + /** A new `TreeSet` with the entry added is returned, * assuming that elem is <em>not</em> in the TreeSet. + * + * @param elem a new element to add. + * @return a new $coll containing `elem` and all the elements of this $coll. */ def insert(elem: A): TreeSet[A] = { assert(tree.lookup(elem).isEmpty) newSet(size + 1, tree.update(elem, ())) } + /** Creates a new `TreeSet` with the entry removed. + * + * @param elem a new element to add. + * @return a new $coll containing all the elements of this $coll except `elem`. + */ def - (elem:A): TreeSet[A] = if (tree.lookup(elem).isEmpty) this else newSet(size - 1, tree delete elem) - /** Checks if this set contains element <code>elem</code>. + /** Checks if this set contains element `elem`. * * @param elem the element to check for membership. - * @return true, iff <code>elem</code> is contained in this set. + * @return true, iff `elem` is contained in this set. */ def contains(elem: A): Boolean = !tree.lookup(elem).isEmpty diff --git a/src/library/scala/collection/immutable/WrappedString.scala b/src/library/scala/collection/immutable/WrappedString.scala index cefbd96b5c..011774e10d 100644 --- a/src/library/scala/collection/immutable/WrappedString.scala +++ b/src/library/scala/collection/immutable/WrappedString.scala @@ -17,14 +17,18 @@ import mutable.{Builder, StringBuilder} import scala.util.matching.Regex /** - * This class serves as a wrapper augmenting `String`s with all the operations - * found in indexed sequences. + * This class serves as a wrapper augmenting `String`s with all the operations + * found in indexed sequences. * - * The difference between this class and `StringOps` is that calling transformer - * methods such as `filter` and `map` will yield an object of type `WrappedString` - * rather than a `String`. + * The difference between this class and `StringOps` is that calling transformer + * methods such as `filter` and `map` will yield an object of type `WrappedString` + * rather than a `String`. * - * @since 2.8 + * @param self a string contained within this wrapped string + * + * @since 2.8 + * @define Coll WrappedString + * @define coll wrapped string */ class WrappedString(override val self: String) extends IndexedSeq[Char] with StringLike[WrappedString] with Proxy { @@ -38,8 +42,9 @@ class WrappedString(override val self: String) extends IndexedSeq[Char] with Str new WrappedString(self.substring(from max 0, until min self.length)) } -/** - * @since 2.8 +/** A companion object for wrapped strings. + * + * @since 2.8 */ object WrappedString { def newBuilder: Builder[Char, WrappedString] = new StringBuilder() mapResult (new WrappedString(_)) |