NSString(MBRegex) Category Reference

Declared in NSString+MBRegex.h

Overview

An NSString class extension that provides various methods for creating and utilizing regular expressions.

To improve performance, these methods utilize the MBRegexCache when possible.

For additional information on the workings of regular expressions, see the Apple documentation for NSRegularExpression.

Creating regular expressions

– regularExpression

Returns an NSRegularExpression instance by treating the receiver as a regular expression pattern string.

- (nullable NSRegularExpression *)regularExpression

Return Value

The regular expression, or nil if the receiver could not be interpreted as a valid regular expression.

Declared In

NSString+MBRegex.h

– regularExpressionWithOptions:

Returns an NSRegularExpression instance by treating the receiver as a regular expression pattern string.

- (nullable NSRegularExpression *)regularExpressionWithOptions:(NSRegularExpressionOptions)options

Parameters

options

The options that govern the behavior of the returned regular expression.

Return Value

The regular expression, or nil if the receiver could not be interpreted as a valid regular expression.

Declared In

NSString+MBRegex.h

– regularExpressionWithOptions:error:

Returns an NSRegularExpression instance by treating the receiver as a regular expression pattern string.

- (nullable NSRegularExpression *)regularExpressionWithOptions:(NSRegularExpressionOptions)options error:(NSErrorPtrPtr)errPtr

Parameters

options

The options that govern the behavior of the returned regular expression.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

The regular expression, or nil if the receiver could not be interpreted as a valid regular expression.

Declared In

NSString+MBRegex.h

Escaping

– escapedRegexPattern

Creates a new regular expression pattern string by escaping metacharacters contained in the receiver.

- (nonnull NSString *)escapedRegexPattern

Return Value

The escaped pattern string.

Discussion

Affected characters are escaped by prefixing them with backslashes.

Declared In

NSString+MBRegex.h

– escapedRegexTemplate

Creates a new regular expression template string by escaping metacharacters contained in the receiver.

- (nonnull NSString *)escapedRegexTemplate

Return Value

The escaped template string.

Discussion

Affected characters are escaped by prefixing them with backslashes.

Declared In

NSString+MBRegex.h

Finding all pattern matches

– matchesWithRegex:

Matches the specified regular expression against the receiver.

- (nullable NSArray *)matchesWithRegex:(nonnull NSString *)pattern

Parameters

pattern

The regular expression pattern to match.

Return Value

An array of NSTextCheckingResult objects representing the regular expression pattern matches found within the receiver, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– matchesWithRegex:options:

Matches the specified regular expression against the receiver.

- (nullable NSArray *)matchesWithRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.

Return Value

An array of NSTextCheckingResult objects representing the regular expression pattern matches found within the receiver, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– matchesWithRegex:options:range:

Matches the specified regular expression against the receiver.

- (nullable NSArray *)matchesWithRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

An array of NSTextCheckingResult objects representing the regular expression pattern matches found within the receiver, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– matchesWithRegex:options:range:error:

Matches the specified regular expression against the receiver.

- (nullable NSArray *)matchesWithRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

An array of NSTextCheckingResult objects representing the regular expression pattern matches found within the receiver, or nil if an error occurred.

Declared In

NSString+MBRegex.h

Testing for pattern matches

– isMatchedByRegex:

Determines if the receiver contains at least one match of the given regular expression pattern.

- (BOOL)isMatchedByRegex:(nonnull NSString *)pattern

Parameters

pattern

The regular expression pattern to match.

Return Value

YES if the receiver contained at least one match of pattern; NO if there were no matches.

Declared In

NSString+MBRegex.h

– isMatchedByRegex:options:

Determines if the receiver contains at least one match of the given regular expression pattern.

- (BOOL)isMatchedByRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.

Return Value

YES if the receiver contained at least one match of pattern; NO if there were no matches.

Declared In

NSString+MBRegex.h

– isMatchedByRegex:options:range:

Determines if the receiver contains at least one match of the given regular expression pattern within the specified range.

- (BOOL)isMatchedByRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

YES if the receiver contained at least one match of pattern; NO if there were no matches.

Declared In

NSString+MBRegex.h

– isMatchedByRegex:options:range:error:

Determines if the receiver contains at least one match of the given regular expression pattern within the specified range.

- (BOOL)isMatchedByRegex:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

YES if the receiver contained at least one match of pattern; NO if there were no matches.

Declared In

NSString+MBRegex.h

Counting pattern matches

– numberOfRegexMatches:

Returns the number of matches found in the receiver of the given regular expression pattern.

- (NSUInteger)numberOfRegexMatches:(nonnull NSString *)pattern

Parameters

pattern

The regular expression pattern to match.

Return Value

The number of matches.

Declared In

NSString+MBRegex.h

– numberOfRegexMatches:options:

Returns the number of matches found in the receiver of the given regular expression pattern.

- (NSUInteger)numberOfRegexMatches:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.

Return Value

The number of matches.

Declared In

NSString+MBRegex.h

– numberOfRegexMatches:options:range:

Returns the number of matches found in the receiver of the given regular expression pattern.

- (NSUInteger)numberOfRegexMatches:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

The number of matches.

Declared In

