<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSValue",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSValue"
  },
  "title" : "NSValue"
}
-->

# NSValue

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

```
class NSValue
```

## Overview

An [`NSValue`](/documentation/Foundation/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`](/documentation/Foundation/NSArray) and [`NSSet`](/documentation/Foundation/NSSet)), [Key-value coding](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/KeyValueCoding.html#//apple_ref/doc/uid/TP40008195-CH25), and other APIs that require Objective-C objects. [`NSValue`](/documentation/Foundation/NSValue) objects are always immutable.

### Subclassing Notes

The abstract [`NSValue`](/documentation/Foundation/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`](/documentation/Foundation/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`](/documentation/Foundation/NSValue) *must* override the primitive instance methods [`getValue(_:)`](/documentation/Foundation/NSValue/getValue(_:)) and [`objCType`](/documentation/Foundation/NSValue/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`](/documentation/Foundation/NSValue) class does not have a designated initializer, so your initializer need only invoke the <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/init()> method of `super`. The [`NSValue`](/documentation/Foundation/NSValue) class adopts the [`NSCopying`](/documentation/Foundation/NSCopying) and [`NSSecureCoding`](/documentation/Foundation/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 <doc://com.apple.documentation/documentation/ObjectiveC/NSObjectProtocol/hash> method to make your subclass work well in collections.

#### Alternatives to Subclassing

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

```objc
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

[`init(bytes:objCType:)`](/documentation/Foundation/NSValue/init(bytes:objCType:))

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

[`valueWithBytes:objCType:`](/documentation/Foundation/NSValue/valueWithBytes:objCType:)

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

[`init(_:withObjCType:)`](/documentation/Foundation/NSValue/init(_:withObjCType:))

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

[`getValue(_:)`](/documentation/Foundation/NSValue/getValue(_:))

Copies the value into the specified buffer.

[`objCType`](/documentation/Foundation/NSValue/objCType)

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

### Working with Pointer and Object Values

[`init(pointer:)`](/documentation/Foundation/NSValue/init(pointer:))

Creates a value object containing the specified pointer.

[`init(nonretainedObject:)`](/documentation/Foundation/NSValue/init(nonretainedObject:))

Creates a value object containing the specified object.

[`pointerValue`](/documentation/Foundation/NSValue/pointerValue)

Returns the value as an untyped pointer.

[`nonretainedObjectValue`](/documentation/Foundation/NSValue/nonretainedObjectValue)

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

### Working with Range Values

[`init(range:)`](/documentation/Foundation/NSValue/init(range:))

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

[`rangeValue`](/documentation/Foundation/NSValue/rangeValue)

The Foundation range structure representation of the value.

### Working with Foundation Geometry Values

[`init(point:)`](/documentation/Foundation/NSValue/init(point:))

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

[`init(size:)`](/documentation/Foundation/NSValue/init(size:))

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

[`init(rect:)`](/documentation/Foundation/NSValue/init(rect:))

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

[`pointValue`](/documentation/Foundation/NSValue/pointValue)

The Foundation point structure representation of the value.

[`sizeValue`](/documentation/Foundation/NSValue/sizeValue)

The Foundation size structure representation of the value.

[`rectValue`](/documentation/Foundation/NSValue/rectValue)

The Foundation rectangle structure representation of the value.

### Working with CoreGraphics Geometry Values

[`init(CGPoint:)`](/documentation/Foundation/NSValue/init(CGPoint:))

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

[`init(CGVector:)`](/documentation/Foundation/NSValue/init(CGVector:))

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

[`init(CGSize:)`](/documentation/Foundation/NSValue/init(CGSize:))

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

[`init(CGRect:)`](/documentation/Foundation/NSValue/init(CGRect:))

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

[`init(CGAffineTransform:)`](/documentation/Foundation/NSValue/init(CGAffineTransform:))

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

[`cgPointValue`](/documentation/Foundation/NSValue/cgPointValue)

Returns the CoreGraphics point structure representation of the value.

[`cgVectorValue`](/documentation/Foundation/NSValue/cgVectorValue)

Returns the CoreGraphics vector structure representation of the value.

[`cgSizeValue`](/documentation/Foundation/NSValue/cgSizeValue)

Returns the CoreGraphics size structure representation of the value.

[`cgRectValue`](/documentation/Foundation/NSValue/cgRectValue)

Returns the CoreGraphics rectangle structure representation of the value.

[`cgAffineTransformValue`](/documentation/Foundation/NSValue/cgAffineTransformValue)

Returns the CoreGraphics affine transform representation of the value.

### Working with UIKit Geometry Values

[`init(UIEdgeInsets:)`](/documentation/Foundation/NSValue/init(UIEdgeInsets:))

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

[`init(UIOffset:)`](/documentation/Foundation/NSValue/init(UIOffset:))

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

[`uiEdgeInsetsValue`](/documentation/Foundation/NSValue/uiEdgeInsetsValue)

Returns the UIKit edge insets structure representation of the value.

[`uiOffsetValue`](/documentation/Foundation/NSValue/uiOffsetValue)

Returns the UIKit offset structure representation of the value.

### Working with CoreAnimation Transform Values

[`init(CATransform3D:)`](/documentation/Foundation/NSValue/init(CATransform3D:))

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

[`caTransform3DValue`](/documentation/Foundation/NSValue/caTransform3DValue)

The CoreAnimation transform structure representation of the value.

### Working with Media Time Values

[`init(CMTime:)`](/documentation/Foundation/NSValue/init(CMTime:))

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

[`init(CMTimeRange:)`](/documentation/Foundation/NSValue/init(CMTimeRange:))

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

[`init(CMTimeMapping:)`](/documentation/Foundation/NSValue/init(CMTimeMapping:))

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

[`timeValue`](/documentation/Foundation/NSValue/timeValue)

The CoreMedia time structure representation of the value.

[`timeRangeValue`](/documentation/Foundation/NSValue/timeRangeValue)

The CoreMedia time range structure representation of the value.

[`timeMappingValue`](/documentation/Foundation/NSValue/timeMappingValue)

The CoreMedia time mapping structure representation of the value.

### Working with Geographic Coordinate Values

[`init(MKCoordinate:)`](/documentation/Foundation/NSValue/init(MKCoordinate:))

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

[`init(MKCoordinateSpan:)`](/documentation/Foundation/NSValue/init(MKCoordinateSpan:))

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

[`mkCoordinateValue`](/documentation/Foundation/NSValue/mkCoordinateValue)

The CoreLocation geographic coordinate structure representation of the value.

[`mkCoordinateSpanValue`](/documentation/Foundation/NSValue/mkCoordinateSpanValue)

The MapKit coordinate span structure representation of the value.

### Working with SceneKit Vector and Matrix Values

[`init(SCNVector3:)`](/documentation/Foundation/NSValue/init(SCNVector3:))

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

[`init(SCNVector4:)`](/documentation/Foundation/NSValue/init(SCNVector4:))

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

[`init(SCNMatrix4:)`](/documentation/Foundation/NSValue/init(SCNMatrix4:))

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

[`scnVector3Value`](/documentation/Foundation/NSValue/scnVector3Value)

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

[`scnVector4Value`](/documentation/Foundation/NSValue/scnVector4Value)

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

[`scnMatrix4Value`](/documentation/Foundation/NSValue/scnMatrix4Value)

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

### Comparing Value Objects

[`isEqual(to:)`](/documentation/Foundation/NSValue/isEqual(to:))

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


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)