Articles

When and How to Use the Equatable and Identifiable Protocols in Swift

December 13, 2021

This article describes the Equatable and Identifiable protocols, and how they can enable Swift programmers to build domain models largely, if not entirely, using value types. While Equatable facilitates using value types not only to model simple values but also to create composite values rich in the language and functionality of the domain, Identifiable makes it possible to use value types to model domain entities with a stable identity. By choosing an appropriate identifier to use with the Identifiable protocol, the duration and scope of the identity can be controlled according to the requirements of the application.

The Equatable protocol
When to conform to Equatable
Modeling values using Swift value types
The Identifiable protocol
When to conform to Identifiable
Modeling entities with identity using Swift value types
Conclusion

The Equatable protocol

The Equatable protocol enables comparison of instances of the same type for value equality. Instances of a type that conforms to Equatable can be compared for value equality using the == operator, and for value inequality using the != operator. Most basic types in the standard library conform to Equatable and a number of other types rely on Equatable conformance. For instance, the contains(_:) method in the Sequence protocol, which returns true if the sequence contains the given element and false otherwise, is available only if elements of the sequence conform to Equatable. Similarly, the firstIndex(of:) method of the Array type is only available if elements of the array conform to Equatable.

The Equatable protocol has the following requirements:

static func ==(Self, Self) -> Bool
static func !=(Self, Self) -> Bool

In practice, only an implementation of the == operator needs to be provided since the standard library contains an implementation of the != operator for Equatable types, which negates the result of the == operator. Things are made even easier for structs and enums, which are the main value types in Swift. Enums without associated values automatically conform to Equatable. Structs, and enums with associated values, can opt in to automatic synthesis of Equatable conformance, provided:

For structs, all stored properties are of types that conform to Equatable, and Equatable conformance is declared in the original definition of the struct or in an extension in the same file
For enums with associated values, all associated values are of types that conform to Equatable, and Equatable conformance is declared in the original definition of the enum or in an extension in the same file

If a struct or enum does not meet the above requirements, or it is considered desirable to customize the Equatable conformance for some reason, an implementation of the == operator must be provided when declaring Equatable conformance.

Given below is an example of a simple type representing a box, implemented as a struct, which gets Equatable conformance just by declaring it in the definition of the struct.

struct Box: Equatable {
    var length: Double
    var width: Double
    var height: Double
}

let box = Box(length: 10, width: 10, height: 5)
let otherBox = Box(length: 10, width: 8, height: 7)

print(box == otherBox)  // false
print(box != otherBox)  // true

Here is a simple enum example, where there is no need to explicitly declare Equatable conformance since there are no associated values.

enum Direction {
    case north, south, east, west
}

let direction = Direction.north
let otherDirection = Direction.east

print(direction == otherDirection)  // false
print(direction != otherDirection)  // true

Now consider the following struct that models a point in a two-dimensional plane.

struct Point {
    var x: Double
    var y: Double
}

It is natural to expect to be able to compare points for equality using their x and y coordinates. Unfortunately, instances of the Point type, as defined above, cannot be used with the == or != operators even though both the stored properties are of the Double type, which is Equatable, because Equatable conformance was not declared in the definition of the Point struct. This can easily be remedied by modifying the original definition of Point to opt in to automatic synthesis of Equatable conformance. Alternatively, an extension can be used to opt in to automatic synthesis of Equatable conformance, provided the extension is in the same file as the original type definition.

// Extension in the same file as the original struct
extension Point: Equatable {}

If the two options presented above are not available, Equatable conformance may still be added through an extension in a separate file by providing an implementation of the == operator required by the Equatable protocol. However, when declaring Equatable conformance through an extension in a separate file, access levels assigned to the type’s members needs to be considered. Any private or fileprivate members cannot be accessed by an extension in a separate file. Members with the internal access level, which is the default access level in Swift, cannot be accessed by an extension in a file not in the same module as the original type definition.

The extension shown below can, therefore, be in a separate file provided the file is in the same module as the original struct, since both the stored properties of Point have the default internal access level.

// Extension in a separate file in the same module as the original struct
extension Point: Equatable {
    static func ==(lhs: Point, rhs: Point) -> Bool {
        lhs.x == rhs.x && lhs.y == rhs.y
    }
}

It is noteworthy that classes do not benefit from automatically synthesized Equatable conformance and, if a class type is to be made Equatable, the conformance must always be manually implemented. This is because classes are reference types, with each instance having an identity unrelated to the value of its attributes. Therefore, it is up to the designer of a class to decide why Equatable conformance is desirable for a certain type implemented using a class and how best to implement Equatable conformance in this context.

When to conform to Equatable

All types that model values should conform to the Equatable protocol. The most common values we know from everyday experience are numbers. But there are many other values in the domains programmers work with and it is important to be able to identify such values so they can modeled appropriately.

Listed below are some defining characteristics of values:

Lack of identity: A value does not have inherent identity and is defined only by the values of its attributes.
Attribute-based equality: Any two values of the same type whose corresponding attributes are equal are considered equal.
Substitutability: Any value can be freely substituted for another value provided the two are equal , i.e., they are of the same type and their corresponding attributes are equal.
Immutability: Once created, a value cannot be changed. An operation on a value may produce a new value of the same type, which if saved in the same variable where the original value was saved, can create an illusion of mutability. A value saved in a constant (declared using the let keyword in Swift) thus provides a guarantee of immutability of its attributes.

Let’s look at the Box type we had defined earlier and see if it passes all the above tests. An instance of the Box type is defined only in terms of its dimensions (length, width and height) and has no identity independent of these attributes. Any two Box instances that have the same dimensions (attributes) are considered equal. When we need a Box instance, we can use any instance with the required dimensions. It follows that any Box instance can be substituted for another provided the corresponding dimensions (attributes) of the two instances are equal.

The concept of immutability of values can sometimes be confusing in Swift. It may seem at first that a Box instance is mutable as it has var properties. This is not true, however. Whenever we modify any property of a given Box instance, under the hood, Swift creates a new instance with the new property values and replaces the original instance with the new instance, creating the aforementioned illusion of mutability (this also happens when we call a mutating method on an instance of a struct or enum).

A Box instance assigned to a constant, therefore, provides a guarantee of immutability of its stored properties, as it is not possible to assign a new value to constant, as shown below.

let myBox = Box(length: 20, width: 10, height: 5)
myBox.length = 10
// Error: Cannot assign to property: 'myBox' is a 'let' constant

Modeling values using Swift value types

Swift comes with a rich complement of value and reference types. Classes and closures are reference types while structs, enums and tuples are value types. Structs and classes are the most commonly used value and reference types respectively. Swift structs are particularly powerful, with the ability to define properties and methods, specify initializers, and conform to protocols. Combining structs and protocols enables abstraction and polymorphism without the need for inheritance.

Once we identify the values in our domain, we can model them using Swift value types, usually structs. This solves a major challenge faced by object-oriented programmers of having to use classes, which are reference types, to model values. Using classes where they are not fit for purpose not only makes the code unnecessarily inefficient but also creates potential for various types of logic errors and makes parts of the code harder to reason about.

Correctly identifying the values in a domain and modeling them using value types leads to the following advantages:

Value types make a program more efficient because instances of value types are easy to create, copy and destroy, without the overhead of heap memory allocation and reference counting that comes with creating and managing instances of reference types
Code dealing with value types is more predictable and easier to reason about because value types provide strong guarantees about mutability, leading to more fine-grained control over how certain parts of the code will behave
Using value types makes it easier to write multi-threaded code, without the need for complex synchronization mechanisms, because a thread can use a value type instance without worrying about the possibility of another thread mutating its state
Since value types have no references, they eliminate the possibility of memory leaks caused by strong reference cycles
Code written using value types is generally more easily testable as all we usually need to do is to create a new value with the expected attributes and test it for equality against the value produced by the program, reducing the need for elaborate setup code and mocking frameworks

The Equatable protocol plays an important role in facilitating the use of value types to model values by ensuring that we can compare instances of the same type for equality based on the values of their attributes. This is why Swift makes it so easy to make structs and enums conform to Equatable, by automatically synthesizing this conformance in most cases.

The Identifiable protocol

The Identifable protocol is for use with any type that needs to have a stable notion of identity. It is declared as follows.

protocol Identifiable {
    associatedtype ID : Hashable
    var id: ID { get }
}

The only requirement of the protocol is that conforming types have a property called id. The protocol leaves it to conforming types to decide what type they want to use for the id property, provided it conforms to the Hashable protocol. This gives flexibility to conforming types to decide whether to use a domain-specific unique identifier or to create a unique identifier within the application with an appropriate duration and scope of the identity.

When to conform to Identifiable

Real-world domains contain not only values but also entities that have a stable identity independent of the values of their attributes. Values are easily dealt with using Swift value types and Equatable conformance. This approach does not work, however, for entities in the domain where we need to preserve their identity. Traditionally, classes have been used to model such entities, which meant having to live with all the issues related to using reference types. With the introduction of the Identifiable protocol, however, Swift value types can be used to model entities with identity. Identifiable conformance is helpful not only in marking out such types but also in providing a uniform manner in which instances of conforming types can be compared using their unique identifiers.

Many domains have existing ways to uniquely identify instances of entities that are suitable for the purposes of the domain model, with identifiers such as part number, product code, customer code, bank account number, etc. In such cases, we can usually use the appropriate domain-specific identifier, stored as a string, as shown below.

struct Part: Identifiable {
    let id: String
    var description: String
}

var part = Part(id: "101C", description: "Bolt, steel, 3.0cm")

In the absence of an existing system of unique identifiers for an entity, we need to create unique identifiers within the application. One simple way to do this is to use integers as identifiers, making the integers auto-incrementing to make them unique.

struct Employee: Identifiable {
    private static var nextID = 0
    
    let id: Int
    var name: String
    
    init(name: String) {
        Employee.nextID += 1
        id = Employee.nextID
        self.name = name
    }
}

var firstEmployee = Employee(name: "Jane Smith")
var secondEmployee = Employee(name: "Oliver Jones")

print(firstEmployee.id)     // 1
print(secondEmployee.id)    // 2

While this approach can work for simple cases, for a single launch or even across launches where a persistent data store is used to coordinate identifiers between launches, it does not scale well, in particular when uniqueness is required across devices or by threads running concurrently.

Swift includes a solution for this out of the box with the UUID type, which provides universally unique identifiers. There are two ways to use the UUID type when conforming to the Identifiable protocol. We can directly use UUID as the type of the id property, or we can use the uuidString property of the UUID type to generate a unique string identifier, in which case the id property would be of the String type, as shown below.

let id = UUID().uuidString

Shown below is the Employee type rewritten with UUID as the type of the id property.

struct Employee: Identifiable {
    let id = UUID()
    var name: String
}

var firstEmployee = Employee(name: "Jane Smith")
var secondEmployee = Employee(name: "Oliver Jones")

print(firstEmployee.id)     // 264FE82B-012B-4CEB-A2F8-D06EF94588E2
print(secondEmployee.id)    // 1A82D5E0-9F6C-4ADD-9889-BE3C616F64AD

Modeling entities with identity using Swift value types

Armed with the Identifiable protocol, we can use value types to model domain entities with a stable identity, getting all the benefits associated with value types mentioned earlier in this article. This significantly reduces, even eliminates in many cases, the need to use classes in the domain model. Consider a case where we need to model a student. To keep the example simple, we assume we just need to store a unique enrolment number, name, and GPA (Grade Point Average) for each student.

For purposes of illustration, let us first see how we run into issues if we attempt to model a student using a struct conforming to Equatable.

struct Student: Equatable {
    let enrolmentNumber: String
    var name: String
    var gpa: Double
}

We create an array containing two instances of the above type.

var students = [
    Student(enrolmentNumber: "1001", name: "Alice Cooper", gpa: 3.2),
    Student(enrolmentNumber: "1002", name: "James Smith", gpa: 3.0)]

Let’s say, on a periodic basis, we need to update the GPAs of certain students, and this is done by copying the student records from a central data repository, modifying the copied records as required, and then replacing the updated records in the repository. To demonstrate this for one student, we copy the second element of the array to a new variable, and change its gpa property.

var student = students[1]
student.gpa = 2.8

We then attempt to use the following code to find the relevant element in the students array and replace it with the value in the student variable.

if let index = students.firstIndex(of: student) {
    students[index] = student
    print("Record updated")
} else {
    print("Record not found")
}
// Record not found

print(students[1].gpa)  // 3.0

This clearly does not work. Since the Student struct we have used conforms to Equatable, each Student instance is defined only by its attributes. The moment we change the value of the gpa property, the new instance can no longer be related to the original instance because the firstIndex(of:) method will only find a matching element in the array if the values of all stored properties are equal. This is why we get a message that no matching record was found in the array. To confirm this, when we print the gpa property of the second element of the array, we find that the value has not been updated.

The same thing happens if we try to check whether the array contains a record for this student. Since the contains(_:) method also uses value-based equality to try and find a matching element in the array, we see that the student instance we modified could not be found in the array.

print(students.contains(student))   // false

The issue is that student is an entity with identity and should not be modeled using a struct conforming to Equatable. We, therefore, modify the Student type to make it conform to the Identifiable protocol. Since each student can be uniquely identified by their enrolment number, we use it as the identifier required by Identifiable.

struct Student: Identifiable {
    let id: String                 // Enrolment number
    var name: String
    var gpa: Double
}

As we had done before, we create an array containing two instances of the above type.

var students = [
    Student(id: "1001", name: "Alice Cooper", gpa: 3.2),
    Student(id: "1002", name: "James Smith", gpa: 3.0)]

Continuing to follow what we had done in our original example, we copy the second element of the array to a new variable, and update the gpa property of the copied instance.

var student = students[1]
student.gpa = 2.8

Now that Student is no longer Equatable, we can’t use the firstIndex(of:) method on the students array. With Identifiable conformance, however, we know that we can use the id property to find matching elements in the array. To do this, we invoke the firstIndex(where:) method on students, using the closure to compare the values of the id property to find a matching element. We rewrite the code to find the correct element in the array, and replace it with the updated value.

if let index = (students.firstIndex() { $0.id == student.id }) {
    students[index] = student
    print("Record updated")
} else {
    print("Record not found")
}
// Record updated

print(students[1].gpa)  // 2.8

This time we get a message that a matching record was found and updated. When we print the gpa value of the second element of the array, we see that the value is as expected.

Since we know that the students array contains elements that conform to Identifiable, we don’t need to perform the id comparison each time we have to find an index at which an element with a given id value may exist. Instead, we can rely on the assurance that every type conforming to Identifiable must have an id property, which conforms to Hashable so must be Equatable. Accordingly, we create an extension to Array to add a firstIndex(of:) method available only when elements of the array conform to Identifiable, which uses an equality check on the id property to find the index of the first matching element, if one exists.

extension Array where Element: Identifiable {
    func firstIndex(of element: Element) -> Int? {
        firstIndex() { $0.id == element.id }
    }
}

We can now rewrite the code we wrote earlier to use the above method, which makes it simpler and more intuitive.

if let index = students.firstIndex(of: student) {
    students[index] = student
    print("Record updated")
} else {
    print("Record not found")
}
// Record updated

print(students[1].gpa)  // 2.8

Similarly, we can create the following extension to the Sequence protocol, which is available only when elements of the sequence conform to Identifiable. This extension defines a contains(_:) method that checks if the sequence contains an element using an equality comparison on the values of the id property.

extension Sequence where Element: Identifiable {
    func contains(_ element: Element) -> Bool {
        contains() { $0.id == element.id }
    }
}

Using this method, we can confirm that the students array contains an element with the same id value as the instance assigned to the student variable, in a simpler and more intuitive way.

print(students.contains(student))   // true

Conclusion

Swift value types are ideally suited to modeling values, by conforming to the Equatable protocol. With the introduction of the Identifiable protocol, however, value types in Swift can also be used to model entities with a stable identity, while controlling the duration and scope of the identity according to the needs of the application. This means that domain models can be built largely, or even entirely, without using classes, which facilitates writing code that is more efficient, easier to reason about, simpler to test, and more concurrency-friendly.

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a conversation on Twitter.

The Power of Optional Chaining in Swift

July 26, 2021

This article covers optional chaining, one of the mechanisms built into Swift to enable us to safely work with optionals. Optional chaining can be used to manipulate an optional in a number of ways, including setting and retrieving the value of a property of the wrapped instance, setting and retrieving a value from a subscript on the wrapped instance, and calling a method on the wrapped instance. Optional chains fail gracefully when they do, which is great for working safely with optionals, but it also means that it is important to know what to expect when using optional chains to be able to use them effectively.

What is optional chaining
Uses of optional chaining
1. Setting and retrieving the value of a property of the wrapped instance
2. Setting and retrieving a value from a subscript on the wrapped instance
3. Calling a method on the wrapped instance
Optional chains fail gracefully
1. Failure of an optional chain to retrieve or return a value
2. Failure of an optional chain to call a method that does not return a value
3. Failure of an optional chain to set a value
Optionals wrapping optionals
Conclusion

What is optional chaining

Optional is a special Swift type, instances of which may or may not wrap an instance of a given Swift type. Since an optional is an instance of the Optional type and not an instance of the type wrapped by the optional, we cannot directly use an optional to set or retrieve the value of a property of the wrapped instance, set or retrieve a value from a subscript on the wrapped instance, or call a method on the wrapped instance. One way to do so would be to unwrap the optional, but it is easier and more convenient in many contexts to work directly with the wrapped instance. This is where optional chaining is used, which allows us to use the wrapped instance without having to unwrap the optional.

When creating an optional chain, we use the normal dot syntax and square brackets (in case of subscripts) to set or retrieve values, and call methods. We just insert a question mark (?) immediately after any optional that appears in the chain. This enables us to reach inside the optional and directly use the wrapped instance.

Uses of optional chaining

We can use an optional chain to manipulate the instance wrapped by an optional in a number of ways, which we will demonstrate using a simple example involving people and their pets.

Let’s start by defining a protocol to model pets, with an optional property for the name of the pet, and a method to enable the pet to make its signature sound.

protocol Pet {
    var name: String? { get set }
    func makeSound()
}

Next, we define a class to model cats, which conforms to the Pet protocol.

class Cat: Pet {
    var name: String?
    
    init(named name: String? = nil) {
        self.name = name
    }
    
    func makeSound() {
        print("Meow")
    }
}

Finally, we define a class to model a person.

class Person {
    var name: String
    var pets: [Pet]?
    
    init?(named name: String) {
        guard !name.isEmpty else { return nil }
        self.name = name
    }
}