NSString+MBRegex.h

– numberOfRegexMatches:options:range:error:

Returns the number of matches found in the receiver of the given regular expression pattern.

- (NSUInteger)numberOfRegexMatches:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

The number of matches.

Declared In

NSString+MBRegex.h

Finding the first pattern match

– firstRegexMatch:

Returns the first occurrence of the specified regular expression pattern found within the receiver.

- (nullable NSTextCheckingResult *)firstRegexMatch:(nonnull NSString *)pattern

Parameters

pattern

The regular expression pattern to match.

Return Value

An NSTextCheckingResult instance containing the results of the match, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– firstRegexMatch:options:

Returns the first occurrence of the specified regular expression pattern found within the receiver.

- (nullable NSTextCheckingResult *)firstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.

Return Value

An NSTextCheckingResult instance containing the results of the match, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– firstRegexMatch:options:range:

Returns the first occurrence of the specified regular expression pattern found within the receiver.

- (nullable NSTextCheckingResult *)firstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

An NSTextCheckingResult instance containing the results of the match, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– firstRegexMatch:options:range:error:

Returns the first occurrence of the specified regular expression pattern found within the receiver.

- (nullable NSTextCheckingResult *)firstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

An NSTextCheckingResult instance containing the results of the match, or nil if an error occurred.

Declared In

NSString+MBRegex.h

Getting the range of the first pattern match

– rangeOfFirstRegexMatch:

Determines the range of the first match of the given regular expression within the receiver.

- (NSRange)rangeOfFirstRegexMatch:(nonnull NSString *)pattern

Parameters

pattern

The regular expression pattern to match.

Return Value

The range of the first match. Will be {NSNotFound, 0} if there is no match.

Declared In

NSString+MBRegex.h

– rangeOfFirstRegexMatch:options:

Determines the range of the first match of the given regular expression within the receiver.

- (NSRange)rangeOfFirstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.

Return Value

The range of the first match. Will be {NSNotFound, 0} if there is no match.

Declared In

NSString+MBRegex.h

– rangeOfFirstRegexMatch:options:range:

Determines the range of the first match of the given regular expression within the receiver.

- (NSRange)rangeOfFirstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

The range of the first match. Will be {NSNotFound, 0} if there is no match.

Declared In

NSString+MBRegex.h

– rangeOfFirstRegexMatch:options:range:error:

Determines the range of the first match of the given regular expression within the receiver.

- (NSRange)rangeOfFirstRegexMatch:(nonnull NSString *)pattern options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

The range of the first match. Will be {NSNotFound, 0} if there is no match.

Declared In

NSString+MBRegex.h

Creating a new string by replacing pattern matches

– stringByReplacingRegexMatches:withTemplate:

Returns a new string by replacing each match of the specified regular expression pattern with the replacement template provided.

- (nullable NSString *)stringByReplacingRegexMatches:(nonnull NSString *)pattern withTemplate:(nonnull NSString *)templ

Parameters

pattern

The regular expression pattern to match.
templ

The template to use for replacing the regular expression matches.

Return Value

The resulting string, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– stringByReplacingRegexMatches:withTemplate:options:

Returns a new string by replacing each match of the specified regular expression pattern with the replacement template provided.

- (nullable NSString *)stringByReplacingRegexMatches:(nonnull NSString *)pattern withTemplate:(nonnull NSString *)templ options:(NSRegularExpressionOptions)options

Parameters

pattern

The regular expression pattern to match.
templ

The template to use for replacing the regular expression matches.
options

The regular expression options that govern how matching will occur.

Return Value

The resulting string, or nil if an error occurred.

Declared In

NSString+MBRegex.h

– stringByReplacingRegexMatches:withTemplate:options:range:

Returns a new string by replacing each match of the specified regular expression pattern with the replacement template provided.

- (nullable NSString *)stringByReplacingRegexMatches:(nonnull NSString *)pattern withTemplate:(nonnull NSString *)templ options:(NSRegularExpressionOptions)options range:(NSRange)range

Parameters

pattern

The regular expression pattern to match.
templ

The template to use for replacing the regular expression matches.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.

Return Value

The resulting string, or nil if an error occurred.

Discussion

Matching is constrained to the given range within the receiver.

Declared In

NSString+MBRegex.h

– stringByReplacingRegexMatches:withTemplate:options:range:error:

Returns a new string by replacing each match of the specified regular expression pattern with the replacement template provided.

- (nullable NSString *)stringByReplacingRegexMatches:(nonnull NSString *)pattern withTemplate:(nonnull NSString *)templ options:(NSRegularExpressionOptions)options range:(NSRange)range error:(NSErrorPtrPtr)errPtr

Parameters

pattern

The regular expression pattern to match.
templ

The template to use for replacing the regular expression matches.
options

The regular expression options that govern how matching will occur.
range

The range of characters in the receiver within which matching will occur.
errPtr

An optional pointer to storage for an NSError instance. If this parameter is non-nil and an error occurs, *errPtr will be updated to point to an NSError describing the problem.

Return Value

The resulting string, or nil if an error occurred.

Discussion

Matching is constrained to the given range within the receiver.

Declared In

NSString+MBRegex.h