ADC Home > Reference Library > Reference > Cocoa > Data Management > NSScanner Class Reference >

Next Page > Hide TOC

NSScanner Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSDecimalNumber.h
NSScanner.h
Related sample code

Overview

The NSScanner class is an abstract superclass of a class cluster that declares the programmatic interface for an object that scans values from an NSString object.

An NSScanner object interprets and converts the characters of an NSString object into number and string values. You assign the scanner’s string on creating it, and the scanner progresses through the characters of that string from beginning to end as you request items.

Because of the nature of class clusters, scanner objects aren’t actual instances of the NSScanner class but one of its private subclasses. Although a scanner object’s class is private, its interface is public, as declared by this abstract superclass, NSScanner. The primitive methods of NSScanner are string and all of the methods listed under “Configuring a Scanner” in the "Methods by Task" section. The objects you create using this class are referred to as scanner objects (and when no confusion will result, merely as scanners).

You can set an NSScanner object to ignore a set of characters as it scans the string using the setCharactersToBeSkipped: method. The default set of characters to skip is the whitespace and newline character set.

To retrieve the unscanned remainder of the string, use [[scanner string]substringFromIndex:[scanner scanLocation]].

Adopted Protocols

NSCopying

Tasks

Creating an Scanner

Getting a Scanner’s String

Configuring a Scanner

Scanning a String

Class Methods

localizedScannerWithString:

Returns an NSScanner object that scans a given string according to the user’s default locale.

+ (id)localizedScannerWithString:(NSString *)aString

Parameters
aString

The string to scan.

Return Value

An NSScanner object that scans aString according to the user’s default locale.

Discussion

Sets the string to scan by invoking initWithString: with aString. The locale is set with setLocale:.

Availability
Declared In
NSScanner.h

scannerWithString:

Returns an NSScanner object that scans a given string.

+ (id)scannerWithString:(NSString *)aString

Parameters
aString

The string to scan.

Return Value

An NSScanner object that scans aString.

Discussion

Sets the string to scan by invoking initWithString: with aString.

Availability
Related Sample Code
Declared In
NSScanner.h

Instance Methods

caseSensitive

Returns a Boolean value that indicates whether the receiver distinguishes case in the characters it scans.

- (BOOL)caseSensitive

Return Value

YES if the receiver distinguishes case in the characters it scans, otherwise NO.

Discussion

Scanners are not case sensitive by default. Note that case sensitivity doesn’t apply to the characters to be skipped.

Availability
See Also
Declared In
NSScanner.h

charactersToBeSkipped

Returns a character set containing the characters the receiver ignores when looking for a scannable element.

- (NSCharacterSet *)charactersToBeSkipped

Return Value

A character set containing the characters the receiver ignores when looking for a scannable element.

Discussion

For example, if a scanner ignores spaces and you send it a scanInt: message, it skips spaces until it finds a decimal digit or other character. While an element is being scanned, however, no characters are skipped. If you scan for something made of characters in the set to be skipped (for example, using scanInt: when the set of characters to be skipped is the decimal digits), the result is undefined.

The default set to skip is the whitespace and newline character set.

Availability
See Also
Declared In
NSScanner.h

initWithString:

Returns an NSScanner object initialized to scan a given string.

- (id)initWithString:(NSString *)aString

Parameters
aString

The string to scan.

Return Value

An NSScanner object initialized to scan aString from the beginning. The returned object might be different than the original receiver.

Availability
See Also
Declared In
NSScanner.h

isAtEnd

Returns a Boolean value that indicates whether the receiver has exhausted all significant characters

- (BOOL)isAtEnd

Return Value

YES if the receiver has exhausted all significant characters in its string, otherwise NO.

If only characters from the set to be skipped remain, returns YES.

Availability
See Also
Related Sample Code
Declared In
NSScanner.h

locale

Returns the receiver’s locale.

- (id)locale

Return Value

The receiver’s locale, or nil if it has none.

Discussion

A scanner’s locale affects the way it interprets numeric values from the string. In particular, a scanner uses the locale’s decimal separator to distinguish the integer and fractional parts of floating-point representations. A scanner with no locale set uses non-localized values.

Availability
See Also
Declared In
NSScanner.h

scanCharactersFromSet:intoString:

Scans the string as long as characters from a given character set are encountered, accumulating characters into a string that’s returned by reference.

- (BOOL)scanCharactersFromSet:(NSCharacterSet *)scanSet intoString:(NSString **)stringValue

Parameters
scanSet

The set of characters to scan.

stringValue

Upon return, contains the characters scanned.

Return Value

YES if the receiver scanned any characters, otherwise NO.

Discussion

Invoke this method with NULL as stringValue to simply scan past a given set of characters.

Availability
See Also
Declared In
NSScanner.h

scanDecimal:

Scans for an NSDecimal value, returning a found value by reference.

- (BOOL)scanDecimal:(NSDecimal *)decimalValue

Parameters
decimalValue

Upon return, contains the scanned value. See the NSDecimalNumber class specification for more information about NSDecimal values.

Return Value

YES if the receiver finds a valid NSDecimal representation, otherwise NO.

Discussion

