Enumerates the string allowing the Block to handle each regular expression match.
SDKs
- iOS 4.0+
- macOS 10.7+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
- (void)enumerateMatchesInString:(NSString *)string options:(NSMatchingParameters
stringThe string.
optionsThe matching options to report. See
NSMatchingfor the supported values.Options rangeThe range of the string to test.
blockThe Block enumerates the matches of the regular expression in the string.
The block takes three arguments:
- result
An
NSTextspecifying the match. This result gives the overall matched range via itsChecking Result rangeproperty, and the range of each individual capture group via itsrangemethod. The range {At Index: NSNot, 0} is returned if one of the capture groups did not participate in this particular match.Found - flags
The current state of the matching progress. See
NSMatchingfor the possible values.Flags - stop
A reference to a Boolean value. The Block can set the value to
YESto stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYESwithin 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 YES. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.
If the NSMatching matching option is specified, the Block will also be called periodically during long-running match operations, with nil result and NSMatching 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 YES.
If the NSMatching matching option is specified, the Block object will be called once after matching is complete, with nil result and the NSMatching matching flag is set in the flags passed to the Block, plus any additional relevant NSMatching from among NSMatching, NSMatching, or NSMatching.
NSMatching and NSMatching matching flags have no effect for methods other than this method.
The NSMatching matching flag is set in the flags passed to the Block if the current match operation reached the end of the search range. The NSMatching 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 NSMatching 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 NSMatching, NSMatching, and NSMatching 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 NSMatching matching option is specified, matches are limited to those at the start of the search range.
If NSMatching 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 NSMatching 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.
NSMatching and NSMatching matching options have no effect if the search range covers the entire string.