Class

NSDimension

NSDimension is an abstract subclass of NSUnit that declares a programmatic interface for objects that represent a dimensional unit of measure. The Foundation framework provides concrete subclasses for many of the most common types of physical units.

Overview

NSDimension subclass

Description

Base unit

NSUnitAcceleration

Unit of measure for acceleration

meters per second squared (m/s²)

NSUnitAngle

Unit of measure for planar angle and rotation

degrees (°)

NSUnitArea

Unit of measure for area

square meters (m²)

NSUnitConcentrationMass

Unit of measure for concentration of mass

milligrams per deciliter (mg/dL)

NSUnitDispersion

Unit of measure for dispersion

parts per million (ppm)

NSUnitDuration

Unit of measure for duration

seconds (sec)

NSUnitElectricCharge

Unit of measure for electric charge

coulombs (C)

NSUnitElectricCurrent

Unit of measure for electric current

amperes (A)

NSUnitElectricPotentialDifference

Unit of measure for electric potential difference

volts (V)

NSUnitElectricResistance

Unit of measure for electric resistance

ohms (Ω)

NSUnitEnergy

Unit of measure for energy

joules (J)

NSUnitFrequency

Unit of measure for frequency

hertz (Hz)

NSUnitFuelEfficiency

Unit of measure for fuel consumption

liters per 100 kilometers (L/100km)

NSUnitIlluminance

Unit of measure for illuminance

lux (lx)

NSUnitLength

Unit of measure for length

meters (m)

NSUnitMass

Unit of measure for mass

kilograms (kg)

NSUnitPower

Unit of measure for power

watts (W)

NSUnitPressure

Unit of measure for pressure

newtons per square meter (N/m²)

NSUnitSpeed

Unit of measure for speed

meters per second (m/s)

NSUnitTemperature

Unit of measure for temperature

kelvin (K)

NSUnitVolume

Unit of measure for volume

liters (L)

Each instance of an NSDimension subclass has a converter, which is used to represent the unit in terms of the dimension’s baseUnit. For example, the NSLengthUnit class uses meters as its base unit. The predefined miles unit is defined by a NSUnitConverterLinear with a coefficient of 1609.34, which corresponds to the conversion ratio of miles to meters (1 mi = 1609.34 m); the predefined meters unit is defined by a NSUnitConverterLinear with a coefficient of 1.0, 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 initWithSymbol:converter: method.

For example, the smoot is a nonstandard unit of length (1 smoot = 1.70180 m). You can create a new instance of NSUnitLength as follows:

NSUnitConverter *smootsToMeters = [[NSUnitConverterLinear alloc] initWithCoefficient:1.70180];
NSUnitLength *smoots = [[NSUnitLength alloc] initWithSymbol:@"smoot" converter:smootsToMeters]];

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 NSUnitSpeed to add a furlongsPerFortnight class method for convenient access as follows:

@interface NSUnitSpeed ()
+ (NSUnitSpeed *)furlongsPerFortnight;
@end
 
@implementation NSUnitSpeed ()
+ (NSUnitSpeed *)furlongsPerFortnight {
    NSUnitConverter *furlongsPerFortnightToMetersPerSecond = [[NSUnitConverterLinear alloc] initWithCoefficient:201.168 / 1209600.0];
    return [[NSUnitSpeed alloc] initWithSymbol:@"fur/ftn" converter:furlongsPerFortnightToMetersPerSecond];
}
@end

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 CustomUnitRadioactivity class that defines both units of radioactivity as follows:

@interface CustomUnitRadioactivity: NSDimension
+ (CustomUnitRadioactivity *)becquerels;
+ (CustomUnitRadioactivity *)curies;
@end
 
@implementation CustomRadioactivityUnit
+ (CustomUnitRadioactivity *)becquerels {
    NSUnitConverter *baseUnitConverter = [[NSUnitConverterLinear alloc] initWithCoefficient:1];
    return [[CustomUnitRadioactivity alloc] initWithSymbol:@"Bq" converter:baseUnitConverter];
}
 
+ (CustomUnitRadioactivity *)curies {
    NSUnitConverter *curiesToBecquerels = [[NSUnitConverterLinear alloc] initWithCoefficient:3.7e10];
    return [[CustomUnitRadioactivity alloc] initWithSymbol:@"Ci" converter:curiesToBecquerels];
}
 
+ (instancetype)baseUnit {
    return [self bacquerels];
}
@end

Subclassing Notes

NSDimension is intended for subclassing. Although the subclasses listed in 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 NSUnit directly.

Methods to Override

All subclasses must fully implement the baseUnit 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 NSUnitIlluminance class defines its baseUnit 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 initWithSymbol:converter: method or extending the subclass and adding a corresponding class method.

Symbols

Creating Dimensions

- initWithSymbol:converter:

Initializes a dimensional unit with the specified symbol and unit converter.

Accessing the Unit Converter

converter

Returns the unit converter used to represent the unit in terms of the dimension’s base unit.

Accessing the Base Unit

+ baseUnit

Returns the base unit.

Relationships

Inherits From

Conforms To