An immutable representation of a compiled regular expression that you apply to Unicode strings.
SDKs
- iOS 4.0+
- macOS 10.7+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
@interface NSRegularExpression : NSObject
Overview
The fundamental matching method for NSRegular
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 NSText
class, which carries information about the overall matched range (via its range
property), and the range of each individual capture group (via the range
method). For basic NSRegular
objects, these match results will be of type NSText
, but subclasses may use other types.
The ICU regular expressions supported by NSRegular
are described at http://userguide.icu-project.org/strings/regexp.
Examples Using NSRegularExpression
What follows are a set of graduated examples for using the NSRegular
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 NSRegular
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 number
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 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 {NSNot
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 NSText
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 range
method. The first capture group range is given by [result range
, the second by [result range
. Sending a result the range
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 {NSNot
. 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 range
will return {NSNot
.
NSRange rangeOfFirstMatch = [regex rangeOfFirstMatchInString:string options:0 range:NSMakeRange(0, [string length])];
if (!NSEqualRanges(rangeOfFirstMatch, NSMakeRange(NSNotFound, 0))) {
NSString *substringForFirstMatch = [string substringWithRange:rangeOfFirstMatch];
}
The matches
returns all the matching results.
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 first
method is similar to matches
but it returns only the first match.
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 enumerate
is the most general and flexible of the matching methods of NSRegular
. 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 NSMatching
or NSMatching
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 NSMatching
for the significance of NSMatching
or NSMatching
.
__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;
}];
NSRegular
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
NSRegular
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 NSRegular
option flags.
Regular Expression Metacharacters
Table 1 describe the character sequences used to match characters within a string.
Regular Expression Metacharacters
Character Expression | Description |
---|---|
| Match a BELL, |
| Match at the beginning of the input. Differs from |
| Match if the current position is a word boundary. Boundaries occur at the transitions between word ( |
| Match a BACKSPACE, |
| Match if the current position is not a word boundary. |
| Match a |
| Match any character with the Unicode General Category of Nd (Number, Decimal Digit.) |
| Match any character that is not a decimal digit. |
| Match an |
| Terminates a |
| Match a FORM FEED, |
| Match if the current position is at the end of the previous match. |
| Match a |
| Match the named character. |
| Match any character with the specified Unicode Property. |
| Match any character not having the specified Unicode Property. |
| Quotes all following characters until |
| Match a CARRIAGE RETURN, \u000D. |
| Match a white space character. White space is defined as [\t\n\f\r\p{Z}]. |
| Match a non-white space character. |
| Match a HORIZONTAL TABULATION, |
| Match the character with the hex value hhhh. |
| Match the character with the hex value hhhhhhhh. Exactly eight hex digits must be provided, even though the largest Unicode code point is |
| Match a word character. Word characters are [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}]. |
| Match a non-word character. |
| Match the character with hex value hhhh. From one to six hex digits may be supplied. |
| Match the character with two digit hex value hh. |
| Match a Grapheme Cluster. |
| Match if the current position is at the end of input, but before the final line terminator, if one exists. |
| Match if the current position is at the end of input. |
| Back Reference. Match whatever the nth capturing group matched. n must be a number |
| Match an Octal character. ooo is from one to three octal digits. |
| Match any one character from the pattern. |
| Match any character. See |
| Match at the beginning of a line. See |
| Match at the end of a line. See |
| 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.
Regular Expression Operators
Operator | Description |
---|---|
| Alternation. A |
| Match |
| Match |
| Match zero or one times. Prefer one. |
| Match exactly n times. |
| Match at least n times. Match as many times as possible. |
| Match between n and m times. Match as many times as possible, but not more than m. |
| Match |
| Match 1 or more times. Match as few times as possible. |
| Match zero or one times. Prefer zero. |
| Match exactly n times. |
| Match at least n times, but no more than required for an overall pattern match. |
| 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. |
| Match exactly n times. |
| Match at least n times. Possessive Match. |
| 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 |
| 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.) |
| Flag settings. Evaluate the parenthesized expression with the specified flags enabled or -disabled. The flags are defined in Flag Options. |
| 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 NSRegular
class provides find-and-replace methods for both immutable and mutable strings using the technique of template matching. Table 3 describes the syntax.
Template Matching Format
Character | Descriptions |
---|---|
| The text of capture group n will be substituted for $n. n must be |
| 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 NSRegular
is initialized, using the NSRegular
option flags.
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 " |
m | Control the behavior of " |
w | Controls the behavior of |
Performance
NSRegular
implements a nondeterministic finite automaton matching engine. As such, complex regular expression patterns containing multiple *
or +
operators may result in poor performance when attempting to perform matches — particularly failing to match a given input. For more information, see the “Performance Tips” section of the ICU User Guide.
ICU License
Table 1, Table 2, Table 3, Table 4 are reproduced from the ICU User Guide, Copyright (c) 2000 - 2009 IBM and Others, which are licensed under the following terms:
COPYRIGHT AND PERMISSION NOTICE
Copyright (c) 1995-2009 International Business Machines Corporation and others. All rights reserved.
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.