Lição 10: Relatórios de Status

Narrativa

Piloto, durante uma missão de longa duração, você não pode simplesmente "ver" o que está acontecendo dentro dos sistemas do mecha. Quando algo falha no calor da batalha, você precisa de informações precisas e imediatas. É aí que entram os Relatórios de Status — mensagens formatadas que registram tudo, desde a temperatura do reator até a integridade estrutural.

Antes de termos painéis holográficos interativos, pilotos confiavam em prints de debug — saídas de texto simples que mostravam o estado interno do sistema. Esta ferramenta básica continua sendo essencial: quando tudo mais falha, um println! bem colocado pode salvar sua missão.

Conceito

Rust oferece várias macros para saída formatada, cada uma com um propósito específico:

format!: Cria uma String formatada sem imprimir. Ideal quando você precisa armazenar o resultado para uso posterior:

let mensagem = format!("Energia: {}%", energia);

println!: Imprime para stdout (saída padrão) com nova linha. Use para informações gerais:

println!("Sistema iniciado às {}", hora);

eprintln!: Imprime para stderr (saída de erro). Use para mensagens de erro ou avisos:

eprintln!("ALERTA: Temperatura crítica!");

dbg!: Macro especial de debug que imprime o valor de uma expressão junto com seu nome e localização no código:

let valor = dbg!(calcular_saida()); // Imprime: [src/lib.rs:42] calcular_saida() = 42

Formatos e Argumentos

Rust suporta múltiplos formatos de exibição:

Display {}: Formato padrão para exibição amigável:

format!("Valor: {}", 42); // "Valor: 42"

Debug {:?}: Formato de debug, útil para desenvolvimento:

format!("Debug: {:?}", (1, 2, 3)); // "Debug: (1, 2, 3)"

