NSValue

Inherits From:
NSObject

Conforms To:
NSCoding
NSCopying
NSObject (NSObject)

Declared In:
Foundation/NSValue.h
Foundation/NSGeometry.h

Class At A Glance

Purpose

An NSValue object serves as an object wrapper for a standard C or Objective-C data item, allowing it to be stored in a collection object such as an NSArray or NSDictionary.

Creation

+ value:withObjCType:	Returns an NSValue containing any C or Objective-C data item.
+ valueWithBytes:objCType:	Returns an NSValue containing any Objective-C data item, which is interpreted as being of the specified Objective-C type.
+ valueWithNonretainedObject:	Returns an NSValue containing an Objective-C object, without retaining the Objective-C object.
+ valueWithPointer:	Returns an NSValue that contains a pointer.

Commonly Used Methods

- objCType	Returns the Objective-C type for the data contained in an NSValue.
- getValue:	Copies an NSValue's contents into a buffer.
- nonretainedObjectValue	Returns an NSValue's contents as an id.
- pointerValue	Returns an NSValue's contents as a pointer to void.

Primitive Methods

- getValue:

- objCType

Class Description

To create an NSValue object with a particular data item, you provide a pointer to the item along with a C string describing the item's type in Objective-C type encoding. You get this string using the @encode() compiler directive, which returns the platform-specific encoding for the given type (See the section "Types Encoding" in the chapter "Objective-C Extensions" in the book Object-Oriented Programming and the Objective-C Language for more information about @encode() and a list of type codes). Fore example, this code excerpt creates theValue containing an NSRange:

NSRange myRange = {4, 10};
NSValue *theValue = [NSValue valueWithBytes:&myRange objCType:@encode(NSRange)];

Note that the type you specify must be of constant length. C strings, variable-length arrays and structures, and other data types of indeterminate length can't be stored in an NSValue. You should use NSString or NSData objects for these. If you must store a variable-length item in an NSValue, you have to store a pointer to the item, not the item itself. This code excerpt incorrectly attempts to place a C string directly into an NSValue object:

/* INCORRECT! */
char *myCString = "This is a string.";
NSValue *theValue = [NSValue value:myCString withObjCType:@encode(char *)];

In this code excerpt the contents of myCString are interpreted as a pointer to a char, so that the first four bytes contained in the string are treated as a pointer (the actual number of bytes used may vary with the hardware architecture). That is, the sequence "This" is interpreted as a pointer value, which is unlikely to be a legal address. The correct way to store such a data item, short of using an NSString object, is to pass the address of its pointer, not the pointer itself:

/* Correct. */
char *myCString = "This is a string.";
NSValue *theValue = [NSValue value:&myCString withObjCType:@encode(char *)];

Here the address of myCString is passed, so that the address of the first character of the string is stored in theValue. Note that the NSValue doesn't copy the contents of the string, but the pointer itself. If you create an NSValue with an allocated data item, don't deallocate its memory while the NSValue object exists.

Adopted Protocols

NSCoding

- encodeWithCoder:

- initWithCoder:

NSCopying

- copyWithZone:

Creating an NSValue

- initWithBytes:objCType:

+ valueWithBytes:objCType:

+ value:withObjCType:

+ valueWithNonretainedObject:

+ valueWithPointer:

+ valueWithPoint:

+ valueWithRect:

+ valueWithSize:

Accessing data

- getValue:

- nonretainedObjectValue

- objCType

- pointValue

- pointerValue

- rectValue

- sizeValue

Comparing objects

- isEqualToValue:

Class Methods

value:withObjCType:

Creates and returns an NSValue containing value, which is interpreted as being of the Objective-C type type. type should be created with the Objective-C @encode() compiler directive; it shouldn't be hard-coded as a C string. See the class description for other considerations in creating an NSValue object and code examples.

See also: + valueWithBytes:objCType:

valueWithBytes:objCType:

Creates and returns an NSValue containing value, which is interpreted as being of the Objective-C type type. type should be created with the Objective-C @encode() compiler directive; it shouldn't be hard-coded as a C string. This method is equivalent to value:withObjCType:, which is part of OpenStep. See the class description for other considerations in creating an NSValue object and code examples.

See also: - initWithBytes:objCType:

valueWithNonretainedObject:

Creates and returns an NSValue containing anObject, but doesn't retain it. This method is equivalent to invoking value:withObjCType: in this manner:

NSValue *theValue = [NSValue value:&anObject withObjCType:@encode(void *)];

This method is useful for preventing an object from being retained when it's added to a collection object (such as an NSArray or NSDictionary).

See also: - nonretainedObjectValue

valueWithPoint:

Creates and returns an NSValue object that contains the specified NSPoint structure (which represents a geometrical point in two dimensions).

See also: - pointValue

valueWithPointer:

Creates and returns an NSValue object that contains aPointer. This method is equivalent to invoking value:withObjCType: in this manner:

NSValue *theValue = [NSValue value:&aPointer withObjCType:@encode(void *)];

This method doesn't copy the contents of aPointer, so you should be sure not to deallocate that memory while the NSValue object exists. NSData objects may be more suited for arbitrary pointers than NSValue objects.

See also: - pointerValue

valueWithRect:

Creates and returns an NSValue object that contains the specified NSRect structure (which represents the coordinates of the rectangle's origin).

See also: - rectValue

valueWithSize:

Creates and returns an NSValue that contains the specified NSSize structure (which represents the width and height of a rectangle).

See also: - sizeValue

Instance Methods

getValue:

Copies the NSValue's contents into buffer. buffer should be large enough to hold the value.

initWithBytes:objCType:

Initializes a newly created NSValue to contain value, which is interpreted as being of the Objective-C type type. type should be created with the Objective-C @encode() compiler directive; it shouldn't be hard-coded as a C string. See the class description for other considerations in creating an NSValue object.

This is the designated initializer for the NSValue class. Returns self.

isEqualToValue:

Returns YES if the receiver and aValue are equal, otherwise returns NO. For NSValue objects, the class, type, and contents are compared to determine equality.

nonretainedObjectValue

For an NSValue object created to hold a pointer-sized data item, returns that item as an id. For any other NSValue object the result is undefined.

See also: - getValue:

objCType

Returns a C string containing the Objective-C type of the data contained in the receiver, as encoded by the @encode() compiler directive.

pointValue

Returns an NSPoint structure (which represents a geometrical point in two dimensions).

See also: - rectValue, - sizeValue

pointerValue

For an NSValue object created to hold a pointer-sized data item, returns that item as a pointer to void. For any other NSValue object the result is undefined.

See also: - getValue:

rectValue

Returns an NSRect structure (which represents the coordinates of the rectangle's origin).

See also: - pointValue, - sizeValue

sizeValue

Returns an NSSize structure (which represents the width and height of a rectangle).

See also: - pointValue, - rectValue

Copyright © 1997, Apple Computer, Inc. All rights reserved.