enumerateMatches(in:options:range:using:)
Enumerates the string allowing the Block to handle each regular expression match.
Declaration
func enumerateMatches(in string: String, options: NSRegularExpression.MatchingOptions = [], range: NSRange, using block: (NSTextCheckingResult?, NSRegularExpression.MatchingFlags, UnsafeMutablePointer<ObjCBool>) -> Void)Parameters
- string:
The string.
- options:
The matching options to report. See Matchingoptions for the supported values.
- range:
The range of the string to test.
- block:
The Block enumerates the matches of the regular expression in the string.
The block takes three arguments:
- result
An Nstextcheckingresult specifying the match. This result gives the overall matched range via its Range property, and the range of each individual capture group via its Range(at:) method. The range {
NSNotFound, 0} is returned if one of the capture groups did not participate in this particular match.- flags
The current state of the matching progress. See Matchingflags for the possible values.
- stop
A reference to a Boolean value. The Block can set the value to True to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to True within the Block.
The Block returns void.
Discussion
This method is the fundamental matching method for regular expressions and is suitable for overriding by subclassers. There are additional convenience methods for returning all the matches as an array, the total number of matches, the first match, and the range of the first match.
By default, the Block iterator method calls the Block precisely once for each match, with a non-nil result and the appropriate flags. The client may then stop the operation by setting the contents of stop to true. The stop argument is an out-only argument. You should only ever set this Boolean to true within the Block.
If the reportProgress matching option is specified, the Block will also be called periodically during long-running match operations, with nil result and progress matching flag set in the Block’s flags parameter, at which point the client may again stop the operation by setting the contents of stop to true.
If the reportCompletion matching option is specified, the Block object will be called once after matching is complete, with nil result and the completed matching flag is set in the flags passed to the Block, plus any additional relevant NSRegularExpression.MatchingFlags from among hitEnd, requiredEnd, or internalError.
progress and completed matching flags have no effect for methods other than this method.
The hitEnd matching flag is set in the flags passed to the Block if the current match operation reached the end of the search range. The requiredEnd matching flag is set in the flags passed to the Block if the current match depended on the location of the end of the search range.
The NSRegularExpression.MatchingFlags matching flag is set in the flags passed to the block if matching failed due to an internal error (such as an expression requiring exponential memory allocations) without examining the entire search range.
The anchored, withTransparentBounds, and withoutAnchoringBounds regular expression options, specified in the options property specified when the regular expression instance is created, can apply to any match or replace method.
If anchored matching option is specified, matches are limited to those at the start of the search range.
If withTransparentBounds matching option is specified, matching may examine parts of the string beyond the bounds of the search range, for purposes such as word boundary detection, lookahead, etc.
If withoutAnchoringBounds matching option is specified, ^ and $ will not automatically match the beginning and end of the search range, but will still match the beginning and end of the entire string.
withTransparentBounds and withoutAnchoringBounds matching options have no effect if the search range covers the entire string.