Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 *)].

Allocating and Initializing Geometry Value Objects

+ (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).

Accessing Data in Value Objects

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

Accessing Data in Value Geometry Objects

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