Mac Developer Library

Developer

Foundation Framework Reference NSValue Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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

  1. typedef struct {
  2. int numFaces;
  3. float radius;
  4. } Polyhedron;
  5. @interface NSValue (Polyhedron)
  6. + (instancetype)valuewithPolyhedron:(Polyhedron)value;
  7. @property (readonly) Polyhedron polyhedronValue;
  8. @end
  9. @implementation NSValue (Polyhedron)
  10. + (instancetype)valuewithPolyhedron:(Polyhedron)value
  11. {
  12. return [self valueWithBytes:&value objCType:@encode(Polyhedron)];
  13. }
  14. - (Polyhedron) polyhedronValue
  15. {
  16. Polyhedron value;
  17. [self getValue:&value];
  18. return value;
  19. }
  20. @end
  • Initializes a value object to contain the specified value, interpreted with the specified Objective-C type.

    Declaration

    Swift

    init(bytes value: UnsafePointer<Void>, objCType type: UnsafePointer<Int8>)

    Objective-C

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

    Parameters

    value

    A pointer to data to be stored in the new value object.

    type

    The Objective-C type of value, as provided by the @encode() compiler directive. Do not hard-code this parameter as a C string.

    Return Value

    An initialized value 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 other considerations in creating a value object.

    This is the designated initializer for the NSValue class.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Parameters

    value

    A pointer to data to be stored in the new value object.

    type

    The Objective-C type of value, as provided by the @encode() compiler directive. Do not hard-code this parameter as a C string.

    Return Value

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

    Discussion

    See Number and Value Programming Topics for other considerations in creating a value object and code examples.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(_ value: UnsafePointer<Void>, withObjCType type: UnsafePointer<Int8>)

    Objective-C

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

    Parameters

    value

    A pointer to data to be stored in the new value object.

    type

    The Objective-C type of value, as provided by the @encode() compiler directive. Do not hard-code this parameter as a C string.

    Return Value

    A new value 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 OS X v10.0 and later.

  • Copies the value into the specified buffer.

    Declaration

    Swift

    func getValue(_ value: UnsafeMutablePointer<Void>)

    Objective-C

    - (void)getValue:(void *)buffer

    Parameters

    buffer

    A buffer into which to copy the value. The buffer must be large enough to hold the value.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var objCType: UnsafePointer<Int8> { get }

    Objective-C

    @property(readonly) const char *objCType

    Discussion

    This property provides the same string produced by the @encode() compiler directive.

    Availability

    Available in OS X v10.0 and later.

  • Creates a value object containing the specified pointer.

    Declaration

    Swift

    init(pointer pointer: UnsafePointer<Void>)

    Objective-C

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

    Parameters

    aPointer

    The value for the new object.

    Return Value

    A new value object that contains aPointer.

    Discussion

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

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

    This method does not copy the contents of aPointer, so you must not to free 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 OS X v10.0 and later.

  • Creates a value object containing the specified object.

    Declaration

    Swift

    init(nonretainedObject anObject: AnyObject?)

    Objective-C

    + (NSValue *)valueWithNonretainedObject:(id)anObject

    Parameters

    anObject

    The value for the new object.

    Return Value

    A new value object that contains anObject.

    Discussion

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

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

    This method is useful if you want to add an object to a collection but don’t want the collection to create a strong reference to it.

    Availability

    Available in OS X v10.0 and later.

  • Returns the value as an untyped pointer.

    Declaration

    Swift

    var pointerValue: UnsafeMutablePointer<Void> { get }

    Objective-C

    @property(readonly) void *pointerValue

    Return Value

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

    Availability

    Available in OS X v10.0 and later.

  • The value as a non-retained pointer to an object. (read-only)

    Declaration

    Swift

    var nonretainedObjectValue: AnyObject? { get }

    Objective-C

    @property(readonly) id nonretainedObjectValue

    Discussion

    If the value was not created to hold a pointer-sized data item, the result is undefined.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(range range: NSRange)

    Objective-C

    + (NSValue *)valueWithRange:(NSRange)range

    Parameters

    range

    The value for the new object.

    Return Value

    A new value object that contains the range information.

    Availability

    Available in OS X v10.0 and later.

  • The Foundation range structure representation of the value. (read-only)

    Declaration

    Swift

    var rangeValue: NSRange { get }

    Objective-C

    @property(readonly) NSRange rangeValue

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(point point: NSPoint)

    Objective-C

    + (NSValue *)valueWithPoint:(NSPoint)aPoint

    Parameters

    aPoint

    The value for the new object.

    Return Value

    A new value object that contains the point information.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(size size: NSSize)

    Objective-C

    + (NSValue *)valueWithSize:(NSSize)size

    Parameters

    size

    The value for the new object.

    Return Value

    A new value object that contains the size information.

    Availability

    Available in OS X v10.0 and later.

    See Also

    sizeValue
    NSSize

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

    Declaration

    Swift

    init(rect rect: NSRect)

    Objective-C

    + (NSValue *)valueWithRect:(NSRect)rect

    Parameters

    rect

    The value for the new object.

    Return Value

    A new value object that contains the data in the rect structure.

    Availability

    Available in OS X v10.0 and later.

    See Also

    rectValue
    NSRect

  • The Foundation point structure representation of the value. (read-only)

    Declaration

    Swift

    var pointValue: NSPoint { get }

    Objective-C

    @property(readonly) NSPoint pointValue

    Availability

    Available in OS X v10.0 and later.

  • The Foundation size structure representation of the value. (read-only)

    Declaration

    Swift

    var sizeValue: NSSize { get }

    Objective-C

    @property(readonly) NSSize sizeValue

    Availability

    Available in OS X v10.0 and later.

  • The Foundation rectangle structure representation of the value. (read-only)

    Declaration

    Swift

    var rectValue: NSRect { get }

    Objective-C

    @property(readonly) NSRect rectValue

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(CATransform3D t: CATransform3D)

    Objective-C

    + (NSValue *)valueWithCATransform3D:(CATransform3D)aTransform

    Parameters

    aTransform

    The value for the new object.

    Return Value

    A new value object that contains the transform information.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

    See Also

    CATransform3DValue
    CATransform3D

  • The CoreAnimation transform structure representation of the value. (read-only)

    Declaration

    Swift

    var CATransform3DValue: CATransform3D { get }

    Objective-C

    @property(readonly) CATransform3D CATransform3DValue

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

    See Also

    + valueWithCATransform3D:
    CATransform3D

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

    Declaration

    Swift

    init(CMTime time: CMTime)

    Objective-C

    + (NSValue *)valueWithCMTime:(CMTime)time

    Parameters

    time

    The value for the new object.

    Return Value

    A new value object that contains the media time information.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    init(CMTimeRange timeRange: CMTimeRange)

    Objective-C

    + (NSValue *)valueWithCMTimeRange:(CMTimeRange)timeRange

    Parameters

    timeRange

    The value for the new object.

    Return Value

    A new value object that contains the time range information.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    init(CMTimeMapping timeMapping: CMTimeMapping)

    Objective-C

    + (NSValue *)valueWithCMTimeMapping:(CMTimeMapping)timeMapping

    Parameters

    timeMapping

    The value for the new object.

    Return Value

    A new value object that contains the time mapping information.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The CoreMedia time structure representation of the value. (read-only)

    Declaration

    Swift

    var CMTimeValue: CMTime { get }

    Objective-C

    @property(readonly) CMTime CMTimeValue

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The CoreMedia time range structure representation of the value. (read-only)

    Declaration

    Swift

    var CMTimeRangeValue: CMTimeRange { get }

    Objective-C

    @property(readonly) CMTimeRange CMTimeRangeValue

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The CoreMedia time mapping structure representation of the value. (read-only)

    Declaration

    Swift

    var CMTimeMappingValue: CMTimeMapping { get }

    Objective-C

    @property(readonly) CMTimeMapping CMTimeMappingValue

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    init(SCNVector3 v: SCNVector3)

    Objective-C

    + (NSValue *)valueWithSCNVector3:(SCNVector3)vector

    Parameters

    vector

    The value for the new object.

    Return Value

    A new value object that contains the vector information.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    init(SCNVector4 v: SCNVector4)

    Objective-C

    + (NSValue *)valueWithSCNVector4:(SCNVector4)vector

    Parameters

    vector

    The value for the new object.

    Return Value

    A new value object that contains the vector information.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    init(SCNMatrix4 v: SCNMatrix4)

    Objective-C

    + (NSValue *)valueWithSCNMatrix4:(SCNMatrix4)v

    Parameters

    v

    The value for the new object.

    Return Value

    A new value object that contains the matrix information.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.10 and later.

  • The three-element Scene Kit vector representation of the value. (read-only)

    Declaration

    Swift

    var SCNVector3Value: SCNVector3 { get }

    Objective-C

    @property(nonatomic, readonly) SCNVector3 SCNVector3Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • The four-element Scene Kit vector representation of the value. (read-only)

    Declaration

    Swift

    var SCNVector4Value: SCNVector4 { get }

    Objective-C

    @property(nonatomic, readonly) SCNVector4 SCNVector4Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • The Scene Kit 4 x 4 matrix representation of the value. (read-only)

    Declaration

    Swift

    var SCNMatrix4Value: SCNMatrix4 { get }

    Objective-C

    @property(nonatomic, readonly) SCNMatrix4 SCNMatrix4Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    func isEqualToValue(_ value: NSValue) -> Bool

    Objective-C

    - (BOOL)isEqualToValue:(NSValue *)aValue

    Parameters

    aValue

    The other value object with which to compare the value object.

    Return Value

    YEStrue if both value objects are equal; otherwise, NOfalse.

    Discussion

    The NSValue class compares the type and contents of each value object to determine equality.

    Availability

    Available in OS X v10.0 and later.