Contents

NSDataDetector

A specialized regular expression object that matches natural language text for predefined data patterns.

Declaration

class NSDataDetector

Overview

Find dates, addresses, links, phone numbers, and transit information in natural language text with NSDataDetector.

NSDataDetector returns the results of matching content in NSTextCheckingResult objects. The NSTextCheckingResult objects that NSDataDetector returns are different from those that NSRegularExpression returns. The results are one of the data detector’s types and contain the corresponding properties. For example, results of type date have a date, timeZone, and duration; and results of type link have a url.

Examples

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

This code fragment creates a data detector that finds URL links and phone numbers. If an error occurs, it returns in error.

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

After creating the data detector instance, you can determine the number of matches within a range of a string using the NSRegularExpression method numberOfMatches(in:options:range:).

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

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

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

The matches(in:options:range:) method is similar to firstMatch(in: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 stops after finding a certain number of matches:

   __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;
   }];

Topics

Creating data detector instances

Getting the checking types

See Also

Pattern Matching