Rust idiomático: contratos, não gosto pessoal

ENTENDA A IDEIA

A ideia central

Uma revisão de código se parece com uma inspeção de ponte. Primeiro, o engenheiro confirma se a estrutura suporta a carga. Depois, confere as dimensões do projeto e as interfaces com as vias existentes. A cor da tinta e a posição das placas entram depois. Se alguém começa pela tinta enquanto uma viga está quebrada, a discussão está na ordem errada.

Código Rust também tem camadas diferentes. Correção responde se o programa produz o resultado prometido sem panic inesperado, corrida de dados ou comportamento indefinido. Contrato público responde o que chamadores podem observar: assinatura, valores, erros, efeitos, custo documentado e compatibilidade. Forma idiomática usa construções reconhecidas pelo ecossistema para comunicar intenção e reduzir estados acidentais. Convenção local resolve escolhas equivalentes dentro de um repositório, como nomes de módulos, ordem de helpers e política de mensagens.

ENTENDA A IDEIA

A ideia central

Essas camadas não têm o mesmo peso. Um iterador elegante não corrige uma soma errada. Um lint não autoriza quebrar uma assinatura pública. Uma preferência da equipe não transforma uma alocação necessária em defeito. A revisão madura pergunta, em ordem: está correto; preserva o contrato; a forma escolhida tem uma razão Rust; a convenção local decide o restante?

As Rust API Guidelines fornecem vocabulário para APIs previsíveis. Elas não certificam uma única resposta para todo domínio. A Rust Reference define a linguagem, não um manual completo de design. Este curso usa essas fontes como apoio técnico e reescreve exemplos de forma independente. O Rust Project não certifica, afilia ou endossa este curso.

ENTENDA A IDEIA

A ideia central

O primeiro exemplo da aula é `&Vec

contra&[String]. Os dois podem ler os mesmos elementos. O slice pede menos: uma sequência contígua emprestada, não o tipo concreto Vec. Essa forma costuma ser melhor porque amplia os chamadores aceitos e registra que a função não precisa de capacity, pushou ownership do vetor. Porém, isso é uma decisão de API, não uma lei de gosto. Se a função realmente usa uma operação específica deVec`, esconder esse fato atrás de outro tipo piora o contrato.

PASSO A PASSO

Visualização passo a passo

VISUALIZAÇÃOVisualização passo a passo

1 / 5

CÓDIGO ANOTADO

Código anotado

O programa modela uma revisão pequena. A função recebe um slice porque somente percorre nomes. Ela devolve um relatório com fatos observáveis, em vez de uma opinião vaga como “ficou mais Rust”. O antes usava `&Vec

` e produzia a mesma contagem. O depois reduz a exigência da fronteira sem mudar o resultado.

src/main.rs

#[derive(Debug, PartialEq)]
struct ReviewReport {
    visible: usize,
    contract_preserved: bool,
}

fn count_visible(names: &[String]) -> usize {
    names.iter().filter(|name| !name.trim().is_empty()).count()
}

CÓDIGO ANOTADO

Código anotado

A segunda função deixa explícita a ordem do processo. Ela não tenta representar toda revisão possível. Ela registra duas provas mínimas: a contagem continua correta e os rótulos públicos esperados continuam iguais.

src/main.rs

fn review(before: &[String], after: &[String]) -> ReviewReport {
    ReviewReport {
        visible: count_visible(after),
        contract_preserved: before == after,
    }
}

CÓDIGO ANOTADO

Código anotado

O main congela uma entrada e compara a versão antes com a versão depois. Em um projeto real, o “antes” viria de testes de caracterização. Aqui, a igualdade torna o contrato visível sem rede, relógio ou estado externo.

A saída é visíveis: 2 e contrato preservado: true. O clone existe somente para criar duas versões comparáveis no exemplo. Ele não faz parte da recomendação de API. Em uma refatoração real, os mesmos testes executam antes e depois sobre commits diferentes.

O motivo para preferir &[String] aparece na assinatura. Um slice pode vir de um Vec, de um array ou de uma fatia menor. A função também não pode aumentar a coleção. Essa restrição reduz o espaço de comportamento que o leitor precisa considerar. O ganho não é um número mágico de desempenho; é um contrato mais preciso.

