[stdlib] String and range expressions

* finish string documentation revisions
* revise examples throughout to use range expressions instead of e.g.
  prefix(upTo: _)

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -95,8 +95,8 @@ if True:
 ///
 ///     let midpoint = absences.count / 2
 ///
-///     let firstHalf = absences.prefix(upTo: midpoint)
-///     let secondHalf = absences.suffix(from: midpoint)
+///     let firstHalf = absences[..<midpoint]
+///     let secondHalf = absences[midpoint...]
 ///
 /// Neither the `firstHalf` nor `secondHalf` slices allocate any new storage
 /// of their own. Instead, each presents a view onto the storage of the
@@ -151,7 +151,7 @@ if True:
 /// Here's an implementation of those steps:
 ///
 ///     if let i = absences.index(where: { $0 > 0 }) {                      // 1
-///         let absencesAfterFirst = absences.suffix(from: i + 1)           // 2
+///         let absencesAfterFirst = absences[(i + 1)...]                   // 2
 ///         if let j = absencesAfterFirst.index(where: { $0 > 0 }) {        // 3
 ///             print("The first day with absences had \(absences[i]).")    // 4
 ///             print("The second day with absences had \(absences[j]).")

stdlib/public/core/Collection.swift

@@ -453,15 +453,15 @@ public struct IndexingIterator<
 ///
 ///     let text = "Buffalo buffalo buffalo buffalo."
 ///     if let firstSpace = text.index(of: " ") {
-///         print(text.prefix(upTo: firstSpace))
+///         print(text[..<firstSpace])
 ///     }
 ///     // Prints "Buffalo"
 ///
-/// The `firstSpace` constant is an index into the `text` string---the position of the first space in the
-/// string. You can store indices in variables, and pass them to
-/// collection algorithms or use them later to access the corresponding
-/// element. In the example above, `firstSpace` is used to extract the prefix
-/// that contains elements up to that index.
+/// The `firstSpace` constant is an index into the `text` string---the position
+/// of the first space in the string. You can store indices in variables, and
+/// pass them to collection algorithms or use them later to access the
+/// corresponding element. In the example above, `firstSpace` is used to
+/// extract the prefix that contains elements up to that index.
 ///
 /// You can pass only valid indices to collection operations. You can find a
 /// complete set of a collection's valid indices by starting with the
@@ -514,20 +514,18 @@ public struct IndexingIterator<
 ///     // Prints "Buffalo"
 ///
 /// You can retrieve the same slice using other methods, such as finding the
-/// terminating index, and then using the `prefix(upTo:)` method, which takes
-/// an index as its parameter, or by using the view's ranged subscript.
+/// terminating index, and the using the string's ranged subscript, or by
+/// using the `prefix(upTo:)` method, which takes an index as its parameter.
 ///
 ///     if let firstSpace = text.index(of: " ") {
-///         print(text.prefix(upTo: firstSpace))
+///         print(text[..<firstSpace]
 ///         // Prints "Buffalo"
 ///
-///         let start = text.startIndex
-///         print(text[start..<firstSpace])
+///         print(text.prefix(upTo: firstSpace))
 ///         // Prints "Buffalo"
 ///     }
 ///
-/// The retrieved slice of `text` is equivalent in each of these
-/// cases.
+/// The retrieved slice of `text` is equivalent in each of these cases.
 ///
 /// Slices Share Indices
 /// --------------------
@@ -795,6 +793,15 @@ public protocol Collection : _Indexable, Sequence
   ///     print(numbers.prefix(upTo: numbers.startIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `prefix(upTo:)` method is equivalent to using a partial
+  /// half-open range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(upTo:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[..<i])
+  ///     }
+  ///     // Prints "[10, 20, 30]"
+  ///
   /// - Parameter end: The "past the end" index of the resulting subsequence.
   ///   `end` must be a valid index of the collection.
   /// - Returns: A subsequence up to, but not including, the `end` position.
@@ -822,6 +829,15 @@ public protocol Collection : _Indexable, Sequence
   ///     print(numbers.suffix(from: numbers.endIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `suffix(from:)` method is equivalent to using a partial range
+  /// from the index as the collection's subscript. The subscript notation is
+  /// preferred over `suffix(from:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[i...])
+  ///     }
+  ///     // Prints "[40, 50, 60]"
+  ///
   /// - Parameter start: The index at which to start the resulting subsequence.
   ///   `start` must be a valid index of the collection.
   /// - Returns: A subsequence starting at the `start` position.
