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 maine começa emsrc/main.rs. É o que ocargo newcria por padrão. - Biblioteca: não tem
main. Serve para ser usada por outros crates. Começa emsrc/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/randvocê 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
modcria um módulo; tudo dentro dele é privado até você marcar compub.- Em structs, cada campo tem sua própria visibilidade.
usetraz nomes para perto e evita caminhos longos.mod financeiro;carrega o módulo do arquivosrc/financeiro.rs.- Crate binário tem
main.rs; crate biblioteca temlib.rs. cargo add nomeacrescenta 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));
}