Class

NSValue

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

Overview

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 NSValuemust override the primitive instance methods get​Value(_:​) and obj​CType. 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 NSSecure​Coding 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

Symbols

Working with Raw Values

init(bytes:​ Unsafe​Raw​Pointer, obj​CType:​ Unsafe​Pointer<Int8>)

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

init(Unsafe​Raw​Pointer, with​Obj​CType:​ Unsafe​Pointer<Int8>)

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

func get​Value(Unsafe​Mutable​Raw​Pointer)

Copies the value into the specified buffer.

var obj​CType:​ Unsafe​Pointer<Int8>

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

Working with Pointer and Object Values

init(pointer:​ Unsafe​Raw​Pointer?)

Creates a value object containing the specified pointer.

init(nonretained​Object:​ Any?)

Creates a value object containing the specified object.

var pointer​Value:​ Unsafe​Mutable​Raw​Pointer?

Returns the value as an untyped pointer.

var nonretained​Object​Value:​ Any?

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

Working with Range Values

init(range:​ NSRange)

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

var range​Value:​ NSRange

The Foundation range structure representation of the value.

Working with Foundation Geometry Values

init(point:​ NSPoint)

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

init(size:​ NSSize)

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

init(rect:​ NSRect)

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

var point​Value:​ NSPoint

The Foundation point structure representation of the value.

var size​Value:​ NSSize

The Foundation size structure representation of the value.

var rect​Value:​ NSRect

The Foundation rectangle structure representation of the value.

Working with CoreGraphics Geometry Values

init(cg​Point:​ CGPoint)

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

init(cg​Vector:​ CGVector)

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

init(cg​Size:​ CGSize)

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

init(cg​Rect:​ CGRect)

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

init(cg​Affine​Transform:​ CGAffine​Transform)

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

var cg​Point​Value:​ CGPoint

Returns the CoreGraphics point structure representation of the value.

var cg​Vector​Value:​ CGVector

Returns the CoreGraphics vector structure representation of the value.

var cg​Size​Value:​ CGSize

Returns the CoreGraphics size structure representation of the value.

var cg​Rect​Value:​ CGRect

Returns the CoreGraphics rectangle structure representation of the value.

var cg​Affine​Transform​Value:​ CGAffine​Transform

Returns the CoreGraphics affine transform representation of the value.

Working with UIKit Geometry Values

init(ui​Edge​Insets:​ UIEdge​Insets)

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

init(ui​Offset:​ UIOffset)

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

var ui​Edge​Insets​Value:​ UIEdge​Insets

Returns the UIKit edge insets structure representation of the value.

var ui​Offset​Value:​ UIOffset

Returns the UIKit offset structure representation of the value.

Working with CoreAnimation Transform Values

init(ca​Transform3D:​ CATransform3D)

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

var ca​Transform3DValue:​ CATransform3D

The CoreAnimation transform structure representation of the value.

Working with Media Time Values

init(time:​ CMTime)

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

init(time​Range:​ CMTime​Range)

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

init(time​Mapping:​ CMTime​Mapping)

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

var time​Value:​ CMTime

The CoreMedia time structure representation of the value.

var time​Range​Value:​ CMTime​Range

The CoreMedia time range structure representation of the value.

var time​Mapping​Value:​ CMTime​Mapping

The CoreMedia time mapping structure representation of the value.

Working with Geographic Coordinate Values

init(mk​Coordinate:​ CLLocation​Coordinate2D)

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

init(mk​Coordinate​Span:​ MKCoordinate​Span)

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

var mk​Coordinate​Value:​ CLLocation​Coordinate2D

The CoreLocation geographic coordinate structure representation of the value.

var mk​Coordinate​Span​Value:​ MKCoordinate​Span

The MapKit coordinate span structure representation of the value.

Working with SceneKit Vector and Matrix Values

init(scn​Vector3:​ SCNVector3)

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

init(scn​Vector4:​ SCNVector4)

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

init(scn​Matrix4:​ SCNMatrix4)

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

var scn​Vector3Value:​ SCNVector3

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

var scn​Vector4Value:​ SCNVector4

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

var scn​Matrix4Value:​ SCNMatrix4

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

Comparing Value Objects

func is​Equal(to:​ NSValue)

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