Up

# NSValue class reference

### Authors

Adam Fedor (`fedor@boulder.colorado.edu`)
Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 33660

Date: 2011-07-31 09:31:39 -0600 (Sun, 31 Jul 2011)

Copyright: (C) 1993, 1994, 1996, 1999 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSNumber class
2. Software documentation for the NSValue class
3. Software documentation for the NSValue(Subclassing) category

# Software documentation for the NSNumber class

## NSNumber : NSValue

> Declared in:
>   Foundation/NSValue.h

> Conforms to:
>   NSCopying
>   NSCoding

Availability: OpenStep
Subclass of NSValue offering convenience methods for initializing from and accessing as any C primitive numeric type. On access, the value will be type-converted if necessary, using standard C conversion rules.
Method summary

- -decimalValue
- +numberWithBool:
- +numberWithChar:
- +numberWithDouble:
- +numberWithFloat:
- +numberWithInt:
- +numberWithInteger:
- +numberWithLong:
- +numberWithLongLong:
- +numberWithShort:
- +numberWithUnsignedChar:
- +numberWithUnsignedInt:
- +numberWithUnsignedInteger:
- +numberWithUnsignedLong:
- +numberWithUnsignedLongLong:
- +numberWithUnsignedShort:
- -boolValue
- -charValue
- -compare:
- -description
- -descriptionWithLocale:
- -doubleValue
- -floatValue
- -initWithBool:
- -initWithChar:
- -initWithDouble:
- -initWithFloat:
- -initWithInt:
- -initWithInteger:
- -initWithLong:
- -initWithLongLong:
- -initWithShort:
- -initWithUnsignedChar:
- -initWithUnsignedInt:
- -initWithUnsignedInteger:
- -initWithUnsignedLong:
- -initWithUnsignedLongLong:
- -initWithUnsignedShort:
- -intValue
- -integerValue
- -isEqualToNumber:
- -longLongValue
- -longValue
- -shortValue
- -stringValue
- -unsignedCharValue
- -unsignedIntValue
- -unsignedIntegerValue
- -unsignedLongLongValue
- -unsignedLongValue
- -unsignedShortValue

### numberWithBool:

+ (NSNumber*) numberWithBool: (BOOL)value;
Availability: OpenStep
New instance from boolean value.

### numberWithChar:

+ (NSNumber*) numberWithChar: (signed char)value;
Availability: OpenStep
New instance from signed char value.

### numberWithDouble:

+ (NSNumber*) numberWithDouble: (double)value;
Availability: OpenStep
New instance from double value.

### numberWithFloat:

+ (NSNumber*) numberWithFloat: (float)value;
Availability: OpenStep
New instance from float value.

### numberWithInt:

+ (NSNumber*) numberWithInt: (signed int)value;
Availability: OpenStep
New instance from (signed) int value.

### numberWithInteger:

+ (NSNumber*) numberWithInteger: (NSInteger)value;
Availability: Not in OpenStep/MacOS-X
Return a number intialised with NSInteger.

### numberWithLong:

+ (NSNumber*) numberWithLong: (signed long)value;
Availability: OpenStep
New instance from (signed) long value.

### numberWithLongLong:

+ (NSNumber*) numberWithLongLong: (signed long long)value;
Availability: OpenStep
New instance from (signed) long long value.

### numberWithShort:

+ (NSNumber*) numberWithShort: (signed short)value;
Availability: OpenStep
New instance from (signed) short value.

### numberWithUnsignedChar:

+ (NSNumber*) numberWithUnsignedChar: (unsigned char)value;
Availability: OpenStep
New instance from unsigned char value.

### numberWithUnsignedInt:

+ (NSNumber*) numberWithUnsignedInt: (unsigned int)value;
Availability: OpenStep
New instance from unsigned int value.

### numberWithUnsignedInteger:

+ (NSNumber*) numberWithUnsignedInteger: (NSUInteger)value;
Availability: Not in OpenStep/MacOS-X
Return a number intialised with NSUInteger.

### numberWithUnsignedLong:

+ (NSNumber*) numberWithUnsignedLong: (unsigned long)value;
Availability: OpenStep
New instance from unsigned long value.

### numberWithUnsignedLongLong:

+ (NSNumber*) numberWithUnsignedLongLong: (unsigned long long)value;
Availability: OpenStep
New instance from unsigned long long value.

### numberWithUnsignedShort:

+ (NSNumber*) numberWithUnsignedShort: (unsigned short)value;
Availability: OpenStep
New instance from unsigned short value.

### boolValue

- (BOOL) boolValue;
Availability: OpenStep
Return value as a BOOL; this will in fact be a char value converted if necessary from type initialized with; if you wish to consider anything nonzero TRUE do not compare directly to `YES`, but use `'!= NO'`.

### charValue

- (signed char) charValue;
Availability: OpenStep
Returns value as a signed char, converting if necessary.

### compare:

- (NSComparisonResult) compare: (NSNumber*)otherNumber;
Availability: OpenStep
Compares receiver with otherNumber, using C type conversion if necessary, and returns `NSOrderedAscending`, `NSOrderedDescending`, or `NSOrderedSame` depending on whether it is less than, greater than, or equal to otherNumber.

