Pular para o conteúdo
Rust em Português

Lição 16 de 18 · 25 min

Módulos e crates

Organize o código em módulos e arquivos, controle o que é público com pub, importe com use e adicione bibliotecas da comunidade com cargo add.

Ao terminar, você vai saber:

  • Criar módulos com mod e controlar a visibilidade com pub
  • Encurtar caminhos com use
  • Separar um módulo em outro arquivo
  • Diferenciar crate binário de crate biblioteca
  • Adicionar uma dependência com cargo add e achar a documentação em docs.rs

Enquanto o programa tem 50 linhas, um arquivo só dá conta. Com 500, você começa a rolar a tela procurando funções. Com 5.000, vira bagunça. O Rust tem duas ferramentas para organizar isso:

  • Módulos dividem o código de um projeto em partes com nome.
  • Crates são os projetos em si: o seu e as bibliotecas que você usa de outras pessoas.

mod: criando um módulo

Um módulo é um bloco com nome. Tudo o que está dentro fica privado por padrão.

mod financeiro {
    pub fn aplicar_desconto(valor: f64, percentual: f64) -> f64 {
        valor * (1.0 - percentual / 100.0)
    }

    // Sem pub: só o próprio módulo enxerga
    fn arredondar(valor: f64) -> f64 {
        (valor * 100.0).round() / 100.0
    }

    pub fn preco_final(valor: f64) -> f64 {
        arredondar(aplicar_desconto(valor, 15.0))
    }
}

fn main() {
    let preco = financeiro::preco_final(59.90);
    println!("Com desconto: R$ {preco:.2}");
}

Para chamar algo de dentro de um módulo, use o caminho com ::, como em financeiro::preco_final. Você já fazia isso com String::from.

pub: o que fica visível

Tente chamar a função privada de fora:

mod financeiro {
    fn arredondar(valor: f64) -> f64 {
        (valor * 100.0).round() / 100.0
    }
}

fn main() {
    println!("{}", financeiro::arredondar(3.14159));
}
error[E0603]: function `arredondar` is private
  |     println!("{}", financeiro::arredondar(3.14159));
  |                                ^^^^^^^^^^ private function

Isso é bom. Você decide o que é a “vitrine” do módulo e o que é detalhe interno. Quem usa o módulo não depende dos detalhes, e você pode mudá-los à vontade.

Com structs, o pub vale campo por campo:

mod banco {
    pub struct Conta {
        pub titular: String,
        saldo: f64, // privado: só muda pelos métodos
    }

    impl Conta {
        pub fn new(titular: &str) -> Self {
            Self { titular: String::from(titular), saldo: 0.0 }
        }

        pub fn depositar(&mut self, valor: f64) {
            if valor > 0.0 {
                self.saldo += valor;
            }
        }

        pub fn saldo(&self) -> f64 {
            self.saldo
        }
    }
}

fn main() {
    let mut conta = banco::Conta::new("Lúcia");
    conta.depositar(300.0);
    // conta.saldo = 1_000_000.0; // não compila: campo privado
    println!("{}: R$ {:.2}", conta.titular, conta.saldo());
}

Ninguém de fora consegue colocar um saldo inventado. A única porta é o depositar, que confere o valor.

use: encurtando caminhos

Escrever banco::Conta toda hora cansa. O use traz o nome para perto:

mod loja {
    pub mod estoque {
        pub fn disponivel(produto: &str) -> bool {
            produto != "sonho"
        }
    }
}

use loja::estoque::disponivel;
use std::collections::HashMap;

fn main() {
    let mut pedidos = HashMap::new();
    pedidos.insert("pão de queijo", 2);

    println!("Pão de queijo? {}", disponivel("pão de queijo"));
    println!("Sonho? {}", disponivel("sonho"));
    println!("{:?}", pedidos);
}

Repare que módulos podem ficar dentro de módulos. E o use std::collections::HashMap que você usou na lição Coleções é exatamente isso: trazer um nome de dentro da biblioteca padrão.

Arquivos separados

O mais comum é cada módulo morar no seu arquivo. Em vez de escrever o conteúdo entre chaves, você escreve só mod financeiro; (com ponto e vírgula) e o Rust procura o arquivo src/financeiro.rs.

A estrutura fica assim:

meu_projeto/
├── Cargo.toml
└── src/
    ├── main.rs
    └── financeiro.rs

Conteúdo de src/financeiro.rs (sem mod financeiro { } em volta, o arquivo já é o módulo):

