iOS Developer Library

Developer

Foundation Framework Reference NSNumber Class Reference

Options
Deployment Target:

On This Page
Language:

NSNumber

NSNumber is a subclass of NSValue that offers a value as any C scalar (numeric) type. It defines a set of methods specifically for setting and accessing the value as a signed or unsigned char, short int, int, long int, long long int, float, or double or as a BOOL. (Note that number objects do not necessarily preserve the type they are created with.) It also defines a compare: method to determine the ordering of two NSNumber objects.

NSNumber is “toll-free bridged” with its Core Foundation counterpart, CFNumberRef. See Toll-Free Bridging for more information on toll-free bridging.

Subclassing Notes

As with any class cluster, subclasses of NSNumber must override the primitive methods of its superclass, NSValue. In addition, there are two requirements around the data type your subclass represents:

  1. Your implementation of objCType must return one of “c”, “C”, “s”, “S”, “i”, “I”, “l”, “L”, “q”, “Q”, “f”, and “d”. This is required for the other methods of NSNumber to behave correctly.

  2. Your subclass must override the accessor method that corresponds to the declared type—for example, if your implementation of objCType returns “i”, you must override intValue.

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • Creates and returns an NSNumber object containing a given value, treating it as a BOOL.

    Declaration

    Objective-C

    + (NSNumber *)numberWithBool:(BOOL)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a BOOL.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a signed char.

    Declaration

    Objective-C

    + (NSNumber *)numberWithChar:(char)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed char.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a double.

    Declaration

    Objective-C

    + (NSNumber *)numberWithDouble:(double)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a double.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a float.

    Declaration

    Objective-C

    + (NSNumber *)numberWithFloat:(float)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a float.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a signed int.

    Declaration

    Objective-C

    + (NSNumber *)numberWithInt:(int)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed int.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an NSInteger.

    Declaration

    Objective-C

    + (NSNumber *)numberWithInteger:(NSInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an NSInteger.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a signed long.

    Declaration

    Objective-C

    + (NSNumber *)numberWithLong:(long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed long.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as a signed long long.

    Declaration

    Objective-C

    + (NSNumber *)numberWithLongLong:(long long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed long long.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing value, treating it as a signed short.

    Declaration

    Objective-C

    + (NSNumber *)numberWithShort:(short)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed short.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an unsigned char.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedChar:(unsigned char)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned char.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an unsigned int.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedInt:(unsigned int)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned int.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an NSUInteger.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedInteger:(NSUInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an NSUInteger.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an unsigned long.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedLong:(unsigned long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned long.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an unsigned long long.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedLongLong:(unsigned long long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned long long.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSNumber object containing a given value, treating it as an unsigned short.

    Declaration

    Objective-C

    + (NSNumber *)numberWithUnsignedShort:(unsigned short)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned short.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • init(bool:) - initWithBool: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a BOOL.

    Declaration

    Swift

    init(bool value: Bool)

    Objective-C

    - (NSNumber *)initWithBool:(BOOL)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a BOOL.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(char:) - initWithChar: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a signed char.

    Declaration

    Swift

    init(char value: Int8)

    Objective-C

    - (NSNumber *)initWithChar:(char)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed char.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(double:) - initWithDouble: Designated Initializer

    Returns an NSNumber object initialized to contain value, treated as a double.

    Declaration

    Swift

    init(double value: Double)

    Objective-C

    - (NSNumber *)initWithDouble:(double)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a double.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(float:) - initWithFloat: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a float.

    Declaration

    Swift

    init(float value: Float)

    Objective-C

    - (NSNumber *)initWithFloat:(float)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a float.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(int:) - initWithInt: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a signed int.

    Declaration

    Swift

    init(int value: Int32)

    Objective-C

    - (NSNumber *)initWithInt:(int)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed int.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(integer:) - initWithInteger: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as an NSInteger.

    Declaration

    Swift

    init(integer value: Int)

    Objective-C

    - (NSNumber *)initWithInteger:(NSInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an NSInteger.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(long:) - initWithLong: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a signed long.

    Declaration

    Swift

    init(long value: Int)

    Objective-C

    - (NSNumber *)initWithLong:(long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed long.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(longLong:) - initWithLongLong: Designated Initializer

    Returns an NSNumber object initialized to contain value, treated as a signed long long.

    Declaration

    Swift

    init(longLong value: Int64)

    Objective-C

    - (NSNumber *)initWithLongLong:(long long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed long long.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init(short:) - initWithShort: Designated Initializer

    Returns an NSNumber object initialized to contain a given value, treated as a signed short.

    Declaration

    Swift

    init(short value: Int16)

    Objective-C

    - (NSNumber *)initWithShort:(short)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as a signed short.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an unsigned char.

    Declaration

    Swift

    init(unsignedChar value: UInt8)

    Objective-C

    - (NSNumber *)initWithUnsignedChar:(unsigned char)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned char.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an unsigned int.

    Declaration

    Swift

    init(unsignedInt value: UInt32)

    Objective-C

    - (NSNumber *)initWithUnsignedInt:(unsigned int)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned int.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an NSUInteger.

    Declaration

    Swift

    init(unsignedInteger value: Int)

    Objective-C

    - (NSNumber *)initWithUnsignedInteger:(NSUInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an NSUInteger.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an unsigned long.

    Declaration

    Swift

    init(unsignedLong value: UInt)

    Objective-C

    - (NSNumber *)initWithUnsignedLong:(unsigned long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned long.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an unsigned long long.

    Declaration

    Swift

    init(unsignedLongLong value: UInt64)

    Objective-C

    - (NSNumber *)initWithUnsignedLongLong:(unsigned long long)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned long long.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object initialized to contain a given value, treated as an unsigned short.

    Declaration

    Swift

    init(unsignedShort value: UInt16)

    Objective-C

    - (NSNumber *)initWithUnsignedShort:(unsigned short)value

    Parameters

    value

    The value for the new number.

    Return Value

    An NSNumber object containing value, treating it as an unsigned short.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • boolValue boolValue Property

    The number object's value expressed as a Boolean value. (read-only)

    Declaration

    Swift

    var boolValue: Bool { get }

    Objective-C

    @property(readonly) BOOL boolValue

    Discussion

    A 0 value always means NOfalse, and any nonzero value is interpreted as YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • charValue charValue Property

    The number object's value expressed as a char. (read-only)

    Declaration

    Swift

    var charValue: Int8 { get }

    Objective-C

    @property(readonly) char charValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an NSDecimal structure. (read-only)

    Declaration

    Objective-C

    @property(readonly) NSDecimal decimalValue

    Discussion

    The NSDecimal value isn’t guaranteed to be exact for float and double values.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as a double, converted as necessary. (read-only)

    Declaration

    Swift

    var doubleValue: Double { get }

    Objective-C

    @property(readonly) double doubleValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as a float, converted as necessary. (read-only)

    Declaration

    Swift

    var floatValue: Float { get }

    Objective-C

    @property(readonly) float floatValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • intValue intValue Property

    The number object's value expressed as an int, converted as necessary. (read-only)

    Declaration

    Swift

    var intValue: Int32 { get }

    Objective-C

    @property(readonly) int intValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an NSInteger object, converted as necessary. (read-only)

    Declaration

    Swift

    var integerValue: Int { get }

    Objective-C

    @property(readonly) NSInteger integerValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as a long long, converted as necessary. (read-only)

    Declaration

    Swift

    var longLongValue: Int64 { get }

    Objective-C

    @property(readonly) long long longLongValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • longValue longValue Property

    The number object's value expressed as a long, converted as necessary. (read-only)

    Declaration

    Swift

    var longValue: Int { get }

    Objective-C

    @property(readonly) long longValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as a short, converted as necessary. (read-only)

    Declaration

    Swift

    var shortValue: Int16 { get }

    Objective-C

    @property(readonly) short shortValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an unsigned char, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedCharValue: UInt8 { get }

    Objective-C

    @property(readonly) unsigned char unsignedCharValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an NSUInteger object, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedIntegerValue: Int { get }

    Objective-C

    @property(readonly) NSUInteger unsignedIntegerValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an unsigned int, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedIntValue: UInt32 { get }

    Objective-C

    @property(readonly) unsigned int unsignedIntValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an unsigned long long, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedLongLongValue: UInt64 { get }

    Objective-C

    @property(readonly) unsigned long long unsignedLongLongValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an unsigned long, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedLongValue: UInt { get }

    Objective-C

    @property(readonly) unsigned long unsignedLongValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number object's value expressed as an unsigned short, converted as necessary. (read-only)

    Declaration

    Swift

    var unsignedShortValue: UInt16 { get }

    Objective-C

    @property(readonly) unsigned short unsignedShortValue

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string that represents the contents of the number object for a given locale.

    Declaration

    Swift

    func descriptionWithLocale(_ aLocale: AnyObject?) -> String

    Objective-C

    - (NSString *)descriptionWithLocale:(id)aLocale

    Parameters

    aLocale

    An object containing locale information with which to format the description. Use nil if you don’t want the description formatted.

    Return Value

    A string that represents the contents of the number object formatted using the locale information in locale.

    Discussion

    For example, if you have an NSNumber object that has the integer value 522, sending it the descriptionWithLocale: message returns the string “522”.

    To obtain the string representation, this method invokes NSString’s initWithFormat:locale: method, supplying the format based on the type the NSNumber object was created with:

    Data Type

    Format Specification

    char

    %i

    double

    %0.16g

    float

    %0.7g

    int

    %i

    long

    %li

    long long

    %lli

    short

    %hi

    unsigned char

    %u

    unsigned int

    %u

    unsigned long

    %lu

    unsigned long long

    %llu

    unsigned short

    %hu

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    stringValue

  • The number object's value expressed as a human-readable string. (read-only)

    Declaration

    Swift

    var stringValue: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringValue

    Discussion

    The string is created by invoking descriptionWithLocale: where locale is nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSComparisonResult value that indicates whether the number object’s value is greater than, equal to, or less than a given number.

    Declaration

    Swift

    func compare(_ aNumber: NSNumber) -> NSComparisonResult

    Objective-C

    - (NSComparisonResult)compare:(NSNumber *)aNumber

    Parameters

    aNumber

    The number to compare to the number object’s value.

    This value must not be nil. If the value is nil, the behavior is undefined and may change in future versions of OS X.

    Return Value

    NSOrderedAscending if the value of aNumber is greater than the number object’s, NSOrderedSame if they’re equal, and NSOrderedDescending if the value of aNumber is less than the number object’s.

    Discussion

    The compare: method follows the standard C rules for type conversion. For example, if you compare an NSNumber object that has an integer value with an NSNumber object that has a floating point value, the integer value is converted to a floating-point value for comparison.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a Boolean value that indicates whether the number object’s value and a given number are equal.

    Declaration

    Swift

    func isEqualToNumber(_ aNumber: NSNumber) -> Bool

    Objective-C

    - (BOOL)isEqualToNumber:(NSNumber *)aNumber

    Parameters

    aNumber

    The number to compare to the number object’s value.

    Return Value

    YEStrue if the number object’s value and aNumber are equal, otherwise NOfalse.

    Discussion

    Two NSNumber objects are considered equal if they have the same id values or if they have equivalent values (as determined by the compare: method).

    This method is more efficient than compare: if you know the two objects are numbers.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a C string containing the Objective-C type of the data contained in the number object.

    Declaration

    Objective-C

    - (const char *)objCType

    Return Value

    A C string containing the Objective-C type of the data contained in the number object, as encoded by the @encode() compiler directive.

    Special Considerations

    The returned type does not necessarily match the method the number object was created with.