### description

- (NSString*) description;
Availability: OpenStep
Returns the string representation of this number using a non-localised conversion (decimal point is '.' irrespective of the locale).

### descriptionWithLocale:

- (NSString*) descriptionWithLocale: (id)locale;
Availability: OpenStep

Produces a string representation of the number. For a boolean this will be either 'true' or 'false'. For other numbers the format is produced using the initWithFormat:locale:... method of NSString, and the format depends on the type of number as follows -

char
  %i
short
  %hi
int
  %i
long
  %li
long long
  %lli
unsigned char
  %u
unsigned short
  %hu
unsigned int
  %u
unsigned long
  %lu
unsigned long long
  %llu
float
  %0.7g
double
  %0.16g

### doubleValue

- (double) doubleValue;
Availability: OpenStep
Returns value as a double, converting if necessary.

### floatValue

- (float) floatValue;
Availability: OpenStep
Returns value as a float, converting if necessary.

### initWithBool:

- (id) initWithBool: (BOOL)value;
Availability: OpenStep
Initialize from boolean value.

### initWithChar:

- (id) initWithChar: (signed char)value;
Availability: OpenStep
Initialize from signed char value.

### initWithDouble:

- (id) initWithDouble: (double)value;
Availability: OpenStep
Initialize from double value.

### initWithFloat:

- (id) initWithFloat: (float)value;
Availability: OpenStep
Initialize from float value.

### initWithInt:

- (id) initWithInt: (signed int)value;
Availability: OpenStep
Initialize from (signed) int value.

### initWithInteger:

- (id) initWithInteger: (NSInteger)value;
Availability: Not in OpenStep/MacOS-X
Initialise the receiver with NSInteger content.

### initWithLong:

- (id) initWithLong: (signed long)value;
Availability: OpenStep
Initialize from (signed) long value.

### initWithLongLong:

- (id) initWithLongLong: (signed long long)value;
Availability: OpenStep
Initialize from (signed) long long value.

### initWithShort:

- (id) initWithShort: (signed short)value;
Availability: OpenStep
Initialize from (signed) short value.

### initWithUnsignedChar:

- (id) initWithUnsignedChar: (unsigned char)value;
Availability: OpenStep
Initialize from unsigned char value.

### initWithUnsignedInt:

- (id) initWithUnsignedInt: (unsigned int)value;
Availability: OpenStep
Initialize from unsigned int value.

### initWithUnsignedInteger:

- (id) initWithUnsignedInteger: (NSUInteger)value;
Availability: Not in OpenStep/MacOS-X
Initialise the receiver with NSUInteger content.

### initWithUnsignedLong:

- (id) initWithUnsignedLong: (unsigned long)value;
Availability: OpenStep
Initialize from unsigned long value.

### initWithUnsignedLongLong:

- (id) initWithUnsignedLongLong: (unsigned long long)value;
Availability: OpenStep
Initialize from unsigned long long value.

### initWithUnsignedShort:

- (id) initWithUnsignedShort: (unsigned short)value;
Availability: OpenStep
Initialize from unsigned short value.

### intValue

- (signed int) intValue;
Availability: OpenStep
Returns value as a (signed) int, converting if necessary.

### integerValue

- (NSInteger) integerValue;
Availability: Not in OpenStep/MacOS-X
Return the contents of the receiver as NSInteger.

### isEqualToNumber:

- (BOOL) isEqualToNumber: (NSNumber*)otherNumber;
Availability: OpenStep
Returns whether receiver and otherNumber represent the same numerical value.

### longLongValue

- (signed long long) longLongValue;
Availability: OpenStep
Returns value as a (signed) long long, converting if necessary.

### longValue

- (signed long) longValue;
Availability: OpenStep
Returns value as a (signed) long, converting if necessary.

### shortValue

- (signed short) shortValue;
Availability: OpenStep
Returns value as a (signed) short, converting if necessary.

### stringValue

- (NSString*) stringValue;
Availability: OpenStep
Returns -description .

### unsignedCharValue

- (unsigned char) unsignedCharValue;
Availability: OpenStep
Returns value as an unsigned char, converting if necessary.

### unsignedIntValue

- (unsigned int) unsignedIntValue;
Availability: OpenStep
Returns value as an unsigned int, converting if necessary.

### unsignedIntegerValue

- (NSUInteger) unsignedIntegerValue;
Availability: Not in OpenStep/MacOS-X
Return the contents of the receiver as NSUInteger.

### unsignedLongLongValue

- (unsigned long long) unsignedLongLongValue;
Availability: OpenStep
Returns value as an unsigned long long, converting if necessary.

### unsignedLongValue

- (unsigned long) unsignedLongValue;
Availability: OpenStep
Returns value as an unsigned long, converting if necessary.

### unsignedShortValue

- (unsigned short) unsignedShortValue;
Availability: OpenStep
Returns value as an unsigned short, converting if necessary.

# Software documentation for the NSValue class

## NSValue : NSObject

