Custom result builder declaration in Swift - Deep Dive

Overview - Custom result builder declaration

What is it?

A custom result builder in Swift is a special way to create complex values by writing code that looks like a simple list or block. It lets you define how multiple pieces of code combine into one result, making your code cleaner and easier to read. You declare a custom result builder by creating a type with specific methods that tell Swift how to build the final value from parts. This feature helps write domain-specific languages or cleanly build data structures using natural syntax.

Why it matters

Without custom result builders, combining many pieces of code into one value would require verbose and repetitive code, making programs harder to write and understand. Custom result builders let developers write expressive, readable code that looks like natural language or structured data. This improves productivity and reduces bugs by hiding complex construction logic behind simple syntax. It also enables powerful frameworks like SwiftUI to create user interfaces declaratively.

Where it fits

Before learning custom result builders, you should understand Swift functions, closures, and basic types. Knowing about protocols and generics helps too. After mastering custom result builders, you can explore SwiftUI, DSLs (domain-specific languages), and advanced Swift metaprogramming techniques.

Mental Model

Core Idea

A custom result builder transforms a block of code into a single value by combining its parts using special builder methods.

Think of it like...

Imagine building a LEGO model by snapping together many small bricks. The custom result builder is like the instruction manual that tells you how to connect each brick to form the final model.

┌─────────────────────────────┐
│   Code block with multiple  │
│   expressions or statements │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Custom Result Builder Type   │
│ - buildBlock(parts...)       │
│ - buildOptional(optional)    │
│ - buildEither(first/second)  │
│ - buildArray(parts)          │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Final combined result value  │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding basic result builders

Concept: Learn what a result builder is and how Swift uses it to combine code blocks into values.

Swift's result builders let you write code blocks that look like normal code but actually produce a single combined value. The compiler uses special methods like buildBlock to join parts together. For example, SwiftUI uses result builders to build UI views from code blocks.

Result

You see how a block of code can be transformed into one value automatically.

Understanding that result builders let you write natural code that the compiler transforms is key to grasping their power.

2

Foundation

Declaring a simple custom result builder

Concept: Create a basic custom result builder type with a buildBlock method.

You declare a struct or enum with the @resultBuilder attribute. Inside, you define static methods like buildBlock that take parts and combine them. For example: @resultBuilder struct StringBuilder { static func buildBlock(_ components: String...) -> String { components.joined(separator: ", ") } } This builder joins strings with commas.

Result

You have a custom builder that combines strings from a block.

Knowing how to declare buildBlock is the foundation for all custom result builders.

3

Intermediate

Handling optional and conditional code

🤔Before reading on: do you think result builders automatically handle if-else and optionals, or do you need to add special methods? Commit to your answer.

Concept: Add methods to handle optional values and conditional branches inside the builder.

Result builders can handle if statements and optionals if you provide methods like buildOptional and buildEither. For example: static func buildOptional(_ component: String?) -> String { component ?? "" } static func buildEither(first component: String) -> String { component } static func buildEither(second component: String) -> String { component } These let the builder combine code with conditions.

Result

Your builder can now process if-else and optional code blocks.

Understanding these methods explains how result builders support real-world control flow.

4

Intermediate

Supporting loops with buildArray

🤔Before reading on: do you think loops inside result builder blocks are handled automatically or require a special method? Commit to your answer.

Concept: Implement buildArray to combine multiple repeated parts from loops.

When you write a for-loop inside a result builder block, Swift calls buildArray to combine the results. For example: static func buildArray(_ components: [String]) -> String { components.joined(separator: "; ") } This method lets the builder handle repeated elements cleanly.

Result

Your builder can now process loops inside code blocks.

Knowing buildArray is essential to support dynamic repeated content in builders.

5

Advanced

Combining multiple builder methods for complex logic

🤔Before reading on: do you think buildBlock is enough to handle all code cases, or do you need to combine multiple builder methods? Commit to your answer.

Concept: Use buildBlock together with buildOptional, buildEither, and buildArray to handle complex code structures.

In practice, your builder must implement several methods to handle all Swift control flow inside blocks. The compiler chooses which method to call based on the code structure. For example, nested if-else and loops require buildEither and buildArray working together with buildBlock.

Result

Your builder can handle complex, nested code blocks with conditions and loops.

Understanding how these methods interplay helps you design robust builders that handle real code.

6

Expert

Advanced customization and limitations

🤔Before reading on: do you think result builders can transform any code, or are there limitations and special cases? Commit to your answer.

Concept: Explore advanced features like buildFinalResult and limitations like inability to handle all Swift syntax or side effects.

You can add buildFinalResult to transform the combined value before returning it. However, result builders cannot handle all Swift syntax, such as arbitrary statements or side effects. Also, debugging builder code can be tricky because the compiler transforms your code behind the scenes.

Result

You understand the advanced customization options and practical limits of result builders.

Knowing these limits prevents misuse and helps you design better builders and debug them effectively.

Under the Hood

Swift's compiler transforms the code inside a result builder block by replacing it with calls to the builder's static methods. It breaks the block into parts, then calls buildBlock, buildOptional, buildEither, and buildArray as needed to combine these parts into one value. This transformation happens at compile time, so the final code runs as if you wrote the combined value directly.

Why designed this way?

