[stdlib][swift-3-indexing-model] changes in index(_:stepsFrom:limitedBy:)

- index(_:stepsFrom:limitedBy:) returns Index?
- formIndex(_:stepsFrom:limitedBy) returns Bool

Author: Max Moiseev

Diff for: stdlib/private/StdlibCollectionUnittest/CheckCollectionInstance.swift.gyb

@@ -109,7 +109,7 @@ internal func _checkIncrementalAdvance<
     var offset: BaseCollection.IndexDistance = 0
     for _ in 0...(d * sign).toIntMax() {
       let j = baseCollection.index(offset, stepsFrom: i)
-      let k = baseCollection.index(offset + sign, stepsFrom: i, limitedBy: limit)
+      let k = baseCollection.index(offset + sign, stepsFrom: i, limitedBy: limit) ?? limit
       let jAtLimit = offset == d
       if jAtLimit {
         expectEqual(limit, j, ${trace})

Diff for: stdlib/private/StdlibCollectionUnittest/CheckCollectionType.swift

@@ -682,7 +682,7 @@ if resiliencyChecks.subscriptRangeOnOutOfBoundsRangesBehavior != .none {
   }
 }
 
-// FIXME: swift-3-indexing-model - add tests for the follow?
+// FIXME: swift-3-indexing-model - add tests for the following?
 //          successor(of: i: Index) -> Index
 //          formSuccessor(i: inout Index)
 //          advance(i: Index, by n: IndexDistance) -> Index

Diff for: stdlib/private/StdlibCollectionUnittest/LoggingWrappers.swift.gyb

@@ -424,7 +424,9 @@ public struct ${Self}<
   }
 
   @warn_unused_result
