Pular para o conteúdo
Rust em Português

Lição 9 de 18 · 25 min

Referências e empréstimo

Empreste valores sem passar a posse: & e &mut, a regra de várias leituras ou uma escrita, referências penduradas e o borrow checker.

Ao terminar, você vai saber:

  • Criar referências com & para ler um valor sem tomar a posse
  • Usar &mut para alterar um valor emprestado
  • Explicar a regra de várias leituras ou uma escrita
  • Entender por que o compilador impede referências penduradas
  • Ler as mensagens do borrow checker sem medo

Na lição anterior, para uma função apenas olhar uma String, você tinha que passar a posse e depois pegar de volta. Funciona, mas é trabalhoso. A solução do Rust é a referência: um jeito de acessar um valor sem ser dono dele. Criar uma referência se chama borrowing (empréstimo).

A analogia é a de emprestar um livro para um amigo. Ele pode ler, mas o livro continua sendo seu. E quando ele terminar, devolve.

Emprestando com &

Para criar uma referência, coloque & antes do valor. Na função, o tipo do parâmetro também ganha o &:

fn main() {
    let lista = String::from("arroz, feijão, ovo");

    let tamanho = contar_letras(&lista); // empresta, não move
    println!("A lista \"{lista}\" tem {tamanho} caracteres.");
}

fn contar_letras(texto: &String) -> usize {
    texto.chars().count()
} // `texto` sai de escopo, mas como não é dono, nada é liberado

Repare: lista continua valendo depois da chamada. A função recebeu um &String, uma referência, e só leu o texto. Quando ela termina, a referência some, mas o valor continua com o dono original.

Uma dica que você vai usar bastante: quando a função só lê texto, prefira receber &str em vez de &String. Assim ela aceita tanto &String quanto um literal:

fn main() {
    let nome = String::from("Gustavo");

    saudar(&nome); // &String vira &str automaticamente
    saudar("Fernanda"); // literal já é &str
}

fn saudar(nome: &str) {
    println!("Fala, {nome}!");
}

Referência só lê

Uma referência comum (&) é imutável. Tente alterar o valor emprestado:

fn main() {
    let recado = String::from("Comprar pão");
    acrescentar(&recado);
}

fn acrescentar(texto: &String) {
    texto.push_str(" e leite");
}
error[E0596]: cannot borrow `*texto` as mutable, as it is behind a `&` reference
  |
6 |     texto.push_str(" e leite");
  |     ^^^^^ `texto` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