Note that the pets property in Person is an optional, which means a person may or may not have one or more pets. Moreover, the Person class has a failable initializer, which prevents us from creating a person with an empty string as the name.

We will use the above setup to demonstrate the ways in which optional chaining can be used to manipulate optionals.

1. Setting and retrieving the value of a property of the wrapped instance

Let’s say we want to create a person named James, who has a cat named Bella. The first step is to create the required Person and Cat instances.

let person = Person(named: "James")
let pet = Cat(named: "Bella")

However, if we try to set the value of the pets property of person, we get an error.

person.pets = [pet]
// Error: Value of optional type 'Person?' must be unwrapped to refer to member 'pets' of wrapped base type 'Person'

This is because the initializer of Person is failable, and it gives us an optional wrapping a person, which is not an instance of type Person but rather an instance of type Optional<Person> (or Person?), as we can see below.

print(type(of: person))     // Optional<Person>

We can, however, work directly with the wrapped instance using an optional chain. We can do this quite simply by modifying the above assignment statement, inserting a question mark immediately after the optional.

person?.pets = [pet]

Since an optional chain is just a normal dot syntax chain with the additional question mark after any optional that may be present in the chain, we can make our optional chains as long as required. For instance, if James gets another cat, we can use the following optional chain to add a new cat to the pets property of person.

let newCat = Cat()
person?.pets?.append(newCat)

We can also use an optional chain to retrieve the value of a property of the wrapped instance. Here is how, for instance, we can retrieve the array of pets owned by James.

let personsPets = person?.pets

It is important to note that any value obtained using an optional chain is always an optional. In the above case, we should get an optional array of pets, which has the type Optional<Array<Pet>> (or [Pet]?). We check the type of personsPets to confirm this and also see that, since James has two pets, personsPets does have a wrapped value and so is not equal to nil.

print(type(of: personsPets))    // Optional<Array<Pet>>
print(personsPets == nil)       // false

2. Setting and retrieving a value from a subscript on the wrapped instance

We can use an optional chain to set a value from a subscript on the wrapped instance. Continuing our running example, let’s say James decides to name his second cat. We can do this using an optional chain, as shown below.

person?.pets?[1].name = "Whiskers"

We can also use an optional chain to retrieve a value from a subscript on the wrapped instance. Here is how we retrieve the name we just set.

var petName = person?.pets?[1].name

Since a value retrieved using an optional chain is always an optional, we can confirm that the name of the cat was correctly set, and retrieved, by printing the string wrapped by petName using the nil coalescing operator.

print(petName ?? "No pet name found")   // Whiskers

It is important to note that, when using an optional chain to set or retrieve a value from a subscript on the wrapped instance, the question mark is inserted before the square brackets, as we have done in the above examples. This is because, in an optional chain, a question mark must be placed immediately after the name of any optional in the chain, which would be before the dot in case we are accessing a property or calling a method on the wrapped instance, and before the square brackets in case we are using a subscript on the wrapped instance.

We would place the question mark after the square brackets in an optional chain in cases where the instance on which we are using a subscript to retrieve a value is not an optional, but the value thus retrieved, which we want to use to set or retrieve the value of a property, or call a method, is an optional. A common example of this is using an optional chain to retrieve a value from a non-optional array holding optional values, and set or retrieve the value of a property, or call a method, on the retrieved optional value. To demonstrate this, we create an array of persons, using the Person class we have been using.

let names = ["Sandra", "Kelly", "Jacob"]
let persons = names.map(Person.init)

Since Person has a failable initializer, we get an array of optional persons, which has the type Array<Optional<Person>> (or [Person?]).

print(type(of: persons)) // Array<Optional<Person>>

Let’s say we want to assign a value to the pets property of the first element of this array. In this case, the array we are accessing is non-optional so we don’t need to insert a question mark before the square brackets. However, since the elements of the array are optional, we do need to use a question mark immediately after the square brackets.

let cat = Cat()
persons[0]?.pets = [cat]

To see the difference more clearly, we can use both forms in the same optional chain. Shown below is how we would set a value for the name property of the above cat.

persons[0]?.pets?[0].name = "Fluffy"

For anyone who may be a bit unsure about what is happening in the above optional chain, it may be useful to step through what the optional chain does. First, we use a subscript on the non-optional persons array in the normal manner. This gets us the first element of the array, which is an optional wrapping a Person instance. To access the pets property of the wrapped Person instance, we insert a question mark immediately after the square brackets. The pets property in turn holds an optional wrapping an array of Pet instances. To use a subscript on this wrapped array, we place the question mark before the square brackets, enabling us to get the first element of the array, and set its name property to the desired value.

Just to complete the example, we can use a similar optional chain to retrieve the pet name we have just set. We store the optional string we get from the optional chain in the petName variable we had defined earlier, and use a nil coalescing operator to print it.

petName = persons[0]?.pets?[0].name
print(petName ?? "No pet name found")   // Fluffy

Longer optional chains are great for writing compact code, but they can sometimes hinder readability. It may be useful, therefore, to break up a longer optional chain where appropriate into easily readable chunks, to keep the code clear and intention-revealing.

3. Calling a method on the wrapped instance

We can use an optional chain to call a method on the instance wrapped by an optional. The Pet type we have been using in our running example has a makeSound() method, which prints the pet’s signature sound, as implemented by the conforming class.

Le’s use an optional chain to get the first pet owned by the person we defined earlier to make a sound.

person?.pets?[0].makeSound()    // Meow

Since the person owns two cats, we can get them to meow in unison.

person?.pets?.forEach() { $0.makeSound() }
// Meow
// Meow

We can also use an optional chain to call a method that returns a value. Just as with a value retrieved using an optional chain from a property or a subscript on the wrapped instance, we always get an optional when we use an optional chain to call a method on the wrapped instance, regardless of whether the return value of the method is optional.

Optional chains fail gracefully

Optional chains are one of the major ways in which we can use Swift optionals in a safe manner. This is because an optional chain never tries to force-unwrap an optional. It instead reaches into the optional and checks whether the optional contains a wrapped instance. If a wrapped instance is found, the optional chain uses it for the intended purpose. If, on the other hand, there is no wrapped instance, or in other words nil is encountered, the optional chain fails gracefully, i.e., it does not cause an error. It is noteworthy that an optional chain with more than one optional fails when it encounters the first optional in the chain that does not contain a wrapped instance.

Failing gracefully is great for working with optionals safely, but it is something we need to bear in mind when using optional chains because at times an optional chain that fails unexpectedly, or only under certain conditions, may introduce hard-to-diagnose bugs in the application. In the remainder of this article, we will consider what happens when an optional chain fails for the use cases discussed above, and ways to deal appropriately with such failures.

1. Failure of an optional chain to retrieve or return a value

When an optional chain is used to retrieve the value of a property of the wrapped instance, retrieve a value from a subscript on the wrapped instance, or call a method on the wrapped instance that returns a value, we can easily find out whether an optional chain has failed because instead of the expected value wrapped in an optional we get nil. We can deal with such situations by checking for nil and taking action accordingly.

The code below illustrates the failure of an optional chain used to retrieve the value of a property of the wrapped instance, where the optional does not actually contain a wrapped instance. We attempt to create a person with an empty string for a name, which we know will cause the initializer to fail and return nil. We then use an optional chain to retrieve the value of the name property, test the result for nil, and print a message accordingly.

let notAPerson = Person(named: "")
let notAName = notAPerson?.name
if notAName == nil {
    print("Person not found")
}
// Person not found

As an additional example, we show the failure of an optional chain used to retrieve a value from a subscript on the wrapped instance, where the optional does not contain a wrapped instance. To do this, we create a valid Person instance, which by default has its pets property set to nil. We use an optional chain to attempt to retrieve the first element of the pets property, test the result for nil, and print a message.

let aPerson = Person(named: "Jane")
let aPersonsPet = aPerson?.pets?[0]
if aPersonsPet == nil {
    print("Pet not found")
}
// Pet not found

2. Failure of an optional chain to call a method that does not return a value

The above mechanism works for cases where the optional chain is being used to retrieve or return a value, so we can test the resulting optional for nil to check for failure. But how about when we use an optional chain to call a method that does not return a value.

To demonstrate this, we define a variable of type Pet?, set its value to nil, and attempt to call the makeSound() method on the non-existent wrapped instance.

let notAPet: Pet? = nil
notAPet?.makeSound()

This does not cause an error because we have used an optional chain, but we also don’t get anything printed on the console, which tells us that the optional chain has failed. In this demonstration, we can check for failure by checking the console, but how can we know whether the optional chain failed in a real-world application where we may not be able to directly confirm whether the call to the method succeeded or failed.

This leads us to the important point that there is no such thing in Swift as a function with no return value. All Swift functions have a return type, and return a value of that type. The return type is either the type that we explicitly declare, or the implicit Void return type with the special return value (), an empty tuple. Since optional chains that retrieve or return a value always evaluate to an optional, when we use an optional chain to call a function with no explicit return type, we get a value of type Void?. We can test this against nil to check whether or not the optional chain succeeded in calling the method.

if notAPet?.makeSound() == nil {
    print("Method not called")
}
// Method not called

We may perform the check for nil inline, as shown above, or store the implicit return value from the function to check for nil at a later time.

var implicitReturnValue: Void? = notAPet?.makeSound()
if implicitReturnValue == nil {
    print("Method not called")
}
// Method not called

Note that rather than relying on type inference, we have explicitly defined the var implicitReturnValue to be of type Void?. If we don’t do this, we will get a warning from the compiler that we are looking for a return value from a function that does not explicitly return a value. So we have to assure the compiler that we know that the function we are calling does not have an explicit return value and we are looking for the implicit return value.

3. Failure of an optional chain to set a value

Finally, we look at cases where an optional chain fails to set the value of a property of the wrapped instance, or to set a value from a subscript on the wrapped instance. For this, we first use an optional chain to attempt to set a value for the name property using the notAPerson optional we had defined in the previous section, which does not contain a wrapped Person instance.

notAPerson?.name = "Jill"

Then we attempt to use an optional chain to set a value from a subscript on the pets property using the constant aPerson that we had defined in the previous section, where we know the pets property is set to an optional with no wrapped [Pet] instance.

aPerson?.pets?[0] = Cat()

In both the above cases, we know for this simple example that the optional chains should have failed, but we seem to have no direct way to confirm it.

We are helped here by a lesser-known aspect of Swift, which is that setting the value of a property, or setting a value from a subscript, implicitly returns the same value as a function with no explicit return value. So, just as in the previous section where we captured the implicit return value of a function which does not have an explicit return value, we can capture the implicit return value from setting the value of a property, and setting a value from a subscript, to check whether the above optional chains succeeded. As in the previous case, the return type will be Void?, so we can do an inline check for nil, or use the implicitReturnValue variable we had defined earlier.

Let’s try the latter approach for the optional chain we used above to attempt to set a property value.

implicitReturnValue = (notAPerson?.name = "Jill")
if implicitReturnValue == nil {
    print("Person does not exist, so name could not be set")
}
// Person does not exist, so name could not be set

We can do the same for the optional chain we used above to attempt to set a value from a subscript.

implicitReturnValue = (aPerson?.pets?[0] = Cat())
if implicitReturnValue == nil {
    print("Person does not exit, or pet could not be added")
}
// Person does not exit, or pet could not be added

This shows that both the optional chains above failed, which is as expected. It is noteworthy that in the first case there is a single point of failure, i.e., notAPerson could be nil. So we can be sure why the optional chain failed. In the second case, however, there are two possible points of failure, i.e., aPerson could be nil, or aPerson could wrap a Person instance with the pets property set to nil.

As noted earlier, the optional chain will fail as soon as it encounters the first optional that does not wrap an instance, or in other words, the first nil. In the above example, we know the optional chain failed because aPerson has its pets property set to nil. We demonstrate the case below where there is no wrapped Person instance by using the notAPerson optional.

implicitReturnValue = (notAPerson?.pets?[0] = Cat())
if implicitReturnValue == nil {
    print("Person does not exit, or pet could not be added")
}
// Person does not exit, or pet could not be added

In both cases, we print the same failure message because the failure of the optional chain does not give us enough information to know which of the two tests for nil failed. In case we need that information for the purposes of our application, we will need to break up the optional chain to isolate the relevant point of failure.

Optionals wrapping optionals

As noted earlier in this article, an optional can wrap an instance of any Swift type. Since Optional is a Swift type, we can have an optional wrapping another optional. In fact, there can be any number of nested optionals.

Creating a nested optional is simple – just add additional question marks. Each additional question mark creates an additional level of nesting. As an example, we create an optional of type Pet? containing a wrapped Cat instance, with two additional levels of nesting.

var nestedPet: Pet??? = Cat()
print(type(of: nestedPet))
// Optional<Optional<Optional<Pet>>>

Unsurprisingly, the type of nestedPet is Optional<Optional<Optional<Pet>>> (or Pet???), which is the type we have specified above.

The good news is that optional chaining takes dealing with nested optionals in its stride, regardless of the levels of nesting. We simply add as many additional question marks as the levels of nesting to access the wrapped instance. We show below how we can use an optional chain to set and retrieve the name property of the Cat instance wrapped in the above nested optional.

nestedPet???.name = "Bella"
let nestedPetName = nestedPet???.name
print(nestedPetName ?? "Pet name not found")  // Bella

Similarly, we can use an optional chain to call a method on an instance wrapped in a nested optional.

nestedPet???.makeSound()  // Meow

To demonstrate setting and retrieving a value from a subscript on an instance wrapped in a nested optional, we create a new type representing a person who has a nested array of pets.

class PersonWithNestedPets {
    var name: String
    var pets: [Pet]???
    
    init?(named name: String) {
        guard !name.isEmpty else { return nil }
        self.name = name
    }
}

We create a new instance of the above type and use an optional chain in the normal manner to set a value for the array of pets.

var personWithNestedPets = PersonWithNestedPets(named: "Ralph")
personWithNestedPets?.pets = [Cat()]

Now, we can use an optional chain, with additional question marks, to set and retrieve the value of the name property of the cat owned by the person.

personWithNestedPets?.pets???[0].name = "Fluffy"
let personsNestedPetName = personWithNestedPets?.pets???[0].name
print(personsNestedPetName ?? "Pet name not found") // Fluffy

While, as we have seen above, we can easily deal with nested optionals using an optional chain, we are not likely to commonly encounter nested optionals in Swift. Under “normal” circumstances, a value obtained using an optional chain, whether it is the value of a property of the wrapped instance, a value retrieved from a subscript on the wrapped instance, or a value returned by a method of the wrapped instance, will not be a nested optional regardless of the number of optionals included in the optional chain, or the number of levels of nesting of a particular optional in the chain. Having said this, consider the following snippet of code.

let annotationView = MKAnnotationView()
let annotationTitle = annotationView.annotation?.title
print(type(of: annotationTitle))    // Optional<Optional<String>>

This is an example of a few instances where things can get a bit different on the margins, when we deal with Objective-C classes bridged to Swift. This particular situation where an optional chain yields a nested optional, which comes about when dealing with MapKit, was kindly pointed out by Mike Chartier. (In fact, this section of the article was added based on Mike’s suggestion.) Since the introduction of Swift, Apple engineers have been hard at work reducing the likelihood of such paradigm-altering interactions for Swift programmers. We are not there yet, as the above example illustrates, but monumental progress has already been made, and more continues to be done every day.

As long as there are cases that we have to deal with that can produce such anomalies, the main thing to do is to be aware of what to expect, so we can take appropriate action. An optional chain, as already noted, can easily deal with a nested optional as long as we know where we are likely to encounter such situations, so they don’t take us by surprise and we can proactively make appropriate modifications to our code.

Conclusion

Optional chaining is an extremely useful and powerful feature of Swift, which allows us to work with optionals without having to unwrap them, and without having to materially change the way in which we normally access properties and subscripts, or call methods. Since optional chains fail gracefully when they do, which is great because our application will not crash and burn if a nil is encountered by an optional chain, we may need to build appropriate checks to confirm whether a particular optional chain succeeded if that information is required by the application.

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a conversation on Twitter.

A Protocol-Oriented Approach to Associated Types and Self Requirements in Swift

September 16, 2020

Associated types and Self requirements are important features of Swift and are used extensively in the standard library. But they can be tricky to use and continue to frustrate many Swift programmers. This article shows how, with a protocol-oriented approach, it is possible not only to avoid having to use associated types in many situations but also to use associated types and Self requirements, where appropriate, to leverage their benefits while avoiding the pitfalls.

What is an associated type
How not to use protocols with associated types
A protocol-oriented way to use associated types
A protocol-oriented alternative to associated types
Use of associated types in the standard library
What is a Self requirement in a protocol
A protocol-oriented approach to using Self requirements
Use of Self requirements in the standard library
Other advantages of protocol-oriented design
1. Dealing with exceptional conditions
2. Extending the domain
Conclusion

What is an associated type

An associated type is a placeholder in a protocol for a type that is used as part of the protocol. Any type that conforms to the protocol must specify an actual type that will replace the placeholder. A protocol can have one or more associated types and these associated types provide flexibility for conforming types to decide which type to use in place of each associated type placeholder. Associated types are specified with the associatedtype keyword. Conforming types can use the typealias keyword to specify the type that will replace each associated type placeholder. In many cases, however, Swift is able to infer that type from the context.

A protocol with an associated type is an incomplete protocol since one or more of the types used as part of the protocol do not get resolved until the protocol is adopted. It is important to note that, although the presence of an associated type makes a protocol generic in the sense that conforming types can substitute any type for the placeholder, it does not mean that every type conforming to such a protocol will be generic. That decision is left to the conforming types.

How not to use protocols with associated types

Protocols with associated types have got something of a bad name in Swift circles. This is due to the very nature of protocols with associated types. As already noted, a protocol with an associated type is an incomplete protocol. It uses a type but that type remains unspecified until a concrete type conforms to the protocol. Therefore, Swift does not consider protocols with associated types as first-class types, i.e., they cannot be used as types of variables, constants, elements of collections, or parameters and return values of functions.

The frustration Swift developers sometimes experience with associated types is because of using protocols with associated types as abstractions for domain entities. Such abstractions then prove unusable as the abstract type cannot be used as the type of a variable, the type of elements of an array, or as a parameter or return type of a function.

To see how an associated type can be problematic when used inappropriately, let’s say we want to automate marking of certain types of exam questions. For a question to be automatically marked, we should be able to compare a given answer with the correct answer for value equality. Since we need to accommodate different types of questions that can be automatically marked, e.g., multiple-choice questions, true-false questions, etc., we need to use a protocol and the protocol should allow us to associate each type of question with a specific type of answer. Sounds like a problem that calls for a protocol with an associated type. Following classic object-oriented thinking, we would use a protocol to model an abstract question, as shown below.