> Declared in:
>   Foundation/NSValue.h

> Conforms to:
>   NSCopying
>   NSCoding

Availability: OpenStep
The `NSValue` class can wrap a single primitive value as an object so it can be used in the containers and other places where an object reference is needed. Once initialized, an `NSValue` is immutable, and there is no `NSMutableValue` class. You initialize it by giving it a pointer to the primitive value, and you should be careful this does not get freed until after the `NSValue` is no longer used.
Method summary

- +valueClassWithObjCType:
- +value:withObjCType:
- +valueWithBytes:objCType:
- +valueWithNonretainedObject:
- +valueWithPoint:
- +valueWithPointer:
- +valueWithRange:
- +valueWithRect:
- +valueWithSize:
- -getValue:
- -initWithBytes:objCType:
- -isEqualToValue:
- -nonretainedObjectValue
- -objCType
- -pointValue
- -pointerValue
- -rangeValue
- -rectValue
- -sizeValue

### value: withObjCType:

+ (NSValue*) value: (const void*)value withObjCType: (const char*)type;
Availability: OpenStep
Create new instance with specified value (a pointer) of given type, which is a string code obtainable through the compile-time operator `@encode(...)`. For example:

        NSValue *theValue = [NSValue value: &n withObjCType: @encode(int)];

### valueWithBytes: objCType:

+ (NSValue*) valueWithBytes: (const void*)value objCType: (const char*)type;
Availability: MacOS-X 10.0.0
Synonym for value:withObjCType:.

### valueWithNonretainedObject:

+ (NSValue*) valueWithNonretainedObject: (id)anObject;
Availability: OpenStep
Create new instance holding anObject. This is useful if you want to add anObject to a collection such as NSArray but don't want it to be retained (a weak reference).

### valueWithPoint:

+ (NSValue*) valueWithPoint: (NSPoint)point;
Availability: OpenStep
Convenience method to create instance holding an `NSPoint` structure.

### valueWithPointer:

+ (NSValue*) valueWithPointer: (const void*)pointer;
Availability: OpenStep
Convenience method to create instance holding a pointer. Same as using `@encode(void *)` in +value:withObjCType: .

### valueWithRange:

+ (NSValue*) valueWithRange: (NSRange)range;
Availability: OpenStep
Convenience method to create instance holding an `NSRange` structure.

### valueWithRect:

+ (NSValue*) valueWithRect: (NSRect)rect;
Availability: OpenStep
Convenience method to create instance holding an `NSRect` structure.

### valueWithSize:

+ (NSValue*) valueWithSize: (NSSize)size;
Availability: OpenStep
Convenience method to create instance holding an `NSSize` structure.

### getValue:

- (void) getValue: (void*)value;
Availability: OpenStep
Copies bytes from the pointer receiver was initialized with into buffer pointed to by value. Number of bytes copied is determined by the type. If type was a void * pointer or object id, the memory address itself is copied.

### initWithBytes: objCType:

- (id) initWithBytes: (const void*)data objCType: (const char*)type;
Availability: MacOS-X 10.0.0
This is a designated initialiser for the class.
Initialize with value of type, parallel to value:withObjCType:.

### isEqualToValue:

- (BOOL) isEqualToValue: (NSValue*)other;
Availability: MacOS-X 10.0.0
Compares this instance to another `NSValue`. For equality, both contents and declared type of the two values must match.

### nonretainedObjectValue

- (id) nonretainedObjectValue;
Availability: OpenStep
If receiver was initialized with an object ID, return it, else raises `NSInternalInconsistencyException`.

### objCType

- (const char*) objCType;
Availability: OpenStep
Returns the string `@encode(...)` compatible type the receiver was initialized with.

### pointValue

- (NSPoint) pointValue;
Availability: OpenStep
If receiver was initialized with an `NSPoint` value, return it, else raises `NSInternalInconsistencyException`.

### pointerValue

- (void*) pointerValue;
Availability: OpenStep
If receiver was initialized with a void * pointer, return it, else raises `NSInternalInconsistencyException`.

### rangeValue

- (NSRange) rangeValue;
Availability: OpenStep
If receiver was initialized with an `NSRange` value, return it, else raises `NSInternalInconsistencyException`.

### rectValue

- (NSRect) rectValue;
Availability: OpenStep
If receiver was initialized with an `NSRect` value, return it, else raises `NSInternalInconsistencyException`.

### sizeValue

- (NSSize) sizeValue;
Availability: OpenStep
If receiver was initialized with an `NSSize` value, return it, else raises `NSInternalInconsistencyException`.

# Software documentation for the NSValue(Subclassing) category

## NSValue(Subclassing)

> Declared in:
>   Foundation/NSValue.h

Availability: Not in OpenStep/MacOS-X
Note: Defines a method that is not in the OpenStep spec, but makes subclassing easier.
Method summary

- +valueClassWithObjCType:

### valueClassWithObjCType:

+ (Class) valueClassWithObjCType: (const char*)type;
Availability: Not in OpenStep/MacOS-X
Used by value: withObjCType: to determine the concrete subclass to alloc.

Up