CustomDebugStringConvertible

protocol CustomDebugStringConvertible

A type with a customized textual representation suitable for debugging purposes.

Swift provides a default debugging textual representation for any type. That default representation is used by the String(reflecting:) initializer and the debugPrint(_:) function for types that don't provide their own. To customize that representation, make your type conform to the CustomDebugStringConvertible protocol.

Because the String(reflecting:) initializer works for instances of any type, returning an instance's debugDescription if the value passed conforms to CustomDebugStringConvertible, accessing a type's debugDescription property directly or using CustomDebugStringConvertible as a generic constraint is discouraged.

Note: Calling the dump(_:_:_:_:) function and printing in the debugger uses both String(reflecting:) and Mirror(reflecting:) to collect information about an instance. If you implement CustomDebugStringConvertible conformance for your custom type, you may want to consider providing a custom mirror by implementing CustomReflectable conformance, as well.

Conforming to the CustomDebugStringConvertible Protocol

Add CustomDebugStringConvertible conformance to your custom types by defining a debugDescription property.

For example, this custom Point struct uses the default representation supplied by the standard library:

struct Point {
    let x: Int, y: Int
}

let p = Point(x: 21, y: 30)
print(String(reflecting: p))
// Prints "p: Point = {
//           x = 21
//           y = 30
//         }"

After adding CustomDebugStringConvertible conformance by implementing the debugDescription property, Point provides its own custom debugging representation.

extension Point: CustomDebugStringConvertible {
    var debugDescription: String {
        return "Point(x: \(x), y: \(y))"
    }
}

print(String(reflecting: p))
// Prints "Point(x: 21, y: 30)"
Inheritance View Protocol Hierarchy →
Import import Swift

Instance Variables

var debugDescription: String Required

A textual representation of this instance, suitable for debugging.

Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(reflecting:) initializer. This initializer works with any type, and uses the custom debugDescription property for types that conform to CustomDebugStringConvertible:

struct Point: CustomDebugStringConvertible {
    let x: Int, y: Int

    var debugDescription: String {
        return "(\(x), \(y))"
    }
}

let p = Point(x: 21, y: 30)
let s = String(reflecting: p)
print(s)
// Prints "(21, 30)"

The conversion of p to a string in the assignment to s uses the Point type's debugDescription property.

Declaration

var debugDescription: String { get }