Use unsigned arithmetics in Range, instead of Longs.

Previously, `Range` used a number of intermediate operations on
`Long`s to avoid overflow. We can streamline a lot of code by
using unsigned `Int` arithmetics. In particular, there is only 1
division in the initialization path, instead of 3.

Although the fields have not changed, the content of
`numRangeElements` is more strict for overfull ranges. This means
that deserializing an overfull range from a previous version would
not be safe. This is why we bump the SerialVersionUID.

This commit upstreams
scala-js/scala-js@d972218
from Scala.js.

Author: sjrd

library/src/scala/collection/immutable/Range.scala

@@ -57,7 +57,7 @@ import scala.util.hashing.MurmurHash3
  *    '''Note:''' this method does not use builders to construct a new range,
  *         and its complexity is O(1).
  */
-@SerialVersionUID(3L)
+@SerialVersionUID(4L)
 sealed abstract class Range(
   val start: Int,
   val end: Int,
@@ -83,11 +83,6 @@ sealed abstract class Range(
     r.asInstanceOf[S with EfficientSplit]
   }
 
-  private[this] def gap           = end.toLong - start.toLong
-  private[this] def isExact       = gap % step == 0
-  private[this] def hasStub       = isInclusive || !isExact
-  private[this] def longLength    = gap / step + ( if (hasStub) 1 else 0 )
-
   def isInclusive: Boolean
 
   final override val isEmpty: Boolean = (
@@ -97,27 +92,90 @@ sealed abstract class Range(
       (if (step >= 0) start >= end else start <= end)
   )
 
+  if (step == 0) throw new IllegalArgumentException("step cannot be 0.")
+
+  /** Number of elements in this range, if it is non-empty.
+   *
+   *  If the range is empty, `numRangeElements` does not have a meaningful value.
+   *
+   *  Otherwise, `numRangeElements` is interpreted in the range [1, 2^32],
+   *  respecting modular arithmetics wrt. the unsigned interpretation.
+   *  In other words, it is 0 if the mathematical value should be 2^32, and the
+   *  standard unsigned int encoding of the mathematical value otherwise.
+   *
+   *  This interpretation allows to represent all values with the correct
+   *  modular arithmetics, which streamlines the usage sites.
+   */
   private[this] val numRangeElements: Int = {
-    if (step == 0) throw new IllegalArgumentException("step cannot be 0.")
-    else if (isEmpty) 0
-    else {
-      val len = longLength
-      if (len > scala.Int.MaxValue) -1
-      else len.toInt
-    }
+    val stepSign = step >> 31 // if (step >= 0) 0 else -1
+    val gap = ((end - start) ^ stepSign) - stepSign // if (step >= 0) (end - start) else -(end - start)
+    val absStep = (step ^ stepSign) - stepSign // if (step >= 0) step else -step
+
+    /* If `absStep` is a constant 1, `div` collapses to being an alias of
+     * `gap`. Then `absStep * div` also collapses to `gap` and therefore
+     * `absStep * div != gap` constant-folds to `false`.
+     *
+     * Since most ranges are exclusive, that makes `numRangeElements` an alias
+     * of `gap`. Moreover, for exclusive ranges with step 1 and start 0 (which
+     * are the common case), it makes it an alias of `end` and the entire
+     * computation goes away.
+     */
+    val div = Integer.divideUnsigned(gap, absStep)
+    if (isInclusive || (absStep * div != gap)) div + 1 else div
   }
 
-  final def length = if (numRangeElements < 0) fail() else numRangeElements
+  final def length: Int =
+    if (isEmpty) 0
+    else if (numRangeElements > 0) numRangeElements
+    else fail()
+
+  /** Computes the element of this range after `n` steps from `start`.
+   *
+   *  `n` is interpreted as an unsigned integer.
+   *
+   *  If the mathematical result is not within this Range, the result won't
+   *  make sense, but won't error out.
+   */
+  @inline
+  private[this] def locationAfterN(n: Int): Int = {
+    /* If `step >= 0`, we interpret `step * n` as an unsigned multiplication,
+     * and the addition as a mixed `(signed, unsigned) -> signed` operation.
+     * With those interpretation, they do not overflow, assuming the
+     * mathematical result is within this Range.
+     *
+     * If `step < 0`, we should compute `start - (-step * n)`, with the
+     * multiplication also interpreted as unsigned, and the subtraction as
+     * mixed. Again, using those interpretations, they do not overflow.
+     * But then modular arithmetics allow us to cancel out the two `-` signs,
+     * so we end up with the same formula.
+     */
+    start + (step * n)
+  }
 
-  // This field has a sensible value only for non-empty ranges
-  private[this] val lastElement = step match {
-    case 1  => if (isInclusive) end else end-1
-    case -1 => if (isInclusive) end else end+1
-    case _  =>
-      val remainder = (gap % step).toInt
-      if (remainder != 0) end - remainder
-      else if (isInclusive) end
-      else end - step
+  /** Last element of this non-empty range.
+   *
+   *  For empty ranges, this value is nonsensical.
+   */
+  private[this] val lastElement: Int = {
+    /* Since we can assume the range is non-empty, `(numRangeElements - 1)`
+     * is a valid unsigned value in the full int range. The general formula is
+     * therefore `locationAfterN(numRangeElements - 1)`.
+     *
+     * We special-case 1 and -1 so that, in the happy path where `step` is a
+     * constant 1 or -1, and we only use `foreach`, `numRangeElements` is dead
+     * code.
+     *
+     * When `step` is not constant, it is probably 1 or -1 anyway, so the
+     * single branch should be predictably true.
+     *
+     * `step == 1 || step == -1`
+     *   equiv `(step + 1 == 2) || (step + 1 == 0)`
+     *   equiv `((step + 1) & ~2) == 0`
+     */
+    if (((step + 1) & ~2) == 0)
+      (if (isInclusive) end else end - step)
+    else
+      locationAfterN(numRangeElements - 1)
   }
 
   /** The last element of this range.  This method will return the correct value
@@ -171,18 +229,22 @@ sealed abstract class Range(
   // which means it will not fail fast for those cases where failing was
   // correct.
   private[this] def validateMaxLength(): Unit = {
-    if (numRangeElements < 0)
+    if (numRangeElements <= 0 && !isEmpty)
       fail()
   }
   private[this] def description = "%d %s %d by %s".format(start, if (isInclusive) "to" else "until", end, step)
   private[this] def fail() = throw new IllegalArgumentException(description + ": seqs cannot contain more than Int.MaxValue elements.")
 
   @throws[IndexOutOfBoundsException]
   final def apply(idx: Int): Int = {
-    validateMaxLength()
-    if (idx < 0 || idx >= numRangeElements)
-      throw CommonErrors.indexOutOfBounds(index = idx, max = numRangeElements - 1)
-    else start + (step * idx)
+    /* If length is not valid, numRangeElements <= 0, so the condition is always true.
+     * We push validateMaxLength() inside the then branch, out of the happy path.
+     */
+    if (idx < 0 || idx >= numRangeElements || isEmpty) {
+      validateMaxLength()
+      val max = if (isEmpty) -1 else numRangeElements - 1
+      throw CommonErrors.indexOutOfBounds(index = idx, max = max)
+    } else locationAfterN(idx)
   }
 
   /*@`inline`*/ final override def foreach[@specialized(Unit) U](f: Int => U): Unit = {
@@ -230,19 +292,23 @@ sealed abstract class Range(
     case _ => super.sameElements(that)
   }
 
+  /** Is the non-negative value `n` greater or equal to the number of elements
+   *  in this non-empty range?
+   *
+   *  This method returns nonsensical results if `n < 0` or if `this.isEmpty`.
+   */
+  @inline private[this] def greaterEqualNumRangeElements(n: Int): Boolean =
+    (n ^ Int.MinValue) > ((numRangeElements - 1) ^ Int.MinValue) // unsigned comparison
+
   /** Creates a new range containing the first `n` elements of this range.
     *
     *  @param n  the number of elements to take.
     *  @return   a new range consisting of `n` first elements.
     */
   final override def take(n: Int): Range =
     if (n <= 0 || isEmpty) newEmptyRange(start)
-    else if (n >= numRangeElements && numRangeElements >= 0) this
-    else {
-      // May have more than Int.MaxValue elements in range (numRangeElements < 0)
-      // but the logic is the same either way: take the first n
-      new Range.Inclusive(start, locationAfterN(n - 1), step)
-    }
+    else if (greaterEqualNumRangeElements(n)) this
+    else new Range.Inclusive(start, locationAfterN(n - 1), step)
 
   /** Creates a new range containing all the elements of this range except the first `n` elements.
     *
@@ -251,42 +317,27 @@ sealed abstract class Range(
     */
   final override def drop(n: Int): Range =
     if (n <= 0 || isEmpty) this
-    else if (n >= numRangeElements && numRangeElements >= 0) newEmptyRange(end)
-    else {
-      // May have more than Int.MaxValue elements (numRangeElements < 0)
-      // but the logic is the same either way: go forwards n steps, keep the rest
-      copy(locationAfterN(n), end, step)
-    }
+    else if (greaterEqualNumRangeElements(n)) newEmptyRange(end)
+    else copy(locationAfterN(n), end, step)
 
   /** Creates a new range consisting of the last `n` elements of the range.
     *
     *  $doesNotUseBuilders
     */
   final override def takeRight(n: Int): Range = {
-    if (n <= 0) newEmptyRange(start)
-    else if (numRangeElements >= 0) drop(numRangeElements - n)
-    else {
-      // Need to handle over-full range separately
-      val y = last
-      val x = y - step.toLong*(n-1)
-      if ((step > 0 && x < start) || (step < 0 && x > start)) this
-      else Range.inclusive(x.toInt, y, step)
-    }
+    if (n <= 0 || isEmpty) newEmptyRange(start)
+    else if (greaterEqualNumRangeElements(n)) this
+    else copy(locationAfterN(numRangeElements - n), end, step)
   }
 
   /** Creates a new range consisting of the initial `length - n` elements of the range.
     *
     *  $doesNotUseBuilders
     */
   final override def dropRight(n: Int): Range = {
-    if (n <= 0) this
-    else if (numRangeElements >= 0) take(numRangeElements - n)
-    else {
-      // Need to handle over-full range separately
-      val y = last - step.toInt*n
-      if ((step > 0 && y < start) || (step < 0 && y > start)) newEmptyRange(start)
-      else Range.inclusive(start, y.toInt, step)
-    }
+    if (n <= 0 || isEmpty) this
+    else if (greaterEqualNumRangeElements(n)) newEmptyRange(end)
+    else Range.inclusive(start, locationAfterN(numRangeElements - 1 - n), step)
   }
 
   // Advance from the start while we meet the given test
@@ -340,8 +391,9 @@ sealed abstract class Range(
     *  @return   a new range consisting of a contiguous interval of values in the old range
     */
   final override def slice(from: Int, until: Int): Range =
-    if (from <= 0) take(until)
-    else if (until >= numRangeElements && numRangeElements >= 0) drop(from)
+    if (isEmpty) this
+    else if (from <= 0) take(until)
+    else if (greaterEqualNumRangeElements(until) && until >= 0) drop(from)
     else {
       val fromValue = locationAfterN(from)
       if (from >= until) newEmptyRange(fromValue)
@@ -351,10 +403,6 @@ sealed abstract class Range(
   // Overridden only to refine the return type
   final override def splitAt(n: Int): (Range, Range) = (take(n), drop(n))
 
-  // Methods like apply throw exceptions on invalid n, but methods like take/drop
-  // are forgiving: therefore the checks are with the methods.
-  private[this] def locationAfterN(n: Int) = start + (step * n)
-
   // When one drops everything.  Can't ever have unchecked operations
   // like "end + 1" or "end - 1" because ranges involving Int.{ MinValue, MaxValue }
   // will overflow.  This creates an exclusive range where start == end
@@ -374,13 +422,13 @@ sealed abstract class Range(
     else new Range.Inclusive(start, end, step)
 
   final def contains(x: Int): Boolean = {
-    if (x == end && !isInclusive) false
+    if (isEmpty) false
     else if (step > 0) {
-      if (x < start || x > end) false
+      if (x < start || x > lastElement) false
       else (step == 1) || (Integer.remainderUnsigned(x - start, step) == 0)
     }
     else {
-      if (x < end || x > start) false
+      if (x > start || x < lastElement) false
       else (step == -1) || (Integer.remainderUnsigned(start - x, -step) == 0)
     }
   }
@@ -483,7 +531,12 @@ sealed abstract class Range(
   final override def toString: String = {
     val preposition = if (isInclusive) "to" else "until"
     val stepped = if (step == 1) "" else s" by $step"
-    val prefix = if (isEmpty) "empty " else if (!isExact) "inexact " else ""
+
+    def isInexact =
+      if (isInclusive) lastElement != end
+      else (lastElement + step) != end
+
+    val prefix = if (isEmpty) "empty " else if (isInexact) "inexact " else ""
     s"${prefix}Range $start $preposition $end$stepped"
   }
 
@@ -543,16 +596,19 @@ object Range {
 
     if (isEmpty) 0
     else {
-      // Counts with Longs so we can recognize too-large ranges.
-      val gap: Long    = end.toLong - start.toLong
-      val jumps: Long  = gap / step
-      // Whether the size of this range is one larger than the
-      // number of full-sized jumps.
-      val hasStub      = isInclusive || (gap % step != 0)
-      val result: Long = jumps + ( if (hasStub) 1 else 0 )
-
-      if (result > scala.Int.MaxValue) -1
-      else result.toInt
+      val stepSign = step >> 31 // if (step >= 0) 0 else -1
+      val gap = ((end - start) ^ stepSign) - stepSign // if (step >= 0) (end - start) else -(end - start)
+      val absStep = (step ^ stepSign) - stepSign // if (step >= 0) step else -step
+
+      val div = Integer.divideUnsigned(gap, absStep)
+      if (isInclusive) {
+        if (div == -1) // max unsigned int
+          -1 // corner case: there are 2^32 elements, which would overflow to 0
+        else
+          div + 1
+      } else {
+        if (absStep * div != gap) div + 1 else div
+      }
     }
   }
   def count(start: Int, end: Int, step: Int): Int =
@@ -576,12 +632,12 @@ object Range {
     */
   def inclusive(start: Int, end: Int): Range.Inclusive = new Range.Inclusive(start, end, 1)
 
-  @SerialVersionUID(3L)
+  @SerialVersionUID(4L)
   final class Inclusive(start: Int, end: Int, step: Int) extends Range(start, end, step) {
     def isInclusive: Boolean = true
   }
 
-  @SerialVersionUID(3L)
+  @SerialVersionUID(4L)
   final class Exclusive(start: Int, end: Int, step: Int) extends Range(start, end, step) {
     def isInclusive: Boolean = false
   }
@@ -635,7 +691,7 @@ object Range {
   * @param lastElement The last element included in the Range
   * @param initiallyEmpty Whether the Range was initially empty or not
   */
-@SerialVersionUID(3L)
+@SerialVersionUID(4L)
 private class RangeIterator(
   start: Int,
   step: Int,