Mirror

struct Mirror

Representation of the sub-structure and optional "display style" of any arbitrary subject instance.

Describes the parts---such as stored properties, collection elements, tuple elements, or the active enumeration case---that make up a particular instance. May also supply a "display style" property that suggests how this structure might be rendered.

Mirrors are used by playgrounds and the debugger.

Inheritance CustomReflectable, CustomStringConvertible View Protocol Hierarchy →
Associated Types
Child = (label: String?, value: Any)

An element of the reflected instance's structure. The optional label may be used when appropriate, e.g. to represent the name of a stored property or of an active enum case, and will be used for lookup when Strings are passed to the descendant method.

Children = AnyCollection<Mirror.Child>

The type used to represent sub-structure.

Depending on your needs, you may find it useful to "upgrade" instances of this type to AnyBidirectionalCollection or AnyRandomAccessCollection. For example, to display the last 20 children of a mirror if they can be accessed efficiently, you might write:

if let b = AnyBidirectionalCollection(someMirror.children) {
  var i = xs.index(b.endIndex, offsetBy: -20,
    limitedBy: b.startIndex) ?? b.startIndex
  while i != xs.endIndex {
     print(b[i])
     b.formIndex(after: &i)
  }
}
Nested Types Mirror.AncestorRepresentation, Mirror.DisplayStyle
Import import Swift

Initializers

init<Subject>(_: Subject, children: DictionaryLiteral<String, Any>, displayStyle: Mirror.DisplayStyle?, ancestorRepresentation: Mirror.AncestorRepresentation)

Represent subject with labeled structure described by children, using an optional displayStyle.

Pass a dictionary literal with String keys as children. Be aware that although an actual Dictionary is arbitrarily-ordered, the ordering of the Mirror's children will exactly match that of the literal you pass.

If subject is not a class instance, ancestorRepresentation is ignored. Otherwise, ancestorRepresentation determines whether ancestor classes will be represented and whether their customMirror implementations will be used. By default, a representation is automatically generated and any customMirror implementation is bypassed. To prevent bypassing customized ancestors, customMirror overrides should initialize the Mirror with:

ancestorRepresentation: .customized({ super.customMirror })

Note: The resulting Mirror's children may be upgraded to AnyRandomAccessCollection later. See the failable initializers of AnyBidirectionalCollection and AnyRandomAccessCollection for details.

Declaration

init<Subject>(_ subject: Subject, children: DictionaryLiteral<String, Any>, displayStyle: Mirror.DisplayStyle? = default, ancestorRepresentation: Mirror.AncestorRepresentation = default)
init<Subject, C where C : Collection, C.Index == C.Indices.Index, C.Indices : Collection, C.Indices == C.Indices.SubSequence, C.SubSequence : Collection, C.SubSequence == C.SubSequence.SubSequence, C.Indices.Index == C.SubSequence.Index, C.Iterator.Element == Mirror.Child, C.SubSequence.Index == C.Indices.Iterator.Element, C.SubSequence.Indices : Collection, C.SubSequence.Indices == C.SubSequence.Indices.SubSequence, C.Indices.Iterator.Element == C.SubSequence.Indices.Index, C.SubSequence.Indices.Index == C.SubSequence.Indices.Iterator.Element, C.SubSequence.Iterator.Element == Mirror.Child>(_: Subject, children: C, displayStyle: Mirror.DisplayStyle?, ancestorRepresentation: Mirror.AncestorRepresentation)

Represent subject with structure described by children, using an optional displayStyle.

If subject is not a class instance, ancestorRepresentation is ignored. Otherwise, ancestorRepresentation determines whether ancestor classes will be represented and whether their customMirror implementations will be used. By default, a representation is automatically generated and any customMirror implementation is bypassed. To prevent bypassing customized ancestors, customMirror overrides should initialize the Mirror with:

ancestorRepresentation: .customized({ super.customMirror })

Note: The traversal protocol modeled by children's indices (ForwardIndex, BidirectionalIndex, or RandomAccessIndex) is captured so that the resulting Mirror's children may be upgraded later. See the failable initializers of AnyBidirectionalCollection and AnyRandomAccessCollection for details.

Declaration

init<Subject, C where C : Collection, C.Index == C.Indices.Index, C.Indices : Collection, C.Indices == C.Indices.SubSequence, C.SubSequence : Collection, C.SubSequence == C.SubSequence.SubSequence, C.Indices.Index == C.SubSequence.Index, C.Iterator.Element == Mirror.Child, C.SubSequence.Index == C.Indices.Iterator.Element, C.SubSequence.Indices : Collection, C.SubSequence.Indices == C.SubSequence.Indices.SubSequence, C.Indices.Iterator.Element == C.SubSequence.Indices.Index, C.SubSequence.Indices.Index == C.SubSequence.Indices.Iterator.Element, C.SubSequence.Iterator.Element == Mirror.Child>(_ subject: Subject, children: C, displayStyle: Mirror.DisplayStyle? = default, ancestorRepresentation: Mirror.AncestorRepresentation = default)
init(_:unlabeledChildren:displayStyle:ancestorRepresentation:)

