20.
Result Builders
Written by Eli Ganim
Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as text.
Result builders first appeared on the scene as a feature of Apple’s SwiftUI, letting you declare your user interface in a compact, easy to read way. It was since expanded as a general language feature that lets you build values by combining a sequence of expressions. Using result builders to define things like HTML documents and database schemas could become commonplace in the future.
In this chapter, you’ll make a result builder to declaratively define attributed strings in a way that is cleaner and more readable than if you built it imperatively using a long sequence of mutating functions. You’ll also use techniques from Chapter 16, “Protocols”, like extensions and typealias, to give your builder code extra clarity.
Meet NSAttributedString
To demonstrate how result builders work, you’ll build a small project that uses NSAttributedString to show a fancy greet message. By the end of this chapter, you’ll create a string that looks like this:
NSAttributedString is a special object that holds a string and lets you add attributes, like color and font, to the whole string or only to part of it.
First, you’ll write some simple “regular” imperative code to generate the greeting. Later, you’ll convert that code to use a result builder.
Open Xcode, go to File ▸ New ▸ Playground…, choose Blank and name it ResultBuilders.
Enter this function into the playground:
func greet(name: String) -> NSAttributedString {
let message = NSAttributedString(string: "Hello " + name)
return message
}
Now, call the function by adding greet(name: "Daenerys") below it. Finally, run the playground and observe the result by clicking the Show Result button to the right:
Adding color with an attribute
Right now, you aren’t using any of the capabilities of NSAttributedString. You’ll change that by adding some color to the greeting message by using an attribute.
func greet(name: String) -> NSAttributedString {
let attributes = [NSAttributedString.Key.foregroundColor : UIColor.red]
let message = NSAttributedString(string: "Hello " + name, attributes: attributes)
return message
}
Adding color to a specific string
What if you wanted to change only the text color of the name of the person you’re greeting and not the word “Hello”? There are two ways to do that: using Range or combining two separate attributed strings. Here, you’ll use the second approach because it’s easier to understand.
let message = NSMutableAttributedString()
message.append(NSAttributedString(string: "Hello "))
message.append(NSAttributedString(string: name, attributes: attributes))
Adding another attributed string
If you want to add another string to the mix — for example, one with a different font size — you need yet another attributed string. Add the following code before the return statement:
let attributes2 = [
NSAttributedString.Key.font : UIFont.systemFont(ofSize: 20),
NSAttributedString.Key.foregroundColor : UIColor.blue
]
message.append(NSAttributedString(string: ", Mother of Dragons", attributes: attributes2))
func greet(name: String) -> NSAttributedString {
NSAttributedString(string: "Hello ")
NSAttributedString(string: name, attributes: ...)
NSAttributedString(string: ", Mother of Dragons", attributes: ...)
}
Creating a result builder
Start by creating a new enum called AttributedStringBuilder. To make it an actual result builder, you need to use the @resultBuilder annotation, which goes above the enum definition.
@resultBuilder
enum AttributedStringBuilder {
}
static func buildBlock(_ components: NSAttributedString...) -> NSAttributedString {
}
let attributedString = NSMutableAttributedString()
for component in components {
attributedString.append(component)
}
return attributedString
Building the greeting string with the result builder
Now, you’ll use the result builder to construct the same greeting string you created earlier by creating a new method.
@AttributedStringBuilder
func greetBuilder(name: String) -> NSAttributedString {
}
@AttributedStringBuilder
func greetBuilder(name: String) -> NSAttributedString {
NSMutableAttributedString(string: "Hello ")
NSMutableAttributedString(string: name)
NSMutableAttributedString(string: ", Mother of Dragons")
}
greetBuilder(name: "Daenerys")
Improving readability by using extensions and type aliases
Earlier in the chapter, you applied attributes like color and font size by creating a dictionary of attributes and then using that dictionary in the attributed string initializer. Now, you’ll use a fancier approach that makes the code much more readable.
extension NSMutableAttributedString {
public func color(_ color : UIColor) -> NSMutableAttributedString {
self.addAttribute(NSAttributedString.Key.foregroundColor,
value: color,
range: NSRange(location: 0, length: self.length))
return self
}
public func font(_ font : UIFont) -> NSMutableAttributedString {
self.addAttribute(NSAttributedString.Key.font,
value: font,
range: NSRange(location: 0, length: self.length))
return self
}
}
let name = NSMutableAttributedString(string: "Daenerys").color(.blue)
Adding fonts and color
Now, go back to greetBuilder, which you created earlier, and use some fonts and color! Replace it with this:
@AttributedStringBuilder
func greetBuilder(name: String, title: String) -> NSAttributedString {
NSMutableAttributedString(string: "Hello ")
NSMutableAttributedString(string: name)
.color(.red)
NSMutableAttributedString(string: ", ")
NSMutableAttributedString(string: title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
greetBuilder(name: "Daenerys", title: "Mother of Dragons")
Using typealias
While the result builder code is pretty straightforward, there are too many NSMutableAttributedString floating around. Fortunately, you can use typealias to make this code even shorter and more specific to your needs.
typealias Text = NSMutableAttributedString
@AttributedStringBuilder
func greetBuilder(name: String, title: String) -> NSAttributedString {
Text(string: "Hello ")
Text(string: name)
.color(.red)
Text(string: ", ")
Text(string: title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
convenience init(_ string: String) {
self.init(string: string)
}
@AttributedStringBuilder
func greetBuilder(name: String, title: String) -> NSAttributedString {
Text("Hello ")
Text(name)
.color(.red)
Text(", ")
Text(title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
// For comparison purposes only.
func greet(name: String) -> NSAttributedString {
let attributes = [NSAttributedString.Key.foregroundColor : UIColor.red]
let message = NSMutableAttributedString()
message.append(NSAttributedString(string: "Hello "))
message.append(NSAttributedString(string: name, attributes: attributes))
let attributes2 = [
NSAttributedString.Key.font : UIFont.systemFont(ofSize: 20),
NSAttributedString.Key.foregroundColor : UIColor.blue
]
message.append(NSAttributedString(string: ", Mother of Dragons", attributes: attributes2))
return message
}
Using conditional logic
If you pass in an empty title, you’ll get a weird result that looks like this:
greetBuilder(name: "Daenerys", title: "")
// Hello Daenerys,
if !title.isEmpty {
Text(", ")
Text(title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
static func buildOptional(_ component: NSAttributedString?) -> NSAttributedString {
component ?? NSAttributedString()
}
Using complex conditional logic
Next, you’ll add one final touch: If the title is empty, you’ll make the greet building method append “No title” to the final result. Start by adding an else clause to the existing if statement:
if !title.isEmpty {
...
} else {
Text(", No title")
}
static func buildEither(first component: NSAttributedString) -> NSAttributedString {
component
}
static func buildEither(second component: NSAttributedString) -> NSAttributedString {
component
}
greetBuilder(name: "Daenerys", title: "")
Using loops with result builders
If you’re familiar with Daenerys from the television show “Game of Thrones”, you know she has many titles: Mother of Dragons, Khaleesi, First of Her Name, Breaker of Chains and more. She insists on having all her titles next to her name, so you need support for multiple titles.
@AttributedStringBuilder
func greetBuilder(name: String, titles: [String]) -> NSAttributedString {
Text("Hello ")
Text(name)
.color(.red)
if !titles.isEmpty {
for title in titles {
Text(", ")
Text(title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
} else {
Text(", No title")
}
}
let titles = ["Khaleesi",
"Mhysa",
"First of Her Name",
"Silver Lady",
"The Mother of Dragons"]
greetBuilder(name: "Daenerys", titles: titles)
static func buildArray(_ components: [NSAttributedString]) -> NSAttributedString {
let attributedString = NSMutableAttributedString()
for component in components {
attributedString.append(component)
}
return attributedString
}
Supporting multiple data types
The greeting string is getting long, so you’d like to be able to break each title to a new line. This feature should be simple. Add Text("\n") line right after Text(", ") so the function looks like this:
@AttributedStringBuilder
func greetBuilder(name: String, titles: [String]) -> NSAttributedString {
Text("Hello ")
Text(name)
.color(.red)
if !titles.isEmpty {
for title in titles {
Text(", ")
Text("\n")
Text(title)
.font(.systemFont(ofSize: 20))
.color(.blue)
}
} else {
Text(", No title")
}
}
enum SpecialCharacters {
case lineBreak
case comma
}
static func buildExpression(_ expression: SpecialCharacters) -> NSAttributedString {
switch expression {
case .lineBreak:
return Text("\n")
case .comma:
return Text(",")
}
}
static func buildExpression(_ expression: NSAttributedString) -> NSAttributedString {
expression
}
Key points
Result builders have use beyond Apple’s SwiftUI. Before tackling the vital topic of pattern matching in Chapter 21, “Pattern Matching”, here are the key points to remember.