Expose matches, ranges and split (#304)

* Expose `matches`, `ranges` and `split`

Publicize these API per the String Processing Algorithms proposal. The proposed
ones return generic `Collection`, empowered by SE-0346. For now we'll wrap the
results with a concrete `Array` until the language feature is ready.

Co-authored-by: Michael Ilseman <michael.ilseman@gmail.com>

Author: 2 people

Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift

@@ -175,12 +175,24 @@ extension BidirectionalCollection {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
-  // 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: ==))
   }
+
+  // FIXME: Return `some Collection<Range<Index>>` for SE-0346
+  /// Finds and returns the ranges of the all occurrences of a given sequence
+  /// within the collection.
+  /// - Parameter other: The sequence to search for.
+  /// - Returns: A collection of ranges of all occurrences of `other`. Returns
+  ///  an empty collection if `other` is not found.
+  @available(SwiftStdlib 5.7, *)
+  public func ranges<S: Sequence>(
+    of other: S
+  ) -> [Range<Index>] where S.Element == Element {
+    ranges(of: ZSearcher(pattern: Array(other), by: ==)).map { $0 }
+  }
 }
 
 extension BidirectionalCollection where Element: Equatable {
@@ -217,8 +229,8 @@ extension BidirectionalCollection where Element: Comparable {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
-  // FIXME: Replace `RangesCollection` when SE-0346 is enabled
   @available(SwiftStdlib 5.7, *)
+  @_disfavoredOverload
   func ranges<R: RegexComponent>(
     of regex: R
   ) -> RangesCollection<RegexConsumer<R, Self>> {
@@ -231,4 +243,17 @@ extension BidirectionalCollection where SubSequence == Substring {
   ) -> ReversedRangesCollection<RegexConsumer<R, Self>> {
     rangesFromBack(of: RegexConsumer(regex))
   }
+
+  // FIXME: Return `some Collection<Range<Index>>` for SE-0346
+  /// Finds and returns the ranges of the all occurrences of a given sequence
+  /// within the collection.
+  /// - Parameter regex: The regex to search for.
+  /// - Returns: A collection or ranges in the receiver of all occurrences of
+  /// `regex`. Returns an empty collection if `regex` is not found.
+  @available(SwiftStdlib 5.7, *)
+  public func ranges<R: RegexComponent>(
+    of regex: R
+  ) -> [Range<Index>] {
+    Array(ranges(of: RegexConsumer(regex)))
+  }
 }

Sources/_StringProcessing/Algorithms/Algorithms/Split.swift

@@ -233,16 +233,24 @@ extension BidirectionalCollection where Element: Equatable {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
-  // FIXME: Replace `SplitCollection` when SE-0346 is enabled
+  @_disfavoredOverload
+  func split<S: Sequence>(
+    by separator: S
+  ) -> SplitCollection<ZSearcher<Self>> where S.Element == Element {
+    split(by: ZSearcher(pattern: Array(separator), by: ==))
+  }
+
+  // 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: The element to be split upon.
   /// - Returns: A collection of subsequences, split from this collection's
   /// elements.
-  func split<S: Sequence>(
+  @available(SwiftStdlib 5.7, *)
+  public func split<S: Sequence>(
     by separator: S
-  ) -> SplitCollection<ZSearcher<Self>> where S.Element == Element {
-    split(by: ZSearcher(pattern: Array(separator), by: ==))
+  ) -> [SubSequence] where S.Element == Element {
+    Array(split(by: ZSearcher(pattern: Array(separator), by: ==)))
   }
 }
 
@@ -282,12 +290,7 @@ extension BidirectionalCollection where Element: Comparable {
 
 @available(SwiftStdlib 5.7, *)
 extension BidirectionalCollection where SubSequence == Substring {
-  // FIXME: Replace `SplitCollection` when SE-0346 is enabled
-  /// 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
   func split<R: RegexComponent>(
     by separator: R
   ) -> SplitCollection<RegexConsumer<R, Self>> {
@@ -299,4 +302,16 @@ extension BidirectionalCollection where SubSequence == Substring {
   ) -> ReversedSplitCollection<RegexConsumer<R, Self>> {
     splitFromBack(by: RegexConsumer(separator))
   }
+
+  // FIXME: Return `some Collection<Substring>` 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.
+  public func split<R: RegexComponent>(
+    by separator: R
+  ) -> [SubSequence] {
+    Array(split(by: RegexConsumer(separator)))
+  }
 }

Sources/_StringProcessing/Algorithms/Matching/MatchReplace.swift

@@ -139,7 +139,7 @@ extension RangeReplaceableCollection where SubSequence == Substring {
     var result = Self()
     result.append(contentsOf: self[..<index])
 
-    for match in self[subrange]._matches(of: regex)
+    for match in self[subrange].matches(of: regex)
       .prefix(maxReplacements)
     {
       result.append(contentsOf: self[index..<match.range.lowerBound])

Sources/_StringProcessing/Algorithms/Matching/Matches.swift

@@ -184,11 +184,8 @@ extension BidirectionalCollection {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
-  // FIXME: Replace `MatchesCollection` when SE-0346 is enabled
-  /// Returns a collection containing all matches of the specified regex.
-  /// - Parameter regex: The regex to search for.
-  /// - Returns: A collection of matches of `regex`.
   @available(SwiftStdlib 5.7, *)
+  @_disfavoredOverload
   func matches<R: RegexComponent>(
     of regex: R
   ) -> MatchesCollection<RegexConsumer<R, Self>> {
@@ -202,10 +199,14 @@ extension BidirectionalCollection where SubSequence == Substring {
     matchesFromBack(of: RegexConsumer(regex))
   }
 
-  // FIXME: Replace the returned value as `some Collection<Regex<R.Output>.Match>
-  // when SE-0346 is enabled
+  // FIXME: Return `some Collection<Regex<R.Output>.Match> for SE-0346
+  /// Returns a collection containing all matches of the specified regex.
+  /// - Parameter regex: The regex to search for.
+  /// - Returns: A collection of matches of `regex`.
   @available(SwiftStdlib 5.7, *)
-  func _matches<R: RegexComponent>(of r: R) -> [Regex<R.RegexOutput>.Match] {
+  public func matches<R: RegexComponent>(
+    of r: R
+  ) -> [Regex<R.RegexOutput>.Match] {
     let slice = self[...]
     var start = self.startIndex
     let end = self.endIndex

Tests/RegexBuilderTests/AlgorithmsTests.swift

@@ -15,13 +15,11 @@ import _StringProcessing
 
 @available(SwiftStdlib 5.7, *)
 class RegexConsumerTests: XCTestCase {
-  // FIXME: enable this test when we update the return type of `matches(of:)`
-  // when SE-0346 is available
-  //  func testMatches() {
-  //    let regex = Capture(OneOrMore(.digit)) { 2 * Int($0)! }
-  //    let str = "foo 160 bar 99 baz"
-  //    XCTAssertEqual(str.matches(of: regex).map(\.result.1), [320, 198])
-  //  }
+  func testMatches() {
+    let regex = Capture(OneOrMore(.digit)) { 2 * Int($0)! }
+    let str = "foo 160 bar 99 baz"
+    XCTAssertEqual(str.matches(of: regex).map(\.output.1), [320, 198])
+  }
 
   func testMatchReplace() {
     func replaceTest<R: RegexComponent>(

Tests/RegexTests/AlgorithmsTests.swift

@@ -163,13 +163,13 @@ class RegexConsumerTests: XCTestCase {
     XCTAssertEqual(s2.replacing(regex, with: ""), "")
 
     XCTAssertEqual(
-      s._matches(of: regex).map(\.0),
+      s.matches(of: regex).map(\.0),
       ["aaa", "aaaaaa", "aaaaaaaaaa"])
     XCTAssertEqual(
-      s1._matches(of: regex).map(\.0),
+      s1.matches(of: regex).map(\.0),
       ["aaaaaa", "aaaaaaaaaa"])
     XCTAssertEqual(
-      s2._matches(of: regex).map(\.0),
+      s2.matches(of: regex).map(\.0),
       ["aa"])
   }
 }