An abstract class representing a dimensional unit of measure.
- iOS 10.0+
- macOS 10.12+
- Mac Catalyst 13.0+
- tvOS 10.0+
- watchOS 3.0+
The Foundation framework provides concrete subclasses for many of the most common types of physical units.
Unit of measure for acceleration
meters per second squared (m/s²)
Unit of measure for planar angle and rotation
Unit of measure for area
square meters (m²)
Unit of measure for concentration of mass
milligrams per deciliter (mg/dL)
Unit of measure for dispersion
parts per million (ppm)
Unit of measure for duration
Unit of measure for electric charge
Unit of measure for electric current
Unit of measure for electric potential difference
Unit of measure for electric resistance
Unit of measure for energy
Unit of measure for frequency
Unit of measure for fuel consumption
liters per 100 kilometers (L/100km)
Unit of measure for illuminance
Unit of measure for length
Unit of measure for mass
Unit of measure for power
Unit of measure for pressure
newtons per square meter (N/m²)
Unit of measure for speed
meters per second (m/s)
Unit of measure for temperature
Unit of measure for volume
Each instance of an
NSDimension subclass has a
converter, which is used to represent the unit in terms of the dimension’s
base. For example, the NSLengthUnit class uses
meters as its base unit. The predefined
miles unit is defined by a
NSUnit with a
1609, which corresponds to the conversion ratio of miles to meters (1 mi = 1609.34 m); the predefined
meters unit is defined by a
NSUnit with a
1, because it’s the base unit.
You typically use an
NSDimension subclass in conjunction with the
NSMeasurement class to represent specific quantities of a particular unit.
Working with Custom Units
In addition to the Apple-provided units, you can define custom units. Custom units can be initialized from a symbol and converter of an existing type or implemented as a class method of an existing type for additional convenience. You can also define your own
NSDimension subclass to represent an entirely new unit dimension.
Initializing a Custom Unit with a Specified Symbol and Definition
The simplest way to define a custom unit is to create a new instance of an existing
NSDimension subclass using the
For example, the smoot is a nonstandard unit of length (1 smoot = 1.70180 m). You can create a new instance of
NSUnit as follows:
Extending Existing NSDimension Subclasses
Alternatively, if a custom unit is used extensively throughout an app, consider extending the corresponding
NSDimension subclass and adding a class method.
For example, speed can be measured in furlongs per fortnight (1 fur/ftn = 201.168 m / 1,209,600 s). If an app makes frequent use of this unit, you can extend
NSUnit to add a
furlongs class method for convenient access as follows:
Creating a Custom NSDimension Subclass
You can create a new subclass of
NSDimension to describe a new unit dimension.
For example, the Foundation framework does not define any units for radioactivity. Radioactivity is the process by which the nucleus of an atom emits radiation. The SI unit of measure for radioactivity is the becquerel (Bq), which is defined as the quantity of radioactive material in which one nucleus decays per second (1 Bq = 1 s-1). Radioactivity is also commonly described in terms of curies (Ci), a unit defined relative to the decay of one gram of the radium-226 isotope (1 Ci = 3.7 × 1010 Bq). You can implement a
Custom class that defines both units of radioactivity as follows:
NSDimension is intended for subclassing. Although the subclasses listed in Table 1 are suitable for most purposes, you may want to define a custom unit type. For instance, you may need a custom unit type to represent a derived unit, such as magnetic flux (measured as the product of electric potential difference and time).
To represent dimensionless units, subclass
Methods to Override
All subclasses must fully implement the
base method designating the base unit, relative to which any additional units are defined.
You should also implement a class method named for the base unit itself, which may be used interchangeably. For example, the
NSUnit class defines its
base in terms of the lux (lx), and provides a corresponding
lux class method.
Alternatives to Subclassing
As described in Working with Custom Units, you only need to create a custom subclass of
NSDimension if a unit of the desired dimension is not yet defined. You can define a custom unit for an existing
NSDimension subclass by either calling the
init method or extending the subclass and adding a corresponding class method.