StringInterpolationProtocol

protocol StringInterpolationProtocol

Represents the contents of a string literal with interpolations while it's being built up.

Conforming Types DefaultStringInterpolation
Associated Types
associatedtype StringLiteralType

Each ExpressibleByStringInterpolation type has an associated StringInterpolation type which conforms to StringInterpolationProtocol. Swift converts an expression like "The time is \(time)." as MyString into a series of statements similar to:

var interpolation = MyString.StringInterpolation(literalCapacity: 13, 
                                                 interpolationCount: 1)

interpolation.appendLiteral("The time is ")
interpolation.appendInterpolation(time)
interpolation.appendLiteral(".")

MyString(stringInterpolation: interpolation)

The StringInterpolation type is responsible for collecting the segments passed to its appendLiteral(_:) and appendInterpolation methods and assembling them into a whole, converting as necessary. Once all of the segments are appended, the interpolation is passed to an init(stringInterpolation:) initializer on the type being created, which must extract the accumulated data from the StringInterpolation.

In simple cases, you can use DefaultStringInterpolation as the interpolation type for types that conform to the ExpressibleByStringLiteral protocol. To use the default interpolation, conform a type to ExpressibleByStringInterpolation and implement init(stringLiteral: String). Values in interpolations are converted to strings, and then passed to that initializer just like any other string literal.

Handling String Interpolations

With a custom interpolation type, each interpolated segment is translated into a call to a special appendInterpolation method. The contents of the interpolation's parentheses are treated as the call's argument list. That argument list can include multiple arguments and argument labels.

The following examples show how string interpolations are translated into calls to appendInterpolation:

The appendInterpolation methods in your custom type must be mutating instance methods that return Void. This code shows a custom interpolation type's declaration of an appendInterpolation method that provides special validation for user input:

extension MyString.StringInterpolation {
    mutating func appendInterpolation(validating input: String) {
        // Perform validation of `input` and store for later use
    }
}

To use this interpolation method, create a string literal with an interpolation using the validating parameter label.

let userInput = readLine() ?? ""
let myString = "The user typed '\(validating: userInput)'." as MyString

appendInterpolation methods support virtually all features of methods: they can have any number of parameters, can specify labels for any or all of their parameters, can provide default values, can have variadic parameters, and can have parameters with generic types. Most importantly, they can be overloaded, so a type that conforms to StringInterpolationProtocol can provide several different appendInterpolation methods with different behaviors. An appendInterpolation method can also throw; when a user writes a literal with one of these interpolations, they must mark the string literal with try or one of its variants.

Initializers

init init(literalCapacity:interpolationCount:) Required

Creates an empty instance ready to be filled with string literal content.

Don't call this initializer directly. Instead, initialize a variable or constant using a string literal with interpolated expressions.

Swift passes this initializer a pair of arguments specifying the size of the literal segments and the number of interpolated segments. Use this information to estimate the amount of storage you will need.

  • Parameter literalCapacity: The approximate size of all literal segments combined. This is meant to be passed to String.reserveCapacity(_:); it may be slightly larger or smaller than the sum of the counts of each literal segment.
  • Parameter interpolationCount: The number of interpolations which will be appended. Use this value to estimate how much additional capacity will be needed for the interpolated segments.

Declaration

init(literalCapacity: Int, interpolationCount: Int)

Instance Methods

func appendLiteral(_ literal: Self.StringLiteralType) Required

Appends a literal segment to the interpolation.

Don't call this method directly. Instead, initialize a variable or constant using a string literal with interpolated expressions.

Interpolated expressions don't pass through this method; instead, Swift selects an overload of appendInterpolation. For more information, see the top-level StringInterpolationProtocol documentation.

  • Parameter literal: A string literal containing the characters that appear next in the string literal.

Declaration

mutating func appendLiteral(_ literal: Self.StringLiteralType)