Result builders were designed to let developers write declarative code that looks natural but compiles into efficient code. The static methods let the compiler know exactly how to combine parts, enabling powerful DSLs like SwiftUI. Alternatives like macros or runtime reflection were less safe or efficient, so this design balances expressiveness and performance.

Code block ──▶ Compiler splits into parts
       │
       ▼
┌─────────────────────────────┐
│ Calls buildBlock(parts...)   │
│ Calls buildOptional(optional)│
│ Calls buildEither(first/second)│
│ Calls buildArray(parts)      │
└─────────────┬───────────────┘
              │
              ▼
      Combined result value

Myth Busters - 3 Common Misconceptions

Quick: Do you think result builders can execute arbitrary Swift statements like loops and variable assignments inside their blocks? Commit to yes or no.

Common Belief: Result builders can handle any Swift code inside their blocks, including loops, variable assignments, and side effects.

Reality: Result builders only transform expressions and limited control flow like if-else and loops that produce values. They cannot handle arbitrary statements or side effects inside the block.

Why it matters: Assuming builders handle all code leads to confusing errors and misuse, causing bugs and frustration.

Quick: Do you think buildBlock alone is enough to handle all control flow inside a result builder? Commit to yes or no.

Common Belief: The buildBlock method is enough to combine all parts of a result builder block, including conditionals and loops.

Reality: buildBlock handles simple sequences, but buildOptional, buildEither, and buildArray are needed to handle optionals, conditionals, and loops respectively.

Why it matters: Missing these methods causes your builder to fail on common code patterns, limiting usefulness.

Quick: Do you think debugging code inside a result builder block is straightforward and shows clear errors? Commit to yes or no.

Common Belief: Debugging result builder code is like normal Swift code, with clear error messages and stack traces.

Reality: Because the compiler transforms builder blocks, error messages can be confusing and debugging is harder.

Why it matters: Not knowing this leads to wasted time and difficulty fixing bugs in builder code.

Expert Zone

1

Result builders rely on static methods and compile-time transformations, so they cannot capture runtime context or side effects directly.

2

The order of evaluation inside builder blocks can affect performance and behavior, especially with complex nested builders.

3

Using buildFinalResult allows subtle control over the final output, enabling transformations or validations before returning.

When NOT to use

Avoid custom result builders when your code requires complex side effects, mutable state, or arbitrary statements. Instead, use regular functions, loops, or imperative code. Also, if debugging clarity is critical, simpler code may be better.

Production Patterns

In production, custom result builders are used to create DSLs like SwiftUI views, HTML builders, or query builders. They enable declarative UI code, clean configuration DSLs, and readable data construction patterns.

Connections

Domain-Specific Languages (DSLs)

Custom result builders enable building DSLs by letting you write expressive, domain-focused code blocks.

Understanding result builders helps grasp how DSLs can be embedded in general-purpose languages to improve expressiveness.

Functional Programming

Result builders use pure functions to combine parts, similar to functional composition patterns.

Knowing functional composition clarifies how builder methods combine code parts into one value.

Natural Language Processing (NLP)

Both result builders and NLP parse and transform structured input into meaningful output.

Seeing result builders as a form of code parsing and transformation connects programming with language processing concepts.

Common Pitfalls

#1 Trying to use variable assignments inside a result builder block.

Wrong approach:

@StringBuilder
func buildText() -> String {
var text = "Hello"
text += " World"
text
}

Correct approach:

@StringBuilder
func buildText() -> String {
"Hello"
" World"
}

Root cause:

Result builders only combine expressions; statements like variable assignments are not supported inside builder blocks.

#2 Omitting buildOptional when using if statements with optional values.

Wrong approach:

@StringBuilder
func buildText(_ name: String?) -> String {
if let n = name {
n
}
}

Correct approach:

@resultBuilder
struct StringBuilder {
static func buildBlock(_ components: String...) -> String {
components.joined(separator: " ")
}
static func buildOptional(_ component: String?) -> String {
component ?? ""
}
}

@StringBuilder
func buildText(_ name: String?) -> String {
if let n = name {
n
}
}

Root cause:

Without buildOptional, the builder cannot handle optional branches, causing compile errors.

#3 Expecting buildBlock to handle loops without buildArray.

Wrong approach:

@StringBuilder
func buildList(_ items: [String]) -> String {
for item in items {
item
}
}

Correct approach:

@resultBuilder
struct StringBuilder {
static func buildBlock(_ components: String...) -> String {
components.joined(separator: ", ")
}
static func buildArray(_ components: [String]) -> String {
components.joined(separator: ", ")
}
}

@StringBuilder
func buildList(_ items: [String]) -> String {
for item in items {
item
}
}

Root cause:

Loops produce arrays of parts that require buildArray to combine them properly.

Key Takeaways

Custom result builders let you write code blocks that the compiler transforms into a single combined value using special static methods.

You must implement methods like buildBlock, buildOptional, buildEither, and buildArray to handle sequences, optionals, conditionals, and loops inside builder blocks.

Result builders enable clean, declarative code styles used in frameworks like SwiftUI and DSLs, improving readability and reducing boilerplate.

Understanding the compile-time transformation and limitations of result builders helps avoid common mistakes and debugging challenges.

Advanced features like buildFinalResult allow further customization, but result builders are not suitable for all code patterns, especially those with side effects.