Add maxSplits and omitEmpty to split methods

This plumbs those parameters down into the SplitCollection type,
and removes Collection conformance for now because (a) we aren't
using it, and (b) it looks tricky to implement properly.

Author: natecook1000

Sources/_StringProcessing/Algorithms/Algorithms/Split.swift

@@ -15,13 +15,28 @@ struct SplitCollection<Searcher: CollectionSearcher> {
   public typealias Base = Searcher.Searched
 
   let ranges: RangesCollection<Searcher>
-  
-  init(ranges: RangesCollection<Searcher>) {
+  var maxSplits: Int
+  var omittingEmptySubsequences: Bool
+
+  init(
+    ranges: RangesCollection<Searcher>,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool)
+  {
     self.ranges = ranges
+    self.maxSplits = maxSplits
+    self.omittingEmptySubsequences = omittingEmptySubsequences
   }
 
-  init(base: Base, searcher: Searcher) {
+  init(
+    base: Base,
+    searcher: Searcher,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool)
+  {
     self.ranges = base.ranges(of: searcher)
+    self.maxSplits = maxSplits
+    self.omittingEmptySubsequences = omittingEmptySubsequences
   }
 }
 
@@ -30,97 +45,127 @@ extension SplitCollection: Sequence {
     let base: Base
     var index: Base.Index
     var ranges: RangesCollection<Searcher>.Iterator
-    var isDone: Bool
-    
-    init(ranges: RangesCollection<Searcher>) {
+    var maxSplits: Int
+    var omittingEmptySubsequences: Bool
+
+    var splitCounter = 0
+    var isDone = false
+
+    init(
+      ranges: RangesCollection<Searcher>,
+      maxSplits: Int,
+      omittingEmptySubsequences: Bool
+    ) {
       self.base = ranges.base
       self.index = base.startIndex
       self.ranges = ranges.makeIterator()
-      self.isDone = false
+      self.maxSplits = maxSplits
+      self.omittingEmptySubsequences = omittingEmptySubsequences
     }
 
     public mutating func next() -> Base.SubSequence? {
       guard !isDone else { return nil }
 
-      guard let range = ranges.next() else {
+      /// Return the rest of base if it's non-empty or we're including
+      /// empty subsequences.
+      func finish() -> Base.SubSequence? {
         isDone = true
-        return base[index...]
+        return index == base.endIndex && omittingEmptySubsequences
+          ? nil
+          : base[index...]
+      }
+      
+      if splitCounter >= maxSplits {
+        return finish()
       }
 
-      defer { index = range.upperBound }
-      return base[index..<range.lowerBound]
+      while true {
+        // If there are no more ranges that matched, return the rest of `base`.
+        guard let range = ranges.next() else {
+          return finish()
+        }
+        
+        defer { index = range.upperBound }
+
+        if omittingEmptySubsequences && index == range.lowerBound {
+          continue
+        }
+        
+        splitCounter += 1
+        return base[index..<range.lowerBound]
+      }
     }
   }
 
   public func makeIterator() -> Iterator {
-    Iterator(ranges: ranges)
-  }
-}
-
-extension SplitCollection: Collection {
-  public struct Index {
-    var start: Base.Index
-    var base: RangesCollection<Searcher>.Index
-    var isEndIndex: Bool
-  }
-
-  public var startIndex: Index {
-    let base = ranges.startIndex
-    return Index(start: ranges.base.startIndex, base: base, isEndIndex: false)
-  }
-
-  public var endIndex: Index {
-    Index(start: ranges.base.endIndex, base: ranges.endIndex, isEndIndex: true)
-  }
-
-  public func formIndex(after index: inout Index) {
-    guard !index.isEndIndex else { fatalError("Cannot advance past endIndex") }
-
-    if let range = index.base.range {
-      let newStart = range.upperBound
-      ranges.formIndex(after: &index.base)
-      index.start = newStart
-    } else {
-      index.isEndIndex = true
-    }
-  }
-
-  public func index(after index: Index) -> Index {
-    var index = index
-    formIndex(after: &index)
-    return index
-  }
-
-  public subscript(index: Index) -> Base.SubSequence {
-    guard !index.isEndIndex else {
-      fatalError("Cannot subscript using endIndex")
-    }
-    let end = index.base.range?.lowerBound ?? ranges.base.endIndex
-    return ranges.base[index.start..<end]
+    Iterator(ranges: ranges, maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 }
 
-extension SplitCollection.Index: Comparable {
-   static func == (lhs: Self, rhs: Self) -> Bool {
-    switch (lhs.isEndIndex, rhs.isEndIndex) {
-    case (false, false):
-      return lhs.start == rhs.start
-    case (let lhs, let rhs):
-      return lhs == rhs
-    }
-  }
-
-  static func < (lhs: Self, rhs: Self) -> Bool {
-    switch (lhs.isEndIndex, rhs.isEndIndex) {
-    case (true, _):
-      return false
-    case (_, true):
-      return true
-    case (false, false):
-      return lhs.start < rhs.start
-    }
-  }
-}
+//extension SplitCollection: Collection {
+//  public struct Index {
+//    var start: Base.Index
+//    var base: RangesCollection<Searcher>.Index
+//    var isEndIndex: Bool
+//  }
+//
+//  public var startIndex: Index {
+//    let base = ranges.startIndex
+//    return Index(start: ranges.base.startIndex, base: base, isEndIndex: false)
+//  }
+//
+//  public var endIndex: Index {
+//    Index(start: ranges.base.endIndex, base: ranges.endIndex, isEndIndex: true)
+//  }
+//
+//  public func formIndex(after index: inout Index) {
+//    guard !index.isEndIndex else { fatalError("Cannot advance past endIndex") }
+//
+//    if let range = index.base.range {
+//      let newStart = range.upperBound
+//      ranges.formIndex(after: &index.base)
+//      index.start = newStart
+//    } else {
+//      index.isEndIndex = true
+//    }
+//  }
+//
+//  public func index(after index: Index) -> Index {
+//    var index = index
+//    formIndex(after: &index)
+//    return index
+//  }
+//
+//  public subscript(index: Index) -> Base.SubSequence {
+//    guard !index.isEndIndex else {
+//      fatalError("Cannot subscript using endIndex")
+//    }
+//    let end = index.base.range?.lowerBound ?? ranges.base.endIndex
+//    return ranges.base[index.start..<end]
+//  }
+//}
+//
+//extension SplitCollection.Index: Comparable {
+//   static func == (lhs: Self, rhs: Self) -> Bool {
+//    switch (lhs.isEndIndex, rhs.isEndIndex) {
+//    case (false, false):
+//      return lhs.start == rhs.start
+//    case (let lhs, let rhs):
+//      return lhs == rhs
+//    }
+//  }
+//
+//  static func < (lhs: Self, rhs: Self) -> Bool {
+//    switch (lhs.isEndIndex, rhs.isEndIndex) {
+//    case (true, _):
+//      return false
+//    case (_, true):
+//      return true
+//    case (false, false):
+//      return lhs.start < rhs.start
+//    }
+//  }
+//}
 
 // MARK: `ReversedSplitCollection`
 
@@ -176,10 +221,15 @@ extension ReversedSplitCollection: Sequence {
 
 extension Collection {
   func split<Searcher: CollectionSearcher>(
-    by separator: Searcher
+    by separator: Searcher,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
   ) -> SplitCollection<Searcher> where Searcher.Searched == Self {
-    // TODO: `maxSplits`, `omittingEmptySubsequences`?
-    SplitCollection(base: self, searcher: separator)
+    SplitCollection(
+      base: self,
+      searcher: separator,
+      maxSplits: maxSplits,
+      omittingEmptySubsequences: omittingEmptySubsequences)
   }
 }
 
@@ -198,9 +248,11 @@ extension BidirectionalCollection {
 extension Collection {
   // TODO: Non-escaping and throwing
   func split(
-    whereSeparator predicate: @escaping (Element) -> Bool
+    whereSeparator predicate: @escaping (Element) -> Bool,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
   ) -> SplitCollection<PredicateConsumer<Self>> {
-    split(by: PredicateConsumer(predicate: predicate))
+    split(by: PredicateConsumer(predicate: predicate), maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 }
 
@@ -216,9 +268,11 @@ extension BidirectionalCollection where Element: Equatable {
 
 extension Collection where Element: Equatable {
   func split(
-    by separator: Element
+    by separator: Element,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
   ) -> SplitCollection<PredicateConsumer<Self>> {
-    split(whereSeparator: { $0 == separator })
+    split(whereSeparator: { $0 == separator }, maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 }
 
@@ -234,10 +288,12 @@ extension BidirectionalCollection where Element: Equatable {
 
 extension Collection where Element: Equatable {
   @_disfavoredOverload
-  func split<S: Sequence>(
-    by separator: S
-  ) -> SplitCollection<ZSearcher<Self>> where S.Element == Element {
-    split(by: ZSearcher(pattern: Array(separator), by: ==))
+  func split<C: Collection>(
+    by separator: C,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
+  ) -> SplitCollection<ZSearcher<Self>> where C.Element == Element {
+    split(by: ZSearcher(pattern: Array(separator), by: ==), maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 
   // FIXME: Return `some Collection<SubSequence>` for SE-0346
@@ -247,10 +303,12 @@ extension Collection where Element: Equatable {
   /// - Returns: A collection of subsequences, split from this collection's
   /// elements.
   @available(SwiftStdlib 5.7, *)
-  public func split<S: Sequence>(
-    by separator: S
-  ) -> [SubSequence] where S.Element == Element {
-    Array(split(by: ZSearcher(pattern: Array(separator), by: ==)))
+  public func split<C: Collection>(
+    separator: C,
+    maxSplits: Int = .max,
+    omittingEmptySubsequences: Bool = true
+  ) -> [SubSequence] where C.Element == Element {
+    Array(split(by: ZSearcher(pattern: Array(separator), by: ==), maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences))
   }
 }
 
@@ -267,12 +325,15 @@ extension BidirectionalCollection where Element: Equatable {
 
 extension BidirectionalCollection where Element: Comparable {
   func split<C: Collection>(
-    by separator: C
+    by separator: C,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
   ) -> SplitCollection<PatternOrEmpty<TwoWaySearcher<Self>>>
     where C.Element == Element
   {
     split(
-      by: PatternOrEmpty(searcher: TwoWaySearcher(pattern: Array(separator))))
+      by: PatternOrEmpty(searcher: TwoWaySearcher(pattern: Array(separator))),
+    maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 
   // FIXME
@@ -292,9 +353,11 @@ extension BidirectionalCollection where Element: Comparable {
 extension BidirectionalCollection where SubSequence == Substring {
   @_disfavoredOverload
   func split<R: RegexComponent>(
-    by separator: R
+    by separator: R,
+    maxSplits: Int,
+    omittingEmptySubsequences: Bool
   ) -> SplitCollection<RegexConsumer<R, Self>> {
-    split(by: RegexConsumer(separator))
+    split(by: RegexConsumer(separator), maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences)
   }
 
   func splitFromBack<R: RegexComponent>(
@@ -303,15 +366,22 @@ extension BidirectionalCollection where SubSequence == Substring {
     splitFromBack(by: RegexConsumer(separator))
   }
 
-  // FIXME: Return `some Collection<Substring>` for SE-0346 
+  // TODO: Is this @_disfavoredOverload necessary?
+  // It prevents split(separator: String) from choosing this overload instead
+  // of the collection-based version when String has RegexComponent conformance
+
+  // FIXME: Return `some Collection<Subsequence>` for SE-0346
   /// Returns the longest possible subsequences of the collection, in order,
   /// around elements equal to the given separator.
   /// - Parameter separator: A regex describing elements to be split upon.
   /// - Returns: A collection of substrings, split from this collection's
   /// elements.
+  @_disfavoredOverload
   public func split<R: RegexComponent>(
-    by separator: R
+    separator: R,
+    maxSplits: Int = .max,
+    omittingEmptySubsequences: Bool = true
   ) -> [SubSequence] {
-    Array(split(by: RegexConsumer(separator)))
+    Array(split(by: RegexConsumer(separator), maxSplits: maxSplits, omittingEmptySubsequences: omittingEmptySubsequences))
   }
 }