iOS Developer Library

Developer

UIKit Framework Reference NSValue Class Reference

Options
Deployment Target:

On This Page
Language:

NSValue

Inherits From


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later

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:

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.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>) -> NSValue

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

  • Copies the value into the specified buffer.

    Declaration

    Swift

    func getValue(_ buffer: 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

  • objCType objCType Property

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

  • Creates a value object containing the specified pointer.

    Declaration

    Swift

    init(pointer aPointer: UnsafePointer<Void>) -> NSValue

    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:

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

  • Creates a value object containing the specified object.

    Declaration

    Swift

    init(nonretainedObject anObject: AnyObject?) -> NSValue

    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:

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

  • Returns the value as an untyped pointer.

    Declaration

    Swift

    func pointerValue() -> UnsafeMutablePointer<Void>

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    var nonretainedObjectValue: AnyObject? { get }

    Objective-C

    @property(nonatomic, readonly) id nonretainedObjectValue

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init(range range: NSRange) -> NSValue

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(CGPoint point: CGPoint) -> NSValue

    Objective-C

    + (NSValue *)valueWithCGPoint:(CGPoint)point

    Parameters

    point

    The value for the new object.

    Return Value

    A new value object that contains the point information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(CGVector vector: CGVector) -> NSValue

    Objective-C

    + (NSValue *)valueWithCGVector:(CGVector)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 UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

    init!(CGSize size: CGSize) -> NSValue

    Objective-C

    + (NSValue *)valueWithCGSize:(CGSize)size

    Parameters

    size

    The value for the new object.

    Return Value

    A new value object that contains the size information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(CGRect rect: CGRect) -> NSValue

    Objective-C

    + (NSValue *)valueWithCGRect:(CGRect)rect

    Parameters

    rect

    The value for the new object.

    Return Value

    A new value object that contains the rectangle information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(CGAffineTransform transform: CGAffineTransform) -> NSValue

    Objective-C

    + (NSValue *)valueWithCGAffineTransform:(CGAffineTransform)transform

    Parameters

    transform

    The value for the new object.

    Return Value

    A new value object that contains the affine transform information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Returns the CoreGraphics point structure representation of the value.

    Declaration

    Swift

    func CGPointValue() -> CGPoint

    Objective-C

    - (CGPoint)CGPointValue

    Return Value

    The CoreGraphics point structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Returns the CoreGraphics vector structure representation of the value.

    Declaration

    Swift

    func CGVectorValue() -> CGVector

    Objective-C

    - (CGVector)CGVectorValue

    Return Value

    The CoreGraphics vector structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later

  • Returns the CoreGraphics size structure representation of the value.

    Declaration

    Swift

    func CGSizeValue() -> CGSize

    Objective-C

    - (CGSize)CGSizeValue

    Return Value

    The CoreGraphics size structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Returns the CoreGraphics rectangle structure representation of the value.

    Declaration

    Swift

    func CGRectValue() -> CGRect

    Objective-C

    - (CGRect)CGRectValue

    Return Value

    The CoreGraphics rectangle structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Returns the CoreGraphics affine transform representation of the value.

    Declaration

    Swift

    func CGAffineTransformValue() -> CGAffineTransform

    Objective-C

    - (CGAffineTransform)CGAffineTransformValue

    Return Value

    The CoreGraphics affine transform representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(UIEdgeInsets insets: UIEdgeInsets) -> NSValue

    Objective-C

    + (NSValue *)valueWithUIEdgeInsets:(UIEdgeInsets)insets

    Parameters

    insets

    The value for the new object.

    Return Value

    A new value object that contains the edge inset information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    init!(UIOffset insets: UIOffset) -> NSValue

    Objective-C

    + (NSValue *)valueWithUIOffset:(UIOffset)insets

    Parameters

    insets

    The value for the new object.

    Return Value

    A new value object that contains the offset information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later

  • Returns the UIKit edge insets structure representation of the value.

    Declaration

    Swift

    func UIEdgeInsetsValue() -> UIEdgeInsets

    Objective-C

    - (UIEdgeInsets)UIEdgeInsetsValue

    Return Value

    The UIKit edge insets structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Returns the UIKit offset structure representation of the value.

    Declaration

    Swift

    func UIOffsetValue() -> UIOffset

    Objective-C

    - (UIOffset)UIOffsetValue

    Return Value

    The UIKit offset structure representation of the value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    init!(CATransform3D aTransform: CATransform3D) -> NSValue

    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 iOS 2.0 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 iOS 2.0 and later

    See Also

    + valueWithCATransform3D:
    CATransform3D

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

    Declaration

    Swift

    init!(CMTime time: CMTime) -> NSValue

    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 iOS 4.0 and later

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

    Declaration

    Swift

    init!(CMTimeRange timeRange: CMTimeRange) -> NSValue

    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 iOS 4.0 and later

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

    Declaration

    Swift

    init!(CMTimeMapping timeMapping: CMTimeMapping) -> NSValue

    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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 and later

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

    Declaration

    Swift

    init!(SCNVector3 vector: SCNVector3) -> NSValue

    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 iOS 8.0 and later

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

    Declaration

    Swift

    init!(SCNVector4 vector: SCNVector4) -> NSValue

    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 iOS 8.0 and later

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

    Declaration

    Swift

    init!(SCNMatrix4 v: SCNMatrix4) -> NSValue

    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 iOS 8.0 and later

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

    Declaration

    Swift

    var SCNVector3Value: SCNVector3 { get }

    Objective-C

    @property(readonly) SCNVector3 SCNVector3Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

    var SCNVector4Value: SCNVector4 { get }

    Objective-C

    @property(readonly) SCNVector4 SCNVector4Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

    var SCNMatrix4Value: SCNMatrix4 { get }

    Objective-C

    @property(readonly) SCNMatrix4 SCNMatrix4Value

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in iOS 8.0 and later

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

    Declaration

    Swift

    func isEqualToValue(_ aValue: 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later