Instance Method

enumerateMatchesInString:options:range:usingBlock:

Enumerates the string allowing the Block to handle each regular expression match.

Declaration

- (void)enumerateMatchesInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range usingBlock:(void (^)(NSTextCheckingResult *result, NSMatchingFlags flags, BOOL *stop))block;

Parameters

string

The string.

options

The matching options to report. See NSMatchingOptions 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 rangeAtIndex: 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 NSMatchingFlags for the possible values.

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 to YES 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 NSMatchingReportProgress matching option is specified, the Block will also be called periodically during long-running match operations, with nil result and NSMatchingProgress 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 NSMatchingReportCompletion matching option is specified, the Block object will be called once after matching is complete, with nil result and the NSMatchingCompleted matching flag is set in the flags passed to the Block, plus any additional relevant NSMatchingFlags from among NSMatchingHitEnd, NSMatchingRequiredEnd, or NSMatchingInternalError.

NSMatchingProgress and NSMatchingCompleted matching flags have no effect for methods other than this method.

The NSMatchingHitEnd matching flag is set in the flags passed to the Block if the current match operation reached the end of the search range. The NSMatchingRequiredEnd 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 NSMatchingFlags 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 NSMatchingAnchored, NSMatchingWithTransparentBounds, and NSMatchingWithoutAnchoringBounds 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 NSMatchingAnchored matching option is specified, matches are limited to those at the start of the search range.

If NSMatchingWithTransparentBounds 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 NSMatchingWithoutAnchoringBounds 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.

NSMatchingWithTransparentBounds and NSMatchingWithoutAnchoringBounds matching options have no effect if the search range covers the entire string.

See Also

Searching Strings Using Regular Expressions

- numberOfMatchesInString:options:range:

Returns the number of matches of the regular expression within the specified range of the string.

- matchesInString:options:range:

Returns an array containing all the matches of the regular expression in the string.

- firstMatchInString:options:range:

Returns the first match of the regular expression within the specified range of the string.

- rangeOfFirstMatchInString:options:range:

Returns the range of the first match of the regular expression within the specified range of the string.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software