NEW: Subscribe to Hacking with Swift+ and accelerate your learning! >>

< Back to Hacking with Swift+

How to use phantom types in Swift

Phantom types are a powerful way to give the Swift compiler extra information about our code so that it can stop us from making mistakes. In this article I’m going to explain how they work and why you’d want them, as well as providing lots of hands-on examples you can try.

Watch the video here, or read the article below

What are phantom types?

The basic definition of a phantom type is this: a type that doesn’t use at least one of its generic type parameters. That’s it – it’s not very complicated, at least when looking at the code.

So, this is a phantom type:

struct Employee<Role>: Equatable {
    var name: String
}

That is generic over some sort of Role, but Role doesn’t appear in the type’s definition – there’s only that one string.

In comparison, here is one of Apple’s Foundation APIs, slightly simplified:

struct Measurement<UnitType> {
    let unit: UnitType
    var value: Double
}

That is not a phantom type, no matter what you might hear elsewhere – it is generic over UnitType but that parameter is used right there for unit, so this is just a regular generic type.

So, the definition of a phantom type is simple, but the real question here is this: why the heck would you want to specify a generic parameter and never use it?

What’s the point?

Our trivial phantom type was this:

struct Employee<Role>: Equatable {
    var name: String
}

That doesn’t use Role at all, so we could just have used this instead:

struct Employee: Equatable {
    var name: String
}

However, there’s an important difference: although we don’t use the generic parameter, Swift does. This allows Swift to enforce rules for us much more strictly.

For example, if you work for a software company you might have employees who work in a coding team and other employees who work in a sales team. We can represent them with no-case enums like these:

enum Sales { }
enum Programmer { }

Tip: It’s a good idea to use a no-case enum rather than a struct, because the enum cannot be instantiated, whereas someone could create an instance of the struct and wonder what it’s good for.

Now, if you had a friend called Zoe who worked in the coding team, she might look like this:

let zoe1 = Employee<Programmer>(name: "Zoe")

And if you had another friend called Zoe who worked in the sales team, she might look like this:

let zoe2 = Employee<Sales>(name: "Zoe")

Now, we made Employee conform to Equatable, and because its single property already conforms to Equatable Swift will be able to synthesize an == function to let us compare two employees. So, we can check whether our two employees are actually the same person like this:

print(zoe1 == zoe2)

Except that won’t work – we aren’t comparing two instances of Employee any more, we’re comparing an Employee<Programmer> and an Employee<Sales>, and Swift considers them to be different. In comparison, if we had made someone’s role a string property, Swift would say that the two Zoe’s are different at runtime, but it wouldn’t stop us from compiling.

That’s the power of phantom types: we give Swift extra information that clarify how things should work, and allow it to work harder on our behalf. When done well, this will allow logic errors to be surfaced as compiler errors: Swift literally won’t build our code because what we’re trying to do doesn’t make sense.

Hands-on examples

If you were working in a hospital that analyzes blood samples, you might start by defining some of the different blood types:

enum OPositive { }
enum APositive { }
enum BPositive { }

Now you can create a BloodSample struct that is generic over some sort of blood type, like this:

struct BloodSample<Type> {
    let amount: Double

    static func +(lhs: BloodSample, rhs: BloodSample) -> BloodSample {
        BloodSample(amount: lhs.amount + rhs.amount)
    }
}

That has a + operator that lets us combine two blood samples, but Swift will automatically understand that two samples from different blood types are different and stop us from mixing them by accident.

So, this code will work:

let sample1 = BloodSample<OPositive>(amount: 5)
let sample2 = BloodSample<APositive>(amount: 5)
let sample3 = BloodSample<OPositive>(amount: 7)

let combined1 = sample1 + sample3

But this will not:

let combined2 = sample1 + sample2

Sometimes the differences between types are less subtle. For example, consider a user struct like this one:

struct User {
    let id: Int
    let age: Int
}

Both id and age are integers, so there’s nothing stopping us from comparing them like this

let user = User(id: 53, age: 53)
print(user.id == user.age)

I mean, yes, the two integers are identical, but if you’re comparing user IDs to ages then it’s almost certainly a mistake – and it’s a mistake phantom types can help us catch.

First, we make no-case enums to represent out variations:

enum UserID { }
enum Age { }

Next, we create a struct that is generic over some kind of type, but doesn’t actually use that type in its definition:

struct Tag<Type>: Equatable {
    var value: Int
}

Now we can modify the User struct so that each of its properties use Tag, like this:

struct User {
    let id: Tag<UserID>
    let age: Tag<Age>

    init(id: Int, age: Int) {
        self.id = Tag(value: id)
        self.age = Tag(value: age)
    }
}

And now trying to compare id and age simply won’t work.

In practice, I’d prefer to change that a little so that Tag conformed to the ExpressibleByIntegerLiteral protocol like this:

struct Tag<Type>: Equatable, ExpressibleByIntegerLiteral {
    init(integerLiteral value: Int) {
        self.value = value
    }

    var value: Int
}

That allows Swift to make instances of Tag directly from an integer, so we can simplify all the types that use Tag so they rely on Swift’s synthesized memberwise initializer:

struct User {
    let id: Tag<UserID>
    let age: Tag<Age>
}

For a broader solution to this same problem, see my article Improving your Swift code using value objects.

The most important thing to remember is that although our phantom types are empty, the Swift compiler is fully aware of them. So, you can use them as constraints in extensions and more – they aren’t special.

Building a state machine

There are lots of practical ways you can use phantom types to build interesting stuff, and I came across one fascinating experiment from Soroush Khanlou. In his example, Soroush uses phantom types to build a state machine where invalid transitions can’t compile – Swift won’t allow it.

Tip: State machines are pieces of code that are designed to move between a series of predefined states. For example, a vending machine might move between the states “waiting for customer”, “coin inserted”, “fetching selection” and “serving selection”. It wouldn’t make sense for the vending machine to go from “waiting for customer” to “serving selection”, because no coin was inserted.

Soroush very kindly gave me permission to use his code here, although I’m going to simplify a little so we can focus on the part that matters.

First, we create the various states our machine can be in. For this example we’ll have have the four that represent a vending machine:

enum Waiting {}
enum CoinInserted {}
enum Fetching {}
enum Serving {}

Second, we create a phantom type to store a transition between two states:

struct Transition<From, To> {}

Neither of those types are used – the struct is literally empty. But that’s okay, because Swift is still able to track them.

Third, we’ll create a Machine struct that represents our state machine in one given state. This has one method that will transition from the current state to a new state, like this:

struct Machine<State> {
    func transition<To>(with transition: Transition<State, To>) -> Machine<To> {
        .init()
    }
}

That’s doing a lot of work in hardly any code, so let’s break it down:

  • The Machine struct is generic over some kind of State.
  • The transition() method is generic over some kind of To, but also relies on the State generic parameter from Machine.
  • We’re telling Swift the transition must be from the current state of our machine, and to some other kind of state.
  • The function returns a new machine that uses the new To state.
  • Using .init() will automatically make a new Machine struct of the correct type: Machine<To>.

Now we can go ahead and create all valid transitions by specifying where they come from and where they go to, like this:

let start = Transition<Waiting, CoinInserted>()
let selectionMade = Transition<CoinInserted, Fetching>()
let delivery = Transition<Fetching, Serving>()
let reset = Transition<Serving, Waiting>()

And that’s it! We can now create a Machine with a particular state, and step it through any other possible valid state, like this:

let m1 = Machine<Waiting>()
let m2 = m1.transition(with: start)
let m3 = m2.transition(with: selectionMade)
let m4 = m3.transition(with: delivery)
let m5 = m4.transition(with: reset)

The magic here is that Swift will check all those transitions at compile time – it’s not possible to make an illegal transition.

For example, this won’t compile:

let m6 = m5.transition(with: delivery)

The problem is that m5 is a Machine<Waiting>, so we can’t go straight from there to a Machine<Serving>.

I think this is a fantastic experiment, because it shows how we can leverage the Swift compiler to prove that our code is correct. Plus, it makes for a fascinating exploration of phantom types in action.

However, in practice this solution doesn’t work so well. To explain why, I asked Soroush himself – here’s what he said:

“I originally wrote this as an experiment to see if I could have the compiler protect me from performing invalid transitions on a state machine, but I quickly realized that changes to the state would cause the type of the entire machine to change, meaning that it couldn’t be stored back into the same variable. This prevents you from having it as a property on, say, a view controller, with transitions modifying the state machine. So: fun to try out, a little impractical in actual usage.”

Undefined as a type

Before I finish, there’s one more technique I want to demonstrate, and it’s quite different from all the earlier examples. It’s this piece of code:

func undefined<T>(_ message: String = "") -> T {
    fatalError("Undefined: \(message)")
}

That isn’t a phantom type, but it is a great example of using Swift’s type system in interesting ways. I first saw this being used by Johannes Weiss from the SwiftNIO team, where he presented this as a useful global function to have around while you’re still building your app.

This function, undefined<T>(), can act as pretty much any other kind of value you want, because it is generic over T and promises to return a T. It won’t actually return a T, but it doesn’t need to: calling fatalError() is enough to see that nothing needs to be returned.

This set up it can act as a placeholder to make your code compile when you’re part-way through your work and don’t want to fill in all the various parts just yet.

You can make simple instances of types using undefined(), like this:

let name: String = undefined("Example string")
let score: Int = undefined("Example int")

You can make it act as a placeholder inside a function you haven’t written yet:

