diff options
Diffstat (limited to 'src/library/scalax/collection/generic/IterableTemplate.scala')
-rwxr-xr-x | src/library/scalax/collection/generic/IterableTemplate.scala | 110 |
1 files changed, 51 insertions, 59 deletions
diff --git a/src/library/scalax/collection/generic/IterableTemplate.scala b/src/library/scalax/collection/generic/IterableTemplate.scala index 01a23f5ecf..e5e22aa7c8 100755 --- a/src/library/scalax/collection/generic/IterableTemplate.scala +++ b/src/library/scalax/collection/generic/IterableTemplate.scala @@ -12,7 +12,7 @@ package scalax.collection.generic import scalax.collection.mutable.{Buffer, ArrayBuffer, ListBuffer} -import scalax.collection.immutable.{List, Nil, ::} +import scalax.collection.immutable.{List, Nil, ::, Stream} import util.control.Break._ import Iterable._ @@ -65,7 +65,7 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], */ def hasDefiniteSize = true - /** Create a new sequence of type CC which contains all elements of this sequence + /** Create a new iterable of type CC which contains all elements of this iterable * followed by all elements of Iterable `that' */ def ++[B >: A](that: Iterable[B]): CC[B] = { @@ -75,7 +75,7 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], b.result } - /** Create a new sequence of type IterableType which contains all elements of this sequence + /** Create a new iterable of type CC which contains all elements of this iterable * followed by all elements of Iterator `that' */ def ++[B >: A](that: Iterator[B]): CC[B] = { @@ -85,12 +85,12 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], b.result } - /** Returns the sequence resulting from applying the given function - * <code>f</code> to each element of this sequence. + /** Returns the iterable resulting from applying the given function + * <code>f</code> to each element of this iterable. * * @param f function to apply to each element. * @return <code>f(a<sub>0</sub>), ..., f(a<sub>n</sub>)</code> if this - * sequence is <code>a<sub>0</sub>, ..., a<sub>n</sub></code>. + * iterable is <code>a<sub>0</sub>, ..., a<sub>n</sub></code>. */ def map[B](f: A => B): CC[B] = { val b = newBuilder[B] @@ -99,11 +99,11 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], } /** Applies the given function <code>f</code> to each element of - * this sequence, then concatenates the results. + * this iterable, then concatenates the results. * * @param f the function to apply on each element. * @return <code>f(a<sub>0</sub>) ::: ... ::: f(a<sub>n</sub>)</code> if - * this sequence is <code>a<sub>0</sub>, ..., a<sub>n</sub></code>. + * this iterable is <code>a<sub>0</sub>, ..., a<sub>n</sub></code>. */ def flatMap[B](f: A => Iterable[B]): CC[B] = { val b = newBuilder[B] @@ -111,10 +111,10 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], b.result } - /** Returns all the elements of this sequence that satisfy the + /** Returns all the elements of this iterable that satisfy the * predicate <code>p</code>. The order of the elements is preserved. - * @param p the predicate used to filter the list. - * @return the elements of this list satisfying <code>p</code>. + * @param p the predicate used to filter the iterable. + * @return the elements of this iterable satisfying <code>p</code>. */ def filter(p: A => Boolean): CC[A] = { val b = newBuilder[A] @@ -128,7 +128,7 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], * predicate inversed. * * @param p the predicate to use to test elements - * @return the list without all elements which satisfy <code>p</code> + * @return the iterable without all elements which satisfy <code>p</code> */ def remove(p: A => Boolean): CC[A] = filter(!p(_)) @@ -203,6 +203,8 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], * predicate, if any. * * @note may not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. * @param p the predicate * @return an option containing the first element in the iterable object * satisfying <code>p</code>, or <code>None</code> if none exists. @@ -221,8 +223,10 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], * the value <code>z</code>. * * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. * @return <code>f(... (f(f(z, a<sub>0</sub>), a<sub>1</sub>) ...), - * a<sub>n</sub>)</code> if the list is + * a<sub>n</sub>)</code> if the iterable is * <code>[a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>]</code>. */ def foldLeft[B](z: B)(op: (B, A) => B): B = { @@ -232,32 +236,40 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], result } - /** Combines the elements of this list together using the binary + /** Combines the elements of this iterable together using the binary * function <code>f</code>, from right to left, and starting with * the value <code>z</code>. * * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. * @return <code>f(a<sub>0</sub>, f(a<sub>1</sub>, f(..., f(a<sub>n</sub>, z)...)))</code> - * if the list is <code>[a<sub>0</sub>, a1, ..., a<sub>n</sub>]</code>. + * if the iterable is <code>[a<sub>0</sub>, a1, ..., a<sub>n</sub>]</code>. */ def foldRight[B](z: B)(op: (A, B) => B): B = elements.foldRight(z)(op) /** Similar to <code>foldLeft</code> but can be used as - * an operator with the order of list and zero arguments reversed. + * an operator with the order of iterable and zero arguments reversed. * That is, <code>z /: xs</code> is the same as <code>xs foldLeft z</code> * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. */ def /: [B](z: B)(op: (B, A) => B): B = foldLeft(z)(op) /** An alias for <code>foldRight</code>. * That is, <code>xs :\ z</code> is the same as <code>xs foldRight z</code> * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. */ def :\ [B](z: B)(op: (A, B) => B): B = foldRight(z)(op) /** Combines the elements of this iterable object together using the binary * operator <code>op</code>, from left to right * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. * @param op The operator to apply * @return <code>op(... op(a<sub>0</sub>,a<sub>1</sub>), ..., a<sub>n</sub>)</code> if the iterable object has elements @@ -277,6 +289,8 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], /** Combines the elements of this iterable object together using the binary * operator <code>op</code>, from right to left * @note Will not terminate for infinite-sized collections. + * @note Might return different results for different runs, unless this iterable is ordered, or + * the operator is associative and commutative. * @param op The operator to apply * * @return <code>a<sub>0</sub> op (... op (a<sub>n-1</sub> op a<sub>n</sub>)...)</code> @@ -288,7 +302,7 @@ trait IterableTemplate[+CC[/*+*/B] <: IterableTemplate[CC, B] with Iterable[B], def reduceRight[B >: A](op: (A, B) => B): B = elements.reduceRight(op) - /** Returns an iterable formed from this iterable and the specified list + /** Returns an iterable formed from this iterable and the specified iterable * `other` by associating each element of the former with * the element at the same position in the latter. * If one of the two iterables is longer than the other, its remaining elements are ignored. @@ -356,7 +370,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the } /** Fills the given array <code>xs</code> with at most `len` elements of - * this sequence starting at position `start`. + * this iterable starting at position `start`. * Copying will stop oce either the end of the current iterable is reached or * `len` elements have been copied. * @@ -378,7 +392,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the } /** Fills the given array <code>xs</code> with the elements of - * this sequence starting at position <code>start</code> + * this iterable starting at position <code>start</code> * until either the end of the current iterable or the end of array `xs` is reached. * * @note Will not terminate for infinite-sized collections. @@ -411,7 +425,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * Returns a sequence containing all of the elements in this iterable object. * @note Will not terminate for infinite-sized collections. */ - def toSequence: Sequence[A] = toList.asInstanceOf[Sequence[A]] // !!! + def toSequence: Sequence[A] = toList /** @deprecated use toSequence instead */ @@ -431,7 +445,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * same order in the sorted iterable as in the original. * * @param lt the comparison function - * @return a list sorted according to the comparison function + * @return a iterable sorted according to the comparison function * <code><(e1: a, e2: a) => Boolean</code>. * @ex <pre> * List("Steve", "Tom", "John", "Bob") @@ -454,7 +468,6 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * <code>sep</code>. * * @ex <code>List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"</code> - * @note Will not terminate for infinite-sized collections. * @param start starting string. * @param sep separator string. * @param end ending string. @@ -467,7 +480,6 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * representations of elements (w.r.t. the method <code>toString()</code>) * are separated by the string <code>sep</code>. * - * @note Will not terminate for infinite-sized collections. * @param sep separator string. * @return a string representation of this iterable object. */ @@ -475,7 +487,6 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the addString(new StringBuilder(), sep).toString /** Converts a collection into a flat <code>String</code> by each element's toString method. - * @note Will not terminate for infinite-sized collections. */ def mkString = addString(new StringBuilder()).toString @@ -485,7 +496,6 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * <code>end</code>. Inside, the string representations of elements (w.r.t. * the method <code>toString()</code>) are separated by the string * <code>sep</code>. - * @note Will not terminate for infinite-sized collections. */ def addString(b: StringBuilder, start: String, sep: String, end: String): StringBuilder = { b append start @@ -501,28 +511,13 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the /** Write all elements of this string into given string builder. * The string representations of elements (w.r.t. the method <code>toString()</code>) * are separated by the string <code>sep</code>. - * @note Will not terminate for infinite-sized collections. */ - def addString(b: StringBuilder, sep: String): StringBuilder = { - var first = true - for (x <- this) { - if (first) first = false - else b append sep - b append x - } - b - } + def addString(b: StringBuilder, sep: String): StringBuilder = addString(b, "", sep, "") /** Write all elements of this string into given string builder without using * any separator between consecutive elements. - * @note Will not terminate for infinite-sized collections. */ - def addString(b: StringBuilder): StringBuilder = { - for (x <- this) { - b append x - } - b - } + def addString(b: StringBuilder): StringBuilder = addString(b, "") /** * returns a projection that can be used to call non-strict <code>filter</code>, @@ -557,10 +552,10 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the // The following methods return non-deterministic results, unless this iterable is an OrderedIterable - /** The first element of this sequence. + /** The first element of this iterable. * * @note Might return different results for different runs, unless this iterable is ordered - * @throws Predef.NoSuchAentException if the sequence is empty. + * @throws Predef.NoSuchElementException if the iterable is empty. */ def head: A = if (isEmpty) throw new NoSuchElementException else elements.next @@ -574,7 +569,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the def headOption: Option[A] = if (isEmpty) None else Some(head) /** @deprecated use headOption instead - * <code>None</code> if list is empty. + * <code>None</code> if iterable is empty. */ @deprecated def firstOption: Option[A] = headOption @@ -589,7 +584,6 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the * than <code>n</code> elements. * * @param n the number of elements to take - * @return a possibly projected sequence * @note Might return different results for different runs, unless this iterable is ordered */ def take(n: Int): CC[A] = { @@ -650,7 +644,7 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the /** The last element of this iterable. * - * @throws Predef.NoSuchElementException if the sequence is empty. + * @throws Predef.NoSuchElementException if the iterable is empty. * @note Might return different results for different runs, unless this iterable is ordered */ def last: A = { @@ -669,9 +663,11 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the def lastOption: Option[A] = if (isEmpty) None else Some(last) /** An iterable consisting of all elements of this iterable except the last one. + * @throws Predef.UnsupportedOperationException if the stream is empty. * @note Might return different results for different runs, unless this iterable is ordered */ def init: CC[A] = { + if (isEmpty) throw new UnsupportedOperationException("empty.init") var lst = head val b = newBuilder[A] for (x <- this) { @@ -732,12 +728,10 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the (l.result, r.result) } - /** Returns the longest prefix of this sequence whose elements satisfy + /** Returns the longest prefix of this iterable whose elements satisfy * the predicate <code>p</code>. * * @param p the test predicate. - * @return the longest prefix of this sequence whose elements satisfy - * the predicate <code>p</code>. * @note Might return different results for different runs, unless this iterable is ordered */ def takeWhile(p: A => Boolean): CC[A] = { @@ -751,12 +745,10 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the b.result } - /** Returns the longest suffix of this sequence whose first element + /** Returns the longest suffix of this iterable whose first element * does not satisfy the predicate <code>p</code>. * * @param p the test predicate. - * @return the longest suffix of the sequence whose first element - * does not satisfy the predicate <code>p</code>. * @note Might return different results for different runs, unless this iterable is ordered */ def dropWhile(p: A => Boolean): CC[A] = { @@ -769,12 +761,12 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the b.result } - /** Returns a pair consisting of the longest prefix of the list whose - * elements all satisfy the given predicate, and the rest of the list. + /** Returns a pair consisting of the longest prefix of the iterable whose + * elements all satisfy the given predicate, and the rest of the iterable. * * @param p the test predicate - * @return a pair consisting of the longest prefix of the list whose - * elements all satisfy <code>p</code>, and the rest of the list. + * @return a pair consisting of the longest prefix of the iterable whose + * elements all satisfy <code>p</code>, and the rest of the iterable. * @note Might return different results for different runs, unless this iterable is ordered */ def span(p: A => Boolean): (CC[A], CC[A]) = { @@ -801,13 +793,13 @@ b * @param thatElem element <code>thatElem</code> is used to fill up the !these.hasNext && !those.hasNext } - /** A sub-sequence view starting at index `from` + /** A sub-iterable view starting at index `from` * and extending up to (but not including) index `until`. * * @param from The index of the first element of the slice * @param until The index of the element following the slice * @note The difference between `view` and `slice` is that `view` produces - * a view of the current sequence, whereas `slice` produces a new sequence. + * a view of the current iterable, whereas `slice` produces a new iterable. * * @note Might return different results for different runs, unless this iterable is ordered * @note view(from, to) is equivalent to view.slice(from, to) |