iOS Developer Library — Prerelease

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.

Value Conversions

NSNumber provides readonly properties that return the object’s stored value converted to a particular Boolean, integer, unsigned integer, or floating point C scalar type. Because numeric types have different storage capabilities, attempting to initialize with a value of one type and access the value of another type may produce an erroneous result—for example, initializing with a double value exceeding FLT_MAX and accessing its floatValue, or initializing with an negative integer value and acessing its unsignedIntegerValue. In some cases, attempting to initialize with a value of a type and access the value of another type may result in loss of precision—for example, initializing with a double value with many significant digits and accessing its floatValue, or initializing with a large integer value and accessing its charValue.

An NSNumber object initialized with a value of a particular type accessing the converted value of a different kind of type, such as unsigned int and float, will convert its stored value to that converted type in the following ways:

Table 1NSNumber from Boolean Value Conversions

NSNumber +numberWithBool:

boolValue

integerValue

unsignedIntegerValue

floatValue

NOfalse

NOfalse

0

0

0.0

YEStrue

YEStrue

1

1

1.0

Table 2NSNumber from Integer Value Conversions

NSNumber +numberWithInteger:

boolValue

integerValue

unsignedIntegerValue

floatValue

0

NOfalse

0

0

0.0

1

YEStrue

1

1

1.0

-1

YEStrue

-1

invalid, erroneous result

-1.0

Table 3NSNumber from Unsigned Integer Value Conversions

NSNumber +numberWithUnsignedInteger:

boolValue

integerValue

unsignedIntegerValue

floatValue

0

NOfalse

0

0

0.0

1

YEStrue

1

1

1.0

Table 4NSNumber from Floating Point Value Conversions

NSNumber +numberWithFloat:

boolValue

integerValue

unsignedIntegerValue

floatValue

0.0

NOfalse

0

0

0.0

1.0

YEStrue

1

1

1.0

-1.0

YEStrue

-1

invalid, erroneous result

-1.0

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.

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

    Declaration

    Objective-C

    + (NSNumber * _Nonnull)numberWithBool:(BOOL)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithChar:(char)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithDouble:(double)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithFloat:(float)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithInt:(int)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithInteger:(NSInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)numberWithLong:(long)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)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.

    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 * _Nonnull)numberWithShort:(short)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    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 * _Nonnull)numberWithUnsignedInteger:(NSUInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    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 * _Nonnull)initWithBool:(BOOL)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)initWithChar:(char)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(double value: Double)

    Objective-C

    - (NSNumber * _Nonnull)initWithDouble:(double)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)initWithFloat:(float)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)initWithInt:(int)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(integer value: Int)

    Objective-C

    - (NSNumber * _Nonnull)initWithInteger:(NSInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)initWithLong:(long)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(longLong value: Int64)

    Objective-C

    - (NSNumber * _Nonnull)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.

    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 * _Nonnull)initWithShort:(short)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    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 * _Nonnull)initWithUnsignedInteger:(NSUInteger)value

    Parameters

    value

    The value for the new number.

    Return Value

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

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    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 * _Nonnull)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.

    Availability

    Available in iOS 2.0 and later.

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var charValue: Int8 { get }

    Objective-C

    @property(readonly) char charValue

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var decimalValue: NSDecimal { get }

    Objective-C

    @property(readonly) NSDecimal decimalValue

    Discussion

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

    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

    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

    Availability

    Available in iOS 2.0 and later.

  • 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

    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

    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

    Availability

    Available in iOS 2.0 and later.

  • 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

    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

    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

    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

    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

    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

    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

    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

    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(_ locale: AnyObject?) -> String

    Objective-C

    - (NSString * _Nonnull)descriptionWithLocale:(id _Nullable)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

    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, nonnull) NSString *stringValue

    Discussion

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

    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(_ otherNumber: NSNumber) -> NSComparisonResult

    Objective-C

    - (NSComparisonResult)compare:(NSNumber * _Nonnull)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.

    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(_ number: NSNumber) -> Bool

    Objective-C

    - (BOOL)isEqualToNumber:(NSNumber * _Nonnull)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.

    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.