NSScanner

Inherits From: NSObject

Conforms To: NSCopying NSObject (NSObject)

Declared In: Foundation/NSScanner.h

Class Description

The NSScanner class declares the programmatic interface to an object that is capable of scanning NSString objects (strings of characters in the UniCode character encoding), converting the scanned strings to various numeric representations, or scanning characters from a character set.

Generally, you instantiate a scanner object by sending one of scannerWithString: or localizedScannerWithString: methods to the NSScanner class object. Either method returns a scanner object initialized with the string you pass in.

NSScanner provides methods of configuring the behavior of the scan. setCaseSensitive: specifies whether the scanner will treat upper case and lower case letters as distinct. setCharactersToBeSkipped: determines the set of characters that will be skipped while scanning. The preset set of characters to skip are whitespace and newline characters. setLocale: specifies the locale to be used while scanning strings. setScanLocation: sets the index in the string object at that scanning will commence. Using this method, you can repeatedly scan portions of a string.

Scanning is performed using any of the scan1/4 methods listed under Scanning a String.

Note that floating point numbers are assumed to be IEEE compliant.

Creating an NSScanner

• + (id)localizedScannerWithString:(NSString *)aString Creates and returns a scanner that scans aString. Invokes initWithString: and sets the locale to the user's default locale.
• + (id)scannerWithString:(NSString *)aString Creates and returns a scanner that scans aString.
• - (id)initWithString:(NSString *)aString Initializes the receiver, a newly allocated scanner, to scan aString. Returns self.

• - (NSString *)string Returns the string object that the scanner was created with.

• - (BOOL)caseSensitive Returns YES if the scanner distinguishes case, and NO otherwise. Scanners are by default not case sensitive.
• - (NSCharacterSet *)charactersToBeSkipped Returns a character set object containing those characters that the scanner ignores when looking for an element. The default set is the whitespace and newline character set.
• - (NSDictionary *)locale Returns a dictionary object containing locale information. Returns nil if the locale dictionary has not been set.
• - (unsigned)scanLocation Returns the character index at which the scanner will begin its next scanning operation.
• - (void)setCaseSensitive:(BOOL)flag If flag is YES, the scanner considers case when scanning characters. If flag is NO, it ignores case distinctions. NSScanners are by default not case sensitive.
• - (void)setCharactersToBeSkipped:(NSCharacterSet *)aSet Sets the scanner to ignore characters from aSet when scanning its string.
• - (void)setLocale:(NSDictionary *)localeDictionary Sets the receiver's dictionary object containing locale information.
• - (void)setScanLocation:(unsigned int)anIndex Sets the location at which the next scan will begin to anIndex.

In the scan1/4methods listed here, the value arguments (which are values returned by reference) are optional. Pass an argument value of nil if you do not wish a return value.

- (BOOL)scanCharactersFromSet:(NSCharacterSet *)aSet

intoString:(NSString **)value Scans the string as long as characters from aSet are encountered, accumulating characters into an optional string that's returned by reference in value. If any characters are scanned, returns YES; otherwise returns NO.

- (BOOL)scanDouble:(double *)value Scans a double into value if possible. Returns YES if a valid floating-point expression was scanned; NO otherwise. HUGE_VAL or -HUGE_VAL is put in value on overflow; 0.0 on underflow. Returns YES in overflow and underflow cases

- (BOOL)scanFloat:(float *)value Scans a float into value if possible. Returns YES if a valid floating-point expression was scanned; NO otherwise. HUGE_VAL or -HUGE_VAL is put in value on overflow; 0.0 on underflow. Returns YES in overflow and underflow cases.

- (BOOL)scanInt:(int *)value Scans an int into value if possible. Returns YES if a valid integer expression was scanned; NO otherwise. INT_MAX or INT_MIN is put in value on overflow. Returns YES in overflow cases.

- (BOOL)scanLongLong:(long long *)value Scans a long long int into value if possible. Returns YES if a valid integer expression was scanned; NO otherwise. LONG_LONG_MAX or LONG_LONG_MIN is put in value on overflow. Returns YES in overflow cases.

- (BOOL)scanString:(NSString *)aString Scans for aString, and if a match is found returns by

intoString:(NSString **)value reference in the optional value argument a string object equal to it. If aString matches the characters at the scan location, returns YES; otherwise returns NO.

- (BOOL)scanUpToCharactersFromSet:(NSCharacterSet *)aSet

intoString:(NSString **)value Scans the string until a character from aSet is encountered, accumulating characters encountered into a string that's returned by reference in the optional value argument. If any characters are scanned, returns YES; otherwise returns NO.

- (BOOL)scanUpToString:(NSString *)aString Scans the string until aString is encountered,

intoString:(NSString **)value accumulating characters encountered into a string that's returned by reference in the optional value argument. If any characters are scanned, returns YES; otherwise returns NO.

- (BOOL)isAtEnd Returns YES if the scanner has exhausted all characters in its string; NO if there are characters left to scan.