This is a bonus post in my little series on the new units of measurement types in Foundation. While I like Apple’s API, I thought it could be interesting to explore a slightly different approach to the same problem. Particularly, I was interested in the question if a pure Swift design could be significantly better than Apple’s interface, for which Objective-C compatibility inevitably is a prime consideration.
Apple’s design
The primary data type for users of Apple’s API is Measurement. It contains a floating-point value and the unit the value is measured in. It is generic over the unit type:
struct Measurement<UnitType: Unit> {
let unit: UnitType
var value: Double
}
let length = Measurement(value: 5, unit: UnitLength.meters)
// length is a Measurement<UnitLength>
Measurement got the value-type treatment — it is a class in Objective-C and a struct in Swift.
Families of units, such as length or duration, are modeled as types in a class hierarchy: Unit > Dimension > UnitLength, UnitDuration, etc. Specific units, such as meters or kilograms, are instances of their unit family class. Each unit is composed of the unit’s symbol ("kg") and a unit converter object that encodes the instructions how to convert the unit to the family’s base unit.
Phantom types
What if we modeled specific units also as types instead of instances? If we had types named Meters, Kilometers, or Miles, we could design a generic measurement type that had just a single stored property for the quantity. The quantity’s unit would be entirely encoded in the type itself:
struct MyMeasurement<UnitType: MyUnit> {
var value: Double
init(_ value: Double) {
self.value = value
}
}
let length = MyMeasurement<Meters>(5)
// length is a MyMeasurement<Meters>
Again, note the difference between the two approaches: in Apple’s API, Measurement is parameterized with the unit family length; the specific unit meters is part of the value. In my design, the generic parameter is the specific unit meters.
MyMeasurement is also called a phantom type because the generic parameter UnitType does not appear anywhere in the type’s definition. Its only purpose is to differentiate two types like MyMeasurement<Meters> and MyMeasurement<Kilometers> from each other so that they cannot be substituted.
We’ll see later whether this is actually useful in our situation because you could argue that a measurement in meters should be totally interchangeable with a measurement in kilometers. For other examples of phantom types in Swift, see this objc.io article or this talk by Johannes Weiß. The Swift standard library also makes use of phantom types, for example with UnsafePointer<Memory>.
Benefits
One obvious benefit of my approach is the 50% smaller size of the measurement data type because the reference to the unit instance is not needed. (Unit instances themselves are shared between all measurements in that unit: two measurements of 5 meters and 10 meters reference the same unit instance.) The size savings are offset by a potentially much larger code size because the compiler has to generate more specializations of the generic type and functions using the type.
Since Unit is a reference type in Apple’s API, passing Measurement values to functions also incurs some retain/release overhead. Both of these factors are unlikely to be significant in a typical app, and I haven’t investigated them further. They have certainly not been important for me while exploring these ideas.
Concrete design
We still need to specify how to define units in this system. Units are grouped into unit families, such as length, temperature, or duration. Let’s start by defining a protocol for a unit family:
/// Represents a physical quantity or “family of units”.
/// Examples: length, temperature, velocity.
protocol UnitFamily {
associatedtype BaseUnit
}
Just as in Apple’s API, each unit family must define a base unit, which is used to convert between units of the same family. For example, the base unit for the family length should be meters. We model this as an associated type of the UnitFamily protocol. This has the advantage that the base unit is encoded in the type system. In Foundation, base units must be documented separately to allow others to extend the system with custom units.
The next piece is the MyUnit protocol for modeling specific units, which in Apple’s design would be instances of a unit family type. (I’m using the My prefix to avoid naming conflicts with Apple’s types.)
/// Represents a unit of measurement.
/// Examples: meters, kilometers, miles, seconds, hours, degrees Celsius.
protocol MyUnit {
associatedtype Family: UnitFamily
static var symbol: String { get }
static var converter: UnitConverter { get }
}
A unit declares the family it belongs to through an associated type. It also defines static properties for its symbol (such as "m" for meters or “lbs” for pounds) and a unit converter that describes how to convert the unit to the family’s base unit. For example, if the base unit for the family Length is Meters, the converter for Kilometers should be UnitConverterLinear(coefficient: 1000). The unit converter for the base unit itself should always have the coefficient 1. I’m borrowing the UnitConverter class from Foundation.
Foundation makes a distinction between Unit for dimensionless units and Dimension for dimensional units. We don’t do this here for simplicity; all our units are dimensional.
A base unit must be a unit, of course, so ideally the associated type BaseUnit in UnitFamily should have a corresponding constraint BaseUnit: MyUnit. Unfortunately, that creates a circular reference between the two protocols, and that is currently not permitted in Swift. Everything works fine without the constraint, though.
Conforming to the protocols
It’s time to add some concrete implementations for these protocols. I’m showing length, duration, and speed here, with a few units each. It would be trivial to add more units (such as miles or centimeters) or entirely different unit families (such as temperature).
I chose to use enums over structs for the types because caseless enums have the nice property that they cannot be instantiated. This is perfect for us because we are only interested in the types, not in instances of the types.
// MARK: - Length
enum Length: UnitFamily {
typealias BaseUnit = Meters
}
enum Meters: MyUnit {
typealias Family = Length
static let symbol = "m"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 1)
}
enum Kilometers: MyUnit {
typealias Family = Length
static let symbol = "km"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 1000)
}
// MARK: - Duration
enum Duration: UnitFamily {
typealias BaseUnit = Seconds
}
enum Seconds: MyUnit {
typealias Family = Duration
static let symbol = "s"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 1)
}
enum Minutes: MyUnit {
typealias Family = Duration
static let symbol = "min"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 60)
}
enum Hours: MyUnit {
typealias Family = Duration
static let symbol = "hr"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 3600)
}
// MARK: - Speed
enum Speed: UnitFamily {
typealias BaseUnit = MetersPerSecond
}
enum MetersPerSecond: MyUnit {
typealias Family = Speed
static let symbol = "m/s"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 1)
}
enum KilometersPerHour: MyUnit {
typealias Family = Speed
static let symbol = "km/h"
static let converter: UnitConverter = UnitConverterLinear(coefficient: 1.0/3.6)
}
Converting measurements
Now that we can represent measurements in different units, we need a way to convert between them. The converted(to:) method takes the type of a target unit and returns a new measurement in that unit, using the unit converters. Note the constraint TargetUnit.Family == UnitType.Family, which limits conversions to the same unit family. The compiler will not let you convert Meters to Seconds.
extension MyMeasurement {
/// Converts `self` to a measurement that has another unit of the same family.
func converted<TargetUnit>(to target: TargetUnit.Type) -> MyMeasurement<TargetUnit>
where TargetUnit: MyUnit, TargetUnit.Family == UnitType.Family
{
let valueInBaseUnit = UnitType.converter.baseUnitValue(fromValue: value)
let valueInTargetUnit = TargetUnit.converter.value(fromBaseUnitValue: valueInBaseUnit)
return MyMeasurement<TargetUnit>(valueInTargetUnit)
}
Let’s also add some convenience functionality to MyMeasurement. Adding conformance to CustomStringConvertible provides us with a nice debugging output, and conforming to ExpressibleByIntegerLiteral and ExpressibleByFloatLiteral makes creating new measurements from literals much more pleasant:
extension MyMeasurement: CustomStringConvertible {
var description: String {
return "\(value) \(UnitType.symbol)"
}
}
extension MyMeasurement: ExpressibleByIntegerLiteral {
init(integerLiteral value: IntegerLiteralType) {
self.value = Double(value)
}
}
extension MyMeasurement: ExpressibleByFloatLiteral {
init(floatLiteral value: FloatLiteralType) {
self.value = value
}
}
In use
Now we can create measurements and convert them to other units. The expressible-by-literal syntax is quite nice:
let fiveMeters: MyMeasurement<Meters> = 5
// → 5.0 m
let threeKilometers: MyMeasurement<Kilometers> = 3
// → 3.0 km
threeKilometers.converted(to: Meters.self)
// → 3000.0 m
threeKilometers.converted(to: Seconds.self)
// error: 'Family' (aka 'Length') is not convertible to 'Family' (aka 'Duration') (as expected)
What about the use of measurements as function arguments? Take this hypothetical delay function that takes a duration and a closure and executes the closure after the specified duration:
func delay(after duration: MyMeasurement<Seconds>, block: () -> ()) {
// ...
}
In this form, the function requires a measurement in seconds. If you want to call it with an argument in milliseconds, it is your responsibility to convert the value. It has the advantage of ensuring type safety over a simple TimeInterval argument — the compiler will not allow you to pass a MyMeasurement<Milliseconds> —, but it is significantly less flexible than the equivalent Measurement<UnitDuration>, which would accept any duration unit.
We can achieve this, too, by making the function generic over the unit type (with the constraint that it must have a Duration family):
func delay<Time>(after duration: MyMeasurement<Time>, block: () -> ())
where Time: MyUnit, Time.Family == Duration
{
// ...
}
It works, but it makes the function signature significantly less readable, even with the where clause out of the way.
For this reason alone, Apple’s design where units are instances not types is probably more practical. And arguably it also makes more sense. After all, meters and kilometers are just different notations for essentially the same thing. But this is an exploration that doesn’t have to make sense, so let’s continue.
Addition and scalar multiplication
It should be possible to add two measurements of the same family together, even if they have different units. This is quite easy to implement with a generic overload of the + operator. As a convention, we convert the right-hand side value to the left-hand side’s unit and return the result in terms of the that unit:
func + <Unit1, Unit2> (lhs: MyMeasurement<Unit1>, rhs: MyMeasurement<Unit2>) -> MyMeasurement<Unit1>
where Unit1: MyUnit, Unit2: MyUnit, Unit1.Family == Unit2.Family
{
let rhsConverted = rhs.converted(to: Unit1.self)
return MyMeasurement(lhs.value + rhsConverted.value)
}
fiveMeters + threeKilometers
// → 3005.0 m
threeKilometers + fiveMeters
// → 3.005 km
Again, note the constraint Unit1.Family == Unit2.Family to prevent adding seconds to meters.
Multiplication with a scalar value is even easier because no unit conversions are involved. We simply multiply the value and create a new measurement. Two overloads are needed for a * b and b * a:
func * <UnitType> (measurement: MyMeasurement<UnitType>, scalar: Double) -> MyMeasurement<UnitType> {
var result = measurement
result.value *= scalar
return result
}
func * <UnitType> (scalar: Double, measurement: MyMeasurement<UnitType>) -> MyMeasurement<UnitType> {
return measurement * scalar
}
threeKilometers * 2
// → 6.0 km
let twoSeconds: MyMeasurement<Seconds> = 2
60 * twoSeconds
// → 120.0 s
Multiplication and division (i.e. physics)
If you remember part 2 of this series, my original goal was to model how unit families are related to each other, e.g. speed = length / duration or energy = power × time. To do this, I introduced a protocol named UnitProduct, and unit families could express the factors they are composed of by conforming to the protocol and naming their factors as associated types.
Let’s do the same here, but now we are going to express relationships directly between units, not unit families. The Product protocol looks very similar:
/// Describes this relation between units:
/// Product = Factor1 * Factor2
protocol Product: MyUnit {
associatedtype Factor1: MyUnit
associatedtype Factor2: MyUnit
}
Note that a single protocol is sufficient to describe both multiplicative and fractional relations because a = b × c is equivalent to b = a / c. The choice is arbitrary, and whatever you choose makes expressing some relations feel less natural. For example, if we want to express speed = length / duration, we have to rewrite it first as length = speed × duration.
The next step is to implement the actual computations, i.e. overloads for the multiplication and division operators that work on types conforming to our protocol. We need four variants:
a = b × c
The generic constraints make this quite complicated. For any type Result that conforms to Product, this overload defines the multiplication of any two measurements whose units Unit1 and Unit2 have the same families as the units specified in Result.Factor1 and Result.Factor2. The result is computed by converting the measurements to Result.Factor1 and Result.Factor2, respectively, and multiplying those.
func * <Unit1, Unit2, Result> (lhs: MyMeasurement<Unit1>, rhs: MyMeasurement<Unit2>) -> MyMeasurement<Result>
where Result: Product, Result.Factor1.Family == Unit1.Family, Result.Factor2.Family == Unit2.Family
{
let left = lhs.converted(to: Result.Factor1.self)
let right = rhs.converted(to: Result.Factor2.self)
return MyMeasurement(left.value * right.value)
}
a = c × b
func * <Unit1, Unit2, Result> (lhs: MyMeasurement<Unit2>, rhs: MyMeasurement<Unit1>) -> MyMeasurement<Result>
where Result: Product, Result.Factor1.Family == Unit1.Family, Result.Factor2.Family == Unit2.Family
{
return rhs * lhs
}
This is exactly the same as the previous function, with lhs and rhs reversed. The implementation simply forwards to the other overload.
b = a / c and c = a / b
func / <Unit1, Unit2, Result> (lhs: MyMeasurement<Result>, rhs: MyMeasurement<Unit2>) -> MyMeasurement<Unit1>
where Result: Product, Result.Factor1.Family == Unit1.Family, Result.Factor2.Family == Unit2.Family
{
let right = rhs.converted(to: Result.Factor2.self)
return MyMeasurement(lhs.value / right.value)
}
func / <Unit1, Unit2, Result> (lhs: MyMeasurement<Result>, rhs: MyMeasurement<Unit1>) -> MyMeasurement<Unit2>
where Result: Product, Result.Factor1.Family == Unit1.Family, Result.Factor2.Family == Unit2.Family
{
let right = rhs.converted(to: Result.Factor1.self)
return MyMeasurement(lhs.value / right.value)
}
Again, these follow the same ideas, only the placement of the generic parameters varies.
Concrete implementation
Now it is finally possible to express the relation length = speed × duration (i.e. speed = length / duration):
extension Meters: Product {
typealias Factor1 = MetersPerSecond
typealias Factor2 = Seconds
}
And it can be used like this:
let tenMeters: MyMeasurement<Meters> = 10
let fourSeconds: MyMeasurement<Seconds> = 4
let speed: MyMeasurement<MetersPerSecond> = tenMeters / fourSeconds
// → 2.5 m/s
let thirtyKilometersPerHour: MyMeasurement<KilometersPerHour> = 30
let twoHours: MyMeasurement<Hours> = 2
let tripLength: MyMeasurement<Meters> = thirtyKilometersPerHour * twoHours
// → 60000.0 m
tripLength.converted(to: Kilometers.self)
// → 60.0 km
It works quite well, but two drawbacks are apparent. First, the compiler cannot infer the return types of the computations automatically at the moment. I don’t know if improvements to the compiler can solve this in the future or if I could provide more help by specifying better generic constraints to the functions. I experimented with this a little bit, but could not make it work.
Second, while the arguments’ units need only have the correct family, the unit of the return type is currently limited to the specific unit used in the Product protocol. So something like let tripLength: MyMeasurement<Kilometers> = ... would not work, you have to take the result in Meters first and then convert it. I consider this a pretty big limitation.
Conclusion
Regardless of the (very real) flaws of this design, note that not a single line of executable code is needed to add this mathematical relation to the type system! Simply by adding the protocol conformance (which only involves defining two associated types), we literally added the proposition 1 meter = 1 m/s × 1 s to the compiler’s pool of “truth”. And if you wanted to add another relation (such as 1 J = 1 W × 1 s), adding another protocol conformance is all that’s required.
I find this fascinating.
Nonetheless, I do not think this API based on phantom types is superior to the one in Foundation. It simply makes more sense to parameterize measurements based on unit families rather than units.