Swift structs can provide mutating and nonmutating versions of their functions. However, the Swift standard library is inconsistent about when it provides one form of a function or the other. Some APIs come in only mutating forms, some come only in nonmutating, and some come in both. Because both types of functions are useful in different situations, I argue that almost all such functions should have both versions provided. In this post, we’ll examine when these different forms are useful, examples APIs that provide one but not the other, and solutions for this problem.
(Quick sidebar here: I’ll be referring to functions that return a new struct with some field changed as nonmutating functions. Unfortunately, Swift also includes a keyword called nonmutating, which is designed for property setters that don’t require the struct to be copied when they’re set. Because I think that nonmutating is the best word to describe functions that return an altered copy of the original, I’ll keep using that language here. Apologies for the confusion.)
Mutating and Nonmutating Forms
These two forms, mutating and nonmutating, are useful in different cases. First, let’s look at when the nonmutating version is more useful.
This code, taken from Beacon’s OAuthSignatureGenerator, uses a long chain of immutable functions to make its code cleaner and more uniform:
public var authorizationHeader: String {
let headerComponents = authorizationParameters
.dictionaryByAdding("oauth_signature", value: self.oauthSignature)
.urlEncodedQueryPairs(using: self.dataEncoding)
.map({ pair in "\(pair.0)=\"\(pair.1)\"" })
.sorted()
.joined(separator: ", ")
return "OAuth " + headerComponents
}
However, it wouldn’t be possible without an extension adding dictionaryByAdding(_:,value:), the nonmutating version of the subscript setter.
Here’s another, slightly more academic example. Inverting a binary tree is more commonly a punchline for bad interviews than practically useful, but the algorithm illustrates this point nicely. To start, let’s define a binary tree an enum like so:
indirect enum TreeNode<Element> {
case children(left: TreeNode<Element>, right: TreeNode<Element>, value: Element)
case leaf(value: Element)
}
To invert this binary tree, the tree on the left goes on the right, and the tree on right goes on the left. The recursive form of nonmutating version is simple and elegant:
extension TreeNode {
func inverted() -> TreeNode<Element> {
switch self {
case let .children(left, right, value):
return .children(left: right.inverted(), right: left.inverted(), value: value)
case let .leaf(value: value):
return .leaf(value: value)
}
}
}
Whereas the recursive mutating version contains lots of extra noise and nonsense:
extension TreeNode {
mutating func invert() {
switch self {
case let .children(left, right, value):
var rightCopy = right
rightCopy.invert()
var leftCopy = left
leftCopy.invert()
self = .children(left: rightCopy, right: leftCopy, value: value)
case .leaf(value: _):
break
}
}
}
Mutating functions are also useful, albeit in different contexts. We primarily work in apps that have a lot of state, and sometimes that state is represented by data in structs. When mutating that state, we often want to do it in place. Swift gives us lots of first class affordances for this: the mutating keyword was added especially for this behavior, and changing any property on a struct acts as a mutating function as well, reassigning the reference to a new copy of the struct with the value changed.
There are concrete examples as well. If you’re animating a CGAffineTransform on a view, that code currently has to look something like this.
UIView.animate(duration: 0.25, animations: {
view.transform = view.transform.rotated(by: .pi)
})
Because the transformation APIs are all nonmutating, you have to manually assign the struct back to the original reference, causing duplicated, ugly code. If there were a mutating rotate(by:) function, then this code would be much cleaner:
UIView.animate(duration: 0.25, animations: {
view.transform.rotate(by: .pi)
})
The APIs aren’t consistent
The primary problem here is that while both mutating functions and nonmutating functions are useful, not all APIs provide versions for both.
Some APIs include only mutating APIs. This is common with collections. Both the APIs for adding items to collections, like Array.append, Dictionary.subscript, Set.insert, and APIs for removing items from collections, like Array.remove(at:), Dictionary.removeValue(forKey:), and Set.remove, have this issue.
Some APIs include only nonmutating APIs. filter and map are defined on Sequence, and they return arrays, so they can’t be mutating (because Sequence objects can’t necessarily be mutated). However, we could have a mutating filterInPlace function on Array. The aforementioned CGAffineTransform functions also fall in this category. They only include nonmutating versions, which is great for representing a CGAffineTransform as a chain of transformations, but not so great for mutating an existing transform, say, on a view.
Some APIs provide both. I think sorting is a great example of getting this right. Sequence includes sorted(by:), which is a nonmutating function that returns a sorted array, whereas MutableCollection (the first protocol in the Sequence and Collection heirarchy that allows mutation) includes sort(by:). This way, users of the API can choose whether they want a mutating sort or a nonmutating sort, and they’re available in the API where they’re first possible. Array, of course, conforms to MutableCollection and Sequence, so it gets both of them.
Another example of an API that gets this right: Set includes union (nonmutating) and formUnion (mutating). (I could quibble with these names, but I’m happy that both version of the API exist.) Swift 4’s new Dictionary merging APIs also include both merge(_:uniquingKeysWith:) and merging(_:uniquingKeysWith:).
Bridging Between the Two
The interesting thing with this problem is that, because of the way Swift is designed, it’s really easy to bridge from one form to the other. If you have the mutating version of any function:
mutating func mutatingVersion() { ... }
You can synthesize a nonmutating version:
func nonMutatingVersion() -> Self {
var copy = self
copy.mutatingVersion()
return copy
}
And vice versa, if you already have a nonmutating version:
func nonMutatingVersion() -> Self { ... }
mutating func mutatingVersion() {
self = self.nonMutatingVersion()
}
As long as the type returned by the nonmutating version is the same as Self, this trick works for any API, which is awesome. The only thing you really need is the new name for the alternate version.
Leaning on the Compiler
With this, I think it should be possible to have the compiler trivially synthesize one version from the other for us. Imagine something like this:
extension Array {
@synthesizeNonmutating(appending(_:))
mutating func append(_ newElement) {
// ...
}
}
The compiler would use the same trick above — create a copy, mutate the copy, and return it — to synthesize a nonmutating version of this function. You could also have a @synthesizeMutating keyword. Types could of course choose not to use this shorthand, which they might do in instances where there are there are optimizations for one form or another. However, getting tooling like this means that API designers no longer have to consider whether they’re APIs are likely to be used in mutating or nonmutating ways, and they can easily add both forms. Because each form is useful in different contexts, providing both allows the consumer of an API to choose which form they want and when.