Invoke this method with NULL as decimalValue to simply scan past an NSDecimal representation.

Availability
Related Sample Code
Declared In
NSDecimalNumber.h

scanDouble:

Scans for a double value, returning a found value by reference.

- (BOOL)scanDouble:(double *)doubleValue

Parameters
doubleValue

Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

Return Value

YES if the receiver finds a valid floating-point representation, otherwise NO.

Discussion

Skips past excess digits in the case of overflow, so the scanner’s position is past the entire floating-point representation.

Invoke this method with NULL as doubleValue to simply scan past a double value representation. Floating-point representations are assumed to be IEEE compliant.

Availability
See Also
Declared In
NSScanner.h

scanFloat:

Scans for a float value, returning a found value by reference.

- (BOOL)scanFloat:(float *)floatValue

Parameters
floatValue

Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

Return Value

YES if the receiver finds a valid floating-point representation, otherwise NO.

Discussion

Skips past excess digits in the case of overflow, so the scanner’s position is past the entire floating-point representation.

Invoke this method with NULL as floatValue to simply scan past a float value representation. Floating-point representations are assumed to be IEEE compliant.

Availability
See Also
Related Sample Code
Declared In
NSScanner.h

scanHexDouble:

Scans for a double value from a hexadecimal representation, returning a found value by reference.

- (BOOL)scanHexDouble:(double *)result

Parameters
result

Upon return, contains the scanned value.

Return Value

YES if the receiver finds a valid double-point representation, otherwise NO.

Discussion

This corresponds to %a or %A formatting. The hexadecimal double representation must be preceded by 0x or 0X.

Invoke this method with NULL as result to simply scan past a hexadecimal double representation.

Availability
Declared In
NSScanner.h

scanHexFloat:

Scans for a double value from a hexadecimal representation, returning a found value by reference.

- (BOOL)scanHexFloat:(float *)result

Parameters
result

Upon return, contains the scanned value.

Return Value

YES if the receiver finds a valid float-point representation, otherwise NO.

Discussion

This corresponds to %a or %A formatting. The hexadecimal float representation must be preceded by 0x or 0X.

Invoke this method with NULL as result to simply scan past a hexadecimal float representation.

Availability
Declared In
NSScanner.h

scanHexInt:

Scans for an unsigned value from a hexadecimal representation, returning a found value by reference.

- (BOOL)scanHexInt:(unsigned *)intValue

Parameters
intValue

Upon return, contains the scanned value. Contains INT_MAX or INT_MIN on overflow.

Return Value

Returns YES if the receiver finds a valid hexadecimal integer representation, otherwise NO.

Discussion

The hexadecimal integer representation may optionally be preceded by 0x or 0X. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire hexadecimal representation.

Invoke this method with NULL as intValue to simply scan past a hexadecimal integer representation.

Availability
Declared In
NSScanner.h

scanHexLongLong:

Scans for a double value from a hexadecimal representation, returning a found value by reference.

- (BOOL)scanHexLongLong:(unsigned long long *)result

Parameters
result

Upon return, contains the scanned value.

Return Value

YES if the receiver finds a valid double-point representation, otherwise NO.

Discussion

Invoke this method with NULL as result to simply scan past a hexadecimal long long representation.

Availability
Declared In
NSScanner.h

scanInt:

Scans for an int value from a decimal representation, returning a found value by reference.

- (BOOL)scanInt:(int *)intValue

Parameters
intValue

Upon return, contains the scanned value. Contains INT_MAX or INT_MIN on overflow.

Return Value

YES if the receiver finds a valid decimal integer representation, otherwise NO.

Discussion

Skips past excess digits in the case of overflow, so the receiver’s position is past the entire decimal representation.

Invoke this method with NULL as intValue to simply scan past a decimal integer representation.

Availability
See Also
Declared In
NSScanner.h

scanInteger:

Scans for an NSInteger value from a decimal representation, returning a found value by reference

- (BOOL)scanInteger:(NSInteger *)value

Parameters
value

Upon return, contains the scanned value.

Return Value

YES if the receiver finds a valid integer representation, otherwise NO.

Discussion

Skips past excess digits in the case of overflow, so the receiver’s position is past the entire integer representation.

Invoke this method with NULL as value to simply scan past a decimal integer representation.

Availability
See Also
Declared In
NSScanner.h

scanLocation

Returns the character position at which the receiver will begin its next scanning operation.

- (NSUInteger)scanLocation

Return Value

The character position at which the receiver will begin its next scanning operation.

Availability
See Also
Declared In
NSScanner.h

scanLongLong:

Scans for a long long value from a decimal representation, returning a found value by reference.

- (BOOL)scanLongLong:(long long *)longLongValue

Parameters
longLongValue

Upon return, contains the scanned value. Contains LLONG_MAX or LLONG_MIN on overflow.

Return Value

YES if the receiver finds a valid decimal integer representation, otherwise NO.

Discussion

All overflow digits are skipped. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire decimal representation.

Invoke this method with NULL as longLongValue to simply scan past a long decimal integer representation.

Availability
Declared In
NSScanner.h

scanString:intoString:

