NSRegularExpression Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSCopying NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in iOS 4.0 and later.
Declared in	NSRegularExpression.h
Related sample code	CoreTextPageViewer

Overview

The NSRegularExpression class is used to represent and apply regular expressions to Unicode strings. An instance of this class is an immutable representation of a compiled regular expression pattern and various option flags. The pattern syntax currently supported is that specified by ICU.

The fundamental matching method for NSRegularExpression is a Block iterator method that allows clients to supply a Block object which will be invoked each time the regular expression matches a portion of the target string. 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.

An individual match is represented by an instance of the NSTextCheckingResult class, which carries information about the overall matched range (via its range property), and the range of each individual capture group (via the rangeAtIndex: method). For basic NSRegularExpression objects, these match results will be of type NSTextCheckingTypeRegularExpression, but subclasses may use other types.

Examples Using NSRegularExpression

What follows are a set of graduated examples for using the NSRegularExpression class. All these examples use the regular expression \\b(a|b)(c|d)\\b as their regular expression.

This snippet creates a regular expression to match two-letter words, in which the first letter is “a” or “b” and the second letter is “c” or “d”. Specifying NSRegularExpressionCaseInsensitive means that matches will be case-insensitive, so this will match “BC”, “aD”, and so forth, as well as their lower-case equivalents.

NSError *error = NULL;

NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern:@"\\b(a|b)(c|d)\\b"

                                                                       options:NSRegularExpressionCaseInsensitive

                                                                         error:&error];

The numberOfMatchesInString:options:range: method provides a simple mechanism for counting the number of matches in a given range of a string.

NSUInteger numberOfMatches = [regex numberOfMatchesInString:string

                                                    options:0

                                                      range:NSMakeRange(0, [string length])];

If you are interested only in the overall range of the first match, the rangeOfFirstMatchInString:options:range: method provides it for you. Some regular expressions (though not the example pattern) can successfully match a zero-length range, so the comparison of the resulting range with {NSNotFound, 0} is the most reliable way to determine whether there was a match or not.

The example regular expression contains two capture groups, corresponding to the two sets of parentheses, one for the first letter, and one for the second. If you are interested in more than just the overall matched range, you want to obtain an NSTextCheckingResult object corresponding to a given match. This object provides information about the overall matched range, via its range property, and also supplies the capture group ranges, via the rangeAtIndex: method. The first capture group range is given by [result rangeAtIndex:1], the second by [result rangeAtIndex:2]. Sending a result the rangeAtIndex: message and passing 0 is equivalent to [result range].

If the result returned is non-nil, then [result range] will always be a valid range, so it is not necessary to compare it against {NSNotFound, 0}. However, for some regular expressions (though not the example pattern) some capture groups may or may not participate in a given match. If a given capture group does not participate in a given match, then [result rangeAtIndex:idx] will return {NSNotFound, 0}.

NSRange rangeOfFirstMatch = [regex rangeOfFirstMatchInString:string options:0 range:NSMakeRange(0, [string length])];