Agora o contraexemplo. Imagine `fn reserve_for_import(rows: &mut Vec

, extra: usize). Essa função chama rows.reserve(extra)porque o objetivo é preparar capacidade antes de uma importação. Trocar&mut Vec

por&mut [Row]seria impossível sem remover a operação central. A regra “sempre aceite slices” aplicada cegamente apagaria a necessidade real. A forma idiomática segue o menor poder necessário, e nesse caso o poder necessário pertence aoVec`.

A convenção local entra depois. Uma equipe pode chamar o relatório de ReviewReport; outra usa Audit. Se ambos os nomes descrevem o mesmo conceito e não afetam usuários, consistência local pode decidir. Mas uma regra interna que exige &String em todas as funções contradiz a intenção de aceitar texto emprestado de várias origens. Convenção local não deve estreitar uma API sem motivo de domínio.

O contrato público merece cuidado adicional. Trocar &String por &str costuma ser compatível para chamadas comuns no código-fonte, mas bibliotecas públicas precisam avaliar compatibilidade de tipos, traits, ponteiros de função, documentação e política SemVer. “Os testes do nosso binário passaram” não prova que todos os consumidores externos continuam compilando. Quanto maior a superfície pública, maior a prova exigida.

Uma decisão útil também registra o que não será alterado. Nesta revisão, a contagem, o tratamento de whitespace e a ordem da coleção ficam congelados. Somente a capacidade exigida do parâmetro muda. Essa frase reduz o impulso de “aproveitar” o diff para renomear itens, trocar o iterador, mudar mensagens e criar validação. Cada melhoria adicional pode ser válida, mas cada uma pede uma prova própria.

A mesma separação ajuda quando a sugestão vem de uma ferramenta. Um diagnóstico do compilador aponta uma obrigação da linguagem. Um lint aponta um padrão que merece revisão. Um formatador escolhe a apresentação. Um guia descreve convenções recorrentes. Nenhum deles conhece sozinho o contrato comercial, a compatibilidade prometida ou os dados que o sistema recebe. A pessoa que refatora combina o sinal da ferramenta com os fatos do domínio.

Pense em uma função pública que recebe String por valor e guarda o texto em uma struct. Um comentário automático pode sugerir empréstimo ao observar um corpo curto, mas &str não pode sobreviver ao retorno sem mudar a modelagem de lifetime. Receber ownership pode ser exatamente o contrato correto. Em outra função que somente calcula o comprimento durante a chamada, receber String força o chamador a mover ou clonar sem necessidade. A mesma palavra String aparece nos dois casos; o tempo de vida do dado decide formas diferentes.

Também existe uma diferença entre regra e heurística. “Não altere comportamento durante este refactor” é uma regra para a mudança atual. “Prefira slices a referências de vetores quando somente lê elementos” é uma heurística de API. A primeira define o objetivo da mudança. A segunda depende do uso real. Marcar essa diferença impede que uma heurística ganhe autoridade que não possui. Registre a exceção perto da decisão, com o motivo e a prova, para evitar que a próxima revisão repita a discussão sem contexto.

Use comentários de revisão com a camada nomeada. “Isto está errado para entrada vazia” é correção. “Esta mudança remove uma variante que os chamadores tratam” é contrato. “Aceite &str porque a função somente lê texto e isso inclui literais e String” é idioma com razão. “Neste crate, helpers privados usam o prefixo parse_” é convenção local. O comentário deixa de parecer gosto porque diz qual risco reduz.

src/main.rs

fn main() {
    let before = vec![String::from("Ana"), String::new(), String::from(" Rui ")];
    let after = before.clone();
    let report = review(&before, &after);

    println!("visíveis: {}", report.visible);
    println!("contrato preservado: {}", report.contract_preserved);
}

PRÁTICA LOCAL

Pratique no seu computador

Antes de executar, preveja as duas contagens. Depois, troque o array por um `Vec

e confirme que a chamada continua igual. Por fim, passe somente&names[1..]` e observe que o slice permite revisar uma parte sem criar outra coleção.

Agora faça uma alteração deliberadamente errada: use filter(|name| !name.is_empty()). Preveja o resultado para a string com dois espaços. O programa compila e a forma continua idiomática, mas o contrato de “nome visível após trim” quebra. Esta alteração separa sintaxe reconhecível de correção.

