From 566a20f0127c57da76d45cafb58cd24ce00c9b55 Mon Sep 17 00:00:00 2001 From: Nate Cook Date: Sun, 24 Apr 2022 01:17:40 -0500 Subject: [PATCH] Update and sync documentation. --- .../Evolution/StringProcessingAlgorithms.md | 301 ++++++++++-------- .../Algorithms/Algorithms/Contains.swift | 17 +- .../Algorithms/Algorithms/FirstRange.swift | 25 +- .../Algorithms/Algorithms/Ranges.swift | 21 +- .../Algorithms/Algorithms/Replace.swift | 89 +++--- .../Algorithms/Algorithms/Split.swift | 29 +- .../Algorithms/Algorithms/StartsWith.swift | 11 +- .../Algorithms/Algorithms/Trim.swift | 73 +++-- .../Algorithms/Matching/FirstMatch.swift | 7 +- .../Algorithms/Matching/MatchReplace.swift | 47 +-- .../Algorithms/Matching/Matches.swift | 7 +- 11 files changed, 366 insertions(+), 261 deletions(-) diff --git a/Documentation/Evolution/StringProcessingAlgorithms.md b/Documentation/Evolution/StringProcessingAlgorithms.md index 6c591c268..b2c4fcc90 100644 --- a/Documentation/Evolution/StringProcessingAlgorithms.md +++ b/Documentation/Evolution/StringProcessingAlgorithms.md @@ -230,20 +230,21 @@ let regex = Regex { ```swift 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`. public func contains(_ other: C) -> Bool where S.Element == Element } 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`. public func contains(_ regex: some RegexComponent) -> Bool } ``` @@ -252,11 +253,12 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift 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(with regex: some RegexComponent) -> Bool } ``` @@ -267,9 +269,10 @@ extension BidirectionalCollection where SubSequence == Substring { extension Collection { /// Returns a new collection of the same type by removing initial elements /// that satisfy the given predicate from the start. - /// - Parameter predicate: A closure that takes an element of the sequence + /// + /// - Parameter predicate: A closure that takes an element of the collection /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. + /// element should be removed. /// - Returns: A collection containing the elements of the collection that are /// not removed by `predicate`. public func trimmingPrefix(while predicate: (Element) throws -> Bool) rethrows -> SubSequence @@ -277,60 +280,75 @@ extension Collection { extension Collection where SubSequence == Self { /// Removes the initial elements that satisfy the given predicate from the - /// start of the sequence. - /// - Parameter predicate: A closure that takes an element of the sequence - /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. + /// start of this collection. + /// + /// - Parameter predicate: A closure that takes an element of the collection + /// as its argument and returns a Boolean value indicating whether the + /// element should be removed. public mutating func trimPrefix(while predicate: (Element) throws -> Bool) rethrows } extension RangeReplaceableCollection { /// Removes the initial elements that satisfy the given predicate from the - /// start of the sequence. - /// - Parameter predicate: A closure that takes an element of the sequence - /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. + /// start of this collection. + /// + /// - Parameter predicate: A closure that takes an element of the collection + /// as its argument and returns a Boolean value indicating whether the + /// element should be removed. public mutating func trimPrefix(while predicate: (Element) throws -> Bool) rethrows } extension Collection where Element: Equatable { - /// Returns a new collection of the same type by removing `prefix` from the - /// start. - /// - Parameter prefix: The collection to remove from this collection. - /// - Returns: A collection containing the elements that does not match - /// `prefix` from the start. + /// Returns a subsequence of this collection by removing the given prefix + /// from the start. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. + /// - Returns: A collection with `prefix` removed from the start. If the + /// entirety of `prefix` does not match the start of this collection, the + /// full contents of this collection are returned. public func trimmingPrefix(_ prefix: Prefix) -> SubSequence where Prefix.Element == Element } extension Collection where SubSequence == Self, Element: Equatable { - /// Removes the initial elements that matches `prefix` from the start. - /// - Parameter prefix: The collection to remove from this collection. + /// Removes the given prefix from the start of this collection, if the prefix + /// is present. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. public mutating func trimPrefix(_ prefix: Prefix) where Prefix.Element == Element } extension RangeReplaceableCollection where Element: Equatable { - /// Removes the initial elements that matches `prefix` from the start. - /// - Parameter prefix: The collection to remove from this collection. + /// Removes the given prefix from the start of this collection, if the prefix + /// is present. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. public mutating func trimPrefix(_ prefix: Prefix) where Prefix.Element == Element } extension BidirectionalCollection where SubSequence == Substring { - /// Returns a new subsequence by removing the initial elements that matches - /// the given regex. - /// - Parameter regex: The regex to remove from this collection. - /// - Returns: A new subsequence containing the elements of the collection - /// that does not match `prefix` from the start. + /// Returns a subsequence of this collection by removing the elements matching + /// the given regex from the start. + /// + /// - Parameter regex: A regex to search for at the start of this collection. + /// - Returns: A collection containing the elements after those that match + /// `regex`. If `regex` does not match at the start of the collection, the + /// entire contents of this collection are returned. public func trimmingPrefix(_ regex: some RegexComponent) -> SubSequence } extension RangeReplaceableCollection where Self: BidirectionalCollection, SubSequence == Substring { - /// Removes the initial elements that matches the given regex. - /// - Parameter regex: The regex to remove from this collection. + /// Removes the initial elements matching the given regex from the start of + /// this collection, if the initial elements match. + /// + /// - Parameter regex: A regex to search for at the start of this collection. public mutating func trimPrefix(_ regex: some RegexComponent) } ``` @@ -339,31 +357,34 @@ extension RangeReplaceableCollection ```swift 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. + /// 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 `other`. + /// Returns `nil` if `other` is not found. public func firstRange(of other: C) -> Range? where C.Element == Element } 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. + /// 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 `other`. + /// Returns `nil` if `other` is not found. public func firstRange(of other: C) -> Range? where C.Element == Element } 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. public func firstRange(of regex: some RegexComponent) -> Range? } ``` @@ -372,21 +393,23 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift extension Collection where Element: Equatable { - /// 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. + /// Finds and 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. public func ranges(of other: C) -> some Collection> where C.Element == Element } extension BidirectionalCollection where SubSequence == Substring { - /// 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. public func ranges(of regex: some RegexComponent) -> some Collection> } ``` @@ -395,10 +418,11 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift extension BidirectionalCollection where SubSequence == Substring { - /// Returns the first match of the specified regex within the collection. + /// Returns the first match for the given regex within this collection. + /// /// - Parameter regex: The regex to search for. - /// - Returns: The first match of `regex` in the collection, or `nil` if - /// there isn't a match. + /// - Returns: The first match for `regex` in this collection, or `nil` if + /// no match is found. public func firstMatch(of regex: R) -> Regex.Match? /// Match a regex in its entirety. @@ -417,9 +441,12 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift extension BidirectionalCollection where SubSequence == Substring { - /// Returns a collection containing all matches of the specified regex. + /// Returns a collection containing all non-overlapping matches of the + /// given regex. + /// /// - Parameter regex: The regex to search for. - /// - Returns: A collection of matches of `regex`. + /// - Returns: A collection of matches for `regex` If no matches are found, + /// the returned collection is empty. public func matches(of regex: R) -> some Collection.Match> } ``` @@ -428,16 +455,18 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift 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`. public func replacing( _ other: C, with replacement: Replacement, @@ -445,27 +474,31 @@ extension RangeReplaceableCollection where Element: Equatable { maxReplacements: Int = .max ) -> Self where C.Element == Element, Replacement.Element == Element - /// 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`. public func replacing( _ other: C, with replacement: Replacement, maxReplacements: Int = .max ) -> Self where C.Element == Element, Replacement.Element == Element - /// 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. public mutating func replace( _ other: C, with replacement: Replacement, @@ -474,16 +507,18 @@ extension RangeReplaceableCollection where Element: Equatable { } 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`. public func replacing( _ r: some RegexComponent, with replacement: Replacement, @@ -491,45 +526,49 @@ extension RangeReplaceableCollection where SubSequence == Substring { maxReplacements: Int = .max ) -> Self where Replacement.Element == Element - /// 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`. public func replacing( _ r: some RegexComponent, with replacement: Replacement, maxReplacements: Int = .max ) -> Self where Replacement.Element == Element - /// 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. public mutating func replace( _ r: some RegexComponent, with replacement: Replacement, maxReplacements: Int = .max ) where Replacement.Element == Element - /// Returns a new collection in which all occurrences of a sequence matching - /// the given regex are replaced by another regex match. + /// Returns a new collection in which all matches for the given regex + /// are replaced, using the given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. + /// - regex: The collection to to search for and replace. /// - 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`. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. - /// - Returns: A new collection in which all occurrences of subsequence - /// matching `regex` are replaced by `replacement`. + /// including captures, and returns a replacement collection. + /// - Returns: A new collection in which all matches for `regex` in + /// `subrange` are replaced by the result of calling `replacement`. public func replacing( _ regex: R, subrange: Range, @@ -537,30 +576,32 @@ extension RangeReplaceableCollection where SubSequence == Substring { with replacement: (Regex.Match) throws -> Replacement ) rethrows -> Self where Replacement.Element == Element - /// 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, using the given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. - /// - 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. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. - /// - Returns: A new collection in which all occurrences of subsequence - /// matching `regex` are replaced by `replacement`. + /// including captures, and returns a replacement collection. + /// - Returns: A new collection in which all matches for `regex` are replaced + /// by the result of calling `replacement`. public func replacing( _ regex: R, maxReplacements: Int = .max, with replacement: (Regex.Match) throws -> Replacement ) rethrows -> Self where Replacement.Element == Element - /// Replaces all occurrences of the sequence matching the given regex with - /// a given collection. + /// Replaces all matches for the given regex in this collection, using the + /// given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. - /// - 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. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. + /// including captures, and returns a replacement collection. public mutating func replace( _ regex: R, maxReplacements: Int = .max, @@ -620,8 +661,8 @@ extension BidirectionalCollection where SubSequence == Substring { ```swift 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. public func replacing( _ other: some Collection, with replacement: some Collection, diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/Contains.swift b/Sources/_StringProcessing/Algorithms/Algorithms/Contains.swift index 2a1ef72a2..0bbd2afe0 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/Contains.swift +++ b/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(_ 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(_ regex: R) -> Bool { contains(RegexConsumer(regex)) diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/FirstRange.swift b/Sources/_StringProcessing/Algorithms/Algorithms/FirstRange.swift index 42703827e..47ca9dd35 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/FirstRange.swift +++ b/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( 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( 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(of regex: R) -> Range? { firstRange(of: RegexConsumer(regex)) diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift b/Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift index 33a9748ac..bf8923f53 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift +++ b/Sources/_StringProcessing/Algorithms/Algorithms/Ranges.swift @@ -182,11 +182,12 @@ extension Collection where Element: Equatable { } // FIXME: Return `some Collection>` 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( of other: C @@ -245,12 +246,12 @@ extension BidirectionalCollection where SubSequence == Substring { } // FIXME: Return `some Collection>` 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( of regex: R diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/Replace.swift b/Sources/_StringProcessing/Algorithms/Algorithms/Replace.swift index 217fb90d6..d520b08a1 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/Replace.swift +++ b/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( _ 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( _ 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( _ 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( _ 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( _ 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( _ regex: R, diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/Split.swift b/Sources/_StringProcessing/Algorithms/Algorithms/Split.swift index 97d8c80dd..b74d3b06b 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/Split.swift +++ b/Sources/_StringProcessing/Algorithms/Algorithms/Split.swift @@ -298,10 +298,19 @@ extension Collection where Element: Equatable { // FIXME: Return `some Collection` 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( separator: C, @@ -372,10 +381,18 @@ extension BidirectionalCollection where SubSequence == Substring { // FIXME: Return `some Collection` 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( separator: R, diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/StartsWith.swift b/Sources/_StringProcessing/Algorithms/Algorithms/StartsWith.swift index 0dd91f360..e15000749 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/StartsWith.swift +++ b/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(with regex: R) -> Bool { starts(with: RegexConsumer(regex)) } diff --git a/Sources/_StringProcessing/Algorithms/Algorithms/Trim.swift b/Sources/_StringProcessing/Algorithms/Algorithms/Trim.swift index 7411236da..2031d049b 100644 --- a/Sources/_StringProcessing/Algorithms/Algorithms/Trim.swift +++ b/Sources/_StringProcessing/Algorithms/Algorithms/Trim.swift @@ -106,6 +106,14 @@ extension Collection { try firstIndex(where: { try !predicate($0) }) ?? endIndex } + /// Returns a new collection of the same type by removing initial elements + /// that satisfy the given predicate from the start. + /// + /// - Parameter predicate: A closure that takes an element of the collection + /// as its argument and returns a Boolean value indicating whether the + /// element should be removed. + /// - Returns: A collection containing the elements of the collection that are + /// not removed by `predicate`. @available(SwiftStdlib 5.7, *) public func trimmingPrefix( while predicate: (Element) throws -> Bool @@ -116,6 +124,12 @@ extension Collection { } extension Collection where SubSequence == Self { + /// Removes the initial elements that satisfy the given predicate from the + /// start of this collection. + /// + /// - Parameter predicate: A closure that takes an element of the collection + /// as its argument and returns a Boolean value indicating whether the + /// element should be removed. @available(SwiftStdlib 5.7, *) public mutating func trimPrefix( while predicate: (Element) throws -> Bool @@ -126,6 +140,12 @@ extension Collection where SubSequence == Self { } extension RangeReplaceableCollection { + /// Removes the initial elements that satisfy the given predicate from the + /// start of this collection. + /// + /// - Parameter predicate: A closure that takes an element of the collection + /// as its argument and returns a Boolean value indicating whether the + /// element should be removed. @_disfavoredOverload @available(SwiftStdlib 5.7, *) public mutating func trimPrefix( @@ -186,13 +206,14 @@ extension RangeReplaceableCollection where Self: BidirectionalCollection { // MARK: Fixed pattern algorithms extension Collection where Element: Equatable { - /// Returns a new collection of the same type by removing initial elements - /// that satisfy the given predicate from the start. - /// - Parameter predicate: A closure that takes an element of the sequence - /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. - /// - Returns: A collection containing the elements of the collection that are - /// not removed by `predicate`. + /// Returns a subsequence of this collection by removing the given prefix + /// from the start, if the prefix is present. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. + /// - Returns: A collection with `prefix` removed from the start. If the + /// entirety of `prefix` does not match the start of this collection, the + /// full contents of this collection are returned. @available(SwiftStdlib 5.7, *) public func trimmingPrefix( _ prefix: Prefix @@ -202,11 +223,11 @@ extension Collection where Element: Equatable { } extension Collection where SubSequence == Self, Element: Equatable { - /// Removes the initial elements that satisfy the given predicate from the - /// start of the sequence. - /// - Parameter predicate: A closure that takes an element of the sequence - /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. + /// Removes the given prefix from the start of this collection, if the prefix + /// is present. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. @available(SwiftStdlib 5.7, *) public mutating func trimPrefix( _ prefix: Prefix @@ -217,11 +238,11 @@ extension Collection where SubSequence == Self, Element: Equatable { extension RangeReplaceableCollection where Element: Equatable { @_disfavoredOverload - /// Removes the initial elements that satisfy the given predicate from the - /// start of the sequence. - /// - Parameter predicate: A closure that takes an element of the sequence - /// as its argument and returns a Boolean value indicating whether the - /// element should be removed from the collection. + /// Removes the given prefix from the start of this collection, if the prefix + /// is present. + /// + /// - Parameter prefix: A sequence of elements to remove from the start of + /// this collection. @available(SwiftStdlib 5.7, *) public mutating func trimPrefix( _ prefix: Prefix @@ -285,11 +306,13 @@ extension RangeReplaceableCollection // MARK: Regex algorithms extension BidirectionalCollection where SubSequence == Substring { - /// Returns a new collection of the same type by removing `prefix` from the - /// start. - /// - Parameter prefix: The collection to remove from this collection. - /// - Returns: A collection containing the elements that does not match - /// `prefix` from the start. + /// Returns a subsequence of this collection by removing the elements matching + /// the given regex from the start. + /// + /// - Parameter regex: A regex to search for at the start of this collection. + /// - Returns: A collection containing the elements after those that match + /// `regex`. If `regex` does not match at the start of the collection, the + /// entire contents of this collection are returned. @available(SwiftStdlib 5.7, *) public func trimmingPrefix(_ regex: R) -> SubSequence { trimmingPrefix(RegexConsumer(regex)) @@ -309,8 +332,10 @@ extension BidirectionalCollection where SubSequence == Substring { extension RangeReplaceableCollection where Self: BidirectionalCollection, SubSequence == Substring { - /// Removes the initial elements that matches the given regex. - /// - Parameter regex: The regex to remove from this collection. + /// Removes the initial elements matching the given regex from the start of + /// this collection, if the initial elements match. + /// + /// - Parameter regex: A regex to search for at the start of this collection. @available(SwiftStdlib 5.7, *) public mutating func trimPrefix(_ regex: R) { trimPrefix(RegexConsumer(regex)) diff --git a/Sources/_StringProcessing/Algorithms/Matching/FirstMatch.swift b/Sources/_StringProcessing/Algorithms/Matching/FirstMatch.swift index 4342391af..72417de3c 100644 --- a/Sources/_StringProcessing/Algorithms/Matching/FirstMatch.swift +++ b/Sources/_StringProcessing/Algorithms/Matching/FirstMatch.swift @@ -53,10 +53,11 @@ extension BidirectionalCollection where SubSequence == Substring { lastMatch(of: RegexConsumer(regex)) } - /// Returns the first match of the specified regex within the collection. + /// Returns the first match for the given regex within this collection. + /// /// - Parameter regex: The regex to search for. - /// - Returns: The first match of `regex` in the collection, or `nil` if - /// there isn't a match. + /// - Returns: The first match for `regex` in this collection, or `nil` if + /// no match is found. @available(SwiftStdlib 5.7, *) public func firstMatch( of r: R diff --git a/Sources/_StringProcessing/Algorithms/Matching/MatchReplace.swift b/Sources/_StringProcessing/Algorithms/Matching/MatchReplace.swift index 206d68554..3867a682e 100644 --- a/Sources/_StringProcessing/Algorithms/Matching/MatchReplace.swift +++ b/Sources/_StringProcessing/Algorithms/Matching/MatchReplace.swift @@ -114,17 +114,18 @@ 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 regex match. + /// Returns a new collection in which all matches for the given regex + /// are replaced, using the given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. + /// - regex: The collection to to search for and replace. /// - 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`. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. - /// - Returns: A new collection in which all occurrences of subsequence - /// matching `regex` are replaced by `replacement`. + /// including captures, and returns a replacement collection. + /// - Returns: A new collection in which all matches for `regex` in + /// `subrange` are replaced by the result of calling `replacement`. @available(SwiftStdlib 5.7, *) public func replacing( _ regex: R, @@ -151,16 +152,17 @@ extension RangeReplaceableCollection where SubSequence == Substring { return result } - /// 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, using the given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. - /// - 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. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. - /// - Returns: A new collection in which all occurrences of subsequence - /// matching `regex` are replaced by `replacement`. + /// including captures, and returns a replacement collection. + /// - Returns: A new collection in which all matches for `regex` are replaced + /// by the result of calling `replacement`. @available(SwiftStdlib 5.7, *) public func replacing( _ regex: R, @@ -174,14 +176,15 @@ extension RangeReplaceableCollection where SubSequence == Substring { with: replacement) } - /// Replaces all occurrences of the sequence matching the given regex with - /// a given collection. + /// Replaces all matches for the given regex in this collection, using the + /// given closure to create the replacement. + /// /// - Parameters: - /// - regex: A regex describing the sequence to replace. - /// - 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. + /// - maxReplacements: A number specifying how many occurrences of `regex` + /// to replace. /// - replacement: A closure that receives the full match information, - /// including captures, and returns a replacement collection. + /// including captures, and returns a replacement collection. @available(SwiftStdlib 5.7, *) public mutating func replace( _ regex: R, diff --git a/Sources/_StringProcessing/Algorithms/Matching/Matches.swift b/Sources/_StringProcessing/Algorithms/Matching/Matches.swift index f038616fe..25c4174ff 100644 --- a/Sources/_StringProcessing/Algorithms/Matching/Matches.swift +++ b/Sources/_StringProcessing/Algorithms/Matching/Matches.swift @@ -200,9 +200,12 @@ extension BidirectionalCollection where SubSequence == Substring { } // FIXME: Return `some Collection.Match> for SE-0346 - /// Returns a collection containing all matches of the specified regex. + /// Returns a collection containing all non-overlapping matches of the + /// given regex. + /// /// - Parameter regex: The regex to search for. - /// - Returns: A collection of matches of `regex`. + /// - Returns: A collection of matches for `regex`. If no matches are found, + /// the returned collection is empty. @available(SwiftStdlib 5.7, *) public func matches( of r: R