PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSNumber


Inherits from:
NSValue : NSObject
Conforms to:
NSCoding
(NSValue)
NSCopying (NSValue)
NSObject (NSObject)
Declared in:
Foundation/NSValue.h
Foundation/NSDecimalNumber.h




Class Description


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. It also defines a compare: method to determine the ordering of two NSNumber objects.

An NSNumber records the numeric type it's created with, and uses the C rules for numeric conversion when comparing NSNumbers of different numeric types and when returning values as C numeric types. See any standard C reference for information on type conversion.


Creating a Subclass of NSNumber

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




Method Types


Creating an NSNumber
+ numberWithBool:
+ numberWithChar:
+ numberWithDouble:
+ numberWithFloat:
+ numberWithInt:
+ numberWithLong:
+ numberWithLongLong:
+ numberWithShort:
+ numberWithUnsignedChar:
+ numberWithUnsignedInt:
+ numberWithUnsignedLong:
+ numberWithUnsignedLongLong:
+ numberWithUnsignedShort:
- initWithBool:
- initWithChar:
- initWithDouble:
- initWithFloat:
- initWithInt:
- initWithLong:
- initWithLongLong:
- initWithShort:
- initWithUnsignedChar:
- initWithUnsignedInt:
- initWithUnsignedLong:
- initWithUnsignedLongLong:
- initWithUnsignedShort:
Accessing numeric values
- boolValue
- charValue
- decimalValue
- descriptionWithLocale:
- doubleValue
- floatValue
- intValue
- longLongValue
- longValue
- shortValue
- stringValue
- unsignedCharValue
- unsignedIntValue
- unsignedLongLongValue
- unsignedLongValue
- unsignedShortValue
Comparing NSNumbers
- compare:
- isEqualToNumber:


Class Methods



numberWithBool:

+ (NSNumber *)numberWithBool:(BOOL)value

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

numberWithChar:

+ (NSNumber *)numberWithChar:(char)value

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

numberWithDouble:

+ (NSNumber *)numberWithDouble:(double)value

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

numberWithFloat:

+ (NSNumber *)numberWithFloat:(float)value

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

numberWithInt:

+ (NSNumber *)numberWithInt:(int)value

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

numberWithLong:

+ (NSNumber *)numberWithLong:(long)value

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

numberWithLongLong:

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

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

numberWithShort:

+ (NSNumber *)numberWithShort:(short)value

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

numberWithUnsignedChar:

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

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

numberWithUnsignedInt:

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

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

numberWithUnsignedLong:

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

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

numberWithUnsignedLongLong:

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

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

numberWithUnsignedShort:

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

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


Instance Methods



boolValue

- (BOOL)boolValue

Returns the receiver's value as a BOOL, converting it as necessary.
Note: The value returned by this method isn't guaranteed to be one of YES or NO. A zero value always means NO or false, but any nonzero value should be interpreted as YES or true.



charValue

- (char)charValue

Returns the receiver's value as a char, converting it as necessary.

compare:

- (NSComparisonResult)compare:(NSNumber *)aNumber

Returns NSOrderedAscending if aNumber's value is greater than the receiver's, NSOrderedSame if they're equal, and NSOrderedDescending if aNumber's value is less than the receiver's.

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



decimalValue

- (NSDecimal)decimalValue

Returns the receiver's value, expressed as an NSDecimal struct. The value returned isn't guaranteed to be exact for float and double values.

descriptionWithLocale:

- (NSString *)descriptionWithLocale:(NSDictionary *)aLocale

Returns an NSString that represents the contents of the receiver. For example, if you have an NSNumber that has the integer value 522, sending it the descriptionWithLocale: message returns the string "522". aLocale specifies options used for formatting the description; use nil if you don't want the description formatted.

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


Data Type Format Specification
char %i
double %0.16g
float %0.7g
int %i
long %li
long long %li
short %hi
unsigned char %u
unsigned int %u
unsigned long %lu
unsigned long long %lu
unsigned short %hu

See Also: - stringValue



doubleValue

- (double)doubleValue

Returns the receiver's value as a double, converting it as necessary.

floatValue

- (float)floatValue

Returns the receiver's value as a float, converting it as necessary.

initWithBool:

- (id)initWithBool:(BOOL)value

Initializes a newly allocated NSNumber to contain value, treated as a BOOL.

initWithChar:

- (id)initWithChar:(char)value

Initializes a newly allocated NSNumber to contain value, treated as a signed char.

initWithDouble:

- (id)initWithDouble:(double)value

Initializes a newly allocated NSNumber to contain value, treated as a double.

initWithFloat:

- (id)initWithFloat:(float)value

Initializes a newly allocated NSNumber to contain value, treated as a float.

initWithInt:

- (id)initWithInt:(int)value

Initializes a newly allocated NSNumber to contain value, treated as a signed int.

initWithLong:

- (id)initWithLong:(long)value

Initializes a newly allocated NSNumber to contain value, treated as a signed long.

initWithLongLong:

- (id)initWithLongLong:(long long)value

Initializes a newly allocated NSNumber to contain value, treated as a signed long long.

initWithShort:

- (id)initWithShort:(short)value

Initializes a newly allocated NSNumber to contain value, treated as a signed short.

initWithUnsignedChar:

- (id)initWithUnsignedChar:(unsigned char)value

Initializes a newly allocated NSNumber to contain value, treated as an unsigned char.

initWithUnsignedInt:

- (id)initWithUnsignedInt:(unsigned int)value

Initializes a newly allocated NSNumber to contain value, treated as an unsigned int.

initWithUnsignedLong:

- (id)initWithUnsignedLong:(unsigned long)value

Initializes a newly allocated NSNumber to contain value, treated as an unsigned long.

initWithUnsignedLongLong:

- (id)initWithUnsignedLongLong:(unsigned long long)value

Initializes a newly allocated NSNumber to contain value, treated as an unsigned long long.

initWithUnsignedShort:

- (id)initWithUnsignedShort:(unsigned short)value

Initializes a newly allocated NSNumber to contain value, treated as an unsigned short.

intValue

- (int)intValue

Returns the receiver's value as an int, converting it as necessary.

isEqualToNumber:

- (BOOL)isEqualToNumber:(NSNumber *)aNumber

Returns YES if the receiver and aNumber are equal, otherwise returns NO. Two NSNumbers are considered equal if they have the same ids or if they have equivalent values (as determined by the compare: method).

longValue

- (long)longValue

Returns the receiver's value as a long, converting it as necessary.

longLongValue

- (long long)longLongValue

Returns the receiver's value as a long long, converting it as necessary.

shortValue

- (short)shortValue

Returns the receiver's value as a short, converting it as necessary.

stringValue

- (NSString *)stringValue

Returns the receiver's value as a human-readable NSString, by invoking descriptionWithLocale: where locale is nil.

unsignedCharValue

- (unsigned char)unsignedCharValue

Returns the receiver's value as an unsigned char, converting it as necessary.

unsignedIntValue

- (unsigned int)unsignedIntValue

Returns the receiver's value as an unsigned int, converting it as necessary.

unsignedLongValue

- (unsigned long)unsignedLongValue

Returns the receiver's value as an unsigned long, converting it as necessary.

unsignedLongLongValue

- (unsigned long long)unsignedLongLongValue

Returns the receiver's value as an unsigned long long, converting it as necessary.

unsignedShortValue

- (unsigned short)unsignedShortValue

Returns the receiver's value as an unsigned short, converting it as necessary.


Table of Contents