-  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index {
+  public func index(
+    n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
+  ) -> Index? {
     Log.advanceLimit[selfType] += 1
     return base.index(n, stepsFrom: i, limitedBy: limit)
   }

Diff for: stdlib/public/core/BidirectionalCollection.swift

@@ -100,14 +100,14 @@ extension BidirectionalIndexable {
   @warn_unused_result
   public func index(
     n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
-  ) -> Index {
+  ) -> Index? {
     if n >= 0 {
       return _advanceForward(i, by: n, limitedBy: limit)
     }
     var i = i
     for _ in stride(from: 0, to: n, by: -1) {
-      if (limit == i) {
-        break;
+      if i == limit {
+        return nil
       }
       formPredecessor(&i)
     }
@@ -157,13 +157,13 @@ extension BidirectionalIndexable where Index : Strideable {
   }
 
   @warn_unused_result
-  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index {
+  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index? {
     // FIXME: swift-3-indexing-model: range check i
 
     // FIXME: swift-3-indexing-model - error: cannot invoke 'advanced' with an argument list of type '(by: Self.IndexDistance)'
     let i = i.advanced(by: n)
-    if (i >= limit) {
-      return limit
+    if (i > limit) {
+      return nil
     }
     return i
   }
@@ -235,7 +235,10 @@ extension BidirectionalCollection {
   public func dropLast(n: Int) -> SubSequence {
     _precondition(
       n >= 0, "Can't drop a negative number of elements from a collection")
-    let end = index(numericCast(-n), stepsFrom: endIndex, limitedBy: startIndex)
+    let end = index(
+      numericCast(-n),
+      stepsFrom: endIndex,
+      limitedBy: startIndex) ?? startIndex
     return self[startIndex..<end]
   }
 
@@ -252,7 +255,10 @@ extension BidirectionalCollection {
     _precondition(
       maxLength >= 0,
       "Can't take a suffix of negative length from a collection")
-    let start = index(numericCast(-maxLength), stepsFrom: endIndex, limitedBy: startIndex)
+    let start = index(
+      numericCast(-maxLength),
+      stepsFrom: endIndex,
+      limitedBy: startIndex) ?? startIndex
     return self[start..<endIndex]
   }
 }

Diff for: stdlib/public/core/Collection.swift

@@ -159,14 +159,14 @@ public protocol Indexable : IndexableBase {
   @warn_unused_result
   func index(n: IndexDistance, stepsFrom i: Index) -> Index
 
-  /// Returns the result of advancing `i` by `n` positions, or until it
-  /// equals `limit`.
+  /// Returns the result of advancing `i` by `n` positions, or `nil` if it
+  /// reaches the `limit`.
   ///
   /// - Returns:
-  ///   - If `n > 0`, the `n`th successor of `i` or `limit`, whichever
-  ///     is reached first.
-  ///   - If `n < 0`, the `n`th predecessor of `i` or `limit`, whichever
-  ///     is reached first.
+  ///   - If `n > 0`, the `n`th successor of `i` or `nil` if the `limit` has
+  ///     been reached.
+  ///   - If `n < 0`, the `n`th predecessor of `i` or `nil` if the `limit` has
+  ///     been reached.
   ///   - Otherwise, `i` unmodified.
   ///
   /// - Precondition: `n >= 0` unless `Self` conforms to
@@ -178,7 +178,7 @@ public protocol Indexable : IndexableBase {
   @warn_unused_result
   func index(
     n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
-  ) -> Index
+  ) -> Index?
 
   /// Advances `i` by `n` positions.
   ///
@@ -195,6 +195,9 @@ public protocol Indexable : IndexableBase {
 
   /// Advances `i` by `n` positions, or until it equals `limit`.
   ///
+  /// - Returns `true` if index has been advanced by exactly `n` steps without
+  ///   reaching the `limit`, and `false` otherwise.
+  ///
   /// - Precondition: `n >= 0` unless `Self` conforms to
   ///   `BidirectionalCollection`.
   ///
@@ -203,7 +206,7 @@ public protocol Indexable : IndexableBase {
   ///   - O(`abs(n)`) otherwise.
   func formIndex(
     n: IndexDistance, stepsFrom i: inout Index, limitedBy limit: Index
-  )
+  ) -> Bool
 
   /// Returns the distance between `start` and `end`.
   ///
@@ -406,14 +409,14 @@ public protocol Collection : Indexable, Sequence {
   func index(n: IndexDistance, stepsFrom i: Index) -> Index
 
   // FIXME: swift-3-indexing-model: Should this mention preconditions on `n`?
-  /// Returns the result of advancing `i` by `n` positions, or until it
-  /// equals `limit`.
+  /// Returns the result of advancing `i` by `n` positions, or `nil` if it
+  /// reaches the `limit`.
   ///
   /// - Returns:
-  ///   - If `n > 0`, the `n`th successor of `i` or `limit`, whichever
-  ///     is reached first.
-  ///   - If `n < 0`, the `n`th predecessor of `i` or `limit`, whichever
-  ///     is reached first.
+  ///   - If `n > 0`, the `n`th successor of `i` or `nil` if the `limit` has
+  ///     been reached.
+  ///   - If `n < 0`, the `n`th predecessor of `i` or `nil` if the `limit` has
+  ///     been reached.
   ///   - Otherwise, `i` unmodified.
   ///
   /// - Precondition: `n >= 0` unless `Self` conforms to
@@ -425,7 +428,7 @@ public protocol Collection : Indexable, Sequence {
   @warn_unused_result
   func index(
     n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
-  ) -> Index
+  ) -> Index?
 
   /// Returns the distance between `start` and `end`.
   ///
@@ -481,7 +484,7 @@ extension Indexable {
   @warn_unused_result
   public func index(
     n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
-  ) -> Index {
+  ) -> Index? {
     // FIXME: swift-3-indexing-model: tests.
     return self._advanceForward(i, by: n, limitedBy: limit)
   }
@@ -492,8 +495,13 @@ extension Indexable {
 
   public func formIndex(
     n: IndexDistance, stepsFrom i: inout Index, limitedBy limit: Index
-  ) {
-    i = index(n, stepsFrom: i, limitedBy: limit)
+  ) -> Bool {
+    if let advancedIndex = index(n, stepsFrom: i, limitedBy: limit) {
+      i = advancedIndex
+      return true
+    }
+    i = limit
+    return false
   }
 
   @warn_unused_result
@@ -529,14 +537,16 @@ extension Indexable {
   @inline(__always)
   @warn_unused_result
   internal
-  func _advanceForward(i: Index, by n: IndexDistance, limitedBy limit: Index) -> Index {
+  func _advanceForward(
+    i: Index, by n: IndexDistance, limitedBy limit: Index
+  ) -> Index? {
     _precondition(n >= 0,
       "Only BidirectionalCollections can be advanced by a negative amount")
 
     var i = i
     for _ in stride(from: 0, to: n, by: 1) {
-      if (limit == i) {
-        break;
+      if i == limit {
+        return nil
       }
       formSuccessor(&i)
     }
@@ -567,15 +577,17 @@ extension Indexable where Index : Strideable {
   }
 
   @warn_unused_result
-  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index {
+  public func index(
+    n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
+  ) -> Index? {
     _precondition(n >= 0,
       "Only BidirectionalCollections can be advanced by a negative amount")
     // FIXME: swift-3-indexing-model: range check i
 
     // FIXME: swift-3-indexing-model - error: cannot invoke 'advanced' with an argument list of type '(by: Self.IndexDistance)'
     let i = i.advanced(by: n)
     if (i >= limit) {
-      return limit
+      return nil
     }
     return i
   }
@@ -728,7 +740,8 @@ extension Collection {
   @warn_unused_result
   public func dropFirst(n: Int) -> SubSequence {
     _precondition(n >= 0, "Can't drop a negative number of elements from a collection")
-    let start = index(numericCast(n), stepsFrom: startIndex, limitedBy: endIndex)
+    let start = index(numericCast(n),
+      stepsFrom: startIndex, limitedBy: endIndex) ?? endIndex
     return self[start..<endIndex]
   }
 
@@ -741,7 +754,8 @@ extension Collection {
     _precondition(
       n >= 0, "Can't drop a negative number of elements from a collection")
     let amount = Swift.max(0, numericCast(count) - n)
-    let end = index(numericCast(amount), stepsFrom: startIndex, limitedBy: endIndex)
+    let end = index(numericCast(amount),
+      stepsFrom: startIndex, limitedBy: endIndex) ?? endIndex
     return self[startIndex..<end]
   }
 
@@ -758,7 +772,8 @@ extension Collection {
     _precondition(
       maxLength >= 0,
       "Can't take a prefix of negative length from a collection")
-    let end = index(numericCast(maxLength), stepsFrom: startIndex, limitedBy: endIndex)
+    let end = index(numericCast(maxLength),
+      stepsFrom: startIndex, limitedBy: endIndex) ?? endIndex
     return self[startIndex..<end]
   }
 
@@ -776,7 +791,8 @@ extension Collection {
       maxLength >= 0,
       "Can't take a suffix of negative length from a collection")
     let amount = Swift.max(0, numericCast(count) - maxLength)
-    let start = index(numericCast(amount), stepsFrom: startIndex, limitedBy: endIndex)
+    let start = index(numericCast(amount),
+      stepsFrom: startIndex, limitedBy: endIndex) ?? endIndex
     return self[start..<endIndex]
   }
 

Diff for: stdlib/public/core/EmptyCollection.swift

@@ -110,7 +110,9 @@ public struct EmptyCollection<Element> :
   /// EmptyCollection does not have any element indices, so it is not
   /// possible to advance indices.
   @warn_unused_result
-  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index {
+  public func index(
+    n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
+  ) -> Index? {
     // TODO: swift-3-indexing-model: tests for traps.
     _preconditionFailure("EmptyCollection can't advance indices")
   }

Diff for: stdlib/public/core/ExistentialCollection.swift.gyb

@@ -232,7 +232,7 @@ internal class _AnyRandomAccessCollectionBox<Element>
     n: IntMax,
     stepsFrom i: _AnyIndexBox,
     limitedBy limit: _AnyIndexBox
-  ) -> _AnyIndexBox {
+  ) -> _AnyIndexBox? {
     _abstract()
   }
   internal func _formIndex(n: IntMax, stepsFrom i: inout _AnyIndexBox) {
@@ -242,7 +242,7 @@ internal class _AnyRandomAccessCollectionBox<Element>
     n: IntMax,
     stepsFrom i: inout _AnyIndexBox,
     limitedBy limit: _AnyIndexBox
-  ) {
+  ) -> Bool {
     _abstract()
   }
   @warn_unused_result
@@ -493,20 +493,20 @@ internal final class _${Kind}Box<
     n: IntMax,
     stepsFrom i: _AnyIndexBox,
     limitedBy limit: _AnyIndexBox
-  ) -> _AnyIndexBox {
-    return _IndexBox(_base:
-      _base.index(
+  ) -> _AnyIndexBox? {
+    return _base.index(
         numericCast(n),
         stepsFrom: _unbox(i),
-        limitedBy: _unbox(limit)))
+        limitedBy: _unbox(limit))
+      .map { _IndexBox(_base: $0) }
   }
 
   internal override func _formIndex(
     n: IntMax,
     stepsFrom i: inout _AnyIndexBox
   ) {
-    if let i = i as? _IndexBox<S.Index> {
-      return _base.formIndex(numericCast(n), stepsFrom: &i._base)
+    if let box = i as? _IndexBox<S.Index> {
+      return _base.formIndex(numericCast(n), stepsFrom: &box._base)
     }
     fatalError("Index type mismatch!")
   }
@@ -515,11 +515,11 @@ internal final class _${Kind}Box<
     n: IntMax,
     stepsFrom i: inout _AnyIndexBox,
     limitedBy limit: _AnyIndexBox
-  ) {
-    if let i = i as? _IndexBox<S.Index> {
+  ) -> Bool {
+    if let box = i as? _IndexBox<S.Index> {
       return _base.formIndex(
         numericCast(n),
-        stepsFrom: &i._base,
+        stepsFrom: &box._base,
         limitedBy: _unbox(limit))
     }
     fatalError("Index type mismatch!")
@@ -1029,9 +1029,9 @@ public struct ${Self}<Element>
     n: IntMax,
     stepsFrom i: AnyIndex,
     limitedBy limit: AnyIndex
-  ) -> AnyIndex {
-    return AnyIndex(
-      _box: _box._index(n, stepsFrom: i._box, limitedBy: limit._box))
+  ) -> AnyIndex? {
+    return _box._index(n, stepsFrom: i._box, limitedBy: limit._box)
+      .map { AnyIndex(_box:$0) }
   }
 
   public func formIndex(n: IntMax, stepsFrom i: inout AnyIndex) {
@@ -1046,12 +1046,16 @@ public struct ${Self}<Element>
     n: IntMax,
     stepsFrom i: inout AnyIndex,
     limitedBy limit: AnyIndex
-  ) {
+  ) -> Bool {
     if _isUnique(&i._box) {
       return _box._formIndex(n, stepsFrom: &i._box, limitedBy: limit._box)
-    } else {
-      i = index(n, stepsFrom: i, limitedBy: limit)
     }
+    if let advanced = index(n, stepsFrom: i, limitedBy: limit) {
+      i = advanced
+      return true
+    }
+    i = limit
+    return false
   }
 
   @warn_unused_result

Diff for: stdlib/public/core/Filter.swift

@@ -233,15 +233,17 @@ public struct LazyFilterCollection<
 
   // TODO: swift-3-indexing-model - add docs
   @warn_unused_result
-  public func index(n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index) -> Index {
+  public func index(
+    n: IndexDistance, stepsFrom i: Index, limitedBy limit: Index
+  ) -> Index? {
     _precondition(n >= 0,
       "Only BidirectionalCollections can be advanced by a negative amount")
     // TODO: swift-3-indexing-model: _failEarlyRangeCheck i?
 
     var index = i.base
     for _ in stride(from: 0, to: n, by: 1) {
       if index == limit.base {
-        break
+        return nil
       }
       _nextFilteredInPlace(&index)
     }