Next Page > Hide TOC

NSValue Class Reference

Overview

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 collections such as instances of NSArray and NSSet, which require their elements to be objects. NSValue objects are always immutable.

Adopted Protocols

• encodeWithCoder:

• initWithCoder:

• – copyWithZone:

Tasks

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:

Class Methods

value:withObjCType:

Creates and returns an NSValue object that contains a given value which is interpreted as being of a given Objective-C type.

+ (NSValue *)value:(const void *)value withObjCType:(const char *)type

Parameters

value

The value for the new NSValue object.

type

The Objective-C type of value. type should be created with the Objective-C @encode() compiler directive; it should not be hard-coded as a C string.

Return Value

A new NSValue object that contains value, which is interpreted as being of the Objective-C type type.

Discussion

This method has the same effect as valueWithBytes:objCType: and may be deprecated in a future release. You should use valueWithBytes:objCType: instead.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + valueWithBytes:objCType:

Related Sample Code

• VideoViewer

Declared In

valueWithBytes:objCType:

Creates and returns an NSValue object that contains a given value, which is interpreted as being of a given Objective-C type.

+ (NSValue *)valueWithBytes:(const void *)value objCType:(const char *)type

Parameters

value

The value for the new NSValue object.

type

The Objective-C type of value. type should be created with the Objective-C @encode() compiler directive; it should not be hard-coded as a C string.

Return Value

A new NSValue object that contains value, which is interpreted as being of the Objective-C type type.

Discussion

See Number and Value Programming Topics for Cocoa for other considerations in creating an NSValue object and code examples.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – initWithBytes:objCType:

Declared In

valueWithNonretainedObject:

Creates and returns an NSValue object that contains a given object.

+ (NSValue *)valueWithNonretainedObject:(id)anObject

Parameters

anObject

The value for the new object.

Return Value

A new NSValue object that contains anObject.

Discussion

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 instance of NSArray or NSDictionary).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – nonretainedObjectValue

Declared In

valueWithPoint:

Creates and returns an NSValue object that contains a given NSPoint structure.

+ (NSValue *)valueWithPoint:(NSPoint)aPoint

Parameters

aPoint

The value for the new object.

Return Value

A new NSValue object that contains the value of point.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – pointValue

Related Sample Code

• Aperture Edit Plugin - Borders & Titles
• Dicey
• ImageMapExample
• PDF Annotation Editor
• TrackBall

Declared In

valueWithPointer:

Creates and returns an NSValue object that contains a given pointer.

+ (NSValue *)valueWithPointer:(const void *)aPointer

Parameters

aPointer

The value for the new object.

Return Value

A new NSValue object that contains aPointer.

Discussion

This method is equivalent to invoking value:withObjCType: in this manner:

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

This method does not copy the contents of aPointer, so you must not to deallocate the memory at the pointer destination while the NSValue object exists. NSData objects may be more suited for arbitrary pointers than NSValue objects.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – pointerValue

Declared In

valueWithRange:

Creates and returns an NSValue object that contains a given NSRange structure.

+ (NSValue *)valueWithRange:(NSRange)range

Parameters

range

The value for the new object.

Return Value

A new NSValue object that contains the value of range.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – rangeValue

Declared In

valueWithRect:

Creates and returns an NSValue object that contains a given NSRect structure.

+ (NSValue *)valueWithRect:(NSRect)rect

Parameters

rect

The value for the new object.

Return Value

A new NSValue object that contains the value of rect.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – rectValue

Related Sample Code

• IBFragmentView
• iSpend
• QTCoreVideo301
• Reducer

Declared In

valueWithSize:

Creates and returns an NSValue object that contains a given NSSize structure.

+ (NSValue *)valueWithSize:(NSSize)size

Parameters

size

The value for the new object.

Return Value

A new NSValue object that contains the value of size.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – sizeValue

Related Sample Code

• Dicey
• ImageMapExample
• QTKitMovieShuffler
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

Instance Methods

getValue:

Copies the receiver’s value into a given buffer.

- (void)getValue:(void *)buffer

Parameters

buffer

A buffer into which to copy the receiver's value. buffer must be large enough to hold the value.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• VideoViewer

Declared In

initWithBytes:objCType:

Initializes and returns an NSValue object that contains a given value, which is interpreted as being of a given Objective-C type.

- (id)initWithBytes:(const void *)value objCType:(const char *)type

Parameters

value

The value for the new NSValue object.

type

The Objective-C type of value. type should be created with the Objective-C @encode() compiler directive; it should not be hard-coded as a C string.

Return Value

An initialized NSValue object that contains value, which is interpreted as being of the Objective-C type type. The returned object might be different than the original receiver.

Discussion

See Number and Value Programming Topics for Cocoa for other considerations in creating an NSValue object.

This is the designated initializer for the NSValue class.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

isEqualToValue:

Returns a Boolean value that indicates whether the receiver and another value are equal.

- (BOOL)isEqualToValue:(NSValue *)value

Parameters

aValue

The value with which to compare the receiver.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

nonretainedObjectValue

Returns the receiver's value as an id.

- (id)nonretainedObjectValue

Return Value

The receiver's value as an id. If the receiver was not created to hold a pointer-sized data item, the result is undefined.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getValue:

Declared In

objCType

Returns a C string containing the Objective-C type of the data contained in the receiver.

- (const char *)objCType

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

pointerValue

Returns the receiver's value as a pointer to void.

- (void *)pointerValue

Return Value

The receiver's value as a pointer to void. If the receiver was not created to hold a pointer-sized data item, the result is undefined.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getValue:

Declared In

pointValue

Returns an NSPoint structure representation of the receiver.

- (NSPoint)pointValue

Return Value

An NSPoint structure representation of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – rectValue
• – sizeValue

Declared In

rangeValue

Returns an NSRange structure representation of the receiver.

- (NSRange)rangeValue

Return Value

An NSRange structure representation of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + valueWithRange:

Declared In

rectValue

Returns an NSRect structure representation of the receiver.

- (NSRect)rectValue

Return Value

An NSRect structure representation of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – pointValue
• – sizeValue

Related Sample Code

• IBFragmentView

Declared In

sizeValue

Returns an NSSize structure representation of the receiver.

- (NSSize)sizeValue

Return Value

An NSSize structure representation of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – pointValue
• – rectValue

Related Sample Code

• QTKitAdvancedDocument
• QTKitCreateMovie
• QTKitFrameStepper
• QTKitMovieShuffler
• QTKitTimeCode

Declared In

Next Page > Hide TOC