Update and sync algorithms documentation

Sources/_StringProcessing/Algorithms/Algorithms/Contains.swift

@@ -23,10 +23,10 @@ extension Collection {
 
 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`.
+  /// given collection.
+  ///
+  /// - Parameter other: A collection to search for within this collection.
+  /// - Returns: `true` if the collection contains `other`, otherwise `false`.
   @available(SwiftStdlib 5.7, *)
   public func contains<C: Collection>(_ other: C) -> Bool
     where C.Element == Element
@@ -63,11 +63,12 @@ extension StringProtocol {
 // MARK: Regex algorithms
 
 extension BidirectionalCollection where SubSequence == Substring {
-  /// Returns a Boolean value indicating whether the collection contains the
-  /// given regex.
+  /// Returns a Boolean value indicating whether this collection contains a
+  /// match for 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`.
+  /// - Returns: `true` if `regex` matched anywhere in this collection,
+  ///   otherwise `false`.
   @available(SwiftStdlib 5.7, *)
   public func contains<R: RegexComponent>(_ regex: R) -> Bool {
     contains(RegexConsumer(regex))

Sources/_StringProcessing/Algorithms/Algorithms/FirstRange.swift

@@ -32,12 +32,12 @@ extension BidirectionalCollection {
 // MARK: Fixed pattern algorithms
 
 extension Collection where Element: Equatable {
-  /// Finds and returns the range of the first occurrence of a given collection
-  /// within this collection.
+  /// Returns the range of the first occurrence of the given collection within
+  /// this collection.
   ///
   /// - Parameter other: The collection to search for.
-  /// - Returns: A range in the collection of the first occurrence of `sequence`.
-  /// Returns nil if `sequence` is not found.
+  /// - Returns: A range in the collection of the first occurrence of `other`.
+  ///   Returns `nil` if `other` is not found.
   @available(SwiftStdlib 5.7, *)
   public func firstRange<C: Collection>(
     of other: C
@@ -49,12 +49,12 @@ extension Collection where Element: Equatable {
 }
 
 extension BidirectionalCollection where Element: Comparable {
-  /// Finds and returns the range of the first occurrence of a given collection
-  /// within this collection.
+  /// Returns the range of the first occurrence of the given collection within
+  /// this collection.
   ///
   /// - Parameter other: The collection to search for.
-  /// - Returns: A range in the collection of the first occurrence of `sequence`.
-  /// Returns `nil` if `sequence` is not found.
+  /// - Returns: A range in the collection of the first occurrence of `other`.
+  ///   Returns `nil` if `other` is not found.
   @available(SwiftStdlib 5.7, *)
   public func firstRange<C: Collection>(
     of other: C
@@ -70,11 +70,12 @@ 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.
+  /// Returns the range of the first match for the given regex within this
+  /// 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.
+  /// - Returns: A range in the collection of the first occurrence of the first
+  ///   match of `regex`. Returns `nil` if no match for `regex` is found.
   @available(SwiftStdlib 5.7, *)
   public func firstRange<R: RegexComponent>(of regex: R) -> Range<Index>? {
     firstRange(of: RegexConsumer(regex))

Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift

@@ -182,11 +182,12 @@ extension Collection where Element: Equatable {
   }
 
   // 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.
+  /// Returns the ranges of the all non-overlapping occurrences of the given
+  /// collection within this collection.
+  ///
+  /// - Parameter other: The collection to search for.
+  /// - Returns: A collection of ranges of all non-overlapping occurrences of
+  ///   `other`. Returns an empty collection if `other` is not found.
   @available(SwiftStdlib 5.7, *)
   public func ranges<C: Collection>(
     of other: C
@@ -245,12 +246,12 @@ extension BidirectionalCollection where SubSequence == Substring {
   }
 
   // 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.
-  /// 
+  /// Returns the ranges of the all non-overlapping matches for the given
+  /// regex within this 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.
+  /// - Returns: A collection of ranges of all matches for `regex`. Returns an
+  ///   empty collection if no match for `regex` is found.
   @available(SwiftStdlib 5.7, *)
   public func ranges<R: RegexComponent>(
     of regex: R

Sources/_StringProcessing/Algorithms/Algorithms/Replace.swift

@@ -67,16 +67,18 @@ 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.
+  /// Returns a new collection in which all occurrences of the given collection
+  /// are replaced.
+  ///
   /// - Parameters:
-  ///   - other: The sequence to replace.
-  ///   - replacement: The new elements to add to the collection.
+  ///   - other: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     `other`.
   ///   - 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`.
+  ///     to replace.
   /// - Returns: A new collection in which all occurrences of `other` in
-  /// `subrange` of the collection are replaced by `replacement`.
+  ///   `subrange` are replaced by `replacement`.
   @available(SwiftStdlib 5.7, *)
   public func replacing<C: Collection, Replacement: Collection>(
     _ other: C,
@@ -91,15 +93,17 @@ extension RangeReplaceableCollection where Element: Equatable {
       maxReplacements: maxReplacements)
   }
 
-  /// Returns a new collection in which all occurrences of a target sequence
-  /// are replaced by another collection.
+  /// Returns a new collection in which all occurrences of the given collection
+  /// are replaced.
+  ///
   /// - Parameters:
-  ///   - other: The sequence to replace.
-  ///   - replacement: The new elements to add to the collection.
+  ///   - other: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     `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`.
+  ///     to replace.
+  /// - Returns: A new collection in which all occurrences of `other` are
+  ///   replaced by `replacement`.
   @available(SwiftStdlib 5.7, *)
   public func replacing<C: Collection, Replacement: Collection>(
     _ other: C,
@@ -113,12 +117,14 @@ extension RangeReplaceableCollection where Element: Equatable {
       maxReplacements: maxReplacements)
   }
 
-  /// Replaces all occurrences of a target sequence with a given collection
+  /// Replaces all ocurrences of the given collection in this collection.
+  ///
   /// - Parameters:
-  ///   - other: The sequence to replace.
-  ///   - replacement: The new elements to add to the collection.
+  ///   - other: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     `other`.
   ///   - maxReplacements: A number specifying how many occurrences of `other`
-  ///   to replace. Default is `Int.max`.
+  ///     to replace.
   @available(SwiftStdlib 5.7, *)
   public mutating func replace<C: Collection, Replacement: Collection>(
     _ other: C,
@@ -177,16 +183,18 @@ 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.
+  /// Returns a new collection in which all matches for the given regex
+  /// are replaced.
+  ///
   /// - Parameters:
-  ///   - regex: A regex describing the sequence to replace.
-  ///   - replacement: The new elements to add to the collection.
+  ///   - regex: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     each match for `regex`.
   ///   - 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`.
+  ///   - maxReplacements: A number specifying how many occurrences of `regex`
+  ///     to replace.
+  /// - Returns: A new collection in which all matches for `regex` in
+  ///   `subrange` are replaced by `replacement`.
   @available(SwiftStdlib 5.7, *)
   public func replacing<R: RegexComponent, Replacement: Collection>(
     _ regex: R,
@@ -201,15 +209,17 @@ extension RangeReplaceableCollection where SubSequence == Substring {
       maxReplacements: maxReplacements)
   }
 
-  /// Returns a new collection in which all occurrences of a sequence matching
-  /// the given regex are replaced by another collection.
+  /// Returns a new collection in which all matches for the given regex
+  /// are replaced.
+  ///
   /// - 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`.
+  ///   - regex: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     each match for `regex`.
+  ///   - maxReplacements: A number specifying how many occurrences of `regex`
+  ///     to replace.
+  /// - Returns: A new collection in which all matches for `regex` are replaced
+  ///   by `replacement`.
   @available(SwiftStdlib 5.7, *)
   public func replacing<R: RegexComponent, Replacement: Collection>(
     _ regex: R,
@@ -223,13 +233,14 @@ extension RangeReplaceableCollection where SubSequence == Substring {
       maxReplacements: maxReplacements)
   }
 
-  /// Replaces all occurrences of the sequence matching the given regex with
-  /// a given collection.
+  /// Replaces all matches for the given regex in this 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`.
+  ///   - regex: The collection to to search for and replace.
+  ///   - replacement: The new elements to add to the collection in place of
+  ///     each match for `regex`.
+  ///   - maxReplacements: A number specifying how many occurrences of `regex`
+  ///     to replace.
   @available(SwiftStdlib 5.7, *)
   public mutating func replace<R: RegexComponent, Replacement: Collection>(
     _ regex: R,

Sources/_StringProcessing/Algorithms/Algorithms/Split.swift

@@ -298,10 +298,19 @@ extension Collection where Element: Equatable {
 
   // 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.
+  /// around elements equal to the given separator collection.
+  ///
+  /// - Parameters:
+  ///   - separator: A collection of elements to be split upon.
+  ///   - maxSplits: The maximum number of times to split the collection,
+  ///     or one less than the number of subsequences to return.
+  ///   - omittingEmptySubsequences: If `false`, an empty subsequence is
+  ///     returned in the result for each consecutive pair of separator
+  ///     sequences in the collection and for each instance of separator
+  ///     sequences at the start or end of the collection. If `true`, only
+  ///     nonempty subsequences are returned.
   /// - Returns: A collection of subsequences, split from this collection's
-  /// elements.
+  ///   elements.
   @available(SwiftStdlib 5.7, *)
   public func split<C: Collection>(
     separator: C,
@@ -372,10 +381,18 @@ extension BidirectionalCollection where SubSequence == Substring {
 
   // 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.
+  /// around subsequence that match the given separator regex.
+  ///
+  /// - Parameters:
+  ///   - separator: A regex to be split upon.
+  ///   - maxSplits: The maximum number of times to split the collection,
+  ///     or one less than the number of subsequences to return.
+  ///   - omittingEmptySubsequences: If `false`, an empty subsequence is
+  ///     returned in the result for each consecutive pair of matches
+  ///     and for each match at the start or end of the collection. If
+  ///     `true`, only nonempty subsequences are returned.
   /// - Returns: A collection of substrings, split from this collection's
-  /// elements.
+  ///   elements.
   @_disfavoredOverload
   public func split<R: RegexComponent>(
     separator: R,

Sources/_StringProcessing/Algorithms/Algorithms/StartsWith.swift

@@ -49,11 +49,12 @@ extension BidirectionalCollection where Element: Equatable {
 
 @available(SwiftStdlib 5.7, *)
 extension BidirectionalCollection where SubSequence == Substring {
-  /// Returns a Boolean value indicating whether the initial elements of the
-  /// sequence are the same as the elements in the specified regex.
-  /// - Parameter regex: A regex to compare to this sequence.
-  /// - Returns: `true` if the initial elements of the sequence matches the
-  /// beginning of `regex`; otherwise, `false`.
+  /// Returns a Boolean value indicating whether the initial elements of this
+  /// collection are a match for the given regex.
+  ///
+  /// - Parameter regex: A regex to match at the beginning of this collection.
+  /// - Returns: `true` if the initial elements of this collection match
+  ///   `regex`; otherwise, `false`.
   public func starts<R: RegexComponent>(with regex: R) -> Bool {
     starts(with: RegexConsumer(regex))
   }