Pretty Debug {:#?}: Debug com formatação legível e indentada:

format!("{:#?}", (1, 2, 3))
// "(
//     1,
//     2,
//     3,
// )"

Argumentos Posicionais e Nomeados

Posicionais: Referenciam argumentos por índice {0}, {1}, etc:

format!("Coordenadas: X={0}, Y={1}, Z={2}", x, y, z);
format!("Repetido: {0} {0} {0}", valor); // Pode repetir

Nomeados: Referenciam argumentos por nome para clareza:

format!("{piloto} pilotando {mecha}", piloto="Silva", mecha="Alpha");
// Ou usando variáveis com o mesmo nome:
format!("{piloto} pilotando {mecha}")

Requisitos e Design

Requisitos:

• Entrada: Dados de sensores, status do sistema, coordenadas, informações de missão
• Processamento: Formatação de strings usando macros do Rust
• Saída: Strings formatadas para logs, relatórios e debug

Design de Dados

Esta lição foca na formatação de strings para debugging e logging:

// Formatação de telemetria de sensores
pub fn formatar_telemetria(sensores: &[(&str, f64)]) -> String;

// Geração de logs de missão
pub fn gerar_log_missao(piloto: &str, mecha: &str, duracao: u32) -> String;

// Exibição de status do sistema
pub fn exibir_status_sistema(energia: u32, escudos: u32, vida: u32) -> String;

// Debug de leituras de sensores
pub fn debug_leitura_sensor(nome: &str, valor: f64) -> String;

// Formatação de coordenadas 3D
pub fn formatar_coordenadas(x: f64, y: f64, z: f64) -> String;

Diagrama Conceitual

flowchart TD
    A[Dados Brutos] --> B{Formatação}
    B -->|format!| C[Strings Formatadas]
    B -->|println!| D[Stdout]
    B -->|eprintln!| E[Stderr]
    B -->|dbg!| F[Debug Output]
    C --> G[Logs & Relatórios]
    D --> G
    E --> H[Alertas & Erros]
    F --> I[Desenvolvimento]

Funções e Módulos

//! Lição 10: Relatórios de Status
//!
//! Print debugging — ferramenta essencial para análise de sistemas.

/// Formata dados de telemetria dos sensores
pub fn formatar_telemetria(sensores: &[(&str, f64)]) -> String;

/// Gera log de missão com informações do piloto
pub fn gerar_log_missao(piloto: &str, mecha: &str, duracao: u32) -> String;

/// Exibe status atual do sistema
pub fn exibir_status_sistema(energia: u32, escudos: u32, vida: u32) -> String;

/// Gera mensagem de debug para sensor
pub fn debug_leitura_sensor(nome: &str, valor: f64) -> String;

/// Formata coordenadas 3D
pub fn formatar_coordenadas(x: f64, y: f64, z: f64) -> String;

Exemplo do Conceito

fn main() {
    // format! - cria String sem imprimir
    let energia = 85;
    let status = format!("Energia: {}%", energia);
    println!("{}", status); // Imprime: Energia: 85%
    
    // println! vs eprintln!
    println!("Sistema normal");  // Vai para stdout
    eprintln!("Alerta de erro!"); // Vai para stderr
    
    // dbg! - debug com contexto
    let temperatura = 75.5;
    dbg!(temperatura); // [src/main.rs:10] temperatura = 75.5
    
    // {:?} vs {:#?} - Debug format
    let dados = ("sensor_a", 42.0, true);
    println!("Compact: {:?}", dados);  // ("sensor_a", 42.0, true)
    println!("Pretty: {:#?}", dados);  // Com quebras e indentação
    
    // Argumentos nomeados para clareza
    let piloto = "Silva";
    let mecha = "Alpha-7";
    let msg = format!("{piloto} inicia {mecha}");
    println!("{}", msg);
    
    // Argumentos posicionais
    let x = 10.5;
    let y = 20.25;
    let z = -5.75;
    let coords = format!("X={0:.2}, Y={1:.2}, Z={2:.2}", x, y, z);
    println!("{}", coords); // X=10.50, Y=20.25, Z=-5.75
}

Explicação:

• Linhas 4-5: format! cria strings; println! exibe no terminal
• Linhas 7-9: eprintln! separa erros de saída normal (útil para piping)
• Linha 13: dbg! mostra nome da variável, arquivo e linha automaticamente
• Linhas 17-18: {:?} é compacto; {:#?} é legível para structs complexas
• Linha 23: Argumentos nomeados (mesmo nome da variável) são automáticos
• Linha 30: Argumentos posicionais {0}, {1} permitem repetição e reordenação

Missão

1. Implementar formatar_telemetria: Use format! para criar relatório de sensores, mostrando nome e valor de cada sensor. Mesmo com slice vazio, retorne uma string não-vazia (por exemplo, um cabeçalho como "Telemetria:") — o teste test_formatar_telemetria_vazio checa esse contrato
2. Implementar gerar_log_missao: Use argumentos nomeados para criar log formatado com piloto, mecha e duração
3. Implementar exibir_status_sistema: Retorne string formatada mostrando energia, escudos e vida
4. Implementar debug_leitura_sensor: Use {:?} para debug e retorne string informativa
5. Implementar formatar_coordenadas: Use argumentos posicionais com precisão fixa (2 casas decimais)

Diagrama de Fluxo da Missão

flowchart TD
    A[Tarefa: Formatar Relatórios] --> B[formatar_telemetria<br/>com format!]
    B --> C[gerar_log_missao<br/>com named args]
    C --> D[exibir_status_sistema<br/>retornar string]
    D --> E[debug_leitura_sensor<br/>com Debug fmt]
    E --> F[formatar_coordenadas<br/>com positional args]
    F --> G[Testes verificam<br/>formatos]
    G --> H{Clippy limpo?}
    H -->|Sim| I[Concluído]
    H -->|Não| J[Corrigir warnings] --> G

Como Executar

# Executar testes (vão falhar até implementar)
cargo test

# Verificar compilação
cargo check

# Verificar lint
cargo clippy -- -D warnings

# Formatar código
cargo fmt --check

Dicas

• {} usa Display trait; {:?} usa Debug trait; tipos primitivos têm ambos
• {:.2} limita a 2 casas decimais: format!("{:.2}", 3.14159) → "3.14"
• {:#?} adiciona quebras de linha e indentação para structs complexas
• eprintln! é útil para scripts que redirecionam stdout para arquivos
• dbg! retorna o valor, então pode ser usado inline: let x = dbg!(a + b);
• Argumentos nomeados são ótimos quando a ordem pode mudar ou não é óbvia