Pattern Match

The ~= (pattern matching) operator evaluates whether a specific value conforms to a defined pattern. It serves as the underlying boolean evaluation mechanism for Swift’s pattern-matching constructs, implicitly driving the execution of switch statement case labels, catch clauses, if case, guard case, for case, and while case statements.

Syntax and Operand Order

Unlike standard equality operators, the ~= operator is asymmetrical. The order of operands is strictly defined and critical to its operation:

• Left-Hand Side (LHS): The pattern to match against.
• Right-Hand Side (RHS): The value being evaluated.

let isMatch = 1...5 ~= 3
print(isMatch) // Prints: true

When the Swift compiler evaluates a switch statement, it translates the case comparisons into ~= expressions. For example, a case 1...5: evaluating a bound value of 3 is compiled under the hood as 1...5 ~= 3.

Standard Library Behavior

The Swift Standard Library provides default overloads for the ~= operator across several common protocols and types:

• Equatable Types: If the pattern and the value are of the same type and conform to Equatable, ~= delegates directly to the == operator.
• Ranges (Range, ClosedRange): When the pattern is a range and the value is of the range’s underlying Bound type, ~= evaluates to pattern.contains(value).
• Optionals: Evaluates whether the unwrapped value of an optional matches the pattern. If the pattern itself is nil (e.g., case nil:), the operator evaluates to true when the value is nil. If the pattern is non-nil but the evaluated value is nil, it safely evaluates to false.
• Errors: Matches specific error types or domains within catch blocks.

Custom Overloading

The ~= operator can be globally overloaded to define custom pattern-matching logic, often between disparate types. To implement custom pattern matching, define a function for the ~= operator that accepts the concrete pattern type as the first parameter and the concrete value type as the second parameter, returning a Bool.

Warning: Never use unconstrained generic parameters (e.g., <T, U>) when overloading ~=. Doing so creates a global catch-all that disables compile-time type checking for pattern matching across the entire module, allowing fundamentally incompatible types to compile in switch statements while silently failing at runtime.

struct PrefixPattern {
    let prefix: String
}

struct TextValue {
    let content: String
}

// Overload the ~= operator for the custom types
func ~=(pattern: PrefixPattern, value: TextValue) -> Bool {
    return value.content.hasPrefix(pattern.prefix)
}

let pattern = PrefixPattern(prefix: "SYS_")
let value = TextValue(content: "SYS_BOOT_COMPLETE")

let customMatch = pattern ~= value
print(customMatch) // Prints: true

By defining this overload with concrete types, the custom evaluation logic is automatically injected into Swift’s control flow structures whenever PrefixPattern is used as a case label against a TextValue.

Master Swift with Deep Grasping Methodology!

Learn More