iOS Developer Library

Developer

Foundation Framework Reference NSRegularExpression Class Reference

Options
Deployment Target:

On This Page
Language:

NSRegularExpression

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 ICU regular expressions are described at http://userguide.icu-project.org/strings/regexp. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 4.0 and later.
  • Creates an NSRegularExpression instance with the specified regular expression pattern and options.

    Declaration

    Objective-C

    + (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 an NSError object if the regular expression pattern is invalid; otherwise returns nil.

    Return Value

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

    Import Statement

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    init?(pattern pattern: String, options options: NSRegularExpressionOptions, error error: NSErrorPointer)

    Objective-C

    - (instancetype)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 an NSError object if the regular expression pattern is invalid; otherwise returns nil.firstMatchInString:options:range

    Return Value

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • pattern pattern Property

    Returns the regular expression pattern. (read-only)

    Declaration

    Swift

    var pattern: String { get }

    Objective-C

    @property(readonly, copy) NSString *pattern

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • options options Property

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

    Declaration

    Swift

    var options: NSRegularExpressionOptions { get }

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var numberOfCaptureGroups: Int { get }

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    class func escapedTemplateForString(_ string: String) -> String

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    class func escapedPatternForString(_ string: String) -> String

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func replacementStringForResult(_ result: NSTextCheckingResult, inString string: String, offset offset: Int, template template: String) -> String

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    struct NSRegularExpressionOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var CaseInsensitive: NSRegularExpressionOptions { get } static var AllowCommentsAndWhitespace: NSRegularExpressionOptions { get } static var IgnoreMetacharacters: NSRegularExpressionOptions { get } static var DotMatchesLineSeparators: NSRegularExpressionOptions { get } static var AnchorsMatchLines: NSRegularExpressionOptions { get } static var UseUnixLineSeparators: NSRegularExpressionOptions { get } static var UseUnicodeWordBoundaries: NSRegularExpressionOptions { get } }

    Objective-C

    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

    • CaseInsensitive

      NSRegularExpressionCaseInsensitive

      Match letters in the pattern independent of case.

      Available in iOS 4.0 and later.

    • AllowCommentsAndWhitespace

      NSRegularExpressionAllowCommentsAndWhitespace

      Ignore whitespace and #-prefixed comments in the pattern.

      Available in iOS 4.0 and later.

    • IgnoreMetacharacters

      NSRegularExpressionIgnoreMetacharacters

      Treat the entire pattern as a literal string.

      Available in iOS 4.0 and later.

    • DotMatchesLineSeparators

      NSRegularExpressionDotMatchesLineSeparators

      Allow . to match any character, including line separators.

      Available in iOS 4.0 and later.

    • AnchorsMatchLines

      NSRegularExpressionAnchorsMatchLines

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

      Available in iOS 4.0 and later.

    • UseUnixLineSeparators

      NSRegularExpressionUseUnixLineSeparators

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

      Available in iOS 4.0 and later.

    • UseUnicodeWordBoundaries

      NSRegularExpressionUseUnicodeWordBoundaries

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

      Available in iOS 4.0 and later.

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    struct NSMatchingFlags : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Progress: NSMatchingFlags { get } static var Completed: NSMatchingFlags { get } static var HitEnd: NSMatchingFlags { get } static var RequiredEnd: NSMatchingFlags { get } static var InternalError: NSMatchingFlags { get } }

    Objective-C

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

    Constants

    • Progress

      NSMatchingProgress

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

      Available in iOS 4.0 and later.

    • Completed

      NSMatchingCompleted

      Set when the Block is called after matching has completed.

      Available in iOS 4.0 and later.

    • HitEnd

      NSMatchingHitEnd

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

      Available in iOS 4.0 and later.

    • RequiredEnd

      NSMatchingRequiredEnd

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

      Available in iOS 4.0 and later.

    • InternalError

      NSMatchingInternalError

      Set when matching failed due to an internal error.

      Available in iOS 4.0 and later.

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    struct NSMatchingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var ReportProgress: NSMatchingOptions { get } static var ReportCompletion: NSMatchingOptions { get } static var Anchored: NSMatchingOptions { get } static var WithTransparentBounds: NSMatchingOptions { get } static var WithoutAnchoringBounds: NSMatchingOptions { get } }

    Objective-C

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

    Constants

    • ReportProgress

      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.

    • ReportCompletion

      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.

    • Anchored

      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.

    • WithTransparentBounds

      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.

    • WithoutAnchoringBounds

      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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 4.0 and later.