Expressible by String Interpolation

讓一個型別可以用 String Interpolation 來初始化物件 (Initialization)。

⭐️ 解說

假設 MyType 是一個遵循 ExpressibleByStringInterpolation 的型別，則 Swift 會將下列這行程式碼：

// count:        123456789012       34567
let s: MyType = "The time is \(time) now."    // interpolated literal
//               ╰──── L ───╯╰──I──╯╰─L─╯
// L: Literal (共 17 個字母)
// I: Interpolation (共 1 個)

自動轉化為：

// ---------------------------------------------------------
//     interpolated literal -> MyType.StringInterpolation
// ---------------------------------------------------------

// ⭐️ 1. (init) 先初始化用來組合字串的 interpolation 物件：
var interpolation = MyType.StringInterpolation(
    literalCapacity   : 17, 
    interpolationCount:  1
)

// ⭐️ 2. (configure) 根據原 interpolated literal 套用相對應的組合方法：
//    let s: MyType = "The time is \(time) now."
//                     ╰──── L ───╯╰──I──╯╰─L─╯
interpolation.appendLiteral("The time is ")    // L
interpolation.appendInterpolation(time)        // I
interpolation.appendLiteral(" now.")           // L

// ---------------------------------------------------------
//     MyType.StringInterpolation -> MyType
// ---------------------------------------------------------

// ⭐️ 3. 使用 MyType(stringInterpolation:) 傳回新物件
let s = MyType(stringInterpolation: interpolation)

整個過程就是將 interpolated literal 轉為 MyType.StringInterpolation，然後再將這個 MyType.StringInterpolation 物件轉為 MyType 傳回。

這也就是為什麼當我們要將 MyType 遵循於 ExpressibleByStringInterpolation 協定時，必須實現下列條件：

• MyType.StringInterpolation (遵循 StringInterpolationProtocol)：

  • .init(literalCapacity:interpolationCount:) (⭐️ 1)

  • .appendLiteral()、.appendInterpolation() (⭐️ 2)

• MyType：

  • .init(stringLiteral:) (⭐️ ExpressibleByStringLiteral)

  • .init(stringInterpolation:) (⭐️ 3)

💈例一

當我們使用下列語法：

// ⭐️ 1. conform to `ExpressibleByStringInterpolation` 
extension MyType: ExpressibleByStringInterpolation {
    // ⭐️ 2. implement init(stringLiteral:)
    init(stringLiteral value: String) {
        // ...
    }
}

Swift 會自動：

• 使用 DefaultStringInterpolation 當作是 MyType.StringInterpolation。

• 使用預設的 .init(stringInterpolation:)：直接將 interpolated literal 丟給 .init(stringLiteral:) 處理。

此時，MyType 就會自動遵循 ExpressibleByStringInterpolation，而無需再做其他設定。請看下面的範例：

👉 replit

// --------------------
//     declarations 
// --------------------

// File
struct File {}

// Path
struct Path {
    var string: String
}

// loadFile()
@discardableResult
func loadFile(_ path: Path) -> File {
    print("file: \(path.string) loaded")
    return File()
}

// ----------------------------------------
//     ExpressibleByStringInterpolation 
// ----------------------------------------

// ⭐️ 1. conform to `ExpressibleByStringInterpolation` 
extension Path: ExpressibleByStringInterpolation {
    // ⭐️ 2. implement init(stringLiteral:)
    init(stringLiteral value: String) {
        self.string = value
    }
}

// -------------
//     main 
// -------------

// Path(string:)
loadFile(Path(string: "~/documents/article.md"))
// file: ~/documents/article.md loaded

// ⭐️ `Path` conforms to `ExpressibleByStringLiteral`  (automatically)
loadFile("~/documents/article.md")
// file: ~/documents/article.md loaded

let username = "joe"

// ⭐️ `Path` conforms to `ExpressibleByStringInterpolation`
let path: Path = "/users/\(username)/file.txt"

loadFile(path)
// file: /users/joe/file.txt loaded

💈例二

👉 replit

// ---------------------
//     declarations 
// ---------------------

struct HTMLComponent {
    let description: String
}

// ⭐️ for: print()
extension HTMLComponent: CustomStringConvertible {}

// ⭐️ ExpressibleByStringInterpolation
// -----------------------------------
// 1. conforms to `ExpressibleByStringLiteral`
// 2. conforms to `ExpressibleByStringInterpolation`
extension HTMLComponent: ExpressibleByStringInterpolation {

    // ⭐️ 1. ExpressibleByStringLiteral
    init(stringLiteral value: String) {
        description = value
    }

    // ⭐️ 2.1 ExpressibleByStringInterpolation
    init(stringInterpolation: StringInterpolation) {
        description = stringInterpolation.output
    }

    // ⭐️ 2.2 ExpressibleByStringInterpolation
    struct StringInterpolation: StringInterpolationProtocol {

        // start with an empty string
        var output = ""

