Class

NSValue

A simple container for a single C or Objective-C data item.

Declaration

@interface NSValue : NSObject

Overview

An NSValue object can hold any of the scalar types such as int, float, and char, as well as pointers, structures, and object id references. Use this class to work with such data types in collections (such as NSArray and NSSet), Key-value coding, and other APIs that require Objective-C objects. NSValue objects are always immutable.

Subclassing Notes

The abstract NSValue class is the public interface of a class cluster consisting mostly of private, concrete classes that create and return a value object appropriate for a given situation. It is possible to subclass NSValue, but doing so requires providing storage facilities for the value (which is not inherited by subclasses) and implementing two primitive methods.

Methods to Override

Any subclass of NSValue must override the primitive instance methods getValue: and objCType. These methods must operate on the storage that you provide for the value.

You might want to implement an initializer for your subclass that is suited to the storage you provide. The NSValue class does not have a designated initializer, so your initializer need only invoke the init method of super. The NSValue class adopts the NSCopying and NSSecureCoding protocols; if you want instances of your own custom subclass created from copying or coding, override the methods in these protocols.

You may also wish to implement the hash method to make your subclass work well in collections.

Alternatives to Subclassing

If you need only to use NSValue objects for wrap a custom data types or structures defined by your app, you need not create an NSValue subclass. Instead, create a category that uses existing NSValue methods to store and retrieve data of your custom type. For example, the code below defines a custom Polyhedron structure and creates NSValue convenience methods to store and retrieve it:

typedef struct {
    int numFaces;
    float radius;
} Polyhedron;
 
@interface NSValue (Polyhedron)
+ (instancetype)valuewithPolyhedron:(Polyhedron)value;
@property (readonly) Polyhedron polyhedronValue;
@end
 
@implementation NSValue (Polyhedron)
+ (instancetype)valuewithPolyhedron:(Polyhedron)value
{
    return [self valueWithBytes:&value objCType:@encode(Polyhedron)];
}
- (Polyhedron) polyhedronValue
{
    Polyhedron value;
    [self getValue:&value];
    return value;
}
@end

Topics

Working with Raw Values

- initWithBytes:objCType:

Initializes a value object to contain the specified value, interpreted with the specified Objective-C type.

+ valueWithBytes:objCType:

Creates a value object containing the specified value, interpreted with the specified Objective-C type.

+ value:withObjCType:

Creates a value object containing the specified value, interpreted with the specified Objective-C type.

- getValue:

Copies the value into the specified buffer.

Deprecated
objCType

A C string containing the Objective-C type of the data contained in the value object.

Working with Pointer and Object Values

+ valueWithPointer:

Creates a value object containing the specified pointer.

+ valueWithNonretainedObject:

Creates a value object containing the specified object.

pointerValue

Returns the value as an untyped pointer.

nonretainedObjectValue

The value as a non-retained pointer to an object.

Working with Range Values

+ valueWithRange:

Creates a new value object containing the specified Foundation range structure.

rangeValue

The Foundation range structure representation of the value.

Working with Foundation Geometry Values

+ valueWithPoint:

Creates a new value object containing the specified Foundation point structure.

+ valueWithSize:

Creates a new value object containing the specified Foundation size structure.

+ valueWithRect:

Creates a new value object containing the specified Foundation rectangle structure.

pointValue

The Foundation point structure representation of the value.

sizeValue

The Foundation size structure representation of the value.

rectValue

The Foundation rectangle structure representation of the value.

Working with CoreGraphics Geometry Values

+ valueWithCGPoint:

Creates a new value object containing the specified CoreGraphics point structure.

+ valueWithCGVector:

Creates a new value object containing the specified CoreGraphics vector structure.

+ valueWithCGSize:

Creates a new value object containing the specified CoreGraphics size structure.

+ valueWithCGRect:

Creates a new value object containing the specified CoreGraphics rectangle structure.

+ valueWithCGAffineTransform:

Creates a new value object containing the specified CoreGraphics affine transform structure.

CGPointValue

Returns the CoreGraphics point structure representation of the value.

CGVectorValue

Returns the CoreGraphics vector structure representation of the value.

CGSizeValue

Returns the CoreGraphics size structure representation of the value.

CGRectValue

Returns the CoreGraphics rectangle structure representation of the value.

CGAffineTransformValue

Returns the CoreGraphics affine transform representation of the value.

Working with UIKit Geometry Values

+ valueWithUIEdgeInsets:

Creates a new value object containing the specified UIKit edge insets structure.

+ valueWithUIOffset:

Creates a new value object containing the specified UIKit offset structure.

UIEdgeInsetsValue

Returns the UIKit edge insets structure representation of the value.

UIOffsetValue

Returns the UIKit offset structure representation of the value.

Working with CoreAnimation Transform Values

+ valueWithCATransform3D:

Creates a new value object containing the specified CoreAnimation transform structure.

CATransform3DValue

The CoreAnimation transform structure representation of the value.

Working with Media Time Values

+ valueWithCMTime:

Creates a new value object containing the specified CoreMedia time structure.

+ valueWithCMTimeRange:

Creates a new value object containing the specified CoreMedia time range structure.

+ valueWithCMTimeMapping:

Creates a new value object containing the specified CoreMedia time mapping structure.

CMTimeValue

The CoreMedia time structure representation of the value.

CMTimeRangeValue

The CoreMedia time range structure representation of the value.

CMTimeMappingValue

The CoreMedia time mapping structure representation of the value.

Working with Geographic Coordinate Values

+ valueWithMKCoordinate:

Creates a new value object containing the specified CoreLocation geographic coordinate structure.

+ valueWithMKCoordinateSpan:

Creates a new value object containing the specified MapKit coordinate span structure.

MKCoordinateValue

The CoreLocation geographic coordinate structure representation of the value.

MKCoordinateSpanValue

The MapKit coordinate span structure representation of the value.

Working with SceneKit Vector and Matrix Values

+ valueWithSCNVector3:

Creates a value object that contains the specified three-element SceneKit vector.

+ valueWithSCNVector4:

Creates a value object that contains the specified four-element SceneKit vector.

+ valueWithSCNMatrix4:

Creates a value object that contains the specified SceneKit 4 x 4 matrix.

SCNVector3Value

The three-element Scene Kit vector representation of the value.

SCNVector4Value

The four-element Scene Kit vector representation of the value.

SCNMatrix4Value

The Scene Kit 4 x 4 matrix representation of the value.

Comparing Value Objects

- isEqualToValue:

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

Instance Methods

Relationships

Inherits From

See Also

Value Wrappers and Transformations

NSNumber

An object wrapper for primitive scalar numeric values.

NSValueTransformer

An abstract class used to transform values from one representation to another.