protocol AutoMarkableQuestion {
    associatedtype Answer: Equatable
    var statement: String { get set }
    var correctAnswer: Answer { get set }
    func isCorrect(answer: Answer) -> Bool
}

The protocol AutoMarkableQuestion defines an associated type Answer, which is a placeholder for the type of answer that will be associated with each concrete question type. As we see in this example, Swift allows us to apply constraints to associated types. Here, we constrain the associated type Answer such that any type which replaces this placeholder must conform to Equatable so instances of concrete answer types can be compared for value equality using the == operator. The protocol also defines a variable to store the question statement, a variable to store the correct answer, and a method to check whether a given answer is correct.

Since the isCorrect(answer:) method will just test the given answer for value equality with the stored correct answer, we can implement this method in a protocol extension.

extension AutoMarkableQuestion {
    func isCorrect(answer: Answer) -> Bool {
        answer == correctAnswer
    }
}

Now, we can define concrete question types that conform to the protocol. Let’s start with a true-false question. Note that we don’t need to use the typealias keyword in this case as Swift is able to infer the type we are using in place of the Answer placeholder.

enum TrueFalseAnswer {
    case t, f
}

struct TrueFalseQuestion: AutoMarkableQuestion {
    var statement: String
    var correctAnswer: TrueFalseAnswer
}

Following the same pattern, we can define a type for multiple-choice questions where the correct answer is one of four choices.

enum MultipleChoiceAnswer {
    case a, b, c, d
}

struct MultipleChoiceQuestion: AutoMarkableQuestion {
    var statement: String
    var correctAnswer: MultipleChoiceAnswer
}

Let’s test these concrete types by defining one instance of each question type.

let trueFalseQuestion = TrueFalseQuestion(
    statement: "The sun revolves around the earth.",
    correctAnswer: .f)

let multipleChoiceQuestion = MultipleChoiceQuestion(
    statement: "Which city is the capital of France? a) Rome; b) Paris; c) London; d) Accra",
    correctAnswer: .b)

We can check the output of the isCorrect(answer:) method by providing a correct and incorrect answer for each question.

print(trueFalseQuestion.isCorrect(answer: .t))
// false
print(trueFalseQuestion.isCorrect(answer: .f))
// true
print(multipleChoiceQuestion.isCorrect(answer: .a))
// false
print(multipleChoiceQuestion.isCorrect(answer: .b))
// true

Associated types get the Swift type system working for us and we are greeted with a compile-time error if the answer we provide is an instance of any type other than the answer type associated with the question being answered. We can see this type-safety in action if we try to provide a multiple-choice answer to a true-false question.

print(trueFalseQuestion.isCorrect(answer: MultipleChoiceAnswer.a))
// Error: Cannot convert value of type 'MultipleChoiceAnswer' to expected argument type 'TrueFalseAnswer'

The compiler complains that the type of the value MultipleChoiceAnswer.a is not the expected answer type for a true-false question. We get a different error is we omit the MultipleChoiceAnswer prefix.

print(trueFalseQuestion.isCorrect(answer: .a))
// Error: Type 'TrueFalseAnswer' has no member 'a'

This is all well and good. But the point of using a protocol is to be able to treat questions at an abstract level so we can use questions without having to know the actual type of each concrete question instance. Let's try and do that with one of the questions.

let question: AutoMarkableQuestion = trueFalseQuestion
// Error: Protocol 'AutoMarkableQuestion' can only be used as a generic constraint because it has Self or Associated type requirements

We get the error that has baffled many Swift programmers. The problem is that, since the AutoMarkableQuestion protocol has an associated type, the protocol is not a first-class type and it can be used only as a generic constraint. Therefore, we are getting an error when assigning an instance of TrueFalseQuestion to a variable of type AutoMarkableQuestion even though TrueFalseQuestion conforms to AutoMarkableQuestion. The same thing happens if we try to create an array to store instances of different concrete question types.

let questions: [AutoMarkableQuestion] = [trueFalseQuestion, multipleChoiceQuestion]
// Error: Protocol 'AutoMarkableQuestion' can only be used as a generic constraint because it has Self or Associated type requirements

The fact that we cannot create a variable of type AutoMarkableQuestion or use AutoMarkableQuestion as the type of the elements of an array is not a limitation of Swift. It simply reflects the fact that the AutoMarkableQuestion protocol is incomplete and the protocol type does not provide sufficient information about instances of conforming types. For example, if we could create a variable of type AutoMarkableQuestion, what answer type would we expect a concrete instance stored in that variable to receive. The reality is that we cannot know since the protocol does not provide that information. We would have the same issue if we could create an array with elements of type AutoMarkableQuestion or a function with a parameter or return value of type AutoMarkableQuestion. This is why Swift renders a protocol with an associated type unusable as a first-class type. This makes the AutoMarkableQuestion protocol unusable as an abstraction, defeating the purpose of creating the protocol.

A protocol-oriented way to use associated types

In the previous section, we saw how using an associated type in a protocol renders it unusable as an abstraction of a domain entity since the protocol cannot be used a first-class type. This can sometimes deter developers from using protocols with associated types. But protocols with associated types can enable us to solve otherwise thorny problems in simple and elegant ways. The solution to this seeming conundrum is to look at the domain through a protocol-oriented lens, using protocols to model traits of domain entities rather than the domain entities themselves. This can enable us to leverage the strengths of associated types while avoiding the issues we saw in the previous section.

Let’s revisit the problem of automating marking of certain types of exam questions. This time, rather than using a protocol with an associated type to model a question, which is a domain entity, we use a protocol with an associated type to model the characteristic that we want our questions to have, i.e., they should support automatic marking.

protocol AutoMarkable {
    associatedtype Answer: Equatable
    var correctAnswer: Answer { get set }
    func isCorrect(answer: Answer) -> Bool
}

The AutoMarkable protocol is similar to the AutoMarkableQuestion protocol we had defined in the previous section. It defines an associated type Answer, which is a placeholder for the type of answer that will be associated with each conforming type. As we had done before, we constrain the associated type Answer such that any type which replaces this placeholder must conform to Equatable so instances of answer types as can be compared for value equality using the == operator. We also define a variable correctAnswer to store the correct answer and a method to check whether a given answer is correct. Unlike the AutoMarkableQuestion protocol, we don’t have a variable to store the question statement, since this protocol does not represent a question but rather a specific attribute of questions.

As we had done with the AutoMarkableQuestion protocol, we use a protocol extension to implement the isCorrect(answer:) method to test the given answer for value equality with the stored correct answer.

extension AutoMarkable {
    func isCorrect(answer: Answer) -> Bool {
        return answer == correctAnswer
    }
}

Now, we can define concrete question types to conform to the AutoMarkable protocol. We start with a true-false question, using the TrueFalseAnswer type we had defined in the previous section.

struct TrueFalseQuestion: AutoMarkable {
    var statement: String
    var correctAnswer: TrueFalseAnswer
}

Following the same pattern, we can define a type to model a multiple-choice question, using the MultipleChoiceAnswer type defined in the previous section.

struct MultipleChoiceQuestion: AutoMarkable {
    var statement: String
    var correctAnswer: MultipleChoiceAnswer
}

To test these types, we write a function to check whether an answer given for a question is correct.

func printResultOf<Question: AutoMarkable>(question: Question, forAnswer answerGiven: Question.Answer) {
    print(question.isCorrect(answer: answerGiven) ? "Correct, one point!" : "Sorry, try again!")
}

Remember the error we got in the previous section when we tried to use the AutoMarkableQuestion protocol as a first-class type and we were told that AutoMarkableQuestion can only be used as a generic constraint, which made the abstraction unusable. Now that we have used the protocol AutoMarkable to abstract a trait of the domain entity rather than a domain entity itself, we can do exactly what the error was telling us to do, i.e., use the AutoMarkable protocol as a generic constraint. In the generic function printResultOf(question:forAnswer:), we have used AutoMarkable as a constraint on the type parameter Question, which requires that any type that replaces the Question placeholder must conform to AutoMarkable.

We create concrete question instances in exactly the same way as we had done in the previous section.

let trueFalseQuestion = TrueFalseQuestion(
    statement: "The sun revolves around the earth.",
    correctAnswer: .f)

let multipleChoiceQuestion = MultipleChoiceQuestion(
    statement: "Which city is the capital of France? a) Rome; b) Paris; c) London; d) Accra",
    correctAnswer: .b)

Now we can use the printResultOf(question:forAnswer:) function to test answers to questions, as shown below.

printResultOf(question: trueFalseQuestion, forAnswer: .t)
// Sorry, try again!
printResultOf(question: trueFalseQuestion, forAnswer: .f)
// Correct, one point!
printResultOf(question: multipleChoiceQuestion, forAnswer: .a)
// Sorry, try again!
printResultOf(question: multipleChoiceQuestion, forAnswer: .b)
// Correct, one point!

Note that the forAnswer parameter of printResultOf(question:forAnswer:) has the type Question.Answer, which is the answer type associated with the concrete type that replaces the Question placeholder. This gets the Swift type system working for us to guard against using the incorrect answer type for any question. We see below the compile-time error we get if we try to use a true-false answer for a multiple-choice question.

printResultOf(question: multipleChoiceQuestion, forAnswer: TrueFalseAnswer.t)
// Error: Cannot convert value of type 'TrueFalseAnswer' to expected argument type 'MultipleChoiceAnswer'

This error tells us that the type of the argument we have provided for the forAnswer parameter does not match the Answer type associated with the type we have used to replace the Question placeholder. The compiler catches us even if we omit the TrueFalseAnswer prefix, reminding us that the MultipleChoiceAnswer type has no member t.

printResultOf(question: multipleChoiceQuestion, forAnswer: .t)
// Error: Type 'MultipleChoiceAnswer' has no member 't'

A protocol-oriented alternative to associated types

As we have seen in previous sections, using a protocol with an associated type is not the right way to create an abstraction for a domain entity since the protocol type will no longer be a first-class type, making it useless as an abstraction. We also saw how using a protocol-oriented approach can enable us to use protocols with associated types as they were intended to be used, i.e., as generic constraints rather than as first-class types. In this section, we will explore how using a protocol-oriented approach can often allow us to avoid using protocols with associated types altogether.

The key to protocol-oriented thinking is to start not by looking for abstractions for domain entities but by understanding what the entities will do and what algorithms we need. Since Swift protocols enable retroactive modeling, we can start by writing some concrete code to better understand what our code is supposed to do, use that knowledge to create abstractions based on the attributes and algorithms we need, and retroactively model our concrete types to work with these abstractions.

Let’s consider a case where we want to model different kinds of animals and the food they eat. Thinking from an object-oriented perspective, where we would normally start by looking for abstractions for domain entities, we may use an Animal protocol to model an animal, as shown below, where the associated type Food creates a placeholder that conforming types will use to specify the type of food that a particular type of animal eats.

protocol Animal {
    associatedtype Food
    func eat(_: Food)
}

Having seen the limitations of protocols with associated types, however, we know that this approach will land us in trouble when we try to use Animal as a first-class type, which would be expected of a protocol used to model an abstraction of a domain entity.

var animal: Animal
// Error: Protocol 'Animal' can only be used as a generic constraint because it has Self or Associated type requirements
var animals: [Animal]
// Error: Protocol 'Animal' can only be used as a generic constraint because it has Self or Associated type requirements

As we had noted in a previous section, the fact that we cannot create a variable of type Animal, or use Animal as the type of the elements of an array, is not a limitation of Swift. It simply reflects the fact that the Animal protocol is incomplete and the protocol type does not provide sufficient information about instances of conforming types. For example, if we could create a variable of type Animal, we would not know what food we can expect a concrete animal instance stored in that variable to eat.

With a protocol-oriented approach, however, we don’t need to think about abstractions at the outset. We can write some concrete code and let it guide us to the abstractions we may need. To demonstrate this, we start by creating two types of food that animals commonly eat.

struct Grass {}
struct Meat {}

Now we can create concrete animal types that eat these types of food.

struct Goat {
    func eat(_: Grass) {
        print("Eating Grass")
    }
}

struct Dog {
    func eat(_: Meat) {
        print("Eating Meat")
    }
}

From the above code, we can see that the characteristic we want animals to have is that they eat, and different types of animals only eat specific types of food. The two cases we have are animals that eat grass and those that eat meat. Here is how we can create abstractions to model these eating traits.

protocol GrassEating {
    func eat(_: Grass)
}

protocol MeatEating {
    func eat(_: Meat)
}

We can use retroactive modeling to make our concrete animal types conform to the relevant protocols.

extension Goat: GrassEating {}
extension Dog: MeatEating {}

Since the implementations of the eat(_:) methods follow a standard pattern in the concrete Goat and Dog types, we can use protocol extensions to implement these methods for animals that eat grass and meat respectively.

extension GrassEating {
    func eat(_: Grass) {
        print("Eating Grass")
    }
}

extension MeatEating {
    func eat(_: Meat) {
        print("Eating Meat")
    }
}

With these extensions in place, we don’t need to implement the eat(_:) method in the concrete types and we can rewrite the Goat and Dog types as below.

struct Goat: GrassEating {}
struct Dog: MeatEating {}

We can also define other grass-eating and meat-eating animals in the same way.

struct Sheep: GrassEating {}
struct Wolf: MeatEating {}

This gives the concrete animal types the ability to eat their specific types of food and the type system will stop us if we try to make them eat something that they should not.

let goat = Goat()
let sheep = Sheep()
let wolf = Wolf()

let grass = Grass()
let meat = Meat()

goat.eat(grass)
// Eating Grass
sheep.eat(grass)
// Eating Grass
wolf.eat(meat)
// Eating Meat

goat.eat(meat)
// Error: Cannot convert value of type 'Meat' to expected argument type 'Grass'

What is different between the Animal protocol we had shown earlier and the GrassEating and MeatEating protocols is that the protocols we are using now are complete protocols and the protocols types are first-class types which can be used as types of variables and as types of elements of arrays.

let grazer: GrassEating = goat
grazer.eat(grass)
// Eating Grass

let grazers: [GrassEating] = [goat, sheep]
grazers.forEach({ $0.eat(grass) })
// Eating Grass
// Eating Grass

Use of associated types in the standard library

The Swift standard library makes extensive use of associated types in the protocols used to model sequences and collections. These associated types give significant flexibility to conforming types to customize certain aspects of their implementations while remaining within the overall framework defined by the protocol.

The Collection protocol, for instance, has five associated types:

Element: Represents the collection’s elements
Index: Represents a position in the collection
Indices: Represents the indices valid for subscripting the collection
Iterator: Provides the collection’s iteration interface
SubSequence: Represents a contiguous subrange of the collection’s elements

These associated types give concrete types that adopt the Collection protocol the flexibility to replace any of the associated type placeholders with appropriate types as required. Array, Set and Dictionary are all collection types in the standard library. Set and Dictionary conform to Collection while Array conforms to RandomAccessCollection and MutableCollection, both of which inherit from Collection. All three are generic collections but there is a difference in the way they use the Element associated type defined by the Collection protocol. Array uses Element as its type parameter, meaning the type that replaces the Element placeholder is decided at the time of instance creation, enabling Array to be used to create an array of any valid type in Swift.

struct Array<Element>

Set also uses Element as the placeholder for the type of elements of each set but, since it needs to test efficiently for membership and ensure that each element appears only once in a set, there is the additional condition that the type of elements should conform to the Hashable protocol.

struct Set<Element> where Element: Hashable

Dictionary is a collection of key-value pairs so it redefines the Element placeholder as a tuple containing a key-value pair, with the condition that only the keys need to conform to the Hashable protocol.

struct Dictionary<Key, Value> where Key: Hashable

String is also a collection as it conforms to BidirectionalCollection and RangeReplaceableCollection, both of which inherit from Collection. There is no need for String to be generic, however, since all strings are collections of characters. Accordingly, the String type replaces the Element placeholder with the Character type and has no type parameter.

If we look further into the Array and String types, we see that Array replaces the SubSequence placeholder with the ArraySlice type, which presents a view onto the storage of a larger array, while String replaces SubSequence with the Substring type, which is a slice of a string that shares its storage with the original string. Since arrays are indexed using integers, Array replaces the Index placeholder with the Int type. String, on the other hand, replaces the Index placeholder with a nested type String.Index, which represents a position of a character or code unit in a string. A string in Swift is actually a collection of extended grapheme clusters, represented by the Swift Character type. Many individual characters can be made up of multiple Unicode scalar values. This is why, unlike Array, which allows random access to its elements using integer indices and whose count property has O(1) complexity, Swift has to actually ‘walk’ a string to be able to get to a certain index in the string or to report the length of the string, so the count property of String has O(n) complexity.

What is a Self requirement in a protocol

A Self requirement is a placeholder in a protocol for a type, used as part of the protocol, which is replaced by the concrete type that conforms to the protocol. A Self requirement can thus be thought of as a special case of an associated type. Like a protocol with an associated type, a protocol with a Self requirement is also an incomplete protocol since the type to be used in place of the Self placeholder gets resolved only when the protocol is adopted. The difference is that, while a conforming type can use any type it wants to replace an associated type, any Self placeholder must be replaced by the confirming type itself.

A protocol-oriented approach to using Self requirements

Thinking back to the animal example we saw in an earlier section, where we modeled the eating characteristic of animals, let’s say we now want to model a different characteristic of animals, i.e., they can mate, but only with other animals of the same type. If we think with an object-oriented mindset, we could use an Animal protocol to model an abstract animal, as shown below, to reflect the mating characteristic of animals.

protocol Animal {
    func mate(with: Self)
}

Note the Self placeholder for the type of the parameter of the mate(with:) method. In concrete types that adopt this protocol, this placeholder must be replaced by the concrete type itself, ensuring that each type of animal can mate only with other animals of the same type. The Animal protocol is thus said to have a Self requirement.

To demonstrate this, we define a Cow type to conform to the Animal protocol, replacing the Self placeholder with Cow.

struct Cow: Animal {
    func mate(with: Cow) {
        print("Mating with another Cow")
    }
}

Since mate(with:) will be implemented similarly in all conforming types, we can use a protocol extension to implement this method.

extension Animal {
    func mate(with other: Self) {
        print("Mating with another \(type(of: other))")
    }
}

Now we can define concrete types conforming to the protocol without having to implement the mate(with:) method.

struct Cow: Animal {}
struct Deer: Animal {}

