Merge pull request scala#7805 from NthPortal/topic/sizeCompare-tweaks

Clean up length/size comparison methods

Author: lrytz

src/library/scala/collection/ArrayOps.scala

@@ -239,6 +239,18 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
     */
   def lastOption: Option[A] = if(isEmpty) None else Some(last)
 
+  /** Compares the size of this array to a test value.
+    *
+    *   @param   otherSize the test value that gets compared with the size.
+    *   @return  A value `x` where
+    *   {{{
+    *        x <  0       if this.size <  otherSize
+    *        x == 0       if this.size == otherSize
+    *        x >  0       if this.size >  otherSize
+    *   }}}
+    */
+  def sizeCompare(otherSize: Int): Int = Integer.compare(xs.length, otherSize)
+
   /** Compares the length of this array to a test value.
     *
     *   @param   len   the test value that gets compared with the length.
@@ -251,6 +263,40 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
     */
   def lengthCompare(len: Int): Int = Integer.compare(xs.length, len)
 
+  /** Method mirroring [[SeqOps.sizeIs]] for consistency, except it returns an `Int`
+    * because `size` is known and comparison is constant-time.
+    *
+    * These operations are equivalent to [[sizeCompare(Int) `sizeCompare(Int)`]], and
+    * allow the following more readable usages:
+    *
+    * {{{
+    * this.sizeIs < size     // this.sizeCompare(size) < 0
+    * this.sizeIs <= size    // this.sizeCompare(size) <= 0
+    * this.sizeIs == size    // this.sizeCompare(size) == 0
+    * this.sizeIs != size    // this.sizeCompare(size) != 0
+    * this.sizeIs >= size    // this.sizeCompare(size) >= 0
+    * this.sizeIs > size     // this.sizeCompare(size) > 0
+    * }}}
+    */
+  def sizeIs: Int = xs.length
+
+  /** Method mirroring [[SeqOps.lengthIs]] for consistency, except it returns an `Int`
+    * because `length` is known and comparison is constant-time.
+    *
+    * These operations are equivalent to [[lengthCompare(Int) `lengthCompare(Int)`]], and
+    * allow the following more readable usages:
+    *
+    * {{{
+    * this.lengthIs < len     // this.lengthCompare(len) < 0
+    * this.lengthIs <= len    // this.lengthCompare(len) <= 0
+    * this.lengthIs == len    // this.lengthCompare(len) == 0
+    * this.lengthIs != len    // this.lengthCompare(len) != 0
+    * this.lengthIs >= len    // this.lengthCompare(len) >= 0
+    * this.lengthIs > len     // this.lengthCompare(len) > 0
+    * }}}
+    */
+  def lengthIs: Int = xs.length
+
   /** Selects an interval of elements. The returned array is made up
     * of all elements `x` which satisfy the invariant:
     * {{{

src/library/scala/collection/IndexedSeq.scala

@@ -72,7 +72,7 @@ trait IndexedSeqOps[+A, +CC[_], +C] extends Any with SeqOps[A, CC, C] { self =>
 
   override def knownSize: Int = length
 
-  override final def sizeCompare(that: Iterable[_]): Int = {
+  override final def lengthCompare(that: Iterable[_]): Int = {
     val res = that.sizeCompare(length)
     // can't just invert the result, because `-Int.MinValue == Int.MinValue`
     if (res == Int.MinValue) 1 else -res

src/library/scala/collection/Iterable.scala

@@ -258,9 +258,12 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
     *        x == 0       if this.size == otherSize
     *        x >  0       if this.size >  otherSize
     *   }}}
+    *
     *  The method as implemented here does not call `size` directly; its running time
-    *  is `O(size min _size)` instead of `O(size)`. The method should be overwritten
-    *  if computing `size` is cheap.
+    *  is `O(size min otherSize)` instead of `O(size)`. The method should be overridden
+    *  if computing `size` is cheap and `knownSize` returns `-1`.
+    *
+    *  @see [[sizeIs]]
     */
   def sizeCompare(otherSize: Int): Int = {
     if (otherSize < 0) 1
@@ -299,14 +302,16 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   /** Compares the size of this $coll to the size of another `Iterable`.
     *
     *   @param   that the `Iterable` whose size is compared with this $coll's size.
+    *   @return  A value `x` where
     *   {{{
     *        x <  0       if this.size <  that.size
     *        x == 0       if this.size == that.size
     *        x >  0       if this.size >  that.size
     *   }}}
+    *
     *  The method as implemented here does not call `size` directly; its running time
     *  is `O(this.size min that.size)` instead of `O(this.size + that.size)`.
-    *  The method should be overwritten if computing `size` is cheap.
+    *  The method should be overridden if computing `size` is cheap and `knownSize` returns `-1`.
     */
   def sizeCompare(that: Iterable[_]): Int = {
     val thatKnownSize = that.knownSize

src/library/scala/collection/LinearSeq.scala

@@ -79,7 +79,7 @@ trait LinearSeqOps[+A, +CC[X] <: LinearSeq[X], +C <: LinearSeq[A] with LinearSeq
     else loop(0, coll)
   }
 
-  override def sizeCompare(that: Iterable[_]): Int = {
+  override def lengthCompare(that: Iterable[_]): Int = {
     val thatKnownSize = that.knownSize
 
     if (thatKnownSize >= 0) this lengthCompare thatKnownSize

src/library/scala/collection/Seq.scala

@@ -774,11 +774,30 @@ trait SeqOps[+A, +CC[_], +C] extends Any
     *        x >  0       if this.length >  len
     *   }}}
     *  The method as implemented here does not call `length` directly; its running time
-    *  is `O(length min len)` instead of `O(length)`. The method should be overwritten
-    *  if computing `length` is cheap.
+    *  is `O(length min len)` instead of `O(length)`. The method should be overridden
+    *  if computing `length` is cheap and `knownSize` returns `-1`.
+    *
+    *  @see [[lengthIs]]
     */
   def lengthCompare(len: Int): Int = super.sizeCompare(len)
 
+  override final def sizeCompare(that: Iterable[_]): Int = lengthCompare(that)
+
+  /** Compares the length of this $coll to the size of another `Iterable`.
+    *
+    *   @param   that the `Iterable` whose size is compared with this $coll's length.
+    *   @return  A value `x` where
+    *   {{{
+    *        x <  0       if this.length <  that.size
+    *        x == 0       if this.length == that.size
+    *        x >  0       if this.length >  that.size
+    *   }}}
+    *  The method as implemented here does not call `length` or `size` directly; its running time
+    *  is `O(this.length min that.size)` instead of `O(this.length + that.size)`.
+    *  The method should be overridden if computing `size` is cheap and `knownSize` returns `-1`.
+    */
+  def lengthCompare(that: Iterable[_]): Int = super.sizeCompare(that)
+
   /** Returns a value class containing operations for comparing the length of this $coll to a test value.
     *
     * These operations are implemented in terms of [[lengthCompare(Int) `lengthCompare(Int)`]], and
@@ -969,25 +988,6 @@ trait SeqOps[+A, +CC[_], +C] extends Any
 }
 
 object SeqOps {
-  /** Operations for comparing the length of a collection to a test value.
-    *
-    * These operations are implemented in terms of
-    * [[scala.collection.SeqOps.lengthCompare(Int) `lengthCompare(Int)`]].
-    */
-  final class LengthCompareOps private[SeqOps](val seq: SeqOps[_, AnyConstr, _]) extends AnyVal {
-    /** Tests if the length of the collection is less than some value. */
-    @inline def <(len: Int): Boolean = seq.lengthCompare(len) < 0
-    /** Tests if the length of the collection is less than or equal to some value. */
-    @inline def <=(len: Int): Boolean = seq.lengthCompare(len) <= 0
-    /** Tests if the length of the collection is equal to some value. */
-    @inline def ==(len: Int): Boolean = seq.lengthCompare(len) == 0
-    /** Tests if the length of the collection is not equal to some value. */
-    @inline def !=(len: Int): Boolean = seq.lengthCompare(len) != 0
-    /** Tests if the length of the collection is greater than or equal to some value. */
-    @inline def >=(len: Int): Boolean = seq.lengthCompare(len) >= 0
-    /** Tests if the length of the collection is greater than some value. */
-    @inline def >(len: Int): Boolean = seq.lengthCompare(len) > 0
-  }
 
   // KMP search utilities
 

src/library/scala/collection/StringOps.scala

@@ -168,8 +168,14 @@ final class StringOps(private val s: String) extends AnyVal {
   /** Get the char at the specified index. */
   @`inline` def apply(i: Int): Char = s.charAt(i)
 
+  def sizeCompare(otherSize: Int): Int = Integer.compare(s.length, otherSize)
+
   def lengthCompare(len: Int): Int = Integer.compare(s.length, len)
 
+  def sizeIs: Int = s.length
+
+  def lengthIs: Int = s.length
+
   /** Builds a new collection by applying a function to all chars of this string.
     *
     *  @param f      the function to apply to each char.