Depois restaure o trim e renomeie count_visible para visible_count. Nenhum teste de resultado deve mudar. Essa escolha pode ser decidida pela convenção local, porque as duas formas comunicam o mesmo contrato. Registre a diferença: a primeira alteração exigia teste de comportamento; a segunda exige consistência de nomes.

Adapte o trecho no projeto local da aula. Confira a saída esperada no enunciado.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Pratique no seu computador

fn count_visible(names: &[String]) -> usize {
    names.iter().filter(|name| !name.trim().is_empty()).count()
}

fn main() {
    let names = [
        String::from("Ada"),
        String::from("  "),
        String::from("Linus"),
    ];
    println!("todos={}", count_visible(&names));
    println!("cauda={}", count_visible(&names[1..]));
}

Comandos locais

cargo new --bin --edition 2024 exemplo-rust
cd exemplo-rust
# Use o código no projeto da aula.
cargo run
cargo clippy -- -D warnings

Rust Playground (opcional)

DESAFIO LOCAL

Troque &Vec por slice sem mudar a contagem

`count_visible(names: &Vec

) -> usizejá devolve a quantidade correta de nomes que não ficam vazios apóstrim. O stub passa nos testes de comportamento, mas exige o tipo concreto Vecsem usar nenhuma operação específica dele. Refatore somente a fronteira paranames: &[String]`.

Entrada: uma referência para uma coleção de String. Saída: a quantidade de itens cujo conteúdo aparado não é vazio. ['Ana', '', ' Rui '] produz 2; uma coleção vazia produz 0; [' ', 'Mia'] produz 1.

Preserve o corpo, a ordem e o custo O(n). Não aloque outra coleção e não mude String para &str dentro do slice, pois isso seria outra mudança de contrato. Rode primeiro o stub e guarde os três RESULT. Depois altere somente a assinatura e rode novamente. O harness confirma o comportamento. O scanner confirma a assinatura pública selecionada, sem afirmar que analisou todo o contrato.

O #[allow(clippy::ptr_arg)] do stub é local e tem uma razão: ele mantém compilável a forma que o exercício deve remover. A solução não precisa da exceção. Não transforme essa licença didática em orientação para silenciar o lint no módulo inteiro.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Exercício 1

Troque &Vec por slice sem mudar a contagem

stub.rs

#[allow(
    clippy::ptr_arg,
    reason = "o exercício começa com a API que será refatorada"
)]
pub fn count_visible(names: &Vec<String>) -> usize {
    names.iter().filter(|name| !name.trim().is_empty()).count()
}

harness.rs

fn json_escape(value: &str) -> String {
    value
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n")
}

fn print_result(case: usize, pass: bool, input: &str, want: &str, got: &str) {
    println!(
        "RESULT {{\"case\":{case},\"pass\":{pass},\"input\":\"{}\",\"want\":\"{}\",\"got\":\"{}\"}}",
        json_escape(input),
        json_escape(want),
        json_escape(got)
    );
}

fn main() {
    let cases = [
        (
            vec!["Ana", "", " Rui "],
            "[\"Ana\", \"\", \" Rui \" ]",
            2usize,
        ),
        (vec![], "[]", 0usize),
        (vec!["  ", "Mia"], "[\"  \", \"Mia\"]", 1usize),
    ];
    for (index, (raw, input, want)) in cases.into_iter().enumerate() {
        let names: Vec<String> = raw.into_iter().map(String::from).collect();
        let got = count_visible(&names);
        print_result(
            index + 1,
            got == want,
            input,
            &want.to_string(),
            &got.to_string(),
        );
    }
}

cases.json

[
  {
    "case": 1,
    "input": "[\"Ana\", \"\", \" Rui \" ]",
    "want": "2"
  },
  {
    "case": 2,
    "input": "[]",
    "want": "0"
  },
  {
    "case": 3,
    "input": "[\"  \", \"Mia\"]",
    "want": "1"
  }
]

source-check.mjs

import { readFileSync } from 'node:fs';

