From f8d6814bb4fb0248d6121335e67eee8fde7ce455 Mon Sep 17 00:00:00 2001 From: Stefan Zeiger Date: Tue, 2 Feb 2016 20:07:08 +0100 Subject: SI-9624 Improve documentation for TraversableOnce - Move the doc comment for `hasDefiniteSize` up from TraversableLike to GenTraversableOnce and improve it. - Add a note to `GenTraversableOnce.isEmpty` that implementations must not consume elements. - Clarify alternatives to subclassing TraversableOnce. --- .../scala/collection/GenTraversableOnce.scala | 20 ++++++++++++++++++++ src/library/scala/collection/TraversableLike.scala | 11 ----------- src/library/scala/collection/TraversableOnce.scala | 9 +++++---- 3 files changed, 25 insertions(+), 15 deletions(-) diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala index 244ff26397..4af2ca23be 100644 --- a/src/library/scala/collection/GenTraversableOnce.scala +++ b/src/library/scala/collection/GenTraversableOnce.scala @@ -67,6 +67,23 @@ trait GenTraversableOnce[+A] extends Any { */ def foreach[U](f: A => U): Unit + /** Tests whether this $coll is known to have a finite size. + * All strict collections are known to have finite size. For a non-strict + * collection such as `Stream`, the predicate returns `'''true'''` if all + * elements have been computed. It returns `'''false'''` if the stream is + * not yet evaluated to the end. Non-empty Iterators usually return + * `'''false'''` even if they were created from a collection with a known + * finite size. + * + * Note: many collection methods will not work on collections of infinite sizes. + * The typical failure mode is an infinite loop. These methods always attempt a + * traversal without checking first that `hasDefiniteSize` returns `'''true'''`. + * However, checking `hasDefiniteSize` can provide an assurance that size is + * well-defined and non-termination is not a concern. + * + * @return `'''true'''` if this collection is known to have finite size, + * `'''false'''` otherwise. + */ def hasDefiniteSize: Boolean def seq: TraversableOnce[A] @@ -80,6 +97,9 @@ trait GenTraversableOnce[+A] extends Any { def size: Int /** Tests whether the $coll is empty. + * + * Note: Implementations in subclasses that are not repeatedly traversable must take + * care not to consume any elements when `isEmpty` is called. * * @return `true` if the $coll contains no elements, `false` otherwise. */ diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index bd1be84e97..bbbc33b3f5 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -138,17 +138,6 @@ trait TraversableLike[+A, +Repr] extends Any result } - /** Tests whether this $coll is known to have a finite size. - * All strict collections are known to have finite size. For a non-strict - * collection such as `Stream`, the predicate returns `'''true'''` if all - * elements have been computed. It returns `'''false'''` if the stream is - * not yet evaluated to the end. - * - * Note: many collection methods will not work on collections of infinite sizes. - * - * @return `'''true'''` if this collection is known to have finite size, - * `'''false'''` otherwise. - */ def hasDefiniteSize = true def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala index 910c59b179..75c0d82922 100644 --- a/src/library/scala/collection/TraversableOnce.scala +++ b/src/library/scala/collection/TraversableOnce.scala @@ -38,9 +38,10 @@ import scala.reflect.ClassTag * `Traversables`, such as folds, conversions, and other operations which * traverse some or all of the elements and return a derived value. * Directly subclassing `TraversableOnce` is not recommended - instead, - * consider declaring an `Iterator` with a `next` and `hasNext` method, - * creating an `Iterator` with one of the methods on the `Iterator` object, - * or declaring a subclass of `Traversable`. + * consider declaring an `Iterator` with a `next` and `hasNext` method or + * creating an `Iterator` with one of the methods on the `Iterator` object. + * Consider declaring a subclass of `Traversable` instead if the elements + * can be traversed repeatedly. * * @define coll traversable or iterator * @define orderDependent @@ -61,8 +62,8 @@ import scala.reflect.ClassTag trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] { self => + //TODO 2.12: Remove these methods. They are already defined in GenTraversableOnce /* Self-documenting abstract methods. */ - def foreach[U](f: A => U): Unit def isEmpty: Boolean def hasDefiniteSize: Boolean -- cgit v1.2.3