As with an associated type, use of a Self requirement gets the Swift type system working for us, allowing each animal to mate with another animal of the same type, but not with an animal of a different type.

let cow = Cow()
let deer = Deer()
let anotherCow = Cow()
let anotherDeer = Deer()

cow.mate(with: anotherCow)
// Mating with another Cow
deer.mate(with: anotherDeer)
// Mating with another Deer

cow.mate(with: deer)
// Error: Cannot convert value of type 'Deer' to expected argument type 'Cow'

But using a Self requirement in the Animal protocol would land us in exactly the same problem that we faced when we used the Food associated type in an earlier section. Just like an associated type, a Self requirement in a protocol also renders the protocol unusable as a first-class type.

let animal: Animal = cow
// Error: Protocol 'Animal' can only be used as a generic constraint because it has Self or Associated type requirements

let animals: [Animal] = [cow, deer]
// Error: Protocol 'Animal' can only be used as a generic constraint because it has Self or Associated type requirements

This is because a protocol with a Self requirement is also an incomplete protocol. Even if we could define a variable of the above protocol type Animal, how would we use this variable since we cannot know from the protocol with which concrete type of animal this animal can mate.

The solution is to again think in a protocol-oriented way and, rather than using a protocol to create an abstraction for the animals themselves, use a protocol to create an abstraction for what animals can do in this context, i.e., they can mate with other animals of the same type. Using this approach, we use a protocol to create an appropriate trait and a protocol extension to implement the trait.

protocol Mating {
    func mate(with: Self)
}

extension Mating {
    func mate(with other: Self) {
        print("Mating with another \(type(of: other))")
    }
}

It is simple to make concrete animal types conform to this protocol. If we don’t have these concrete types, we can declare the conformance when we define the concrete types; if we already have them, we can declare conformance via extensions to the concrete types. Here, we show the former approach, with conformance declared at the time of creating concrete animal types.

struct Cow: Mating {}
struct Deer: Mating {}

This affords us the same benefit of the Swift type system that we had when we gave the Animal protocol a Self requirement, i.e., animals are allowed to mate with their own type but not with an animal of another type.

cow.mate(with: anotherCow)
// Mating with another Cow
deer.mate(with: anotherDeer)
// Mating with another Deer

cow.mate(with: deer)
// Error: Cannot convert value of type 'Deer' to expected argument type 'Cow'

Note that the Mating protocol has a Self requirement and cannot be used as a first-class type. Unlike the Animal protocol, however, where not being able to use the protocol type as a first-class type posed a problem because animal is a domain entity, this limitation actually makes sense when we think about the use cases of Mating. When and why would we want to create a variable of type Mating or an array with elements of type Mating. Even if we could do so, how would we use such a variable or such an array since we will not know the concrete type of animals that can mate with an animal instance stored in such a variable or in an element of such an array.

Use of Self requirements in the standard library

Self requirements are quite common in protocols found in the standard library. Take the Equatable protocol as an example, which enables two instances of a type to be compared for value equality using the == operator and value inequality using != operator. The following function is required to conform to the Equatable protocol.

static func ==(Self, Self) -> Bool

Use of Self placeholders for the types of both parameters ensures that, in implementations provided by conforming types, both the parameters must be of the conforming type. Consider the case where we have the following Course type.

struct Course {
    var code: Int
    var name: String
}

We can make Course conform to the Equatable protocol through the following extension, where the == function we implement replaces both the Self placeholders with the Course type.

extension Course: Equatable {
    static func ==(lhs: Course, rhs: Course) -> Bool {
        lhs.code == rhs.code && lhs.name == rhs.name
    }
}

The above implementation of == is shown for illustrative purposes only. In practice, Swift is able to automatically synthesize Equatable conformance for most structs and enums, provided Equatable conformance is declared in the type’s original declaration. So we could simply have defined our Course type as follows to make it conform to Equatable.

struct Course: Equatable {
    var code: Int
    var name: String
}

Two other commonly used standard library protocols Comparable and Hashable, both of which inherit from Equatable, also have Self requirements. Another protocol with Self requirements that is used often is Numeric, which provides a basis for arithmetic on scalar values, such as integers and floating-point numbers. The Numeric protocol can be used to write generic methods that can operate on any numeric type in the standard library. It can also be used as a constraint on type parameters of generic types to ensure that certain type parameters can only be used with numeric types, without having to specify the specific numeric type until the moment of instance creation.

Other advantages of protocol-oriented design

So far in this article, we have seen how protocols can help avoid having to use associated types in many situations while also enabling associated types and Self requirements to be used effectively where appropriate. The protocol-oriented approach that we have used offers other advantages as well. To see these advantages in action, let’s quickly recap the two design approaches we have used to deal with a domain dealing with animals. In the first approach, we used a protocol to create an abstract Animal type, with an associated type Food as a placeholder for the types of food different animals eat. Subsequently, we showed the same Animal protocol with a Self requirement to model the characteristic that animals can mate, but only with animals of the same type. If we put these requirements together, the Animal protocol would look like this.

protocol Animal {
    associatedtype Food
    func eat(_: Food)
    func mate(with: Self)
}

As we saw, this approach creates issues as it renders the Animal type unusable as a first-class type, making the abstraction quite useless. We then presented a protocol-oriented approach, using protocols as abstractions for what animals can do rather than for the animals themselves. We created the following protocols to model the ability of animals to eat different types of food.

protocol GrassEating {
    func eat(_: Grass)
}

protocol MeatEating {
    func eat(_: Meat)
}

With this approach, we could use the protocols as first-class types, using the abstractions to represent individual animals and groups of animals according to the food they eat. We then used the same approach to represent the mating trait, with the following protocol.

protocol Mating {
    func mate(with: Self)
}

These traits, as we have seen, can be easily added not only to new animal types by declaring conformance to the protocol at the time of defining the concrete types but also to existing animal types through retroactive modeling by declaring conformance to the protocol in extensions to the concrete types.

Now let’s see what other advantages, besides the ones we have already seen, we get with a protocol-oriented design where we use protocols as abstractions for traits rather than as abstractions for domain entities. We will briefly cover two additional benefits of this protocol-oriented approach in the remainder of this article.

1. Dealing with exceptional conditions

If we use a protocol to model a domain entity, as we did with the Animal protocol, the implicit assumption is that all animals have the same characteristics, i.e., they eat a particular type of food and they mate with their own kind. But what if there are animals that do one but not the other. One example of such an animal is a mule, which is produced by breeding a jack (male donkey) with a mare (female horse). Ignoring for a moment that in our model, where an animal can mate only with its own kind, a mule cannot be born, how would we use a model where every animal must have a mate(with:) method, to deal with a case where an animal needs to eat but cannot mate.

Such exceptions do occur in real-life domains and using protocols to create abstractions for domain entities can sometimes back us into corners from which there may not be a graceful exit. What would we do if we need to model an animal that needs to eat but cannot mate? Make the mate(with:) method throw an error to deal with the exceptional case? That would make the API awkward to use at client sites, in particular when the overwhelming majority of concrete animal types will actually not throw an error but client sites will have to incorporate error handling to be able to cater to the few exceptions. Moreover, if the exception is not known during initial design, introducing it later may risk breaking existing client code.

With a protocol-oriented approach, however, we can easily handle such exceptions because we use abstractions to represent the individual traits rather than the animals themselves. If we need to model an animal that does not need one or more of the traits, we simply don’t make that concrete type conform to those traits. We show this by creating two new kinds of animals, both of which eat grass but one of them does not mate.

struct Horse: GrassEating, Mating {}
struct Mule: GrassEating {}

let horse = Horse()
let mule = Mule()
let anotherHorse = Horse()
let anotherMule = Mule()

horse.eat(grass)
// Eating Grass
horse.mate(with: anotherHorse)
// Mating with another Horse

mule.eat(grass)
// Eating Grass
mule.mate(with: anotherMule)
// Error: Value of type 'Mule' has no member 'mate'

This approach obviates the need to anticipate or design for all possible exceptions at the outset. With individual traits represented by separate protocols and concrete types composed using these traits, it is quite easy to deal with exceptions regardless of whether they are known during initial design or present themselves at a later stage.

2. Extending the domain

Another advantage of protocol-oriented design is that it allows us to easily extend the domain. This is because traits modeled using protocols represent certain characteristics or abilities that apply to domain entities. The traits don’t say anything about what the domain entities are and can be used for any domain entity that has the same characteristics or abilities. Let’s consider the eating and mating traits as an example, which we have thus far applied to animals because that was the requirement of the domain at the time. We are free, however, to apply the same traits to any domain entity that needs to have the same characteristic or ability. In this case, for instance, we could easily extend the domain to include humans in the same context, since humans also eat specific types of food and mate only with other humans. As humans have a more diversified palate than animals, we just need to create some new types of food.

struct Vegetable {}
struct Fruit {}

let vegetable = Vegetable()
let fruit = Fruit()

Next, we create traits for eating these new types of food, using protocols and protocol extensions, as we did for other eating traits.

protocol VegetableEating {
    func eat(_: Vegetable)
}

extension VegetableEating {
    func eat(_: Vegetable) {
        print("Eating a Vegetable")
    }
}

protocol FruitEating {
    func eat(_: Fruit)
}

extension FruitEating {
    func eat(_: Fruit) {
        print("Eating a Fruit")
    }
}

Now we can create a concrete type to model humans.

struct Human: MeatEating, VegetableEating, FruitEating, Mating {}

Note that we have used the newly defined traits VegetableEating and FruitEating seamlessly with the traits MeatEating and Mating that we had defined for animals.

An instance of the Human type defined above will automatically get methods to eat the three types of food that we have specified and a method to mate with other humans.

let human = Human()

human.eat(meat)
// Eating Meat
human.eat(vegetable)
// Eating a Vegetable
human.eat(fruit)
// Eating a Fruit

let anotherHuman = Human()
human.mate(with: anotherHuman)
// Mating with another Human

Conclusion

Associated types and Self requirements are important features of Swift and are used extensively in the standard library. It is crucial to bear in mind, however, that a protocol with an associated type or a Self requirement is an incomplete protocol and cannot be used as a first-class type. This is why it is not advisable to use such protocols to represent abstractions for domain entities since such abstractions will be unusable. With a protocol-oriented approach, however, where protocols are used to represent things domain entities can do and roles domain entities can play rather than the domain entities themselves, it is possible in many cases to avoid having to use associated types in protocols. This approach also makes it possible to use associated types and Self requirements in protocols, where appropriate, to leverage the advantages that associated types and Self requirements offer while avoiding the pitfalls.

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a discussion on Twitter.

Encapsulating Domain Data, Logic and Business Rules With Value Types in Swift

January 30, 2019

This article shows how we can leverage the power of Swift value types to encapsulate domain data, logic and business rules. It keeps classes focused on maintaining the identity of entities in the domain and managing state changes through their life cycles, helping to deal effectively with domain complexity and facilitating efficient, easily testable and concurrency-friendly programs.

When and How to Use Value and Reference Types in Swift
When and How to Use the Equatable and Identifiable Protocols in Swift

Designing with value and reference types
Representing immutable state
Dealing with mutable state
1. Swift value types and mutability
2. Controlling mutability of value types
The interplay of value and reference types
Usage considerations
Benefits
1. Separation of concerns
2. Testability
3. Efficiency
4. Concurrency
Conclusion

Designing with value and reference types

Swift offers a rich collection not just of reference types, in the form of classes and closures, but also of value types, in the form of structs, enums and tuples. Enums, tuples and closures are more specialized in what they do, so structs and classes are the most commonly used value and reference types respectively. To be able to program effectively with value and reference types, it is vitally important to understand the difference between value and reference semantics.

Values are used in almost all programs. Usually, these are basic values, like numbers and strings. Swift uses structs to represent numbers and strings. But structs in Swift can do a lot more than just represent simple data values. They can define properties and methods, specify initializers and conform to protocols, enabling abstraction and polymorphism. Since basic Swift data types (like numbers and strings) and basic container types (like arrays) are structs, even their functionality can be extended.

The real power of value types comes from composition, where we combine relatively simple value types to build value types capable of encapsulating the data, logic and business rules related to the various responsibilities of entities in the domain. The entities themselves are represented using classes because they have identity, a life cycle, and state that needs to be managed through that life cycle.

As an example, let’s consider a bank account as an entity that we need to model. A bank account has an identity in the domain, a life cycle and state that needs to be preserved. It is appropriate, therefore, to use a class to model a bank account. However, rather than burdening the class with the data, logic and business rules related to all the responsibilities of a bank account, we can design domain-specific value types to encapsulate the data, logic and business rules related to each of the major responsibilities of the class. This way, the class will be directly responsible only for maintaining the identity of the bank account and preserving its state.

To keep things manageable, let’s look at the two basic attributes of a bank account – account number and balance. Our first instinct may be to model the account number as a String and the account balance using a basic value type, like the Decimal type from the Standard Library, or a general-purpose Money type. However, once we start to get a deeper insight into the domain, we realize that there is more to it than that. A bank account number is not just a simple number. It is usually composed of components, which may need to be combined in different ways, often with other static elements, for different purposes, according to specific rules. Likewise for the account balance. There is usually a ledger balance and an available balance. There could also be an overdraft limit and there are specific rules governing when certain operations are allowed.

Representing immutable state

Not all state of an entity is meant to be mutable. Some attributes are set when an instance is created and do not change over its lifetime. For a bank account, the unique identifier that each account is assigned when it is created would be such an attribute.

As a first step in modeling a bank account, therefore, we create a value type that will allow each account to be uniquely identified. Note that we have not called this type ‘account number’. The account number that we commonly associate with each account is not the only way to identify a bank account, as we will see below. We assume we have already defined a Money type to represent monetary values and perform basic operations on such values.

struct AccountIdentifier {
    var accountNumber: String {
        return branchCode + base + suffix
    }
    
    var iban: String {
        var iban = ""
        // Logic to build IBAN
        return iban
    }
    
    let branchCode: String
    let base: String
    let suffix: String
}

The bank account number that we normally see and use is typically a derived value. It is composed from sub-identifiers. Which identifiers are used, and in what order, may vary from case to case. For the purposes of our example, we have used a branch code, a base number unique to each customer, and a suffix which allows the same customer to hold multiple accounts linked to the same base number.

We have given our AccountIdentifier type a computed property, which concatenates the three sub-identifiers to form an account number that can be used to identify the account in normal use, such as on bank statements. This number would, however, only be unique for accounts within the same bank. Most bank accounts need other identifiers that will be unique in a broader context. For example, in order to clear cheques and process domestic fund transfers, withdrawals from other banks’ ATMs, etc., we may need a reference which will be unique across all banks that participate in the relevant clearing system. Similarly, when sending or receiving cross-border fund transfers, some sort of international identifier is often required. The most common such identifier is the International Bank Account Number (IBAN).

These identifiers can constructed by combining the sub-identifiers with static information, like standard bank and country codes. There are rules governing these combinations, such as how long an identifier must be, and how and where to insert padding. To keep the example simple and focused, we have just added an iban computed property to our AccountIdentifier type, without going into details of how an IBAN is actually constructed.

The point of the foregoing discussion is that real-world domains are usually complex, in ways that we can only begin to appreciate once we start to get an in-depth understanding. Trying to get one class to deal with all the data, logic and business rules related to a real-world entity is likely to make the class unwieldy and a nightmare to maintain. Using domain-specific value types enables us to break down the complexity into manageable chunks, which can be encapsulated behind APIs rich in the language of the domain.

Dealing with mutable state

Entities usually have mutable state. The classes we use to model them are responsible for keeping track of that state through the life cycle of the entity. The state is usually composed of values. Let’s consider the bank account example introduced earlier in this article. Unlike the account identifier, which is fixed for the life of the account, the account balance needs to change as money is deposited into and withdrawn from the account. Before we model this behaviour, let’s take a look at how mutation relates to values and value types.

As the state of a class mutates, the values themselves don’t change. They are just replaced by new ones. When we add a number to another, for instance, we don’t really change either number. We just create a new number equal to the sum of the two numbers. We can assign the sum to a new variable or to one of the variables holding the original numbers. Doing the latter may create the impression that we have modified the number. In fact, we have just discarded the old value in the variable and replaced it with a new one.

1. Swift value types and mutability

On the surface, Swift seems to allow mutation of the state of values by letting us define structs with variable stored properties and mutating methods. If you look under the hood, however, this is just sleight of hand. What Swift actually does when we change the value of a stored property of a struct, either directly or by using a mutating method, is to create a new instance of the struct and assign it to the variable to which the original instance was assigned, discarding the original instance in the process.

Here is a quick test to prove this.

struct TestStruct {
    mutating func changeValue(to newValue: Int) {
        value = newValue
    }
    
    var value: Int
}

var testVar = TestStruct(value: 5) {
    didSet {
        print("New instance created, with value: \(testVar.value)")
    }
}

We define a struct with a single variable stored property, and a mutating method that assigns a new value to the stored property. We then declare a new variable and assign an instance of the struct to the variable. We also give the variable a didSet observer, which will print a message whenever a new value gets assigned to the variable.

Let’s see what happens when we assign a new value to the stored property of the instance, directly as well as by using the mutating method.

testVar.value = 6           // New instance created, with value: 6
testVar.changeValue(to: 7)  // New instance created, with value: 7

In both cases, we get a message in the console confirming that, rather than modifying the same instance, Swift has assigned a new instance with the new value to the variable.

To obtain further confirmation, we assign a new instance of the struct to a constant. We then try to modify the stored property in the same ways as above.

let testConst = TestStruct(value: 5)

testConst.value = 6
// Error: Cannot assign to property: 'testConst' is a 'let' constant
testConst.changeValue(to: 7)
// Error: Cannot use mutating member on immutable value: 'testConst' is a 'let' constant

Sure enough, both our attempts to mutate the value of the stored property are met with errors because Swift is unable to assign the new instance it has created to a constant.

This shows that whenever we change the value of a stored property of a value type instance, directly or through a mutating method, it has the same effect as creating a new instance and assigning it to the variable holding the original instance, which gets discarded in the process.

2. Controlling mutability of value types

We have seen that Swift can only mutate a value type instance by assigning a new value to the variable that holds the instance. This means that we can control when a value type instance can be mutated, and when it cannot be, simply by assigning the instance to a variable (declared with the var keyword) or to a constant (declared with the let keyword) respectively. When we assign a value type instance to a constant, we are in effect guaranteeing that the instance can never be mutated, even if it has variable stored properties and mutating methods.