@@ -843,6 +859,15 @@ public protocol Collection : _Indexable, Sequence
   ///     }
   ///     // Prints "[10, 20, 30, 40]"
   ///
+  /// Using the `prefix(through:)` method is equivalent to using a partial
+  /// closed range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(through:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[...i])
+  ///     }
+  ///     // Prints "[10, 20, 30, 40]"
+  ///
   /// - Parameter end: The index of the last element to include in the
   ///   resulting subsequence. `end` must be a valid index of the collection
   ///   that is not equal to the `endIndex` property.
@@ -1619,6 +1644,15 @@ extension Collection {
   ///     print(numbers.prefix(upTo: numbers.startIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `prefix(upTo:)` method is equivalent to using a partial
+  /// half-open range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(upTo:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[..<i])
+  ///     }
+  ///     // Prints "[10, 20, 30]"
+  ///
   /// - Parameter end: The "past the end" index of the resulting subsequence.
   ///   `end` must be a valid index of the collection.
   /// - Returns: A subsequence up to, but not including, the `end` position.
@@ -1649,6 +1683,15 @@ extension Collection {
   ///     print(numbers.suffix(from: numbers.endIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `suffix(from:)` method is equivalent to using a partial range
+  /// from the index as the collection's subscript. The subscript notation is
+  /// preferred over `suffix(from:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[i...])
+  ///     }
+  ///     // Prints "[40, 50, 60]"
+  ///
   /// - Parameter start: The index at which to start the resulting subsequence.
   ///   `start` must be a valid index of the collection.
   /// - Returns: A subsequence starting at the `start` position.
@@ -1673,6 +1716,15 @@ extension Collection {
   ///     }
   ///     // Prints "[10, 20, 30, 40]"
   ///
+  /// Using the `prefix(through:)` method is equivalent to using a partial
+  /// closed range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(through:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[...i])
+  ///     }
+  ///     // Prints "[10, 20, 30, 40]"
+  ///
   /// - Parameter end: The index of the last element to include in the
   ///   resulting subsequence. `end` must be a valid index of the collection
   ///   that is not equal to the `endIndex` property.

stdlib/public/core/MutableCollection.swift

@@ -267,13 +267,13 @@ public protocol MutableCollection : _MutableIndexable, Collection
   ///     // numbers == [30, 10, 20, 30, 30, 60, 40]
   ///
   /// The `numbers` array is now arranged in two partitions. The first
-  /// partition, `numbers.prefix(upTo: p)`, is made up of the elements that
-  /// are not greater than 30. The second partition, `numbers.suffix(from: p)`,
+  /// partition, `numbers[..<p]`, is made up of the elements that
+  /// are not greater than 30. The second partition, `numbers[p...]`,
   /// is made up of the elements that *are* greater than 30.
   ///
-  ///     let first = numbers.prefix(upTo: p)
+  ///     let first = numbers[..<p]
   ///     // first == [30, 10, 20, 30, 30]
-  ///     let second = numbers.suffix(from: p)
+  ///     let second = numbers[p...]
   ///     // second == [60, 40]
   ///
   /// - Parameter belongsInSecondPartition: A predicate used to partition

stdlib/public/core/OptionSet.swift

@@ -10,10 +10,10 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A type that presents a mathematical set interface to a bit mask.
+/// A type that presents a mathematical set interface to a bitset.
 ///
-/// You use the `OptionSet` protocol to represent bit mask types, where
-/// individual bits represent members of the set. Adopting this protocol in
+/// You use the `OptionSet` protocol to represent bitset types, where
+/// individual bits represent members of a set. Adopting this protocol in
 /// your custom types lets you perform set-related operations such as
 /// membership tests, unions, and intersections on those types. What's more,
 /// when implemented using specific criteria, adoption of this protocol
@@ -30,8 +30,8 @@
 /// For example, consider a custom type called `ShippingOptions` that is an
 /// option set of the possible ways to ship a customer's purchase.
 /// `ShippingOptions` includes a `rawValue` property of type `Int` that stores
-/// the bit mask of available shipping options. The static members `NextDay`,
-/// `SecondDay`, `Priority`, and `Standard` are unique, individual options.
+/// the bit mask of available shipping options. The static members `nextDay`,
+/// `secondDay`, `priority`, and `standard` are unique, individual options.
 ///
 ///     struct ShippingOptions: OptionSet {
 ///         let rawValue: Int