const requirements = {
  "required": [
    {
      "label": "count_visible é uma função pública que recebe slice",
      "pattern": "pub\\s+fn\\s+count_visible\\s*\\(\\s*names\\s*:\\s*&\\s*\\[\\s*String\\s*\\]"
    }
  ],
  "forbidden": [
    {
      "label": "a exceção antiga de ptr_arg foi removida",
      "pattern": "clippy\\s*::\\s*ptr_arg"
    }
  ],
  "scopes": [
    {
      "label": "função pública count_visible",
      "start_pattern": "pub\\s+fn\\s+count_visible\\s*\\(\\s*names\\s*:\\s*&\\s*\\[\\s*String\\s*\\]",
      "required": [
        {
          "label": "count_visible filtra nomes visíveis",
          "pattern": "names\\s*\\.\\s*iter\\s*\\(\\s*\\)[\\s\\S]*?\\.\\s*filter\\s*\\("
        }
      ],
      "forbidden": [
        {
          "label": "count_visible não recria um Vec",
          "pattern": "\\bVec\\s*::|\\.\\s*(?:to_vec|to_owned|collect)\\s*\\("
        }
      ]
    }
  ]
};
const file = process.argv[2] || 'stub.rs';
const source = readFileSync(file, 'utf8');
function rustCodeOnly(source) {
  let output = '';
  let index = 0;
  let blockDepth = 0;
  let state = 'code';
  let rawEnd = '';
  while (index < source.length) {
    const current = source[index];
    const next = source[index + 1];
    if (state === 'line-comment') {
      if (current === '\n') { state = 'code'; output += '\n'; } else output += ' ';
      index += 1;
      continue;
    }
    if (state === 'block-comment') {
      if (current === '/' && next === '*') { blockDepth += 1; output += '  '; index += 2; }
      else if (current === '*' && next === '/') {
        blockDepth -= 1; output += '  '; index += 2;
        if (blockDepth === 0) state = 'code';
      } else { output += current === '\n' ? '\n' : ' '; index += 1; }
      continue;
    }
    if (state === 'string') {
      if (current === '\\') { output += '  '; index += Math.min(2, source.length - index); }
      else { output += current === '\n' ? '\n' : ' '; index += 1; if (current === '"') state = 'code'; }
      continue;
    }
    if (state === 'raw-string') {
      if (source.startsWith(rawEnd, index)) {
        output += ' '.repeat(rawEnd.length); index += rawEnd.length; state = 'code';
      } else { output += current === '\n' ? '\n' : ' '; index += 1; }
      continue;
    }
    if (current === '/' && next === '/') { state = 'line-comment'; output += '  '; index += 2; continue; }
    if (current === '/' && next === '*') { state = 'block-comment'; blockDepth = 1; output += '  '; index += 2; continue; }
    const raw = /^(?:br|r)(#+)?"/.exec(source.slice(index));
    if (raw) {
      const hashes = raw[1] || ''; rawEnd = '"' + hashes; state = 'raw-string';
      output += ' '.repeat(raw[0].length); index += raw[0].length; continue;
    }
    if (current === 'b' && next === '"') { state = 'string'; output += '  '; index += 2; continue; }
    const character = /^(?:b)?'(?:\\.|[^'\\])'/.exec(source.slice(index));
    if (character) { output += ' '.repeat(character[0].length); index += character[0].length; continue; }
    if (current === '"') { state = 'string'; output += ' '; index += 1; continue; }
    output += current;
    index += 1;
  }
  return output;
}
const code = rustCodeOnly(source);
const errors = [];
function evaluate(sourceCode, contract, prefix = '') {
  for (const item of contract.required || []) {
    const matches = [...sourceCode.matchAll(new RegExp(item.pattern, 'gms'))].length;
    const minimum = item.min_count || 1;
    if (matches < minimum) errors.push(`${prefix}ausente: ${item.label} (esperado ${minimum}, encontrado ${matches})`);
  }
  for (const item of contract.forbidden || []) {
    const matches = [...sourceCode.matchAll(new RegExp(item.pattern, 'gms'))].length;
    const minimum = item.min_count || 1;
    if (matches >= minimum) errors.push(`${prefix}proibido: ${item.label} (limite ${minimum - 1}, encontrado ${matches})`);
  }
  for (const sequence of contract.ordered || []) {
    let cursor = 0;
    let valid = true;
    for (const pattern of sequence.patterns) {
      const match = new RegExp(pattern, 'ms').exec(sourceCode.slice(cursor));
      if (!match) { valid = false; break; }
      cursor += match.index + match[0].length;
    }
    if (!valid) errors.push(`${prefix}ordem inválida: ${sequence.label}`);
  }
}
function itemBody(scope) {
  const matches = [...code.matchAll(new RegExp(scope.start_pattern, 'gms'))];
  if (matches.length !== 1) {
    errors.push(`escopo ${scope.label} precisa identificar um item; encontrado ${matches.length}`);
    return null;
  }
  const start = matches[0].index + matches[0][0].length;
  let opening = -1;
  for (let index = start; index < code.length; index += 1) {
    if (code[index] === ';') { errors.push(`escopo ${scope.label} não possui corpo`); return null; }
    if (code[index] === '{') { opening = index; break; }
  }
  if (opening === -1) { errors.push(`escopo ${scope.label} não possui chave de abertura`); return null; }
  let depth = 0;
  for (let index = opening; index < code.length; index += 1) {
    if (code[index] === '{') depth += 1;
    else if (code[index] === '}') {
      depth -= 1;
      if (depth === 0) return code.slice(opening + 1, index);
    }
  }
  errors.push(`escopo ${scope.label} possui chaves sem fechamento`);
  return null;
}
if (!requirements.allow_cfg && /#\s*!?\s*\[\s*cfg(?:_attr)?\b/ms.test(code)) {
  errors.push('atributos cfg são proibidos neste exercício');
}
evaluate(code, requirements);
for (const scope of requirements.scopes || []) {
  const body = itemBody(scope);
  if (body !== null) evaluate(body, scope, `escopo ${scope.label}: `);
}
if (errors.length) {
  console.error('Contrato de fonte não atendido:\n- ' + errors.join('\n- '));
  process.exit(1);
}
console.log('Contrato de fonte atendido.');

