Mac Developer Library

Developer

Foundation Framework Reference NSScanner Class Reference

Options
Deployment Target:

On This Page
Language:

NSScanner

The NSScanner class is an abstract superclass of a class cluster that declares the programmatic interface for an object that scans values from an NSString object. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns an NSScanner object that scans a given string.

    Declaration

    Objective-C

    + (instancetype)scannerWithString:(NSString *)aString

    Parameters

    aString

    The string to scan.

    Return Value

    An NSScanner object that scans aString.

    Discussion

    Sets the string to scan by invoking initWithString: with aString.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSScanner object that scans a given string according to the user’s default locale.

    Declaration

    Swift

    class func localizedScannerWithString(_ aString: String) -> AnyObject

    Objective-C

    + (id)localizedScannerWithString:(NSString *)aString

    Parameters

    aString

    The string to scan.

    Return Value

    An NSScanner object that scans aString according to the user’s default locale.

    Discussion

    Sets the string to scan by invoking initWithString: with aString. The locale is set with setLocale:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • init(string:) initWithString: Designated Initializer

    Returns an NSScanner object initialized to scan a given string.

    Declaration

    Swift

    init(string aString: String)

    Objective-C

    - (instancetype)initWithString:(NSString *)aString

    Parameters

    aString

    The string to scan.

    Return Value

    An NSScanner object initialized to scan aString from the beginning. The returned object might be different than the original receiver.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • string string Property

    The string the scanner will scan. (read-only)

    Declaration

    Swift

    var string: String { get }

    Objective-C

    @property(readonly, copy) NSString *string

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The character position at which the receiver will begin its next scanning operation.

    Declaration

    Swift

    var scanLocation: Int

    Objective-C

    @property NSUInteger scanLocation

    Discussion

    Raises an NSRangeException if index is beyond the end of the string being scanned.

    This property is useful for backing up to rescan after an error.

    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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Flag that indicates whether the receiver distinguishes case in the characters it scans.

    Declaration

    Swift

    var caseSensitive: Bool

    Objective-C

    @property BOOL caseSensitive

    Discussion

    YEStrue if the receiver distinguishes case in the characters it scans, otherwise NOfalse. The default value is NOfalse. Note that case sensitivity doesn’t apply to the characters to be skipped.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Character set containing the characters the scanner ignores when looking for a scannable element.

    Declaration

    Swift

    @NSCopying var charactersToBeSkipped: NSCharacterSet?

    Objective-C

    @property(copy) NSCharacterSet *charactersToBeSkipped

    Discussion

    Characters to be skipped are skipped prior to the scanner examining the target. 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, 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 characters to be skipped are treated 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 pre-composed 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 pre-composed characters).

    The default set to skip is the whitespace and newline character set.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    whitespaceAndNewlineCharacterSet (NSCharacterSet)

  • locale locale Property

    The locale to use when scanning.

    Declaration

    Swift

    var locale: AnyObject?

    Objective-C

    @property(retain) id locale

    Discussion

    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 non-localized values. New scanners have no locale by default.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans the string as long as characters from a given character set are encountered, accumulating characters into a string that’s returned by reference.

    Declaration

    Swift

    func scanCharactersFromSet(_ scanSet: NSCharacterSet, intoString stringValue: AutoreleasingUnsafeMutablePointer<NSString?>) -> Bool

    Objective-C

    - (BOOL)scanCharactersFromSet:(NSCharacterSet *)scanSet intoString:(NSString **)stringValue

    Parameters

    scanSet

    The set of characters to scan.

    stringValue

    Upon return, contains the characters scanned.

    Return Value

    YEStrue if the receiver scanned any characters, otherwise NOfalse.

    Discussion

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans the string until a character from a given character set is encountered, accumulating characters into a string that’s returned by reference.

    Declaration

    Swift

    func scanUpToCharactersFromSet(_ stopSet: NSCharacterSet, intoString stringValue: AutoreleasingUnsafeMutablePointer<NSString?>) -> Bool

    Objective-C

    - (BOOL)scanUpToCharactersFromSet:(NSCharacterSet *)stopSet intoString:(NSString **)stringValue

    Parameters

    stopSet

    The set of characters up to which to scan.

    stringValue

    Upon return, contains the characters scanned.

    Return Value

    YEStrue if the receiver scanned any characters, otherwise NOfalse.

    If the only scanned characters are in the charactersToBeSkipped character set (which is the whitespace and newline character set by default), then returns NOfalse.

    Discussion

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

    If no characters in stopSet are present in the scanner's source string, the remainder of the source string is put into stringValue, the receiver’s scanLocation is advanced to the end of the source string, and the method returns YEStrue.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans for an NSDecimal value, returning a found value by reference.

    Declaration

    Swift

    func scanDecimal(_ decimalValue: COpaquePointer) -> Bool

    Objective-C

    - (BOOL)scanDecimal:(NSDecimal *)decimalValue

    Parameters

    decimalValue

    Upon return, contains the scanned value. See the NSDecimalNumber class specification for more information about NSDecimal values.

    Return Value

    YEStrue if the receiver finds a valid NSDecimal representation, otherwise NOfalse.

    Discussion

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans for a double value, returning a found value by reference.

    Declaration

    Swift

    func scanDouble(_ doubleValue: UnsafeMutablePointer<Double>) -> Bool

    Objective-C

    - (BOOL)scanDouble:(double *)doubleValue

    Parameters

    doubleValue

    Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

    Return Value

    YEStrue if the receiver finds a valid floating-point representation, otherwise NOfalse. Overflow or underflow are both considered valid floating-point representations.

    Discussion

    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 NULL as doubleValue to simply scan past a double value representation. Floating-point representations are assumed to be IEEE compliant.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    doubleValue (NSString)

  • Scans for a float value, returning a found value by reference.

    Declaration

    Swift

    func scanFloat(_ floatValue: UnsafeMutablePointer<Float>) -> Bool

    Objective-C

    - (BOOL)scanFloat:(float *)floatValue

    Parameters

    floatValue

    Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

    Return Value

    YEStrue if the receiver finds a valid floating-point representation, otherwise NOfalse. Overflow or underflow are both considered valid floating-point representations.

    Discussion

    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 NULL as floatValue to simply scan past a float value representation. Floating-point representations are assumed to be IEEE compliant.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    floatValue (NSString)

  • Scans for a double value from a hexadecimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanHexDouble(_ result: UnsafeMutablePointer<Double>) -> Bool

    Objective-C

    - (BOOL)scanHexDouble:(double *)result

    Parameters

    result

    Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

    Return Value

    YEStrue if the receiver finds a valid double-point representation, otherwise NOfalse. Overflow or underflow are both considered valid floating-point representations.

    Discussion

    This corresponds to %a or %A formatting. The hexadecimal double representation must be preceded by 0x or 0X.

    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 NULL as result to simply scan past a hexadecimal double representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Scans for a double value from a hexadecimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanHexFloat(_ result: UnsafeMutablePointer<Float>) -> Bool

    Objective-C

    - (BOOL)scanHexFloat:(float *)result

    Parameters

    result

    Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow, or 0.0 on underflow.

    Return Value

    YEStrue if the receiver finds a valid float-point representation, otherwise NOfalse. Overflow or underflow are both considered valid floating-point representations.

    Discussion

    This corresponds to %a or %A formatting. The hexadecimal float representation must be preceded by 0x or 0X.

    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 NULL as result to simply scan past a hexadecimal float representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Scans for an unsigned value from a hexadecimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanHexInt(_ intValue: UnsafeMutablePointer<UInt32>) -> Bool

    Objective-C

    - (BOOL)scanHexInt:(unsigned int *)intValue

    Parameters

    intValue

    Upon return, contains the scanned value. Contains UINT_MAX on overflow.

    Return Value

    Returns YEStrue if the receiver finds a valid hexadecimal integer representation, otherwise NOfalse. Overflow is considered a valid hexadecimal integer representation.

    Discussion

    The hexadecimal integer representation may optionally be preceded by 0x or 0X. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire hexadecimal representation.

    Invoke this method with NULL as intValue to simply scan past a hexadecimal integer representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans for a long long value from a hexadecimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanHexLongLong(_ result: UnsafeMutablePointer<UInt64>) -> Bool

    Objective-C

    - (BOOL)scanHexLongLong:(unsigned long long *)result

    Parameters

    result

    Upon return, contains the scanned value. Contains HUGE_VAL or –HUGE_VAL on overflow.

    Return Value

    YEStrue if the receiver finds a valid hexadecimal long long representation, otherwise NOfalse. Overflow is considered a valid hexadecimal long long representation.

    Discussion

    The hexadecimal integer representation may optionally be preceded by 0x or 0X. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire hexadecimal representation.

    Invoke this method with NULL as result to simply scan past a hexadecimal long long representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Scans for an NSInteger value from a decimal representation, returning a found value by reference

    Declaration

    Swift

    func scanInteger(_ value: UnsafeMutablePointer<Int>) -> Bool

    Objective-C

    - (BOOL)scanInteger:(NSInteger *)value

    Parameters

    value

    Upon return, contains the scanned value. Contains INT_MAX or INT_MIN on overflow.

    Return Value

    YEStrue if the receiver finds a valid integer representation, otherwise NOfalse. Overflow is considered a valid integer representation.

    Discussion

    Skips past excess digits in the case of overflow, so the receiver’s position is past the entire integer representation.

    Invoke this method with NULL as value to simply scan past a decimal integer representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.

    See Also

    integerValue (NSString)
    – scanInt:

  • Scans for an int value from a decimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanInt(_ intValue: UnsafeMutablePointer<Int32>) -> Bool

    Objective-C

    - (BOOL)scanInt:(int *)intValue

    Parameters

    intValue

    Upon return, contains the scanned value. Contains INT_MAX or INT_MIN on overflow.

    Return Value

    YEStrue if the receiver finds a valid decimal integer representation, otherwise NOfalse. Overflow is considered a valid integer representation.

    Discussion

    Skips past excess digits in the case of overflow, so the receiver’s position is past the entire decimal representation.

    Invoke this method with NULL as intValue to simply scan past a decimal integer representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    intValue (NSString)
    – scanInteger:

  • Scans for a long long value from a decimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanLongLong(_ longLongValue: UnsafeMutablePointer<Int64>) -> Bool

    Objective-C

    - (BOOL)scanLongLong:(long long *)longLongValue

    Parameters

    longLongValue

    Upon return, contains the scanned value. Contains LLONG_MAX or LLONG_MIN on overflow.

    Return Value

    YEStrue if the receiver finds a valid decimal integer representation, otherwise NOfalse. Overflow is considered a valid decimal integer representation.

    Discussion

    All overflow digits are skipped. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire decimal representation.

    Invoke this method with NULL as longLongValue to simply scan past a long decimal integer representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans a given string, returning an equivalent string object by reference if a match is found.

    Declaration

    Swift

    func scanString(_ string: String, intoString stringValue: AutoreleasingUnsafeMutablePointer<NSString?>) -> Bool

    Objective-C

    - (BOOL)scanString:(NSString *)string intoString:(NSString **)stringValue

    Parameters

    string

    The string for which to scan at the current scan location.

    stringValue

    Upon return, if the receiver contains a string equivalent to string at the current scan location, contains a string equivalent to string.

    Return Value

    YEStrue if string matches the characters at the scan location, otherwise NOfalse.

    Discussion

    If string is present at the current scan location, then the current scan location is advanced to after the string; otherwise the scan location does not change.

    Invoke this method with NULL as stringValue to simply scan past a given string.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Scans for an unsigned long long value from a decimal representation, returning a found value by reference.

    Declaration

    Swift

    func scanUnsignedLongLong(_ unsignedLongLongValue: UnsafeMutablePointer<UInt64>) -> Bool

    Objective-C

    - (BOOL)scanUnsignedLongLong:(unsigned long long *)unsignedLongLongValue

    Parameters

    unsignedLongLongValue

    Upon return, contains the scanned value. Contains ULLONG_MAX on overflow.

    Return Value

    YEStrue if the receiver finds a valid decimal integer representation, otherwise NOfalse. Overflow is considered a valid decimal integer representation.

    Discussion

    All overflow digits are skipped. Skips past excess digits in the case of overflow, so the receiver’s position is past the entire decimal representation.

    Invoke this method with NULL as unsignedLongLongValue to simply scan past an unsigned long decimal integer representation.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • Scans the string until a given string is encountered, accumulating characters into a string that’s returned by reference.

    Declaration

    Swift

    func scanUpToString(_ stopString: String, intoString stringValue: AutoreleasingUnsafeMutablePointer<NSString?>) -> Bool

    Objective-C

    - (BOOL)scanUpToString:(NSString *)stopString intoString:(NSString **)stringValue

    Parameters

    stopString

    The string to scan up to.

    stringValue

    Upon return, contains any characters that were scanned.

    Return Value

    YEStrue if the receiver scans any characters, otherwise NOfalse.

    If the only scanned characters are in the charactersToBeSkipped character set (which by default is the whitespace and newline character set), then this method returns NOfalse.

    Discussion

    If stopString is present in the receiver, then on return the scan location is set to the beginning of that string.

    If stopString is the first string in the receiver, then the method returns NOfalse and stringValue is not changed.

    If the search string (stopString) isn't present in the scanner's source string, the remainder of the source string is put into stringValue, the receiver’s scanLocation is advanced to the end of the source string, and the method returns YEStrue.

    Invoke this method with NULL as stringValue to simply scan up to a given string.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • atEnd atEnd Property

    Flag that indicates whether the receiver has exhausted all significant characters. (read-only)

    Declaration

    Swift

    var atEnd: Bool { get }

    Objective-C

    @property(getter=isAtEnd, readonly) BOOL atEnd

    Discussion

    YEStrue if the receiver has exhausted all significant characters in its string, otherwise NOfalse.

    If only characters from the set to be skipped remain, returns YEStrue.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.10 and later.