stdlib: add unavailable methods on string indices to make migration to Swift 3 easier

Author: gribozavr

stdlib/public/core/StringUTF8.swift

@@ -134,9 +134,9 @@ extension String {
       ///
       /// - Precondition: The next value is representable.
       @warn_unused_result
-      internal func successor() -> Index {
+      internal func _successor() -> Index {
         // FIXME: swift-3-indexing-model: pull the following logic into UTF8View.index(after: Index)
-        // FIXME: swift-3-indexing-model: remove the successor() function.
+        // FIXME: swift-3-indexing-model: remove the _successor() function.
         let currentUnit = UTF8.CodeUnit(truncatingBitPattern: _buffer)
         let hiNibble = currentUnit >> 4
         // Map the high nibble of the current code unit into the
@@ -228,7 +228,7 @@ extension String {
     @warn_unused_result
     public func index(after i: Index) -> Index {
       // FIXME: swift-3-indexing-model: range check i?
-      return i.successor()
+      return i._successor()
     }
 
     /// Access the element at `position`.

stdlib/public/core/UnavailableStringAPIs.swift.gyb

@@ -109,3 +109,43 @@ ${stringSubscriptComment}
     Builtin.unreachable()
   }
 }
+
+% for View in ['UTF8View', 'UTF16View', 'UnicodeScalarView', 'CharacterView']:
+%   Index = 'String.%s.Index' % View
+%   Distance = 'String.%s.Index' % View
+extension ${Index} {
+  @available(
+    *, unavailable,
+    message: "To get the next index call 'index(after:)' on the ${View} instance that produced the index.")
+  public func successor() -> ${Index} {
+    Builtin.unreachable()
+  }
+%   if View != 'UTF8View':
+  @available(
+    *, unavailable,
+    message: "To get the previous index call 'index(before:)' on the ${View} instance that produced the index.")
+  public func predecessor() -> ${Index} {
+    Builtin.unreachable()
+  }
+%   end
+  @available(
+    *, unavailable,
+    message: "To advance an index by n steps call 'index(_:offsetBy:)' on the ${View} instance that produced the index.")
+  public func advancedBy(n: ${Distance}) -> ${Index} {
+    Builtin.unreachable()
+  }
+  @available(
+    *, unavailable,
+    message: "To advance an index by n steps stopping at a given limit call 'index(_:offsetBy:limitedBy:)' on ${View} instance that produced the index.  Note that the Swift 3 API returns 'nil' when trying to advance past the limit; the Swift 2 API returned the limit.")
+  public func advancedBy(n: ${Distance}, limit: ${Index}) -> ${Index} {
+    Builtin.unreachable()
+  }
+  @available(
+    *, unavailable,
+    message: "To find the distance between two indices call 'distance(from:to:)' on the ${View} instance that produced the index.")
+  public func distanceTo(end: ${Index}) -> ${Distance} {
+    Builtin.unreachable()
+  }
+}
+% end
+