Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 scan¼ 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.

Getting an NSScanner's String

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

Configuring an NSScanner

- (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.

Scanning a String

In the scan¼methods 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.