NSTextCheckingResult Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSTextCheckingResult.h
Related sample code

Overview

NSTextCheckingResult is a class used to describe items located by text checking. Each of these objects represents an occurrence of requested textual content that has been found during the analysis of a block of text.

On both iOS and OS X, instances of NSTextCheckingResult are returned by the NSRegularExpression class and the NSDataDetector class to indicate the discovery of content. In those cases, what is found may be a match for a regular expression or a date, address, phone number, and so on. On OS X, instances of NSTextCheckingResult are returned by the NSSpellChecker object to describe the results of spelling, grammar, or text-substitution actions.

Tasks

Text Checking Type Range and Type

Text Checking Results for Text Replacement

Text Checking Results for Regular Expressions

Text Checking Result Components

Text Checking Results for URLs

Text Checking Results for Addresses

Text Checking Results for Transit Information

Text Checking Results for Phone Numbers

Text Checking Results for Dates and Times

Text Checking Results for Typography

Text Checking Results for Spelling

Text Checking Results for Orthography

Text Checking Results for Grammar

Adjusting the Ranges of a Text Checking Result

Properties

addressComponents

The address dictionary of a type checking result. (read-only)

@property(readonly) NSDictionary *addressComponents
Discussion

The dictionary keys are described in “Keys for Address Components.”

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

components

A dictionary containing the components of a type checking result. (read-only)

@property(readonly) NSDictionary *components
Discussion

Currently used by the transit checking result. The supported keys are located in “Keys for Transit Components.”

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

date

The date component of a type checking result. (read-only)

@property(readonly) NSDate *date
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

duration

The duration component of a type checking result. (read-only)

@property(readonly) NSTimeInterval duration
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

grammarDetails

The details of a located grammatical type checking result. (read-only)

@property(readonly) NSArray *grammarDetails
Discussion

This array of strings is suitable for presenting to the user.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

numberOfRanges

Returns the number of ranges. (read-only)

@property(readonly) NSUInteger numberOfRanges
Discussion

A result must have at least one range, but may optionally have more (for example, to represent regular expression capture groups).

Passing rangeAtIndex: the value 0 always returns the value of the the range property. Additional ranges, if any, will have indexes from 1 to numberOfRanges-1.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

orthography

The detected orthography of a type checking result. (read-only)

@property(readonly) NSOrthography *orthography
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

phoneNumber

The phone number of a type checking result. (read-only)

@property(readonly) NSString *phoneNumber
Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

range

Returns the range of the result that the receiver represents. (read-only)

@property(readonly) NSRange range
Discussion

This property will be present for all returned NSTextCheckingResult instances.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

regularExpression

The regular expression of a type checking result. (read-only)

@property(readonly) NSRegularExpression *regularExpression
Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

replacementString

A replacement string from one of a number of replacement checking results. (read-only)

@property(readonly) NSString *replacementString
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

resultType

Returns the text checking result type that the receiver represents. (read-only)

@property(readonly) NSTextCheckingType resultType
Discussion

The possible result types for the built in checking capabilities are described in “NSTextCheckingType.”

This property will be present for all returned NSTextCheckingResult instances.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

timeZone

The time zone component of a type checking result. (read-only)

@property(readonly) NSTimeZone *timeZone
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

URL

The URL of a type checking result. (read-only)

@property(readonly) NSURL *URL
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

Class Methods

addressCheckingResultWithRange:components:

Creates and returns a text checking result with the specified address components.

+ (NSTextCheckingResult *)addressCheckingResultWithRange:(NSRange)range components:(NSDictionary *)components
Parameters
range

The range of the detected result.

components

A dictionary containing the address components. The dictionary keys are described in “Keys for Address Components.”

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeAddress.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

correctionCheckingResultWithRange:replacementString:

Creates and returns a text checking result after detecting a possible correction.

+ (NSTextCheckingResult *)correctionCheckingResultWithRange:(NSRange)range replacementString:(NSString *)replacementString
Parameters
range

The range of the detected result.

replacementString

The suggested replacement string.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeSpelling.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

dashCheckingResultWithRange:replacementString:

Creates and returns a text checking result with the specified dash corrected replacement string.

+ (NSTextCheckingResult *)dashCheckingResultWithRange:(NSRange)range replacementString:(NSString *)replacementString
Parameters
range

The range of the detected result.

replacementString

The replacement string.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeDash.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

dateCheckingResultWithRange:date:

Creates and returns a text checking result with the specified date.