If we take a value type instance assigned to a constant and assign it to a variable, we can mutate the instance assigned to the variable. It is important to note, however, that the instance that gets mutated is a copy of the instance assigned to the constant, which itself remains unchanged. This is because value type instances in Swift automatically get copied on assignment, with no data sharing between an instance and its copy. It is noteworthy that this guarantee of no data sharing is true by definition only for ‘pure’ values, i.e., value type instances all of whose stored properties are also instances of value types. The picture can get a bid muddled if we create value types with stored properties which are instances of reference types, as we will see a bit later.

For now, we demonstrate how pure values guarantee automatic copying on assignment with no data sharing.

struct PureValue {
    var value: Int
}

let pureValueConst = PureValue(value: 5)
var pureValueVar = pureValueConst
pureValueVar.value = 10

print(pureValueConst.value)     // 5
print(pureValueVar.value)       // 10

The struct PureValue has a mutable property of type Int. We assign a new instance of this type to the constant pureValueConst. We then assign the value of the constant to the variable pureValueVar. When we modify the value assigned to the variable, we see that the value assigned to the constant remains unchanged.

An instance of a value type assigned to a constant cannot be changed directly and will remain unaltered regardless of how many times we assign its value to a variable or pass it as an argument to a function, which also creates a copy of the instance and does not affect the original instance. This can give us fine-grained control over how certain parts of the code will behave, making code more predictable and easier to reason about.

We continue with the bank account example introduced earlier in this article and define a value type to model the account balance. As already noted, the account balance is not a single number. There is a ledger balance, which may or may not be the same as the available balance. There could be various reasons for a difference between the two, including a delay between authorization and posting of transactions, presence of a hold on a certain amount of funds, availability of an overdraft limit, etc. For the purposes of this example, we consider just one scenario, an optional overdraft limit.

struct AccountBalance {
    init(_ ledger: Money, overdraftLimit: Money? = nil) {
        self.ledger = ledger
        self.overdraftLimit = overdraftLimit
    }
    
    var available: Money {
        return ledger + (overdraftLimit ?? Money(0))
    }
    
    var ledger: Money
    var overdraftLimit: Money?
}

The ledger balance, the actual recorded balance of the account, and the overdraft limit, are stored properties. The latter is an optional since there may or may not be an overdraft allowed on a particular account. The available balance is computed from the stored properties.

Next, we add the following mutating method to the AccountBalance type, which can be used to increase the balance of the account.

mutating func increase(by amount: Money) {
        ledger = ledger + amount
}

Before we add a method to decrease the balance, we need to think about what should happen if the amount to be decreased exceeds the available balance of the account. This depends on the domain business rule, which could be to disallow such requests, or to allow an unauthorized overdraft, which could attract a higher rate of interest.

For our example, we assume that the account balance cannot be decreased below the available balance and the following error should occur if such an attempt is made.

enum AccountError: Error {
    case insufficientBalance
}

Having agreed the business rule to be used, we add the following method to the AccountBalance type, to decrease the balance of an account, subject to the business rule.

mutating func decrease(by amount: Money) throws {
    guard amount <= available else {
        throw AccountError.insufficientBalance
    }
    ledger = ledger - amount
}

Note the throws keyword in the signature of the decrease(by:) method, which makes it a throwing function.

The interplay of value and reference types

We have already seen that we can stop the mutation of a value type instance that has variable stored properties, simply by assigning it to a constant. But this guarantee holds only for pure values, i.e., value type instances all of whose stored properties also hold values. Things may be different if the value type instance holds an instance of a reference type. This is because, unlike a variable holding a value type instance, where the variable and the instance assigned to it are logically unified and the value held by a variable cannot be manipulated independently of the variable, a variable holding a reference type instance is distinct from the instance assigned to it. A variable holding a reference type instance holds only a reference to the actual instance, which is allocated on the heap. There may be one or more other references to the same instance, any of which may be used to mutate the instance.

If a value type instance, which holds a reference type instance, is assigned to a constant, the only guarantee we get is that the reference held by the value type instance will not change, i.e., it will point to the same location in memory. This, however, cannot stop the actual reference type instance at that memory location from being modified. In fact, we can do this ourselves by assigning the value type instance to a variable, declared with the var keyword. Since values get copied on assignment, the new value will have a property holding a copy of the reference to the same memory location. We can use the new value to modify the reference type instance, which is now implicitly shared between the two values, because they both holds references to it.

class ReferenceType {
    init(value: Int) {
        self.value = value
    }
    
    var value: Int
}

struct ValueWithReference {
    var reference: ReferenceType
}

let valueWithRefConst = ValueWithReference(reference: ReferenceType(value: 5))
var valueWithRefVar = valueWithRefConst
valueWithRefVar.reference.value = 10

print(valueWithRefConst.reference.value)    // 10
print(valueWithRefVar.reference.value)      // 10

We define a class called ReferenceType, which holds a value of type Int. We then define a struct called ValueWithReference and give it a property called reference of type ReferenceType.

We assign a new instance of ValueWithReference to a constant. We then assign the value of this constant to a variable and mutate the reference property of the instance assigned to the variable. When we print the Int values held by both the instances, we find that the value assigned to the constant has been modified, although we never touched it. This is because the ReferenceType instance is shared between the two instances of ValueWithReference and modifying it in one place affects the other as well.

One way to control such mutation could be to perform a deep copy each time a reference type instance is copied. But this can potentially have materially negative performance implications, owing to the heap memory allocation and reference counting involved in making copies of reference type instances, in particular if we end up having to create deep copies of reference type instances holding instances of other reference types. Another way to deal with the problem is to make all reference type instances used to represent values immutable, but this would still require a lot of copying, which is not an inherent strength of reference types.

There is a strong case, therefore, to use pure values to model the state of entities. This not only makes code more predictable and less prone to errors, it can also significantly improve performance characteristics. This is because value types are ‘cheaper’ to copy as they do not incur performance penalties due to allocation of memory on the heap and the overhead of reference counting. Pure values also facilitate concurrency since each thread can use its own copy of the data held by value type instances with no shared state.

There is no magic formula for how to mix value and reference types in designing applications, and different situations may demand different strategies. It stands to reason, however, to use value and reference types in ways that play to their strengths and not otherwise.

Given below are some guidelines, which could help manage the interplay of value and reference types:

Use classes to model entities while using pure values to encapsulate as much of the domain data, logic and business rules as possible.
Carefully consider how much of the state of a class needs to be mutable.
For mutable parts of the state of a class that need to be accessible to code outside the class, make the properties only privately settable. This will ensure that, while the mutable values can be accessed by those on the outside, the class remains solely in charge of mutating its state.
When any values that form the accessible state of a class need to be used outside the class, to the extent possible, assign them to let constants. This way, any code that uses these values can be confident that they were not modified since being copied from an instance of the class.

We now return to our bank account example. Having defined value types to encapsulate the data, logic and business rules related to the relevant aspects of a bank account, we define the following class to model a bank account.

class Account {
    init(identifier: AccountIdentifier, balance: AccountBalance) {
        self.identifier = identifier
        self.balance = balance
    }
    
    func credit(_ amount: Money) {
        balance.increase(by: amount)
    }
    
    func debit(_ amount: Money) throws {
        try balance.decrease(by: amount)
    }
    
    let identifier: AccountIdentifier
    private(set) var balance: AccountBalance
}

The Account class exposes the API to be used to perform operations on the account, leaving the heavy lifting to the value types already defined. This includes enforcing the business rule that an account cannot be debited for an amount exceeding its available balance. Accordingly, the debit(_:) method above simply propagates any errors that may be thrown by the decrease(by:) method of the AccountBalance type.

Note the private(set) modifier to the declaration of the balance property. There is no access level specified for the property, which means it has the default internal access level, enabling it to be used by code in any source file in the same module. However, the private(set) modifier makes the property settable only by code in the enclosing declaration and any extensions of that declaration in the same source file.

This has the effect of permitting the class, including any of its extensions in the same source file, to set the value of the balance property, while providing read-only access to the property to all other code.

Usage considerations

Value type instances in Swift are always copied on assignment. We have already noted how constants declared with the let keyword can be used to ensure that value type instances, even those with variable properties and mutating methods, are not modified after they are copied from a class instance. Care also needs to be taken to ensure that any client code does not rely on outdated information. Ideally, rules should be established regarding when a value obtained from a class should be discarded immediately after use and when it can be stored, and for how long. What makes sense in each scenario will depend on how often the state of the class instance is updated and the recency requirement of the use case of the client code.

For instance, in the case of a bank account:

Code that needs to report real-time balance information should discard the value immediately after use.
Code that generates statements as of the close of the previous day can store values obtained during the day and discard them at the end of each day.
Code that needs access to static information such as account identifiers can refresh its values each time a batch run takes place, which would reflect updates for new accounts opened, accounts closed, etc.

Similar rules can be established on a case by cases basis, depending on the requirements and workflow of the domain.

Benefits

1. Separation of concerns

What we have seen is just a subset of the responsibilities of a class used to model a bank account. Imagine such a class in a real-world system and the amount of logic and number of business rules it would contain. This could lead to a significantly bloated class with a mixed bag of related but separate responsibilities. With all state of the entity modeled using value types, each value type takes responsibility for managing its own data, logic and business rules. The class maintains the identity of the entity, preserves its state, and exposes the API to be used by client code, but leaves all operations and validation to the respective value types.

2. Testability

Code that deals with pure values is inherently more easily testable because of the defining characteristics of values – attribute-based equality, lack of identity or life cycle, and substitutability. There is no need to use mocking frameworks or elaborate setup code to test value types, as often required for testing classes, which maintain state over their life cycles and their behaviour can change with changes in state. For testing a value type instance, all we need to do is create a new value with the expected attributes and perform an equality comparison.

3. Efficiency

It is considerably more efficient in Swift to work with value types compared to reference types, since the latter must be allocated on the heap and involve significant overhead to manage reference counting. Although there is more copying involved when dealing with values, copies of value type instances in Swift are generally ‘cheap’ and many copies can simply be optimized away by the compiler.

4. Concurrency

Since value type instances are always copied on assignment, and on being passed as arguments to a function, with no data sharing between copies, we can safely hand over values to processes running on different threads, without having to worry about synchronization, race conditions, deadlocks, etc. With the state of the domain entities modeled using pure values, any client code that simply needs to query the state of the entity can be handed a value that represents the relevant aspect of the state of the entity. These operations can run in parallel without any conflicts.

Only when an operation that may mutate the state of the class is to be executed do we need direct access to an instance of the class. In practice, such operations are typically executed much less frequently than queries. For a bank account, for instance, the most common operations are checking the balance, generating statements, generating IBANs, etc. All such operations can safely proceed concurrently, which could lead to significant gains in efficiency and response times.

Conclusion

We could construct our programs only using the value types provided by the Standard Library and simple general-purpose value types of our own, letting classes directly manage the detailed logic and myriad business rules related to all their responsibilities. But this would mean not using the real power of Swift value types in managing complexity and making code simpler and more efficient. We can keep classes lean and focused by creating domain-specific values types that encapsulate domain data, logic and business rules.

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a conversation on Twitter.

Rethinking Design Patterns in Swift – State Pattern

December 6, 2018

*** Updated for Swift 5.1 ***

The State pattern enables an entity, which can change its behaviour based on its internal state, to use a set of types conforming to a common interface to represent these states. This allows behaviour related to states, and transitions between states, to be modeled in a flexible and extensible manner. The State pattern provides an effective way to implement finite state machines. In this article, we work through a case study to demonstrate how the State pattern can be implemented in Swift, exploring various aspects of the pattern and showing its ability to handle changes in requirements. We also look at key design and implementation considerations as well as benefits and practical applications of the pattern.

Rethinking Design Patterns in Swift – Command Pattern

Finite state machines
State pattern
1. Intent
2. Structure and participants
State machine diagram
1. States, events and transitions
2. Entry and exit activities for states
3. Transition effects and guard conditions
State Pattern implementation
1. The Context type
2. The State interface
3. The Context type revisited
4. Concrete state types
5. Test run
Dealing with Change
1. Adding a transition
2. Adding properties to concrete state types
3. Adding a transition effect
4. Adding a new state
Key design and implementation considerations
1. Handling state transitions
2. States with state
3. Creating states
4. Events and activities not applicable to certain states
5. Specifying activities in states or transitions
Benefits of the State pattern
1. Clear control flow
2. Partitioning behaviour
3. Flexibility and extensibility
Practical applications of the State pattern
1. Database updates
2. Drawing programs and frameworks
3. Graphical user interfaces
4. Network protocols
5. Game programming
6. Embedded systems
Conclusion
References

Finite state machines

A finite state machine, also called finite state automaton, is an abstract machine that can be in any one of a finite number of states, and can transition among these states in response to certain trigger events.

Real-world domains commonly contain entities that may, at any point in time, be in one of a number of possible states. Depending on what state the entity is in, it may react differently to the same action or event. These kinds of entities can be modeled effectively using finite state machines, also called finite state automata.

Consider a typical vending machine. When no money has been inserted, pressing a button that is supposed to vend a particular item has no effect. This is because the machine is not in the right state for that action to be performed. Even when money is inserted, the machine may vend some items but not others, depending on how much money has been inserted and how much each item costs. Once the item that was paid for has been given, the machine goes back to the state where it will not vend anything without receiving money.

Simple state machines can be implemented in code using conditional statements, typically nested switch statements. This may be adequate, and quite efficient, for very simple state machine implementations. However, this approach does not scale well. When dealing with more complex state machines, it can lead to code that is cumbersome, hard-to-understand and challenging to maintain.

The State pattern provides a robust way to implement a state machine. State-specific behaviour is encapsulated by a set of types that conform to the same interface. The entity being modeled relies on these types to handle events that may trigger transitions between its states.

State pattern

1. Intent

The State pattern enables an instance of a type to change its behaviour with changes in its internal state. From an external perspective, the instance may appear to change its type.

2. Structure and participants

The class diagram below illustrates the structure of the State pattern:

State pattern class diagram

The Context type provides the interface to be used by clients. The State type defines an interface, to be used by the context, which represents state-specific behaviour of the context. Each concrete state type encapsulates the behaviour associated with a particular state of the context. The context is thus able to delegate state-specific behaviour to the concrete state types.

The flexibility of the pattern comes from the fact that the context depends only on the interface defined by the State type and not on any of the concrete state types. Instances of concrete state types can thus be swapped in and out as the context transitions from one state to another.

State machine diagram

A state machine diagram, or state diagram, is a visual representation of a state machine. Each state is represented by a rounded rectangle and arrows connecting the rectangles show transitions between states. If the state machine has a default initial state, a small filled circle is used to represent an initial pseudostate, which typically transitions automatically into the first proper state.

Let’s assume we have been tasked with building the control unit for a security system, which sounds an alarm when there is an intrusion or the threat of an intrusion. The security system will be connected to sensors, each of which can detect a breach, such as a door or window being opened. When the system is armed, such a breach should cause an alarm to be sounded. The system will also have one or more panic switches, which can be used to sound an alarm even when there is no actual breach but there may be an imminent threat of a breach from a potential intruder. When the system is not armed, a breach or panic signal should not have any effect.

We also need to ensure that, once armed, the system can be disarmed only through the use of a code. This code will be set when the system is initialized and must be used to disarm the system. The same code must also be used to reset the system, i.e., stop the alarm once it has been sounded.

If we think of the security system described above as a state machine, we can represent it visually by the following state diagram:

Initial state diagram for security system

Although the diagram is fairly intuitive, let’s briefly look at its constituent parts and some of the formalisms governing construction of state diagrams, as per the Unified Modeling Language (UML) specification.

1. States, events and transitions

Our system can be in any of three states: Disarmed, Armed and Alarm. The Disarmed state is the default initial state.

Transitions between the states can be triggered by the following events:

Arm: Triggers a transition from the Disarmed state to the Armed state.
Disarm: Triggers a transition from the Armed state to the Disarmed state.
Breach: Indicates that a sensor has been breached. Triggers a transition from the Armed state to the Alarm state.
Panic: Indicates that a panic switch has been activated. Triggers a transition from the Armed state to the Alarm state.
Reset: Triggers a transition from the Alarm state to the Disarmed state.

2. Entry and exit activities for states

Any of the states in a state machine may have entry and/or exit activities. An entry activity is performed just after a state is entered while an exit activity is performed just before a state is exited. Specifying activities for states is not mandatory but it is a useful way of ensuring that states encapsulate the behavior associated with them.

3. Transition effects and guard conditions

A complete specification of a transition can have four parts – a trigger event, a guard condition, an effect and a target state. The trigger event is what causes the transition to fire and the target state is the state that becomes active on completion of the transition. The guard condition is an optional boolean expression which is evaluated when the relevant trigger event occurs. If a transition has a guard condition, it will fire only if the boolean expression evaluates to true. An effect is an optional action or activity that is performed before the transition completes, i.e., before the target state becomes active. A transition label is used to represent the trigger event, guard condition and effect in the format: ‘event [guard condition] / effect’.

State Pattern implementation

1. The Context type

Having visualized our state machine, let’s start implementing it by defining the Context type, which has methods corresponding to events in the state diagram.

class System {
    func arm() {}
    func disarm(usingCode code: String) {}
    func breach() {}
    func panic() {}
    func reset(usingCode code: String) {}
}

What we have at the moment is just a skeleton of the Context type, with empty implementations of the methods. This is because we are yet to put in place the machinery of the State pattern, which will be used by the Context type to provide the required functionality.

2. The State interface

When describing the structure of the State pattern, we had noted that the context delegates state-specific behavior to the concrete state types, using methods defined by the State interface, to which all the concrete state types conform.

Each concrete state type will represent a single state of the context. It will be responsible not only for handling events that may trigger transitions from that state but also for executing the entry and exit activities of the state. These are separate responsibilities but we need to combine them into a single interface. Swift allows us to do this cleanly using protocol composition, which lets us combine the requirements of two or more protocols.

protocol Events {}

protocol Activities {}

typealias State = Events & Activities

We have defined separate protocols to represent events, which may trigger transitions between states, and activities related to the states themselves. We combine the requirements of these protocols into a single protocol, which we bind to the name State using a typealias. This demonstrates how protocol composition can facilitate following the Interface Segregation Principle to define protocols narrowly while being able to combine their requirements to meet the needs of the application.

Having worked out the overall scheme, we define the requirements of the Events protocol.

protocol Events {
    mutating func arm(_: System) -> Transition?
    mutating func disarm(usingCode: String, _: System) -> Transition?
    mutating func breach(_: System) -> Transition?
    mutating func panic(_: System) -> Transition?
    mutating func reset(usingCode: String, _: System) -> Transition?
}

