- Inherits from:
- NSObject
- Conforms to:
- NSCopying
- NSObject (NSObject)
Declared in:
- Foundation/NSScanner.h
- Foundation/NSDecimalNumber.h
An NSScanner object interprets and converts the characters of an NSString 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. This cluster has a single public class, NSScanner.
The objects you create using this class are referred to as scanner objects (and when no confusion will result, merely as scanners). 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 NSScanner class declares the programmatic interface for an object that scans values from an NSString object. NSScanner's primitive methods are string and all of the methods listed under "Configuring an NSScanner," found in "Method Types" .
Generally, you instantiate a scanner object by invoking the scannerWithString: or localizedScannerWithString: class methods. Either method returns a scanner object initialized with the string you pass to it. The newly created scanner starts at the beginning of its string, progressing through the characters as you request values with scan... methods. You can change the implicit scan location with the setScanLocation: method, to re-scan a portion of the string after an error or to skip ahead a certain number of characters. Scan operations start at the scan location and advance the scanner to just past the last character in the scanned value representation (if any). For example, after scanning an integer from the string "137 small cases of bananas", a scanner's location will be 3, indicating the space immediately after the number.
You can configure a scanner to skip a set of characters with the setCharactersToBeSkipped: method. A scanner ignores characters to be skipped at the beginning of any scan operation. Once it finds a scannable character, however, it includes all characters matching the request. Scanners skip whitespace and newline characters by default. If you continue with the previous example's string and use scanUpToString:intoString: to find the substring before "of", the scanner skips the space character before the word "small" but includes the space before "of" in its result unless you include a space in the search string:
Search String | Result String |
"of" (no space before) | "small cases " (includes the space following) |
" of" (space before) | "small cases" (stops before the space) |
You can also configure a scanner to consider or ignore case using the setCaseSensitive: method. By default a scanner ignores case. Note that case is always considered with regard to characters to be skipped. To skip all English vowels, for example, you must set the characters to be skipped to those in the string "AEIOUaeiou".
A scanner bases some of its scanning behavior on a locale,
which specifies a language and conventions for value representations.
NSScanner uses only the locale's definition for the decimal separator
(given by the key named NSDecimalSeparator
).
You can create a scanner with the user's locale by using localizedScannerWithString:, or set
the locale explicitly using setLocale:. If you use a method that doesn't
specify a locale, the scanner assumes the default locale values.
For an example of using a scanner, suppose you have a string containing lines such as:
This method scans such a string to extract the product information for each line:
- (BOOL)scanProductString:(NSString *)string { NSCharacterSet *semicolonSet; NSScanner *theScanner; NSString *PRODUCT = @"Product:"; NSString *COST = @"Cost:"; NSString *productName; float productCost; semicolonSet = [NSCharacterSet characterSetWithCharactersInString:@";"]; theScanner = [NSScanner scannerWithString:string]; while ([theScanner isAtEnd] == NO) { if ([theScanner scanString:PRODUCT intoString:NULL] && [theScanner scanUpToCharactersFromSet:semicolonSet ntoString:&productName] && theScanner scanString:@";" intoString:NULL] && [theScanner scanString:COST intoString:NULL] && [theScanner scanFloat:&productCost]) { /* Do something with productName and productCost. */ } else return NO; } return YES; }
This method uses alternating scan operations to skip the expected substrings "Product:" and "Cost:", as well as the semicolon, and to read the values for the product name and cost (read as a float for simplicity's sake). It returns NO if an error occurs on any scan operation, and YES if it successfully scans and processes all lines. Note that because a scanner skips whitespace and newlines by default, the loop does no special processing for them.
NSCopying
- - copyWithZone:
- Creating an NSScanner
- + scannerWithString:
- + localizedScannerWithString:
- - initWithString:
- Getting an NSScanner's string
- - string
- Configuring an NSScanner
- - setScanLocation:
- - scanLocation
- - setCaseSensitive:
- - caseSensitive
- - setCharactersToBeSkipped:
- - charactersToBeSkipped
- - setLocale:
- - locale
- Scanning a string
- - scanCharactersFromSet:intoString:
- - scanUpToCharactersFromSet:intoString:
- - scanDecimal:
- - scanDouble:
- - scanFloat:
- - scanInt:
- - scanHexInt:
- - scanLongLong:
- - scanString:intoString:
- - scanUpToString:intoString:
- - isAtEnd
+ (id)localizedScannerWithString:(NSString
*)aString
+ (id)scannerWithString:(NSString
*)aString
- (BOOL)caseSensitive
See Also: - setCaseSensitive:, - setCharactersToBeSkipped:
- (NSCharacterSet *)charactersToBeSkipped
The default set to skip is the whitespace and newline character set.
See Also: - setCharactersToBeSkipped:, + whitespaceAndNewlineCharacterSet (NSCharacterSet)
- (id)initWithString:(NSString
*)aString
See Also: + localizedScannerWithString:, + scannerWithString:
- (BOOL)isAtEnd
See Also: - charactersToBeSkipped
- (NSDictionary *)locale
nil
if it has none. 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 the default locale
values.See Also: - setLocale:
- (BOOL)scanCharactersFromSet:(NSCharacterSet
*)scanSet
intoString:(NSString **)stringValue
Invoke this method with nil as stringValue to simply scan past a given set of characters.
See Also: - scanUpToCharactersFromSet:intoString:
- (BOOL)scanDecimal:(NSDecimal
*)decimalValue
Invoke this method with nil as decimalValue to simply scan past an NSDecimal representation.
- (BOOL)scanDouble:(double
*)doubleValue
HUGE_VAL
or -HUGE_VAL
by
reference in doubleValue on overflow,
or 0.0 on underflow. 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 nil as doubleValue to simply scan past a double value representation. Floating-point representations are assumed to be IEEE compliant.
See Also: - doubleValue (NSString)
- (BOOL)scanFloat:(float
*)floatValue
HUGE_VAL
or -HUGE_VAL
by
reference in floatValue on overflow,
or 0.0 on underflow. 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 nil as floatValue to simply scan past a float value representation. Floating-point representations are assumed to be IEEE compliant.
See Also: - floatValue (NSString)
- (BOOL)scanHexInt:(unsigned
*)intValue
INT_MAX
or INT_MIN
by
reference in intValue on overflow.
Skips past excess digits in the case of overflow, so the scanner's
position is past the entire hexadecimal representation.Invoke this method with nil as intValue to simply scan past a hexadecimal integer representation.
- (BOOL)scanInt:(int
*)intValue
INT_MAX
or INT_MIN
by
reference in intValue on overflow.
Skips past excess digits in the case of overflow, so the scanner's
position is past the entire decimal representation.Invoke this method with nil as intValue to simply scan past a decimal integer representation.
See Also: - intValue (NSString)
- (unsigned)scanLocation
See Also: - setScanLocation:
- (BOOL)scanLongLong:(long
long *)longLongValue
LONG_LONG_MAX
or LONG_LONG_MIN
by
reference in longLongValue on overflow.
All overflow digits are skipped. Skips past excess digits in the
case of overflow, so the scanner's position is past the entire
decimal representation.Invoke this method with nil as longLongValue to simply scan past a long decimal integer representation.
- (BOOL)scanString:(NSString
*)string
intoString:(NSString **)stringValue
Invoke this method with nil as stringValue to simply scan past a given string.
See Also: - scanUpToString:intoString:
- (BOOL)scanUpToCharactersFromSet:(NSCharacterSet
*)stopSet
intoString:(NSString **)stringValue
Invoke this method with nil as stringValue to simply scan up to a given set of characters.
See Also: - scanCharactersFromSet:intoString:
- (BOOL)scanUpToString:(NSString
*)stopString
intoString:(NSString **)stringValue
Invoke this method with nil as stringValue to simply scan up to a given string.
See Also: - scanString:intoString:
- (void)setCaseSensitive:(BOOL)flag
See Also: - caseSensitive, - setCharactersToBeSkipped:
- (void)setCharactersToBeSkipped:(NSCharacterSet
*)skipSet
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 precomposed 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 precomposed characters).
The default set of characters to skip is the whitespace and newline character set.
See Also: - charactersToBeSkipped, + whitespaceCharacterSet (NSCharacterSet)
- (void)setLocale:(NSDictionary
*)aLocale
nil
,
which causes it to use the default locale values.See Also: - locale
- (void)setScanLocation:(unsigned)index
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.
See Also: - scanLocation
- (NSString *)string
See Also: - locale