protocol CustomDebugStringConvertible

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

Conforming Types AnyHashable, Array, ArraySlice, CVaListPointer, Character, ClosedRange, CodingKey, CollectionOfOne, ContiguousArray, Dictionary, Double, Float, Float80, KeyValuePairs, ObjectIdentifier, OpaquePointer, Optional, Range, SIMD16, SIMD2, SIMD3, SIMD32, SIMD4, SIMD64, SIMD8, Set, StaticString, String, String.UTF16View, String.UTF8View, String.UnicodeScalarView, Substring, Unicode.Scalar, UnsafeBufferPointer, UnsafeMutableBufferPointer, UnsafeMutableRawBufferPointer, UnsafeRawBufferPointer

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)"

Instance Variables

var debugDescription 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)
// Prints "(21, 30)"

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


var debugDescription: String