NSValue class reference

Authors

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

Version: 37003

Date: 2013-08-22 09:44:54 -0600 (Thu, 22 Aug 2013)

Contents -

Software documentation for the NSNumber class
Software documentation for the NSValue class
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

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: MacOS-X 10.5.0

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: MacOS-X 10.5.0

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: MacOS-X 10.5.0

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: MacOS-X 10.5.0

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: MacOS-X 10.5.0

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: MacOS-X 10.5.0

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

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.