        // --------------------------------------------------
        //     .init(literalCapacity:interpolationCount:)
        // --------------------------------------------------

        // allocate enough space to hold twice the amount of literal text
        init(literalCapacity: Int, interpolationCount: Int) {
            // 就一個字串而已，有必要預留空間嗎？
            output.reserveCapacity(literalCapacity * 2)
        }

        // ----------------------
        //     append literal
        // ----------------------

        // string literal
        mutating func appendLiteral(_ literal: String) {
            print("appending (literal): \(literal)")
            output.append(literal)
        }

        // -----------------------------
        //     append interpolations
        // -----------------------------

        // twitter link
        mutating func appendInterpolation(twitter: String) {
            print("appending (twitter): \(twitter)")
            output.append("<a href=\"https://twitter/\(twitter)\">twitter</a>")
        }

        // email address
        mutating func appendInterpolation(email: String) {
            print("appending (email  ): \(email)")
            output.append("<a href=\"mailto:\(email)\">\(email)</a>")
        }
    }
}

// ------------
//     main 
// ------------

let text: HTMLComponent = "follow me on \(twitter: "twostraws"), or email me at \(email: "[e-mail]")."

print(text)
// follow me on <a href="https://twitter/twostraws">twitter</a>, 
// or email me at <a href="mailto:[e-mail]">[e-mail]</a>.

// ------------
//     log 
// ------------

/*
appending (literal): follow me on 
appending (twitter): twostraws
appending (literal): , or email me at 
appending (email  ): [e-mail]
appending (literal): .
*/

💈例三

import Foundation  // for `NSAttributedString`, `NSMutableAttributedString`
import UIKit       // for `UIFont`

// ColoredString
struct ColoredString {
    // the final attributed string, once all interpolations have finished    
    let value: NSAttributedString
}

// 🅿️ ExpressibleByStringInterpolation
extension ColoredString: ExpressibleByStringInterpolation {
    
    // --------------------------------------------
    // ⭐️ `ExpressibleByStringLiteral` requirements
    // --------------------------------------------
    // 1. associatedtype: `StringInterpolation`
    // 2. init(stringLiteral:)
    // 3. init(stringInterpolation:)
    
    // ⭐️ 2.
    //    - create an instance from a literal string
    init(stringLiteral value: String) {
        self.value = NSAttributedString(string: value)
    }
    
    // ⭐️ 3.
    //    - create an instance from an interpolated string
    init(stringInterpolation: StringInterpolation) {
        self.value = stringInterpolation.output
    }
    
    // -------------------------------------------
    // ⭐️ 1. associatedtype: `StringInterpolation` 
    // -------------------------------------------
    //    assembles an attributed string from various interpolations
    struct StringInterpolation: StringInterpolationProtocol {
        
        // this is where we store the attributed string as we're building it
        var output = NSMutableAttributedString()
        
        // default attribute to use for text
        var baseAttributes: [NSAttributedString.Key: Any] = [
            .font: UIFont(name: "Georgia-Italic", size: 64) ?? .systemFont(ofSize: 64), 
            .foregroundColor: UIColor.white
        ]
        
        // --------------------------------------------
        // ⭐️ `StringInterpolationProtocol` requirments
        // --------------------------------------------
        
        // ⭐️ 1.1 can be used as a performance optimization.
        init(literalCapacity: Int, interpolationCount: Int) { }
        
        // ⭐️ 1.2 called when appending some raw text
        mutating func appendLiteral(_ literal: String) {
            
            // give it our base styling
            let attributedString = NSAttributedString(
                string    : literal, 
                attributes: baseAttributes
            )
            
            // add it to our scratchpad string
            output.append(attributedString)
        }
        
        // ⭐️ 1.3 called when appending a colored message
        mutating func appendInterpolation(_ str: String, _ color: UIColor) {
            
            // take a copy of our base attributes and apply the color
            var attributes = baseAttributes
            attributes[.foregroundColor] = color
            
            // wrap it in a new attributed string and add it to our scratchpad
            let attributedString = NSAttributedString(
                string    : str, 
                attributes: attributes
            )
            
            // append to our scratchpad string
            output.append(attributedString)
        }
    }
}

// custom type initialized with string interpolatiopn
let str: ColoredString = "\("Red", .red), \("Orange", .orange), \("Blue", .blue)"

📗 參考

• Hacking with Swift ⟩

  • Super-powered string interpolation in Swift 5.0 (💈例三)

  • How to use custom string interpolation ⭐️ (💈例二)

• NSHipster ⟩ Expressible​ByString​Interpolation

• Sundell ⟩ Making types expressible by string interpolation (💈例一)

📘 手冊

• Swift ⟩ Initialization with Literals ⟩

  • ExpressibleByStringLiteral

  • ExpressibleByStringInterpolation

  • StringInterpolationProtocol ⭐️

• SwiftDoc ⟩ ExpressibleByStringInterpolation

👥 相關

• String Interpolation