+ (NSTextCheckingResult *)dateCheckingResultWithRange:(NSRange)range date:(NSDate *)date
Parameters
range

The range of the detected result.

date

The detected date.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeDate.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

dateCheckingResultWithRange:date:timeZone:duration:

Creates and returns a text checking result with the specified date, time zone, and duration.

+ (NSTextCheckingResult *)dateCheckingResultWithRange:(NSRange)range date:(NSDate *)date timeZone:(NSTimeZone *)timeZone duration:(NSTimeInterval)duration
Parameters
range

The range of the detected result.

date

The detected date.

timeZone

The detected time zone.

duration

The detected duration.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeDate.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

grammarCheckingResultWithRange:details:

Creates and returns a text checking result with the specified array of grammatical errors.

+ (NSTextCheckingResult *)grammarCheckingResultWithRange:(NSRange)range details:(NSArray *)details
Parameters
range

The range of the detected result.

details

An array of details regarding the grammatical errors. This array of strings is suitable for presenting to the user.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeGrammar.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

linkCheckingResultWithRange:URL:

Creates and returns a text checking result with the specified URL.

+ (NSTextCheckingResult *)linkCheckingResultWithRange:(NSRange)range URL:(NSURL *)url
Parameters
range

The range of the detected result.

url

The URL.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeLink.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSTextCheckingResult.h

orthographyCheckingResultWithRange:orthography:

Creates and returns a text checking result with the specified orthography.

+ (NSTextCheckingResult *)orthographyCheckingResultWithRange:(NSRange)range orthography:(NSOrthography *)orthography
Parameters
range

The range of the detected result.

orthography

An orthography object that describes the script.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeOrthography.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

phoneNumberCheckingResultWithRange:phoneNumber:

Creates and returns a text checking result with the specified phone number.

+ (NSTextCheckingResult *)phoneNumberCheckingResultWithRange:(NSRange)range phoneNumber:(NSString *)phoneNumber
Parameters
range

The range of the detected result.

phoneNumber

The phone number.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypePhoneNumber.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

quoteCheckingResultWithRange:replacementString:

Creates and returns a text checking result with the specified quote-balanced replacement string.

+ (NSTextCheckingResult *)quoteCheckingResultWithRange:(NSRange)range replacementString:(NSString *)replacementString
Parameters
range

The range of the detected result.

replacementString

The replacement string.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeQuote.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

regularExpressionCheckingResultWithRanges:count:regularExpression:

Creates and returns a type checking result with the specified regular expression data.

+ (NSTextCheckingResult *)regularExpressionCheckingResultWithRanges:(NSRangePointer)ranges count:(NSUInteger)count regularExpression:(NSRegularExpression *)regularExpression
Parameters
ranges

A C array of ranges, which must have at least one element, and the first element represents the overall range.

count

The number of items in the ranges array.

regularExpression

The regular expression.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeRegularExpression.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

replacementCheckingResultWithRange:replacementString:

Creates and returns a text checking result with the specified replacement string.

+ (NSTextCheckingResult *)replacementCheckingResultWithRange:(NSRange)range replacementString:(NSString *)replacementString
Parameters
range

The range of the detected result.

replacementString

The replacement string.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeReplacement.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

spellCheckingResultWithRange:

Creates and returns a text checking result with the range of a misspelled word.

+ (NSTextCheckingResult *)spellCheckingResultWithRange:(NSRange)range
Parameters
range

The range of the detected result.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeSpelling.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTextCheckingResult.h

transitInformationCheckingResultWithRange:components:

Creates and returns a text checking result with the specified transit information.

+ (NSTextCheckingResult *)transitInformationCheckingResultWithRange:(NSRange)range components:(NSDictionary *)components
Parameters
range

The range of the detected result.

components

A dictionary containing the transit components. The currently supported keys are NSTextCheckingAirlineKey and NSTextCheckingFlightKey.

Return Value

Returns an NSTextCheckingResult with the specified range and a resultType of NSTextCheckingTypeTransitInformation.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

Instance Methods

rangeAtIndex:

Returns the result type that the range represents.

- (NSRange)rangeAtIndex:(NSUInteger)idx
Parameters
idx

The index of the result.

Return Value

The range of the result.

Discussion

A result must have at least one range, but may optionally have more (for example, to represent regular expression capture groups).

Passing rangeAtIndex: the value 0 always returns the value of the the range property. Additional ranges, if any, will have indexes from 1 to numberOfRanges-1.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

resultByAdjustingRangesWithOffset:

Returns a new text checking result after adjusting the ranges as specified by the offset.

