NSValue

Inherits From: NSObject

Conforms To: NSCoding, NSCopying NSObject (NSObject)

Declared In: Foundation/NSValue.h

Foundation/NSGeometry.h

Class Description

NSValue objects provide an object-oriented wrapper for the data types defined in standard C and Objective C. The NSValue class is often used to put Objective C and standard C data types into collections that require objects, such as NSArray objects. When a value object is instantiated, it is encoded with the specified data type.

The NSValue class declares the programmatic interface to an object that contains a C data type. It provides methods for creating value objects that contain values of a specified data type, pointers, and other objects.

Use NSValue objects to put C types into collections. Use NSNumber objects to put numbers into collections.

The following code puts an NSRange into an NSArray, using the Objective C @encode directive to get a character string that encodes the type structure of NSRange:

[myArray insertObject:[NSValue value:&range withObjCType:@encode(NSRange)] atIndex:n]

To get the value back, you would do this:

[[myArray objectAtIndex:n] getValue:&range]

NSValue objects are provided with generic coding and copying behavior. To subclass NSValue and preserve class when encoding or copying, override classForCoder, initWithCoder:, encodeWithCoder: (for encoding), and copyWithZone: (for copying).

General Exception Conditions

NSValue can raise NSInternalInconsistencyException in a variety of cases where an unkown Objective C type is found. In addition, NSValue's implementation of encodeWithCoder: can raise NSInvalidArgumentException if an attempt is made to encode void.

Allocating and Initializing Value Objects

• + (NSValue *)value:(const void *)value Creates and returns a value object containing the value withObjCType:(const char *)type value of the Objective C type type.
• + (NSValue *)valueWithNonretainedObject: (id)anObject Creates and returns a value object containing the object anObject, without retaining anObject. This is provided as a convenience method: the statement [NSValue valueWithNonretainedOject:anObject] is equivalent to the statement [NSValue value:&anObject withObjCType:@encode(void *)].
• + (NSValue *)valueWithPointer:(const void *)pointer Creates and returns a value object that contains the specified pointer. This is provided as a convenience method: the statement [NSValue valueWithPointer:pointer] is equivalent to the statement [NSValue value:&pointer withObjCType:@encode(void *)].

• + (NSValue *)valueWithPoint:(NSPoint)point Creates and returns a value object that contains the specified NSPoint structure (which represents a geometrical point in two dimensions).
• + (NSValue *)valueWithRect:(NSRect)rect Creates and returns a value object that contains the specified NSRect structure, representing a rectangle.
• + (NSValue *)valueWithSize:(NSSize)size Creates and returns a value object that contains the specified NSSize structure (which stores a width and a height).

• - (void)getValue:(void *)value Copies the receiver's data into value.
• - (id)nonretainedObjectValue Returns the non-retained object that's contained in the receiver. It's an error to send this message to an NSValue object that doesn't store a nonretained object.
• - (const char *)objCType Returns the Objective C type of the data contained in the receiver.
• - (void *)pointerValue Returns the value pointed to by a pointer contained in an value object. It's an error to send this message to an NSValue that doesn't store a pointer.

• - (NSPoint)pointValue Returns the point structure that's contained in the receiver.
• - (NSRect)rectValue Returns the rectangle structure that's contained in the receiver.
• - (NSSize)sizeValue Returns the size structure that's contained in the receiver.