Casos e valores esperados

Caso	Entrada	Valor esperado
1	`["Ana", "", " Rui " ]`	`2`
2	`[]`	`0`
3	`[" ", "Mia"]`	`1`

Execute com o Cargo local

Execute os comandos de preparação.
Copie os arquivos acima para os arquivos vazios com os mesmos nomes.
Execute a verificação de base. O stub deve mostrar o comportamento atual.
Edite stub.rs. Depois, execute a verificação final da forma da fonte.

Comandos de preparação

cargo new --bin --edition 2024 jeitorust-01-contratos-nao-gosto-exercicio-1
cd jeitorust-01-contratos-nao-gosto-exercicio-1
touch stub.rs harness.rs cases.json source-check.mjs
printf 'include!("../stub.rs");\ninclude!("../harness.rs");\n' > src/main.rs

Verificação de base — confirme o comportamento atual antes da mudança

cargo fmt --check
cargo run --bin jeitorust-01-contratos-nao-gosto-exercicio-1
cargo clippy -- -D warnings

Verificação final — confirme a forma da fonte após a mudança

node source-check.mjs stub.rs

Abrir o Rust Playground (opcional)

Mostrar dicas

O corpo já preserva o comportamento; altere somente o tipo aceito na fronteira.
Use names: &[String]; uma referência a Vec<String> sofre coerção para slice no chamador.

Revelar solução

solution.rs

pub fn count_visible(names: &[String]) -> usize {
    names.iter().filter(|name| !name.trim().is_empty()).count()
}

O slice aceita Vec e outras sequências contíguas sem ampliar poderes da função; os casos confirmam a contagem, e o scanner confirma a sintaxe selecionada da fronteira.

A solução pede somente um slice. `Vec

sofre coerção para&[String]`, por isso o harness não precisa mudar. Arrays e subslices também passam a ser aceitos. O tempo permanece O(n), e o espaço adicional permanece O(1).

pub fn count_visible(names: &[String]) -> usize {
    names.iter().filter(|name| !name.trim().is_empty()).count()
}

O caso de borda são strings com whitespace. A refatoração não toca no trim, então " " continua invisível. Uma alternativa recebe `impl IntoIterator

`, mas ela move elementos e amplia muito mais o contrato. Isso seria adequado para uma função consumidora, não para uma leitura emprestada.