if (!NSEqualRanges(rangeOfFirstMatch, NSMakeRange(NSNotFound, 0))) {

    NSString *substringForFirstMatch = [string substringWithRange:rangeOfFirstMatch];

The firstMatchInString:options:range: returns only the first match.

NSArray *matches = [regex matchesInString:string

                                  options:0

                                    range:NSMakeRange(0, [string length])];

for (NSTextCheckingResult *match in matches) {

     NSRange matchRange = [match range];

     NSRange firstHalfRange = [match rangeAtIndex:1];

     NSRange secondHalfRange = [match rangeAtIndex:2];

The matchesInString:options:range: method is similar to firstMatchInString:options:range: but it returns all the matching results.

NSTextCheckingResult *match = [regex firstMatchInString:string

                                                options:0

                                                  range:NSMakeRange(0, [string length])];

if (match) {

    NSRange matchRange = [match range];

    NSRange firstHalfRange = [match rangeAtIndex:1];

    NSRange secondHalfRange = [match rangeAtIndex:2];

The Block enumeration method enumerateMatchesInString:options:range:usingBlock: is the most general and flexible of the matching methods of NSRegularExpression. It allows you to iterate through matches in a string, performing arbitrary actions on each as specified by the code in the Block and to stop partway through if desired. In the following example case, the iteration is stopped after a certain number of matches have been found.

If neither of the special options NSMatchingReportProgress or NSMatchingReportCompletion is specified, then the result argument to the Block is guaranteed to be non-nil, and as mentioned before, it is guaranteed to have a valid overall range. See “NSMatchingOptions” for the significance of NSMatchingReportProgress or NSMatchingReportCompletion.

__block NSUInteger count = 0;

[regex enumerateMatchesInString:string options:0 range:NSMakeRange(0, [string length]) usingBlock:^(NSTextCheckingResult *match, NSMatchingFlags flags, BOOL *stop){

     NSRange matchRange = [match range];

     NSRange firstHalfRange = [match rangeAtIndex:1];

     NSRange secondHalfRange = [match rangeAtIndex:2];

     if (++count >= 100) *stop = YES;

}];

NSRegularExpression also provides simple methods for performing find-and-replace operations on a string. The following example returns a modified copy, but there is a corresponding method for modifying a mutable string in place. The template specifies what is to be used to replace each match, with $0 representing the contents of the overall matched range, $1 representing the contents of the first capture group, and so on. In this case, the template reverses the two letters of the word.

NSString *modifiedString = [regex stringByReplacingMatchesInString:string

                                                           options:0

                                                             range:NSMakeRange(0, [string length])

                                                      withTemplate:@"$2$1"];

Concurrency and Thread Safety

NSRegularExpression is designed to be immutable and thread safe, so that a single instance can be used in matching operations on multiple threads at once. However, the string on which it is operating should not be mutated during the course of a matching operation, whether from another thread or from within the Block used in the iteration.

Regular Expression Syntax

The following tables describe the character expressions used by the regular expression to match patterns within a string, the pattern operators that specify how many times a pattern is matched and additional matching restrictions, and the last table specifies flags that can be included in the regular expression pattern that specify search behavior over multiple lines (these flags can also be specified using the “NSRegularExpressionOptions” option flags.

Regular Expression Metacharacters

Table 1 describe the character sequences used to match characters within a string.

**Table 1** Regular Expression Metacharacters
Character Expression	Description
`\a`	Match a BELL, `\u0007`
`\A`	Match at the beginning of the input. Differs from `^` in that `\A` will not match after a new line within the input.
`\b, outside of a [Set]`	Match if the current position is a word boundary. Boundaries occur at the transitions between word (`\w`) and non-word (`\W`) characters, with combining marks ignored. For better word boundaries, see `NSRegularExpressionUseUnicodeWordBoundaries`.
`\b, within a [Set]`	Match a BACKSPACE, `\u0008`.
`\B`	Match if the current position is not a word boundary.
`\cX`	Match a `control-X` character
`\d`	Match any character with the Unicode General Category of Nd (Number, Decimal Digit.)
`\D`	Match any character that is not a decimal digit.
`\e`	Match an `ESCAPE`, `\u001B`.
`\E`	Terminates a `\Q ... \E` quoted sequence.
`\f`	Match a FORM FEED, `\u000C`.
`\G`	Match if the current position is at the end of the previous match.
`\n`	Match a `LINE FEED`, `\u000A`.
`\N{`UNICODE CHARACTER NAME`}`	Match the named character.
`\p{`UNICODE PROPERTY NAME`}`	Match any character with the specified Unicode Property.
`\P{`UNICODE PROPERTY NAME`}`	Match any character not having the specified Unicode Property.
`\Q`	Quotes all following characters until `\E`.
`\r`	Match a CARRIAGE RETURN, \u000D.
`\s`	Match a white space character. White space is defined as [\t\n\f\r\p{Z}].
`\S`	Match a non-white space character.
`\t`	Match a HORIZONTAL TABULATION, `\u0009`.
`\u`hhhh	Match the character with the hex value hhhh.
`\U`hhhhhhhh	Match the character with the hex value hhhhhhhh. Exactly eight hex digits must be provided, even though the largest Unicode code point is `\U0010ffff`.
`\w`	Match a word character. Word characters are [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}].
`\W`	Match a non-word character.
`\x{`hhhh`}`	Match the character with hex value hhhh. From one to six hex digits may be supplied.
`\x`hh	Match the character with two digit hex value hh.
`\X`	Match a Grapheme Cluster.
`\Z`	Match if the current position is at the end of input, but before the final line terminator, if one exists.
`\z`	Match if the current position is at the end of input.
`\`n	Back Reference. Match whatever the nth capturing group matched. n must be a number `> 1` and `<` total number of capture groups in the pattern.
`\0`ooo	Match an Octal character. ooo is from one to three octal digits. `0377` is the largest allowed Octal character. The leading zero is required; it distinguishes Octal constants from back references.
`[`pattern`]`	Match any one character from the pattern.
`.`	Match any character. See also `NSRegularExpressionDotMatchesLineSeparators` and the `s` character expression above.
`^`	Match at the beginning of a line. See also `NSRegularExpressionAnchorsMatchLines` and the `m` character expression above.
`$`	Match at the end of a line. See also `NSRegularExpressionAnchorsMatchLines` and the `m` character expression above.
`\`	Quotes the following character. Characters that must be quoted to be treated as literals are `* ? + [ ( ) { } ^ $ \| \ . /`

Regular Expression Operators

Table 2 defines the regular expression operators.

**Table 2** Regular Expression Operators
Operator	Description
`\|`	Alternation. A`\|`B matches either A or B.
`*`	Match `0` or more times. Match as many times as possible.
`+`	Match `1` or more times. Match as many times as possible.
`?`	Match zero or one times. Prefer one.
`{`n`}`	Match exactly n times.
`{`n`,}`	Match at least n times. Match as many times as possible.
`{`n`,`m`}`	Match between n and m times. Match as many times as possible, but not more than m.
`*?`	Match `0` or more times. Match as few times as possible.
`+?`	Match 1 or more times. Match as few times as possible.
`??`	Match zero or one times. Prefer zero.
`{`n`}?`	Match exactly n times.
`{`n`,}?`	Match at least n times, but no more than required for an overall pattern match.
`{`n`,`m`}?`	Match between n and m times. Match as few times as possible, but not less than n.
`*+`	Match 0 or more times. Match as many times as possible when first encountered, do not retry with fewer even if overall match fails (Possessive Match).
`++`	Match 1 or more times. Possessive match.
`?+`	Match zero or one times. Possessive match.
`{`n`}+`	Match exactly n times.
`{`n`,}+`	Match at least n times. Possessive Match.
`{`n`,`m`}+`	Match between n and m times. Possessive Match.
`(`...`)`	Capturing parentheses. Range of input that matched the parenthesized subexpression is available after the match.
`(?:`...`)`	Non-capturing parentheses. Groups the included pattern, but does not provide capturing of matching text. Somewhat more efficient than capturing parentheses.
`(?>`...`)`	Atomic-match parentheses. First match of the parenthesized subexpression is the only one tried; if it does not lead to an overall pattern match, back up the search for a match to a position before the "`(?>`"
`(?# ... )`	Free-format comment `(?# comment )`.
`(?= ... )`	Look-ahead assertion. True if the parenthesized pattern matches at the current input position, but does not advance the input position.
`(?! ... )`	Negative look-ahead assertion. True if the parenthesized pattern does not match at the current input position. Does not advance the input position.
(?<= ... )	Look-behind assertion. True if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators.)
`(?<! ... )`	Negative Look-behind assertion. True if the parenthesized pattern does not match text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators.)
`(?ismwx-ismwx:` `...` `)`	Flag settings. Evaluate the parenthesized expression with the specified flags enabled or -disabled. The flags are defined in “Flag Options.”
`(?ismwx-ismwx)`	Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, (?i) changes to a case insensitive match.The flags are defined in “Flag Options.”

Template Matching Format

The NSRegularExpression class provides find-and-replace methods for both immutable and mutable strings using the technique of template matching. Table 3 describes the syntax.

**Table 3** Template Matching Format
Character	Descriptions
`$`n	The text of capture group n will be substituted for $n. n must be `>= 0` and not greater than the number of capture groups. A `$` not followed by a digit has no special meaning, and will appear in the substitution text as itself, a `$`.
`\`	Treat the following character as a literal, suppressing any special meaning. Backslash escaping in substitution text is only required for '$' and '\', but may be used on any other character without bad effects.

The replacement string is treated as a template, with $0 being replaced by the contents of the matched range, $1 by the contents of the first capture group, and so on. Additional digits beyond the maximum required to represent the number of capture groups will be treated as ordinary characters, as will a $ not followed by digits. Backslash will escape both $ and \.

Flag Options

The following flags control various aspects of regular expression matching. These flag values may be specified within the pattern using the (?ismx-ismx) pattern options. Equivalent behaviors can be specified for the entire pattern when an NSRegularExpression is initialized, using the “NSRegularExpressionOptions” option flags.

**Table 4** Flag Options
Flag (Pattern)	Description
i	If set, matching will take place in a case-insensitive manner.
x	If set, allow use of white space and #comments within patterns
s	If set, a "`.`" in a pattern will match a line terminator in the input text. By default, it will not. Note that a `carriage-return / line-feed pair` in text behave as a single line terminator, and will match a single "`.`" in a regular expression pattern
m	Control the behavior of "`^`" and "`$`" in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, "`^`" and "`$`" will also match at the start and end of each line within the input text.
Para	Controls the behavior of `\b` in a pattern. If set, word boundaries are found according to the definitions of word found in Unicode UAX 29, Text Boundaries. By default, word boundaries are identified by means of a simple classification of characters as either “word” or “non-word”, which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of spaces and other non-word characters.

ICU License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of their respective owners.

Tasks

Creating Regular Expressions

Getting the Regular Expression and Options

Searching Strings Using Regular Expressions

Replacing Strings Using Regular Expressions

Escaping Characters in a String

Custom Replace Functionality

Properties

numberOfCaptureGroups

Returns the number of capture groups in the regular expression. (read-only)

@property(readonly) NSUInteger numberOfCaptureGroups

Discussion

A capture group consists of each possible match within a regular expression. Each capture group can then be used in a replacement template to insert that value into a replacement string.

This value puts a limit on the values of n for $n in templates, and it determines the number of ranges in the returned NSTextCheckingResult instances returned in the match... methods.

An exception will be generated if you attempt to access a result with an index value exceeding numberOfCaptureGroups-1.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

options

Returns the options used when the regular expression option was created. (read-only)

@property(readonly) NSRegularExpressionOptions options

Discussion

The options property specifies aspects of the regular expression matching that are always used when matching the regular expression. For example, if the expression is case sensitive, allows comments, ignores metacharacters, etc.. See “NSRegularExpressionOptions” for a complete discussion of the possible constants and their meanings.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

pattern

Returns the regular expression pattern. (read-only)

@property(readonly) NSString *pattern

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

Class Methods

escapedPatternForString:

Returns a string by adding backslash escapes as necessary to protect any characters that would match as pattern metacharacters.

+ (NSString *)escapedPatternForString:(NSString *)string

Parameters

string: The string.

Return Value

The escaped string.

Discussion

Returns a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as pattern metacharacters.

See “Flag Options” for the format of template.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

escapedTemplateForString:

Returns a template string by adding backslash escapes as necessary to protect any characters that would match as pattern metacharacters.

+ (NSString *)escapedTemplateForString:(NSString *)string

Parameters

string: The template string.

Return Value

The escaped template string.

Discussion

Returns a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as pattern metacharacters.

See “Flag Options” for the format of template.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

regularExpressionWithPattern:options:error:

Creates an NSRegularExpression instance with the specified regular expression pattern and options.

+ (NSRegularExpression *)regularExpressionWithPattern:(NSString *)pattern options:(NSRegularExpressionOptions)options error:(NSError **)error

Parameters

pattern: The regular expression pattern to compile.
options: The matching options. See “NSRegularExpressionOptions” for possible values. The values can be combined using the C-bitwise OR operator.
error: An out value that returns any error encountered during initialization. Returns nil if the regular expression pattern is invalid.

Return Value

An instance of NSRegularExpression for the specified regular expression and options.

Availability

Available in iOS 4.0 and later.

Related Sample Code

CoreTextPageViewer

Declared In

NSRegularExpression.h

Instance Methods

enumerateMatchesInString:options:range:usingBlock:

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

- (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.

Availability

Available in iOS 4.0 and later.

Related Sample Code

CoreTextPageViewer

Declared In

NSRegularExpression.h

firstMatchInString:options:range:

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

- (NSTextCheckingResult *)firstMatchInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range

Parameters

string: The string to search.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.

Return Value

An NSTextCheckingResult object. 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.

Discussion

This is a convenience method that calls enumerateMatchesInString:options:range:usingBlock:.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

initWithPattern:options:error:

Returns an initialized NSRegularExpression instance with the specified regular expression pattern and options.

- (id)initWithPattern:(NSString *)pattern options:(NSRegularExpressionOptions)options error:(NSError **)error

Parameters

pattern: The regular expression pattern to compile.
options: The regular expression options that are applied to the expression during matching. See “NSRegularExpressionOptions” for possible values.
error: An out value that returns any error encountered during initialization. Returns nil if the regular expression pattern is invalid.

Return Value

An instance of NSRegularExpression for the specified regular expression and options.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

matchesInString:options:range:

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

- (NSArray *)matchesInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range

Parameters

string: The string to search.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.

Return Value

An array of NSTextCheckingResult objects. Each 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.

Discussion

This is a convenience method that calls enumerateMatchesInString:options:range:usingBlock: passing the appropriate string, options, and range..

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

numberOfMatchesInString:options:range:

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

- (NSUInteger)numberOfMatchesInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range

Parameters

string: The string to search.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.

Return Value

The number of matches of the regular expression.

Discussion

This is a convenience method that calls enumerateMatchesInString:options:range:usingBlock:.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

rangeOfFirstMatchInString:options:range:

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

- (NSRange)rangeOfFirstMatchInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range

Parameters

string: The string to search.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.

Return Value

The range of the first match. Returns {NSNotFound, 0} if no match is found.

Discussion

This is a convenience method that calls enumerateMatchesInString:options:range:usingBlock:.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

replaceMatchesInString:options:range:withTemplate:

Replaces regular expression matches within the mutable string the using the template string.

- (NSUInteger)replaceMatchesInString:(NSMutableString *)string options:(NSMatchingOptions)options range:(NSRange)range withTemplate:(NSString *)template

Parameters

string: The mutable string to search and replace values within.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.
template: The substitution template used when replacing matching instances.

Return Value

The number of matches.

Discussion

See “Flag Options” for the format of template.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

replacementStringForResult:inString:offset:template:

Used to perform template substitution for a single result for clients implementing their own replace functionality.

- (NSString *)replacementStringForResult:(NSTextCheckingResult *)result inString:(NSString *)string offset:(NSInteger)offset template:(NSString *)template

Parameters

result: The result of the single match.
string: The string from which the result was matched.
offset: The offset to be added to the location of the result in the string.
template: See “Flag Options” for the format of template.

Return Value

A replacement string.

Discussion

For clients implementing their own replace functionality, this is a method to perform the template substitution for a single result, given the string from which the result was matched, an offset to be added to the location of the result in the string (for example, in cases that modifications to the string moved the result since it was matched), and a replacement template.

This is an advanced method that is used only if you wanted to iterate through a list of matches yourself and do the template replacement for each one, plus maybe some other calculation that you want to do in code, then you would use this at each step.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

stringByReplacingMatchesInString:options:range:withTemplate:

Returns a new string containing matching regular expressions replaced with the template string.

- (NSString *)stringByReplacingMatchesInString:(NSString *)string options:(NSMatchingOptions)options range:(NSRange)range withTemplate:(NSString *)template

Parameters

string: The string to search for values within.
options: The matching options to use. See “NSMatchingOptions” for possible values.
range: The range of the string to search.
template: The substitution template used when replacing matching instances.

Return Value

A string with matching regular expressions replaced by the template string.

Discussion

See “Flag Options” for the format of template.

Availability

Available in iOS 4.0 and later.

Declared In

NSRegularExpression.h

Constants

NSRegularExpressionOptions

These constants define the regular expression options. These constants are used by the property options, regularExpressionWithPattern:options:error:, and initWithPattern:options:error:.

enum {
   NSRegularExpressionCaseInsensitive             = 1 << 0,
   NSRegularExpressionAllowCommentsAndWhitespace  = 1 << 1,
   NSRegularExpressionIgnoreMetacharacters        = 1 << 2,
   NSRegularExpressionDotMatchesLineSeparators    = 1 << 3,
   NSRegularExpressionAnchorsMatchLines           = 1 << 4,
   NSRegularExpressionUseUnixLineSeparators       = 1 << 5,
   NSRegularExpressionUseUnicodeWordBoundaries    = 1 << 6
};
typedef NSUInteger NSRegularExpressionOptions;

Constants

NSRegularExpressionCaseInsensitive

Match letters in the pattern independent of case.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionAllowCommentsAndWhitespace

Ignore whitespace and #-prefixed comments in the pattern.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionIgnoreMetacharacters

Treat the entire pattern as a literal string.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionDotMatchesLineSeparators

Allow . to match any character, including line separators.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionAnchorsMatchLines

Allow ^ and $ to match the start and end of lines.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionUseUnixLineSeparators

Treat only \n as a line separator (otherwise, all standard line separators are used).

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSRegularExpressionUseUnicodeWordBoundaries

Use Unicode TR#29 to specify word boundaries (otherwise, traditional regular expression word boundaries are used).

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingFlags

Set by the Block as the matching progresses, completes, or fails. Used by the method enumerateMatchesInString:options:range:usingBlock:.

enum {
   NSMatchingProgress               = 1 << 0,
   NSMatchingCompleted              = 1 << 1,
   NSMatchingHitEnd                 = 1 << 2,
   NSMatchingRequiredEnd            = 1 << 3,
   NSMatchingInternalError          = 1 << 4
};
typedef NSUInteger NSMatchingFlags;

Constants

NSMatchingProgress

Set when the Block is called to report progress during a long-running match operation.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingCompleted

Set when the Block is called after matching has completed.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingHitEnd

Set when the current match operation reached the end of the search range.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingRequiredEnd

Set when the current match depended on the location of the end of the search range.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingInternalError

Set when matching failed due to an internal error.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingOptions

The matching options constants specify the reporting, completion and matching rules to the expression matching methods. These constants are used by all methods that search for, or replace values, using a regular expression.

enum {
   NSMatchingReportProgress         = 1 << 0,
   NSMatchingReportCompletion       = 1 << 1,
   NSMatchingAnchored               = 1 << 2,
   NSMatchingWithTransparentBounds  = 1 << 3,
   NSMatchingWithoutAnchoringBounds = 1 << 4
};
typedef NSUInteger NSMatchingOptions;

Constants

NSMatchingReportProgress

Call the Block periodically during long-running match operations. This option has no effect for methods other than enumerateMatchesInString:options:range:usingBlock:. See enumerateMatchesInString:options:range:usingBlock: for a description of the constant in context.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingReportCompletion

Call the Block once after the completion of any matching. This option has no effect for methods other than enumerateMatchesInString:options:range:usingBlock:. See enumerateMatchesInString:options:range:usingBlock: for a description of the constant in context.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingAnchored

Specifies that matches are limited to those at the start of the search range. See enumerateMatchesInString:options:range:usingBlock: for a description of the constant in context.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingWithTransparentBounds

Specifies that matching may examine parts of the string beyond the bounds of the search range, for purposes such as word boundary detection, lookahead, etc. This constant has no effect if the search range contains the entire string. See enumerateMatchesInString:options:range:usingBlock: for a description of the constant in context.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

NSMatchingWithoutAnchoringBounds

Specifies that ^ 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. This constant has no effect if the search range contains the entire string. See enumerateMatchesInString:options:range:usingBlock: for a description of the constant in context.

Available in iOS 4.0 and later.

Declared in NSRegularExpression.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

NSRegularExpression Class Reference

Overview

Examples Using NSRegularExpression

Concurrency and Thread Safety

Regular Expression Syntax

Regular Expression Metacharacters

Regular Expression Operators

Template Matching Format

Flag Options

ICU License

Tasks

Creating Regular Expressions

Getting the Regular Expression and Options

Searching Strings Using Regular Expressions

Replacing Strings Using Regular Expressions

Escaping Characters in a String

Custom Replace Functionality

Properties

numberOfCaptureGroups

Discussion

Availability

Declared In

options

Discussion

Availability

See Also

Declared In

pattern

Availability

See Also

Declared In

Class Methods

escapedPatternForString:

Parameters

Return Value

Discussion

Availability

Declared In

escapedTemplateForString:

Parameters

Return Value

Discussion

Availability

Declared In

regularExpressionWithPattern:options:error:

Parameters

Return Value

Availability

See Also

Related Sample Code

Declared In

Instance Methods

enumerateMatchesInString:options:range:usingBlock:

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

firstMatchInString:options:range:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

initWithPattern:options:error:

Parameters

Return Value

Availability

See Also

Declared In

matchesInString:options:range:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

numberOfMatchesInString:options:range: