Swift’s result builders feature is arguably one of the most interesting recent additions to the language, as it plays a core part in making SwiftUI’s declarative, DSL-like API work the way it does. In fact, result builders were first introduced as a semi-official language feature called “function builders” as part of the Swift 5.1 release that accompanied the introduction of SwiftUI, but has since been promoted into a proper part of the language as of Swift 5.4.

In this article, let’s take a closer look at how result builders work and how we can use them, as well as how they can give us some really valuable insights into how SwiftUI’s API operates under the hood.

Please note that the official version of result builders that this article will cover is, at the time of writing, currently in beta as part of Swift 5.4 and Xcode 12.5.

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Setting things up

For me, one of the best ways to truly understand how a given Swift feature works is to actually build something with it, so that’s what we’ll do. As an example, let’s say that we’re working on an app that includes an API for defining various settings — using a Setting type that looks like this:

struct Setting {
    var name: String
    var value: Value
}

extension Setting {
    enum Value {
        case bool(Bool)
        case int(Int)
        case string(String)
        case group([Setting])
    }
}

The above example type uses associated enum values to ensure complete type safety even though various settings can contain different types of values. To learn more about that pattern, check out the Basics article about enums.

Since the above type includes support for nested settings (through its group value), we’re able to use it to construct hierarchies. For example, here we’ve created a dedicated group for all of our settings that are considered experimental:

let settings = [
    Setting(name: "Offline mode", value: .bool(false)),
    Setting(name: "Search page size", value: .int(25)),
    Setting(name: "Experimental", value: .group([
        Setting(name: "Default name", value: .string("Untitled")),
        Setting(name: "Fluid animations", value: .bool(true))
    ]))
]

While there’s certainly nothing really wrong with the above API (in fact, it’s quite nice!), let’s see what it could end up looking like if we were to give it a “result builders makeover” — which in turn could let us transform it into more of a DSL, similar to what SwiftUI offers.

The basics of how result builders work

Like its name implies, Swift’s result builders feature essentially lets us build a result by combining multiple expressions into a single value. Within SwiftUI, that’s used to transform the contents of one of its many containers (such as HStack or VStack) into a single enclosing view, which can be seen by calling the type(of:) function on such a container instance:

import SwiftUI

let stack = VStack {
    Text("Hello")
    Text("World")
    Button("I'm a button") {}
}

// Prints 'VStack<TupleView<(Text, Text, Button<Text>)>>'
print(type(of: stack))

In general, anytime we see TupleView when using SwiftUI, that means that a result builder has been used to combine multiple views into one.

SwiftUI uses a number of different result builder implementations, such as ViewBuilder and SceneBuilder, but since we’re not able to look into the source code for those types, let’s instead build our own result builder for the settings API that we took a look at above.

Just like a property wrapper, a result builder is implemented as a normal Swift type that’s annotated with a special attribute — @resultBuilder in this case. Then, specific method names are used to implement its various capabilities. For example, a method named buildBlock with zero arguments is used to build the result of an empty function or closure:

@resultBuilder
struct SettingsBuilder {
    static func buildBlock() -> [Setting] { [] }
}

The return type of the above function (an array of Setting values in our case) then determines the type of function or closure that our builder can be applied to. For example, we might choose to implement our top-level settings API as a global function that applies our new SettingsBuilder to any closure that was passed into it — like this:

func makeSettings(@SettingsBuilder _ content: () -> [Setting]) -> [Setting] {
    content()
}

With the above in place, we can now call makeSettings with an empty trailing closure and we’ll get an empty array back:

let settings = makeSettings {}

While our new API is not yet very useful, it’s already showed us a few aspects of how result builders work. But now, let’s actually start building some proper results.

Combining multiple values into a single result

To enable our SettingsBuilder to accept input, all that we have to do is to declare additional overloads of buildBlock with arguments matching the input that we’re looking to receive. In our case, we’ll simply implement a single method that accepts a list of Setting values, which we’ll then return as an array — like this:

extension SettingsBuilder {
    static func buildBlock(_ settings: Setting...) -> [Setting] {
        settings
    }
}

Above we’re using a variadic argument list, which SwiftUI can’t currently use, since its View protocol contains an associated type. Instead, SwiftUI’s ViewBuilder defines 10 different overloads of buildBlock, each with a different number of arguments — which is why a SwiftUI view can’t have more than 10 children. However, that limitation does not apply to our SettingsBuilder.

With that new buildBlock overload in place, we’ll now be able to fill any closure that we’re passing to makeSettings with Setting values, and our result builder (with some help from the compiler) will combine all of those expressions into an array, which is then returned:

let settings = makeSettings {
    Setting(name: "Offline mode", value: .bool(false))
    Setting(name: "Search page size", value: .int(25))

    Setting(name: "Experimental", value: .group([
        Setting(name: "Default name", value: .string("Untitled")),
        Setting(name: "Fluid animations", value: .bool(true))
    ]))
}

While the above is arguably already a slight improvement over the inline array that we were previously using, let’s continue to take inspiration from SwiftUI, and also add a result builder-powered API for defining groups. To make that happen, let’s start by defining a new SettingsGroup type that also annotates a closure (this time stored in a property) with the @SettingsBuilder attribute in order to connect it to our result builder:

struct SettingsGroup {
    var name: String
    @SettingsBuilder var settings: () -> [Setting]
}

An alternative approach would’ve been to instead implement a custom initializer (rather than relying on Swift’s memberwise initializers feature) and to then immediately call our settings closure and store its result, rather than storing a reference to the closure itself. That has the benefit of avoiding having to make our closure escaping at the cost of a slightly more verbose implementation that could prove to be a bit more performant, but also less flexible (as the closure will now only be called once, up front):

struct SettingsGroup {
    var name: String
    var settings: [Setting]

    init(name: String,
         @SettingsBuilder builder: () -> [Setting]) {
        self.name = name
        self.settings = builder()
    }
}

With either of the above two implementations in place (let’s go with the first one for now), we’re now able to define groups the exact same way as when defining top-level settings — by simply expressing each nested Setting within a closure, like this:

SettingsGroup(name: "Experimental") {
    Setting(name: "Default name", value: .string("Untitled"))
    Setting(name: "Fluid animations", value: .bool(true))
}

However, if we actually try to place the above group within our makeSettings closure, we’ll end up getting a compiler error — since our result builder’s buildBlock method currently expects a variadic list of Setting values, and our new SettingsGroup is a completely different type.

To fix that issue, let’s introduce a thin abstraction that can be shared between both Setting and SettingsGroup, for example in the shape of a protocol that lets us convert any instance of those types into an array of Setting values:

protocol SettingsConvertible {
    func asSettings() -> [Setting]
}

extension Setting: SettingsConvertible {
    func asSettings() -> [Setting] { [self] }
}

extension SettingsGroup: SettingsConvertible {
    func asSettings() -> [Setting] {
        [Setting(name: name, value: .group(settings()))]
    }
}

Then, we simply have to modify our result builder’s buildBlock implementation to accept SettingsConvertible instances, rather than concrete Setting values, and we’ll then flatten that new argument list using flatMap:

extension SettingsBuilder {
    static func buildBlock(_ values: SettingsConvertible...) -> [Setting] {
        values.flatMap { $0.asSettings() }
    }
}

With the above in place, we can now define all of our settings in a very “SwiftUI-like” way, by constructing groups just like how we’d organize our various SwiftUI views using stacks and other containers:

let settings = makeSettings {
    Setting(name: "Offline mode", value: .bool(false))
    Setting(name: "Search page size", value: .int(25))

    SettingsGroup(name: "Experimental") {
        Setting(name: "Default name", value: .string("Untitled"))
        Setting(name: "Fluid animations", value: .bool(true))
    }
}

Really nice! So the buildBlock overloads that a given result builder contains directly determines what type of expressions that we’ll be able to place within each closure or function that has been annotated to use that builder.

Conditionals

Next, let’s take a look at how we can add support for evaluating conditionals within our result builder-powered closures. Initially, it might seem like that should “just work”, given that Swift itself supports all kinds of different conditionals. However, that’s not the case — so with our current SettingsBuilder implementation we’ll end up getting a compiler error if we try to do something like this:

let shouldShowExperimental: Bool = ...

let settings = makeSettings {
    Setting(name: "Offline mode", value: .bool(false))
    Setting(name: "Search page size", value: .int(25))

    // Compiler error: Closure containing control flow statement
    // cannot be used with result builder 'SettingsBuilder'.
    if shouldShowExperimental {
        SettingsGroup(name: "Experimental") {
            Setting(name: "Default name", value: .string("Untitled"))
            Setting(name: "Fluid animations", value: .bool(true))
        }
    }
}

The above example once again shows us that the code that’s being executed within a result builder-annotated closure isn’t treated the same way as “normal” Swift code — as each expression needs to be explicitly handled by our builder, including conditionals like if statements.

To add that sort of handling code, we’ll need to implement the buildIf method, which is what the compiler will map each stand-alone if statement to. Since each such statement can evaluate to either true or false, we’ll get its body expression passed as an optional — which in our case will look like this:

// Here we extend Array to make it conform to our SettingsConvertible
// protocol, in order to be able to return an empty array from our
// 'buildIf' implementation in case a nil value was passed:
extension Array: SettingsConvertible where Element == Setting {
    func asSettings() -> [Setting] { self }
}

extension SettingsBuilder {
    static func buildIf(_ value: SettingsConvertible?) -> SettingsConvertible {
        value ?? []
    }
}

With the above in place, our if statement from before now works just as we’d expect. But let’s also add support for combined if/else statements, which can be done by implementing two overloads of the buildEither method — one with the parameter label first, and one with second, each corresponding to the first and second branch of a given if/else statement:

extension SettingsBuilder {
    static func buildEither(first: SettingsConvertible) -> SettingsConvertible {
        first
    }

    static func buildEither(second: SettingsConvertible) -> SettingsConvertible {
        second
    }
}

We’ll now be able to add an else clause to our if statement from before, for example in order to let users request access to our app’s experimental settings if those are not yet shown:

let settings = makeSettings {
    Setting(name: "Offline mode", value: .bool(false))
    Setting(name: "Search page size", value: .int(25))

    if shouldShowExperimental {
        SettingsGroup(name: "Experimental") {
            Setting(name: "Default name", value: .string("Untitled"))
            Setting(name: "Fluid animations", value: .bool(true))
        }
    } else {
        Setting(name: "Request experimental access", value: .bool(false))
    }
}

Finally, those buildEither methods that we just implemented now (as of Swift 5.3) also enable switch statements to be used within result builder contexts, without requiring any additional build methods.

So for example, let’s say that we’re looking to refactor our above shouldShowExperimental boolean into an enum, in order to support multiple access levels. We could then simply switch on that enum within our makeSettings closure, and the Swift compiler will automatically route those expressions into our buildEither methods from before:

enum UserAccessLevel {
    case restricted
    case normal
    case experimental
}

let accesssLevel: UserAccessLevel = ...

let settings = makeSettings {
    Setting(name: "Offline mode", value: .bool(false))
    Setting(name: "Search page size", value: .int(25))

    switch accesssLevel {
    case .restricted:
        Setting.Empty()
    case .normal:
        Setting(name: "Request experimental access", value: .bool(false))
    case .experimental:
        SettingsGroup(name: "Experimental") {
            Setting(name: "Default name", value: .string("Untitled"))
            Setting(name: "Fluid animations", value: .bool(true))
        }
    }
}

One additional thing worth noting about the above code is that we’re using a new Setting.Empty type within our switch statement’s .restricted case. That’s because we’re not (yet) able to use the break keyword within a result builder switch statement, so we’ll need to express some kind of value within each code branch. So just like how SwiftUI has EmptyView, our new Settings API now has a Setting.Empty type for those kinds of situations:

extension Setting {
    struct Empty: SettingsConvertible {
        func asSettings() -> [Setting] { [] }
    }
}

And with that, our new result builder-powered settings API is now finished! It’s really quite fascinating just how little code that’s required to build a SwiftUI-like DSL using this new language feature.

Support Swift by Sundell by checking out this sponsor:

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Conclusion

With features like property wrappers and result builders, Swift is moving into some very interesting new territories, by enabling us to add our own logic to various fundamental language mechanisms — like how expressions are evaluated, or how properties are assigned and stored.

Granted, those new features do also make Swift more complicated, even though (at least in the best of worlds), they could also let library designers — both at Apple and in the wider developer community — hide that complexity behind well-formed APIs.

What do you think? Are you looking forward to using result builders within your own code, and did you gain some additional insight into how SwiftUI’s API works by reading this article? If so, feel free to share it, and you’re also more than welcome to contact me (either via Twitter or email) if you have any questions, comments, or feedback.

Thanks for reading! 🚀

Generating formatted string representations of various kinds of values can often be quite tricky, especially if we want those strings to be fully adapted to the user’s language, locale and other system-wide preferences.

Thankfully, Apple ships a quite comprehensive suite of fully localized formatters as part of each of their platforms, and while we’ve already taken a look at the most commonly used among those — like DateFormatter and NumberFormatter — in this article, let’s instead explore some of the lesser-known Formatter subclasses, and how they can prove to be incredibly useful in certain situations.

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Names of people

If there’s one thing that all Formatter types that come built into the system have in common is that they’re all performing tasks that are much more complicated than what they initially might seem like.

Take user names, or names of people in general, as an example. Let’s say that we’re working on an app that stores each user’s full name using a single fullName property defined within a User data model — like this:

struct User {
    var fullName: String
    ...
}

Then, let’s say that we’re currently making the assumption that if we split a given user’s fullName string into space-separated components, then the first component will always be the user’s “first name” — which we then use as that user’s “display name” across our app’s UI:

extension User {
    func displayName() -> String {
        String(fullName.split(separator: " ")[0])
    }
}

The above is an incredibly common mistake to make. Not only does the preferred order of a name’s various components differ between different languages, countries, and cultures around the world — names can also often have many more components than just “first name” and “last name”, which our code currently doesn’t account for.

For example, what if a user entered “Dr. John Appleseed” as their full name? Then that user’s display name would currently be computed as “Dr.”. Not great.

Thankfully, this is a problem that our friends at Apple have already solved. Enter PersonNameComponentsFormatter, which handles all of the complexities involved in correctly parsing and formatting a person’s name. Here’s how we could update our displayName method to use that formatter instead:

extension User {
    func displayName() -> String {
        let formatter = PersonNameComponentsFormatter()
        let components = formatter.personNameComponents(from: fullName)
        return components?.givenName ?? name
    }
}

Not only will the above new version yield results that are much more correct regardless of the user’s name or locale, but the intent of our code is now arguably much more clear as well.

PersonNameComponentsFormatter also enables us to turn a set of name components into a fully localized name as well, which can be incredibly useful when dealing with user names that are already split up into separate components — like this:

struct User {
    var firstName: String
    var lastName: String
    ...
}

extension User {
    func fullName() -> String {
        let formatter = PersonNameComponentsFormatter()

        var components = PersonNameComponents()
        components.givenName = firstName
        components.familyName = lastName

        return formatter.string(from: components)
    }
}

The reason that we’ve implemented all of our name computation code as methods, rather than computed properties, is to clearly show that our logic requires some amount of processing, since it’s not just returning a value that can be computed in O(1) time. To learn more about that approach, check out “Computed properties in Swift”.

Addresses

Next, let’s take a look at a Formatter type that ships as part of the Contacts framework — CNPostalAddressFormatter, which provides an easy way to format addresses into localized strings.

Just like names, the way addresses are supposed to be formatted varies a lot between different countries, and handling all of that complexity ourselves would be quite overwhelming.

As an example, let’s say that we’re working on some form of shopping app that contains the following ShippingAddress type:

struct ShippingAddress {
    var street: String
    var postalCode: String
    var city: String
    var country: String
}

If we now wanted to generate a formatted string representation of such an address (for example to show the user what address that a given product will be shipped to), then all that we have to do is to convert our shipping address data into a CNPostalAddress instance (which can be done using its mutable counterpart, CNMutablePostalAddress), and then ask CNPostalAddressFormatter to convert that instance into a string — like this:

import Contacts

extension ShippingAddress {
    func formattedString() -> String {
        let formatter = CNPostalAddressFormatter()

        let address = CNMutablePostalAddress()
        address.street = street
        address.postalCode = postalCode
        address.city = city
        address.country = country

        return formatter.string(from: address)
    }
}

Of course, if we’re dealing with addresses retrieved using the Contacts framework itself, then those will already be represented using CNPostalAddress instances, so the above type conversion is only necessary when working with a custom way of storing addresses.

Relative time

Although the standard DateFormatter type is quite well-known and commonly used within all sorts of applications, it also has a somewhat lesser-known “cousin” called RelativeDateTimeFormatter which can be used to generate localized strings that describe the relative time interval between two dates.

For example, here’s how we could use that specialized formatter to compute a string that tells the user how much time that’s left until a given Event starts:

struct Event {
    var title: String
    var startDate: Date
    ...
}

extension Event {
    func relativeTimeString() -> String {
        let formatter = RelativeDateTimeFormatter()
        formatter.dateTimeStyle = .named
        formatter.formattingContext = .beginningOfSentence
        return formatter.localizedString(for: startDate, relativeTo: Date())
    }
}

What’s really cool is that by specifying that we want to use the named date time style (like we do above), words like “Tomorrow” and “Yesterday” will be used to describe intervals that have specific names.

Lists

Finally, let’s take a quick look at ListFormatter, which perhaps isn’t as complex as some of the other formatters that we’ve explored so far, but it can still be useful in certain situations.

Essentially, ListFormatter enables us to concatenate an array of strings into a single, localized list-like string. Using it is as easy as passing the array of strings that we wish to join to its static localizedString method, and it’ll then return a formatted string based on the user’s locale and language settings:

// In English:

let ingredientsList = ListFormatter.localizedString(
    byJoining: ["Apples", "Sugar", "Flour", "Butter"]
)

print(ingredientsList) // "Apples, Sugar, Flour, and Butter"

// In Swedish:

let ingredientsList = ListFormatter.localizedString(
    byJoining: ["Äpplen", "Socker", "Mjöl", "Smör"]
)

print(ingredientsList) // "Äpplen, Socker, Mjöl och Smör"

Note how the English and Swedish versions doesn’t just differ in terms of language, but also in how commas are used. Those kinds of details might seem insignificant, but can really make an app feel much more thoroughly localized — and once again, we didn’t have to write any custom code to account for those variances — it’s all handled for us by the system.

Support Swift by Sundell by checking out this sponsor:

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Conclusion

It’s very clear that Apple’s dedication to high-quality localization isn’t just limited to their own apps and system features — their various platform SDKs also ship with numerous APIs, tools and features that we can use to elevate the localization of our own apps as well. All that we have to do is to use the right APIs when dealing with locale-dependent values — such as names, numbers, addresses and dates.

Hopefully this article has given you a few insights on how to do just that, and feel free to reach out via either Twitter or email if you have any questions or comments.

Thanks for reading!

Although Combine is mainly focused around the concept of publishers that emit sequences of values over time, it also includes a set of convenience APIs that enable us to leverage the full power of the framework without necessarily having to write completely custom publisher implementations from scratch.

For example, let’s say that we wanted to add Combine support to an existing, closure-based API — such as this ImageProcessor, which uses the classic completion handler pattern to asynchronously notify its callers when the processing for a given image either finished or failed:

struct ImageProcessor {
    func process(
        _ image: UIImage,
        then handler: @escaping (Result<UIImage, Error>) -> Void
    ) {
        // Process the image and call the handler when done
        ...
    }
}

The above API uses Swift’s built-in Result type to encapsulate either a successfully processed image, or any error that was encountered. To learn more, check out this Basics article.

Now, rather than rewriting our ImageProcessor, let’s actually add a new, Combine-powered API to it in a completely additive way. Not only will that keep all of our existing code intact, but it’ll also let us choose whether to use Combine or a completion handler on a case-by-case basis even as we write new code.

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Retrofitting with futures

To make that happen, let’s use Combine’s Future type, which is an adaptation of the Futures/Promises pattern that’s very commonly used across a wide range of different programming languages. Essentially, a Combine Future gives us a promise closure that we can call when an asynchronous operation was completed, and Combine will then automatically map the Result that we give that closure into proper publisher events.

What’s really convenient in this case is that our existing completion handler closure already uses a Result type as its input, so all that we have to do within our Future-based implementation is to simply pass the promise closure that Combine gives us into a call to our existing process API — like this:

extension ImageProcessor {
    func process(_ image: UIImage) -> Future<UIImage, Error> {
        Future { promise in
            process(image, then: promise)
        }
    }
}

Just to illustrate, here’s what the above implementation would’ve looked like if we were to instead use a dedicated completion handler closure and then manually pass its result to our promise:

extension ImageProcessor {
    func process(_ image: UIImage) -> Future<UIImage, Error> {
        Future { promise in
            process(image) { result in
    promise(result)
}
        }
    }
}

So the Future type offers a very neat way to convert existing, closure-based APIs into ones that can be used within the reactive world of Combine — and, since those futures are really just publishers like any other, that means that we can use Combine’s entire suite of operators to transform and observe them:

processor.process(image)
    .replaceError(with: .errorIcon)
    .map { $0.withRenderingMode(.alwaysTemplate) }
    .receive(on: DispatchQueue.main)
    .assign(to: \.image, on: imageView)
    .store(in: &cancellables)

However, just like Futures and Promises in general, Combine’s Future type can only emit a single result, as it will immediately complete and get closed down once its promise closure was called.

So what if we instead wanted to emit multiple values over time, which is really what Combine was mainly designed to do?

Handling multiple output values

Let’s go back to our closure-based ImageProcessor API from before and imagine that it instead accepted two closures — one that gets called periodically with progress updates as an image is being processed, and one that’s called once the operation was fully completed:

struct ImageProcessor {
    typealias CompletionRatio = Double
    typealias ProgressHandler = (CompletionRatio) -> Void
    typealias CompletionHandler = (Result<UIImage, Error>) -> Void

    func process(
        _ image: UIImage,
        onProgress: @escaping ProgressHandler,
        onComplete: @escaping CompletionHandler
    ) {
        // Process the image and call the progress handler to
        // report the operation's ongoing progress, and then
        // call the completion handler once the image has finished
        // processing, or if an error was encountered.
        ...
    }
}

Above we’re using type aliases, both to make our actual method definition a bit easier to read, and to contextualize the Double that gets passed into our ProgressHandler. To learn more, check out “The power of type aliases in Swift”.

Before we start updating our Combine-based extension for the above new API, let’s introduce an enum called ProgressEvent, which we’ll use as the output type for the Combine publishers that we’ll create (since publishers can only emit a single type of values). It’ll include two cases, one for update events, and one for completion events:

extension ImageProcessor {
    enum ProgressEvent {
        case updated(completionRatio: CompletionRatio)
        case completed(UIImage)
    }
}

An initial idea on how to update our Combine API might be to keep using the Future type, just like we did before, but to now call its promise closure multiple times to report both update and completion events — for example like this:

extension ImageProcessor {
    func process(_ image: UIImage) -> Future<ProgressEvent, Error> {
        Future { promise in
            process(image,
                onProgress: { ratio in
                    promise(.success(
    .updated(completionRatio: ratio)
))
                },
                onComplete: { result in
                    promise(result.map(ProgressEvent.completed))
                }
            )
        }
    }
}

However, the above won’t work, since — as mentioned earlier — Combine futures can only emit a single value, which means that with the above setup, we’ll only receive the very first updated event before our entire pipeline will complete.

Sending values using subjects

Instead, this is a great use case for a subject — which lets us send as many values as we’d like before manually completing it. Combine ships with two main subject implementations: PassthroughSubject and CurrentValueSubject. Let’s start by using the former, which doesn’t hold on to any of the values that we’ll send it, but will rather pass them through to each of its subscribers.

Here’s how we could use such a subject to update our Combine-powered ImageProcessing API to now fully support both progress updates and completion events:

extension ImageProcessor {
    func process(_ image: UIImage) -> AnyPublisher<ProgressEvent, Error> {
        // First, we create our subject:
        let subject = PassthroughSubject<ProgressEvent, Error>()

        // Then, we call our closure-based API, and whenever it
        // sends us a new event, then we'll pass that along to
        // our subject. Finally, when our operation was finished,
        // then we'll send a competion event to our subject:
        process(image,
            onProgress: { ratio in
                subject.send(.updated(completionRatio: ratio))
            },
            onComplete: { result in
                switch result {
                case .success(let image):
                    subject.send(.completed(image))
                    subject.send(completion: .finished)
                case .failure(let error):
                    subject.send(completion: .failure(error))
                }
            }
        )
        
        // To avoid returning a mutable object, we convert our
        // subject into a type-erased publisher before returning it:
        return subject.eraseToAnyPublisher()
    }
}

Now all that we have to do is to update our call site from before to handle ProgressEvent values, rather than just UIImage instances — like this:

processor.process(image)
    .replaceError(with: .completed(.errorIcon))
    .receive(on: DispatchQueue.main)
    .sink { event in
        switch event {
        case .updated(let completionRatio):
            progressView.completionRatio = completionRatio
        case .completed(let image):
            imageView.image = image.withRenderingMode(
                .alwaysTemplate
            )
        }
    }
    .store(in: &cancellables)

However, one thing to keep in mind when using PassthroughSubject is that each subscriber that attaches to it will only receive the values that were sent after that subscription became active.

So in our case, since we’re starting each image processing operation immediately, and since we don’t know whether a caller might apply some form of delay to the way it handles our emitted values, we might instead want to use a CurrentValueSubject. Like its name implies, such a subject will keep track of the current (or last) value that we sent to it, and will in turn send that to all new subscribers once they connect to our subject.

Thankfully, switching between those two subject variants is typically really simple, since the only difference is that we have to initialize a CurrentValueSubject with the initial current value that we’d like it to keep track of:

extension ImageProcessor {
    func process(_ image: UIImage) -> AnyPublisher<ProgressEvent, Error> {
        let subject = CurrentValueSubject<ProgressEvent, Error>(
    .updated(completionRatio: 0)
)

        ...

        return subject.eraseToAnyPublisher()
    }
}

Worth pointing out, though, is that the above new implementation will also cause that initial ProgressEvent value to be immediately emitted when our subject is created, which may or may not be what we want, depending on the situation. But, in this case, it’ll actually be really nice, as that’ll ensure that all of our progress handling code will always be reset to zero when connected to our subject.

Support Swift by Sundell by checking out this sponsor:

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.

Conclusion

Combine’s Future and subject types are definitely worth keeping in mind when building Combine-powered APIs — and often act as much simpler alternatives to building completely custom publishers from scratch. There’s of course also Published properties, which offer another way to emit values through stored properties, which were covered in depth in this article — so Combine really does offer a quite comprehensive suite of tools that we can choose from depending on what we’re looking to build.

Thanks for reading! You’re more than welcome to reach out via either Twitter or email if you have any questions, comments or feedback. Also, feel free to check out this week’s sponsor using the link above if you’d like to support my work.

SwiftUI’s Binding property wrapper lets us establish a two-way binding between a given piece of state and any view that wishes to modify that state. Typically, creating such a binding simply involves referencing the state property that we wish to bind to using the $ prefix, but when it comes to collections, things are often not quite as straightforward.

For example, let’s say that we’re building a note taking app, and that we’d like to bind each Note model within an array to a series of NoteEditingView instances that are being created within a SwiftUI ForEach loop — like this:

struct Note: Hashable, Identifiable {
    let id: UUID
    var title: String
    var text: String
    ...
}

class NoteList: ObservableObject {
    @Published var notes: [Note]
    ...
}

struct NoteEditView: View {
    @Binding var note: Note

    var body: some View {
        ...
    }
}

struct NoteListView: View {
    @ObservedObject var list: NoteList

    var body: some View {
        List {
            ForEach(list.notes) { note in
                NavigationLink(note.title,
                    destination: NoteEditView(
    note: $note
)
                )
            }
        }
    }
}

Unfortunately, the above code sample doesn’t fully compile, for the same reason that we can’t directly mutate a value within a classic for loop — the note arguments that are being passed into our ForEach are all immutable, non-bindable values.

Instead, let’s try to iterate over the indices of our notes array, which will let us bind to mutable versions of our Note models by subscripting into $list.notes using the index that’s now passed into our ForEach closure:

struct NoteListView: View {
    @ObservedObject var list: NoteList

    var body: some View {
        List {
            ForEach(list.notes.indices) { index in
    NavigationLink(list.notes[index].title,
        destination: NoteEditView(
            note: $list.notes[index]
        )
    )
}
        }
    }
}

While our code now successfully compiles, and might initially even seem to be fully working — as soon as we’ll mutate our array of notes, we’ll get the following warning printed within the Xcode console:

ForEach(_:content:) should only be used for *constant* data. Instead conform
data to Identifiable or use ForEach(_:id:content:) and provide an explicit id!

Alright, so let’s do what SwiftUI tells us, by passing an explicit id key path when creating our ForEach instance — like this:

struct NoteListView: View {
    @ObservedObject var list: NoteList

    var body: some View {
        List {
            ForEach(list.notes.indices, id: \.self) { index in
                NavigationLink(list.notes[index].title,
                    destination: NoteEditView(
                        note: $list.notes[index]
                    )
                )
            }
        }
    }
}

At this point, we might have actually solved the problem. There are no more warnings being emitted, and things might continue to work perfectly fine even as we mutate our Note array. However, “might” is really the keyword here, as what we’ve essentially done is to make the index of each note its “reuse identifier”. What that means is that we might run into certain odd behaviors (or crashes, even) if our array ever changes rapidly, as SwiftUI will now consider each note’s index a stable identifier for that particular model and its associated NavigationLink.

So to truly fix the problem, we’re either going to have to refactor our NoteList class to also offer a way to access each Note by its proper UUID-based id (which would let us pass an array of those ids to ForEach, rather than using Int-based array indices), or we’re going to have to dive a bit deeper into Swift’s collection APIs in order to make our array indices truly unique.

In this case, let’s go for the second strategy, by introducing a custom collection that’ll combine the indices of another collection with the identifiers of the elements that it contains. To get started, let’s define a new type called IdentifiableIndices, which wraps a Base collection and also declares an Index and an Element type:

struct IdentifiableIndices<Base: RandomAccessCollection>
    where Base.Element: Identifiable {

    typealias Index = Base.Index

    struct Element: Identifiable {
        let id: Base.Element.ID
        let rawValue: Index
    }

    fileprivate var base: Base
}

Next, let’s make our new collection conform to the standard library’s RandomAccessCollection protocol, which mostly involves forwarding the required properties and methods to our underlying base collection — except for the implementation of subscript, which returns an instance of the Element type that we defined above:

extension IdentifiableIndices: RandomAccessCollection {
    var startIndex: Index { base.startIndex }
    var endIndex: Index { base.endIndex }

    subscript(position: Index) -> Element {
    Element(id: base[position].id, rawValue: position)
}

    func index(before index: Index) -> Index {
        base.index(before: index)
    }

    func index(after index: Index) -> Index {
        base.index(after: index)
    }
}

That’s it! Our new collection is now ready for action. However, to make it a bit more convenient to use, let’s also introduce two small extensions that’ll heavily improve its overall ergonomics. First, let’s make it easy to create an IdentifiableIndices instance by adding the following computed property to all compatible base collections (that is, ones that support random access, and also contains Identifiable elements):

extension RandomAccessCollection where Element: Identifiable {
    var identifiableIndices: IdentifiableIndices<Self> {
        IdentifiableIndices(base: self)
    }
}

The reason we can confidently make the above a computed property, rather than a method, is because IdentifiableIndices computes its elements lazily. That is, it doesn’t iterate over its base collection when first created, but rather acts more like a lens into that collection’s indices and identifiers. So creating it is an O(1) operation.

Finally, let’s also extend SwiftUI’s ForEach type with a convenience API that’ll let us iterate over an IdentifiableIndices collection without also having to manually access the rawValue of each index:

extension ForEach where ID == Data.Element.ID,
                        Data.Element: Identifiable,
                        Content: View {
    init<T>(
        _ indices: Data,
        @ViewBuilder content: @escaping (Data.Index) -> Content
    ) where Data == IdentifiableIndices<T> {
        self.init(indices) { index in
            content(index.rawValue)
        }
    }
}

With the above pieces in place, we can now go back to our NoteListView and make its usage of ForEach much more stable and reliable by making it iterate over our Note array’s identifiableIndices — like this:

struct NoteListView: View {
    @ObservedObject var list: NoteList

    var body: some View {
        List {
            ForEach(list.notes.identifiableIndices) { index in
                NavigationLink(list.notes[index].title,
                    destination: NoteEditView(
                        note: $list.notes[index]
                    )
                )
            }
        }
    }
}

However, while the above solution should prove to work really well in many different kinds of situations, it’s still possible to encounter crashes and other bugs if the last element of our collection is ever removed. It seems like SwiftUI applies some form of caching to the collection bindings that it creates, which can cause an outdated index to be used when subscripting into our underlying Note array — and if that happens when the last element was removed, then our app will crash with an out-of-bounds error. Not great.

While this certainly seems to be a bug within SwiftUI itself, it’s still something that we can work around locally for now. Rather than using SwiftUI’s built-in API for retrieving nested bindings for each collection element, let’s instead create custom Binding instances, which (at least in my experience) will completely solve the problem.

To make that happen, let’s modify our previous ForEach extension to instead accept a Binding reference to the collection that we wish to iterate over (which, in turn, requires that collection to conform to MutableCollection), and to then use that to create custom Binding instances for getting and setting each element. Finally, we’ll pass each such custom binding to our content closure, along with the index of the current element — like this:

extension ForEach where ID == Data.Element.ID,
                        Data.Element: Identifiable,
                        Content: View {
    init<T>(
        _ data: Binding<T>,
        @ViewBuilder content: @escaping (T.Index, Binding<T.Element>) -> Content
    ) where Data == IdentifiableIndices<T>, T: MutableCollection {
        self.init(data.wrappedValue.identifiableIndices) { index in
            content(
                index.rawValue,
                Binding(
    get: { data.wrappedValue[index.rawValue] },
    set: { data.wrappedValue[index.rawValue] = $0 }
)
            )
        }
    }
}

If we now use the above new API to update our NoteListView to instead look like this, then we should be able to modify our NoteList model object however we please without encountering any kind of SwiftUI-related issues within our view:

struct NoteListView: View {
    @ObservedObject var list: NoteList

    var body: some View {
        List {
            ForEach($list.notes) { index, note in
    NavigationLink(note.wrappedValue.title,
        destination: NoteEditView(
            note: note
        )
    )
}
        }
    }
}

While I do hope that future SwiftUI releases will add new convenience APIs for creating bindings to a collection’s elements, the fact that SwiftUI uses standard Swift protocols (such as RandomAccessCollection and Identifiable) to drive its logic means that we can very often augment it to fit our needs, or to temporarily work around bugs and other issues, which is a huge benefit in cases like this.

Thanks for reading, and feel free to reach out via either Twitter or email if you have any questions, comments or feedback.

Support Swift by Sundell by checking out this sponsor:

Architecting SwiftUI apps with MVC and MVVM: Although you can create an app simply by throwing some code together, without best practices and a robust architecture, you’ll soon end up with unmanageable spaghetti code. Learn how to create solid and maintainable apps with fewer bugs using this free guide.