Up

NSScanner class reference

Authors

Eric Norum (eric@skatter.usask.ca)
Richard Frith-Macdonald (rfm@gnu.org)

Version: 26606

Date: 2008-06-08 11:38:33 +0100 (Sun, 08 Jun 2008)

Copyright: (C) 1996,1999 Free Software Foundation, Inc.

Software documentation for the NSScanner class

NSScanner : NSObject

Declared in:
Foundation/NSScanner.h
Conforms to:
NSCopying
Availability: OpenStep

The NSScanner class cluster (currently a single class in GNUstep) provides a mechanism to parse the contents of a string into number and string values by making a sequence of scan operations to step through the string retrieving successive items.

You can tell the scanner whether its scanning is supposed to be case sensitive or not, and you can specify a set of characters to be skipped before each scanning operation (by default, whitespace and newlines).

Method summary

localizedScannerWithString: 

+ (id) localizedScannerWithString: (NSString*)aString;
Availability: OpenStep

Returns an NSScanner instance set up to scan aString (using -initWithString: and with a locale set the default locale (using -setLocale:

scannerWithString: 

+ (id) scannerWithString: (NSString*)aString;
Availability: OpenStep

Create and return a scanner that scans aString.
Uses -initWithString: and with no locale set.

caseSensitive 

- (BOOL) caseSensitive;
Availability: OpenStep

If the scanner is set to be case-sensitive in its scanning of the string (other than characters to be skipped), this method returns YES, otherwise it returns NO.
The default is for a scanner to not be case sensitive.

charactersToBeSkipped 

- (NSCharacterSet*) charactersToBeSkipped;
Availability: OpenStep

Returns a set of characters containing those characters that the scanner ignores when starting any scan operation. Once a character not in this set has been encountered during an operation, skipping is finished, and any further characters from this set that are found are scanned normally.
The default for this is the whitespaceAndNewlineCharacterSet.

initWithString: 

- (id) initWithString: (NSString*)aString;
Availability: OpenStep

Initialises the scanner to scan aString. The GNUstep implementation may make an internal copy of the original string - so it is not safe to assume that if you modify a mutable string that you initialised a scanner with, the changes will be visible to the scanner.
Returns the scanner object.

isAtEnd 

- (BOOL) isAtEnd;
Availability: OpenStep

Returns YES if no more characters remain to be scanned.
Returns YES if all characters remaining to be scanned are to be skipped.
Returns NO if there are characters left to scan.

locale 

- (NSDictionary*) locale;
Availability: OpenStep

Returns the locale set for the scanner, or nil if no locale has been set. A scanner uses it's locale to alter the way it handles scanning - it uses the NSDecimalSeparator value for scanning numbers.

scanCharactersFromSet: intoString: 

- (BOOL) scanCharactersFromSet: (NSCharacterSet*)aSet intoString: (NSString**)value;
Availability: OpenStep

After initial skipping (if any), this method scans any characters from aSet, terminating when a character not in the set is found.
Returns YES if any character is scanned, NO otherwise.
If value is not null, any character scanned are stored in a string returned in this location.

scanDecimal: 

- (BOOL) scanDecimal: (NSDecimal*)value;
Availability: MacOS-X 10.0.0

Not implemented.

scanDouble: 

- (BOOL) scanDouble: (double*)value;
Availability: OpenStep

After initial skipping (if any), this method scans a double value, placing it in doubleValue if that is not null. Returns YES if anything is scanned, NO otherwise.
On overflow, HUGE_VAL or - HUGE_VAL is put into doubleValue
On underflow, 0.0 is put into doubleValue
Scans past any excess digits

scanFloat: 

- (BOOL) scanFloat: (float*)value;
Availability: OpenStep

After initial skipping (if any), this method scans a float value, placing it in floatValue if that is not null. Returns YES if anything is scanned, NO otherwise.
On overflow, HUGE_VAL or - HUGE_VAL is put into floatValue
On underflow, 0.0 is put into floatValue
Scans past any excess digits

scanHexDouble: 

- (BOOL) scanHexDouble: (double*)result;
Availability: MacOS-X 10.5.0

Not implemented

scanHexFloat: 

- (BOOL) scanHexFloat: (float*)result;
Availability: MacOS-X 10.5.0

Not implemented

scanHexInt: 

- (BOOL) scanHexInt: (unsigned int*)value;
Availability: OpenStep

After initial skipping (if any), this method scans a hexadecimal integer value (optionally prefixed by "0x" or "0X"), placing it in intValue if that is not null.
Returns YES if anything is scanned, NO otherwise.
On overflow, INT_MAX or INT_MIN is put into intValue
Scans past any excess digits

scanHexLongLong: 

- (BOOL) scanHexLongLong: (unsigned long long*)result;
Availability: MacOS-X 10.5.0

Not implemented

scanInt: 

- (BOOL) scanInt: (int*)value;
Availability: OpenStep

After initial skipping (if any), this method scans a integer value, placing it in intValue if that is not null.
Returns YES if anything is scanned, NO otherwise.
On overflow, INT_MAX or INT_MIN is put into intValue
Scans past any excess digits

scanInteger: 

- (BOOL) scanInteger: (NSInteger*)value;
Availability: MacOS-X 10.5.0

Not implemented

scanLocation 

- (unsigned) scanLocation;
Availability: OpenStep

Returns the current position that the scanner has reached in scanning the string. This is the position at which the next scan operation will begin.

scanLongLong: 

- (BOOL) scanLongLong: (long long*)value;
Availability: OpenStep

After initial skipping (if any), this method scans a long decimal integer value placing it in longLongValue if that is not null.
Returns YES if anything is scanned, NO otherwise.
On overflow, LONG_LONG_MAX or LONG_LONG_MIN is put into longLongValue
Scans past any excess digits

scanRadixUnsignedInt: 

- (BOOL) scanRadixUnsignedInt: (unsigned int*)value;
Availability: Not in OpenStep/MacOS-X

After initial skipping (if any), this method scans an unsigned integer value placing it in intValue if that is not null. If the number begins with "0x" or "0X" it is treated as hexadecimal, otherwise if the number begins with "0" it is treated as octal, otherwise the number is treated as decimal.
Returns YES if anything is scanned, NO otherwise.
On overflow, INT_MAX or INT_MIN is put into intValue
Scans past any excess digits

scanString: intoString: 

- (BOOL) scanString: (NSString*)string intoString: (NSString**)value;
Availability: OpenStep

After initial skipping (if any), this method scans for string and places the characters found in value if that is not null.
Returns YES if anything is scanned, NO otherwise.

scanUpToCharactersFromSet: intoString: 

- (BOOL) scanUpToCharactersFromSet: (NSCharacterSet*)aSet intoString: (NSString**)value;
Availability: OpenStep

After initial skipping (if any), this method scans characters until it finds one in set. The scanned characters are placed in stringValue if that is not null.
Returns YES if anything is scanned, NO otherwise.

scanUpToString: intoString: 

- (BOOL) scanUpToString: (NSString*)string intoString: (NSString**)value;
Availability: OpenStep

After initial skipping (if any), this method scans characters until it finds string. The scanned characters are placed in value if that is not null. If string is not found, all the characters up to the end of the scanned string will be returned.

Returns YES if anything is scanned, NO otherwise.

NB. If the current scanner location points to a copy of string, or points to skippable characters immediately before a copy of string then this method returns NO since it finds no characters to store in value before it finds string.

To count the occurrences of string, this should be used in conjunction with the -scanString:intoString: method.

 NSString *ch = @"[";
 unsigned total = 0;

 [scanner scanUpToString: ch intoString: NULL];
 while ([scanner scanString: ch intoString: NULL] == YES)
  {
    total++;
    [scanner scanUpToString: ch intoString: NULL];
  }
 NSLog(@"total %d", total);
 

setCaseSensitive: 

- (void) setCaseSensitive: (BOOL)flag;
Availability: OpenStep

Sets the case sensitivity of the scanner.
Case sensitivity governs matching of characters being scanned, but does not effect the characters in the set to be skipped.
The default is for a scanner to not be case sensitive.

setCharactersToBeSkipped: 

- (void) setCharactersToBeSkipped: (NSCharacterSet*)aSet;
Availability: OpenStep

Sets the set of characters that the scanner will skip over at the start of each scanning operation to be skipSet. Skipping is performed by literal character matching - the case sensitivity of the scanner does not effect it. If this is set to nil, no skipping is done.
The default for this is the whitespaceAndNewlineCharacterSet.

setLocale: 

- (void) setLocale: (NSDictionary*)localeDictionary;
Availability: OpenStep

This method sets the locale used by the scanner to aLocale. The locale may be set to nil.

setScanLocation: 

- (void) setScanLocation: (unsigned int)anIndex;
Availability: OpenStep

This method sets the location in the scanned string at which the next scan operation begins. Raises an NSRangeException if index is beyond the end of the scanned string.

string 

- (NSString*) string;
Availability: OpenStep

Returns the string being scanned.


Up