[stdlib] Remove BinaryInteger._word(at:)

Removes BinaryInteger's _word(at:) requirement and its
countOfRepresentedWords property, making the words property the
sole way to access an integer's words.

This is a better fix for https://bugs.swift.org/browse/SR-5275.

Author: lorentey

stdlib/public/core/DoubleWidth.swift.gyb

@@ -157,31 +157,6 @@ public struct DoubleWidth<Base : FixedWidthInteger> :
       self.init(exactly: integerPart)
     }
   }
-    
-  public func _word(at n: Int) -> UInt {
-    if Base.bitWidth < UInt.bitWidth {
-      if UInt.bitWidth % Base.bitWidth != 0 {
-        fatalError("word(at:) is not supported on this type")
-      }
-      if n > 0 {
-        // Since `Base` is narrower than word, any non-zero word will give us
-        // the correct value here (0 or ~0).
-        return _storage.high._word(at: n)
-      }
-      return _storage.low._word(at: 0) |
-        (_storage.high._word(at: 0) << numericCast(Base.bitWidth))
-    } else {
-      // multiples of word-size only
-      if Base.bitWidth % UInt.bitWidth != 0 {
-        fatalError("word(at:) is not supported on this type")
-      }
-
-      // TODO: move to Int128 just like init(_builtinIntegerLiteral:) ?
-      return (n < _storage.low._countRepresentedWords) ?
-        _storage.low._word(at: n) :
-        _storage.high._word(at: n - _storage.low._countRepresentedWords)
-    }
-  }
 
   public struct Words : Collection {
     public enum _IndexValue {

stdlib/public/core/Integers.swift.gyb

@@ -1427,27 +1427,22 @@ public protocol BinaryInteger :
   /// - Parameter source: An integer to convert to this type.
   init<T : BinaryInteger>(clamping source: T)
 
-  /// Returns the n-th word, counting from the least significant to most
-  /// significant, of this value's binary representation.
-  ///
-  /// The `_word(at:)` method returns negative values in two's complement
-  /// representation, regardless of a type's underlying implementation. If `n`
-  /// is greater than the number of words in this value's current
-  /// representation, the result is `0` for positive numbers and `~0` for
-  /// negative numbers.
-  ///
-  /// - Parameter n: The word to return, counting from the least significant to
-  ///   most significant. `n` must be greater than or equal to zero.
-  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
-  ///   n-th word of this value.
-  func _word(at n: Int) -> UInt
-
-  // FIXME(integers): add doc comments
-  // FIXME: Should be `Words : Collection where Words.Iterator.Element == UInt`
+  // FIXME: Should be `Words : Collection where Words.Element == UInt`
   // See <rdar://problem/31798916> for why it isn't.
-  associatedtype Words
+  /// A type that represents the words of a binary integer. 
+  /// Must implement the `Collection` protocol with an `UInt` element type.
+  associatedtype Words : Sequence where Words.Element == UInt
+
+  /// Returns a collection containing the words of this value's binary
+  /// representation, in order from the least significant to most significant.
+  ///
+  /// Negative values are returned in two's complement representation,
+  /// regardless of the type's underlying implementation.
   var words: Words { get }
 
+  /// The least significant word in this value's binary representation.
+  var _lowUWord: UInt { get }
+
   /// The number of bits in the current binary representation of this value.
   ///
   /// This property is a constant for instances of fixed-width integer
@@ -1543,13 +1538,10 @@ extension BinaryInteger {
     return (self > (0 as Self) ? 1 : 0) - (self < (0 as Self) ? 1 : 0)
   }
 
-  /// The number of words used for the current binary representation of this
-  /// value.
-  ///
-  /// This property is a constant for instances of fixed-width integer types.
   @_transparent
-  public var _countRepresentedWords: Int {
-    return (self.bitWidth + ${word_bits} - 1) / ${word_bits}
+  public var _lowUWord: UInt {
+    var it = words.makeIterator()
+    return it.next() ?? 0
   }
 
   public func quotientAndRemainder(dividingBy rhs: Self)
@@ -1887,26 +1879,6 @@ extension BinaryInteger {
 }
 #endif
 
-extension BinaryInteger {
-  // FIXME(integers): Should be removed once words get implemented properly.
-  // Meanhile it allows to conform to the BinaryInteger without implementing
-  // underscored APIs. https://bugs.swift.org/browse/SR-5275
-  public func _word(at n: Int) -> UInt {
-    fatalError("Should be overridden")
-  }
-
-  // FIXME(integers): inefficient. Should get rid of _word(at:) and
-  // _countRepresentedWords, and make `words` the basic operation.
-  public var words: [UInt] {
-    var result = [UInt]()
-    result.reserveCapacity(_countRepresentedWords)
-    for i in 0..<self._countRepresentedWords {
-      result.append(_word(at: i))
-    }
-    return result
-  }
-}
-
 //===----------------------------------------------------------------------===//
 //===--- FixedWidthInteger ------------------------------------------------===//
 //===----------------------------------------------------------------------===//
@@ -2320,24 +2292,24 @@ ${unsafeOperationComment(x.operator)}
   }
 % end
 
-  @inline(__always)
+  @_transparent
   public init<T : BinaryInteger>(extendingOrTruncating source: T) {
-    if Self.bitWidth <= ${word_bits} {
-      self = Self.init(_truncatingBits: source._word(at: 0))
+    if Self.bitWidth <= ${word_bits} || source.bitWidth <= ${word_bits} {
+      self = Self.init(_truncatingBits: source._lowUWord)
     }
     else {
-      var result: Self = source < (0 as T) ? ~0 : 0
-      // start with the most significant word
-      var n = source._countRepresentedWords
-      while n >= 0 {
-        // masking is OK here because this we have already ensured
-        // that Self.bitWidth > ${word_bits}.  Not masking results in
+      let neg = source < (0 as T)
+      var result: Self = neg ? ~0 : 0
+      var shift: Self = 0
+      let width = Self(_truncatingBits: Self.bitWidth._lowUWord)
+      for word in source.words {
+        guard shift < width else { break }
+        // masking shift is OK here because we have already ensured
+        // that shift < Self.bitWidth. Not masking results in
         // infinite recursion.
-        result &<<= (${word_bits} as Self)
-        result |= Self(_truncatingBits: source._word(at: n))
-        n -= 1
+        result ^= Self(_truncatingBits: neg ? ~word : word) &<< shift
+        shift += ${word_bits}
       }
-
       self = result
     }
   }
@@ -2798,22 +2770,6 @@ ${assignmentOperatorComment(x.operator, True)}
       )._lowUWord._value)
   }
 
-  @_transparent
-  public func _word(at n: Int) -> UInt {
-    _precondition(n >= 0, "Negative word index")
-    if _fastPath(n < _countRepresentedWords) {
-      let shift = UInt(n._value) &* ${word_bits}
-      let bitWidth = UInt(self.bitWidth._value)
-      _sanityCheck(shift < bitWidth)
-      return (self &>> ${Self}(_truncatingBits: shift))._lowUWord
-    }
-% if signed:
-    return self < (0 as ${Self}) ? ~0 : 0
-% else:
-    return 0
-% end
-  }
-
 % if Self == 'UInt' or (bits > word_bits and not signed):
   // FIXME should be RandomAccessCollection
   public struct Words : BidirectionalCollection {

test/Prototypes/BigInt.swift

@@ -121,8 +121,7 @@ public struct _BigInt<Word: FixedWidthInteger & UnsignedInteger> :
     // FIXME: This is broken on 32-bit arch w/ Word = UInt64
     let wordRatio = UInt.bitWidth / Word.bitWidth
     _sanityCheck(wordRatio != 0)
-    for i in 0..<source._countRepresentedWords {
-      var sourceWord = source._word(at: i)
+    for var sourceWord in source.words {
       for _ in 0..<wordRatio {
         _data.append(Word(extendingOrTruncating: sourceWord))
         sourceWord >>= Word.bitWidth
@@ -660,38 +659,6 @@ public struct _BigInt<Word: FixedWidthInteger & UnsignedInteger> :
     }
   }
 
-  public func _word(at n: Int) -> UInt {
-    let ratio = UInt.bitWidth / Word.bitWidth
-    _sanityCheck(ratio != 0)
-
-    var twosComplementData = _dataAsTwosComplement()
-
-    // Find beginning of range. If we're beyond the value, return 1s or 0s.
-    let start = n * ratio
-    if start >= twosComplementData.count {
-      return isNegative ? UInt.max : 0
-    }
-
-    // Find end of range. If the range extends beyond the representation,
-    // add bits to the end.
-    let end = (n + 1) * ratio
-    if end > twosComplementData.count {
-      twosComplementData.append(contentsOf:
-        repeatElement(isNegative ? Word.max : 0,
-          count: end - twosComplementData.count))
-    }
-
-    // Build the correct word from the range determined above.
-    let wordSlice = twosComplementData[start..<end]
-    var result: UInt = 0
-    for v in wordSlice.reversed() {
-      result <<= Word.bitWidth
-      result |= UInt(extendingOrTruncating: v)
-    }
-
-    return result
-  }
-
   public var words: [UInt] {
     _sanityCheck(UInt.bitWidth % Word.bitWidth == 0)
     var words: [UInt] = []
@@ -1316,10 +1283,6 @@ struct Bit : FixedWidthInteger, UnsignedInteger {
     return self
   }
 
-  func _word(at n: Int) -> UInt {
-    return UInt(value)
-  }
-
   var words: UInt.Words {
     return UInt(value).words
   }