- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSObject (NSObject)
Declared in:
- Foundation/NSValue.h
- Foundation/NSGeometry.h
- Foundation/NSRange.h
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.
- 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. |
- objCType | Returns the Objective-C type for the data contained in an NSValue. |
- getValue: | Copies an NSValue's contents into a buffer. |
An NSValue object is a simple container for a single C or Objective-C data item. It can hold any of the scalar types such as int, float, and char, as well as pointers, structures, and object ids. The purpose of this class is to allow items of such data types to be added to collection objects such as NSArrays and NSSets, which require their elements to be objects. NSValue objects are always immutable.
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 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 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.
NSCoding
- - encodeWithCoder:
- - initWithCoder:
NSCopying
- - copyWithZone:
- Creating an NSValue
- - initWithBytes:objCType:
- + valueWithBytes:objCType:
- + value:withObjCType:
- + valueWithNonretainedObject:
- + valueWithPointer:
- + valueWithPoint:
- + valueWithRange:
- + valueWithRect:
- + valueWithSize:
- Accessing data
- - getValue:
- - nonretainedObjectValue
- - objCType
- - pointValue
- - pointerValue
- - rangeValue
- - rectValue
- - sizeValue
- Comparing objects
- - isEqualToValue:
+ (NSValue *)value:(const
void *)value
withObjCType:(const char *)type
@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:
+ (NSValue *)valueWithBytes:(const
void *)value
objCType:(const char *)type
@encode()
compiler
directive; it shouldn't be hard-coded as a C string. This method
is equivalent to value:withObjCType:,
which is part of Cocoa. See the class description for other considerations
in creating an NSValue object and code examples.See Also: - initWithBytes:objCType:
+ (NSValue *)valueWithNonretainedObject:(id)anObject
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
+ (NSValue *)valueWithPoint:(NSPoint)aPoint
See Also: - pointValue
+ (NSValue *)valueWithPointer:(const
void *)aPointer
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
+ (NSValue *)valueWithRange:(NSRange)range
See Also: - rangeValue
+ (NSValue *)valueWithRect:(NSRect)rect
See Also: - rectValue
+ (NSValue *)valueWithSize:(NSSize)size
See Also: - sizeValue
- (void)getValue:(void
*)buffer
- (id)initWithBytes:(const
void *)value
objCType:(const char *)type
@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:(NSValue
*)aValue
- (id)nonretainedObjectValue
See Also: - getValue:
- (const char *)objCType
@encode()
compiler
directive.- (NSPoint)pointValue
See Also: - rectValue, - sizeValue
- (void *)pointerValue
See Also: - getValue:
- (NSRange)rangeValue
See Also: + valueWithRange:
- (NSRect)rectValue
See Also: - pointValue, - sizeValue
- (NSSize)sizeValue
See Also: - pointValue, - rectValue