- (NSTextCheckingResult *)resultByAdjustingRangesWithOffset:(NSInteger)offset
Parameters
offset

The amount the ranges are adjusted.

Return Value

A new NSTextCheckingResult instance with the adjusted range or ranges.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextCheckingResult.h

Constants

Keys for Transit Components

The following constants identify the possible keys returned in the components dictionary.

NSString * const NSTextCheckingAirlineKey;
NSString * const NSTextCheckingFlightKey;
Constants
NSTextCheckingAirlineKey

A key that corresponds to the airline of a transit result.

Available in OS X v10.7 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingFlightKey

A key that corresponds to the flight component of a transit result.

Available in OS X v10.7 and later.

Declared in NSTextCheckingResult.h.

Keys for Address Components

The following constants identify the possible keys returned in the addressComponents dictionary.

NSString * const NSTextCheckingNameKey;
NSString * const NSTextCheckingJobTitleKey;
NSString * const NSTextCheckingOrganizationKey;
NSString * const NSTextCheckingStreetKey;
NSString * const NSTextCheckingCityKey;
NSString * const NSTextCheckingStateKey;
NSString * const NSTextCheckingZIPKey;
NSString * const NSTextCheckingCountryKey;
NSString * const NSTextCheckingPhoneKey;
Constants
NSTextCheckingNameKey

A key that corresponds to the name component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingJobTitleKey

A key that corresponds to the job component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingOrganizationKey

A key that corresponds to the organization component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingStreetKey

A key that corresponds to the street address component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingCityKey

A key that corresponds to the city component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingStateKey

A key that corresponds to the state or province component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingZIPKey

A key that corresponds to the zip code or postal code component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingCountryKey

A key that corresponds to the country component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingPhoneKey

A key that corresponds to the phone number component of the address.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingType

These constants specify the type of checking the methods should do. They are returned by resultType.

enum {
   NSTextCheckingTypeOrthography        = 1ULL << 0,
   NSTextCheckingTypeSpelling           = 1ULL << 1,
   NSTextCheckingTypeGrammar            = 1ULL << 2,
   NSTextCheckingTypeDate               = 1ULL << 3,
   NSTextCheckingTypeAddress            = 1ULL << 4,
   NSTextCheckingTypeLink               = 1ULL << 5,
   NSTextCheckingTypeQuote              = 1ULL << 6,
   NSTextCheckingTypeDash               = 1ULL << 7,
   NSTextCheckingTypeReplacement        = 1ULL << 8,
   NSTextCheckingTypeCorrection         = 1ULL << 9,
   NSTextCheckingTypeRegularExpression  = 1ULL << 10
   NSTextCheckingTypePhoneNumber        = 1ULL << 11,
   NSTextCheckingTypeTransitInformation = 1ULL << 12
};
typedef uint64_t NSTextCheckingType;
Constants
NSTextCheckingTypeOrthography

Attempts to identify the language

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeSpelling

Checks spelling.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeGrammar

Checks grammar.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeDate

Attempts to locate dates.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeAddress

Attempts to locate addresses.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeLink

Attempts to locate URL links.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeQuote

Replaces quotes with smart quotes.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeDash

Replaces dashes with em-dashes.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeReplacement

Replaces characters such as (c) with the appropriate symbol (in this case ©).

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeCorrection

Performs autocorrection on misspelled words.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeRegularExpression

Matches a regular expression.

Available in OS X v10.7 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypePhoneNumber

Matches a phone number.

Available in OS X v10.7 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypeTransitInformation

Matches a transit information, for example, flight information.

Available in OS X v10.7 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingTypes

Defines the types of checking that are available. These values can be combined using the C-bitwise OR operator. The system supports its own internal types, and the user can extend those types by subclassing NSTextCheckingResult and adding their own custom types.

enum {
   NSTextCheckingAllSystemTypes    = 0xffffffffULL,
   NSTextCheckingAllCustomTypes    = 0xffffffffULL << 32,
   NSTextCheckingAllTypes          = (NSTextCheckingAllSystemTypes | NSTextCheckingAllCustomTypes)
};
typedef uint64_t NSTextCheckingTypes;
Constants
NSTextCheckingAllSystemTypes

Checking types supported by the system. The first 32 types are reserved.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingAllCustomTypes

Checking types that can be used by clients.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.

NSTextCheckingAllTypes

All possible checking types, both system- and user-supported.

Available in OS X v10.6 and later.

Declared in NSTextCheckingResult.h.