pub fn aplicar_desconto(valor: f64, percentual: f64) -> f64 {
    valor * (1.0 - percentual / 100.0)
}

pub fn parcelar(valor: f64, vezes: u32) -> f64 {
    valor / vezes as f64
}

Conteúdo de src/main.rs:

mod financeiro;

use financeiro::{aplicar_desconto, parcelar};

fn main() {
    let total = aplicar_desconto(1200.0, 10.0);
    println!("Total: R$ {total:.2}");
    println!("Em 10x: R$ {:.2}", parcelar(total, 10));
}

O mod financeiro; aparece uma vez, no main.rs. Os outros arquivos não precisam declarar nada. E o use com chaves traz vários nomes de uma vez.

Crate binário e crate biblioteca

Crate é a unidade que o compilador transforma em algo. Há dois tipos:

  • Binário: vira um programa executável. Tem uma fn main e começa em src/main.rs. É o que o cargo new cria por padrão.
  • Biblioteca: não tem main. Serve para ser usada por outros crates. Começa em src/lib.rs.
cargo new calculadora          # crate binário
cargo new --lib impostos       # crate biblioteca

Um mesmo projeto pode ter os dois: a lógica em src/lib.rs e um src/main.rs pequeno que usa essa lógica. Isso facilita os testes, como você vai ver na próxima lição.

Dependências: cargo add

O Cargo baixa bibliotecas da comunidade para você. Por exemplo, a biblioteca padrão não tem gerador de números aleatórios. Quem faz isso é o crate rand:

cargo add rand

O comando acrescenta uma linha no Cargo.toml, na seção [dependencies], com a versão mais recente. Na próxima vez que você rodar cargo build ou cargo run, o Cargo baixa e compila o crate.

Um sorteio de brindes na padaria:

fn main() {
    // Sorteia um número de 1 a 100, incluindo os dois
    let numero_da_sorte: u32 = rand::random_range(1..=100);
    println!("O número sorteado foi {numero_da_sorte}");
}

Não precisou de use: o caminho rand::random_range já diz de onde vem a função.

Este exemplo não roda sem o rand instalado. E atenção: bibliotecas mudam a forma de uso entre versões. Se o seu rand for diferente, os nomes das funções podem ser outros. Por isso o próximo ponto é tão importante.

crates.io e docs.rs

  • crates.io é onde ficam os crates públicos. Lá você pesquisa, vê quantos downloads cada um tem e quando foi atualizado.
  • docs.rs tem a documentação de todos os crates publicados, gerada automaticamente a partir do código. Em docs.rs/rand você vê exemplos e a lista de funções da versão que está usando.

Antes de escolher um crate, olhe: tem documentação? Foi atualizado recentemente? Muita gente usa? Para tarefas comuns, a comunidade costuma ter um favorito claro, como serde para converter dados, clap para argumentos de linha de comando e chrono para datas.

Resumo

  • mod cria um módulo; tudo dentro dele é privado até você marcar com pub.
  • Em structs, cada campo tem sua própria visibilidade.
  • use traz nomes para perto e evita caminhos longos.
  • mod financeiro; carrega o módulo do arquivo src/financeiro.rs.
  • Crate binário tem main.rs; crate biblioteca tem lib.rs.
  • cargo add nome acrescenta uma dependência; crates.io lista os crates e docs.rs guarda a documentação.

Desafio

Organize um conversor de temperatura em módulos: crie um módulo conversao com duas funções públicas, celsius_para_fahrenheit e fahrenheit_para_celsius, e uma função privada que arredonda para uma casa decimal. Na main, use use para chamar as duas funções sem o prefixo do módulo.

Ver uma resposta
mod conversao {
    fn arredondar(valor: f64) -> f64 {
        (valor * 10.0).round() / 10.0
    }

    pub fn celsius_para_fahrenheit(c: f64) -> f64 {
        arredondar(c * 9.0 / 5.0 + 32.0)
    }

    pub fn fahrenheit_para_celsius(f: f64) -> f64 {
        arredondar((f - 32.0) * 5.0 / 9.0)
    }
}

use conversao::{celsius_para_fahrenheit, fahrenheit_para_celsius};

fn main() {
    println!("Verão no Rio, 38 °C = {} °F", celsius_para_fahrenheit(38.0));
    println!("100 °F = {} °C", fahrenheit_para_celsius(100.0));
}
Salvo só neste navegador.