A aplicação cega também falha se a função precisar de reserve, capacity ou outra operação própria de Vec. Nesse caso, &Vec ou &mut Vec pode representar uma necessidade real. A pergunta não é “slice é mais bonito”; é “qual poder esta função usa?”.

DESAFIO LOCAL

Generalize o prefixo público para &str

public_label(prefix: &String, id: u64) -> String formata um identificador público. O formato prefixo-0000 já está correto e precisa permanecer byte a byte igual. O tipo String, porém, é mais estreito que a necessidade: a função somente lê texto.

Entrada: um prefixo textual e um inteiro sem sinal. Saída: o prefixo, um hífen e o id com quatro dígitos mínimos. ("pedido", 7) produz "pedido-0007"; ("X", 42) produz "X-0042"; ("", 0) produz "-0000".

Troque &String por &str. Não altere a máscara de format!, não remova zeros e não valide prefixo vazio. O caso vazio parece estranho, mas faz parte do contrato congelado. Uma revisão separada pode discutir se ele deve ser recusado.

Este exercício combina duas provas. O harness protege o contrato textual. O requisito de fonte procura a assinatura &str e a máscara. Comentários, strings comuns, strings raw e strings raw de bytes não satisfazem o scanner; a construção precisa existir no código.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Exercício 2

Generalize o prefixo público para &str

stub.rs

#[allow(
    clippy::ptr_arg,
    reason = "o exercício começa com a API que será refatorada"
)]
pub fn public_label(prefix: &String, id: u64) -> String {
    format!("{prefix}-{id:04}")
}

harness.rs

fn json_escape(value: &str) -> String {
    value
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n")
}

fn print_result(case: usize, pass: bool, input: &str, want: &str, got: &str) {
    println!(
        "RESULT {{\"case\":{case},\"pass\":{pass},\"input\":\"{}\",\"want\":\"{}\",\"got\":\"{}\"}}",
        json_escape(input),
        json_escape(want),
        json_escape(got)
    );
}

fn main() {
    let cases = [
        ("pedido", 7u64, "(\"pedido\", 7)", "pedido-0007"),
        ("X", 42u64, "(\"X\", 42)", "X-0042"),
        ("", 0u64, "(\"\", 0)", "-0000"),
    ];
    for (index, (prefix, id, input, want)) in cases.into_iter().enumerate() {
        let owned = String::from(prefix);
        let got = public_label(&owned, id);
        print_result(index + 1, got == want, input, want, &got);
    }
}

cases.json

[
  {
    "case": 1,
    "input": "(\"pedido\", 7)",
    "want": "pedido-0007"
  },
  {
    "case": 2,
    "input": "(\"X\", 42)",
    "want": "X-0042"
  },
  {
    "case": 3,
    "input": "(\"\", 0)",
    "want": "-0000"
  }
]

source-check.mjs

import { readFileSync } from 'node:fs';

