CompositionStringConvertible

A Swift protocol for composing the textual representation of a type in terms of its components.

The CompositionStringConvertible protocol inherits from CustomStringConvertible and provides a default implementation of description in a style similar to the textual representation supplied by the standard library.

protocolCompositionStringConvertible:CustomStringConvertible{func describe(to formatter:inoutCompositionFormatter)}

Types that conform to CompositionStringConvertible may customize the components that are included in their textual representation.

Consider the following structure:

structPerson{letfirstName:StringletlastName:Stringletage:Intletpet:Animal?varfullName:String{[firstName, lastName].joined(separator:"")}}

Person doesn't implement CustomStringConvertible so a default textual representation is provided by the standard library:

letp=Person(firstName:"Matt", lastName:"Comi", age:42, pet:nil)print(p) // "Person(firstName: "Matt", lastName: "Comi", age: 42, pet: nil)"

Traditionally, the only way to customize this representation is by conforming to CustomStringConvertible and manually implementing var description: String. Alternatively, consider this conformance to CompositionStringConvertible:

extensionPerson:CompositionStringConvertible{func describe(to formatter:inoutCompositionFormatter){
formatter.includesNilValues =false
formatter.append(fullName)
formatter.append(age, label:"age")
formatter.append(pet, label:"pet")}}

This implementation:

• Replaces the firstName and lastName properties with the fullName computed property.
• Omits the label of the fullName property.
• Indicates that nil values should not be included.

print(p) // "Person("Matt Comi", age: 42)"

Formatting

Values appended to the CompositionFormatter are formatted using String(describing:). This behavior may be overridden on platforms where FormatStyle is available:

func append<T, U:FormatStyle>(_ value:T?, formatStyle:U, label:String?=nil)where T ==U.FormatInput, U.FormatOutput ==String

Consider this Task type:

structTask{letname:Stringletprogress:Float}

A Task has the following default textual representation:

lett=Task(name:"Tidy Garden", progress:0.2)print(t) // "Task(name: "Tidy Garden", progress: 0.2) 

By conforming to CompositionStringConvertible a task's progress may be represented as a percentage:

extensionTask:CompositionStringConvertible{func describe(to formatter:inoutCompositionFormatter){
formatter.append(name)
formatter.append(progress, formatStyle:.percent, label:"progress")}}print(t) // "Task("Tidy Garden", progress: 20%)