func userID(for username: String) -> Int? {
    undefined(username)
}

In that instance you could use fatalError() to mark the missing code, but then again fatalError() does have legitimate uses outside of marking unfinished work so it becomes harder to find and replace later.

And you can even use it repeatedly when there are lots of parameters you haven’t filled in yet:

let timer = Timer(timeInterval: undefined(), target: undefined(), selector: undefined(), userInfo: undefined(), repeats: undefined())

Obviously many of these places could be replaced with hard-coded placeholders, such as 0 or an empty string, but the magic of undefined() is that it will crash as soon as it’s touched – it will work only at compile time, to help you move your project forward, but can’t possibly work at runtime. Also, it’s easier to search your code for “undefined” than some magic value!

Of course, you might have the question “if undefined<T>() isn’t a phantom type, what is it?” And to be honest I had exactly the same question, so I went back to the source and asked Johannes. Here’s what he said:

I wouldn't call undefined<T>() a phantom type because first of all, really it's a value. Well, a value that we'll never generate, but still. Even calling T a phantom type isn't quite right: T can be anything, so it could be a String which is far from a phantom type. I think the closest somewhat correct term I have for this is that it's called the "bottom value", usually written like ⏊, and even that is probably not right because the "bottom type" is defined as not having values! So the term "bottom value" isn't great either, but I guess we could say "undefined's return type is bottom"?

I love that answer, because it shows just how nuanced the discussion is.

Anyway, that finishes up our discussion about phantom types. You’ve seen how they work and I’ve given you some hands-on examples, plus I’ve walked you through how we can build state machines using them as an interesting experiment, and even how we can create simple placeholder functions that can act as helpers to make our code compile while we’re still working. They might not be phantom types, but they are still fascinating!

Further reading

Phantom types are a fascinating area of discussion, and there’s a lot of high-quality material I recommend you check out.

First, Johannes Weiss delivered the talk that originally introduced to me to phantom types in Swift: The Type System is Your Friend. He also introduced the undefined() function there, although I recommend you check out his repository on GitHub because it’s a little more advanced.

Second, Brandon Case delivered a talk called Strings Are Evil, where he builds a file-handling system where phantom types make it impossible to created badly-formed file paths.

Third, if the idea of tagged integers interested you, you might want to check out the Tagged repository on GitHub, which takes the concept significantly further. As an alternative, you should check out my article Improving your Swift code using value objects.

Fourth, I walked you through a simplified version of Soroush Khanlou’s state machine, but if you’d like to read the full version it’s in this GitHub Gist

Finally, Ole Begemann walks through what it would look like to rewrite Apple’s Measurement API using phantom types in this article: Measurements and Units with Phantom Types

Challenges

If you’d like to take your knowledge of phantom types further, try creating phantom types to solve these problems:

  1. A Temperature type that is generic over whether it uses Celsius or Fahrenheit.
  2. A Car type that is generic over whether it uses diesel or gas for the engine.

I also have a question that I’d like you to consider: what benefits of phantom types could we gain by using a class hierarchy instead? Just as importantly, what benefits would we lose?

If you liked this, you'd love Hacking with Swift+…

Here's just a sample of the other tutorials, with each one coming as an article to read and as a 4K Ultra HD video.

Find out more and subscribe here


Creating a WaveView to draw smooth waveforms
CUSTOM SWIFTUI COMPONENTS

FREE: Creating a WaveView to draw smooth waveforms

In this article I’m going to walk you through building a WaveView with SwiftUI, allowing us to create beautiful waveform-like effects to bring your user interface to life.

Using memoization to speed up slow functions
HIGH-PERFORMANCE APPS

FREE: Using memoization to speed up slow functions

In this article you’ll learn how memoization can dramatically boost the performance of slow functions, and how easy Swift makes it thanks to its generics and closures.

Understanding generics – part 1
INTERMEDIATE SWIFT

Understanding generics – part 1

Generics are one of the most powerful features of Swift, allowing us to write code once and reuse it in many ways. In this article we’ll explore how they work, why adding constraints actually helps us write more code, and how generics help solve one of the biggest problems in Swift.

Uploading Codable data
NETWORKING

Uploading Codable data

In a previous article we already looked at a great way to download data using Combine, but in this article we’re going to examine the other side of the problem: uploading Codable data. Apple’s API here is a little gnarly, so I’m going to show you how to wrap it in a neat container using generics and Result.

Creating a particle system in SwiftUI
SWIFTUI SPECIAL EFFECTS

Creating a particle system in SwiftUI

Particle systems let us create special effects such as confetti, fire, smoke, rain, and snow, all by adjusting a range of inputs. In this article we’re going to build our own particle system entirely driven by SwiftUI, so you can easily add some sparkle to your apps.

Remaking the Tips app
REMAKING APPS

