Clean up based on the String Processing Algorithms proposal (#247)

* Clean up based on the String Processing Algorithms proposal

- Move functions and types that have not been proposed from public to internal
- Add doc comments for public API
- Add FIXME for API awaiting SE-0346
- Replace `_MatchResult` with `Regex<Output>.Match` and update tests

Co-authored-by: Richard Wei <rxrwei@gmail.com>

Author: itingliu

Sources/_StringProcessing/Algorithms/Algorithms/Contains.swift

@@ -12,7 +12,7 @@
 // MARK: `CollectionSearcher` algorithms
 
 extension Collection {
-  public func contains<Searcher: CollectionSearcher>(
+  func contains<Searcher: CollectionSearcher>(
     _ searcher: Searcher
   ) -> Bool where Searcher.Searched == Self {
     firstRange(of: searcher) != nil
@@ -22,6 +22,11 @@ extension Collection {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
+  /// Returns a Boolean value indicating whether the collection contains the
+  /// given sequence.
+  /// - Parameter other: A sequence to search for within this collection.
+  /// - Returns: `true` if the collection contains the specified sequence,
+  /// otherwise `false`.
   public func contains<S: Sequence>(_ other: S) -> Bool
     where S.Element == Element
   {
@@ -30,7 +35,7 @@ extension Collection where Element: Equatable {
 }
 
 extension BidirectionalCollection where Element: Comparable {
-  public func contains<S: Sequence>(_ other: S) -> Bool
+  func contains<S: Sequence>(_ other: S) -> Bool
     where S.Element == Element
   {
     firstRange(of: other) != nil
@@ -40,6 +45,11 @@ extension BidirectionalCollection where Element: Comparable {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
+  /// Returns a Boolean value indicating whether the collection contains the
+  /// given regex.
+  /// - Parameter regex: A regex to search for within this collection.
+  /// - Returns: `true` if the regex was found in the collection, otherwise
+  /// `false`.
   public func contains<R: RegexComponent>(_ regex: R) -> Bool {
     contains(RegexConsumer(regex))
   }

Sources/_StringProcessing/Algorithms/Algorithms/FirstRange.swift

@@ -12,7 +12,7 @@
 // MARK: `CollectionSearcher` algorithms
 
 extension Collection {
-  public func firstRange<S: CollectionSearcher>(
+  func firstRange<S: CollectionSearcher>(
     of searcher: S
   ) -> Range<Index>? where S.Searched == Self {
     var state = searcher.state(for: self, in: startIndex..<endIndex)
@@ -21,7 +21,7 @@ extension Collection {
 }
 
 extension BidirectionalCollection {
-  public func lastRange<S: BackwardCollectionSearcher>(
+  func lastRange<S: BackwardCollectionSearcher>(
     of searcher: S
   ) -> Range<Index>? where S.BackwardSearched == Self {
     var state = searcher.backwardState(for: self, in: startIndex..<endIndex)
@@ -32,6 +32,11 @@ extension BidirectionalCollection {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
+  /// Finds and returns the range of the first occurrence of a given sequence
+  /// within the collection.
+  /// - Parameter sequence: The sequence to search for.
+  /// - Returns: A range in the collection of the first occurrence of `sequence`.
+  /// Returns nil if `sequence` is not found.
   public func firstRange<S: Sequence>(
     of sequence: S
   ) -> Range<Index>? where S.Element == Element {
@@ -42,6 +47,11 @@ extension Collection where Element: Equatable {
 }
 
 extension BidirectionalCollection where Element: Comparable {
+  /// Finds and returns the range of the first occurrence of a given sequence
+  /// within the collection.
+  /// - Parameter other: The sequence to search for.
+  /// - Returns: A range in the collection of the first occurrence of `sequence`.
+  /// Returns `nil` if `sequence` is not found.
   public func firstRange<S: Sequence>(
     of other: S
   ) -> Range<Index>? where S.Element == Element {
@@ -56,11 +66,16 @@ extension BidirectionalCollection where Element: Comparable {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
+  /// Finds and returns the range of the first occurrence of a given regex
+  /// within the collection.
+  /// - Parameter regex: The regex to search for.
+  /// - Returns: A range in the collection of the first occurrence of `regex`.
+  /// Returns `nil` if `regex` is not found.
   public func firstRange<R: RegexComponent>(of regex: R) -> Range<Index>? {
     firstRange(of: RegexConsumer(regex))
   }
 
-  public func lastRange<R: RegexComponent>(of regex: R) -> Range<Index>? {
+  func lastRange<R: RegexComponent>(of regex: R) -> Range<Index>? {
     lastRange(of: RegexConsumer(regex))
   }
 }

Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift

@@ -11,7 +11,7 @@
 
 // MARK: `RangesCollection`
 
-public struct RangesCollection<Searcher: CollectionSearcher> {
+struct RangesCollection<Searcher: CollectionSearcher> {
   public typealias Base = Searcher.Searched
 
   let base: Base
@@ -33,7 +33,7 @@ public struct RangesCollection<Searcher: CollectionSearcher> {
   }
 }
 
-public struct RangesIterator<Searcher: CollectionSearcher>: IteratorProtocol {
+struct RangesIterator<Searcher: CollectionSearcher>: IteratorProtocol {
   public typealias Base = Searcher.Searched
 
   let base: Base
@@ -92,7 +92,7 @@ extension RangesCollection: Collection {
 }
 
 extension RangesCollection.Index: Comparable {
-  public static func == (lhs: Self, rhs: Self) -> Bool {
+  static func == (lhs: Self, rhs: Self) -> Bool {
     switch (lhs.range, rhs.range) {
     case (nil, nil):
       return true
@@ -103,7 +103,7 @@ extension RangesCollection.Index: Comparable {
     }
   }
 
-  public static func < (lhs: Self, rhs: Self) -> Bool {
+  static func < (lhs: Self, rhs: Self) -> Bool {
     switch (lhs.range, rhs.range) {
     case (nil, _):
       return false
@@ -117,8 +117,8 @@ extension RangesCollection.Index: Comparable {
 
 // MARK: `ReversedRangesCollection`
 
-public struct ReversedRangesCollection<Searcher: BackwardCollectionSearcher> {
-  public typealias Base = Searcher.BackwardSearched
+struct ReversedRangesCollection<Searcher: BackwardCollectionSearcher> {
+  typealias Base = Searcher.BackwardSearched
 
   let base: Base
   let searcher: Searcher
@@ -157,15 +157,15 @@ extension ReversedRangesCollection: Sequence {
 // MARK: `CollectionSearcher` algorithms
 
 extension Collection {
-  public func ranges<S: CollectionSearcher>(
+  func ranges<S: CollectionSearcher>(
     of searcher: S
   ) -> RangesCollection<S> where S.Searched == Self {
     RangesCollection(base: self, searcher: searcher)
   }
 }
 
 extension BidirectionalCollection {
-  public func rangesFromBack<S: BackwardCollectionSearcher>(
+  func rangesFromBack<S: BackwardCollectionSearcher>(
     of searcher: S
   ) -> ReversedRangesCollection<S> where S.BackwardSearched == Self {
     ReversedRangesCollection(base: self, searcher: searcher)
@@ -175,7 +175,8 @@ extension BidirectionalCollection {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
-  public func ranges<S: Sequence>(
+  // FIXME: Replace `RangesCollection` when SE-0346 is enabled
+  func ranges<S: Sequence>(
     of other: S
   ) -> RangesCollection<ZSearcher<Self>> where S.Element == Element {
     ranges(of: ZSearcher(pattern: Array(other), by: ==))
@@ -194,7 +195,7 @@ extension BidirectionalCollection where Element: Equatable {
 }
 
 extension BidirectionalCollection where Element: Comparable {
-  public func ranges<S: Sequence>(
+  func ranges<S: Sequence>(
     of other: S
   ) -> RangesCollection<PatternOrEmpty<TwoWaySearcher<Self>>>
     where S.Element == Element
@@ -216,13 +217,14 @@ extension BidirectionalCollection where Element: Comparable {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
-  public func ranges<R: RegexComponent>(
+  // FIXME: Replace `RangesCollection` when SE-0346 is enabled
+  func ranges<R: RegexComponent>(
     of regex: R
   ) -> RangesCollection<RegexConsumer<R, Self>> {
     ranges(of: RegexConsumer(regex))
   }
 
-  public func rangesFromBack<R: RegexComponent>(
+  func rangesFromBack<R: RegexComponent>(
     of regex: R
   ) -> ReversedRangesCollection<RegexConsumer<R, Self>> {
     rangesFromBack(of: RegexConsumer(regex))

Sources/_StringProcessing/Algorithms/Algorithms/Replace.swift

@@ -12,7 +12,7 @@
 // MARK: `CollectionSearcher` algorithms
 
 extension RangeReplaceableCollection {
-  public func replacing<Searcher: CollectionSearcher, Replacement: Collection>(
+  func replacing<Searcher: CollectionSearcher, Replacement: Collection>(
     _ searcher: Searcher,
     with replacement: Replacement,
     subrange: Range<Index>,
@@ -36,7 +36,7 @@ extension RangeReplaceableCollection {
     return result
   }
 
-  public func replacing<Searcher: CollectionSearcher, Replacement: Collection>(
+  func replacing<Searcher: CollectionSearcher, Replacement: Collection>(
     _ searcher: Searcher,
     with replacement: Replacement,
     maxReplacements: Int = .max
@@ -50,7 +50,7 @@ extension RangeReplaceableCollection {
       maxReplacements: maxReplacements)
   }
 
-  public mutating func replace<
+  mutating func replace<
     Searcher: CollectionSearcher, Replacement: Collection
   >(
     _ searcher: Searcher,
@@ -67,6 +67,16 @@ extension RangeReplaceableCollection {
 // MARK: Fixed pattern algorithms
 
 extension RangeReplaceableCollection where Element: Equatable {
+  /// Returns a new collection in which all occurrences of a target sequence
+  /// are replaced by another collection.
+  /// - Parameters:
+  ///   - other: The sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - subrange: The range in the collection in which to search for `other`.
+  ///   - maxReplacements: A number specifying how many occurrences of `other`
+  ///   to replace. Default is `Int.max`.
+  /// - Returns: A new collection in which all occurrences of `other` in
+  /// `subrange` of the collection are replaced by `replacement`.
   public func replacing<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
@@ -79,7 +89,16 @@ extension RangeReplaceableCollection where Element: Equatable {
       subrange: subrange,
       maxReplacements: maxReplacements)
   }
-  
+
+  /// Returns a new collection in which all occurrences of a target sequence
+  /// are replaced by another collection.
+  /// - Parameters:
+  ///   - other: The sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - maxReplacements: A number specifying how many occurrences of `other`
+  ///   to replace. Default is `Int.max`.
+  /// - Returns: A new collection in which all occurrences of `other` in
+  /// `subrange` of the collection are replaced by `replacement`.
   public func replacing<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
@@ -91,7 +110,13 @@ extension RangeReplaceableCollection where Element: Equatable {
       subrange: startIndex..<endIndex,
       maxReplacements: maxReplacements)
   }
-  
+
+  /// Replaces all occurrences of a target sequence with a given collection
+  /// - Parameters:
+  ///   - other: The sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - maxReplacements: A number specifying how many occurrences of `other`
+  ///   to replace. Default is `Int.max`.
   public mutating func replace<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
@@ -108,7 +133,7 @@ extension RangeReplaceableCollection where Element: Equatable {
 extension RangeReplaceableCollection
   where Self: BidirectionalCollection, Element: Comparable
 {
-  public func replacing<S: Sequence, Replacement: Collection>(
+  func replacing<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
     subrange: Range<Index>,
@@ -121,7 +146,7 @@ extension RangeReplaceableCollection
       maxReplacements: maxReplacements)
   }
 
-  public func replacing<S: Sequence, Replacement: Collection>(
+  func replacing<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
     maxReplacements: Int = .max
@@ -133,7 +158,7 @@ extension RangeReplaceableCollection
       maxReplacements: maxReplacements)
   }
 
-  public mutating func replace<S: Sequence, Replacement: Collection>(
+  mutating func replace<S: Sequence, Replacement: Collection>(
     _ other: S,
     with replacement: Replacement,
     maxReplacements: Int = .max
@@ -149,6 +174,16 @@ extension RangeReplaceableCollection
 // MARK: Regex algorithms
 
 extension RangeReplaceableCollection where SubSequence == Substring {
+  /// Returns a new collection in which all occurrences of a sequence matching
+  /// the given regex are replaced by another collection.
+  /// - Parameters:
+  ///   - regex: A regex describing the sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - subrange: The range in the collection in which to search for `regex`.
+  ///   - maxReplacements: A number specifying how many occurrences of the
+  ///   sequence matching `regex` to replace. Default is `Int.max`.
+  /// - Returns: A new collection in which all occurrences of subsequence
+  /// matching `regex` in `subrange` are replaced by `replacement`.
   public func replacing<R: RegexComponent, Replacement: Collection>(
     _ regex: R,
     with replacement: Replacement,
@@ -161,7 +196,16 @@ extension RangeReplaceableCollection where SubSequence == Substring {
       subrange: subrange,
       maxReplacements: maxReplacements)
   }
-  
+
+  /// Returns a new collection in which all occurrences of a sequence matching
+  /// the given regex are replaced by another collection.
+  /// - Parameters:
+  ///   - regex: A regex describing the sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - maxReplacements: A number specifying how many occurrences of the
+  ///   sequence matching `regex` to replace. Default is `Int.max`.
+  /// - Returns: A new collection in which all occurrences of subsequence
+  /// matching `regex` are replaced by `replacement`.
   public func replacing<R: RegexComponent, Replacement: Collection>(
     _ regex: R,
     with replacement: Replacement,
@@ -173,7 +217,14 @@ extension RangeReplaceableCollection where SubSequence == Substring {
       subrange: startIndex..<endIndex,
       maxReplacements: maxReplacements)
   }
-  
+
+  /// Replaces all occurrences of the sequence matching the given regex with
+  /// a given collection.
+  /// - Parameters:
+  ///   - regex: A regex describing the sequence to replace.
+  ///   - replacement: The new elements to add to the collection.
+  ///   - maxReplacements: A number specifying how many occurrences of the
+  ///   sequence matching `regex` to replace. Default is `Int.max`.
   public mutating func replace<R: RegexComponent, Replacement: Collection>(
     _ regex: R,
     with replacement: Replacement,