const requirements = {
  "required": [
    {
      "label": "public_label é uma função pública que recebe &str",
      "pattern": "pub\\s+fn\\s+public_label\\s*\\(\\s*prefix\\s*:\\s*&\\s*str\\b"
    }
  ],
  "forbidden": [
    {
      "label": "a exceção antiga de ptr_arg foi removida",
      "pattern": "clippy\\s*::\\s*ptr_arg"
    }
  ],
  "scopes": [
    {
      "label": "função pública public_label",
      "start_pattern": "pub\\s+fn\\s+public_label\\s*\\(\\s*prefix\\s*:\\s*&\\s*str\\b",
      "required": [
        {
          "label": "public_label usa format!",
          "pattern": "\\bformat\\s*!\\s*\\("
        }
      ],
      "forbidden": [
        {
          "label": "public_label não cria cópia intermediária do prefixo",
          "pattern": "\\.\\s*(?:to_owned|to_string)\\s*\\("
        }
      ]
    }
  ]
};
const file = process.argv[2] || 'stub.rs';
const source = readFileSync(file, 'utf8');
function rustCodeOnly(source) {
  let output = '';
  let index = 0;
  let blockDepth = 0;
  let state = 'code';
  let rawEnd = '';
  while (index < source.length) {
    const current = source[index];
    const next = source[index + 1];
    if (state === 'line-comment') {
      if (current === '\n') { state = 'code'; output += '\n'; } else output += ' ';
      index += 1;
      continue;
    }
    if (state === 'block-comment') {
      if (current === '/' && next === '*') { blockDepth += 1; output += '  '; index += 2; }
      else if (current === '*' && next === '/') {
        blockDepth -= 1; output += '  '; index += 2;
        if (blockDepth === 0) state = 'code';
      } else { output += current === '\n' ? '\n' : ' '; index += 1; }
      continue;
    }
    if (state === 'string') {
      if (current === '\\') { output += '  '; index += Math.min(2, source.length - index); }
      else { output += current === '\n' ? '\n' : ' '; index += 1; if (current === '"') state = 'code'; }
      continue;
    }
    if (state === 'raw-string') {
      if (source.startsWith(rawEnd, index)) {
        output += ' '.repeat(rawEnd.length); index += rawEnd.length; state = 'code';
      } else { output += current === '\n' ? '\n' : ' '; index += 1; }
      continue;
    }
    if (current === '/' && next === '/') { state = 'line-comment'; output += '  '; index += 2; continue; }
    if (current === '/' && next === '*') { state = 'block-comment'; blockDepth = 1; output += '  '; index += 2; continue; }
    const raw = /^(?:br|r)(#+)?"/.exec(source.slice(index));
    if (raw) {
      const hashes = raw[1] || ''; rawEnd = '"' + hashes; state = 'raw-string';
      output += ' '.repeat(raw[0].length); index += raw[0].length; continue;
    }
    if (current === 'b' && next === '"') { state = 'string'; output += '  '; index += 2; continue; }
    const character = /^(?:b)?'(?:\\.|[^'\\])'/.exec(source.slice(index));
    if (character) { output += ' '.repeat(character[0].length); index += character[0].length; continue; }
    if (current === '"') { state = 'string'; output += ' '; index += 1; continue; }
    output += current;
    index += 1;
  }
  return output;
}
const code = rustCodeOnly(source);
const errors = [];
function evaluate(sourceCode, contract, prefix = '') {
  for (const item of contract.required || []) {
    const matches = [...sourceCode.matchAll(new RegExp(item.pattern, 'gms'))].length;
    const minimum = item.min_count || 1;
    if (matches < minimum) errors.push(`${prefix}ausente: ${item.label} (esperado ${minimum}, encontrado ${matches})`);
  }
  for (const item of contract.forbidden || []) {
    const matches = [...sourceCode.matchAll(new RegExp(item.pattern, 'gms'))].length;
    const minimum = item.min_count || 1;
    if (matches >= minimum) errors.push(`${prefix}proibido: ${item.label} (limite ${minimum - 1}, encontrado ${matches})`);
  }
  for (const sequence of contract.ordered || []) {
    let cursor = 0;
    let valid = true;
    for (const pattern of sequence.patterns) {
      const match = new RegExp(pattern, 'ms').exec(sourceCode.slice(cursor));
      if (!match) { valid = false; break; }
      cursor += match.index + match[0].length;
    }
    if (!valid) errors.push(`${prefix}ordem inválida: ${sequence.label}`);
  }
}
function itemBody(scope) {
  const matches = [...code.matchAll(new RegExp(scope.start_pattern, 'gms'))];
  if (matches.length !== 1) {
    errors.push(`escopo ${scope.label} precisa identificar um item; encontrado ${matches.length}`);
    return null;
  }
  const start = matches[0].index + matches[0][0].length;
  let opening = -1;
  for (let index = start; index < code.length; index += 1) {
    if (code[index] === ';') { errors.push(`escopo ${scope.label} não possui corpo`); return null; }
    if (code[index] === '{') { opening = index; break; }
  }
  if (opening === -1) { errors.push(`escopo ${scope.label} não possui chave de abertura`); return null; }
  let depth = 0;
  for (let index = opening; index < code.length; index += 1) {
    if (code[index] === '{') depth += 1;
    else if (code[index] === '}') {
      depth -= 1;
      if (depth === 0) return code.slice(opening + 1, index);
    }
  }
  errors.push(`escopo ${scope.label} possui chaves sem fechamento`);
  return null;
}
if (!requirements.allow_cfg && /#\s*!?\s*\[\s*cfg(?:_attr)?\b/ms.test(code)) {
  errors.push('atributos cfg são proibidos neste exercício');
}
evaluate(code, requirements);
for (const scope of requirements.scopes || []) {
  const body = itemBody(scope);
  if (body !== null) evaluate(body, scope, `escopo ${scope.label}: `);
}
if (errors.length) {
  console.error('Contrato de fonte não atendido:\n- ' + errors.join('\n- '));
  process.exit(1);
}
console.log('Contrato de fonte atendido.');