Scans a given string, returning an equivalent string object by reference if a match is found.

- (BOOL)scanString:(NSString *)string intoString:(NSString **)stringValue

Parameters
string

The string for which to scan at the current scan location.

stringValue

Upon return, if the receiver contains a string equivalent to string at the current scan location, contains a string equivalent to string.

Return Value

YES if stringValue matches the characters at the scan location, otherwise NO.

Discussion

If string is present at the current scan location, then the current scan location is advanced to after the string; otherwise the scan location does not change.

Invoke this method with NULL as stringValue to simply scan past a given string.

Availability
See Also
Declared In
NSScanner.h

scanUpToCharactersFromSet:intoString:

Scans the string until a character from a given character set is encountered, accumulating characters into a string that’s returned by reference.

- (BOOL)scanUpToCharactersFromSet:(NSCharacterSet *)stopSet intoString:(NSString **)stringValue

Parameters
stopSet

The set of characters up to which to scan.

stringValue

Upon return, contains the characters scanned.

Return Value

YES if the receiver scanned any characters, otherwise NO.

If the only scanned characters are in the charactersToBeSkipped character set (which is the whitespace and newline character set by default), then returns NO.

Discussion

Invoke this method with NULL as stringValue to simply scan up to a given set of characters.

If no characters in stopSet are present in the scanner's source string, the remainder of the source string is put into stringValue, the receiver’s scanLocation is advanced to the end of the source string, and the method returns YES.

Availability
See Also
Declared In
NSScanner.h

scanUpToString:intoString:

Scans the string until a given string is encountered, accumulating characters into a string that’s returned by reference.

- (BOOL)scanUpToString:(NSString *)stopString intoString:(NSString **)stringValue

Parameters
stopString

The string to scan up to.

stringValue

Upon return, contains any characters that were scanned.

Return Value

YES if the receiver scans any characters, otherwise NO.

If the only scanned characters are in the charactersToBeSkipped character set (which by default is the whitespace and newline character set), then this method returns NO.

Discussion

If stopString is present in the receiver, then on return the scan location is set to the beginning of that string.

If stopString is the first string in the receiver, then the method returns NO and stringValue is not changed.

If the search string (stopString) isn't present in the scanner's source string, the remainder of the source string is put into stringValue, the receiver’s scanLocation is advanced to the end of the source string, and the method returns YES.

Invoke this method with NULL as stringValue to simply scan up to a given string.

Availability
See Also
Declared In
NSScanner.h

setCaseSensitive:

Sets whether the receiver is case sensitive when scanning characters.

- (void)setCaseSensitive:(BOOL)flag

Parameters
flag

If YES, the receiver will distinguish case when scanning characters, otherwise it will ignore case distinctions.

Discussion

Scanners are not case sensitive by default. Note that case sensitivity doesn’t apply to the characters to be skipped.

Availability
See Also
Declared In
NSScanner.h

setCharactersToBeSkipped:

Sets the set of characters to ignore when scanning for a value representation.

- (void)setCharactersToBeSkipped:(NSCharacterSet *)skipSet

Parameters
skipSet

The characters to ignore when scanning for a value representation.

Discussion

For example, if a scanner ignores spaces and you send it a scanInt: message, it skips spaces until it finds a decimal digit or other character. While an element is being scanned, however, no characters are skipped. If you scan for something made of characters in the set to be skipped (for example, using scanInt: when the set of characters to be skipped is the decimal digits), the result is undefined.

The characters to be skipped are treated literally as single values. A scanner doesn’t apply its case sensitivity setting to these characters and doesn’t attempt to match composed character sequences with anything in the set of characters to be skipped (though it does match pre-composed characters individually). If you want to skip all vowels while scanning a string, for example, you can set the characters to be skipped to those in the string “AEIOUaeiou” (plus any accented variants with pre-composed characters).

The default set of characters to skip is the whitespace and newline character set.

Availability
See Also
Related Sample Code
Declared In
NSScanner.h

setLocale:

Sets the receiver’s locale to a given locale.

- (void)setLocale:(id)aLocale

Parameters
aLocale

The locale for the receiver.

Discussion

A scanner’s locale affects the way it interprets values from the string. In particular, a scanner uses the locale’s decimal separator to distinguish the integer and fractional parts of floating-point representations. A new scanner’s locale is by default nil, which causes it to use non-localized values.

Availability
See Also
Declared In
NSScanner.h

setScanLocation:

Sets the location at which the next scan operation will begin to a given index.

- (void)setScanLocation:(NSUInteger)index

Parameters
index

The location at which the next scan operation will begin. Raises an NSRangeException if index is beyond the end of the string being scanned.

Discussion

This method is useful for backing up to rescan after an error.

Rather than setting the scan location directly to skip known sequences of characters, use scanString:intoString: or scanCharactersFromSet:intoString:, which allow you to verify that the expected substring (or set of characters) is in fact present.

Availability
See Also
Declared In
NSScanner.h

string

Returns the string with which the receiver was created or initialized.

- (NSString *)string

Return Value

The string with which the receiver was created or initialized.

Availability
See Also
Declared In
NSScanner.h

Next Page > Hide TOC

© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.