This protocol contains one method for each of the events that may trigger a transition from one state to another. Each method takes an instance of the Context type as a parameter, to be able to call methods on the system to effect actions as required. Note that all the methods are marked with the keyword mutating. This is because we will use structs to model the concrete states and we want to account for the possibility that any of the methods may need to mutate the state of its concrete state instance.

Not every state in a state machine may have a possible transition to every other state. In our case, for instance, when the alarm system is in the Disarmed state, a breach or a panic event should not have any effect. Similarly, a breach or panic event should have no effect on a system already in the Alarm state. An otherwise valid transition may also fail due to a guard condition not evaluating to true. This would be the case if an attempt is made to trigger a transition from the Armed or Alarm States to the Disarmed state, without providing a valid code.

This is why the return type of all the above methods is Transition?. This allows each concrete type to return a suitable transition, with the option to return nil if a transition is not possible.

Here is the Transition type, which specifies the target state of the transition and an optional effect.

struct Transition {
    var targetState: State
    var effect: Effect? = nil
    
    typealias Effect = (System) -> ()
}

We use a protocol extension to provide default implementations of all the methods of the Events protocol. All these implementations return nil to cover the case where a transition is not possible. This will let the concrete state types implement methods only for the events that can actually cause a transition from that state.

extension Events {
    mutating func arm(_: System) -> Transition? { return nil }
    mutating func disarm(usingCode: String, _: System) -> Transition? { return nil }
    mutating func breach(_: System) -> Transition? { return nil }
    mutating func panic(_: System) -> Transition? { return nil }
    mutating func reset(usingCode: String, _: System) -> Transition? { return nil }
}

Next, we define the requirements of the Activities protocol.

protocol Activities {
    func enter(_: System)
    func exit(_: System)
}

These methods will allow each concrete state type to define entry and exit activities for the state it represents. Both these methods take an instance of the Context type as a parameter, to be able to call methods on the system to effect any required actions.

Since every state will not have entry and/or exit activities, we define the following extension to the above protocol.

extension Activities {
    func enter(_: System) {}
    func exit(_: System) {}
}

With default empty implementations of both the methods in place, concrete state types will need to implement these methods only for states that actually have entry and/or exit activities respectively.

3. The Context type revisited

Now we are in a position to implement the methods in the Context type. The Context type will delegate state-specific behaviour to the concrete state types using the interface defined by the State type.

class System {
    init(code: String) {
        self.code = code
        state = DisarmedState()
    }
    
    func arm() {
        process(transition: state.arm(self))
    }
    
    func disarm(usingCode code: String) {
        process(transition: state.disarm(usingCode: code, self))
    }
    
    func breach() {
        process(transition: state.breach(self))
    }
    
    func panic() {
        process(transition: state.panic(self))
    }
    
    func reset(usingCode code: String) {
        process(transition: state.reset(usingCode: code, self))
    }
    
    func isValid(code: String) -> Bool {
        let isValid = code == self.code
        print(isValid ? "Code accepted" : "Invalid code")
        return isValid
    }
    
    private func process(transition: Transition?) {
        guard let transition = transition else { return }
        state.exit(self)
        transition.effect?(self)
        state = transition.targetState
        state.enter(self)
    }
    
    private var state: State
    private let code: String
}

The state property of the Context type is the lynchpin of the State pattern. As the program runs and the context transitions from one state to another, instances of different concrete state types will be assigned to this property. State-related behaviour will thus be delegated using this property to the relevant concrete state instances.

The initial state of the state machine is set in the initializer of the Context type. The context does not have to know when to execute a transition and to which state. That knowledge will be encapsulated in the concrete state types, as we will see in the next section. All the context has to do is to use the return value of the functions called on the concrete state types to transition to the next state. This is done in the process(transition:) method, which does nothing if the argument is nil and executes a transition when one is available.

4. Concrete state types

Having laid the groundwork, we are ready to implement state-related behaviour in the concrete state types, each of which will conform to the State protocol.

Let’s start with the simplest concrete state type, which represents the Disarmed state.

struct DisarmedState: State {
    func enter(_: System) {
        print("System disarmed")
    }
    
    func arm(_ system: System) -> Transition? {
        return Transition(targetState: ArmedState())
    }
}

The enter(_:) method, which will be executed when this state is entered, disarms the system. For the purposes of this demonstration, it simply prints a message to the console stating that the system has been disarmed.

When the system is disarmed, a breach or a panic event does not apply. Neither can the system be reset from this state. The only applicable method from the Events protocol, therefore, is arm(_:), which causes the system to become armed by returning a transition with an instance of ArmedState as the target state.

This is the state we will implement next.

struct ArmedState: State {
    func enter(_: System) {
        print("System armed")
    }

    func disarm(usingCode code: String, _ system: System) -> Transition? {
        guard system.isValid(code: code) else { return nil }
        return Transition(targetState: DisarmedState())
    }
    
    func breach(_ system: System) -> Transition? {
        return Transition(targetState: AlarmState())
    }
    
    func panic(_ system: System) -> Transition? {
        return Transition(targetState: AlarmState())
    }
}

The enter(_:) method in this case arms the system. The disarm(usingCode:_:) method disarms the system by returning a transition with an instance of DisarmedState as the target state, provided the correct code has been entered. If the code is not correct, nil is returned to indicate that a transition should not take place. The breach(_:) and panic(_:) methods return transitions with instances of AlarmState as the target state.

The last state we need to implement is the Alarm state.

struct AlarmState: State {
    func enter(_: System) {
        print("Alarm sounded")
    }
    
    func exit(_: System) {
        print("Alarm stopped")
    }
    
    func reset(usingCode code: String, _ system: System) -> Transition? {
        guard system.isValid(code: code) else { return nil }
        return Transition(targetState: DisarmedState())
    }
}

The enter(_:) method for this state sounds the alarm. This is the only state with an exit(_:) method, which stops the alarm. Once the alarm has been sounded, any further breach or panic event should not cause a transition, so these events don’t apply to this state. The reset(usingCode:_:) method returns a transition with an instance of DisarmedState if the code provided is valid, returning nil otherwise.

5. Test run

First, we test the system in its initial Disarmed state. In this state, a breach reported by a sensor or the press of a panic button should not have any effect. So we call the two methods on a newly minted System instance and see what happens.

let system = System(code: "1234")
system.breach()
system.panic()

As expected, nothing gets printed to the console.

Let us arm the system and then trigger a breach.

system.arm()                        // System armed
system.breach()                     // Alarm sounded
system.reset(usingCode: "1234")     // Code accepted
                                    // Alarm stopped
                                    // System disarmed

This time, when the breach() method is called, the alarm is sounded as expected. We then call the reset(usingCode:) method to stop the alarm and disarm the system.

Let’t see if the panic switches also work as expected.

system.arm()                        // System armed
system.panic()                      // Alarm sounded
system.reset(usingCode: "1234")     // Code accepted
                                    // Alarm stopped
                                    // System disarmed

A call to the panic() method has the same effect as the breach() method earlier. As before, we call the reset(usingCode:) method to stop the alarm and disarm the system.

Now let’s arm the system and then try to disarm it, first with an invalid code and then with the correct code.

system.arm()                        // System armed
system.disarm(usingCode: "0000")    // Invalid code
system.disarm(usingCode: "1234")    // Code accepted
                                    // System disarmed

When we use the wrong code, the state of the system remains unchanged and we just get a polite error message. When we use the correct code, the system gets disarmed.

Finally, let’s make sure that once we are in the Alarm state, the system can be reset only using the correct code.

system.arm()                        // System armed
system.breach()                     // Alarm sounded
system.reset(usingCode: "1111")     // Invalid code
system.reset(usingCode: "1234")     // Code accepted
                                    // Alarm stopped
                                    // System disarmed

As expected, when we enter an invalid code, it is rejected. The correct code is accepted, stopping the alarm and disarming the system.

We are done. It is time to unveil the security system to the world and let the orders roll in.

Dealing with Change

It is said that change is the only constant in life. This is probably more true in systems development than in many other situations. Most real-world systems have to deal with change and the true test of the robustness of a design is how well it can embrace change.

We have been selling our security system for some time and the inevitable change requests are beginning to come in. Let’s see how the State pattern allows our system to flex as business requirements change.

1. Adding a transition

In the initial design of the security system, if a sensor is breached or a panic button is pressed while the system is disarmed, there is no effect. Some customers have asked for a design change where a panic can be triggered even when the system is disarmed. This panic functionality could be used, even when the system is disarmed, to scare off any unsavoury characters who may be lurking around a property secured by one of our security systems.

We modify the state diagram we had drawn earlier, to reflect the new requirement:

State diagram for adding a transition to the security system

The only change from the earlier state diagram is a new transition from the Disarmed state to the Alarm state, triggered by a panic event.

To effect this change, we need to extend the behaviour of the system only when it is disarmed. With the behaviour related to every state encapsulated in its own type, all we have to do is add the following method to the DisarmedState struct.

func panic(_ system: System) -> Transition? {
    return Transition(targetState: AlarmState())
}

Voila! Our system will now go into the Alarm state when a panic is triggered in the Disarmed state.

let system = System(code: "1234")
system.panic()                      // Alarm sounded

So far so good.

Time to crank our change request engine up a few notches.

2. Adding properties to concrete state types

As the fame of our security system has spread, more and more businesses are beginning to use it. Being more security conscious than home owners, their requirement is that when the system is in the Armed state, the user should be given only a limited number of attempts to try and disarm it. If the user makes more than the permitted number of attempts using an invalid code, the system should sound the alarm.

We dust off our last state diagram and make the required changes:

State diagram for adding a conditional transition to the security system

We have added a new transition from the Armed state to the Alarm state, which is triggered by the disarm event, but has a guard clause and fires only if the code provided is not valid and the maximum number of permitted attempts has been exceeded.

The only changes we will need to make will be to the ArmedState struct.

First, we add the following stored properties to enable tracking of the number of attempts made to disarm the system and to ensure that the maximum is not exceeded.

private var disarmAttempts = 0
private let maxDisarmAttempts = 3

Then, we modify the disarm(usingCode:_:) method to increment disarmAttempts for each call and to return a transition with an instance of AlarmState if the maximum number of attempts is exceeded.

mutating func disarm(usingCode code: String, _ system: System) -> Transition? {
    disarmAttempts += 1
    if system.isValid(code: code) {
        return Transition(targetState: DisarmedState())
    } else if disarmAttempts > maxDisarmAttempts {
        return Transition(targetState: AlarmState())
    } else {
        return nil
    }
}

Note that this is the first time we have used a mutating method in a concrete state type. However, since we have already accounted for this possibility in all the methods in the Events protocol, there is no need to make any changes to the protocol.

That’s all we need to do. Time for some testing.

let system = System(code: "1234")
system.arm()                        // System armed
system.disarm(usingCode: "0000")    // Invalid code
system.disarm(usingCode: "1111")    // Invalid code
system.disarm(usingCode: "2222")    // Invalid code
system.disarm(usingCode: "3333")    // Invalid code
                                    // Alarm sounded

Sure enough, we are allowed three attempts with an invalid code, but the moment we try a fourth time, the alarm sounds.

3. Adding a transition effect

Business users are a demanding bunch. Now they want that every time a user exceeds the maximum number of attempts permitted to disarm the system, in addition to sounding the alarm, the system should inform the system administrator.

This presents an interesting situation. There are two transitions that leave the Armed state, one leading to the Disarmed state and the other to the Alarm state. The exit activity of the Armed sate, which disarms the system, applies regardless of which transition fires. The requirement to inform the administrator, however, would apply only to the transition that leads to the Alarm state, which would be triggered if the maximum number of attempts allowed to disarm the system is exceeded.

When we have to add an action or activity to be executed only for a certain transition leaving a state but not for other transitions leaving the same state, we need to use a transition effect. This is executed after the exit activity of the state being exited has been executed but before executing the entry activity of the target state.

Given below is the modified state diagram with a transition effect added in the correct place.

State diagram for adding a transition effect to the security system

Implementing this in code is quite simple. Our Transition type allows us to add an optional transition effect. Until now, we have not had to use one, so we have simply been ignoring the effect parameter of the Transition initializer, since the property has a default value of nil. To add a transition effect, all we need to do is to provide a closure with the activity to be performed, using the trailing closure syntax.

We modify the disarm(usingCode:_:) method of the ArmedState struct, to add the required effect to the transition triggered when the code provided is not valid and the value of disarmAttempts exceeds the value of maxDisarmAttempts.

mutating func disarm(usingCode code: String, _ system: System) -> Transition? {
    disarmAttempts += 1
    if system.isValid(code: code) {
        return Transition(targetState: DisarmedState())
    } else if disarmAttempts > maxDisarmAttempts {
        return Transition(targetState: AlarmState()) { system in
            print("Administrator informed")
        }
    } else {
        return nil
    }
}

This is it. Let’s see if it works.

let system = System(code: "1234")
system.arm()                        // System armed
system.disarm(usingCode: "0000")    // Invalid code
system.disarm(usingCode: "1111")    // Invalid code
system.disarm(usingCode: "2222")    // Invalid code
system.disarm(usingCode: "3333")    // Invalid code
                                    // Administrator informed
                                    // Alarm sounded

This time, when we make the fourth attempt to disarm the system using an invalid code, the administrator is informed and then the alarm is sounded.

4. Adding a new state

With the fame of our security system spreading, it has attracted the attention of establishments such as banks, with more complex security requirements.

Home and normal business owners use the panic feature, which can be used to sound the alarm when the system is disarmed, to scare off random unsavoury characters. Banks, on the other hand, face the possibility of armed robbers entering the premises during normal hours of operation, when the system would be disarmed. To deal with such situations, banks typically install panic buttons out of public view, which can easily be activated by staff. However, if armed robbers have already entered the premises, it may not be wise to sound the alarm. What would be more useful is a mechanism which would trigger a message to law enforcement personnel, without sounding the alarm.

We know the drill. Let’s modify our state diagram to visualize the new requirement:

State diagram for adding a new state to the security system

Our state diagram now sports a new Silent Alarm state, which results from a panic event when the system is in the Disarmed state. When the system is in the Silent Alarm state, it can be reset in the same way as for the Alarm state.

We define a new concrete state type called SilentAlarmState which, like all other concrete state types, conforms to the State protocol.

struct SilentAlarmState: State {
    func enter(_: System) {
        print("Police informed")
    }
    
    func reset(usingCode code: String, _ system: System) -> Transition? {
        guard system.isValid(code: code) else { return nil }
        return Transition(targetState: DisarmedState())
    }
}

The enter(_:) method informs the police. No exit(_:) method is required. The reset(usingCode:_:) method is the same as in the Alarm state, which ensures that the system must be reset using the correct code.

The only other thing we have to do is to modify the panic(_:) method in the DisarmedState struct, as shown below.

func panic(_ system: System) -> Transition? {
    return Transition(targetState: SilentAlarmState())
}

That’s it. Time for a test-drive.

let system = System(code: "1234")
system.panic()                      // Police informed
system.reset(usingCode: "1234")     // Code accepted
                                    // System disarmed

Everything works as expected and we can now sell our system to banks and other high-security establishments.

The above examples show the flexibility that the State pattern gives us to accommodate changing requirements with only localized changes in code, without having the effects of these changes ripple through the code base.

Key design and implementation considerations

1. Handling state transitions

A signature characteristic of the State pattern is transition between states, which leads to the question: Which participant should be responsible for deciding when to transition from one state to another, and for knowing which state to transition to under what conditions? This responsibility could be given to either the Context type or the concrete state types themselves. While it is possible to make the context responsible for controlling state transitions, that would concentrate too much responsibility in the context. This could lead to creating just the kind of complex and hard-to-modify logic in the context that the State pattern aims to avoid.

The more common approach, which we have followed, is to let the concrete state types encapsulate the state transition logic. This does create a bit of dependency among the concrete state types, since each concrete state type must be aware of at least one other concrete state type. However, the benefit in making the transition logic decentralized and easy to modify makes this minor compromise worthwhile.

It is pertinent to note that while the context in our approach does not decide when a transition is to happen and to which state, we have given responsibility to the context to process the transitions. This ensures that each transition takes place in a well-orchestrated and orderly manner, with the specific steps required to complete transitions specified in one place and not sprinkled throughout the concrete state types.

2. States with state

Another question that arises when implementing the State pattern is whether the concrete state types should have stored properties, or put another way, whether the states should have state of their own. It is perfectly acceptable to define concrete state types that have stored instance properties. These properties can be used by the concrete state types in discharging their responsibilities.

It is especially interesting when some of these properties are mutable, allowing refinement of behaviour, depending on the values of these properties. In our example, as part of dealing with one of the change requests, we gave the ArmedState struct one mutable and one immutable property. These allowed us to add a conditional transition from the Armed state to the Alarm state.

3. Creating states

Each transition needs an instance of the target concrete state type, which means we need to decide where to put state creation logic. There is an argument for putting this logic in the Context type. However, this would mean that the context would have knowledge of individual concrete state types and will have to change when we need to add or remove a state. The approach we have taken is to let the concrete state types directly create instances of other concrete state types, eliminating the need for the context to know anything about concrete states. The context processes transitions between states using only the State interface, without knowing which concrete state types are involved.

4. Events and activities not applicable to certain states

Implementing a state machine means having to deal with a lot of optionality. It is quite common to have trigger events that don’t apply to certain states. Every state can specify entry and exit activities, but may not. Similarly, every transition can specify an effect, but may not. Having to implement methods for each of these possibilities could lead to a proliferation of methods that don’t do anything.

We have tackled this issue in two ways. First, by using protocol extensions, we have provided default implementations of all the methods related to trigger events as well as entry and exit activities of states. So concrete state types need to implement methods related only to those trigger events and activities that actually apply to them. Second, we have used an optional closure to specify the transition effect, with a default value of nil. This means that an effect needs to be specified only by transitions that actually have an effect and not otherwise.

5. Specifying activities in states or transitions

When a transition fires, it can cause a number of things to happen, including an exit activity for the state from where the transition got triggered, an entry activity for the target state, and an effect that is external to the states. The latter case is encountered when there are activities or actions that must be performed after the state from which the transition was triggered has been exited but before the target state of the transition is entered.

This gives fine-grained control over how to specify and sequence various activities resulting from transitions. It also affords an opportunity to think about whether an action or activity should be specified as an activity in a state or as a transition effect external to any state. Specifying actions and activities inside states can help stop data and logic that should be encapsulated in states from leaking out into transitions. It can also ensure that each state is able to perform any setup activities, which processes inside the state may rely on, when it is entered and it can perform any cleanup activities before they it is exited. Any actions or activities that belong outside the states can be specified as transition effects, to be performed, where required, between exit and entry activities of the relevant states.

