NSScanner Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSDecimalNumber.h NSScanner.h |
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.” 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]].
Tasks
Creating a Scanner
Getting a Scanner’s String
Configuring a Scanner
-
– setScanLocation: -
– scanLocation -
– setCaseSensitive: -
– caseSensitive -
– setCharactersToBeSkipped: -
– charactersToBeSkipped -
– setLocale: -
– locale
Scanning a String
Class Methods
localizedScannerWithString:
Returns an NSScanner object that scans a given string according to the user’s default locale.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hscannerWithString:
Returns an NSScanner object that scans a given string.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hInstance Methods
caseSensitive
Returns a Boolean value that indicates whether the receiver distinguishes case in the characters it scans.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hcharactersToBeSkipped
Returns a character set containing the characters the receiver ignores when looking for a scannable element.
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
- Available in OS X v10.0 and later.
See Also
-
– setCharactersToBeSkipped: -
whitespaceAndNewlineCharacterSet(NSCharacterSet)
Declared In
NSScanner.hinitWithString:
Returns an NSScanner object initialized to scan a given string.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hisAtEnd
Returns a Boolean value that indicates whether the receiver has exhausted all significant characters
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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hlocale
Returns the receiver’s 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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hscanCharactersFromSet: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.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hscanDecimal:
Scans for an NSDecimal value, returning a found value by reference.
Parameters
- decimalValue
Upon return, contains the scanned value. See the
NSDecimalNumberclass specification for more information aboutNSDecimalvalues.
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
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hscanDouble:
Scans for a double value, returning a found value by reference.
Parameters
- doubleValue
Upon return, contains the scanned value. Contains
HUGE_VALor–HUGE_VALon overflow, or0.0on 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
- Available in OS X v10.0 and later.
See Also
-
doubleValue(NSString)
Declared In
NSScanner.hscanFloat:
Scans for a float value, returning a found value by reference.
Parameters
- floatValue
Upon return, contains the scanned value. Contains
HUGE_VALor–HUGE_VALon overflow, or0.0on 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
- Available in OS X v10.0 and later.
See Also
-
floatValue(NSString)
Declared In
NSScanner.hscanHexDouble:
Scans for a double value from a hexadecimal representation, returning a found value by reference.
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
- Available in OS X v10.5 and later.
Declared In
NSScanner.hscanHexFloat:
Scans for a double value from a hexadecimal representation, returning a found value by reference.
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
- Available in OS X v10.5 and later.
Declared In
NSScanner.hscanHexInt:
Scans for an unsigned value from a hexadecimal representation, returning a found value by reference.
Parameters
- intValue
Upon return, contains the scanned value. Contains
INT_MAXorINT_MINon 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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hscanHexLongLong:
Scans for a long long value from a hexadecimal representation, returning a found value by reference.
Parameters
- result
Upon return, contains the scanned value.
Return Value
YES if the receiver finds a valid hexadecimal long long 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 result to simply scan past a hexadecimal long long representation.
Availability
- Available in OS X v10.5 and later.
Declared In
NSScanner.hscanInt:
Scans for an int value from a decimal representation, returning a found value by reference.
Parameters
- intValue
Upon return, contains the scanned value. Contains
INT_MAXorINT_MINon 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
- Available in OS X v10.0 and later.
See Also
-
intValue(NSString) -
– scanInteger:
Declared In
NSScanner.hscanInteger:
Scans for an NSInteger value from a decimal representation, returning a found value by reference
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
- Available in OS X v10.5 and later.
See Also
-
integerValue(NSString) -
– scanInt:
Declared In
NSScanner.hscanLocation
Returns the character position at which the receiver will begin its next scanning operation.
Return Value
The character position at which the receiver will begin its next scanning operation.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hscanLongLong:
Scans for a long long value from a decimal representation, returning a found value by reference.
Parameters
- longLongValue
Upon return, contains the scanned value. Contains
LLONG_MAXorLLONG_MINon 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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hscanString:intoString:
Scans a given string, returning an equivalent string object by reference if a match is found.
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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hscanUpToCharactersFromSet:intoString:
Scans the string until a character from a given character set is encountered, accumulating characters into a string that’s returned by reference.
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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hscanUpToString:intoString:
Scans the string until a given string is encountered, accumulating characters into a string that’s returned by reference.
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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hsetCaseSensitive:
Sets whether the receiver is case sensitive when scanning characters.
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
- Available in OS X v10.0 and later.
Declared In
NSScanner.hsetCharactersToBeSkipped:
Sets the set of characters to ignore when scanning for a value representation.
Parameters
- skipSet
The characters to ignore when scanning for a value representation. Pass
nilto not ignore any characters.
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
- Available in OS X v10.0 and later.
See Also
-
– charactersToBeSkipped -
whitespaceAndNewlineCharacterSet(NSCharacterSet)
Declared In
NSScanner.hsetLocale:
Sets the receiver’s locale to a given locale.
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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.hsetScanLocation:
Sets the location at which the next scan operation will begin to a given index.
Parameters
- index
The location at which the next scan operation will begin. Raises an
NSRangeExceptionif 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
- Available in OS X v10.0 and later.
See Also
Declared In
NSScanner.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-01-21)