5 | fn acrescentar(texto: &mut String) {
  |                        +++

Seu amigo pegou o livro emprestado para ler, não para rabiscar.

Referência mutável: &mut

Se a função precisa alterar, use uma referência mutável, &mut. Três lugares precisam do mut: a variável, a criação da referência e o tipo do parâmetro.

fn main() {
    let mut recado = String::from("Comprar pão");

    acrescentar(&mut recado);
    println!("{recado}");
}

fn acrescentar(texto: &mut String) {
    texto.push_str(" e leite");
}

Saída:

Comprar pão e leite

Todo esse mut espalhado é de propósito: só de olhar a chamada acrescentar(&mut recado), você já sabe que recado pode mudar ali.

A regra de ouro: várias leituras OU uma escrita

Em qualquer momento, para um mesmo valor, você pode ter:

  • várias referências imutáveis (&), ou
  • uma única referência mutável (&mut).

Nunca as duas coisas ao mesmo tempo.

Pense num documento compartilhado. Várias pessoas podem ler ao mesmo tempo sem problema. Mas se alguém está editando, ninguém mais pode editar junto, e quem está lendo pode acabar vendo algo pela metade. O Rust proíbe essa bagunça antes de o programa rodar.

Várias leituras: tudo certo.

fn main() {
    let cidade = String::from("Florianópolis");

    let leitura1 = &cidade;
    let leitura2 = &cidade;
    println!("{leitura1} e {leitura2}");
}

Duas escritas ao mesmo tempo: proibido.

fn main() {
    let mut placar = String::from("0 x 0");

    let editor1 = &mut placar;
    let editor2 = &mut placar;

    editor1.push_str(" (1º tempo)");
    editor2.push_str(" (2º tempo)");
}
error[E0499]: cannot borrow `placar` as mutable more than once at a time
  |
4 |     let editor1 = &mut placar;
  |                   ----------- first mutable borrow occurs here
5 |     let editor2 = &mut placar;
  |                   ^^^^^^^^^^^ second mutable borrow occurs here
6 |
7 |     editor1.push_str(" (1º tempo)");
  |     ------- first borrow later used here

Leitura e escrita misturadas: também proibido.

fn main() {
    let mut nome = String::from("Ana");

    let leitura = &nome;
    nome.push_str(" Paula"); // tenta alterar enquanto alguém lê
    println!("{leitura}");
}
error[E0502]: cannot borrow `nome` as mutable because it is also borrowed as immutable
  |
4 |     let leitura = &nome;
  |                   ----- immutable borrow occurs here
5 |     nome.push_str(" Paula");
  |     ^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here
6 |     println!("{leitura}");
  |               --------- immutable borrow later used here

Por que isso importa? Ao crescer, a String pode mudar de lugar na heap. Se leitura ainda apontasse para o lugar antigo, estaria lendo memória que não vale mais.

O empréstimo acaba no último uso

Um detalhe que alivia muito: o empréstimo dura só até o último uso da referência, não até o fim das chaves. Este código compila:

fn main() {
    let mut nome = String::from("Ana");

    let leitura = &nome;
    println!("{leitura}"); // último uso de `leitura`

    nome.push_str(" Paula"); // agora pode alterar
    println!("{nome}");
}

A leitura terminou antes da escrita começar. Nada se sobrepõe, então está tudo certo.

Referência pendurada: o compilador não deixa

Uma referência pendurada (dangling reference) aponta para algo que já foi liberado. Em C, isso é um bug famoso e perigoso. No Rust, não compila:

fn criar_apelido() -> &String {
    let apelido = String::from("Tetê");
    &apelido
} // `apelido` é liberado aqui, e a referência apontaria para o nada

fn main() {
    let a = criar_apelido();
    println!("{a}");
}
error[E0106]: missing lifetime specifier
  |
1 | fn criar_apelido() -> &String {
  |                       ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value,
          but there is no value for it to be borrowed from
help: instead, you are more likely to want to return an owned value
  |
1 + fn criar_apelido() -> String {

A mensagem fala em lifetime (tempo de vida), que é por quanto tempo uma referência continua válida. A parte importante é a dica: a função devolve algo emprestado, mas não há de quem emprestar. É como devolver a chave de um apartamento que acabou de ser demolido.

O próprio compilador sugere a correção: devolver a String, passando a posse para quem chamou:

fn criar_apelido() -> String {
    String::from("Tetê")
}

fn main() {
    let a = criar_apelido();
    println!("{a}");
}

O borrow checker

Quem confere todas essas regras é o borrow checker (verificador de empréstimos), uma parte do compilador. Ele analisa o código e garante que:

  • toda referência aponta para um valor que ainda existe;
  • nunca há escrita junto com outra escrita ou leitura no mesmo valor.

No começo, ele parece um fiscal chato. Com o tempo, você percebe que ele está apontando bugs reais, do tipo que em outras linguagens só aparece em produção, numa sexta à noite. E as regras que ele aplica não custam nada em tempo de execução: tudo é conferido na compilação.

Quando ele reclamar, leia a mensagem com calma. Ela sempre mostra onde o empréstimo começou, onde houve o conflito e onde o empréstimo ainda é usado. Quase sempre a solução é reorganizar a ordem das linhas, encurtar o uso de uma referência ou, em último caso, usar clone.

Resumo

  • &valor empresta para leitura, sem passar a posse.
  • &mut valor empresta para escrita; a variável também precisa ser mut.
  • Para o mesmo valor: várias referências & ou uma única &mut, nunca as duas.
  • O empréstimo dura até o último uso da referência.
  • O compilador impede referências penduradas.
  • O borrow checker confere tudo isso na compilação, sem custo quando o programa roda.

Desafio

Escreva duas funções. A primeira, contar_vogais, recebe um &str e devolve quantas vogais (a, e, i, o, u, sem acento) ele tem. A segunda, gritar, recebe um &mut String e transforma o texto em maiúsculas com um ponto de exclamação no fim. No main, crie uma String, conte as vogais, depois chame gritar e imprima o resultado, mostrando que a variável original continua valendo.

Ver uma resposta
fn contar_vogais(texto: &str) -> usize {
    let mut total = 0;
    for letra in texto.chars() {
        if "aeiouAEIOU".contains(letra) {
            total += 1;
        }
    }
    total
}

fn gritar(texto: &mut String) {
    *texto = texto.to_uppercase();
    texto.push('!');
}

fn main() {
    let mut frase = String::from("bora estudar rust");

    let vogais = contar_vogais(&frase); // empréstimo para leitura
    println!("\"{frase}\" tem {vogais} vogais.");

    gritar(&mut frase); // empréstimo para escrita
    println!("{frase}");
}

O *texto = ... troca o valor inteiro para onde a referência aponta. O * significa “o valor lá do outro lado da referência”.

Salvo só neste navegador.