Casos e valores esperados

Caso	Entrada	Valor esperado
1	`("pedido", 7)`	`pedido-0007`
2	`("X", 42)`	`X-0042`
3	`("", 0)`	`-0000`

Execute com o Cargo local

Execute os comandos de preparação.
Copie os arquivos acima para os arquivos vazios com os mesmos nomes.
Execute a verificação de base. O stub deve mostrar o comportamento atual.
Edite stub.rs. Depois, execute a verificação final da forma da fonte.

Comandos de preparação

cargo new --bin --edition 2024 jeitorust-01-contratos-nao-gosto-exercicio-2
cd jeitorust-01-contratos-nao-gosto-exercicio-2
touch stub.rs harness.rs cases.json source-check.mjs
printf 'include!("../stub.rs");\ninclude!("../harness.rs");\n' > src/main.rs

Verificação de base — confirme o comportamento atual antes da mudança

cargo fmt --check
cargo run --bin jeitorust-01-contratos-nao-gosto-exercicio-2
cargo clippy -- -D warnings

Verificação final — confirme a forma da fonte após a mudança

node source-check.mjs stub.rs

Abrir o Rust Playground (opcional)

Mostrar dicas

O formato textual é contrato; o tipo concreto String não precisa ser.
Troque somente &String por &str e mantenha format!("{prefix}-{id:04}").

Revelar solução

solution.rs

pub fn public_label(prefix: &str, id: u64) -> String {
    format!("{prefix}-{id:04}")
}

&str aceita String, literais e fatias de texto; o harness preserva cada byte do rótulo e o requisito estrutural impede manter a assinatura estreita.

&str descreve texto UTF-8 emprestado sem exigir a alocação concreta String. O chamador continua podendo passar &owned, mas também pode passar um literal ou uma fatia. A formatação mantém tempo O(p), onde p é o tamanho da saída, e espaço O(p) para a nova String.

pub fn public_label(prefix: &str, id: u64) -> String {
    format!("{prefix}-{id:04}")
}

O prefixo vazio preserva "-0000". Uma alternativa aceita impl AsRef<str>, mas adiciona genericidade sem benefício para uma função que só precisa emprestar durante a chamada. Esse tipo genérico pode aumentar monomorfizações e tornar ponteiros de função menos diretos. &str é a fronteira menor.

Não aplique a regra cegamente a uma função que precisa guardar o texto depois do retorno. Nesse caso, receber String por valor pode comunicar transferência de ownership e evitar clone. O melhor tipo nasce do tempo de vida e do uso, não de uma tabela fixa.

RESUMO DA AULA

O que você leva desta aula

Correção vem antes de idioma: código elegante ainda pode devolver o valor errado.
O contrato público limita refactors por assinatura, valores, erros, efeitos e compatibilidade.
A forma idiomática reduz poderes e estados quando existe uma razão técnica verificável.
A convenção local decide escolhas equivalentes; ela não pode contradizer o domínio ou apagar compatibilidade.
Testes de comportamento e requisitos de fonte provam coisas diferentes e devem trabalhar juntos.
A próxima aula automatiza a camada de forma com rustfmt para liberar a revisão de design.

+145 XPpossíveis nesta aula

A ideia central

A ideia central

A ideia central

Visualização passo a passo

Código anotado

Código anotado

Código anotado

Pratique no seu computador

Troque &Vec por slice sem mudar a contagem

Casos e valores esperados

Execute com o Cargo local

Generalize o prefixo público para &str

Casos e valores esperados

Execute com o Cargo local

O que você leva desta aula

Você transformou esta ideia em prática.