NSNumber Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | NSDecimalNumber.h NSValue.h |
| Companion guides | |
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 counterpart, CFNumberRef. See “Toll-Free Bridging” for more information on toll-free bridging.
Subclassing Notes
As with any class cluster, if you create a subclass of NSNumber, you have to override the primitive methods of its superclass, NSValue. Furthermore, there is a restricted set of return values that your implementation of the NSValue method objCType can return, in order to take advantage of the abstract implementations of the non-primitive methods. The valid return values are “c”, “C”, “s”, “S”, “i”, “I”, “l”, “L”, “q”, “Q”, “f”, and “d”.
Tasks
Creating an NSNumber Object
-
+ numberWithBool: -
+ numberWithChar: -
+ numberWithDouble: -
+ numberWithFloat: -
+ numberWithInt: -
+ numberWithInteger: -
+ numberWithLong: -
+ numberWithLongLong: -
+ numberWithShort: -
+ numberWithUnsignedChar: -
+ numberWithUnsignedInt: -
+ numberWithUnsignedInteger: -
+ numberWithUnsignedLong: -
+ numberWithUnsignedLongLong: -
+ numberWithUnsignedShort:
Initializing an NSNumber Object
-
– initWithBool: -
– initWithChar: -
– initWithDouble: -
– initWithFloat: -
– initWithInt: -
– initWithInteger: -
– initWithLong: -
– initWithLongLong: -
– initWithShort: -
– initWithUnsignedChar: -
– initWithUnsignedInt: -
– initWithUnsignedInteger: -
– initWithUnsignedLong: -
– initWithUnsignedLongLong: -
– initWithUnsignedShort:
Accessing Numeric Values
-
– boolValue -
– charValue -
– decimalValue -
– doubleValue -
– floatValue -
– intValue -
– integerValue -
– longLongValue -
– longValue -
– shortValue -
– unsignedCharValue -
– unsignedIntegerValue -
– unsignedIntValue -
– unsignedLongLongValue -
– unsignedLongValue -
– unsignedShortValue
Retrieving String Representations
Comparing NSNumber Objects
Accessing Type Information
Class Methods
numberWithBool:
Creates and returns an NSNumber object containing a given value, treating it as a BOOL.
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.
Declared In
NSValue.hnumberWithChar:
Creates and returns an NSNumber object containing a given value, treating it as a signed char.
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.
Declared In
NSValue.hnumberWithDouble:
Creates and returns an NSNumber object containing a given value, treating it as a double.
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.
Declared In
NSValue.hnumberWithFloat:
Creates and returns an NSNumber object containing a given value, treating it as a float.
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.
Declared In
NSValue.hnumberWithInt:
Creates and returns an NSNumber object containing a given value, treating it as a signed int.
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.
Declared In
NSValue.hnumberWithInteger:
Creates and returns an NSNumber object containing a given value, treating it as an NSInteger.
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.
Declared In
NSValue.hnumberWithLong:
Creates and returns an NSNumber object containing a given value, treating it as a signed long.
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.
Declared In
NSValue.hnumberWithLongLong:
Creates and returns an NSNumber object containing a given value, treating it as a signed long long.
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.
Declared In
NSValue.hnumberWithShort:
Creates and returns an NSNumber object containing value, treating it as a signed short.
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.
Declared In
NSValue.hnumberWithUnsignedChar:
Creates and returns an NSNumber object containing a given value, treating it as an unsigned char.
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.
Declared In
NSValue.hnumberWithUnsignedInt:
Creates and returns an NSNumber object containing a given value, treating it as an unsigned int.
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.
Declared In
NSValue.hnumberWithUnsignedInteger:
Creates and returns an NSNumber object containing a given value, treating it as an NSUInteger.
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.
Declared In
NSValue.hnumberWithUnsignedLong:
Creates and returns an NSNumber object containing a given value, treating it as an unsigned long.
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.
Declared In
NSValue.hnumberWithUnsignedLongLong:
Creates and returns an NSNumber object containing a given value, treating it as an unsigned long long.
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.
Declared In
NSValue.hnumberWithUnsignedShort:
Creates and returns an NSNumber object containing a given value, treating it as an unsigned short.
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.
Declared In
NSValue.hInstance Methods
boolValue
Returns the receiver’s value as a BOOL.
Return Value
The receiver’s value as a BOOL, converting it as necessary.
Special Considerations
Prior to OS X v10.3, the value returned isn’t guaranteed to be one of YES or NO. A 0 value always means NO or false, but any nonzero value should be interpreted as YES or true.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hcharValue
Returns the receiver’s value as a char.
Return Value
The receiver’s value as a char, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hcompare:
Returns an NSComparisonResult value that indicates whether the receiver is greater than, equal to, or less than a given number.
Parameters
- aNumber
The number with which to compare the receiver.
This value must not be
nil. If the value isnil, 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 receiver’s, NSOrderedSame if they’re equal, and NSOrderedDescending if the value of aNumber is less than the receiver’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.
Declared In
NSValue.hdecimalValue
Returns the receiver’s value, expressed as an NSDecimal structure.
Return Value
The receiver’s value, expressed as an NSDecimal structure. The value returned isn’t guaranteed to be exact for float and double values.
Availability
- Available in iOS 2.0 and later.
Declared In
NSDecimalNumber.hdescriptionWithLocale:
Returns a string that represents the contents of the receiver for a given locale.
Parameters
- aLocale
An object containing locale information with which to format the description. Use
nilif you don’t want the description formatted.
Return Value
A string that represents the contents of the receiver 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
Declared In
NSValue.hdoubleValue
Returns the receiver’s value as a double.
Return Value
The receiver’s value as a double, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hfloatValue
Returns the receiver’s value as a float.
Return Value
The receiver’s value as a float, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hinitWithBool:
Returns an NSNumber object initialized to contain a given value, treated as a BOOL.
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.
Declared In
NSValue.hinitWithChar:
Returns an NSNumber object initialized to contain a given value, treated as a signed char.
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.
Declared In
NSValue.hinitWithDouble:
Returns an NSNumber object initialized to contain value, treated as a double.
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.
Declared In
NSValue.hinitWithFloat:
Returns an NSNumber object initialized to contain a given value, treated as a float.
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.
Declared In
NSValue.hinitWithInt:
Returns an NSNumber object initialized to contain a given value, treated as a signed int.
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.
Declared In
NSValue.hinitWithInteger:
Returns an NSNumber object initialized to contain a given value, treated as an NSInteger.
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.
Declared In
NSValue.hinitWithLong:
Returns an NSNumber object initialized to contain a given value, treated as a signed long.
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.
Declared In
NSValue.hinitWithLongLong:
Returns an NSNumber object initialized to contain value, treated as a signed long long.
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.
Declared In
NSValue.hinitWithShort:
Returns an NSNumber object initialized to contain a given value, treated as a signed short.
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.
Declared In
NSValue.hinitWithUnsignedChar:
Returns an NSNumber object initialized to contain a given value, treated as an unsigned char.
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.
Declared In
NSValue.hinitWithUnsignedInt:
Returns an NSNumber object initialized to contain a given value, treated as an unsigned int.
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.
Declared In
NSValue.hinitWithUnsignedInteger:
Returns an NSNumber object initialized to contain a given value, treated as an NSUInteger.
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.
Declared In
NSValue.hinitWithUnsignedLong:
Returns an NSNumber object initialized to contain a given value, treated as an unsigned long.
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.
Declared In
NSValue.hinitWithUnsignedLongLong:
Returns an NSNumber object initialized to contain a given value, treated as an unsigned long long.
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.
Declared In
NSValue.hinitWithUnsignedShort:
Returns an NSNumber object initialized to contain a given value, treated as an unsigned short.
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.
Declared In
NSValue.hintegerValue
Returns the receiver’s value as an NSInteger.
Return Value
The receiver’s value as an NSInteger, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hintValue
Returns the receiver’s value as an int.
Return Value
The receiver’s value as an int, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hisEqualToNumber:
Returns a Boolean value that indicates whether the receiver and a given number are equal.
Parameters
- aNumber
The number with which to compare the receiver.
Return Value
YES if the receiver and aNumber are equal, otherwise NO.
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.
Declared In
NSValue.hlongLongValue
Returns the receiver’s value as a long long.
Return Value
The receiver’s value as a long long, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hlongValue
Returns the receiver’s value as a long.
Return Value
The receiver’s value as a long, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hobjCType
Returns a C string containing the Objective-C type of the data contained in the receiver.
Return Value
A C string containing the Objective-C type of the data contained in the receiver, as encoded by the @encode() compiler directive.
Special Considerations
The returned type does not necessarily match the method the receiver was created with.
shortValue
Returns the receiver’s value as a short.
Return Value
The receiver’s value as a short, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hstringValue
Returns the receiver’s value as a human-readable string.
Return Value
The receiver’s value as a human-readable string, created by invoking descriptionWithLocale: where locale is nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hunsignedCharValue
Returns the receiver’s value as an unsigned char.
Return Value
The receiver’s value as an unsigned char, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hunsignedIntegerValue
Returns the receiver’s value as an NSUInteger.
Return Value
The receiver’s value as an NSUInteger, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hunsignedIntValue
Returns the receiver’s value as an unsigned int.
Return Value
The receiver’s value as an unsigned int, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.hunsignedLongLongValue
Returns the receiver’s value as an unsigned long long.
Return Value
The receiver’s value as an unsigned long long, converting it as necessary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSValue.h© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-02-08)