Remaking the Tips app

In this article we’re going to look at how to rebuild the Tips app using SwiftUI, including how to make scrolling tabs of content, how to get a parallax scrolling effect, and more.

Customizing ProgressView using ProgressViewStyle
INTERMEDIATE SWIFTUI

Customizing ProgressView using ProgressViewStyle

SwiftUI’s ProgressView gives us control over showing determinate or indeterminate progress, but it’s a bit dull – just a thin line and an activity spinner. Fortunately, we also get the ProgressViewStyle protocol so we can build entirely custom progress views, and in this article I’ll show you how it’s done.

Creating a LongPressButton to trigger after delay
CUSTOM SWIFTUI COMPONENTS

Creating a LongPressButton to trigger after delay

In this article I’m going to walk you through building a LongPressButton with SwiftUI, which will requires users to press and hold for a second before it’s triggered.

Creating a FlipView to provide a card flip effect
CUSTOM SWIFTUI COMPONENTS

Creating a FlipView to provide a card flip effect

If you’re looking for a simple and fun special effect to add to your code, I’ve got just the thing for you. In this article I’m going to walk you through building a FlipView with SwiftUI, which will encapsulate how to move between a front view and a back view using a 3D flip animation.

The pros and cons of operator overloading
ADVANCED SWIFT

The pros and cons of operator overloading

I’ve written about operator overloading previously, not least in my book Pro Swift, but in the article I want to go into more depth on the places where it’s really useful – and the places where it’s not such a good idea.

Controlling views using the accelerometer
SWIFTUI SPECIAL EFFECTS

Controlling views using the accelerometer

Reading device motion and orientation is a fast and slightly magical way to incorporate the real world into your apps, and can do a huge amount to add a little spark of delight to your UI. In this article I’m going to show you how easy it is to control SwiftUI layouts using the accelerometer, and give you a few ideas for special effects.

User-friendly network access
NETWORKING

User-friendly network access

Anyone can write Swift code to fetch network data, but much harder is knowing how to write code to do it respectfully. In this article we’ll look at building a considerate network stack, taking into account the user’s connection, preferences, and more.

Storing preferences efficiently
MAKING THE MOST OF FOUNDATION

Storing preferences efficiently

Apple’s UserDefaults system lets us store small amounts of user data for our app, which might sound simple but it’s deceptively powerful. In this article I’ll show you the correct way to create initial preferences, how to share preferences across applications, how to synchronize data with iCloud, and why this is a case where property wrappers probably aren’t a good solution.

Making the most of optionals
ADVANCED SWIFT

Making the most of optionals

Swift’s optionals are implemented as simple enums, with just a little compiler magic sprinkled around as syntactic sugar. However, they do much more than people realize, and in this article I’m going to demonstrate some of their power features that can really help you write better code – and blow your mind along the way.

Using dates safely and effectively
MAKING THE MOST OF FOUNDATION

Using dates safely and effectively

Working with dates in software is hard, and if you don’t understand why then think about time zones, think about leap years, or think about how it’s the year 2563 in the Thai calendar. Apple gives us many tools for making them easier but they can be hard to discover, so in this article I’m going to try to provide some clear guidance for what to use and when.

Customizing Toggle using ToggleStyle
INTERMEDIATE SWIFTUI

Customizing Toggle using ToggleStyle

Most of the time the built-in iOS controls are great, but sometimes you want something just a little different. In this article I’m going to walk you through how you can take complete control over the way toggle switches work in SwiftUI, providing custom rendering and interactions.

Creating a FilteringList to filter a list using text input
CUSTOM SWIFTUI COMPONENTS

Creating a FilteringList to filter a list using text input

Many apps show lots of data in a list, and allow users to filter that list by typing in a text view. In this article we’re going to build that in SwiftUI, then pull it out into a reusable component you can apply anywhere.

Existentials and type erasure – part 2
ADVANCED SWIFT

Existentials and type erasure – part 2

In the first part of this tutorial we looked at the underlying problem that type erasure is trying to solve, and tried out Swift’s approach using AnySequence. In this second part we’re going to adapt Swift’s own solution to get real type erasure for our own code.

Creating a ShapeView to render UIBezierPaths
CUSTOM SWIFTUI COMPONENTS

Creating a ShapeView to render UIBezierPaths

Bezier paths let us draw all sorts of shapes efficiently and smoothly, and with a little work we can bring them into SwiftUI then animate them smooth, and in this article I’m going to walk you through making a very simple ShapeView struct to do just that.

Finding and fixing slow rendering
HIGH-PERFORMANCE APPS

Finding and fixing slow rendering

Instruments is a powerful tool for identifying performance problems, but in this article I’ll show you how to find code that slows down rendering in your app, causing slow scrolling, wasted CPU time, and more – all through the simulator.

Link copied to your pasteboard.