Benefits of the State pattern

1. Clear control flow

Compared to the alternative of using simple data values to represent states and making the context responsible for deciding what action to perform for each event based on these data values, the State pattern delivers much clearer control flow. In fact, the context is no longer responsible for the control flow. All it has to do is delegate state-specific behaviour to its state property, letting the concrete instance it holds swing into action to provide the required functionality.

2. Partitioning behaviour

The State pattern lets us distribute the behavior of what could otherwise become a monolithic unit of code to a number of concrete state types, each responsible for encapsulating the data and logic related to a single state of the context. This leads to a neat partitioning of behaviour, with all behaviour related to a particular state localized in a single type. This includes not only the entry, exit and other activities associated with the state but also logic related to when it is possible to transition from the state and determining the target state for each transition.

3. Flexibility and extensibility

As we have already seen, the State pattern makes it easy to modify and extend behaviour. Whether modifying the behavior of an existing state or adding a completely new state, the State pattern helps localize the effect of the change. This is thanks to decoupling of the context from the concrete state types that contain the logic related to the various states of the context. The context only uses the methods defined by the State interface, and is not dependent on any of the concrete state types. In fact, with the concrete state types taking responsibility for creating their own instances, the context does not even need to be aware of how many concrete state types actually exist.

Practical applications of the State pattern

Here is a sampling of some applications of the State pattern, discovered and described by practitioners and subject matter experts:

1. Database updates

[Larman] discusses employing the State pattern to simplify the logic used to commit or rollback changes made to records in a database. At any given time, a database record in memory may be new (not in the database) or old (retrieved from the database). An old record could be clean (unmodified) or dirty (modified).

Based on the state of a record, it should react differently to a commit or a rollback operation. For example, on a commit operation, an “old dirty” record should be updated to the database, because it has been modified since being retrieved, while an “old clean” record should simply be ignored since it has not been modified.

2. Drawing programs and frameworks

[Gamma] talks about how the State pattern can be used to create interactive drawing programs and frameworks. In a typical drawing program, the user has a palette of “tools” to select from, which may include a drawing tool, a paint tool, a selection tool, a text tool, etc. Based on which tool the user has selected, user actions such as a mouse click, mouse press and release, keystroke input, etc., may be handled differently.

When the drawing tool is active, for instance, a mouse press may start the creation of a new shape while a mouse release may give the shape its final size and position. When the selection tool is active, the same mouse press may be used to mark the start of a rectangular area within which all shapes will be selected, while a mouse release may complete the selection.

3. Graphical user interfaces

[Martin] notes how the State pattern can be used to capture and implement high-level application policies for GUIs, making them explicit and easy to maintain. Modern GUIs can present a plethora of information in a single screen. However, not all information that could be presented may be applicable, relevant or even permitted for display at any given time. Similarly, certain tools or menu options could be made unavailable at certain times by disabling them or not displaying them altogether. For instance, different information and functionality will usually be available depending on whether the user is just browsing or logged in with a password. For multi-stage actions, the screen presented to the user may be different depending on what stage the user has reached.

4. Network protocols

[Gamma] provides a worked example of how the State pattern can be used to model a TCP connection. An object representing a TCP connection can be in one of several different states, e.g., established, listening, closed. Depending on the current state of the connection, it will react differently to requests, such as a request to open or close a connection.

5. Game programming

[Nystrom] describes how the State pattern can be used to control the behaviour and graphical representation of game characters, based on their current state. A character in an adventure game, for instance, can be in various states, such as standing, running, ducking, diving, sliding, etc. Depending on the state, the character would be represented differently on the screen and would react differently to various commands.

State pattern implementations could even be used concurrently to model not only the state of a character but also what equipment she may be carrying. The same fire command could then be used to release an arrow or fire a gun, depending on what weapon the character is wielding at the time.

6. Embedded systems

A number of real-world machines have distinct states, which determine whether and how the machine responds to a particular command or event.

[Freeman] gives an example of a gumball machine, which may or may not have gumballs to dispense and may or may not have coins inserted, so will react differently when the crank is turned depending on its state. Similar logic would apply to most vending machines.

[Martin] looks at a turnstile, the likes of which are found in places ranging from train stations and museums to lobbies of office buildings. A turnstile may be in a locked or unlocked state, may change state based on a valid ticket being inserted or an entry pass being scanned, and may or may not let a person through depending on its state.

Conclusion

A state machine is a useful abstraction to model entities commonly found in a number of real-world domains. The State pattern provides a robust way to implement a state machine. Owing to encapsulation of the behaviour related to individual states and decoupling of the context from the concrete state types, there is clearer control flow and partitioning of behaviour, leading to more flexible and maintainable applications.

References

[Gamma]	Gamma, E., Helm, R., Johnson, R. & Vlissides, J. (1995). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley
[Freeman]	Freeman, E., Freeman, E., Sierra, K. & Bates, B. (2004). Head First Design Patterns. O’Reilly Media
[Larman]	Larman, C. (2005). Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development (3rd ed.). Prentice Hall
[Martin]	Martin, R. C. (2003). Agile Software Development: Principles, Patterns and Practices. Prentice Hall
[Nystrom]	Nystrom, R. (2014). Game Programming Patterns

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a conversation on Twitter

Understanding, Preventing and Handling Errors in Swift

February 26, 2018

In this article, we start by looking at the likely sources of errors in an application, some ways to prevent errors from occurring and implementing error handling, thinking about resilience as well as usability. We will explore the error handling model built into Swift, covering the powerful tools, associated techniques and how to apply them to build robust applications.

Recoverable vs. unrecoverable errors
Sources of errors
Preventing errors
Handling errors
1. User experience considerations
2. Where to put error handling code
Using optionals for simple error handling
Representing errors
Throwing errors
Propagating errors
Catching errors
Selectively propagating errors
Try vs. try? vs. try!
1. Converting errors to optionals with try?
2. Asserting that errors will not occur with try!
Throws vs. rethrows
Performing clean-up actions with defer
Errors and polymorphism
Conclusion

Recoverable vs. unrecoverable errors

Recoverable errors are errors that may temporarily halt normal program execution but the program should be able to recover gracefully and continue executing without the loss of any vital functionality. Unrecoverable errors are those from which the program cannot recover and must shut down. These could be caused by bugs in program logic or other unexpected situations such as unavailability of a resource without which the program cannot execute in a meaningful manner.

In this article, we will be focusing on recoverable errors since normal error handling does not apply to unrecoverable errors. Given the unexpected nature of unrecoverable errors, it is hard to plan for them. One strategy could be to put appropriate checks at places where a potential unrecoverable error could occur. If a check fails, a crash sequence could be initiated to shut the program down in as orderly a fashion as possible. This could include informing user that the application has encountered a fatal error and must terminate, saving any unsaved state and information related to the unrecoverable error, either seeking the user’s consent to send crash-related information to the developer or displaying an error code or other information that the user could quote when reporting the issue.

Sources of errors

Our programs may encounter errors in various ways. Before we delve into the specifics of how to handle errors, let’s look at how they may come about. Getting a better understanding of sources of errors can help write code to try and avoid many errors in the first place.

Invalid user input: A user may not be aware of what constitutes invalid input or may make a mistake while providing input, for instance, non-numeric input where a number is expected or a non-existent choice when choosing among options.
Contextually inappropriate user input: A user may provide input which is not appropriate given the context in which the input is being sought. This can often be the case when prior choices or selections made by the user affect what can be considered valid input. For instance, if an application asks a user to choose her country, any country could constitute a valid input. However, if the application has already asked the user to select a region and she has selected Europe, then a country choice of Canada would be contextually inappropriate. Similarly, if the user has already selected a certain service, only locations where that service is offered would be appropriate choices.
Unavailability of an external system: An external system could be temporarily unavailable or non-responsive. For instance, a network may have a temporary outage or may be busy. It is also possible that an external system such as a persistence mechanism may have failed.
Unexpected behaviour of an external system: An external system may fail to provide the expected response or information. This could be the result of a malfunction, an unexpected configuration change in the external system, lack of the required credentials, etc.
Internal inconsistency or violation of invariants: There could be instances where a combination of external inputs and internal processes, each of which may be valid in isolation, may put our program in an internally inconsistent state. We could also have cases where actions taken by individual modules of a larger system, which may be valid in the context of each module, may violate invariants at the overall system level.

Preventing errors

Programs should be designed, wherever practicable, to try and prevent errors.

Structuring and validating user input: Structuring user input with radio buttons, check boxes, slider controls, etc., can limit the type or range of input a user can provide. Even freeform input should be validated where appropriate. To guard against contextually inappropriate input, funnels can be created which use options selected earlier to limit the input a user can provide to a given prompt. To use our earlier example, if a user selects Europe as the region, only countries in Europe should be presented for the next selection. Similarly, if a certain type of service has been selected, only locations where that service is offered should be available for selection.
Prompts and warnings: Users can be prompted to reconfirm input provided. This can be done for each screen or related information provided over various screens can be summarized for verification. A warning prompt may be appropriate before committing irreversible changes or before accessing an external system, such as a network, which may not always be available. To maintain a balance between error prevention and streamlined user experience, users can be given the ability to disable certain prompts and warnings. Alternatively, a program may be able to adapt based on the frequency of a particular error for a certain user or group of users.
Instructions and context-sensitive help: Assisting users in navigating the application by providing appropriate instructions and context-sensitive help can greatly aid in minimizing instances of users selecting inappropriate options or providing erroneous input.
Consistency: Consistency is important not only for enhancing user experience but also for minimizing errors. From consistent screen design, so the same action is triggered in the same or similar way, to standardizing how users navigate through the application, when and how prompts and warnings are displayed and how users can seek help, it is best to choose one style and stick to it.

Handling errors

Whilst we should always design applications with error prevention as an objective, errors are inevitable in any real-world application. A robust mechanism to gracefully recover from errors is thus an essential part of application design.

The elegance of code is in maintaining as light a touch as possible in handling errors. Unnecessary or unnecessarily complex error-handling code can obfuscate the natural flow of application logic. The normal pathway through the application should always be clear, with errors and exceptional processing handled as simply and as unobtrusively as possible.

1. User experience considerations

From a user experience perspective, it is important that error handling should blend as seamlessly as possible into the natural flow of the application. It should not stand out like something the application designer did not expect or had not planned for. User interface elements such as screens, dialogs, popups, etc., used to indicate and recover from errors should fit with the overall theme of the application. While it is natural to want to make error situations stand out in some way to capture user attention, user interface elements used to handle errors should not appear as an afterthought or as something bolted on after the application had been designed.

Error handling code should explain, in as much detail as is appropriate, why a certain error occurred, what the user should do to get back to the normal flow of the application and, optionally, what steps the user could take to prevent recurrence.

2. Where to put error handling code

It is generally good practice to handle errors as close to the source as practically possible. However, given the architecture of modern applications, it is desirable in most situations to push errors some way up the call chain to get to a place where it is appropriate to handle them.

The reason for not handling errors as soon as they occur has to do with the architectural goal of separating user interface control from domain logic and infrastructure. With this separation of concerns, an error encountered in the model layer, which contains domain logic and business rules, or in the infrastructure layer, which deals with networking, persistence, etc., must be captured in an appropriate way along with the information required to effectively respond to it.

The error and the associated information then needs to be propagated back up the call chain to a place where it is appropriate to handle the user interaction required to report and suitably recover from the error. It is important, however, not to unnecessarily propagate errors and to deal with them as close to the source as possible within the context of the architecture pattern being used.

Using optionals for simple error handling

There are situations where we expect a function, method, initializer or closure to return an instance of a type but we also want to account for the possibility of failure. This could be the result of calling a function that is expected but not guaranteed to return an instance of a type, or an initializer that may fail to create a valid instance under certain circumstances. For simple operations where the reason for the error can be discerned from the context, it can be quite efficient to return an optional wrapping an instance of the expected type when the operation succeeds and return nil to indicate an error.

Let’s consider a class that models a person. For the sake of simplicity, let’s assume we record just the name of each person. We want to ensure, however, that an instance is created only if the name provided is not blank. Otherwise, the calling code should be notified that an instance could not be created. To accomplish this, we can use a failable initializer, which will either return an optional wrapping a Person instance or return nil.

class Person {
    init?(named name: String) {
        guard !name.isEmpty else { return nil }
        self.name = name
    }
    
    let name: String
}

The calling code can safely unwrap the result using optional binding.

func personCreationTester(name: String) {
    if let person = Person(named: name) {
        print("Created person named \(person.name)")
    } else {
        print("Person creation failed. Name is blank")
    }
}

personCreationTester(name: "Laura") // Created person named Laura
personCreationTester(name: "")      // Person creation failed. Name is blank

Use of optionals to indicate simple errors is a common feature in the Swift Standard Library as well. The Collection protocol, for instance, defines an index(of:) method that returns the first index where the specified value appears in the collection, returning nil if the value is not found.

Here, we demonstrate it with an array.

func arrayIndexTester(number: Int) {
    let numbers = [1, 2, 3]
    if let index = numbers.index(of: number) {
        print("Index of \(number) is \(index)")
    } else {
        print("\(number) is not in the array")
    }
}

arrayIndexTester(number: 2)     // Index of 2 is 1
arrayIndexTester(number: 4)     // 4 is not in the array

This basic form of error handling works quite well for simple operations with a return value and a single known point of failure. However, a number of operations in real-world applications are more complex and may have multiple points of failure. The calling code would likely need to know why a certain operation failed to be able to take appropriate action.

For such cases, we turn to the error handling mechanism built into Swift.

Representing errors

Errors in Swift are modeled using a type that conforms to the Error protocol. It is an empty protocol so there are no properties or methods to implement. It just indicates that a type can be used for error handling.

Swift enums are particularly suited to modeling errors. We define an enum that conforms to Error. Each case of the enum represents one error case. Where required, associated values can be used to provide supplementary information related to the error. As an example, when an error is thrown because a value is outside the permitted range for an operation, associated values can be used to indicate the upper and lower bonds of the permitted range. This can help create error messages that explain to the user why the error occurred and how to take corrective action.

Another use of associated values could be to encapsulate errors thrown at a lower level of abstraction or by methods dealing with infrastructure or third-party APIs. If methods at a higher level of abstraction simply propagate errors thrown by a lower-level abstraction or by a call to infrastructure services, third-party APIs, etc., it would pollute the higher-level API and expose implementation details. Errors thrown by lower layers should normally be caught and errors appropriate to the abstraction thrown in their place, with associated values used, where required, to preserve the underlying error.

Let’s suppose we are working in a domain dealing with enrollment of students in courses offered by a university. Students must be registered before they can enroll in any course. Their basic information is captured at the time of registration. Students may become inactive for a certain period of time due to non-payment of fees, suspension, extended leave of absence, etc. Inactive students are not allowed to enroll in courses. All students have a current level of achievement, which is used to determine whether they are eligible to enroll for a certain course, each of which has a minimum required level of achievement.

An attempt to enroll a student in a course may fail for three reasons. The student may be inactive, the course may already be full, or the student may not meet the minimum required achievement level. We define an EnrollmentError enum to represent these three error cases.

enum EnrollmentError: Error {
    case inactiveStudent
    case courseFull
    case doesNotMeetMinLevel(Int)
}

Note the use of an associated value to provide supplementary information for the error case where the minimum achievement level is not met.

Throwing errors

Errors can be thrown using the keyword throw. For example, an error to indicate that a course is full would be thrown like this.

throw EnrollmentError.courseFull

Once an error has been thrown, it must be dealt with in some way. An error thrown inside a function can be handled in the same function. However, as noted in an earlier section, there is often a need to pass errors thrown inside a function up the call chain to a place where it is more appropriate to handle them. This can be done by adding the keyword throws to the function’s signature, immediately after the closing parenthesis of the parameter list and before the return arrow, if one is present. This has the effect of throwing errors, which are not handled by the same function, up the call chain to the scope from where the function was called. A function with the keyword throws in its signature is called a throwing function.

Swift functions, methods, closures and initializers can all throw errors. For the sake of brevity, in the remainder of this post, the term throwing function will be used to refer to any function, method, closure or initializer that can throw errors.

Continuing our example of enrolling students in courses, we define a class to model a student. For every student, we record the name and the current level of achievement. All newly created students are active by default. Each student also has an ID. In a real-world application, students may be assigned unique IDs that are meaningful from a domain perspective, reflecting information such as year of graduation, department code, etc. For our purposes, we just use an instance of UUID to generate a unique value for each student.

class Student {
    init(named name: String, level: Int) {
        self.name = name
        self.level = level
    }
    
    let id = UUID()
    let name: String
    var level: Int
    var active = true
}

Next, we define a class to model a course, which has properties to store the name of the course, minimum achievement level required to enroll in the course and course capacity. Each course also has a unique ID. As with students, while courses in a real application may have domain-relevant IDs, for our purposes, we just use an instance of UUID.

We also give the class a method to enroll students in the course. We define a lightweight Enrollment type to capture the IDs of the student and the course for each successful enrollment. The enroll(_:) method throws the appropriate error if the student attempting to enroll in a course does not meet the minimum achievement level for the course.

typealias Enrollment = (studentId: UUID, courseId: UUID)

class Course {
    init(named name: String, minLevel: Int, capacity: Int) {
        self.name = name
        self.minLevel = minLevel
        self.capacity = capacity
    }
    
    func enroll(_ student: Student) throws -> Enrollment {
        guard student.level >= minLevel else {
            throw EnrollmentError.doesNotMeetMinLevel(minLevel)
        }
        return (studentId: student.id, courseId: id)
    }
    
    let id = UUID()
    let name: String
    let minLevel: Int
    let capacity: Int
}

Note the keyword throws in the signature of the method.

Propagating errors

A function that calls a throwing function is not required to handle any errors that may be thrown. It can simply propagate the errors, i.e., pass them up the call chain, to be handled elsewhere. To be able to propagate errors, a function must itself be throwing. Inside a throwing function, we prefix any expression that may throw an error with the try keyword. An expression prefixed with try is called a try expression.

To demonstrate this, we define a Registrar class, which has a method to enroll a student in a course. It first checks if the student is inactive or if the course is already full and throws appropriate errors as required. It then uses a try expression to call the enroll(_:) method on the course instance and stores the resulting Enrollment in a list of valid enrollments. Since the function itself is throwing, any error that may be thrown in the try expression is simply propagated.

