NSScanner Class Cluster

Class Cluster Description

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.

Scanning Behavior

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. See "Locales" in the "Other Features" section of the Foundation Kit documentation for more information on locales.

For an example of using a scanner, suppose you have a string containing lines such as:

Product: Acme Potato Peeler; Cost: 0.98
Product: Chef Pierre Pasta Fork; Cost: 0.75
Product: Chef Pierre Colander; Cost: 1.27

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.

NSScanner

Inherits From:
NSObject

Conforms To:
NSCopying
NSObject (NSObject)

Declared In:
Foundation/NSScanner.h
Foundation/NSDecimalNumber.h

Class Description

Adopted Protocols

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

Class Methods

localizedScannerWithString:

Returns an NSScanner that scans aString according to the user's default locale (set with setLocale:). Sets the string to scan by invoking initWithString: with aString. See "Locales" in the "Other Features" section of the Foundation Kit documentation for more information on locales.

scannerWithString:

Returns an NSScanner that scans aString. Sets the string to scan by invoking initWithString: with aString.

Instance Methods

caseSensitive

Returns YES if the scanner distinguishes case in the characters it scans, NO otherwise. NSScanners are not case sensitive by default. Note that case sensitivity doesn't apply to the characters to be skipped.

See also: - setCaseSensitive:, - setCharactersToBeSkipped:

charactersToBeSkipped

Returns a character set containing the characters that the scanner ignores when looking for a scannable element. 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.

See also: - setCharactersToBeSkipped:, + whitespaceAndNewlineCharacterSet (NSCharacterSet)

initWithString:

Initializes a newly allocated NSScanner to scan aString from the beginning. Returns self.

See also: + localizedScannerWithString:, + scannerWithString:

isAtEnd

Returns YES if the scanner has exhausted all significant characters in its string, NO if there are characters left to scan. If only characters from the set to be skipped remain, this method returns YES.

See also: - charactersToBeSkipped

locale

Returns the scanner's locale, or 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 "Locales" in the "Other Features" section of the Foundation Kit documentation for more information on locales.

See also: - setLocale:

scanCharactersFromSet:intoString:

Scans the string as long as characters from scanSet are encountered, accumulating characters into a string that's returned by reference in stringValue. Returns YES if the scanner scans any characters; otherwise returns NO.

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

See also: - scanUpToCharactersFromSet:intoString:

scanDecimal:

Scans an NSDecimal value if possible, returning it by reference in decimalValue. Returns YES if the scanner finds a valid NSDecimal representation, NO otherwise. See the NSDecimalNumber class specification for more information.

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

scanDouble:

Scans a double value if possible, returning it by reference in doubleValue. Returns YES if the scanner finds a valid floating-point representation, NO otherwise. Returns HUGE_VAL or -HUGE_VAL by reference in value on overflow, or 0.0 on underflow. Skips past excess digits in the case of overflow, so that 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.