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:(NSMatching Options)options range:(NSRange)range usingBlock:(void (^)(NSText Checking Result *result, NSMatching Flags flags, BOOL *stop))block;
Parameters
string
The string.
options
The matching options to report. See
NSMatching
for the supported values.Options 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
NSText
specifying the match. This result gives the overall matched range via itsChecking Result range
property, and the range of each individual capture group via itsrange
method. 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
NSMatching
for the possible values.Flags - stop
A reference to a Boolean value. The Block can set the value to
YES
to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYES
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 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.