Class

NSNumber

An object wrapper for primitive scalar numeric values.

Declaration

@interface NSNumber : NSValue

Overview

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 counterparts: CFNumberRef for integer and floating point values, and CFBooleanRef for Boolean values. 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 accessing 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 1

NSNumber from Boolean Value Conversions

Table 2

NSNumber from Integer Value Conversions

Value

boolValue

integerValue

unsignedIntegerValue

floatValue

0

NO

0

0

0.0

1

YES

1

1

1.0

-1

YES

-1

invalid, erroneous result

-1.0

Table 3

NSNumber from Unsigned Integer Value Conversions

Table 4

NSNumber from Floating Point Value Conversions

Value

boolValue

integerValue

unsignedIntegerValue

floatValue

0.0

NO

0

0

0.0

1.0

YES

1

1

1.0

-1.0

YES

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

Topics

Creating an NSNumber Object

+ numberWithBool:

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

+ numberWithChar:

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

+ numberWithDouble:

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

+ numberWithFloat:

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

+ numberWithInt:

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

+ numberWithInteger:

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

+ numberWithLong:

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

+ numberWithLongLong:

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

+ numberWithShort:

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

+ numberWithUnsignedChar:

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

+ numberWithUnsignedInt:

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

+ numberWithUnsignedInteger:

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

+ numberWithUnsignedLong:

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

+ numberWithUnsignedLongLong:

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

+ numberWithUnsignedShort:

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

Initializing an NSNumber Object

- initWithBool:

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

- initWithChar:

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

- initWithDouble:

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

- initWithFloat:

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

- initWithInt:

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

- initWithInteger:

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

- initWithLong:

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

- initWithLongLong:

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

- initWithShort:

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

- initWithUnsignedChar:

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

- initWithUnsignedInt:

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

- initWithUnsignedInteger:

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

- initWithUnsignedLong:

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

- initWithUnsignedLongLong:

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

- initWithUnsignedShort:

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

Accessing Numeric Values

boolValue

The number object's value expressed as a Boolean value.

charValue

The number object's value expressed as a char.

decimalValue

The number object's value expressed as an NSDecimal structure.

doubleValue

The number object's value expressed as a double, converted as necessary.

floatValue

The number object's value expressed as a float, converted as necessary.

intValue

The number object's value expressed as an int, converted as necessary.

integerValue

The number object's value expressed as an NSInteger object, converted as necessary.

longLongValue

The number object’s value expressed as a long long, converted as necessary.

longValue

The number object's value expressed as a long, converted as necessary.

shortValue

The number object's value expressed as a short, converted as necessary.

unsignedCharValue

The number object's value expressed as an unsigned char, converted as necessary.

unsignedIntegerValue

The number object's value expressed as an NSUInteger object, converted as necessary.

unsignedIntValue

The number object's value expressed as an unsigned int, converted as necessary.

unsignedLongLongValue

The number object’s value expressed as an unsigned long long, converted as necessary.

unsignedLongValue

The number object's value expressed as an unsigned long, converted as necessary.

unsignedShortValue

The number object's value expressed as an unsigned short, converted as necessary.

Retrieving String Representations

- descriptionWithLocale:

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

stringValue

The number object's value expressed as a human-readable string.

Comparing NSNumber Objects

- compare:

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

- isEqualToNumber:

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

Accessing Type Information

- objCType

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

Number Validation

NSDecimalIsNotANumber

Returns a Boolean that indicates whether a given decimal contains a valid number.

Initializers

Relationships

Inherits From

See Also

Numbers

NSInteger

Describes an integer.

NSUInteger

Describes an unsigned integer.

NSDecimal

A structure representing a base-10 number.

NSDecimalNumber

An object for representing and performing arithmetic on base-10 numbers.

NSNumberFormatter

A formatter that converts between numeric values and their textual representations.