class Registrar {
    func enroll(_ student: Student, in course: Course) throws {
        guard student.active else {
            throw EnrollmentError.inactiveStudent
        }
        guard isNotFull(course) else {
            throw EnrollmentError.courseFull
        }
        let enrollment = try course.enroll(student)
        enrollments.append(enrollment)
    }
    
    private func isNotFull(_ course: Course) -> Bool {
        return enrollments.filter({ $0.courseId == course.id }).count < course.capacity
    }
    
    private var enrollments: [Enrollment] = []
}

Note that, from the perspective of any code calling the above method, it can throw all three cases of EnrollmentError. The fact that two of the error cases are thrown inside the method and one is just propagated is not relevant.

Catching errors

All errors thrown by our code must be handled somewhere. If an error is not handled and keeps on getting propagated, it will eventually bubble all the way up the call stack, causing the application to crash. It is advisable, therefore, to keep track of errors being thrown and to handle them as soon as it is appropriate to do so.

To handle errors, we first catch them by means of a do-catch statement. This consists of a do clause, within which any statement or function call that can throw an error must appear in a try expression. The do clause is immediately followed by one or more catch clauses, each of which may match one or more errors using pattern matching. A catch clause may also include a where clause, allowing more specific matching behaviour.

Here is the general form of the do-catch statement.

do {
    try expression
    statements
} catch pattern 1 {
    statements
} catch pattern 2 where condition {
    statements
} catch {
    statements
}

Note the last catch clause, which does not contain any pattern. This will match any error and bind it to a local constant named error.

If no error is thrown in a do clause, execution continues along the same path and all catch clauses which are part of the same do-catch statement are skipped. If an error is thrown by any try expression, no further code in the enclosing do clause is executed and the catch clauses are evaluated in the order in which they appear to see which one matches the error. The first catch clause that matches the error is executed and the remaining ones are skipped. If no catch clause matches the error, the error is transferred to the surrounding scope, where it must either be handled by an enclosing do-catch statement or propagated.

To demonstrate catching errors, we define a method to test enrolling students in a course. This method uses an instance of Registrar to try and enroll students, catching all the errors thrown and printing appropriate messages to the console.

func testEnroll(_ students: [Student], in course: Course, using registrar: Registrar) {
    for student in students {
        do {
            try registrar.enroll(student, in: course)
            print("Successfully enrolled \(student.name) in "\(course.name)"")
        } catch EnrollmentError.inactiveStudent {
            print("\(student.name) is not an active student")
        } catch EnrollmentError.courseFull {
            print("Could not enroll \(student.name). Course is full")
        } catch EnrollmentError.doesNotMeetMinLevel(let minLevel) {
            print("Could not enroll \(student.name). Must at least be at level \(minLevel)")
        } catch {
            print("Unknown error")
        }
    }
}

Note the last catch clause, without which this code will not compile. This may seem counter-intuitive since we have only one error type and all of its cases are matched by the first three catch clauses. It is important to bear in mind, however, that errors in Swift are not typed. All the compiler knows is that errors thrown will be of a type that conforms to Error. The only way it has to ensure that all error cases will be matched is to insist on having the mop-up catch clause.

Here is some code to test the enrollment process.

let swiftBasics = Course(named: "Swift Basics", minLevel: 5, capacity: 2)
var students = [
    Student(named: "Laura", level: 6),
    Student(named: "Chris", level: 5),
    Student(named: "Charles", level: 4),
    Student(named: "Paul", level: 7),
    Student(named: "Jenna", level: 8)]
students[1].active = false
var registrar = Registrar()
testEnroll(students, in: swiftBasics, using: registrar)
// Successfully enrolled Laura in "Swift Basics"
// Chris is not an active student
// Could not enroll Charles. Must at least be at level 5
// Successfully enrolled Paul in "Swift Basics"
// Could not enroll Jenna. Course is full

Of the five students we tried to enroll above, only Laura and Paul were successfully enrolled. Chris was denied because his active status was revoked and Charles fell short of the minimum required achievement level. Jenna met the course requirements but could not be enrolled because the course capacity had already been reached.

Selectively propagating errors

A function that calls a throwing function may catch certain errors and propagate others. Such a function must be a throwing function to be able to propagate errors that it does not handle. Errors that get propagated may include errors thrown in one or more try expressions enclosed in do-catch statements, which are not matched by any of the catch clauses, as well as errors thrown in one or more try expressions that appear outside do-catch statements.

To demonstrate a throwing function that selectively handles some errors, we modify the Registrar class to give it a list of students who can exceptionally be enrolled in a course, provided they are only one short of the minimum achievement level required. We add a do-catch statement to the enroll(_:in:) method to catch errors related to minimum achievement level, using a where clause to match achievement level errors only if the achievement level of the student is exactly one below the required minimum and the student is included in the list of exceptions. The catch block ensures that such students are also enrolled in the course. All other errors are propagated as before.

class Registrar {
    func enroll(_ student: Student, in course: Course) throws {
        guard student.active else {
            throw EnrollmentError.inactiveStudent
        }
        guard isNotFull(course) else {
            throw EnrollmentError.courseFull
        }
        var enrollment: Enrollment
        do {
            enrollment = try course.enroll(student)
        } catch EnrollmentError.doesNotMeetMinLevel(let minLevel) where qualifiesForException(student, minLevel) {
            enrollment = (studentId: student.id, courseId: course.id)
        }
        enrollments.append(enrollment)
    }
    
    private func isNotFull(_ course: Course) -> Bool {
        return enrollments.filter({ $0.courseId == course.id }).count < course.capacity
    }
    
    private func qualifiesForException(_ student: Student, _ minLevel: Int) -> Bool {
        return (minLevel - student.level) == 1 && exceptions.contains(student.id)
    }
    
    private var enrollments: [Enrollment] = []
    var exceptions: [UUID] = []
}

Let’s see how this works.

let unitTesting = Course(named: "Unit Testing", minLevel: 5, capacity: 2)
students = [
    Student(named: "Mary", level: 4),
    Student(named: "Pauline", level: 4)]
registrar.exceptions.append(students[1].id)
testEnroll(students, in: unitTesting, using: registrar)
// Could not enroll Mary. Must at least be at level 5
// Successfully enrolled Pauline in "Unit Testing"

Both Mary and Pauline have an achievement level one below the minimum requirement and as such they should not be allowed to register for the course. Pauline, however, has been added to the exceptions array in the Registrar instance. When the code above is run, the error related to minimum achievement level for Pauline is caught by the Registrar instance. In the case of Mary, the Registrar instance just propagates the error.

Try vs. try? vs. try!

So far, we have seen only the try keyword, which requires handling the error in some way, either by catching it with a do-catch statement or propagating it by marking the function as throwing. There are two other flavours of try that can be used to deal with errors without catching or propagating them, so they don’t need to appear inside a do-catch statement or a throwing function.

1. Converting errors to optionals with try?

The try? keyword can be used to convert an error into an optional. If an error is thrown inside a try? expression, the expression evaluates to nil. If there is no error, the expression evaluates to an optional wrapping the value of the expression.

This comes in handy in situations where a particular use case only requires knowing whether an error got thrown and not which error it was. It can also be useful, for instance, when using frameworks and third-party libraries where we may not be interested in the details of some of the errors thrown but only in whether an operation failed.

To demonstrate, we define an error type with a single error case. We also define two throwing functions, only one of which actually throws an error.

enum TestError: Error {
    case someError
}

func canThrowButDoesNot() throws -> String {
    return "My string"
}

func canAndDoesThrow() throws -> String {
    throw TestError.someError
}

We use the above functions to see the result of a try? expression, when the throwing function actually throws an error and when it does not.

print((try? canThrowButDoesNot()) ?? "nil")     // My string
print((try? canAndDoesThrow()) ?? "nil")        // nil

When an error does not get thrown, we get an optional wrapping a string, which we unwrap using the ?? (nil-coalescing) operator. When an error does get thrown, we get nil.

2. Asserting that errors will not occur with try!

The try! keyword can be used to assert that an error will not be thrown. If there is no error, execution continues normally. If, however, an error does get thrown in a try! expression, the application will crash.

We can test the use of try! using the same functions we used above.

// Using try! is dangerous. Will cause a crash if error is thrown
print(try! canThrowButDoesNot())    // My string
print(try! canAndDoesThrow())       // Crash!!!

When no error is thrown, we get a String (not an optional wrapping a String). When an error does get thrown, our application crashes and burns.

Using try! is akin to forced unwrapping of an optional, which I would advise avoiding altogether. Swift provides a plethora of language features and associated techniques to work safely with optionals. Using try? and working with the resulting optional can lead to safer and more robust code.

Even in cases where we want to assert that an error should only occur if the application is unable to continue executing, we should not use try! as it will abruptly crash the application. It is advisable in such scenarios to use try?. This way, we get the opportunity to terminate the application in as orderly a manner as possible, as already explained in the section dealing with unrecoverable errors.

Throws vs. rethrows

We have already seen that a function that contains code that throws errors but does not handle all possible errors must itself be a throwing function, to be able to propagate any errors that don’t get handled. But what about a function that does not itself contain code that throws errors but takes a throwing closure as a parameter. Such a function could be given as an argument a closure that can throw but also a closure that cannot throw.

If the argument is a closure that can throw, the function should only be called with one of the flavours of try. However, if the argument is a closure that cannot throw, we should be able to call the function normally. Marking such a function with throws is not appropriate and we need another way.

Swift provides an elegant solution to this problem with the keyword rethrows, which is used for functions that take throwing closures as parameters. It indicates that the function can throw if the closure passed as the argument can throw. In such a case, any call to the rethrowing function must be annotated with one of the flavours of try. However, it can be called like a normal function when the closure passed as the argument cannot throw.

To demonstrate this, we define a function that takes as its only parameter a closure that returns a string but can also throw. The body of the function simply executes the closure and returns the same string.

func throwingClosureExpecter(closure: () throws -> String) rethrows -> String {
    return try closure()
}

Note the rethrows keyword in the function signature immediately after the closing parenthesis of the parameter list and before the return arrow. This indicates that the function may or may not throw depending on whether a throwing closure is passed in as the argument.

We need to test the behaviour of this function under three scenarios: When the closure cannot throw, when the closure can throw but does not, and when the closure can and does throw. To do this, we will use the two throwing functions canThrowButDoesNot() and canAndDoesThrow() that we had defined in the last section. For the scenario where the closure cannot throw, we define the following function.

func cannotThrow() -> String {
    return "My string"
}

Now we can test the three scenarios.

print(throwingClosureExpecter(closure: cannotThrow))                            // My string
print((try? throwingClosureExpecter(closure: canThrowButDoesNot)) ?? "nil")     // My string
print((try? throwingClosureExpecter(closure: canAndDoesThrow)) ?? "nil")        // nil

In the first case, we pass in a closure that cannot throw so there is no need for any form of try and our expression simply prints out the string returned by the closure. In the second case, we pass in a closure that can throw so we use a try? expression. Since no error is actually thrown, we get an optional wrapping the string returned by the closure, which we unwrap using the nil coalescing operator. In the final case, we pass in a closure that can and does throw so we again use a try? expression. Since an error is actually thrown, we get nil.

Just to complete the demonstration, we pass in a closure that can throw to our rethrowing function and try calling it without any form of try. The result is a compiler error.

// Compiler error: Call can throw but is not marked with 'try'
print(throwingClosureExpecter(closure: canThrowButDoesNot))    // Does not compile
print(throwingClosureExpecter(closure: canAndDoesThrow))       // Does not compile

It does not matter whether the closure actually throws an error. If the closure can throw, the rethrowing function can also throw and it must be called using some form of try.

It is important to note that a rethrowing function can only throw errors thrown by a closure passed in as an argument. It cannot throw any errors of its own.

Performing clean-up actions with defer

When an error is thrown, the current scope is exited. This could result in skipping clean-up actions that would have been performed had execution continued along the normal path. A defer statement can be used to ensure that certain actions are performed before the current scope is exited. A defer statement can contain as many statements as required and one scope can contain multiple defer statements.

It is noteworthy that defer statements are executed regardless of whether the current scope is exited normally or early due to a return statement, an error being thrown, etc. Defer statements are recognized as they are encountered in the normal execution path. If an early exit gets triggered, only defer statements encountered up to that point are executed prior to exiting the scope. Therefore, all defer statements that need to be executed prior to a particular early exit should be placed before the point where that early exit may occur.

When order of execution is important, we must bear in mind that defer statements are executed in the reverse of the order in which they are encountered during the normal flow of execution. We can think of them as being stored in a stack rather than a queue. Moreover, a defer statement itself cannot cause an early exit, so should not include statements such as return and should not throw errors.

To see how defer works in practice, we define a throwing function that takes a boolean parameter, which determines whether it will throw an error. The function contains three defer statements, each of which just prints a string to the console to indicate that it was executed. Two of the three defer statements appear before the point at which an error may be thrown.

func throwerWithDefer(shouldThrow: Bool) throws {
    defer {
        print("First defer statement executed")
    }
    defer {
        print("Second defer statement executed")
    }
    print("Prior to throw")
    if shouldThrow {
        throw TestError.someError
    }
    print("After throw")
    defer {
        print("Third defer statement executed")
    }
}

We now execute the above function and see the order of execution, first when no error is thrown and then when an error is thrown.

try? throwerWithDefer(shouldThrow: false)
// Prior to throw
// After throw
// Third defer statement executed
// Second defer statement executed
// First defer statement executed

When no error is thrown, the function executes normally and all three defer statements are executed, in reverse order, before the function is exited.

try? throwerWithDefer(shouldThrow: true)
// Prior to throw
// Second defer statement executed
// First defer statement executed

When an error is thrown, it causes an early exit from the function so code that appears after the point at which the error is thrown does not get executed. The first two defer statements, which are placed before the point at which the error is thrown, get executed before the function is exited. The third defer statement, which is placed after the point at which the error is thrown, does not get executed.

Errors and polymorphism

Polymorphism allows us to program to interfaces rather then implementations. With object-oriented programming, this is made possible by inheritance; with protocol-oriented programming, by making types conform to protocols. For polymorphism and abstraction to work correctly, our subclasses and conforming types should comply with the Liskov Substitution Principle, which requires that we should be able to freely substitute any subclass instance where a superclass type is expected and, by extension, any conforming type instance where a protocol type is expected.

In the context of methods that can throw, this means the following:

If a method in a class cannot throw, it cannot be overridden in a subclass by a throwing method. Similarly, a protocol requirement for a method that cannot throw cannot be satisfied with a throwing method. This is because code that calls a method that cannot throw does not need to handle or propagate errors. If the same method can be overridden by a subclass or implemented by a conforming type as a throwing method, it will break client code since it will end up calling a throwing method without being able to handle errors.
If a method in a class can throw, it can be overridden in a subclass by throwing method as well as a method that cannot throw. Similarly, a protocol requirement for a throwing method can be satisfied with a throwing method as well as a method that cannot throw. This is because code that calls a throwing method must be able to handle or propagate errors and it should be able to deal with situations when an error is thrown and when it isn’t. Therefore, such a method can be overridden by a subclass or implemented by a conforming type as a throwing method or a method that cannot throw without breaking any client code.

Here is some code to demonstrate the above with protocols and structs. It can easily be rewritten for class inheritance as well.

protocol X {
    func someFunc()
}

// Compiler error: Type 'A' does not conform to protocol 'X'
struct A: X {
    func someFunc() throws {}
}

Our attempt to satisfy the protocol requirement for a method that cannot throw with a throwing method is met with a compiler error.

protocol Y {
    func anotherFunc() throws
}

struct B: Y {
    func anotherFunc() throws {}
}

struct C: Y {
    func anotherFunc() {}
}

A protocol requirement for a throwing method can be satisfied by a throwing method as well as a method that cannot throw.

Conclusion

Swift provides excellent error handling capabilities. We can represent various cases for each error, use the error cases to encapsulate related information, throw the errors, propagate them and, when appropriate, catch them using pattern matching. We can even convert errors to optionals, suppress them or simply assert that they will not occur. This can enable us to build robust and relatively unobtrusive error handling right into our applications.

It is important to remember though that we should always think about how to prevent errors in the first place. For this, we need to understand the sources of errors, both in a general sense and in ways that are specific to a particular application. The sweet spot lies in achieving the right balance between error prevention and error handling. This is not always easy and takes experience to get right, but the payoff in usability and resilience should be well worth the effort.

Thank you for reading! I always appreciate constructive comments and feedback. Please feel free to leave a comment in the comments section of this post or start a discussion on Twitter.

Articles

Contents

The Equatable protocol

When to conform to Equatable

Modeling values using Swift value types

The Identifiable protocol

When to conform to Identifiable

Modeling entities with identity using Swift value types

Conclusion

Contents

What is optional chaining

Uses of optional chaining

1. Setting and retrieving the value of a property of the wrapped instance

2. Setting and retrieving a value from a subscript on the wrapped instance

3. Calling a method on the wrapped instance

Optional chains fail gracefully

1. Failure of an optional chain to retrieve or return a value

2. Failure of an optional chain to call a method that does not return a value

3. Failure of an optional chain to set a value

Optionals wrapping optionals

Conclusion

Contents

What is an associated type

How not to use protocols with associated types

A protocol-oriented way to use associated types

A protocol-oriented alternative to associated types

Use of associated types in the standard library

What is a Self requirement in a protocol

A protocol-oriented approach to using Self requirements

Use of Self requirements in the standard library

Other advantages of protocol-oriented design

1. Dealing with exceptional conditions

2. Extending the domain

Conclusion

Contents

Designing with value and reference types

Representing immutable state

Dealing with mutable state

1. Swift value types and mutability

2. Controlling mutability of value types

The interplay of value and reference types

Usage considerations

Benefits

1. Separation of concerns

2. Testability

3. Efficiency

4. Concurrency

Conclusion

Contents

Finite state machines

State pattern

1. Intent

2. Structure and participants

State machine diagram

1. States, events and transitions

2. Entry and exit activities for states

3. Transition effects and guard conditions

State Pattern implementation

1. The Context type

2. The State interface

3. The Context type revisited

4. Concrete state types

5. Test run

Dealing with Change

1. Adding a transition

2. Adding properties to concrete state types

3. Adding a transition effect

4. Adding a new state

Key design and implementation considerations

1. Handling state transitions

2. States with state

3. Creating states

4. Events and activities not applicable to certain states

5. Specifying activities in states or transitions

Benefits of the State pattern

1. Clear control flow

2. Partitioning behaviour

3. Flexibility and extensibility

Practical applications of the State pattern

1. Database updates