Lição 23: Inventário Estruturado (HashMap/HashSet)

1. Narrativa

O mecha Æther mantém um inventário preciso de recursos — munição, peças de reposição, suprimentos de emergência. Cada recurso tem um nome e uma quantidade. HashMap<K, V> mapeia cada item ao seu estoque, enquanto HashSet garante que módulos únicos nunca sejam duplicados no sistema.

2. Conceito

HashMap e HashSet são coleções baseadas em hash table — acesso O(1) na média:

• HashMap<K, V>: Mapeia chaves a valores — recurso → quantidade
• HashSet: Conjunto de valores únicos — sem duplicatas
• Entry API: .entry().and_modify().or_insert() — upsert eficiente
• Operações de conjunto: .intersection(), .union() — comparar conjuntos

3. Requisitos

• Criar e manipular HashMap para rastrear recursos por quantidade
• Usar .insert(), .remove(), .get(), .contains_key()
• Usar Entry API para reabastecimento inteligente
• Criar HashSet e usar operações de interseção e união

4. Design de Dados

graph LR
    A[HashMap String u32] --> B[insert: Munição → 50]
    B --> C[insert: Míssil → 12]
    C --> D[get: Munição → Some 50]
    C --> E[entry: Munição → and_modify +10]
    A --> F[HashSet String]
    F --> G[insert: Módulo A]
    F --> H[intersection: A ∩ B]

5. Diagrama de Fluxo

flowchart TD
    A[Início] --> B[Criar inventário vazio]
    B --> C[Registrar recursos]
    C --> D{Recurso existe?}
    D -->|Sim| E[Atualizar quantidade]
    D -->|Não| F[Inserir novo]
    E --> G[Consultar inventário]
    F --> G
    G --> H[Listar relatório]
    H --> I[Fim]

6. Funções

Função	Descrição
criar_inventario	Cria HashMap<String, u32> vazio
registrar_recurso	Adiciona ou sobrescreve recurso com .insert()
remover_recurso	Remove recurso e retorna quantidade
obter_quantidade	Consulta quantidade com .get()
tem_recurso	Verifica existência com .contains_key()
contar_tipos	Conta chaves distintas com .len()
reabastecer_recurso	Usa Entry API para incrementar ou inserir
listar_inventario	Formata relatório de todos os recursos
criar_conjunto_unico	Cria HashSet vazio
adicionar_item_unico	Adiciona item ao conjunto
tem_item_unico	Verifica pertencimento
remover_item_unico	Remove item do conjunto
itens_em_comum	Interseção entre dois conjuntos
unir_conjuntos	União de dois conjuntos

7. Exemplo

let mut inv: HashMap<String, u32> = HashMap::new();
inv.insert("Munição Plasma".to_string(), 50);
inv.insert("Míssil Guiado".to_string(), 12);
assert_eq!(inv.get("Munição Plasma"), Some(&50));
inv.entry("Munição Plasma".to_string()).and_modify(|v| *v += 10).or_insert(10);
assert_eq!(inv.get("Munição Plasma"), Some(&60));

8. Missão

1. Implementar criar_inventario retornando HashMap::new()
2. Implementar registrar_recurso usando .insert()
3. Implementar remover_recurso usando .remove()
4. Implementar obter_quantidade usando .get()
5. Implementar tem_recurso usando .contains_key()
6. Implementar contar_tipos usando .len()
7. Implementar reabastecer_recurso com Entry API (.entry().and_modify().or_insert())
8. Implementar listar_inventario iterando sobre o HashMap
9. Implementar funções de HashSet: criar, adicionar, verificar, remover
10. Implementar itens_em_comum com .intersection() e unir_conjuntos com .union()

9. Como Executar

cargo build
cargo test
cargo clippy -- -D warnings
cargo fmt --check

10. Dicas

• HashMap não preserva ordem de inserção — itere para listar
• .entry() é mais eficiente que get + insert separados
• HashSet usa .insert() como HashMap, mas sem valor associado
• .intersection() e .union() retornam iterators, use .collect() para materializar
• Avançado (Lição 26): funções como obter_quantidade, itens_em_comum e unir_conjuntos usam anotações de lifetime explícitas (<'a>) nas assinaturas. Você estudará lifetimes em detalhe na Lição 26 — por ora, entenda que 'a apenas amarra a referência retornada ao tempo de vida dos dados de entrada