Associated Values em Swift: o que é, sintaxe e exemplos

O que são Associated Values?

Associated Values são informações adicionais que um caso de enum pode armazenar consigo mesmo. Ao contrário dos raw values, que são fixos no nível de declaração, os associated values são definidos ao criar uma instância de enum.

Imagine modelar um método de pagamento: o caso creditCard pode armazenar os últimos 4 dígitos e a data de validade, enquanto o caso applePay não armazena nada. Com associated values, isso é implementado naturalmente, sem subclasses ou campos opcionais.

De acordo com a documentação da Apple, os associated values transformam um enum de um simples conjunto de constantes em um tipo de dado algébrico (sum type), característico de linguagens funcionais. Isso aumenta significativamente a expressividade do código.

Sintaxe de associated values

Os Associated Values são declarados entre parênteses após o caso, especificando nomes e tipos de parâmetros, como em funções.

enum MediaFile {
    case image(width: Int, height: Int, format: String)
    case video(duration: Double, codec: String)
    case audio(bitrate: Int)
    case unknown
}

Ao criar uma instância, os associated values são passados como argumentos:

let photo = MediaFile.image(width: 1920, height: 1080, format: "jpeg")
let clip = MediaFile.video(duration: 120.5, codec: "h264")

O Swift não impõe restrições quanto ao número ou tipos de associated values. Você pode usar genéricos, funções de fechamento e outros enums dentro de associated values. Isso possibilita a construção de estruturas aninhadas complexas.

Os nomes dos parâmetros de associated values são usados como rótulos de argumento ao criar uma instância — isso melhora a legibilidade do código. Ao extrair via switch, os nomes servem como documentação, esclarecendo o significado de cada valor. Essa abordagem torna o código autodocumentado e reduz a probabilidade de erros ao corresponder dados. Isso é especialmente valioso no desenvolvimento em equipe de grandes aplicativos iOS.

Switch com associated values

Switch é a principal forma de extrair associated values. Os valores são vinculados a constantes ou variáveis via let ou var.

func describe(_ file: MediaFile) -> String {
    switch file {
    case .image(let w, let h, let fmt):
        return "Image \(w)x\(h) .\(fmt)"
    case .video(let duration, let codec):
        return "Video \(duration)s, \(codec)"
    case .audio(let bitrate):
        return "Audio \(bitrate)kbps"
    case .unknown:
        return "Unknown format"
    }
}

O Swift suporta correspondência parcial — você pode especificar valores concretos para associated values:

switch file {
case .image(let w, let h, "png"):
    print("Imagem PNG \(w)x\(h)")
case .image(1920, 1080, _):
    print("Imagem Full HD")
default:
    break
}

Usar um curinga (_) permite ignorar associated values desnecessários, e constantes nos casos permitem verificar correspondências com valores específicos.

Associated Values vs Raw Values

Muitos desenvolvedores iniciantes confundem associated values com raw values. São mecanismos diferentes com casos de uso diferentes.

De acordo com Swift Evolution, os associated values foram introduzidos no Swift 2.0 como parte do redesenho do enum. Eles fornecem uma abordagem algébrica para tipos, onde cada caso é um construtor separado com sua própria assinatura.

Exemplos práticos de associated values

Os Associated Values são ativamente usados em projetos iOS reais. Vamos considerar três cenários típicos.

Modelagem de respostas de API

enum APIResponse<T: Codable> {
    case success(data: T, cached: Bool)
    case failure(error: Error, retryAvailable: Bool)
    case loading(progress: Double)
}

Máquina de Estados de UI

enum ViewState<T> {
    case idle
    case loading(message: String)
    case loaded(data: T)
    case error(message: String, retryAction: () -> Void)
}

Com associated values, o enum se torna uma ferramenta poderosa para máquinas de estado: cada caso é um estado, os associated values são parâmetros desse estado. O compilador garante que todas as transições sejam tratadas.

Extração via if case e guard case

Para verificar um único caso sem switch, use if case ou guard case. Isso é mais compacto quando você precisa lidar apenas com uma opção.

let error = NetworkError.timeout(seconds: 30)

if case .timeout(let seconds) = error {
    print("Solicitação expirou após \(seconds)s")
}

guard case .httpError(let code, _) = error else {
    return
}
print("Erro HTTP com código \(code)")