Reference

A reference to a captured portion of a regular expression.

iOS
16.0+
macOS
13.0+
tvOS
16.0+
watchOS
9.0+
struct Reference<Capture>

You can use a Reference to access a regular expression, both during the matching process and after a capture has been successful.

In this example, the kind reference captures either "CREDIT" or "DEBIT" at the beginning of a line. Later in the regular expression, the presence of kind matches the same substring that was captured previously at the end of the line.

let kindRef = Reference(Substring.self)
let kindRegex = ChoiceOf {
    "CREDIT"
    "DEBIT"
}

let transactionRegex = Regex {
    Anchor.startOfLine
    Capture(kindRegex, as: kindRef)
    OneOrMore(.anyNonNewline)
    kindRef
    Anchor.endOfLine
}

let validTransaction = "CREDIT     109912311421    Payroll   $69.73  CREDIT"
let invalidTransaction = "DEBIT     00522142123    Expense   $5.17  CREDIT"

print(validTransaction.contains(transactionRegex))
// Prints "true"
print(invalidTransaction.contains(transactionRegex))
// Prints "false"

Any reference that is used for matching must be captured elsewhere in the Regex block. You can use a reference for matching before it is captured; in that case, the reference will not match until it has previously been captured.

To access the captured “transaction kind”, you can use the kind reference to subscript a Regex.Match instance:

if let match = validTransaction.firstMatch(of: transactionRegex) {
    print(match[kindRef])
}
// Prints "CREDIT"

To use a Reference to capture a transformed value, include a transform closure when capturing.

struct Transaction {
    var id: UInt64
}
let transactionRef = Reference(Transaction.self)

let transactionIDRegex = Regex {
    Capture(kindRegex, as: kindRef)
    OneOrMore(.whitespace)
    TryCapture(as: transactionRef) {
        OneOrMore(.digit)
    } transform: { str in
        UInt64(str).map(Transaction.init(id:))
    }
    OneOrMore(.anyNonNewline)
    kindRef
    Anchor.endOfLine
}

if let match = validTransaction.firstMatch(of: transactionIDRegex) {
    print(match[transactionRef])
}
// Prints "Transaction(id: 109912311421)"