iOS Developer Library

Developer

Foundation Framework Reference NSDataDetector Class Reference

Options
Deployment Target:

On This Page
Language:

NSDataDetector

The NSDataDetector class is a specialized subclass of the NSRegularExpression class designed to match data detectors.

Currently the NSDataDetector class can match dates, addresses, links, phone numbers and transit information.

The results of matching content is returned as NSTextCheckingResult objects. However, the NSTextCheckingResult objects returned by NSDataDetector are different from those returned by the base class NSRegularExpression. Results returned by NSDataDetector will be of one of the data detectors types, depending on the type of result being returned, and they will have corresponding properties. For example, results of type NSTextCheckingTypeDate have a date, timeZone, and duration; results of type NSTextCheckingTypeLink have a URL, and so forth.

Examples

The following shows several graduated examples of using the NSDataDetector class.

This code fragment creates a data detector that will find URL links and phone numbers. If an error was encountered it is returned in error.

  • NSError *error = NULL;
  • NSDataDetector *detector = [NSDataDetector dataDetectorWithTypes:NSTextCheckingTypeLink|NSTextCheckingTypePhoneNumber
  • error:&error];

Once the data detector instance is created you can determine the number of matches within a range of a string using the NSRegularExpression method numberOfMatchesInString:options:range:.

  • NSUInteger numberOfMatches = [detector numberOfMatchesInString:string
  • options:0
  • range:NSMakeRange(0, [string length])];

If you are interested only in the overall range of the first match, the numberOfMatchesInString:options:range: method provides it. However, with data detectors, this is less likely than with regular expressions, because clients usually will be interested in additional information as well.

The additional information available depends on the type of the result. For results of type NSTextCheckingTypeLink, it is the URL property that is significant. For results of type NSTextCheckingTypePhoneNumber , it is the phoneNumber property instead.

The matchesInString:options:range: method is similar to the firstMatchInString:options:range:, except that it returns all matches rather than only the first. The following code fragment finds all the matches for links and phone numbers in a string.

  • NSArray *matches = [detector matchesInString:string
  • options:0
  • range:NSMakeRange(0, [string length])];
  • for (NSTextCheckingResult *match in matches) {
  • NSRange matchRange = [match range];
  • if ([match resultType] == NSTextCheckingTypeLink) {
  • NSURL *url = [match URL];
  • } else if ([match resultType] == NSTextCheckingTypePhoneNumber) {
  • NSString *phoneNumber = [match phoneNumber];
  • }
  • }

The NSRegularExpression Block object enumerator is the most general and flexible of the matching methods. 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 code fragment, the iteration is stopped after a certain number of matches have been found.

  • __block NSUInteger count = 0;
  • [detector enumerateMatchesInString:string
  • options:0
  • range:NSMakeRange(0, [string length])
  • usingBlock:^(NSTextCheckingResult *match, NSMatchingFlags flags, BOOL *stop){
  • NSRange matchRange = [match range];
  • if ([match resultType] == NSTextCheckingTypeLink) {
  • NSURL *url = [match URL];
  • } else if ([match resultType] == NSTextCheckingTypePhoneNumber) {
  • NSString *phoneNumber = [match phoneNumber];
  • }
  • if (++count >= 100) *stop = YES;
  • }];

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 4.0 and later.
  • Creates and returns a new data detector instance.

    Declaration

    Objective-C

    + (NSDataDetector *)dataDetectorWithTypes:(NSTextCheckingTypes)checkingTypes error:(NSError **)error

    Parameters

    checkingTypes

    The checking types. The supported checking types are a subset of the types specified in NSTextCheckingType. Those constants can be combined using the C-bitwise OR operator.

    error

    An out parameter that if an error occurs during initialization contains the encountered error.

    Return Value

    Returns the newly initialized data detector. If an error was encountered returns nil, and error contains the error.

    Discussion

    Currently, the supported data detectors checkingTypes are: NSTextCheckingTypeDate, NSTextCheckingTypeAddress, NSTextCheckingTypeLink, NSTextCheckingTypePhoneNumber, and NSTextCheckingTypeTransitInformation.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 4.0 and later.

  • Initializes and returns a data detector instance.

    Declaration

    Swift

    init?(types checkingTypes: NSTextCheckingTypes, error error: NSErrorPointer)

    Objective-C

    - (instancetype)initWithTypes:(NSTextCheckingTypes)checkingTypes error:(NSError **)error

    Parameters

    checkingTypes

    The checking types. The supported checking types are a subset of the types NSTextCheckingType. Those constants can be combined using the C-bitwise OR operator.

    error

    An out parameter that if an error occurs during initialization contains the encountered error.

    Return Value

    Returns the newly initialized data detector. If an error was encountered returns nil, and error contains the error.

    Discussion

    Currently, the supported data detectors checkingTypes are: NSTextCheckingTypeDate, NSTextCheckingTypeAddress, NSTextCheckingTypeLink, NSTextCheckingTypePhoneNumber, and NSTextCheckingTypeTransitInformation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.