Represent subject with child values given by unlabeledChildren, using an optional displayStyle. The result's child labels will all be nil.

This initializer is especially useful for the mirrors of collections, e.g.:

extension MyArray : CustomReflectable {
  var customMirror: Mirror {
    return Mirror(self, unlabeledChildren: self, displayStyle: .collection)
  }
}

If subject is not a class instance, ancestorRepresentation is ignored. Otherwise, ancestorRepresentation determines whether ancestor classes will be represented and whether their customMirror implementations will be used. By default, a representation is automatically generated and any customMirror implementation is bypassed. To prevent bypassing customized ancestors, customMirror overrides should initialize the Mirror with:

ancestorRepresentation: .Customized({ super.customMirror })

Note: The traversal protocol modeled by children's indices (ForwardIndex, BidirectionalIndex, or RandomAccessIndex) is captured so that the resulting Mirror's children may be upgraded later. See the failable initializers of AnyBidirectionalCollection and AnyRandomAccessCollection for details.

Declaration

init<Subject, C where C : Collection, C.Index == C.Indices.Index, C.Indices : Collection, C.Indices == C.Indices.SubSequence, C.SubSequence : Collection, C.SubSequence == C.SubSequence.SubSequence, C.Indices.Index == C.Indices.Iterator.Element>(_ subject: Subject, unlabeledChildren: C, displayStyle: Mirror.DisplayStyle? = default, ancestorRepresentation: Mirror.AncestorRepresentation = default)
init(reflecting:)

Reflect upon the given subject.

If the dynamic type of subject conforms to CustomReflectable, the resulting mirror is determined by its customMirror property. Otherwise, the result is generated by the language.

Note: If the dynamic type of subject has value semantics, subsequent mutations of subject will not observable in Mirror. In general, though, the observability of such mutations is unspecified.

Declaration

init(reflecting subject: Any)

Instance Variables

var children: Mirror.Children

A collection of Child elements describing the structure of the reflected subject.

Declaration

var children: Mirror.Children { get }
var customMirror: Mirror

The custom mirror for this instance.

If this type has value semantics, the mirror should be unaffected by subsequent mutations of the instance.

Declaration

var customMirror: Mirror { get }
var description: String

A textual representation of this instance.

Instead of accessing this property directly, convert an instance of any type to a string by using the String(describing:) initializer. For example:

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

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

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

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

Declaration

var description: String { get }
var displayStyle: Mirror.DisplayStyle?

Suggests a display style for the reflected subject.

Declaration

var displayStyle: Mirror.DisplayStyle? { get }
var subjectType: Any.Type

The static type of the subject being reflected.

This type may differ from the subject's dynamic type when self is the superclassMirror of another mirror.

Declaration

var subjectType: Any.Type { get }
var superclassMirror: Mirror?

Declaration

var superclassMirror: Mirror? { get }

Instance Methods

func descendant(_:_:)

Return a specific descendant of the reflected subject, or nil Returns a specific descendant of the reflected subject, or nil if no such descendant exists.

A String argument selects the first Child with a matching label. An integer argument n select the nth Child. For example:

var d = Mirror(reflecting: x).descendant(1, "two", 3)

is equivalent to:

var d = nil
let children = Mirror(reflecting: x).children
if let p0 = children.index(children.startIndex,
  offsetBy: 1, limitedBy: children.endIndex) {
  let grandChildren = Mirror(reflecting: children[p0].value).children
  SeekTwo: for g in grandChildren {
    if g.label == "two" {
      let greatGrandChildren = Mirror(reflecting: g.value).children
      if let p1 = greatGrandChildren.index(
        greatGrandChildren.startIndex,
        offsetBy: 3, limitedBy: greatGrandChildren.endIndex) {
        d = greatGrandChildren[p1].value
      }
      break SeekTwo
    }
  }
}

As you can see, complexity for each element of the argument list depends on the argument type and capabilities of the collection used to initialize the corresponding subject's parent's mirror. Each String argument results in a linear search. In short, this function is suitable for exploring the structure of a Mirror in a REPL or playground, but don't expect it to be efficient.

Declaration

func descendant(_ first: MirrorPath, _ rest: MirrorPath...) -> Any?