A Linguagem de Programação Rust

por Steve Klabnik, Carol Nichols e Chris Krycho, com contribuições da Comunidade Rust

Esta versão do texto pressupõe que você está usando Rust 1.90.0 (lançado em 2025-09-18) ou posterior, com edition = "2024" no arquivo Cargo.toml de todos os projetos para configurá-los com as convenções idiomáticas da edição Rust 2024. Consulte a seção “Instalação” do Capítulo 1 para instruções de instalação ou atualização do Rust e veja o Apêndice E para informações sobre edições.

O formato HTML está disponível online em https://doc.rust-lang.org/stable/book/ e offline nas instalações do Rust feitas com rustup; execute rustup doc --book para abri-lo.

Também há várias [traduções] mantidas pela comunidade.

Este texto também está disponível em formato impresso e ebook pela No Starch Press.

🚨 Quer uma experiência de aprendizado mais interativa? Experimente outra versão do Rust Book, com: questionários, destaques, visualizações e mais: https://rust-book.cs.brown.edu

Prefácio

A linguagem de programação Rust percorreu um longo caminho em poucos anos: de sua criação e incubação por uma comunidade pequena e ainda nascente de entusiastas até se tornar uma das linguagens de programação mais admiradas e mais procuradas do mundo. Olhando em retrospecto, era inevitável que o poder e a promessa do Rust chamassem atenção e conquistassem espaço na programação de sistemas. O que não era inevitável era o crescimento global do interesse e da inovação que se espalhou pelas comunidades de código aberto e catalisou a adoção em larga escala em diversos setores.

Hoje, é fácil apontar os excelentes recursos que o Rust oferece para explicar essa explosão de interesse e adoção. Quem não quer segurança de memória, e alto desempenho, e um compilador amigável, e ótimas ferramentas, entre tantos outros benefícios? A linguagem Rust que você vê hoje combina anos de pesquisa em programação de sistemas com a sabedoria prática de uma comunidade vibrante e apaixonada. Essa linguagem foi projetada com propósito e lapidada com cuidado, oferecendo a desenvolvedoras e desenvolvedores uma ferramenta que facilita a escrita de código seguro, rápido e confiável.

Mas o que torna o Rust realmente especial é sua raiz em capacitar você, a pessoa usuária, a alcançar seus objetivos. Esta é uma linguagem que quer ver você ter sucesso, e esse princípio de capacitação percorre o núcleo da comunidade que constrói, mantém e promove a linguagem. Desde a edição anterior deste texto de referência, Rust se desenvolveu ainda mais e se tornou uma linguagem verdadeiramente global e confiável. O Projeto Rust agora conta com forte apoio da Rust Foundation, que também investe em iniciativas importantes para garantir que Rust permaneça seguro, estável e sustentável.

Esta edição de A Linguagem de Programação Rust é uma atualização abrangente, refletindo a evolução da linguagem ao longo dos anos e trazendo informações novas valiosas. Mas ela não é apenas um guia de sintaxe e bibliotecas: é um convite para participar de uma comunidade que valoriza qualidade, desempenho e design cuidadoso. Seja você uma pessoa desenvolvedora experiente querendo explorar Rust pela primeira vez, seja alguém já experiente em Rust buscando refinar suas habilidades, esta edição oferece algo para todo mundo.

A jornada do Rust tem sido feita de colaboração, aprendizado e iteração. O crescimento da linguagem e do seu ecossistema reflete diretamente a comunidade vibrante e diversa por trás dela. As contribuições de milhares de desenvolvedores, desde quem projeta o núcleo da linguagem até contribuidores eventuais, são o que fazem do Rust uma ferramenta tão singular e poderosa. Ao pegar este livro, você não está apenas aprendendo uma nova linguagem de programação: está se juntando a um movimento para tornar o software melhor, mais seguro e mais prazeroso de desenvolver.

Boas-vindas à comunidade Rust!

• Bec Rumbul, Diretora-Executiva da Rust Foundation

Introdução

Nota: Esta edição do livro é a mesma de The Rust Programming Language, disponível em formato impresso e ebook pela No Starch Press.

Boas-vindas a A Linguagem de Programação Rust, um livro introdutório sobre Rust. A linguagem de programação Rust ajuda você a escrever software mais rápido e mais confiável. Ergonomia de alto nível e controle de baixo nível costumam entrar em conflito no design de linguagens de programação; Rust desafia esse conflito. Ao equilibrar grande capacidade técnica com uma ótima experiência para desenvolvedores, Rust oferece a opção de controlar detalhes de baixo nível, como o uso de memória, sem toda a dificuldade tradicionalmente associada a esse tipo de controle.

Para quem Rust é indicado

Rust é ideal para muita gente por vários motivos. Vamos olhar para alguns dos grupos mais importantes.

Equipes de desenvolvimento

Rust tem se mostrado uma ferramenta produtiva para colaboração entre grandes equipes com níveis variados de conhecimento em programação de sistemas. Código de baixo nível é propenso a vários bugs sutis que, na maioria das outras linguagens, só podem ser detectados com testes extensivos e revisão de código cuidadosa feita por pessoas experientes. Em Rust, o compilador atua como uma espécie de guardião ao se recusar a compilar código com esses bugs difíceis de encontrar, inclusive bugs de concorrência. Trabalhando junto com o compilador, a equipe pode dedicar seu tempo à lógica do programa em vez de sair caçando bugs.

Rust também traz ferramentas modernas para desenvolvedores ao mundo da programação de sistemas:

• O Cargo, gerenciador de dependências e ferramenta de build incluídos, torna simples e consistente adicionar, compilar e gerenciar dependências em todo o ecossistema Rust.
• A ferramenta de formatação rustfmt garante um estilo de código consistente entre diferentes pessoas desenvolvedoras.
• O Rust Language Server viabiliza integração com ambientes de desenvolvimento integrados (IDEs), oferecendo autocompletar e mensagens de erro inline.

Ao usar essas e outras ferramentas do ecossistema Rust, pessoas desenvolvedoras podem ser produtivas mesmo escrevendo código em nível de sistema.

Estudantes

Rust também é para estudantes e para pessoas interessadas em aprender conceitos de sistemas. Usando Rust, muita gente aprendeu sobre tópicos como desenvolvimento de sistemas operacionais. A comunidade é bastante acolhedora e fica feliz em responder às dúvidas de estudantes. Por meio de esforços como este livro, as equipes do Rust querem tornar conceitos de sistemas mais acessíveis a mais pessoas, especialmente quem está começando a programar.

Empresas

Centenas de empresas, grandes e pequenas, usam Rust em produção para diversas tarefas, incluindo ferramentas de linha de comando, serviços web, tooling de DevOps, dispositivos embarcados, análise e transcodificação de áudio e vídeo, criptomoedas, bioinformática, motores de busca, aplicações de Internet das Coisas, aprendizado de máquina e até partes importantes do navegador Firefox.

Pessoas desenvolvedoras de código aberto

Rust é para quem quer construir a linguagem de programação Rust, sua comunidade, ferramentas para desenvolvedores e bibliotecas. Adoraríamos contar com a sua contribuição para a linguagem Rust.

Pessoas que valorizam velocidade e estabilidade

Rust é para quem deseja velocidade e estabilidade em uma linguagem. Por velocidade, queremos dizer tanto a rapidez com que o código Rust pode executar quanto a velocidade com que Rust permite escrever programas. As verificações do compilador Rust garantem estabilidade durante a adição de recursos e a refatoração. Isso contrasta com o código legado frágil em linguagens sem essas verificações, que desenvolvedores costumam ter receio de modificar. Ao buscar abstrações de custo zero, isto é, recursos de nível mais alto que compilam para código de baixo nível tão rápido quanto código escrito manualmente, Rust se esforça para fazer com que código seguro também seja código rápido.

A linguagem Rust espera dar suporte a muitos outros perfis de usuário também; os mencionados aqui são apenas alguns dos grupos mais importantes. No geral, a maior ambição do Rust é eliminar os trade-offs que programadores aceitaram por décadas, oferecendo segurança e produtividade, velocidade e ergonomia. Experimente Rust e veja se as escolhas da linguagem funcionam para você.

Para quem este livro é indicado

Este livro presume que você já escreveu código em outra linguagem de programação, mas não faz suposições sobre qual seja. Tentamos tornar o material amplamente acessível para pessoas com os mais diversos históricos de programação. Não gastamos muito tempo explicando o que é programação ou como pensar sobre ela. Se você é totalmente iniciante em programação, será melhor atendido por um livro que ofereça especificamente uma introdução à programação.

Como usar este livro

Em geral, este livro presume que você o está lendo em sequência, do começo ao fim. Capítulos posteriores se baseiam em conceitos apresentados antes, e os capítulos iniciais podem não se aprofundar em certos assuntos porque voltarão a eles em mais detalhes depois.

Você encontrará dois tipos de capítulos neste livro: capítulos conceituais e capítulos de projeto. Nos capítulos conceituais, você aprenderá sobre algum aspecto do Rust. Nos capítulos de projeto, construiremos pequenos programas juntos, aplicando o que você aprendeu até aquele ponto. Os Capítulos 2, 12 e 21 são capítulos de projeto; os demais são capítulos conceituais.

O Capítulo 1 explica como instalar Rust, como escrever um programa “Hello, world!” e como usar o Cargo, o gerenciador de pacotes e ferramenta de build do Rust. O Capítulo 2 é uma introdução prática à escrita de um programa em Rust, fazendo você construir um jogo de adivinhação. Ali, cobrimos conceitos em alto nível, e capítulos posteriores darão detalhes adicionais. Se você quer colocar a mão na massa logo de início, o Capítulo 2 é o lugar certo. Se você é um tipo de aprendiz especialmente meticuloso e prefere entender cada detalhe antes de avançar, talvez queira pular o Capítulo 2 e ir direto ao Capítulo 3, que cobre recursos do Rust parecidos com os de outras linguagens de programação; depois, você pode voltar ao Capítulo 2 quando quiser trabalhar em um projeto que aplique os detalhes aprendidos.

No Capítulo 4, você aprenderá sobre o sistema de ownership do Rust. O Capítulo 5 discute structs e métodos. O Capítulo 6 cobre enums, expressões match e as construções de fluxo de controle if let e let...else. Você usará structs e enums para criar tipos personalizados.

No Capítulo 7, você aprenderá sobre o sistema de módulos do Rust e sobre as regras de privacidade para organizar seu código e sua interface pública de programação de aplicações (API). O Capítulo 8 discute algumas estruturas de dados de coleção comuns fornecidas pela biblioteca padrão: vetores, strings e hash maps. O Capítulo 9 explora a filosofia e as técnicas de tratamento de erros em Rust.

O Capítulo 10 se aprofunda em genéricos, traits e lifetimes, que dão a você o poder de definir código aplicável a múltiplos tipos. O Capítulo 11 é inteiramente dedicado a testes, que, mesmo com as garantias de segurança do Rust, ainda são necessários para assegurar que a lógica do programa está correta. No Capítulo 12, construiremos nossa própria implementação de um subconjunto da funcionalidade do utilitário de linha de comando grep, que busca texto dentro de arquivos. Para isso, usaremos muitos dos conceitos discutidos nos capítulos anteriores.

O Capítulo 13 explora closures e iteradores, recursos do Rust vindos de linguagens de programação funcionais. No Capítulo 14, examinaremos o Cargo em mais profundidade e falaremos sobre boas práticas para compartilhar suas bibliotecas com outras pessoas. O Capítulo 15 discute smart pointers fornecidos pela biblioteca padrão e os traits que habilitam sua funcionalidade.

No Capítulo 16, veremos diferentes modelos de programação concorrente e falaremos sobre como Rust ajuda você a programar com múltiplas threads sem medo. No Capítulo 17, daremos continuidade a isso explorando a sintaxe async e await do Rust, junto com tasks, futures e streams, e o modelo de concorrência leve que eles possibilitam.

O Capítulo 18 observa como os idioms do Rust se comparam a princípios de programação orientada a objetos com os quais você talvez já esteja familiarizado. O Capítulo 19 é uma referência sobre padrões e pattern matching, formas poderosas de expressar ideias em programas Rust. O Capítulo 20 reúne uma variedade de tópicos avançados de interesse, incluindo Rust inseguro, macros e mais detalhes sobre lifetimes, traits, tipos, funções e closures.

No Capítulo 21, concluiremos um projeto no qual implementaremos um servidor web multithread de baixo nível!

Por fim, alguns apêndices contêm informações úteis sobre a linguagem em um formato mais voltado a referência. O Apêndice A cobre as palavras-chave do Rust, o Apêndice B cobre operadores e símbolos, o Apêndice C cobre traits deriváveis fornecidos pela biblioteca padrão, o Apêndice D cobre algumas ferramentas úteis de desenvolvimento, e o Apêndice E explica as edições do Rust. No Apêndice F, você encontra traduções do livro, e no Apêndice G veremos como o Rust é feito e o que é o Rust nightly.

Não existe jeito errado de ler este livro: se quiser pular adiante, vá em frente! Talvez você precise voltar a capítulos anteriores se encontrar alguma confusão. Mas faça o que funcionar melhor para você.

Uma parte importante do processo de aprender Rust é aprender a ler as mensagens de erro exibidas pelo compilador: elas vão guiar você até um código que funciona. Por isso, forneceremos muitos exemplos que não compilam, junto com a mensagem de erro que o compilador mostrará em cada situação. Saiba que, se você digitar e executar um exemplo aleatório, ele pode não compilar! Leia sempre o texto ao redor para ver se o exemplo que você está tentando executar foi pensado para gerar erro. O Ferris também ajudará a diferenciar código que não foi feito para funcionar:

Ferris	Significado
	Este código não compila!
	Este código entra em pânico!
	Este código não produz o comportamento desejado.

Na maioria das situações, vamos conduzir você até a versão correta de qualquer código que não compile.

Código-fonte

Os arquivos-fonte a partir dos quais este livro é gerado podem ser encontrados no GitHub.

Primeiros Passos

Vamos começar sua jornada com Rust! Há muito a aprender, mas toda jornada começa em algum lugar. Neste capítulo, vamos abordar:

• A instalação do Rust no Linux, no macOS e no Windows
• A escrita de um programa que imprime Hello, world!
• O uso do cargo, o gerenciador de pacotes e sistema de build do Rust

Instalação

Instalação

O primeiro passo é instalar o Rust. Vamos baixar o Rust por meio do rustup, uma ferramenta de linha de comando para gerenciar versões do Rust e ferramentas associadas. Você precisará de uma conexão com a internet para o download.

Nota: Se por algum motivo você preferir não usar rustup, consulte a página Other Rust Installation Methods para ver outras opções.

Os passos a seguir instalam a versão estável mais recente do compilador Rust. As garantias de estabilidade do Rust asseguram que todos os exemplos do livro que compilam continuarão compilando em versões mais novas do Rust. A saída pode variar um pouco entre versões, porque Rust frequentemente melhora mensagens de erro e avisos. Em outras palavras, qualquer versão estável mais nova que você instalar seguindo estes passos deve funcionar como esperado com o conteúdo deste livro.

Instalando o rustup no Linux ou no macOS

Se você estiver usando Linux ou macOS, abra um terminal e digite o seguinte comando:

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

O comando baixa um script e inicia a instalação da ferramenta rustup, que instala a versão estável mais recente do Rust. Você pode ser solicitado a informar sua senha. Se a instalação for bem-sucedida, a seguinte linha aparecerá:

Rust is installed now. Great!

Você também precisará de um linker, que é um programa que o Rust usa para juntar a saída compilada em um único arquivo. É provável que você já tenha um. Se receber erros de linker, deve instalar um compilador C, que normalmente já inclui um linker. Um compilador C também é útil porque alguns pacotes comuns do Rust dependem de código C e precisarão de um compilador desse tipo.

No macOS, você pode obter um compilador C executando:

$ xcode-select --install

Usuários de Linux normalmente devem instalar GCC ou Clang, de acordo com a documentação de sua distribuição. Por exemplo, se você usa Ubuntu, pode instalar o pacote build-essential.

Instalando o rustup no Windows

No Windows, acesse https://www.rust-lang.org/tools/install e siga as instruções de instalação do Rust. Em algum momento do processo, será solicitado que você instale o Visual Studio. Isso fornece um linker e as bibliotecas nativas necessárias para compilar programas. Se precisar de mais ajuda nessa etapa, veja https://rust-lang.github.io/rustup/installation/windows-msvc.html.

O restante deste livro usa comandos que funcionam tanto no cmd.exe quanto no PowerShell. Se houver diferenças específicas, explicaremos qual usar.

Solucionando problemas

Para verificar se o Rust foi instalado corretamente, abra um shell e execute a seguinte linha:

$ rustc --version

Você deverá ver o número da versão, o hash do commit e a data do commit da versão estável mais recente lançada, no seguinte formato:

rustc x.y.z (abcabcabc yyyy-mm-dd)

Se você vir essas informações, o Rust foi instalado com sucesso! Se não aparecerem, verifique se o Rust está na variável de sistema %PATH%, assim:

No CMD do Windows, use:

> echo %PATH%

No PowerShell, use:

> echo $env:Path

No Linux e no macOS, use:

$ echo $PATH

Se isso estiver correto e o Rust ainda assim não funcionar, há vários lugares em que você pode conseguir ajuda. Descubra como entrar em contato com outros rustaceanos (um apelido brincalhão que usamos para nós mesmos) na página da comunidade.

Atualizando e desinstalando

Depois que o Rust estiver instalado via rustup, atualizar para uma versão nova é simples. No shell, execute o seguinte script de atualização:

$ rustup update

Para desinstalar Rust e rustup, execute o seguinte script no shell:

$ rustup self uninstall

Lendo a documentação local

A instalação do Rust também inclui uma cópia local da documentação, para que você possa lê-la offline. Execute rustup doc para abrir essa documentação no seu navegador.

Sempre que um tipo ou função for fornecido pela biblioteca padrão e você não tiver certeza do que faz ou como usar, recorra à documentação da interface de programação de aplicações (API)!

Usando editores de texto e IDEs

Este livro não faz suposições sobre quais ferramentas você usa para escrever código Rust. Praticamente qualquer editor de texto dá conta do recado! Ainda assim, muitos editores de texto e ambientes de desenvolvimento integrados (IDEs) têm suporte embutido para Rust. Você sempre pode encontrar uma lista razoavelmente atualizada de vários editores e IDEs na página de ferramentas do site do Rust.

Trabalhando offline com este livro

Em vários exemplos, usaremos pacotes Rust além da biblioteca padrão. Para acompanhar esses exemplos, você precisará ter conexão com a internet ou já ter baixado essas dependências com antecedência. Para baixar as dependências antes, você pode executar os comandos a seguir. Mais tarde explicaremos em detalhes o que é cargo e o que cada um desses comandos faz.

$ cargo new get-dependencies
$ cd get-dependencies
$ cargo add rand@0.8.5 trpl@0.2.0

Isso fará cache dos downloads desses pacotes, então você não precisará baixá-los depois. Depois de executar esse comando, você não precisa manter a pasta get-dependencies. Se tiver executado esse comando, poderá usar a flag --offline com todos os comandos cargo no restante do livro para utilizar essas versões em cache em vez de tentar acessar a rede.

Olá, Mundo!

Olá, Mundo!

Agora que você instalou o Rust, chegou a hora de escrever seu primeiro programa em Rust. É tradicional, ao aprender uma nova linguagem, escrever um pequeno programa que imprima Hello, world! na tela, então faremos o mesmo aqui.

Nota: Este livro presume familiaridade básica com a linha de comando. Rust não faz exigências específicas sobre edição, tooling ou o local onde seu código vive, então, se você preferir usar uma IDE em vez da linha de comando, fique à vontade para usar a sua favorita. Muitas IDEs já têm algum grau de suporte a Rust; consulte a documentação da sua IDE para detalhes. A equipe do Rust tem investido bastante em viabilizar um ótimo suporte a IDEs por meio do rust-analyzer. Veja o Apêndice D para mais detalhes.

Configuração do diretório do projeto

Você começará criando um diretório para guardar seu código Rust. Para o Rust, não importa onde seu código fica, mas, para os exercícios e projetos deste livro, sugerimos criar um diretório projects dentro do seu diretório pessoal e manter todos os seus projetos lá.

Abra um terminal e digite os comandos a seguir para criar o diretório projects e, dentro dele, um diretório para o projeto “Hello, world!”.

No Linux, no macOS e no PowerShell do Windows, digite isto:

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

No CMD do Windows, digite isto:

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

Fundamentos de um programa Rust

Em seguida, crie um novo arquivo-fonte e chame-o de main.rs. Arquivos Rust sempre terminam com a extensão .rs. Se você estiver usando mais de uma palavra no nome do arquivo, a convenção é separá-las com underscore. Por exemplo, use hello_world.rs em vez de helloworld.rs.

Agora abra o arquivo main.rs que acabou de criar e digite o código da Listagem 1-1.

fn main() {
    println!("Hello, world!");
}

Salve o arquivo e volte para a janela do terminal no diretório ~/projects/hello_world. No Linux ou no macOS, digite os seguintes comandos para compilar e executar o arquivo:

$ rustc main.rs
$ ./main
Hello, world!

No Windows, use o comando .\main em vez de ./main:

> rustc main.rs
> .\main
Hello, world!

Independentemente do sistema operacional, a string Hello, world! deve ser impressa no terminal. Se isso não acontecer, volte à parte “Solucionando problemas” da seção de instalação para ver formas de conseguir ajuda.

Se Hello, world! apareceu, parabéns! Você escreveu oficialmente um programa em Rust. Isso faz de você um programador Rust: boas-vindas!

Anatomia de um programa Rust

Vamos revisar esse programa “Hello, world!” em detalhes. Aqui está a primeira peça do quebra-cabeça:

fn main() {

}

Essas linhas definem uma função chamada main. A função main é especial: ela é sempre o primeiro código executado em todo programa Rust executável. Aqui, a primeira linha declara uma função chamada main que não recebe parâmetros e não retorna nada. Se houvesse parâmetros, eles apareceriam dentro dos parênteses (()).

O corpo da função fica entre {}. Rust exige chaves ao redor do corpo de todas as funções. É considerado bom estilo colocar a chave de abertura na mesma linha da declaração da função, com um espaço entre elas.

Nota: Se você quiser manter um estilo padrão entre projetos Rust, pode usar uma ferramenta de formatação automática chamada rustfmt para formatar seu código de um jeito específico. Falaremos mais sobre rustfmt no Apêndice D. A equipe do Rust inclui essa ferramenta na distribuição padrão do Rust, assim como rustc, então ela provavelmente já está instalada no seu computador!

O corpo da função main contém o seguinte código:

#![allow(unused)]
fn main() {
println!("Hello, world!");
}

Essa linha faz todo o trabalho deste pequeno programa: ela imprime texto na tela. Há três detalhes importantes aqui.

Primeiro, println! chama uma macro do Rust. Se estivesse chamando uma função, seria escrito como println sem o !. Macros em Rust são uma forma de escrever código que gera código para estender a sintaxe da linguagem, e vamos discuti-las com mais detalhes no Capítulo 20. Por enquanto, basta saber que usar ! significa que você está chamando uma macro, não uma função comum, e que macros nem sempre seguem as mesmas regras das funções.

Segundo, você vê a string "Hello, world!". Passamos essa string como argumento para println!, e ela é impressa na tela.

Terceiro, terminamos a linha com ponto e vírgula (;), o que indica que essa expressão acabou e a próxima já pode começar. A maioria das linhas de código Rust termina com ponto e vírgula.

Compilação e execução

Você acabou de executar um programa recém-criado, então vamos examinar cada etapa do processo.

Antes de executar um programa Rust, você precisa compilá-lo usando o compilador Rust, digitando o comando rustc e passando o nome do arquivo-fonte, assim:

$ rustc main.rs

Se você tem experiência com C ou C++, perceberá que isso se parece com gcc ou clang. Após uma compilação bem-sucedida, Rust gera um executável binário.

No Linux, no macOS e no PowerShell do Windows, você pode ver o executável digitando o comando ls no shell:

$ ls
main  main.rs

No Linux e no macOS, você verá dois arquivos. No PowerShell do Windows, verá os mesmos três arquivos que veria usando o CMD. No CMD do Windows, você digitaria o seguinte:

> dir /B %= a opção /B diz para mostrar apenas os nomes dos arquivos =%
main.exe
main.pdb
main.rs

Isso mostra o arquivo-fonte com a extensão .rs, o arquivo executável (main.exe no Windows, mas main nas demais plataformas) e, no Windows, um arquivo com informações de depuração com a extensão .pdb. A partir daí, você executa o arquivo main ou main.exe, assim:

$ ./main # ou .\main no Windows

Se o seu main.rs é o programa “Hello, world!”, essa linha imprimirá Hello, world! no terminal.

Se você estiver mais acostumado a uma linguagem dinâmica, como Ruby, Python ou JavaScript, talvez não esteja acostumado a compilar e executar um programa como etapas separadas. Rust é uma linguagem compilada antecipadamente (ahead of time), o que significa que você pode compilar um programa e entregar o executável para outra pessoa, e ela poderá executá-lo mesmo sem ter Rust instalado. Se você entregar um arquivo .rb, .py ou .js, a pessoa precisará ter, respectivamente, uma implementação de Ruby, Python ou JavaScript instalada. Mas, nessas linguagens, normalmente basta um único comando para compilar e executar o programa. Tudo envolve trade-offs no design de linguagens.

Compilar apenas com rustc funciona bem para programas simples, mas, à medida que o projeto cresce, você vai querer gerenciar todas as opções e facilitar o compartilhamento do código. Em seguida, apresentaremos a ferramenta Cargo, que ajudará você a escrever programas Rust do mundo real.

Olá, Cargo!

Olá, Cargo!

Cargo é o sistema de build e gerenciador de pacotes do Rust. A maioria dos rustaceanos usa essa ferramenta para gerenciar seus projetos Rust, porque Cargo cuida de muitas tarefas para você, como compilar seu código, baixar as bibliotecas das quais ele depende e compilar essas bibliotecas. Chamamos as bibliotecas de que seu código precisa de dependências.

Os programas mais simples em Rust, como o que escrevemos até agora, não têm dependências. Se tivéssemos criado o projeto “Hello, world!” com o Cargo, ele usaria apenas a parte do Cargo responsável por compilar seu código. Conforme você escrever programas Rust mais complexos, adicionará dependências e, se iniciar o projeto com Cargo, isso será muito mais fácil.

Como a vasta maioria dos projetos Rust usa Cargo, o restante deste livro pressupõe que você também o está usando. Cargo vem instalado com Rust se você usou os instaladores oficiais discutidos na seção “Instalação”. Se instalou o Rust de outra forma, verifique se o Cargo está instalado digitando o seguinte no terminal:

$ cargo --version

Se você vir um número de versão, então está tudo certo! Se vir um erro, como command not found, consulte a documentação do seu método de instalação para descobrir como instalar Cargo separadamente.

Criando um projeto com Cargo

Vamos criar um novo projeto usando Cargo e observar como ele difere do nosso projeto original “Hello, world!”. Volte para o diretório projects ou para o local onde decidiu guardar seu código. Em qualquer sistema operacional, execute o seguinte:

$ cargo new hello_cargo
$ cd hello_cargo

O primeiro comando cria um novo diretório e projeto chamados hello_cargo. Demos ao projeto o nome hello_cargo, e o Cargo cria seus arquivos em um diretório com esse mesmo nome.

Entre no diretório hello_cargo e liste os arquivos. Você verá que o Cargo gerou dois arquivos e um diretório para nós: um arquivo Cargo.toml e um diretório src com um arquivo main.rs dentro dele.

Ele também inicializou um novo repositório Git junto com um arquivo .gitignore. Os arquivos do Git não serão gerados se você executar cargo new dentro de um repositório Git já existente; você pode mudar esse comportamento usando cargo new --vcs=git.

Nota: Git é um sistema de controle de versão bastante comum. Você pode mudar cargo new para usar outro sistema de controle de versão ou nenhum, usando a flag --vcs. Execute cargo new --help para ver as opções disponíveis.

Abra Cargo.toml no editor de texto de sua preferência. Ele deve se parecer com o código da Listagem 1-2.

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2024"

[dependencies]

Esse arquivo está no formato TOML (Tom’s Obvious, Minimal Language), que é o formato de configuração do Cargo.

A primeira linha, [package], é um cabeçalho de seção que indica que as declarações seguintes configuram um package. À medida que adicionarmos mais informações a esse arquivo, acrescentaremos outras seções.

As três linhas seguintes definem as informações de configuração de que o Cargo precisa para compilar seu programa: o nome, a versão e a edição do Rust a ser usada. Falaremos sobre a chave edition no Apêndice E.

A última linha, [dependencies], marca o começo de uma seção na qual você listará as dependências do projeto. Em Rust, pacotes de código são chamados de crates. Não precisaremos de outros crates para este projeto, mas precisaremos no primeiro projeto do Capítulo 2, então usaremos essa seção naquela ocasião.

Agora abra src/main.rs e dê uma olhada:

Nome do arquivo: src/main.rs

fn main() {
    println!("Hello, world!");
}

O Cargo gerou para você um programa “Hello, world!”, exatamente como o que escrevemos na Listagem 1-1! Até aqui, as diferenças entre o nosso projeto e o projeto gerado pelo Cargo são que o Cargo colocou o código dentro do diretório src e criou um arquivo de configuração Cargo.toml no diretório superior.

O Cargo espera que seus arquivos-fonte fiquem dentro do diretório src. O diretório de topo do projeto deve conter apenas arquivos README, informações de licença, arquivos de configuração e qualquer outra coisa que não esteja diretamente relacionada ao código. Usar Cargo ajuda a organizar seus projetos. Há um lugar para cada coisa, e cada coisa fica em seu lugar.

Se você iniciou um projeto sem usar Cargo, como fizemos com o projeto “Hello, world!”, pode convertê-lo para um projeto que use Cargo. Mova o código do projeto para o diretório src e crie um arquivo Cargo.toml adequado. Uma forma simples de obter esse arquivo Cargo.toml é executar cargo init, que o criará automaticamente para você.

Compilando e executando um projeto Cargo

Agora vamos ver o que muda quando compilamos e executamos o programa “Hello, world!” com Cargo! No diretório hello_cargo, compile o projeto digitando:

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

Esse comando cria um executável em target/debug/hello_cargo ou target\debug\hello_cargo.exe no Windows, em vez de gerá-lo no diretório atual. Como o build padrão é de depuração, o Cargo coloca o binário em um diretório chamado debug. Você pode executar o executável com este comando:

$ ./target/debug/hello_cargo # ou .\target\debug\hello_cargo.exe no Windows
Hello, world!

Se tudo correr bem, Hello, world! deve ser impresso no terminal. Executar cargo build pela primeira vez também faz o Cargo criar um novo arquivo no nível superior do projeto: Cargo.lock. Esse arquivo mantém registro das versões exatas das dependências do projeto. Como este projeto não tem dependências, o arquivo é bem enxuto. Você nunca precisará alterá-lo manualmente; o Cargo gerencia seu conteúdo para você.

Acabamos de compilar um projeto com cargo build e executá-lo com ./target/debug/hello_cargo, mas também podemos usar cargo run para compilar o código e depois executar o binário resultante em um único comando:

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

Usar cargo run é mais conveniente do que lembrar de executar cargo build e depois usar o caminho completo até o binário, então a maioria dos desenvolvedores prefere cargo run.

Observe que, desta vez, não vimos a saída indicando que o Cargo estava compilando hello_cargo. O Cargo percebeu que os arquivos não haviam mudado, então ele não recompilou nada; apenas executou o binário. Se você tivesse modificado o código-fonte, o Cargo recompilaria o projeto antes de executá-lo, e você veria esta saída:

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

O Cargo também oferece um comando chamado cargo check. Esse comando verifica rapidamente se seu código compila, mas não produz um executável:

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

Por que você não iria querer um executável? Muitas vezes, cargo check é bem mais rápido do que cargo build, porque pula a etapa de gerar o executável. Se você estiver checando seu trabalho continuamente enquanto escreve código, usar cargo check acelera o processo de descobrir se o projeto ainda está compilando! Por isso, muitos rustaceanos executam cargo check periodicamente enquanto escrevem seus programas, para garantir que tudo continua compilando. Depois, quando estão prontos para usar o executável, executam cargo build.

Vamos recapitular o que aprendemos até aqui sobre Cargo:

• Podemos criar um projeto usando cargo new.
• Podemos compilar um projeto usando cargo build.
• Podemos compilar e executar um projeto em uma única etapa usando cargo run.
• Podemos verificar se há erros em um projeto sem produzir um binário usando cargo check.
• Em vez de salvar o resultado do build no mesmo diretório do código, o Cargo o armazena no diretório target/debug.

Uma vantagem adicional do Cargo é que os comandos são os mesmos independentemente do sistema operacional em que você está trabalhando. Por isso, a partir deste ponto, deixaremos de fornecer instruções separadas para Linux e macOS versus Windows.

Compilando para release

Quando o projeto finalmente estiver pronto para release, você pode usar cargo build --release para compilá-lo com otimizações. Esse comando criará um executável em target/release em vez de target/debug. As otimizações fazem o código Rust rodar mais rápido, mas ativá-las aumenta o tempo de compilação. Por isso há dois perfis diferentes: um para desenvolvimento, quando você quer recompilar rapidamente e com frequência, e outro para gerar o programa final que será entregue ao usuário, que não será recompilado repetidamente e deverá executar o mais rápido possível. Se você estiver medindo o tempo de execução do seu código, lembre-se de rodar cargo build --release e fazer o benchmark com o executável em target/release.

Aproveitando as convenções do Cargo

Em projetos simples, o Cargo não oferece muito mais valor do que usar rustc diretamente, mas ele mostra seu valor à medida que os programas ficam mais complexos. Quando um programa cresce para múltiplos arquivos ou passa a precisar de dependências, é muito mais fácil deixar o Cargo coordenar o build.

Mesmo sendo simples, o projeto hello_cargo já usa grande parte do ferramental real que você vai utilizar no restante da sua carreira com Rust. Na prática, para trabalhar em qualquer projeto existente, você pode usar os comandos a seguir para baixar o código com Git, entrar no diretório do projeto e compilar:

$ git clone example.org/someproject
$ cd someproject
$ cargo build

Para mais informações sobre Cargo, consulte sua documentação.

Resumo

Você já começou muito bem sua jornada com Rust! Neste capítulo, você aprendeu a:

• Instalar a versão estável mais recente do Rust usando rustup.
• Atualizar para uma versão mais nova do Rust.
• Abrir a documentação instalada localmente.
• Escrever e executar um programa “Hello, world!” usando rustc diretamente.
• Criar e executar um novo projeto usando as convenções do Cargo.

Este é um ótimo momento para construir um programa mais substancial e se acostumar a ler e escrever código Rust. Então, no Capítulo 2, construiremos um programa de jogo de adivinhação. Se preferir começar entendendo como conceitos comuns de programação funcionam em Rust, veja o Capítulo 3 e depois volte ao Capítulo 2.

Programando um Jogo de Adivinhação

Vamos entrar no Rust trabalhando juntos em um projeto prático! Este capítulo apresenta alguns conceitos comuns da linguagem ao mostrar como usá-los em um programa real. Você aprenderá sobre let, match, métodos, funções associadas, crates externos e muito mais. Nos capítulos seguintes, exploraremos essas ideias em mais detalhes. Aqui, o objetivo é praticar os fundamentos.

Implementaremos um problema clássico para iniciantes: um jogo de adivinhação. O funcionamento é simples: o programa gera um número inteiro aleatório entre 1 e 100 e pede que a pessoa jogadora digite um palpite. Depois que o palpite é informado, o programa diz se ele é baixo demais ou alto demais. Se o palpite estiver correto, o jogo imprime uma mensagem de parabéns e encerra.

Configurando um Novo Projeto

Para configurar um novo projeto, vá até o diretório projects que você criou no Capítulo 1 e crie um novo projeto com o Cargo:

$ cargo new guessing_game
$ cd guessing_game

O primeiro comando, cargo new, recebe o nome do projeto (guessing_game) como primeiro argumento. O segundo comando entra no diretório do projeto recém-criado.

Veja o arquivo Cargo.toml gerado:

Nome do arquivo: Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2024"

[dependencies]

Como você viu no Capítulo 1, cargo new gera para você um programa “Hello, world!”. Veja o arquivo src/main.rs:

Nome do arquivo: src/main.rs

fn main() {
    println!("Hello, world!");
}

Agora vamos compilar esse programa “Hello, world!” e executá-lo em uma única etapa usando o comando cargo run:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/guessing_game`
Hello, world!

O comando run é útil quando você precisa iterar rapidamente em um projeto, como faremos neste jogo, testando cada alteração antes de seguir adiante.

Abra novamente o arquivo src/main.rs. Você escreverá todo o código neste arquivo.

Processando um Palpite

A primeira parte do programa do jogo de adivinhação vai pedir uma entrada ao usuário, processá-la e verificar se ela está no formato esperado. Para começar, vamos permitir que a pessoa jogadora digite um palpite. Insira o código da Listagem 2-1 em src/main.rs.

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Esse código contém muita coisa, então vamos analisá-lo linha por linha. Para receber a entrada do usuário e depois imprimir o resultado, precisamos trazer para o escopo a biblioteca de entrada e saída io. A biblioteca io faz parte da biblioteca padrão, conhecida como std:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Por padrão, Rust traz para o escopo de todo programa um conjunto de itens definidos na biblioteca padrão. Esse conjunto é chamado de prelude, e você pode ver tudo o que ele inclui na documentação da biblioteca padrão.

Se um tipo que você quer usar não estiver no prelude, será necessário trazê-lo explicitamente para o escopo com uma instrução use. A biblioteca std::io fornece vários recursos úteis, incluindo a capacidade de ler entrada do usuário.

Como você viu no Capítulo 1, a função main é o ponto de entrada no programa:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

A sintaxe fn declara uma nova função; os parênteses () indicam que não há parâmetros; e a chave { inicia o corpo da função.

Como você também aprendeu no Capítulo 1, println! é uma macro que imprime uma string na tela:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Esse código imprime uma mensagem informando sobre o jogo e pedindo a entrada do usuário.

Armazenando Valores com Variáveis

A seguir, criaremos uma variável para armazenar a entrada do usuário, assim:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Agora o programa começa a ficar interessante! Há bastante coisa acontecendo nessa linha curta. Usamos a instrução let para criar a variável. Aqui vai outro exemplo:

let apples = 5;

Esta linha cria uma nova variável chamada apples e a vincula ao valor 5. Em Rust, variáveis são imutáveis por padrão; isto é, depois que damos um valor a uma variável, esse valor não muda. Discutiremos esse conceito em detalhes na seção “Variáveis e Mutabilidade” do Capítulo 3. Para tornar uma variável mutável, adicionamos mut antes do nome da variável:

let apples = 5; // immutable
let mut bananas = 5; // mutable

Nota: a sintaxe // inicia um comentário que vai até o fim da linha. Rust ignora tudo o que estiver em comentários. Falaremos mais sobre comentários no Capítulo 3.

Voltando ao programa do jogo de adivinhação, agora você sabe que let mut guess vai introduzir uma variável mutável chamada guess. O sinal de igual (=) diz ao Rust que queremos associar algo à variável naquele momento. À direita do sinal de igual está o valor ao qual guess será associado, que é o resultado da chamada String::new, uma função que retorna uma nova instância de String. String é um tipo de string fornecido pela biblioteca padrão; trata-se de um pedaço de texto codificado em UTF-8 que pode crescer.

A sintaxe :: em String::new indica que new é uma função associada ao tipo String. Uma função associada é uma função implementada em um tipo, neste caso String. A função new cria uma string nova e vazia. Você verá uma função new em vários tipos porque esse é um nome comum para uma função que cria algum valor novo.

Portanto, a linha let mut guess = String::new(); cria uma variável mutável que está associada, naquele momento, a uma instância nova e vazia de String.

Recebendo entrada do usuário

Lembre-se de que incluímos a funcionalidade de entrada e saída da biblioteca padrão com use std::io; na primeira linha do programa. Agora vamos chamar a função stdin do módulo io, que nos permitirá lidar com a entrada do usuário:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Se não tivéssemos importado o módulo io com use std::io; no início do programa, ainda poderíamos usar a função escrevendo a chamada como std::io::stdin. A função stdin retorna uma instância de std::io::Stdin, um tipo que representa um manipulador para a entrada padrão do seu terminal.

Em seguida, a linha .read_line(&mut guess) chama o método read_line nesse manipulador de entrada padrão para obter a entrada do usuário. Também passamos &mut guess como argumento para read_line, indicando em qual string a entrada deverá ser armazenada. O comportamento de read_line é pegar tudo o que o usuário digita na entrada padrão e anexar esse conteúdo à string passada como argumento, sem sobrescrever o que ela já contém. Por isso, o argumento precisa ser mutável: o método vai alterar o conteúdo da string.

O & indica que esse argumento é uma referência, o que dá a você uma forma de permitir que várias partes do código acessem um mesmo dado sem precisar copiá-lo na memória muitas vezes. Referências são um recurso complexo, e uma das grandes vantagens do Rust é que ele torna o uso delas seguro e prático. Você não precisa entender todos esses detalhes agora para terminar este programa. Por enquanto, basta saber que, assim como variáveis, referências são imutáveis por padrão. Por isso, você precisa escrever &mut guess em vez de &guess para torná-la mutável. O Capítulo 4 explicará referências com mais detalhes.

Lidando com falhas potenciais com Result

Ainda estamos trabalhando nessa linha de código. Agora estamos discutindo uma terceira linha de texto, mas observe que ela ainda faz parte de uma única linha lógica de código. A próxima parte é este método:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Poderíamos ter escrito este código como:

io::stdin().read_line(&mut guess).expect("Failed to read line");

No entanto, uma linha longa é difícil de ler, por isso é melhor dividi-la. Muitas vezes, vale a pena introduzir uma quebra de linha e outros espaços em branco para separar linhas longas quando você chama um método com a sintaxe .method_name(). Agora vamos discutir o que essa linha faz.

Como mencionamos antes, read_line coloca tudo o que a pessoa usuária digita na string que passamos a ele, mas também retorna um valor Result. Result é uma enumeração, geralmente chamada de enum, que é um tipo que pode estar em um dentre vários estados possíveis. Chamamos cada estado possível de variante.

Capítulo 6 abordará enums em mais detalhes. O propósito de tipos Result é codificar informações sobre tratamento de erros.

As variantes de Result são Ok e Err. A variante Ok indica que a operação foi bem-sucedida e contém o valor gerado com sucesso. A variante Err significa que a operação falhou e contém informações sobre como ou por que ela falhou.

Valores do tipo Result, como valores de qualquer outro tipo, têm métodos definidos neles. Uma instância de Result tem um método expect que você pode chamar. Se essa instância de Result for um valor Err, expect fará o programa encerrar e exibirá a mensagem que você passou como argumento para expect. Se o método read_line retornar um Err, isso provavelmente será resultado de um erro vindo do sistema operacional subjacente. Se essa instância de Result for um valor Ok, expect pegará o valor que Ok está contendo e o retornará para você usar. Nesse caso, esse valor é o número de bytes da entrada da pessoa usuária.

Se você não chamar expect, o programa será compilado, mas você receberá um aviso:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `Result` that must be used
  --> src/main.rs:10:5
   |
10 |     io::stdin().read_line(&mut guess);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
   |
10 |     let _ = io::stdin().read_line(&mut guess);
   |     +++++++

warning: `guessing_game` (bin "guessing_game") generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.59s

Rust avisa que você não usou o valor Result retornado de read_line, indicando que o programa não tratou um possível erro.

A forma correta de suprimir o aviso é escrever código de tratamento de erros, mas, no nosso caso, queremos apenas encerrar o programa quando ocorrer um problema, então podemos usar expect. Você aprenderá como se recuperar de erros no Capítulo 9.

Imprimindo valores com placeholders de println!

Além da chave de fechamento, há apenas mais uma linha para discutir no código até aqui:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Essa linha imprime a string que agora contém a entrada da pessoa usuária. O conjunto {} de chaves funciona como um placeholder: pense em {} como pequenas garras de caranguejo segurando um valor no lugar. Ao imprimir o valor de uma variável, o nome da variável pode ir entre as chaves. Ao imprimir o resultado da avaliação de uma expressão, coloque chaves vazias na string de formatação e, em seguida, acrescente à string de formatação uma lista de expressões separadas por vírgula, a serem impressas em cada placeholder vazio, na mesma ordem. Imprimir uma variável e o resultado de uma expressão em uma única chamada a println! ficaria assim:

#![allow(unused)]
fn main() {
let x = 5;
let y = 10;

println!("x = {x} and y + 2 = {}", y + 2);
}

Esse código imprimiria x = 5 and y + 2 = 12.

Testando a primeira parte

Vamos testar a primeira parte do jogo de adivinhação. Execute-o usando cargo run:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.44s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6

Neste ponto, a primeira parte do jogo está concluída: estamos recebendo entrada do teclado e depois imprimindo essa entrada.

Gerando um número secreto

A seguir, precisamos gerar um número secreto que a pessoa usuária tentará adivinhar. O número secreto deve ser diferente a cada vez para que o jogo seja divertido de jogar mais de uma vez. Vamos usar um número aleatório entre 1 e 100 para que o jogo não fique muito difícil. Rust ainda não inclui funcionalidade de números aleatórios em sua biblioteca padrão. No entanto, a equipe do Rust fornece uma crate chamada rand com essa funcionalidade.

Aumentando a funcionalidade com uma crate

Lembre-se de que uma crate é uma coleção de arquivos de código-fonte Rust. O projeto que estamos construindo é uma crate binária, isto é, um executável. A crate rand é uma crate de biblioteca, que contém código destinado a ser usado em outros programas e não pode ser executado sozinha.

A forma como o Cargo coordena crates externas é onde ele realmente brilha. Antes de escrevermos código que use rand, precisamos modificar o arquivo Cargo.toml para incluir a crate rand como dependência. Abra esse arquivo agora e adicione a linha a seguir no final, abaixo do cabeçalho da seção [dependencies] que o Cargo criou para você. Certifique-se de especificar rand exatamente como está aqui, com esse número de versão, ou os exemplos de código deste tutorial podem não funcionar:

Nome do arquivo: Cargo.toml

[dependencies]
rand = "0.8.5"

No arquivo Cargo.toml, tudo o que vem depois de um cabeçalho faz parte daquela seção, até que outra seção comece. Em [dependencies], você informa ao Cargo de quais crates externas o projeto depende e de quais versões dessas crates você precisa. Neste caso, especificamos a crate rand com o especificador de versão semântica 0.8.5. O Cargo entende Versionamento Semântico, às vezes chamado de SemVer, que é um padrão para escrever números de versão. O especificador 0.8.5 é, na verdade, uma abreviação de ^0.8.5, o que significa qualquer versão que seja pelo menos 0.8.5, mas abaixo de 0.9.0.

O Cargo considera que essas versões têm APIs públicas compatíveis com a versão 0.8.5, e essa especificação garante que você obterá a versão de patch mais recente que ainda compilará com o código deste capítulo. Não há garantia de que qualquer versão 0.9.0 ou superior tenha a mesma API usada nos exemplos a seguir.

Agora, sem alterar nenhum código, vamos compilar o projeto, como mostra a Listagem 2-2.

$ cargo build
  Updating crates.io index
   Locking 15 packages to latest Rust 1.85.0 compatible versions
    Adding rand v0.8.5 (available: v0.9.0)
 Compiling proc-macro2 v1.0.93
 Compiling unicode-ident v1.0.17
 Compiling libc v0.2.170
 Compiling cfg-if v1.0.0
 Compiling byteorder v1.5.0
 Compiling getrandom v0.2.15
 Compiling rand_core v0.6.4
 Compiling quote v1.0.38
 Compiling syn v2.0.98
 Compiling zerocopy-derive v0.7.35
 Compiling zerocopy v0.7.35
 Compiling ppv-lite86 v0.2.20
 Compiling rand_chacha v0.3.1
 Compiling rand v0.8.5
 Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
  Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.48s

Você pode ver números de versão diferentes, embora todos sejam compatíveis com o código graças ao SemVer, e linhas diferentes, dependendo do sistema operacional. As linhas também podem aparecer em outra ordem.

Quando incluímos uma dependência externa, o Cargo busca no registry as versões mais recentes de tudo de que a dependência precisa. O registry é uma cópia dos dados de Crates.io. O Crates.io é onde as pessoas do ecossistema Rust publicam seus projetos Rust de código aberto para que outras pessoas possam usá-los.

Depois de atualizar o registry, o Cargo verifica a seção [dependencies] e baixa todas as crates listadas que ainda não foram baixadas. Nesse caso, embora tenhamos listado apenas rand como dependência, o Cargo também obteve outras crates das quais rand depende para funcionar. Depois de baixar as crates, Rust as compila e, em seguida, compila o projeto com as dependências disponíveis.

Se você executar cargo build imediatamente de novo, sem fazer nenhuma alteração, não verá nenhuma saída além da linha Finished. O Cargo sabe que já baixou e compilou as dependências e que você não mudou nada nelas no arquivo Cargo.toml. Ele também sabe que você não mudou nada no seu código, então não o recompila. Sem nada a fazer, ele simplesmente encerra.

Se você abrir o arquivo src/main.rs, fizer uma alteração trivial, salvá-lo e compilar novamente, verá apenas duas linhas de saída:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s

Essas linhas mostram que o Cargo atualiza apenas o build com a pequena mudança feita no arquivo src/main.rs. Como as dependências não mudaram, o Cargo sabe que pode reutilizar o que já foi baixado e compilado para elas.

Garantindo builds reproduzíveis

O Cargo tem um mecanismo que garante que você possa recriar o mesmo artefato toda vez que você ou qualquer outra pessoa compilar o código: ele usará apenas as versões das dependências que você especificou até que você diga o contrário. Por exemplo, imagine que, na próxima semana, a versão 0.8.6 da crate rand seja lançada, contendo uma correção de bug importante, mas também uma regressão que quebrará seu código. Para lidar com isso, Rust cria o arquivo Cargo.lock na primeira vez que você executa cargo build, então agora temos esse arquivo no diretório guessing_game.

Quando você compila um projeto pela primeira vez, o Cargo descobre todas as versões das dependências que atendem aos critérios e depois as grava no arquivo Cargo.lock. Quando você compilar o projeto no futuro, o Cargo verá que o arquivo Cargo.lock existe e usará as versões especificadas ali, em vez de repetir todo o trabalho de descobrir as versões novamente. Isso permite que você tenha um build reproduzível automaticamente. Em outras palavras, o seu projeto permanecerá na versão 0.8.5 até que você atualize explicitamente, graças ao arquivo Cargo.lock. Como esse arquivo é importante para builds reproduzíveis, muitas vezes ele é versionado junto com o restante do código no projeto.

Atualizando uma crate para obter uma nova versão

Quando você quiser atualizar uma crate, o Cargo fornece o comando update, que ignorará o arquivo Cargo.lock e descobrirá todas as versões mais recentes que atendem às especificações do seu Cargo.toml. O Cargo então escreverá essas versões no arquivo Cargo.lock. Fora isso, por padrão, o Cargo procurará apenas versões maiores que 0.8.5 e menores que 0.9.0. Se a crate rand tivesse lançado as duas novas versões 0.8.6 e 0.999.0, você veria o seguinte ao executar cargo update:

Há muito mais a dizer sobre Cargo e seu ecossistema, que discutiremos no Capítulo 14, mas, por enquanto, isso é tudo o que você precisa saber. O Cargo facilita muito a reutilização de bibliotecas, então os rustaceanos conseguem escrever projetos menores, montados a partir de vários pacotes.

Gerando um número aleatório

Vamos começar a usar rand para gerar um número a ser adivinhado. O próximo passo é atualizar src/main.rs, como mostra a Listagem 2-3.

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Primeiro, adicionamos a linha use rand::Rng;. A trait Rng define métodos que geradores de números aleatórios implementam, e essa trait precisa estar em escopo para que possamos usar esses métodos. O Capítulo 10 abordará traits em detalhes.

A seguir, estamos adicionando duas linhas no meio. Na primeira, chamamos a função rand::thread_rng, que nos fornece o gerador de números aleatórios específico que vamos usar: um que é local à thread de execução atual e é inicializado pelo sistema operacional. Depois, chamamos o método gen_range nesse gerador de números aleatórios. Esse método é definido pela trait Rng que trouxemos para o escopo com a instrução use rand::Rng;. O método gen_range recebe uma expressão de intervalo como argumento e gera um número aleatório dentro desse intervalo. O tipo de expressão de intervalo que estamos usando aqui tem a forma start..=end e inclui os limites inferior e superior; por isso, precisamos especificar 1..=100 para pedir um número entre 1 e 100.

Nota: você não vai simplesmente saber quais traits usar e quais métodos e funções chamar de uma crate, então cada crate tem documentação com instruções sobre como usá-la. Outro recurso interessante do Cargo é que executar o comando cargo doc --open compila localmente a documentação fornecida por todas as suas dependências e a abre no navegador. Se você tiver interesse em outras funcionalidades da crate rand, por exemplo, execute cargo doc --open e clique em rand na barra lateral à esquerda.

A segunda nova linha imprime o número secreto. Isso é útil enquanto estamos desenvolvendo o programa para podermos testá-lo, mas vamos removê-la da versão final. Não existe muita graça em um jogo que imprime a resposta assim que começa!

Tente executar o programa algumas vezes:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5

Você deve obter números aleatórios diferentes, e todos eles devem estar entre 1 e 100. Ótimo trabalho!

Comparando o Palpite com o Número Secreto

Agora que temos a entrada da pessoa usuária e um número aleatório, podemos compará-los. Esse passo é mostrado na Listagem 2-4. Observe que esse código ainda não compilará, como explicaremos.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    // --snip--
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Primeiro, adicionamos outra instrução use, trazendo para o escopo um tipo da biblioteca padrão chamado std::cmp::Ordering. O tipo Ordering é outro enum e tem as variantes Less, Greater e Equal. Esses são os três resultados possíveis ao comparar dois valores.

Em seguida, adicionamos cinco novas linhas na parte inferior que usam o tipo Ordering. O método cmp compara dois valores e pode ser chamado em qualquer coisa que possa ser comparada. Ele recebe uma referência ao que você quer comparar com o valor atual; aqui, ele está comparando guess com secret_number. Depois, retorna uma variante do enum Ordering que trouxemos para o escopo com a instrução use. Usamos uma expressão match para decidir o que fazer a seguir com base em qual variante de Ordering foi retornada pela chamada a cmp com os valores em guess e secret_number.

Uma expressão match é composta por braços. Um braço consiste em um padrão a ser comparado e no código que deve ser executado se o valor dado a match se encaixar no padrão daquele braço. Rust pega o valor fornecido a match e verifica, em sequência, o padrão de cada braço. Padrões e a construção match são recursos poderosos do Rust: eles permitem expressar uma grande variedade de situações que seu código pode encontrar e garantem que você trate todas elas. Esses recursos serão abordados em detalhes no Capítulo 6 e no Capítulo 19, respectivamente.

Vamos percorrer um exemplo com a expressão match que usamos aqui. Digamos que a pessoa usuária tenha chutado 50 e que o número secreto gerado aleatoriamente desta vez seja 38.

Quando o código compara 50 com 38, o método cmp retorna Ordering::Greater, porque 50 é maior que 38. A expressão match recebe o valor Ordering::Greater e começa a verificar o padrão de cada braço. Ela olha para o padrão do primeiro braço, Ordering::Less, e vê que o valor Ordering::Greater não corresponde a Ordering::Less, então ignora o código desse braço e segue para o próximo. O padrão do braço seguinte é Ordering::Greater, que corresponde a Ordering::Greater! O código associado a esse braço será executado e imprimirá Too big! na tela. A expressão match termina após a primeira correspondência bem-sucedida, então ela não verifica o último braço nesse cenário.

No entanto, o código da Listagem 2-4 ainda não compila. Vamos tentar:

$ cargo build
   Compiling libc v0.2.86
   Compiling getrandom v0.2.2
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.10
   Compiling rand_core v0.6.2
   Compiling rand_chacha v0.3.0
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
  --> src/main.rs:23:21
   |
23 |     match guess.cmp(&secret_number) {
   |                 --- ^^^^^^^^^^^^^^ expected `&String`, found `&{integer}`
   |                 |
   |                 arguments to this method are incorrect
   |
   = note: expected reference `&String`
              found reference `&{integer}`
note: method defined here
  --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/cmp.rs:979:8

For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game` (bin "guessing_game") due to 1 previous error

A essência do erro é que existem tipos incompatíveis. Rust tem um sistema de tipos forte e estático, mas também possui inferência de tipos. Quando escrevemos let mut guess = String::new(), Rust conseguiu inferir que guess deveria ser uma String, sem exigir que escrevêssemos isso explicitamente. Já secret_number é um tipo numérico. Alguns dos tipos numéricos de Rust podem conter um valor entre 1 e 100: i32, um número de 32 bits; u32, um inteiro sem sinal de 32 bits; i64, um número de 64 bits; entre outros. A menos que você especifique algo diferente, Rust usa i32 por padrão, então esse é o tipo de secret_number, a menos que alguma informação em outro ponto faça o compilador inferir outro tipo numérico. O erro acontece porque Rust não pode comparar uma string com um tipo numérico.

No fim das contas, queremos converter a String lida da entrada em um tipo numérico, para podermos compará-la numericamente com o número secreto. Fazemos isso adicionando a linha a seguir ao corpo de main:

Nome do arquivo: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    // --snip--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

A linha é:

let guess: u32 = guess.trim().parse().expect("Please type a number!");

Criamos uma variável chamada guess. Mas espere: o programa já não tem uma variável com esse nome? Tem, mas, felizmente, Rust nos permite sombrear o valor anterior de guess com um novo. Shadowing nos permite reutilizar o nome da variável em vez de nos obrigar a criar duas variáveis diferentes, como guess_str e guess, por exemplo. Veremos isso com mais detalhes no Capítulo 3, mas, por enquanto, basta saber que esse recurso é muito usado quando queremos converter um valor de um tipo para outro.

Associamos essa nova variável à expressão guess.trim().parse(). O guess na expressão se refere à variável guess original, que continha a entrada como string. O método trim em uma instância de String remove qualquer espaço em branco no início e no fim, o que precisamos fazer antes de converter a string para u32, que só pode conter dados numéricos. A pessoa usuária precisa pressionar enter para satisfazer read_line e inserir seu palpite, o que adiciona um caractere de nova linha à string. Por exemplo, se a pessoa usuária digitar 5 e pressionar enter, guess ficará assim: 5\n. O \n representa “nova linha”. No Windows, pressionar enter resulta em retorno de carro e nova linha, \r\n. O método trim elimina \n ou \r\n, deixando apenas 5.

O método parse em strings converte uma string em outro tipo. Aqui, nós o usamos para converter uma string em número. Precisamos dizer ao Rust exatamente qual tipo numérico queremos usando let guess: u32. Os dois-pontos (:) depois de guess dizem ao Rust que vamos anotar o tipo da variável. Rust tem alguns tipos numéricos embutidos; o u32 visto aqui é um inteiro sem sinal de 32 bits. Ele é uma boa escolha padrão para um número pequeno e positivo. Você aprenderá sobre outros tipos numéricos no Capítulo 3.

Além disso, a anotação u32 neste programa de exemplo, junto com a comparação com secret_number, significa que Rust inferirá que secret_number também deve ser um u32. Assim, agora a comparação será entre dois valores do mesmo tipo!

O método parse só funcionará em caracteres que podem ser convertidos logicamente em número e, portanto, pode falhar facilmente. Se, por exemplo, a string contivesse A👍%, não haveria como convertê-la em número. Como isso pode falhar, o método parse retorna um valor do tipo Result, assim como o método read_line faz, como discutimos anteriormente em “Lidando com falhas potenciais com Result”. Vamos tratar esse Result da mesma forma, usando novamente o método expect. Se parse retornar uma variante Err de Result porque não conseguiu criar um número a partir da string, a chamada a expect encerrará o jogo e imprimirá a mensagem que fornecemos. Se parse conseguir converter a string para número, ele retornará a variante Ok de Result, e expect retornará o número que queremos a partir do valor Ok.

Vamos executar o programa agora:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
  76
You guessed: 76
Too big!

Muito bom! Mesmo com espaços antes do palpite, o programa ainda conseguiu entender que a pessoa usuária digitou 76. Execute o programa algumas vezes para observar o comportamento com diferentes tipos de entrada: acerte o número, escolha um número alto demais e depois um baixo demais.

Temos a maior parte do jogo funcionando agora, mas a pessoa usuária só pode dar um palpite. Vamos mudar isso adicionando um loop!

Permitindo Múltiplos Palpites com Looping

A palavra-chave loop cria um loop infinito. Vamos adicionar um loop para dar mais chances de acertar o número:

Nome do arquivo: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    // --snip--

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        // --snip--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => println!("You win!"),
        }
    }
}

Como você pode ver, movemos tudo a partir do prompt que pede o palpite para dentro de um loop. Certifique-se de recuar em mais quatro espaços as linhas dentro do loop e execute o programa novamente. Agora o programa pedirá outro palpite indefinidamente, o que introduz um novo problema: não parece haver uma forma de sair!

A pessoa usuária sempre pode interromper o programa usando o atalho de teclado ctrl-C. Mas há outra forma de escapar desse monstro insaciável, como mencionamos na discussão sobre parse em “Comparando o Palpite com o Número Secreto”: se a pessoa usuária inserir uma resposta que não seja número, o programa vai encerrar. Podemos nos aproveitar disso para permitir que ela saia, como mostra o exemplo a seguir:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit

thread 'main' panicked at src/main.rs:28:47:
Please type a number!: ParseIntError { kind: InvalidDigit }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Digitar quit encerra o jogo, mas, como você pode notar, qualquer outra entrada não numérica também o encerra. Isso está longe do ideal; queremos que o jogo também termine quando o número correto for adivinhado.

Desistir após um palpite correto

Vamos programar o jogo para encerrar quando a pessoa usuária vencer, adicionando uma instrução break:

Nome do arquivo: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Adicionar a linha break após You win! faz o programa sair do loop quando a pessoa usuária acerta o número secreto. Sair do loop também significa sair do programa, porque o loop é a última parte de main.

Tratamento de entrada inválida

Para refinar ainda mais o comportamento do jogo, em vez de travar o programa quando o usuário insere um não-número, vamos fazer o jogo ignorar um não-número para que o usuário pode continuar adivinhando. Podemos fazer isso alterando a linha onde guess é convertido de String para u32, conforme mostrado na Listagem 2-5.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        // --snip--

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Mudamos de uma chamada a expect para uma expressão match, deixando de encerrar o programa em caso de erro para passar a tratá-lo. Lembre-se de que parse retorna um Result, e Result é um enum com as variantes Ok e Err. Estamos usando uma expressão match aqui, assim como fizemos com o resultado Ordering retornado pelo método cmp.

Se parse conseguir transformar a string em um número, ele retornará um valor Ok contendo o número resultante. Esse valor corresponderá ao padrão do primeiro braço, e a expressão match retornará apenas o valor num produzido por parse dentro do Ok. Esse número irá parar exatamente onde queremos: na nova variável guess que estamos criando.

Se parse não conseguir transformar a string em um número, ele retornará um valor Err com mais informações sobre o erro. Esse valor não corresponde ao padrão Ok(num) do primeiro braço, mas corresponde ao padrão Err(_) do segundo. O sublinhado _ é um curinga; neste exemplo, estamos dizendo que queremos corresponder a todos os valores Err, independentemente das informações que carregam. Então o programa executa o código do segundo braço, continue, que o faz ir para a próxima iteração do loop e pedir outro palpite. Na prática, o programa ignora qualquer erro que parse encontrar!

Agora tudo no programa deve funcionar conforme o esperado. Vamos tentar:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!

Incrível! Com um último ajuste pequeno, terminaremos o jogo de adivinhação. Lembre-se de que o programa ainda está imprimindo o número secreto. Isso foi útil para testar, mas estraga o jogo. Vamos remover o println! que imprime o número secreto. A Listagem 2-6 mostra o código final.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Neste ponto, você construiu com sucesso o jogo de adivinhação. Parabéns!

Resumo

Este projeto foi uma forma prática de apresentar muitos novos conceitos do Rust: let, match, funções, uso de crates externas e muito mais. Nos próximos capítulos, você aprenderá sobre esses conceitos com mais detalhes. Capítulo 3 cobre conceitos que a maioria das linguagens de programação possui, como variáveis, dados tipos e funções, e mostra como usá-los no Rust. O Capítulo 4 explora ownership, um recurso que torna o Rust diferente de outras linguagens. Capítulo 5 discute estruturas e sintaxe de método, e o Capítulo 6 explica como funcionam as enumerações.

Conceitos Comuns de Programação

Este capítulo aborda conceitos que aparecem em praticamente toda linguagem de programação e mostra como eles funcionam em Rust. Muitas linguagens têm muito em comum em seu núcleo. Nenhum dos conceitos apresentados aqui é exclusivo do Rust, mas vamos discuti-los no contexto da linguagem e explicar as convenções em torno de seu uso.

Mais especificamente, você aprenderá sobre variáveis, tipos básicos, funções, comentários e fluxo de controle. Esses fundamentos estarão presentes em todo programa Rust, e aprendê-los cedo dará a você uma base sólida para começar.

Variáveis e Mutabilidade

Variáveis e Mutabilidade

Como mencionado na seção “Armazenando valores com variáveis”, por padrão, as variáveis são imutáveis. Esse é um dos vários empurrões que o Rust dá para que você escreva código tirando proveito da segurança e da facilidade de concorrência que a linguagem oferece. Ainda assim, você continua tendo a opção de tornar suas variáveis mutáveis. Vamos explorar como e por que Rust incentiva você a preferir a imutabilidade e por que, às vezes, pode fazer sentido abrir mão disso.

Quando uma variável é imutável, depois que um valor é associado a um nome, você não pode alterar esse valor. Para ilustrar isso, gere um novo projeto chamado variables dentro do diretório projects usando cargo new variables.

Depois, no novo diretório variables, abra src/main.rs e substitua seu código pelo seguinte, que ainda não compilará:

Nome do arquivo: src/main.rs

fn main() {
    let x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

Salve e execute o programa com cargo run. Você deverá receber uma mensagem de erro sobre imutabilidade, como mostrado nesta saída:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0384]: cannot assign twice to immutable variable `x`
 --> src/main.rs:4:5
  |
2 |     let x = 5;
  |         - first assignment to `x`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable
  |
help: consider making this binding mutable
  |
2 |     let mut x = 5;
  |         +++

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` (bin "variables") due to 1 previous error

Este exemplo mostra como o compilador ajuda você a encontrar erros em seus programas. Erros de compilação podem ser frustrantes, mas, na verdade, eles só significam que seu programa ainda não está fazendo com segurança aquilo que você quer; eles não significam que você é um mau programador! Rustaceanos experientes também recebem erros do compilador.

Você recebeu a mensagem de erro cannot assign twice to immutable variable `x` porque tentou atribuir um segundo valor à variável imutável x.

É importante recebermos erros em tempo de compilação quando tentamos mudar um valor marcado como imutável, porque exatamente esse tipo de situação pode levar a bugs. Se uma parte do código opera supondo que um valor nunca vai mudar e outra parte muda esse valor, é possível que a primeira parte do código não faça o que foi projetada para fazer. A causa desse tipo de bug pode ser difícil de rastrear depois, principalmente quando a segunda parte do código muda o valor apenas às vezes. O compilador Rust garante que, quando você afirma que um valor não vai mudar, ele realmente não vai mudar, então você não precisa ficar acompanhando isso manualmente. Isso torna o código mais fácil de entender.

Mas a mutabilidade pode ser muito útil e pode tornar o código mais prático de escrever. Embora as variáveis sejam imutáveis por padrão, você pode torná-las mutáveis adicionando mut antes do nome da variável, como fez no Capítulo 2. Adicionar mut também comunica intenção a futuras pessoas leitoras do código, indicando que outras partes do programa mudarão o valor dessa variável.

Por exemplo, vamos mudar src/main.rs para o seguinte:

Nome do arquivo: src/main.rs

fn main() {
    let mut x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

Quando executamos o programa agora, obtemos isto:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
The value of x is: 5
The value of x is: 6

Temos permissão para mudar o valor associado a x de 5 para 6 quando mut é usado. No fim das contas, decidir usar mutabilidade ou não depende de você e do que parecer mais claro naquela situação específica.

Declarando constantes

Assim como variáveis imutáveis, constantes são valores associados a um nome e que não podem mudar, mas há algumas diferenças entre constantes e variáveis.

Primeiro, não é permitido usar mut com constantes. Constantes não são apenas imutáveis por padrão, elas são sempre imutáveis. Você declara constantes usando a palavra-chave const em vez de let, e o tipo do valor deve ser anotado. Falaremos sobre tipos e anotações de tipo na próxima seção, “Tipos de dados”, então não se preocupe com os detalhes agora. Só saiba que você sempre precisa anotar o tipo.

Constantes podem ser declaradas em qualquer escopo, inclusive no escopo global, o que as torna úteis para valores que muitas partes do código precisam conhecer.

A última diferença é que constantes só podem ser definidas como expressões constantes, e não como o resultado de um valor que só poderia ser calculado em tempo de execução.

Aqui está um exemplo de declaração de constante:

#![allow(unused)]
fn main() {
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
}

O nome da constante é THREE_HOURS_IN_SECONDS, e seu valor é o resultado da multiplicação de 60, o número de segundos em um minuto, por 60, o número de minutos em uma hora, por 3, o número de horas que queremos contar neste programa. A convenção de nomenclatura do Rust para constantes é usar somente maiúsculas, com underscores entre as palavras. O compilador consegue avaliar um conjunto limitado de operações em tempo de compilação, o que nos permite escrever esse valor de uma forma mais fácil de entender e verificar, em vez de definir a constante diretamente como 10.800. Veja a seção do Rust Reference sobre avaliação de constantes para mais informações sobre as operações que podem ser usadas ao declarar constantes.

Constantes são válidas durante todo o tempo de execução do programa, dentro do escopo em que foram declaradas. Essa propriedade as torna úteis para valores do domínio da sua aplicação que múltiplas partes do programa talvez precisem conhecer, como o número máximo de pontos que qualquer jogador de um jogo pode ganhar ou a velocidade da luz.

Dar nome de constantes a valores hardcoded usados ao longo do programa é útil para transmitir o significado desse valor a futuras pessoas mantenedoras do código. Isso também ajuda a ter apenas um lugar no código que precisará ser alterado se o valor hardcoded tiver de ser atualizado no futuro.

Shadowing

Como você viu no tutorial do jogo de adivinhação no Capítulo 2, você pode declarar uma nova variável com o mesmo nome de uma variável anterior. Rustaceanos dizem que a primeira variável é shadowed pela segunda, o que significa que a segunda variável é aquela que o compilador verá quando você usar aquele nome. Na prática, a segunda variável encobre a primeira, e qualquer uso desse nome se refere a ela até que ela própria seja shadowed ou até que o escopo termine. Podemos fazer shadowing de uma variável repetindo o mesmo nome e usando novamente a palavra-chave let, assim:

Nome do arquivo: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }

    println!("The value of x is: {x}");
}

Este programa primeiro associa x ao valor 5. Em seguida, cria uma nova variável x repetindo let x =, pegando o valor original e somando 1, de modo que x passa a valer 6. Depois, dentro de um escopo interno criado com chaves, a terceira instrução let também faz shadowing de x e cria uma nova variável, multiplicando o valor anterior por 2, o que faz x valer 12. Quando esse escopo termina, o shadowing interno acaba, e x volta a valer 6. Quando executamos esse programa, ele produz a seguinte saída:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
The value of x in the inner scope is: 12
The value of x is: 6

Shadowing é diferente de marcar uma variável com mut, porque receberemos um erro em tempo de compilação se, por engano, tentarmos reatribuir um valor a essa variável sem usar a palavra-chave let. Ao usar let, podemos realizar algumas transformações sobre um valor, mas fazer com que a variável seja imutável depois que essas transformações terminarem.

A outra diferença entre mut e shadowing é que, como estamos efetivamente criando uma nova variável quando usamos let de novo, podemos mudar o tipo do valor e ainda reutilizar o mesmo nome. Por exemplo, suponha que nosso programa peça a uma pessoa usuária que informe quantos espaços quer entre certos textos, digitando caracteres de espaço, e depois queiramos armazenar essa entrada como um número:

fn main() {
    let spaces = "   ";
    let spaces = spaces.len();
}

A primeira variável spaces é do tipo string, e a segunda variável spaces é do tipo numérico. Shadowing nos poupa de precisar inventar nomes diferentes, como spaces_str e spaces_num; em vez disso, podemos reutilizar o nome mais simples spaces. No entanto, se tentarmos usar mut para isso, como mostrado aqui, receberemos um erro em tempo de compilação:

fn main() {
    let mut spaces = "   ";
    spaces = spaces.len();
}

O erro diz que não temos permissão para mudar o tipo de uma variável:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0308]: mismatched types
 --> src/main.rs:3:14
  |
2 |     let mut spaces = "   ";
  |                      ----- expected due to this value
3 |     spaces = spaces.len();
  |              ^^^^^^^^^^^^ expected `&str`, found `usize`

For more information about this error, try `rustc --explain E0308`.
error: could not compile `variables` (bin "variables") due to 1 previous error

Agora que exploramos como as variáveis funcionam, vamos ver mais tipos de dados que elas podem assumir.

Tipos de Dados

Tipos de Dados

Todo valor em Rust tem um certo tipo de dado, que informa ao Rust que tipo de dado está sendo especificado, para que ele saiba como trabalhar com esse dado. Vamos examinar dois subconjuntos de tipos de dados: escalares e compostos.

Tenha em mente que Rust é uma linguagem de tipagem estática, o que significa que ela precisa conhecer os tipos de todas as variáveis em tempo de compilação. Na maior parte do tempo, o compilador consegue inferir qual tipo queremos usar com base no valor e em como o utilizamos. Nos casos em que muitos tipos são possíveis, como quando convertemos uma String para um tipo numérico usando parse na seção “Comparando o Palpite com o Número Secreto” no Capítulo 2, precisamos adicionar uma anotação de tipo, assim:

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Not a number!");
}

Se não adicionarmos a anotação de tipo : u32 mostrada no código anterior, o Rust exibirá o erro a seguir, o que significa que o compilador precisa de mais informações para saber qual tipo queremos usar:

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0284]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^        ----- type must be known at this point
  |
  = note: cannot satisfy `<_ as FromStr>::Err == _`
help: consider giving `guess` an explicit type
  |
2 |     let guess: /* Type */ = "42".parse().expect("Not a number!");
  |              ++++++++++++

For more information about this error, try `rustc --explain E0284`.
error: could not compile `no_type_annotations` (bin "no_type_annotations") due to 1 previous error

Você verá anotações de tipo diferentes para outros tipos de dados.

Tipos Escalares

Um tipo escalar representa um único valor. Rust tem quatro tipos escalares primários: inteiros, números de ponto flutuante, booleanos e caracteres. Você talvez reconheça esses tipos de outras linguagens de programação. Vamos ver como eles funcionam em Rust.

Tipos Inteiros

Um inteiro é um número sem componente fracionário. Já usamos um tipo inteiro no Capítulo 2, o tipo u32. Essa declaração de tipo indica que o valor a ele associado deve ser um inteiro sem sinal, pois os tipos inteiros com sinal começam com i em vez de u, e que ocupa 32 bits de espaço. A Tabela 3-1 mostra os tipos inteiros embutidos no Rust. Podemos usar qualquer uma dessas variantes para declarar o tipo de um valor inteiro.

Tabela 3-1: Tipos Inteiros em Rust

Cada variante pode ser com sinal ou sem sinal e tem um tamanho explícito. Com sinal e sem sinal se referem a se o número pode ser negativo ou não. Em outras palavras, se o número precisa carregar um sinal junto consigo, ele é com sinal; caso contrário, ele é sempre positivo e pode ser representado sem sinal. É como escrever números no papel: quando o sinal importa, o número é escrito com um sinal de mais ou de menos; no entanto, quando é seguro assumir que ele é positivo, ele aparece sem sinal. Números com sinal são armazenados usando a representação em complemento de dois.

Cada variante com sinal pode armazenar números entre −(2^{n − 1}) e 2^{n − 1} − 1, inclusive, em que n é o número de bits usado por aquela variante. Assim, um i8 pode armazenar números entre −(2⁷) e 2⁷ − 1, isto é, de −128 a 127. As variantes sem sinal podem armazenar números entre 0 e 2ⁿ − 1; logo, um u8 pode armazenar números entre 0 e 2⁸ − 1, isto é, de 0 a 255.

Além disso, os tipos isize e usize dependem da arquitetura do computador em que seu programa está sendo executado: 64 bits em arquiteturas de 64 bits e 32 bits em arquiteturas de 32 bits.

Você pode escrever literais inteiros em qualquer um dos formatos mostrados na Tabela 3-2. Note que literais numéricos que podem assumir vários tipos aceitam um sufixo de tipo, como 57u8, para indicar o tipo. Literais numéricos também podem usar _ como separador visual para facilitar a leitura, como em 1_000, que tem o mesmo valor de 1000.

Tabela 3-2: Literais Inteiros em Rust

Então, como saber qual tipo inteiro usar? Se você estiver em dúvida, os defaults do Rust geralmente são um bom ponto de partida: tipos inteiros usam i32 por padrão. A principal situação em que você usaria isize ou usize é ao indexar algum tipo de coleção.

Tipos de Ponto Flutuante

Rust também tem dois tipos primitivos para números de ponto flutuante, que são números com casas decimais. Os tipos de ponto flutuante do Rust são f32 e f64, com 32 e 64 bits de tamanho, respectivamente. O tipo padrão é f64 porque, em CPUs modernas, ele tem velocidade semelhante à de f32, mas é capaz de representar mais precisão. Todos os tipos de ponto flutuante têm sinal.

Este é um exemplo mostrando números de ponto flutuante em ação:

Nome do arquivo: src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

Números de ponto flutuante são representados de acordo com o padrão IEEE-754.

Operações Numéricas

Rust oferece suporte às operações matemáticas básicas que você esperaria para todos os tipos numéricos: adição, subtração, multiplicação, divisão e resto. A divisão inteira é truncada em direção a zero até o inteiro mais próximo. O código a seguir mostra como usar cada operação numérica em uma instrução let:

Nome do arquivo: src/main.rs

fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

    // division
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Results in -1

    // remainder
    let remainder = 43 % 5;
}

Cada expressão dessas instruções usa um operador matemático e avalia para um único valor, que é então vinculado a uma variável. O Apêndice B contém uma lista de todos os operadores fornecidos pelo Rust.

O Tipo Booleano

Como na maioria das outras linguagens de programação, um tipo booleano em Rust tem dois valores possíveis: true e false. Booleanos têm tamanho de um byte. O tipo booleano em Rust é especificado com bool. Por exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // with explicit type annotation
}

A principal forma de usar valores booleanos é com condicionais, como uma expressão if. Veremos como expressões if funcionam em Rust na seção “Fluxo de Controle”.

O Tipo Caractere

O tipo char do Rust é o tipo alfabético mais primitivo da linguagem. Aqui estão alguns exemplos de declaração de valores char:

Nome do arquivo: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // with explicit type annotation
    let heart_eyed_cat = '😻';
}

Observe que especificamos literais char com aspas simples, ao contrário de literais de string, que usam aspas duplas. O tipo char do Rust ocupa 4 bytes e representa um valor escalar Unicode, o que significa que ele pode representar muito mais do que apenas ASCII. Letras acentuadas, caracteres chineses, japoneses e coreanos, emojis e espaços de largura zero são todos valores char válidos em Rust. Valores escalares Unicode variam de U+0000 até U+D7FF e de U+E000 até U+10FFFF, inclusive. No entanto, “caractere” não é exatamente um conceito do Unicode, então sua intuição humana sobre o que é um “caractere” pode não corresponder ao que um char representa em Rust. Discutiremos esse tópico em detalhes em “Armazenando Texto Codificado em UTF-8 com Strings” no Capítulo 8.

Tipos Compostos

Tipos compostos podem agrupar vários valores em um único tipo. Rust tem dois tipos compostos primitivos: tuplas e arrays.

O Tipo Tupla

Uma tupla é uma forma geral de agrupar vários valores de tipos diferentes em um único tipo composto. Tuplas têm comprimento fixo: uma vez declaradas, não podem crescer nem encolher.

Criamos uma tupla escrevendo uma lista de valores separados por vírgula entre parênteses. Cada posição da tupla tem um tipo, e os tipos dos diferentes valores da tupla não precisam ser iguais. Adicionamos anotações de tipo opcionais neste exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

A variável tup se vincula à tupla inteira porque uma tupla é considerada um único elemento composto. Para obter os valores individuais de uma tupla, podemos usar correspondência de padrões para desestruturar o valor da tupla, assim:

Nome do arquivo: src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("The value of y is: {y}");
}

Esse programa primeiro cria uma tupla e a vincula à variável tup. Depois, ele usa um padrão com let para pegar tup e transformá-la em três variáveis separadas, x, y e z. Isso é chamado de desestruturação, porque quebra a tupla única em três partes. Por fim, o programa imprime o valor de y, que é 6.4.

Também podemos acessar um elemento da tupla diretamente usando um ponto (.) seguido pelo índice do valor que queremos acessar. Por exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

Esse programa cria a tupla x e depois acessa cada elemento da tupla usando seus respectivos índices. Como na maioria das linguagens de programação, o primeiro índice de uma tupla é 0.

A tupla sem nenhum valor recebe um nome especial: unit. Esse valor e seu tipo correspondente são ambos escritos como () e representam um valor vazio ou um tipo de retorno vazio. Expressões retornam implicitamente o valor unit se não retornarem nenhum outro valor.

O Tipo Array

Outra forma de ter uma coleção de vários valores é com um array. Diferente de uma tupla, todo elemento de um array precisa ter o mesmo tipo. E, diferente dos arrays em algumas outras linguagens, arrays em Rust têm comprimento fixo.

Escrevemos os valores de um array como uma lista separada por vírgulas entre colchetes:

Nome do arquivo: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];
}

Arrays são úteis quando você quer que os dados sejam alocados na pilha, como os outros tipos que vimos até aqui, em vez de no heap, assunto que discutiremos mais no Capítulo 4, ou quando quer garantir que sempre terá um número fixo de elementos. No entanto, arrays não são tão flexíveis quanto o tipo vetor. Um vetor é um tipo de coleção semelhante, fornecido pela biblioteca padrão, que pode crescer ou encolher porque seu conteúdo vive no heap. Se você estiver em dúvida entre usar um array ou um vetor, é bem provável que deva usar um vetor. O Capítulo 8 discute vetores com mais detalhes.

Ainda assim, arrays são mais úteis quando você sabe que o número de elementos não precisará mudar. Por exemplo, se você estivesse usando os nomes dos meses em um programa, provavelmente usaria um array em vez de um vetor, porque sabe que sempre haverá 12 elementos:

#![allow(unused)]
fn main() {
let months = ["January", "February", "March", "April", "May", "June", "July",
              "August", "September", "October", "November", "December"];
}

Você escreve o tipo de um array usando colchetes com o tipo de cada elemento, um ponto e vírgula e, em seguida, o número de elementos do array, assim:

#![allow(unused)]
fn main() {
let a: [i32; 5] = [1, 2, 3, 4, 5];
}

Aqui, i32 é o tipo de cada elemento. Depois do ponto e vírgula, o número 5 indica que o array contém cinco elementos.

Você também pode inicializar um array para que todos os elementos tenham o mesmo valor especificando o valor inicial, seguido de um ponto e vírgula, e então o comprimento do array entre colchetes, como aqui:

#![allow(unused)]
fn main() {
let a = [3; 5];
}

O array chamado a conterá 5 elementos, todos inicialmente definidos com o valor 3. Isso é o mesmo que escrever let a = [3, 3, 3, 3, 3];, mas de uma forma mais concisa.

Acesso a Elementos de Array

Um array é um único bloco de memória de tamanho conhecido e fixo, que pode ser alocado na pilha. Você pode acessar elementos de um array usando indexação, assim:

Nome do arquivo: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}

Neste exemplo, a variável chamada first receberá o valor 1 porque esse é o valor no índice [0] do array. A variável chamada second receberá o valor 2 do índice [1] do array.

Acesso Inválido a Elemento de Array

Vamos ver o que acontece se você tentar acessar um elemento de um array que está além do seu final. Digamos que você execute este código, semelhante ao jogo de adivinhação do Capítulo 2, para obter do usuário um índice de array:

Nome do arquivo: src/main.rs

use std::io;

fn main() {
    let a = [1, 2, 3, 4, 5];

    println!("Please enter an array index.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Failed to read line");

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

    let element = a[index];

    println!("The value of the element at index {index} is: {element}");
}

Esse código compila com sucesso. Se você o executar com cargo run e digitar 0, 1, 2, 3 ou 4, o programa imprimirá o valor correspondente naquele índice do array. Mas, se em vez disso você digitar um número além do final do array, como 10, verá uma saída assim:

thread 'main' panicked at src/main.rs:19:19:
index out of bounds: the len is 5 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

O programa produziu um erro em tempo de execução no ponto em que tentou usar um valor inválido na operação de indexação. O programa foi encerrado com uma mensagem de erro e não executou a instrução final println!. Quando você tenta acessar um elemento usando indexação, o Rust verifica se o índice especificado é menor que o comprimento do array. Se o índice for maior ou igual ao comprimento, o Rust entra em pânico. Essa verificação precisa acontecer em tempo de execução, especialmente neste caso, porque o compilador não tem como saber qual valor um usuário digitará quando executar o código depois.

Esse é um exemplo dos princípios de segurança de memória do Rust em ação. Em muitas linguagens de baixo nível, esse tipo de verificação não é feito e, quando você fornece um índice incorreto, memória inválida pode ser acessada. O Rust protege você contra esse tipo de erro saindo imediatamente, em vez de permitir o acesso à memória e continuar. O Capítulo 9 discute mais sobre o tratamento de erros em Rust e sobre como escrever código legível e seguro, que nem entre em pânico nem permita acessos inválidos à memória.

Funções

Funções

Funções são onipresentes em código Rust. Você já viu uma das funções mais importantes da linguagem: a função main, que é o ponto de entrada de muitos programas. Você também já viu a palavra-chave fn, que permite declarar novas funções.

Código Rust usa snake case como estilo convencional para nomes de funções e variáveis, em que todas as letras ficam em minúsculas e as palavras são separadas por sublinhados. Aqui está um programa que contém um exemplo de definição de função:

Nome do arquivo: src/main.rs

fn main() {
    println!("Hello, world!");

    another_function();
}

fn another_function() {
    println!("Another function.");
}

Definimos uma função em Rust digitando fn, seguido pelo nome da função e por um conjunto de parênteses. As chaves informam ao compilador onde o corpo da função começa e termina.

Podemos chamar qualquer função que tenhamos definido digitando seu nome seguido por um conjunto de parênteses. Como another_function está definida no programa, ela pode ser chamada de dentro da função main. Observe que definimos another_function depois da função main no código-fonte; também poderíamos tê-la definido antes. Rust não se importa com o lugar em que você define suas funções, apenas com o fato de elas estarem definidas em algum escopo visível para quem as chama.

Vamos iniciar um novo projeto binário chamado functions para explorar melhor as funções. Coloque o exemplo another_function em src/main.rs e execute-o. Você deverá ver a seguinte saída:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.28s
     Running `target/debug/functions`
Hello, world!
Another function.

As linhas são executadas na ordem em que aparecem na função main. Primeiro, a mensagem “Hello, world!” é impressa; depois, another_function é chamada e sua mensagem é impressa.

Parâmetros

Podemos definir funções com parâmetros, que são variáveis especiais que fazem parte da assinatura de uma função. Quando uma função tem parâmetros, você pode fornecer valores concretos para eles. Tecnicamente, esses valores concretos são chamados de argumentos, mas, em conversas casuais, as pessoas tendem a usar as palavras parâmetro e argumento de forma intercambiável, tanto para as variáveis na definição da função quanto para os valores concretos passados quando você chama a função.

Nesta versão de another_function, adicionamos um parâmetro:

Nome do arquivo: src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("The value of x is: {x}");
}

Tente executar este programa; você deve obter a seguinte saída:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
The value of x is: 5

A declaração de another_function tem um parâmetro chamado x. O tipo de x é especificado como i32. Quando passamos 5 para another_function, a macro println! coloca 5 no lugar do par de chaves que continha x na string de formatação.

Nas assinaturas de funções, você deve declarar o tipo de cada parâmetro. Essa é uma decisão deliberada no design de Rust: exigir anotações de tipo em definições de função significa que o compilador quase nunca precisa que você as use em outras partes do código para descobrir a que tipo você está se referindo. O compilador também consegue fornecer mensagens de erro mais úteis se souber quais tipos a função espera.

Ao definir vários parâmetros, separe suas declarações com vírgulas, assim:

Nome do arquivo: src/main.rs

fn main() {
    print_labeled_measurement(5, 'h');
}

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("The measurement is: {value}{unit_label}");
}

Este exemplo cria uma função chamada print_labeled_measurement com dois parâmetros. O primeiro se chama value e é um i32. O segundo se chama unit_label e tem tipo char. A função então imprime um texto contendo tanto value quanto unit_label.

Vamos experimentar esse código. Substitua o programa atual do arquivo src/main.rs do projeto functions pelo exemplo anterior e execute-o com cargo run:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/functions`
The measurement is: 5h

Como chamamos a função com 5 como valor de value e 'h' como valor de unit_label, a saída do programa contém esses valores.

Instruções e expressões

Corpos de funções são compostos por uma série de instruções, opcionalmente terminando com uma expressão. Até agora, as funções que vimos não incluíam uma expressão final, mas você já viu uma expressão como parte de uma instrução. Como Rust é uma linguagem baseada em expressões, essa é uma distinção importante de entender. Outras linguagens não fazem exatamente a mesma distinção, então vamos examinar o que são instruções e expressões e como suas diferenças afetam os corpos das funções.

• Instruções são comandos que executam alguma ação e não retornam um valor.
• Expressões são avaliadas para produzir um valor resultante.

Vejamos alguns exemplos.

Na verdade, já usamos instruções e expressões. Criar uma variável e atribuir um valor a ela com a palavra-chave let é uma instrução. Na Listagem 3-1, let y = 6; é uma instrução.

fn main() {
    let y = 6;
}

Definições de funções também são instruções; o exemplo inteiro anterior é, por si só, uma instrução. Como veremos em breve, chamar uma função não é uma instrução.

Instruções não retornam valores. Portanto, você não pode atribuir uma instrução let a outra variável, como o código a seguir tenta fazer; você receberá um erro:

Nome do arquivo: src/main.rs

fn main() {
    let x = (let y = 6);
}

Ao executar esse programa, o erro obtido será parecido com este:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^
  |
  = note: only supported directly in conditions of `if` and `while` expressions

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` (bin "functions") due to 1 previous error; 1 warning emitted

A instrução let y = 6 não retorna valor algum, então não existe nada ao qual x possa se vincular. Isso é diferente do que acontece em outras linguagens, como C e Ruby, em que a atribuição retorna o valor atribuído. Nessas linguagens, você pode escrever x = y = 6 e fazer com que tanto x quanto y tenham o valor 6; em Rust, não é assim.

Expressões produzem um valor e constituem a maior parte do restante do código que você escreverá em Rust. Considere uma operação matemática como 5 + 6, que é uma expressão avaliada para o valor 11. Expressões podem fazer parte de instruções: na Listagem 3-1, o 6 na instrução let y = 6; é uma expressão avaliada para o valor 6. Chamar uma função é uma expressão. Chamar uma macro é uma expressão. Um novo bloco de escopo criado com chaves também é uma expressão, por exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let y = {
        let x = 3;
        x + 1
    };

    println!("The value of y is: {y}");
}

Esta expressão:

{
    let x = 3;
    x + 1
}

é um bloco que, neste caso, é avaliado como 4. Esse valor é vinculado a y como parte da instrução let. Observe a linha x + 1 sem ponto e vírgula no final, o que é diferente da maior parte das linhas que você viu até agora. Expressões não incluem ponto e vírgula ao final. Se você adicionar um ponto e vírgula ao fim de uma expressão, estará transformando-a em uma instrução, e ela então deixará de retornar um valor. Tenha isso em mente ao explorar os valores de retorno de funções e as expressões a seguir.

Funções com valores de retorno

Funções podem retornar valores para o código que as chama. Não damos nomes aos valores de retorno, mas precisamos declarar seu tipo após uma seta (->). Em Rust, o valor de retorno da função é sinônimo do valor da expressão final no bloco do corpo da função. Você pode retornar mais cedo de uma função usando a palavra-chave return e especificando um valor, mas a maioria das funções retorna a última expressão implicitamente. Aqui está um exemplo de função que retorna um valor:

Nome do arquivo: src/main.rs

fn five() -> i32 {
    5
}

fn main() {
    let x = five();

    println!("The value of x is: {x}");
}

Não há chamadas de função, macros nem mesmo instruções let na função five, apenas o número 5 sozinho. Isso é uma função perfeitamente válida em Rust. Observe também que o tipo de retorno da função foi especificado como -> i32. Tente executar esse código; a saída deve ser parecida com esta:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
The value of x is: 5

O 5 em five é o valor de retorno da função, e por isso o tipo de retorno é i32. Vamos examinar isso com mais detalhes. Há dois pontos importantes. Primeiro, a linha let x = five(); mostra que estamos usando o valor de retorno de uma função para inicializar uma variável. Como a função five retorna 5, essa linha é a mesma coisa que:

#![allow(unused)]
fn main() {
let x = 5;
}

Segundo, a função five não tem parâmetros e define o tipo de retorno, mas o corpo da função é apenas um 5, sem ponto e vírgula, porque essa é uma expressão cujo valor queremos retornar.

Vamos ver outro exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1
}

Executar esse código imprimirá The value of x is: 6. Mas o que acontece se colocarmos um ponto e vírgula ao final da linha que contém x + 1, transformando-a de expressão em instrução?

Nome do arquivo: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1;
}

Compilar esse código produzirá um erro, como este:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error[E0308]: mismatched types
 --> src/main.rs:7:24
  |
7 | fn plus_one(x: i32) -> i32 {
  |    --------            ^^^ expected `i32`, found `()`
  |    |
  |    implicitly returns `()` as its body has no tail or `return` expression
8 |     x + 1;
  |          - help: remove this semicolon to return this value

For more information about this error, try `rustc --explain E0308`.
error: could not compile `functions` (bin "functions") due to 1 previous error

A principal mensagem de erro, mismatched types, revela o problema central desse código. A definição da função plus_one diz que ela retornará um i32, mas instruções não produzem um valor; isso é expresso por (), o tipo unit. Portanto, nada é retornado, o que contradiz a definição da função e resulta em erro. Nessa saída, Rust fornece até uma mensagem que pode ajudar a corrigir o problema: ela sugere remover o ponto e vírgula, o que resolveria o erro.

Comentários

Comentários

Todo programador se esforça para tornar seu código fácil de entender, mas às vezes uma explicação extra é necessária. Nesses casos, programadores deixam comentários no código-fonte, que o compilador ignora, mas que podem ser úteis para quem estiver lendo o código.

Aqui está um comentário simples:

#![allow(unused)]
fn main() {
// hello, world
}

Em Rust, o estilo idiomático de comentário começa com duas barras, e o comentário continua até o fim da linha. Para comentários que ocupam mais de uma linha, você precisa incluir // em cada linha, assim:

#![allow(unused)]
fn main() {
// So we're doing something complicated here, long enough that we need
// multiple lines of comments to do it! Whew! Hopefully, this comment will
// explain what's going on.
}

Comentários também podem ser colocados ao final de linhas que contêm código:

Nome do arquivo: src/main.rs

fn main() {
    let lucky_number = 7; // I'm feeling lucky today
}

Mas com mais frequência você os verá neste formato, com o comentário em uma linha separada acima do código que ele está anotando:

Nome do arquivo: src/main.rs

fn main() {
    // I'm feeling lucky today
    let lucky_number = 7;
}

Rust também tem outro tipo de comentário, os comentários de documentação, que discutiremos na seção “Publicando uma crate no Crates.io” do Capítulo 14.

Fluxo de Controle

Fluxo de Controle

A capacidade de executar algum código dependendo de uma condição ser true e a capacidade de executar código repetidamente enquanto uma condição for true são blocos fundamentais da maioria das linguagens de programação. As construções mais comuns que permitem controlar o fluxo de execução de código em Rust são expressões if e loops.

Expressões if

Uma expressão if permite ramificar o código dependendo de condições. Você fornece uma condição e então diz: “Se esta condição for satisfeita, execute este bloco de código. Se ela não for satisfeita, não execute esse bloco.”

Crie um novo projeto chamado branches dentro do seu diretório projects para explorar a expressão if. No arquivo src/main.rs, digite o seguinte:

Nome do arquivo: src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

Todas as expressões if começam com a palavra-chave if, seguida de uma condição. Neste caso, a condição verifica se a variável number tem valor menor que 5. Colocamos o bloco de código a ser executado caso a condição seja true logo após a condição, entre chaves. Blocos de código associados às condições em expressões if às vezes são chamados de braços, assim como os braços de expressões match que discutimos na seção “Comparando o Palpite com o Número Secreto” do Capítulo 2.

Opcionalmente, também podemos incluir uma expressão else, como escolhemos fazer aqui, para fornecer ao programa um bloco alternativo de código a ser executado caso a condição avalie para false. Se você não fornecer uma expressão else e a condição for false, o programa simplesmente ignorará o bloco if e seguirá adiante para o próximo trecho de código.

Tente executar esse código; você deverá ver a seguinte saída:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was true

Vamos agora alterar o valor de number para um valor que torne a condição false, só para ver o que acontece:

fn main() {
    let number = 7;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

Execute o programa de novo e veja a saída:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was false

Também vale notar que a condição nesse código precisa ser um bool. Se a condição não for um bool, teremos um erro. Por exemplo, tente executar o seguinte código:

Nome do arquivo: src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("number was three");
    }
}

Desta vez, a condição do if avalia para o valor 3, e o Rust gera um erro:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: mismatched types
 --> src/main.rs:4:8
  |
4 |     if number {
  |        ^^^^^^ expected `bool`, found integer

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

O erro indica que o Rust esperava um bool, mas recebeu um inteiro. Diferentemente de linguagens como Ruby e JavaScript, o Rust não tentará converter automaticamente tipos não booleanos em booleanos. Você precisa ser explícito e sempre fornecer ao if um booleano como condição. Se quisermos que o bloco if execute somente quando um número for diferente de 0, por exemplo, podemos alterar a expressão if para a seguinte forma:

Nome do arquivo: src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number was something other than zero");
    }
}

Executar esse código imprimirá number was something other than zero.

Tratando Múltiplas Condições com else if

Você pode usar várias condições combinando if e else em uma expressão else if. Por exemplo:

Nome do arquivo: src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("number is divisible by 4");
    } else if number % 3 == 0 {
        println!("number is divisible by 3");
    } else if number % 2 == 0 {
        println!("number is divisible by 2");
    } else {
        println!("number is not divisible by 4, 3, or 2");
    }
}

Esse programa tem quatro caminhos possíveis. Depois de executá-lo, você deverá ver a seguinte saída:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
number is divisible by 3

Quando esse programa é executado, ele verifica cada expressão if em ordem e executa o primeiro corpo cuja condição avalia para true. Observe que, mesmo que 6 seja divisível por 2, não vemos a saída number is divisible by 2, nem vemos o texto number is not divisible by 4, 3, or 2 do bloco else. Isso acontece porque o Rust executa apenas o bloco correspondente à primeira condição true e, depois que encontra uma, nem sequer verifica as demais.

Usar muitas expressões else if pode poluir o código, então, se você tiver mais de uma, talvez valha a pena refatorar. O Capítulo 6 descreve uma poderosa construção de ramificação do Rust chamada match para esses casos.

Usando if em uma Instrução let

Como if é uma expressão, podemos usá-lo no lado direito de uma instrução let para atribuir o resultado a uma variável, como na Listagem 3-2.

fn main() {
    let condition = true;
    let number = if condition { 5 } else { 6 };

    println!("The value of number is: {number}");
}

A variável number ficará vinculada a um valor dependendo do resultado da expressão if. Execute esse código para ver o que acontece:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
The value of number is: 5

Lembre-se de que blocos de código avaliam para a última expressão neles, e números sozinhos também são expressões. Neste caso, o valor da expressão if inteira depende de qual bloco de código é executado. Isso significa que os valores que podem surgir como resultado de cada braço do if precisam ter o mesmo tipo; na Listagem 3-2, os resultados dos braços if e else eram inteiros i32. Se os tipos não forem compatíveis, como no exemplo a seguir, teremos um erro:

Nome do arquivo: src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "six" };

    println!("The value of number is: {number}");
}

Quando tentamos compilar esse código, recebemos um erro. Os braços if e else têm tipos de valor incompatíveis, e o Rust aponta exatamente onde está o problema no programa:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: `if` and `else` have incompatible types
 --> src/main.rs:4:44
  |
4 |     let number = if condition { 5 } else { "six" };
  |                                 -          ^^^^^ expected integer, found `&str`
  |                                 |
  |                                 expected because of this

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

A expressão no bloco if avalia para um inteiro, e a expressão no bloco else avalia para uma string. Isso não funciona porque variáveis precisam ter um único tipo, e o Rust precisa saber de forma definitiva, em tempo de compilação, qual é o tipo da variável number. Conhecer o tipo de number permite que o compilador verifique se esse tipo é válido em todos os lugares em que usamos number. O Rust não conseguiria fazer isso se o tipo de number fosse determinado apenas em tempo de execução; o compilador seria mais complexo e daria menos garantias sobre o código se precisasse acompanhar múltiplos tipos hipotéticos para qualquer variável.

Repetição com Loops

Com frequência é útil executar um bloco de código mais de uma vez. Para isso, o Rust fornece vários loops, que executam o código dentro do corpo do loop até o fim e então voltam imediatamente ao começo. Para experimentar com loops, vamos criar um novo projeto chamado loops.

Rust tem três tipos de loop: loop, while e for. Vamos experimentar cada um deles.

Repetindo Código com loop

A palavra-chave loop diz ao Rust para executar um bloco de código repetidas vezes, para sempre, ou até que você diga explicitamente que ele deve parar.

Como exemplo, altere o arquivo src/main.rs no seu diretório loops para que fique assim:

Nome do arquivo: src/main.rs

fn main() {
    loop {
        println!("again!");
    }
}

Quando executarmos esse programa, veremos again! sendo impresso continuamente, repetidas vezes, até interrompermos o programa manualmente. A maioria dos terminais oferece o atalho de teclado ctrl-C para interromper um programa preso em um loop contínuo. Experimente:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/loops`
again!
again!
again!
again!
^Cagain!

O símbolo ^C representa o ponto em que você pressionou ctrl-C.

Você pode ou não ver a palavra again! impressa depois de ^C, dependendo de onde o código estava dentro do loop quando recebeu o sinal de interrupção.

Felizmente, o Rust também fornece uma forma de sair de um loop usando código. Você pode colocar a palavra-chave break dentro do loop para dizer ao programa quando deve parar de executá-lo. Lembre-se de que fizemos isso no jogo de adivinhação, na seção “Saindo Depois de um Palpite Correto” do Capítulo 2, para encerrar o programa quando o usuário acertava o número.

Também usamos continue no jogo de adivinhação. Dentro de um loop, essa palavra-chave diz ao programa para pular qualquer código restante da iteração atual e ir direto para a próxima.

Retornando Valores a Partir de Loops

Um dos usos de loop é repetir uma operação que você sabe que pode falhar, como verificar se uma thread concluiu seu trabalho. Você também pode precisar passar o resultado dessa operação para fora do loop e usá-lo no restante do código. Para fazer isso, você pode adicionar o valor que deseja retornar após a expressão break usada para interromper o loop; esse valor será retornado para fora do loop, para que você possa utilizá-lo, como mostrado aqui:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
        }
    };

    println!("The result is {result}");
}

Antes do loop, declaramos uma variável chamada counter e a inicializamos com 0. Em seguida, declaramos uma variável chamada result para armazenar o valor retornado pelo loop. Em cada iteração do loop, somamos 1 à variável counter e então verificamos se counter é igual a 10. Quando isso acontece, usamos a palavra-chave break com o valor counter * 2. Depois do loop, usamos um ponto e vírgula para encerrar a instrução que atribui o valor a result. Por fim, imprimimos o valor contido em result, que neste caso é 20.

Você também pode usar return de dentro de um loop. Enquanto break sai apenas do loop atual, return sempre sai da função atual.

Desambiguando com Rótulos de Loop

Se você tiver loops dentro de loops, break e continue se aplicam ao loop mais interno naquele ponto. Opcionalmente, você pode especificar um rótulo de loop em um loop e então usar esse rótulo com break ou continue para indicar que essas palavras-chave devem se aplicar ao loop rotulado, em vez do mais interno. Rótulos de loop devem começar com uma aspas simples. Aqui está um exemplo com dois loops aninhados:

fn main() {
    let mut count = 0;
    'counting_up: loop {
        println!("count = {count}");
        let mut remaining = 10;

        loop {
            println!("remaining = {remaining}");
            if remaining == 9 {
                break;
            }
            if count == 2 {
                break 'counting_up;
            }
            remaining -= 1;
        }

        count += 1;
    }
    println!("End count = {count}");
}

O loop externo tem o rótulo 'counting_up, e ele contará de 0 a 2. O loop interno, sem rótulo, conta regressivamente de 10 a 9. O primeiro break que não especifica rótulo sairá apenas do loop interno. Já a instrução break 'counting_up; sairá do loop externo. Esse código imprime:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
count = 0
remaining = 10
remaining = 9
count = 1
remaining = 10
remaining = 9
count = 2
remaining = 10
End count = 2

Simplificando Loops Condicionais com while

Um programa frequentemente precisa avaliar uma condição dentro de um loop. Enquanto a condição for true, o loop continua. Quando a condição deixa de ser true, o programa chama break, interrompendo o loop. É possível implementar esse comportamento usando uma combinação de loop, if, else e break; se quiser, você pode tentar isso agora em um programa. No entanto, esse padrão é tão comum que o Rust oferece uma construção específica para ele, chamada loop while. Na Listagem 3-3, usamos while para fazer o programa repetir três vezes, contando regressivamente, e então, depois do loop, imprimir uma mensagem e sair.

fn main() {
    let mut number = 3;

    while number != 0 {
        println!("{number}!");

        number -= 1;
    }

    println!("LIFTOFF!!!");
}

Essa construção elimina muito do aninhamento que seria necessário se você usasse loop, if, else e break, além de ficar mais clara. Enquanto a condição avaliar para true, o código é executado; caso contrário, o loop é encerrado.

Percorrendo uma Coleção com for

Você pode escolher usar a construção while para iterar sobre os elementos de uma coleção, como um array. Por exemplo, o loop da Listagem 3-4 imprime cada elemento do array a.

fn main() {
    let a = [10, 20, 30, 40, 50];
    let mut index = 0;

    while index < 5 {
        println!("the value is: {}", a[index]);

        index += 1;
    }
}

Aqui, o código percorre os elementos do array em ordem crescente. Ele começa no índice 0 e continua até alcançar o índice final do array, isto é, até que index < 5 deixe de ser true. Executar esse código imprimirá todos os elementos do array:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
the value is: 10
the value is: 20
the value is: 30
the value is: 40
the value is: 50

Os cinco valores do array aparecem no terminal, como esperado. Mesmo que index chegue ao valor 5 em algum momento, o loop para antes de tentar buscar um sexto valor do array.

No entanto, essa abordagem é propensa a erros. Poderíamos fazer o programa entrar em pânico se o valor do índice ou a condição do teste estivesse errada. Por exemplo, se você alterasse a definição do array a para ter quatro elementos, mas esquecesse de atualizar a condição para while index < 4, o código entraria em pânico. Ela também é mais lenta, porque o compilador insere código de tempo de execução para verificar a cada iteração se o índice está dentro dos limites do array.

Como alternativa mais concisa, você pode usar um loop for e executar algum código para cada item de uma coleção. Um loop for tem a aparência do código na Listagem 3-5.

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }
}

Quando executarmos esse código, veremos a mesma saída da Listagem 3-4. Mais importante: aumentamos a segurança do código e eliminamos a chance de bugs resultantes de passar do fim do array ou de não percorrê-lo por completo e deixar elementos para trás. O código de máquina gerado para loops for também pode ser mais eficiente, porque o índice não precisa ser comparado ao comprimento do array em cada iteração.

Usando o loop for, você não precisaria lembrar de alterar outro trecho de código se mudasse a quantidade de valores no array, como acontecia com o método usado na Listagem 3-4.

A segurança e a concisão dos loops for fazem deles a construção de loop mais usada em Rust. Mesmo em situações em que você quer executar algum código um número específico de vezes, como no exemplo da contagem regressiva feito com um loop while na Listagem 3-3, a maioria dos rustaceanos usaria um loop for. O jeito de fazer isso seria usando um Range, fornecido pela biblioteca padrão, que gera todos os números em sequência a partir de um número inicial e até antes de outro número.

Veja como a contagem regressiva ficaria usando um loop for e outro método que ainda não discutimos, rev, para inverter o intervalo:

Nome do arquivo: src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("LIFTOFF!!!");
}

Esse código fica um pouco melhor, não fica?

Resumo

Você conseguiu! Este foi um capítulo grande: você aprendeu sobre variáveis, tipos de dados escalares e compostos, funções, comentários, expressões if e loops. Para praticar os conceitos discutidos neste capítulo, tente construir programas que façam o seguinte:

• Converter temperaturas entre Fahrenheit e Celsius.
• Gerar o enésimo número de Fibonacci.
• Imprimir a letra da canção natalina “The Twelve Days of Christmas”, aproveitando a repetição da música.

Quando estiver pronto para seguir em frente, vamos falar sobre um conceito do Rust que não existe comumente em outras linguagens de programação: ownership.

Entendendo Ownership

Ownership é o recurso mais característico do Rust e tem implicações profundas em todo o restante da linguagem. É ele que permite ao Rust oferecer garantias de segurança de memória sem precisar de um garbage collector, por isso é importante entender como ownership funciona. Neste capítulo, falaremos sobre ownership e também sobre recursos relacionados: empréstimos, slices e a forma como o Rust organiza dados na memória.

O que é Ownership?

O que é ownership?

Ownership é um conjunto de regras que governa como um programa Rust gerencia a memória. Todo programa precisa gerenciar a forma como usa a memória do computador durante a execução. Algumas linguagens têm garbage collection, que procura regularmente por memória não utilizada enquanto o programa roda; em outras, a pessoa programadora precisa alocar e liberar memória explicitamente. Rust usa uma terceira abordagem: a memória é gerenciada por meio de um sistema de ownership com um conjunto de regras verificadas pelo compilador. Se alguma delas for violada, o programa não compila. Nenhum dos recursos de ownership torna seu programa mais lento em tempo de execução.

Como ownership é um conceito novo para muita gente, leva algum tempo para se acostumar. A boa notícia é que, quanto mais experiência você adquire com Rust e com as regras do sistema de ownership, mais natural se torna escrever código seguro e eficiente. Continue firme!

Ao entender ownership, você terá uma base sólida para compreender os recursos que tornam o Rust único. Neste capítulo, aprenderemos ownership trabalhando com alguns exemplos que se concentram em uma estrutura de dados muito comum: strings.

Regras de Ownership

Primeiro, vamos olhar para as regras de ownership. Tenha essas regras em mente enquanto passamos pelos exemplos que as ilustram:

• Cada valor em Rust tem um dono.
• Só pode haver um dono por vez.
• Quando o dono sai de escopo, o valor é descartado.

Escopo de Variáveis

Agora que já passamos pela sintaxe básica de Rust, não incluiremos todo o boilerplate fn main() { nos exemplos. Então, se você estiver acompanhando, lembre-se de colocar manualmente os exemplos a seguir dentro de uma função main. Assim, eles ficam um pouco mais concisos e podemos focar nos detalhes reais em vez do código repetitivo.

Como primeiro exemplo de ownership, vamos observar o escopo de algumas variáveis. Um escopo é o intervalo dentro de um programa durante o qual um item é válido. Considere a variável a seguir:

#![allow(unused)]
fn main() {
let s = "hello";
}

A variável s se refere a uma string literal, cujo valor está codificado no texto do próprio programa. A variável é válida a partir do ponto em que é declarada até o fim do escopo atual. A Listagem 4-1 mostra um programa com comentários anotando onde a variável s seria válida.

fn main() {
    {                      // s is not valid here, since it's not yet declared
        let s = "hello";   // s is valid from this point forward

        // do stuff with s
    }                      // this scope is now over, and s is no longer valid
}

Em outras palavras, existem dois pontos importantes no tempo aqui:

• Quando s entra no escopo, é válido.
• Ela permanece válida até sair de escopo.

Neste ponto, a relação entre escopos e validade de variáveis é semelhante à de outras linguagens de programação. Agora vamos aprofundar essa ideia introduzindo o tipo String.

O Tipo String

Para ilustrar as regras de ownership, precisamos de um tipo de dado mais complexo do que aqueles que cobrimos na seção “Tipos de Dados” do Capítulo 3. Os tipos vistos até agora têm tamanho conhecido, podem ser armazenados na pilha e removidos dela quando o escopo termina, e podem ser copiados de maneira rápida e trivial para criar uma nova instância independente quando outra parte do código precisar usar o mesmo valor em outro escopo. Mas agora queremos olhar para dados armazenados no heap e explorar como o Rust sabe quando deve limpá-los, e o tipo String é um ótimo exemplo.

Vamos nos concentrar nas partes de String relacionadas a ownership. Esses mesmos aspectos também se aplicam a outros tipos de dados complexos, sejam eles fornecidos pela biblioteca padrão ou criados por você. Falaremos dos aspectos de String que não envolvem ownership no Capítulo 8.

Já vimos literais de string, nas quais o valor da string fica codificado no programa. Literais de string são convenientes, mas não servem para toda situação em que podemos querer usar texto. Uma razão é que elas são imutáveis. Outra é que nem todo valor de string pode ser conhecido quando escrevemos o código: e se quisermos, por exemplo, ler a entrada do usuário e armazená-la? Para esse tipo de situação, Rust oferece o tipo String. Esse tipo gerencia dados alocados no heap e, por isso, consegue armazenar uma quantidade de texto desconhecida em tempo de compilação. Podemos criar um String a partir de uma string literal usando a função from:

#![allow(unused)]
fn main() {
let s = String::from("hello");
}

O operador de dois pontos duplos :: nos permite associar essa função from ao tipo String, em vez de usar algum nome como string_from. Falaremos mais sobre essa sintaxe na seção “Métodos” do Capítulo 5 e, quando tratarmos de namespace com módulos, em “Caminhos para Referenciar um Item na Árvore de Módulos” no Capítulo 7.

Esse tipo de string pode ser mutado:

fn main() {
    let mut s = String::from("hello");

    s.push_str(", world!"); // push_str() appends a literal to a String

    println!("{s}"); // this will print `hello, world!`
}

Então, qual é a diferença aqui? Por que String pode sofrer mutação, mas literais não? A diferença está na forma como esses dois tipos lidam com a memória.

Memória e Alocação

No caso de uma string literal, conhecemos o conteúdo em tempo de compilação, e por isso o texto é gravado diretamente no executável final. É isso que torna literais de string rápidas e eficientes. Mas essas propriedades vêm justamente da imutabilidade da string literal. Infelizmente, não podemos colocar um bloco de memória no binário para cada pedaço de texto cujo tamanho é desconhecido em tempo de compilação e que pode mudar enquanto o programa roda.

Com o tipo String, para suportar um trecho de texto mutável e que possa crescer, precisamos alocar no heap uma quantidade de memória desconhecida em tempo de compilação para armazenar o conteúdo. Isso significa:

• A memória precisa ser solicitada ao alocador em tempo de execução.
• Precisamos de uma forma de devolver essa memória ao alocador quando terminarmos de usar nossa String.

Essa primeira parte é feita por nós: quando chamamos String::from, a implementação solicita a memória necessária. Isso é praticamente universal em linguagens de programação.

No entanto, a segunda parte é diferente. Em linguagens com um garbage collector (GC), o GC acompanha e limpa a memória que não está mais em uso, e não precisamos pensar nisso. Na maioria das linguagens sem GC, é nossa responsabilidade identificar quando a memória deixou de ser usada e chamar código para liberá-la explicitamente, assim como fizemos para solicitá-la. Fazer isso corretamente foi historicamente um problema difícil de programação. Se esquecermos, desperdiçaremos memória. Se fizermos isso cedo demais, teremos uma variável inválida. Se fizermos isso duas vezes, também é um bug. Precisamos emparelhar exatamente um allocate com exatamente um free.

O Rust segue um caminho diferente: a memória é devolvida automaticamente assim que a variável que a possui sai de escopo. Esta é uma versão do nosso exemplo de escopo da Listagem 4-1 usando uma String em vez de uma string literal:

fn main() {
    {
        let s = String::from("hello"); // s is valid from this point forward

        // do stuff with s
    }                                  // this scope is now over, and s is no
                                       // longer valid
}

Existe um ponto natural em que podemos devolver ao alocador a memória da qual nossa String precisa: quando s sai de escopo. Quando uma variável sai de escopo, o Rust chama uma função especial para nós. Essa função se chama drop, e é nela que o autor de String pode colocar o código que devolve a memória. O Rust chama drop automaticamente ao encontrar a chave de fechamento.

Nota: em C++, esse padrão de desalocar recursos ao final da vida útil de um item às vezes é chamado de Resource Acquisition Is Initialization (RAII). A função drop do Rust será familiar para você se já usou padrões RAII.

Esse padrão tem um impacto profundo na forma como código Rust é escrito. Ele pode parecer simples agora, mas o comportamento do código pode ser inesperado em situações mais complicadas, quando queremos que múltiplas variáveis usem os dados que alocamos no heap. Vamos explorar algumas dessas situações agora.

Variáveis e Dados Interagindo com move

Múltiplas variáveis podem interagir com os mesmos dados de maneiras diferentes no Rust. A Listagem 4-2 mostra um exemplo usando um inteiro.

fn main() {
    let x = 5;
    let y = x;
}

Provavelmente conseguimos adivinhar o que isso faz: “Associe o valor 5 a x; depois, faça uma cópia do valor em x e associe essa cópia a y.” Agora temos duas variáveis, x e y, e ambas são iguais a 5. É exatamente isso que está acontecendo, porque inteiros são valores simples com tamanho fixo e conhecido, e esses dois valores 5 são empilhados na pilha.

Agora vamos dar uma olhada na versão String:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;
}

Isso parece muito semelhante, então podemos supor que funcione do mesmo jeito: isto é, que a segunda linha faria uma cópia do valor em s1 e a associaria a s2. Mas não é bem isso que acontece.

Dê uma olhada na Figura 4-1 para ver o que está acontecendo “por baixo dos panos” com String. Uma String é composta de três partes, mostradas à esquerda: um ponteiro para a memória que contém o conteúdo da string, um comprimento e uma capacidade. Esse conjunto de dados é armazenado na pilha. À direita está a memória no heap que contém o conteúdo.

Figura 4-1: A representação na memória de um String mantendo o valor "hello" vinculado a s1

O comprimento é a quantidade de memória, em bytes, que o conteúdo de String está usando no momento. A capacidade é a quantidade total de memória, em bytes, que a String recebeu do alocador. A diferença entre comprimento e capacidade é importante, mas não neste contexto, então por enquanto podemos ignorar a capacidade.

Quando atribuímos s1 a s2, os dados de String são copiados, o que significa que copiamos o ponteiro, o comprimento e a capacidade que estão na pilha. Não copiamos os dados no heap para os quais o ponteiro aponta. Em outras palavras, a representação na memória fica como na Figura 4-2.

Figura 4-2: A representação na memória da variável s2 que possui uma cópia do ponteiro, comprimento e capacidade de s1

A representação não se parece com a Figura 4-3, que mostra como a memória ficaria se o Rust também copiasse os dados do heap. Se o Rust fizesse isso, a operação s2 = s1 poderia ser muito cara em tempo de execução caso os dados no heap fossem grandes.

Figura 4-3: Outra possibilidade para o que s2 = s1 poderia fazer se o Rust também copiasse os dados do heap

Anteriormente, dissemos que, quando uma variável sai de escopo, o Rust chama automaticamente a função drop e limpa a memória no heap daquela variável. Mas a Figura 4-2 mostra os dois ponteiros de dados apontando para o mesmo local. Isso é um problema: quando s2 e s1 saírem de escopo, ambas tentarão liberar a mesma memória. Isso é conhecido como erro de double free e é um dos bugs de segurança de memória que mencionamos antes. Liberar memória duas vezes pode levar à corrupção de memória, o que potencialmente abre espaço para vulnerabilidades de segurança.

Para garantir a segurança de memória, depois da linha let s2 = s1;, o Rust considera s1 como não mais válida. Portanto, o Rust não precisa liberar nada quando s1 sair de escopo. Veja o que acontece quando você tenta usar s1 depois que s2 é criada; isso não funciona:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;

    println!("{s1}, world!");
}

Você receberá um erro como este porque o Rust impede que você use a referência invalidada:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:16
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, world!");
  |                ^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

For more information about this error, try `rustc --explain E0382`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Se você já ouviu os termos cópia superficial e cópia profunda em outras linguagens, provavelmente a ideia de copiar ponteiro, comprimento e capacidade sem copiar os dados parece uma cópia superficial. Mas, como Rust também invalida a primeira variável, isso não recebe o nome de cópia superficial, e sim de move. Neste exemplo, diríamos que s1 foi movido para s2. O que realmente acontece é mostrado na Figura 4-4.

Figura 4-4: A representação na memória após s1 ter sido invalidada

Isso resolve nosso problema! Com apenas s2 válida, quando ela sair de escopo, sozinha liberará a memória, e pronto.

Além disso, há uma escolha de design implícita aqui: o Rust nunca cria automaticamente cópias “profundas” dos seus dados. Portanto, qualquer cópia automática pode ser considerada barata em termos de desempenho em tempo de execução.

Escopo e Atribuição

O oposto também vale para a relação entre escopo, ownership e a liberação de memória por meio da função drop. Quando você atribui um valor totalmente novo a uma variável existente, o Rust chama drop e libera imediatamente a memória do valor original. Considere este código, por exemplo:

fn main() {
    let mut s = String::from("hello");
    s = String::from("ahoy");

    println!("{s}, world!");
}

Inicialmente declaramos uma variável s e a associamos a uma String com o valor "hello". Em seguida, criamos imediatamente uma nova String com o valor "ahoy" e a atribuímos a s. Nesse ponto, nada mais se refere ao valor original no heap. A Figura 4-5 ilustra os dados da pilha e do heap nesse momento:

Figura 4-5: A representação na memória depois que o valor inicial foi completamente substituído

A string original sai imediatamente de escopo. O Rust executará drop sobre ela, e sua memória será liberada imediatamente. Quando imprimirmos o valor no fim, ele será "ahoy, world!".

Variáveis e Dados Interagindo com clone

Se quisermos copiar profundamente os dados no heap de uma String, e não apenas os dados na pilha, podemos usar um método comum chamado clone. Falaremos sobre a sintaxe de métodos no Capítulo 5, mas, como esse é um recurso comum em muitas linguagens de programação, é provável que você já os tenha visto antes.

Aqui está um exemplo do método clone em ação:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();

    println!("s1 = {s1}, s2 = {s2}");
}

Isso funciona muito bem e produz explicitamente o comportamento mostrado na Figura 4-3, em que os dados no heap de fato são copiados.

Quando você vê uma chamada para clone, sabe que algum código arbitrário está sendo executado e que ele pode ser caro. É um indicador visual de que algo diferente está acontecendo.

Dados Somente de Pilha: Copy

Há outro detalhe sobre o qual ainda não falamos. Este código usando inteiros, parte do qual foi mostrado na Listagem 4-2, funciona e é válido:

fn main() {
    let x = 5;
    let y = x;

    println!("x = {x}, y = {y}");
}

Mas esse código parece contradizer o que acabamos de aprender: não temos uma chamada para clone, mas x ainda é válido e não foi movido para y.

A razão é que tipos como números inteiros, que têm um tamanho conhecido em tempo de compilação, são armazenados inteiramente na pilha; por isso, copiar seus valores é rápido. Isso significa que não há motivo para impedir que x continue válido depois que criamos a variável y. Em outras palavras, aqui não há diferença entre cópia profunda e cópia superficial, então chamar clone não faria nada diferente da cópia superficial usual, e podemos omiti-lo.

O Rust tem uma anotação especial chamada trait Copy que podemos usar em tipos armazenados na pilha, como os inteiros. Falaremos mais sobre traits no Capítulo 10. Se um tipo implementa a trait Copy, as variáveis que o usam não são movidas; em vez disso, são copiadas de forma simples, continuando válidas após a atribuição a outra variável.

O Rust não nos permitirá anotar um tipo com Copy se esse tipo, ou qualquer uma de suas partes, implementar a trait Drop. Se esse tipo precisar que algo especial aconteça quando o valor sair de escopo e adicionarmos a anotação Copy a esse tipo, receberemos um erro em tempo de compilação. Para saber como adicionar a anotação Copy ao seu tipo para implementar essa trait, consulte “Derivable Traits” no Apêndice C.

Então, quais tipos implementam a trait Copy? Você pode verificar a documentação do tipo em questão para ter certeza, mas, como regra geral, qualquer grupo de valores escalares simples pode implementar Copy, e nada que exija alocação ou represente algum tipo de recurso pode implementar Copy. Estes são alguns dos tipos que implementam Copy:

• Todos os tipos inteiros, como u32.
• O tipo booleano, bool, com valores true e false.
• Todos os tipos de ponto flutuante, como f64.
• O tipo de caractere, char.
• Tuplas, se contiverem apenas tipos que também implementem Copy. Por exemplo, (i32, i32) implementa Copy, mas (i32, String) não.

Ownership e Funções

A mecânica de passar um valor para uma função é semelhante à de atribuí-lo a uma variável. Passar uma variável para uma função move ou copia esse valor, assim como acontece em uma atribuição. A Listagem 4-3 traz um exemplo com algumas anotações mostrando onde as variáveis entram e saem de escopo.

fn main() {
    let s = String::from("hello");  // s comes into scope

    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope

    makes_copy(x);                  // Because i32 implements the Copy trait,
                                    // x does NOT move into the function,
                                    // so it's okay to use x afterward.

} // Here, x goes out of scope, then s. However, because s's value was moved,
  // nothing special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{some_string}");
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{some_integer}");
} // Here, some_integer goes out of scope. Nothing special happens.

Se tentássemos usar s após a chamada para takes_ownership, Rust geraria um erro em tempo de compilação. Essas verificações estáticas nos protegem contra erros. Tente adicionar código em main que use s e x para ver onde você pode usá-los e onde as regras de ownership impedem isso.

Valores de retorno e escopo

A devolução de valores também pode transferir ownership. A Listagem 4-4 mostra um exemplo de função que retorna algum valor, com anotações semelhantes às da Listagem 4-3.

fn main() {
    let s1 = gives_ownership();        // gives_ownership moves its return
                                       // value into s1

    let s2 = String::from("hello");    // s2 comes into scope

    let s3 = takes_and_gives_back(s2); // s2 is moved into
                                       // takes_and_gives_back, which also
                                       // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
  // happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {       // gives_ownership will move its
                                       // return value into the function
                                       // that calls it

    let some_string = String::from("yours"); // some_string comes into scope

    some_string                        // some_string is returned and
                                       // moves out to the calling
                                       // function
}

// This function takes a String and returns a String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string comes into
    // scope

    a_string  // a_string is returned and moves out to the calling function
}

O ownership de uma variável sempre segue o mesmo padrão: atribuir um valor a outra variável o move. Quando uma variável que inclui dados no heap sai de escopo, o valor é limpo por drop, a menos que o ownership desses dados tenha sido movido para outra variável.

Embora isso funcione, assumir ownership e depois devolvê-lo em toda função é um pouco tedioso. E se quisermos deixar uma função usar um valor, mas sem assumir seu ownership? É bem inconveniente que tudo o que passamos também precise ser devolvido caso queiramos reutilizar o valor depois, além de quaisquer dados resultantes do corpo da função que também desejemos retornar.

O Rust nos permite retornar vários valores usando uma tupla, como mostrado na Listagem 4-5.

fn main() {
    let s1 = String::from("hello");

    let (s2, len) = calculate_length(s1);

    println!("The length of '{s2}' is {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String

    (s, length)
}

Mas isso é muita cerimônia e trabalho para um conceito que deveria ser comum. Felizmente, o Rust tem um recurso para usar um valor sem transferir ownership: referências.

Referências e Empréstimos

Referências e Empréstimos

O problema com o código com a tupla da Listagem 4-5 é que precisamos retornar a String para a função chamadora para que ainda possamos usá-la depois da chamada para calculate_length, porque a String foi movida para dentro de calculate_length. Em vez disso, podemos fornecer uma referência ao valor String. Uma referência é parecida com um ponteiro no sentido de que é um endereço que podemos seguir para acessar os dados armazenados naquele local; esses dados pertencem a alguma outra variável. Diferentemente de um ponteiro, uma referência tem a garantia de apontar para um valor válido de um tipo específico durante toda a vida dessa referência.

Veja como você definiria e usaria uma função calculate_length que recebe como parâmetro uma referência a um objeto, em vez de assumir o ownership do valor:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

Primeiro, repare que todo o código envolvendo a tupla na declaração da variável e no valor de retorno da função desapareceu. Segundo, observe que passamos &s1 para calculate_length e que, na definição da função, recebemos &String em vez de String. Esses e comerciais (&) representam referências, e elas permitem que você se refira a algum valor sem assumir seu ownership. A Figura 4-6 ilustra esse conceito.

Figura 4-6: Um diagrama de &String s apontando para String s1

Observação: o oposto de referenciar usando & é desreferenciar, o que é feito com o operador de desreferência, *. Veremos alguns usos do operador de desreferência no Capítulo 8 e discutiremos os detalhes de desreferenciação no Capítulo 15.

Vamos observar mais de perto a chamada de função aqui:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

A sintaxe &s1 nos permite criar uma referência que se refere ao valor de s1, mas não é dona dele. Como a referência não possui ownership, o valor para o qual ela aponta não será desalocado quando a referência deixar de ser usada.

Da mesma forma, a assinatura da função usa & para indicar que o tipo do parâmetro s é uma referência. Vamos adicionar algumas anotações explicativas:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because s does not have ownership of what
  // it refers to, the String is not dropped.

O escopo em que a variável s é válida é igual ao escopo de qualquer parâmetro de função, mas o valor apontado pela referência não é desalocado quando s deixa de ser usado, porque s não tem ownership. Quando funções recebem referências como parâmetros em vez dos próprios valores, não precisamos devolver esses valores para transferir o ownership de volta, porque nunca o tivemos.

Chamamos o ato de criar uma referência de borrowing ou empréstimo. Como na vida real: se uma pessoa é dona de algo, você pode pegar emprestado dela. Quando terminar, precisa devolver. Você não é o dono.

Então, o que acontece se tentarmos modificar algo que estamos pegando emprestado? Experimente o código da Listagem 4-6. Aviso de antemão: não funciona!

fn main() {
    let s = String::from("hello");

    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

Este é o erro:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
8 |     some_string.push_str(", world");
  |     ^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn change(some_string: &mut String) {
  |                         +++

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Assim como variáveis são imutáveis por padrão, referências também são. Não temos permissão para modificar algo para o qual temos apenas uma referência.

Referências Mutáveis

Podemos corrigir o código da Listagem 4-6 para permitir modificar um valor emprestado com apenas alguns pequenos ajustes, usando, em vez disso, uma referência mutável:

fn main() {
    let mut s = String::from("hello");

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

Primeiro, mudamos s para mut. Depois, criamos uma referência mutável com &mut s no ponto em que chamamos a função change e atualizamos a assinatura da função para aceitar uma referência mutável com some_string: &mut String. Isso deixa muito claro que a função change vai mutar o valor que tomou emprestado.

Referências mutáveis têm uma grande restrição: se você tem uma referência mutável para um valor, não pode ter nenhuma outra referência para esse mesmo valor. Este código, que tenta criar duas referências mutáveis para s, falha:

fn main() {
    let mut s = String::from("hello");

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{r1}, {r2}");
}

Este é o erro:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{r1}, {r2}");
  |                -- first borrow later used here

For more information about this error, try `rustc --explain E0499`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Esse erro diz que o código é inválido porque não podemos pegar s emprestada como mutável mais de uma vez ao mesmo tempo. O primeiro empréstimo mutável está em r1 e precisa durar até ser usado no println!, mas, entre a criação dessa referência mutável e seu uso, tentamos criar outra referência mutável em r2 que empresta os mesmos dados de r1.

A restrição que impede múltiplas referências mutáveis aos mesmos dados ao mesmo tempo permite mutação, mas de uma forma muito controlada. É algo com que novos rustaceanos costumam ter dificuldade, porque a maioria das linguagens permite mutar quando você quiser. A vantagem dessa restrição é que o Rust consegue evitar data races em tempo de compilação. Uma data race é parecida com uma condição de corrida e acontece quando estes três comportamentos ocorrem:

• Dois ou mais ponteiros acessam os mesmos dados ao mesmo tempo.
• Pelo menos um desses ponteiros está sendo usado para escrever nos dados.
• Não há nenhum mecanismo de sincronização sendo usado para coordenar o acesso.

Data races causam comportamento indefinido e podem ser difíceis de diagnosticar e corrigir quando você está tentando rastreá-las em tempo de execução; o Rust evita esse problema recusando-se a compilar código com data races.

Como sempre, podemos usar chaves para criar um novo escopo, permitindo múltiplas referências mutáveis, desde que não sejam simultâneas:

fn main() {
    let mut s = String::from("hello");

    {
        let r1 = &mut s;
    } // r1 goes out of scope here, so we can make a new reference with no problems.

    let r2 = &mut s;
}

O Rust impõe uma regra semelhante para combinar referências mutáveis e imutáveis. Este código gera um erro:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    let r3 = &mut s; // BIG PROBLEM

    println!("{r1}, {r2}, and {r3}");
}

Este é o erro:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no problem
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no problem
6 |     let r3 = &mut s; // BIG PROBLEM
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{r1}, {r2}, and {r3}");
  |                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Também não podemos ter uma referência mutável enquanto temos uma referência imutável ao mesmo valor.

Quem está usando uma referência imutável não espera que o valor mude de repente enquanto a referência ainda está em uso. No entanto, múltiplas referências imutáveis são permitidas, porque ninguém que esteja apenas lendo os dados consegue afetar a leitura dos demais.

Observe que o escopo de uma referência começa no ponto em que ela é introduzida e continua até a última vez em que essa referência é usada. Por exemplo, este código compila porque o último uso das referências imutáveis está no println!, antes da introdução da referência mutável:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{r1} and {r2}");
    // Variables r1 and r2 will not be used after this point.

    let r3 = &mut s; // no problem
    println!("{r3}");
}

Os escopos das referências imutáveis r1 e r2 terminam depois do println!, onde são usadas pela última vez, o que acontece antes da criação da referência mutável r3. Esses escopos não se sobrepõem, então esse código é permitido: o compilador consegue perceber que a referência já não está mais sendo usada em um ponto anterior ao fim do escopo.

Mesmo que erros de borrowing possam ser frustrantes às vezes, lembre-se de que é o compilador do Rust apontando um possível bug cedo, em tempo de compilação em vez de em tempo de execução, e mostrando exatamente onde está o problema. Assim, você não precisa sair procurando por que seus dados não são aquilo que você achava que fossem.

Referências Pendentes

Em linguagens com ponteiros, é fácil criar por engano um dangling pointer ou ponteiro pendente, isto é, um ponteiro que faz referência a um local da memória que talvez já tenha sido entregue a outra pessoa, ao liberar alguma memória enquanto ainda se preserva um ponteiro para ela. Em Rust, ao contrário, o compilador garante que referências jamais serão pendentes: se você tem uma referência para algum dado, o compilador garante que o dado não sairá de escopo antes da referência.

Vamos tentar criar uma referência pendente para ver como o Rust evita isso com um erro de compilação:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String {
    let s = String::from("hello");

    &s
}

Este é o erro:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &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: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn dangle() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Essa mensagem de erro faz referência a um recurso que ainda não cobrimos: lifetimes. Discutiremos lifetimes em detalhe no Capítulo 10. Mas, se você ignorar as partes sobre lifetimes, a mensagem contém a chave para entender por que esse código é um problema:

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

Vamos observar com mais cuidado o que está acontecendo em cada etapa do código de dangle:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope and is dropped, so its memory goes away.
  // Danger!

Como s é criada dentro de dangle, quando o código de dangle termina, s é desalocada. Mas tentamos retornar uma referência a ela. Isso significa que a referência apontaria para uma String inválida. Nada bom! O Rust não nos deixa fazer isso.

A solução aqui é retornar a String diretamente:

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

Isso funciona sem problemas. O ownership é movido para fora, e nada é desalocado.

As Regras das Referências

Vamos recapitular o que discutimos sobre referências:

• Em qualquer momento, você pode ter ou uma referência mutável ou qualquer quantidade de referências imutáveis.
• Referências sempre precisam ser válidas.

A seguir, veremos um tipo diferente de referência: fatias.

O Tipo Slice

O Tipo Slice

Slices permitem referenciar uma sequência contígua de elementos em uma coleção. Um slice é um tipo de referência e, portanto, não tem ownership.

Aqui está um pequeno problema de programação: escreva uma função que receba uma string composta por palavras separadas por espaços e retorne a primeira palavra que encontrar nessa string. Se a função não encontrar um espaço na string, então a string inteira deve ser considerada uma única palavra e, nesse caso, a string inteira deve ser retornada.

Observação: para fins de introdução a slices, nesta seção vamos assumir apenas ASCII; uma discussão mais completa sobre tratamento de UTF-8 aparece na seção “Armazenando Texto Codificado em UTF-8 com Strings” do Capítulo 8.

Vamos ver como escreveríamos a assinatura dessa função sem usar slices, para entender o problema que eles resolvem:

fn first_word(s: &String) -> ?

A função first_word recebe um parâmetro do tipo &String. Não precisamos de ownership, então isso está ótimo. Em Rust idiomático, funções não assumem ownership de seus argumentos a menos que precisem, e as razões para isso vão ficar mais claras conforme avançarmos. Mas o que deveríamos retornar? Na verdade, não temos uma forma de falar sobre parte de uma string. No entanto, podemos retornar o índice do fim da palavra, indicado por um espaço. Vamos tentar isso, como mostrado na Listagem 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Como precisamos percorrer a String elemento por elemento e verificar se um byte corresponde a um espaço, vamos converter nossa String em um array de bytes usando o método as_bytes.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Em seguida, criamos um iterador sobre esse array de bytes usando o método iter:

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Discutiremos iteradores em mais detalhes no Capítulo 13. Por enquanto, saiba que iter é um método que retorna cada elemento de uma coleção, e que enumerate envolve o resultado de iter e retorna cada elemento como parte de uma tupla. O primeiro elemento da tupla retornada por enumerate é o índice, e o segundo é uma referência ao elemento. Isso é um pouco mais conveniente do que calcular o índice por conta própria.

Como o método enumerate retorna uma tupla, podemos usar padrões para desestruturar essa tupla. Vamos falar mais sobre padrões no Capítulo 6. No loop for, especificamos um padrão que usa i para o índice na tupla e &item para o byte individual da tupla. Como recebemos uma referência ao elemento de .iter().enumerate(), usamos & no padrão.

Dentro do loop for, procuramos o byte que representa o espaço usando a sintaxe de literal de byte. Se encontrarmos um espaço, retornamos sua posição. Caso contrário, retornamos o comprimento da string usando s.len().

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Agora temos uma forma de descobrir o índice do fim da primeira palavra da string, mas há um problema. Estamos retornando um usize por conta própria, mas ele só é um número significativo no contexto da &String. Em outras palavras, como ele é um valor separado da String, não há garantia de que continuará válido no futuro. Considere o programa da Listagem 4-8, que usa a função first_word da Listagem 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but s no longer has any content that we
    // could meaningfully use with the value 5, so word is now totally invalid!
}

Esse programa compila sem erro algum e também continuaria compilando se usássemos word depois da chamada a s.clear(). Como word não está ligado ao estado de s, ele ainda contém o valor 5. Poderíamos usar esse valor 5 junto com a variável s para tentar extrair dela a primeira palavra, mas isso seria um bug, porque o conteúdo de s mudou desde que salvamos 5 em word.

Ter de se preocupar com o índice em word ficando fora de sincronia com os dados em s é tedioso e propenso a erros! Gerenciar esses índices fica ainda mais frágil se escrevermos uma função second_word. A assinatura dela teria de ser algo assim:

fn second_word(s: &String) -> (usize, usize) {

Agora estamos acompanhando um índice de início e um de fim, e temos ainda mais valores calculados a partir de dados em um estado específico, mas que não estão ligados a esse estado de forma alguma. Temos três variáveis soltas e sem relação direta, que precisam permanecer sincronizadas.

Felizmente, o Rust tem uma solução para esse problema: string slices.

String Slices

Um string slice é uma referência a uma sequência contígua de elementos de uma String, e ele se parece com isto:

fn main() {
    let s = String::from("hello world");

    let hello = &s[0..5];
    let world = &s[6..11];
}

Em vez de ser uma referência para a String inteira, hello é uma referência para uma parte da String, especificada pelo trecho adicional [0..5]. Criamos slices usando um intervalo entre colchetes, especificando [starting_index..ending_index], em que starting_index é a primeira posição do slice e ending_index é uma posição além da última. Internamente, a estrutura de dados do slice armazena a posição inicial e o comprimento do slice, que corresponde a ending_index menos starting_index. Assim, no caso de let world = &s[6..11];, world seria um slice contendo um ponteiro para o byte no índice 6 de s com um valor de comprimento igual a 5.

A Figura 4-7 mostra isso em um diagrama.

Figura 4-7: Um string slice referindo-se a uma parte de String

Com a sintaxe de intervalo .. do Rust, se você quiser começar do índice 0, pode omitir o valor antes dos dois pontos. Em outras palavras, estes dois trechos são equivalentes:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let slice = &s[0..2];
let slice = &s[..2];
}

Da mesma forma, se o seu slice incluir o último byte da String, você pode omitir o número final. Isso significa que estes trechos são equivalentes:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

Você também pode omitir ambos os valores para pegar um slice da string inteira. Logo, estes trechos também são equivalentes:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

Observação: os índices de intervalo de string slices precisam estar em limites válidos de caracteres UTF-8. Se você tentar criar um string slice no meio de um caractere multibyte, seu programa será encerrado com erro.

Com todas essas informações em mente, vamos reescrever first_word para retornar um slice. O tipo que representa um string slice é escrito como &str:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

Obtemos o índice do fim da palavra da mesma forma que fizemos na Listagem 4-7, procurando a primeira ocorrência de um espaço. Quando encontramos um espaço, retornamos um string slice usando o início da string e o índice do espaço como índices inicial e final.

Agora, quando chamamos first_word, recebemos de volta um único valor ligado aos dados subjacentes. O valor é composto por uma referência ao ponto inicial do slice e pelo número de elementos do slice.

Retornar um slice também funcionaria para uma função second_word:

fn second_word(s: &String) -> &str {

Agora temos uma API simples e muito mais difícil de usar incorretamente, porque o compilador garante que as referências para dentro da String continuem válidas. Lembra do bug no programa da Listagem 4-8, quando obtivemos o índice do fim da primeira palavra, mas depois limpamos a string e, com isso, esse índice ficou inválido? Aquele código estava logicamente incorreto, mas não mostrava nenhum erro imediatamente. Os problemas só apareceriam depois, se continuássemos tentando usar o índice da primeira palavra com uma string já esvaziada. Slices tornam esse bug impossível e nos avisam muito mais cedo de que há um problema no código. Usar a versão com slice de first_word vai gerar um erro de compilação:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

Este é o erro do compilador:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                   ---- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Lembre-se, pelas regras de borrowing, que se temos uma referência imutável para alguma coisa, também não podemos pegar uma referência mutável para essa mesma coisa. Como clear precisa truncar a String, ele precisa obter uma referência mutável. O println! após a chamada a clear usa a referência em word, então a referência imutável ainda precisa estar ativa naquele ponto. O Rust proíbe que a referência mutável em clear e a referência imutável em word existam ao mesmo tempo, e a compilação falha. O Rust não apenas tornou nossa API mais fácil de usar como também eliminou toda uma classe de erros em tempo de compilação!

Literais de String como Slices

Lembre-se de que falamos sobre literais de string serem armazenados dentro do binário. Agora que sabemos sobre slices, conseguimos entender corretamente os literais de string:

#![allow(unused)]
fn main() {
let s = "Hello, world!";
}

O tipo de s aqui é &str: é um slice apontando para aquele ponto específico do binário. Essa é também a razão pela qual literais de string são imutáveis: &str é uma referência imutável.

String Slices como Parâmetros

Saber que você pode obter slices de literais e de valores String nos leva a mais uma melhoria em first_word, que é sua assinatura:

fn first_word(s: &String) -> &str {

Um rustaceano mais experiente escreveria a assinatura mostrada na Listagem 4-9, porque ela nos permite usar a mesma função tanto com valores &String quanto com valores &str.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Se tivermos um string slice, podemos passá-lo diretamente. Se tivermos uma String, podemos passar um slice da String ou uma referência à String. Essa flexibilidade aproveita coerções de deref, um recurso que veremos na seção “Usando Coerções de Deref em Funções e Métodos” do Capítulo 15.

Definir uma função para receber um string slice em vez de uma referência para String torna nossa API mais geral e mais útil, sem perder nenhuma funcionalidade:

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Outros Slices

String slices, como você pode imaginar, são específicos para strings. Mas existe também um tipo mais geral de slice. Considere este array:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];
}

Assim como podemos querer nos referir a parte de uma string, podemos querer nos referir a parte de um array. Faríamos isso assim:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

Esse slice tem o tipo &[i32]. Ele funciona da mesma maneira que string slices, armazenando uma referência ao primeiro elemento e um comprimento. Você usará esse tipo de slice para vários outros tipos de coleção. Vamos discutir essas coleções em detalhe quando falarmos sobre vetores no Capítulo 8.

Resumo

Os conceitos de ownership, borrowing e slices garantem segurança de memória em programas Rust em tempo de compilação. A linguagem Rust dá a você controle sobre o uso da memória da mesma forma que outras linguagens de programação de sistemas. Mas ter o dono dos dados limpando automaticamente esses dados quando ele sai de escopo significa que você não precisa escrever e depurar código extra para obter esse controle.

Ownership afeta o funcionamento de muitas outras partes do Rust, então vamos falar mais sobre esses conceitos ao longo do restante do livro. Vamos agora para o Capítulo 5 e ver como agrupar pedaços de dados em uma struct.

Usando structs para agrupar dados relacionados

Uma struct, ou estrutura, é um tipo de dado personalizado que permite agrupar e nomear vários valores relacionados que, juntos, formam um conjunto com significado. Se você tem familiaridade com uma linguagem orientada a objetos, uma struct se parece com os atributos de dados de um objeto. Neste capítulo, vamos comparar tuplas e structs para expandir o que você já sabe e mostrar em que situações structs são a melhor forma de agrupar dados.

Vamos ver como definir e instanciar structs. Também discutiremos como definir funções associadas, especialmente o tipo de função associada chamado method, para especificar comportamentos ligados a um tipo de struct. Structs e enums, que serão discutidos no Capítulo 6, são os blocos fundamentais para criar novos tipos no domínio do seu programa e aproveitar ao máximo a verificação de tipos em tempo de compilação que Rust oferece.

Definindo e Instanciando Structs

Definindo e Instanciando Structs

Structs são parecidas com tuplas, discutidas na seção “O Tipo Tupla”, porque ambas armazenam vários valores relacionados. Assim como nas tuplas, os elementos de uma struct podem ter tipos diferentes. A diferença é que, em uma struct, cada pedaço de dado recebe um nome, o que torna mais claro o significado dos valores. Por causa desses nomes, structs são mais flexíveis do que tuplas: você não precisa depender da ordem dos dados para especificar ou acessar os valores de uma instância.

Para definir uma struct, usamos a palavra-chave struct e damos um nome à estrutura inteira. O nome da struct deve descrever o significado dos dados que estão sendo agrupados. Em seguida, entre chaves, definimos os nomes e os tipos dos dados que ela contém, chamados de campos. Por exemplo, a Listagem 5-1 mostra uma struct que armazena informações sobre uma conta de usuário.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

Para usar uma struct depois de defini-la, criamos uma instância dela especificando valores concretos para cada campo. Criamos uma instância escrevendo o nome da struct e, em seguida, chaves contendo pares chave: valor, em que as chaves são os nomes dos campos e os valores são os dados que queremos armazenar neles. Não é necessário especificar os campos na mesma ordem em que eles foram declarados na struct. Em outras palavras, a definição da struct funciona como um modelo geral para o tipo, e as instâncias preenchem esse modelo com dados específicos para criar valores daquele tipo. Por exemplo, podemos declarar um usuário específico como mostra a Listagem 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

Para obter um valor específico de uma struct, usamos notação de ponto. Por exemplo, para acessar o endereço de e-mail desse usuário, usamos user1.email. Se a instância for mutável, podemos alterar um valor usando a notação de ponto e atribuindo um novo valor a um campo específico. A Listagem 5-3 mostra como alterar o valor do campo email de uma instância mutável de User.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

Observe que a instância inteira precisa ser mutável; o Rust não permite marcar apenas alguns campos como mutáveis. Como acontece com qualquer expressão, também podemos construir uma nova instância da struct como a última expressão no corpo de uma função para retorná-la implicitamente.

A Listagem 5-4 mostra uma função build_user que retorna uma instância de User com o e-mail e o nome de usuário fornecidos. O campo active recebe o valor true, e sign_in_count recebe o valor 1.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Faz sentido dar aos parâmetros da função os mesmos nomes dos campos da struct, mas ter de repetir os nomes email e username tanto nos campos quanto nas variáveis pode ficar um pouco cansativo. Se a struct tivesse mais campos, repetir cada nome ficaria ainda mais incômodo. Felizmente, há uma abreviação conveniente!

Usando a Abreviação de Inicialização de Campos

Como os nomes dos parâmetros e os nomes dos campos da struct são exatamente os mesmos na Listagem 5-4, podemos usar a sintaxe field init shorthand para reescrever build_user de forma que ela se comporte exatamente igual, mas sem repetir username e email, como mostra a Listagem 5-5.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Aqui, estamos criando uma nova instância da struct User, que tem um campo chamado email. Queremos atribuir ao campo email o valor contido no parâmetro email da função build_user. Como o campo email e o parâmetro email têm o mesmo nome, só precisamos escrever email em vez de email: email.

Criando Instâncias com a Sintaxe de Atualização de Struct

Muitas vezes é útil criar uma nova instância de uma struct que aproveite a maior parte dos valores de outra instância do mesmo tipo, alterando apenas alguns campos. Podemos fazer isso usando a sintaxe de atualização de struct.

Primeiro, na Listagem 5-6, mostramos como criar uma nova instância de User em user2 do jeito tradicional, sem a sintaxe de atualização. Definimos um novo valor para email, mas reutilizamos os mesmos valores de user1, instância criada na Listagem 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

Usando a sintaxe de atualização de struct, podemos obter o mesmo efeito com menos código, como mostra a Listagem 5-7. A sintaxe .. indica que os campos restantes, não definidos explicitamente, devem receber os mesmos valores que os campos da instância fornecida.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

O código da Listagem 5-7 também cria uma instância em user2 com um valor diferente para email, mas com os mesmos valores de username, active e sign_in_count vindos de user1. O trecho ..user1 precisa vir por último para indicar que quaisquer campos restantes devem receber seus valores dos campos correspondentes em user1, mas podemos escolher explicitamente quantos campos quisermos, em qualquer ordem, independentemente da ordem em que eles foram declarados na struct.

Observe que a sintaxe de atualização de struct usa = como uma atribuição; isso acontece porque ela move os dados, como vimos na seção “Variáveis e Dados Interagindo com Move”. Neste exemplo, não podemos mais usar user1 depois de criar user2, porque a String armazenada no campo username de user1 foi movida para user2. Se tivéssemos dado a user2 novos valores String tanto para email quanto para username, e portanto usássemos de user1 apenas os valores active e sign_in_count, então user1 ainda seria válido depois da criação de user2. Tanto active quanto sign_in_count são tipos que implementam a trait Copy, então o comportamento discutido na seção “Dados Somente de Pilha: Copy” se aplica aqui. Também ainda podemos usar user1.email nesse exemplo, porque o valor desse campo não foi movido para fora de user1.

Criando Tipos Diferentes com Tuple Structs

Rust também oferece suporte a structs que se parecem com tuplas, chamadas tuple structs. Tuple structs têm o significado adicional fornecido pelo nome da struct, mas não têm nomes associados a seus campos; em vez disso, elas armazenam apenas os tipos dos campos. Tuple structs são úteis quando você quer dar um nome à tupla inteira e fazer com que ela seja um tipo diferente de outras tuplas, mas nomear cada campo, como em uma struct comum, seria verboso ou redundante.

Para definir uma tuple struct, começamos com a palavra-chave struct, seguida do nome da struct e então os tipos da tupla. Por exemplo, aqui definimos e usamos duas tuple structs chamadas Color e Point:

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

Observe que os valores black e origin têm tipos diferentes porque são instâncias de tuple structs diferentes. Cada struct que você define é um tipo próprio, mesmo que os campos internos tenham os mesmos tipos. Por exemplo, uma função que recebe um parâmetro do tipo Color não pode receber um Point, embora ambos sejam compostos de três valores i32. Fora isso, instâncias de tuple struct se comportam de forma semelhante às tuplas: você pode desestruturá-las em suas partes individuais e usar . seguido do índice para acessar um valor específico. Diferentemente das tuplas, porém, tuple structs exigem que você use o nome do tipo ao desestruturá-las. Por exemplo, escreveríamos let Point(x, y, z) = origin; para desestruturar os valores de origin em variáveis chamadas x, y e z.

Definindo Structs Unit-Like

Você também pode definir structs que não têm nenhum campo. Elas são chamadas de unit-like structs porque se comportam de maneira semelhante a (), o tipo unit que mencionamos na seção “O Tipo Tupla”. Unit-like structs podem ser úteis quando você precisa implementar uma trait em algum tipo, mas não quer armazenar nenhum dado nesse tipo em si. Vamos discutir traits no Capítulo 10. Aqui está um exemplo de declaração e instanciação de uma unit-like struct chamada AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Para definir AlwaysEqual, usamos a palavra-chave struct, o nome desejado e então um ponto e vírgula. Não precisamos de chaves nem de parênteses! Depois, podemos obter uma instância de AlwaysEqual na variável subject de forma semelhante: usando apenas o nome definido, sem chaves nem parênteses. Imagine que, mais tarde, implementaremos comportamento para esse tipo de forma que toda instância de AlwaysEqual seja sempre igual a qualquer instância de qualquer outro tipo, talvez para ter um resultado conhecido em testes. Não precisaríamos de nenhum dado para implementar esse comportamento. Você verá no Capítulo 10 como definir traits e implementá-las em qualquer tipo, incluindo unit-like structs.

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

Um Programa de Exemplo Usando Structs

Um Exemplo de Programa Usando Structs

Para entender quando pode fazer sentido usar structs, vamos escrever um programa que calcula a área de um retângulo. Começaremos usando variáveis soltas e depois vamos refatorar o programa até chegarmos ao uso de structs.

Vamos criar um novo projeto binário com Cargo chamado rectangles, que receberá a largura e a altura de um retângulo, especificadas em pixels, e calculará sua área. A Listagem 5-8 mostra um pequeno programa com uma forma de fazer exatamente isso em src/main.rs.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

Agora, execute esse programa com cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

Esse código consegue descobrir a área do retângulo chamando a função area com cada dimensão, mas ainda podemos fazer mais para que ele fique claro e legível.

O problema com esse código fica evidente na assinatura de area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

A função area deveria calcular a área de um único retângulo, mas a função que escrevemos recebe dois parâmetros, e em nenhum ponto do programa fica claro que eles estão relacionados. Seria mais legível e mais fácil de manter agrupar largura e altura. Já discutimos uma forma de fazer isso na seção “O Tipo Tupla” do Capítulo 3: usando tuplas.

Refatorando com Tuplas

A Listagem 5-9 mostra outra versão do programa usando tuplas.

fn main() {
    let rect1 = (30, 50);

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

Em certo sentido, esse programa é melhor. As tuplas nos permitem adicionar um pouco de estrutura, e agora estamos passando apenas um argumento. Mas, por outro lado, essa versão é menos clara: tuplas não dão nome aos seus elementos, então precisamos acessar as partes por índice, o que torna o cálculo menos óbvio.

Confundir largura e altura não faria diferença para o cálculo da área, mas, se quisermos desenhar o retângulo na tela, isso passaria a importar! Teríamos de lembrar que width corresponde ao índice 0 da tupla e height ao índice 1. Isso seria ainda mais difícil para outra pessoa descobrir e manter em mente ao usar nosso código. Como não expressamos o significado desses dados no próprio código, fica mais fácil introduzir erros.

Refatorando com Structs

Usamos structs para adicionar significado ao rotular os dados. Podemos transformar a tupla que estamos usando em uma struct com um nome para o todo e nomes para cada parte, como mostra a Listagem 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

Aqui, definimos uma struct chamada Rectangle. Dentro das chaves, definimos os campos width e height, ambos do tipo u32. Depois, em main, criamos uma instância específica de Rectangle com largura 30 e altura 50.

Nossa função area agora é definida com um único parâmetro, que chamamos de rectangle e cujo tipo é um empréstimo imutável de uma instância da struct Rectangle. Como mencionamos no Capítulo 4, queremos tomar emprestada a struct, em vez de assumir seu ownership. Assim, main continua com o ownership e pode seguir usando rect1; é por isso que usamos & tanto na assinatura da função quanto no ponto em que a chamamos.

A função area acessa os campos width e height da instância Rectangle. Observe que acessar campos de uma instância de struct emprestada não move os valores dos campos, e é por isso que você verá com frequência structs sendo emprestadas. Nossa assinatura de area agora expressa exatamente o que queremos dizer: calcular a área de um Rectangle usando seus campos width e height. Isso deixa claro que largura e altura estão relacionadas e dá nomes descritivos aos valores, em vez de usar os índices 0 e 1 de uma tupla. É um ganho real de clareza.

Adicionando Funcionalidade com Traits Derivadas

Seria útil poder imprimir uma instância de Rectangle enquanto estivermos depurando o programa, para enxergar os valores de todos os seus campos. A Listagem 5-11 tenta fazer isso usando a macro println!, como já fizemos em capítulos anteriores. Mas isso não vai funcionar.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1}");
}

Quando compilamos esse código, recebemos um erro com esta mensagem principal:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

A macro println! pode fazer muitos tipos de formatação e, por padrão, as chaves informam ao println! que ele deve usar a formatação conhecida como Display, isto é, uma saída pensada para consumo direto por usuários finais. Os tipos primitivos que vimos até agora implementam Display por padrão, porque existe basicamente uma única forma razoável de mostrar um 1, por exemplo. Mas, com structs, a forma como println! deveria formatar a saída é menos óbvia, porque há várias possibilidades: você quer vírgulas ou não? Quer imprimir as chaves? Todos os campos devem aparecer? Por causa dessa ambiguidade, o Rust não tenta adivinhar o que queremos, e structs não recebem uma implementação padrão de Display para ser usada com println! e o placeholder {}.

Se continuarmos lendo as mensagens de erro, encontraremos esta observação útil:

   |                        |`Rectangle` cannot be formatted with the default formatter
   |                        required by this formatting parameter

Vamos tentar! A chamada da macro println! agora ficará assim: println!("rect1 is {rect1:?}");. Colocar o especificador :? dentro das chaves informa ao println! que queremos usar um formato de saída chamado Debug. A trait Debug nos permite imprimir a struct de uma maneira útil para desenvolvedores, para que possamos inspecionar seu valor enquanto depuramos o código.

Compile o código com essa mudança. Droga! Ainda recebemos um erro:

error[E0277]: `Rectangle` doesn't implement `Debug`

Mas, de novo, o compilador nos dá uma observação útil:

   |                        required by this formatting parameter
   |

O Rust de fato oferece funcionalidade para imprimir informações de depuração, mas precisamos habilitá-la explicitamente para nossa struct. Para isso, adicionamos o atributo externo #[derive(Debug)] logo antes da definição da struct, como mostra a Listagem 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

Agora, quando executarmos o programa, não veremos mais erros e obteremos a seguinte saída:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

Ótimo! Não é a saída mais bonita do mundo, mas ela mostra os valores de todos os campos dessa instância, o que certamente ajuda durante a depuração. Quando temos structs maiores, é útil contar com uma saída um pouco mais fácil de ler; nesses casos, podemos usar {:#?} em vez de {:?} na string de println!. Neste exemplo, usar o estilo {:#?} produz a seguinte saída:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

Outra forma de imprimir um valor usando o formato Debug é com a macro dbg!, que assume o ownership de uma expressão (diferentemente de println!, que recebe uma referência), imprime o arquivo e o número da linha em que a chamada à macro dbg! ocorre, junto com o valor resultante da expressão, e então devolve o ownership desse valor.

Observação: a macro dbg! imprime na saída de erro padrão (stderr), ao contrário de println!, que imprime na saída padrão (stdout). Vamos falar mais sobre stderr e stdout na seção “Redirecionando Erros para a Saída de Erro Padrão” do Capítulo 12.

Aqui está um exemplo em que nos interessa tanto o valor atribuído ao campo width quanto o valor da struct inteira em rect1:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

Podemos colocar dbg! em volta da expressão 30 * scale e, como dbg! devolve o ownership do valor da expressão, o campo width receberá exatamente o mesmo valor que receberia se a chamada a dbg! não estivesse ali. Não queremos que dbg! assuma o ownership de rect1, então usamos uma referência a rect1 na chamada seguinte. A saída desse exemplo é assim:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

Podemos ver que a primeira parte da saída veio da linha 10 de src/main.rs, onde estamos depurando a expressão 30 * scale, e que o valor resultante é 60 (a formatação Debug para inteiros imprime apenas o valor). A chamada a dbg! na linha 14 de src/main.rs imprime o valor de &rect1, que é a struct Rectangle. Essa saída usa a versão mais legível da formatação Debug para o tipo Rectangle. A macro dbg! pode ser realmente útil quando você está tentando entender o que seu código está fazendo.

Além da trait Debug, o Rust fornece várias outras traits que podemos usar com o atributo derive para adicionar comportamentos úteis aos nossos tipos personalizados. Essas traits e seus comportamentos estão listados no Apêndice C. No Capítulo 10, veremos como implementar essas traits com comportamento personalizado e também como criar suas próprias traits. Há ainda muitos outros atributos além de derive; para mais informações, veja a seção “Attributes” da Referência do Rust.

Nossa função area é muito específica: ela calcula apenas a área de retângulos. Seria útil vincular esse comportamento mais de perto à nossa struct Rectangle, já que ele não faz sentido para outros tipos. Vamos ver como continuar refatorando esse código, transformando a função area em um método area definido no tipo Rectangle.

Métodos

Métodos

Métodos são parecidos com funções: nós os declaramos com a palavra-chave fn e um nome, eles podem ter parâmetros e valor de retorno, e contêm algum código que é executado quando o método é chamado. Diferentemente das funções, os métodos são definidos no contexto de uma struct, de um enum ou de um trait object, que veremos respectivamente no Capítulo 6 e no Capítulo 18. Além disso, o primeiro parâmetro de um método é sempre self, que representa a instância da struct sobre a qual o método está sendo chamado.

Sintaxe de Métodos

Vamos mudar a função area, que recebe uma instância de Rectangle como parâmetro, para um método area definido na própria struct Rectangle, como mostra a Listagem 5-13.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

Para definir a função no contexto de Rectangle, começamos um bloco impl (de implementação) para Rectangle. Tudo dentro desse bloco impl ficará associado ao tipo Rectangle. Em seguida, movemos a função area para dentro das chaves do impl e alteramos o primeiro parâmetro, que neste caso é o único, para self na assinatura e em todo o corpo da função. Em main, onde antes chamávamos a função area e passávamos rect1 como argumento, agora podemos usar a sintaxe de métodos para chamar o método area em nossa instância de Rectangle. A sintaxe de métodos vem depois da instância: adicionamos um ponto, o nome do método, parênteses e eventuais argumentos.

Na assinatura de area, usamos &self em vez de rectangle: &Rectangle. &self é, na verdade, uma abreviação de self: &Self. Dentro de um bloco impl, o tipo Self é um alias para o tipo ao qual o bloco impl se refere. Métodos precisam ter um parâmetro chamado self do tipo Self como primeiro parâmetro, então o Rust permite abreviar isso usando apenas o nome self nessa posição. Repare que ainda precisamos usar & antes de self para indicar que esse método toma a instância Self por empréstimo, assim como fizemos em rectangle: &Rectangle. Métodos podem assumir o ownership de self, tomar self por empréstimo imutável, como fizemos aqui, ou tomar self por empréstimo mutável, como fariam com qualquer outro parâmetro.

Escolhemos &self aqui pelo mesmo motivo que usamos &Rectangle na versão em forma de função: não queremos assumir o ownership, apenas ler os dados da struct, sem modificá-los. Se quiséssemos alterar a instância sobre a qual o método foi chamado, usaríamos &mut self como primeiro parâmetro. Métodos que assumem o ownership da instância usando apenas self como primeiro parâmetro são mais raros; essa técnica costuma ser usada quando o método transforma self em outra coisa e você quer impedir que o chamador use a instância original depois da transformação.

A principal razão para usar métodos em vez de funções, além da sintaxe mais natural e do fato de não precisarmos repetir o tipo de self em toda assinatura, é organização. Colocamos tudo o que pode ser feito com uma instância de um tipo em um único bloco impl, em vez de obrigar usuários futuros do código a procurar as capacidades de Rectangle em vários lugares da biblioteca.

Observe que podemos escolher dar a um método o mesmo nome de um dos campos da struct. Por exemplo, podemos definir um método em Rectangle também chamado width:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

Aqui, escolhemos fazer o método width retornar true se o valor do campo width da instância for maior que 0 e false se esse valor for 0. Podemos usar um campo dentro de um método com o mesmo nome para qualquer finalidade. Em main, quando escrevemos rect1.width seguido de parênteses, o Rust sabe que queremos dizer o método width. Quando não usamos parênteses, o Rust sabe que estamos nos referindo ao campo width.

Muitas vezes, embora nem sempre, quando damos a um método o mesmo nome de um campo, queremos que ele apenas devolva o valor armazenado nesse campo e não faça mais nada. Métodos desse tipo são chamados de getters, e o Rust não os implementa automaticamente para campos de struct, como algumas outras linguagens fazem. Getters são úteis porque você pode tornar o campo privado e o método público, permitindo acesso somente leitura a esse campo como parte da API pública do tipo. Vamos discutir o que é público e privado, bem como como marcar um campo ou método dessa forma, no Capítulo 7.

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

Métodos com Mais Parâmetros

Vamos praticar o uso de métodos implementando um segundo método na struct Rectangle. Desta vez, queremos que uma instância de Rectangle receba outra instância de Rectangle e retorne true se o segundo Rectangle puder caber inteiramente dentro de self, isto é, do primeiro Rectangle; caso contrário, deve retornar false. Em outras palavras, depois de definir o método can_hold, queremos poder escrever o programa mostrado na Listagem 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

A saída esperada deve ser parecida com a seguinte, porque as duas dimensões de rect2 são menores que as dimensões de rect1, enquanto rect3 é mais largo que rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Sabemos que queremos definir um método, então ele ficará dentro do bloco impl Rectangle. O nome do método será can_hold, e ele receberá um empréstimo imutável de outro Rectangle como parâmetro. Podemos inferir o tipo desse parâmetro olhando para o código que chama o método: rect1.can_hold(&rect2) passa &rect2, que é um empréstimo imutável de rect2, uma instância de Rectangle. Isso faz sentido porque só precisamos ler rect2, e não escrevê-lo, o que exigiria um empréstimo mutável. Além disso, queremos que main mantenha o ownership de rect2 para poder usá-lo novamente depois de chamar can_hold. O valor de retorno de can_hold será um booleano, e a implementação verificará se a largura e a altura de self são maiores que a largura e a altura do outro Rectangle, respectivamente. Vamos adicionar esse novo método can_hold ao bloco impl da Listagem 5-13, como mostra a Listagem 5-15.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Quando executarmos esse código com a função main da Listagem 5-14, obteremos a saída desejada. Métodos podem receber vários parâmetros depois do parâmetro self, e esses parâmetros funcionam exatamente como parâmetros em funções.

Funções Associadas

Todas as funções definidas dentro de um bloco impl são chamadas de funções associadas porque estão associadas ao tipo nomeado depois de impl. Podemos definir funções associadas que não têm self como primeiro parâmetro e, por isso, não são métodos, porque elas não precisam de uma instância do tipo para trabalhar. Já usamos uma função assim: String::from, definida no tipo String.

Funções associadas que não são métodos costumam ser usadas como construtores, retornando uma nova instância da struct. Frequentemente elas recebem o nome new, mas new não é um nome especial nem faz parte da linguagem. Por exemplo, poderíamos fornecer uma função associada chamada square que recebe um parâmetro de dimensão e o usa tanto como largura quanto como altura, facilitando a criação de um Rectangle quadrado sem precisar repetir o mesmo valor duas vezes:

Nome do arquivo: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

As palavras-chave Self no tipo de retorno e no corpo da função são aliases para o tipo que aparece após a palavra-chave impl, que neste caso é Rectangle.

Para chamar essa função associada, usamos a sintaxe :: com o nome da struct; let sq = Rectangle::square(3); é um exemplo. Essa função fica no namespace da struct: a sintaxe :: é usada tanto para funções associadas quanto para namespaces criados por módulos. Vamos falar sobre módulos no Capítulo 7.

Vários Blocos impl

Cada struct pode ter vários blocos impl. Por exemplo, a Listagem 5-15 é equivalente ao código mostrado na Listagem 5-16, que coloca cada método em seu próprio bloco impl.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Não há motivo para separar esses métodos em vários blocos impl aqui, mas essa é uma sintaxe válida. Veremos um caso em que vários blocos impl são úteis no Capítulo 10, quando discutirmos tipos genéricos e traits.

Resumo

Structs permitem criar tipos personalizados que façam sentido para o seu domínio. Ao usar structs, você consegue manter dados relacionados juntos e dar nome a cada parte, deixando o código mais claro. Em blocos impl, você pode definir funções associadas ao tipo, e métodos são uma forma de função associada que permite especificar o comportamento das instâncias dessas structs.

Mas structs não são a única forma de criar tipos personalizados: vamos agora para o recurso de enums do Rust, adicionando mais uma ferramenta à nossa caixa de ferramentas.

Enums e Pattern Matching

Neste capítulo, veremos enumerações, também chamadas de enums. Enums permitem definir um tipo enumerando suas possíveis variantes. Primeiro, vamos definir e usar um enum para mostrar como ele pode codificar significado junto com dados. Em seguida, exploraremos um enum particularmente útil chamado Option, que expressa que um valor pode ser alguma coisa ou nada. Depois, veremos como o pattern matching na expressão match facilita executar códigos diferentes para valores diferentes de um enum. Por fim, abordaremos como a construção if let é outro idiom conciso e conveniente para lidar com enums no seu código.

Definindo um Enum

Definindo um Enum

Enquanto structs oferecem uma forma de agrupar campos e dados relacionados, como um Rectangle com width e height, enums oferecem uma forma de dizer que um valor pode ser um dentre um conjunto possível de valores. Por exemplo, talvez queiramos dizer que Rectangle é uma dentre várias formas possíveis, junto com Circle e Triangle. Para isso, o Rust nos permite codificar essas possibilidades como um enum.

Vamos analisar uma situação que talvez queiramos expressar em código e ver por que enums são úteis e, nesse caso, mais apropriados do que structs. Digamos que precisamos trabalhar com endereços IP. Atualmente, dois padrões principais são usados para endereços IP: versão quatro e versão seis. Como essas são as únicas possibilidades que nosso programa encontrará, podemos enumerar todas as variantes possíveis, e é daí que vem o nome enumeração.

Qualquer endereço IP pode ser um endereço de versão quatro ou de versão seis, mas não ambos ao mesmo tempo. Essa propriedade dos endereços IP torna a estrutura de dados enum apropriada, porque um valor enum só pode ser uma de suas variantes. Tanto endereços de versão quatro quanto de versão seis ainda são, no fundo, endereços IP, então devem ser tratados como o mesmo tipo quando o código estiver lidando com situações que se aplicam a qualquer tipo de endereço IP.

Podemos expressar esse conceito em código definindo um enum IpAddrKind e listando os tipos possíveis que um endereço IP pode assumir, V4 e V6. Essas são as variantes do enum:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind agora é um tipo de dado personalizado que podemos usar em outras partes do nosso código.

Valores de Enum

Podemos criar instâncias de cada uma das duas variantes de IpAddrKind assim:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Observe que as variantes do enum ficam em um namespace sob seu identificador, e usamos dois pontos duplos para separar as duas partes. Isso é útil porque agora tanto IpAddrKind::V4 quanto IpAddrKind::V6 têm o mesmo tipo: IpAddrKind. Podemos então, por exemplo, definir uma função que aceite qualquer IpAddrKind:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

E podemos chamar essa função com qualquer uma das variantes:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Usar enums tem ainda mais vantagens. Pensando um pouco mais no nosso tipo de endereço IP, neste momento ainda não temos uma forma de armazenar os dados do endereço IP em si; só sabemos qual tipo ele é. Como você acabou de aprender sobre structs no Capítulo 5, talvez fique tentado a resolver esse problema com structs, como mostra a Listagem 6-1.

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

Aqui, definimos uma struct IpAddr com dois campos: um campo kind, do tipo IpAddrKind (o enum que definimos anteriormente), e um campo address, do tipo String. Temos duas instâncias dessa struct. A primeira é home, e ela tem o valor IpAddrKind::V4 como kind, com os dados de endereço associados 127.0.0.1. A segunda instância é loopback. Ela tem a outra variante de IpAddrKind, V6, e o endereço associado ::1. Usamos uma struct para agrupar os valores kind e address, e assim a variante fica associada ao valor.

No entanto, representar esse mesmo conceito usando apenas um enum é mais conciso. Em vez de colocar um enum dentro de uma struct, podemos colocar os dados diretamente em cada variante do enum. Esta nova definição do enum IpAddr diz que tanto a variante V4 quanto a V6 terão um valor String associado:

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

Anexamos os dados diretamente a cada variante do enum, então não há necessidade de uma struct extra. Aqui também fica mais fácil enxergar outro detalhe de como enums funcionam: o nome de cada variante do enum que definimos também se torna uma função que constrói uma instância desse enum. Ou seja, IpAddr::V4() é uma chamada de função que recebe um argumento String e retorna uma instância do tipo IpAddr. Recebemos essa função construtora automaticamente como resultado da definição do enum.

Há outra vantagem em usar um enum em vez de uma struct: cada variante pode ter tipos e quantidades de dados associados diferentes. Endereços IP de versão quatro sempre terão quatro componentes numéricos com valores entre 0 e 255. Se quiséssemos armazenar endereços V4 como quatro valores u8, mas ainda representar endereços V6 como um único valor String, não conseguiríamos fazer isso com uma struct. Enums lidam com esse caso com facilidade:

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

Mostramos várias formas de definir estruturas de dados para armazenar endereços IP de versão quatro e de versão seis. No entanto, armazenar endereços IP e codificar de que tipo eles são é algo tão comum que a biblioteca padrão já tem uma definição que podemos usar! Vamos ver como a biblioteca padrão define IpAddr. Ela tem exatamente o enum e as variantes que definimos e usamos, mas incorpora os dados do endereço dentro das variantes na forma de duas structs diferentes, definidas de maneiras distintas para cada variante:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

Esse código ilustra que você pode colocar qualquer tipo de dado dentro de uma variante de enum: strings, tipos numéricos ou structs, por exemplo. Você pode até incluir outro enum! Além disso, os tipos da biblioteca padrão muitas vezes não são muito mais complicados do que aquilo que você mesmo criaria.

Observe que, embora a biblioteca padrão contenha uma definição para IpAddr, ainda podemos criar e usar nossa própria definição sem conflito, porque não trouxemos a definição da biblioteca padrão para o nosso escopo. Vamos falar mais sobre como trazer tipos para o escopo no Capítulo 7.

Vejamos outro exemplo de enum na Listagem 6-2. Este aqui tem uma variedade bem ampla de tipos embutidos em suas variantes.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

Esse enum tem quatro variantes com tipos diferentes:

• Quit: não tem nenhum dado associado
• Move: tem campos nomeados, como uma struct
• Write: inclui uma única String
• ChangeColor: inclui três valores i32

Definir um enum com variantes como as da Listagem 6-2 é semelhante a definir tipos diferentes de structs, exceto que o enum não usa a palavra-chave struct e que todas as variantes ficam agrupadas sob o tipo Message. As structs a seguir poderiam armazenar os mesmos dados que as variantes do enum anterior armazenam:

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

Mas, se usássemos structs diferentes, cada uma com seu próprio tipo, não conseguiríamos definir com a mesma facilidade uma função que aceitasse qualquer um desses tipos de mensagem, como conseguimos com o enum Message definido na Listagem 6-2, que é um único tipo.

Há mais uma semelhança entre enums e structs: assim como podemos definir métodos em structs usando impl, também podemos definir métodos em enums. Aqui está um método chamado call que poderíamos definir no nosso enum Message:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

O corpo do método usaria self para obter o valor sobre o qual o método foi chamado. Neste exemplo, criamos uma variável m com o valor Message::Write(String::from("hello")), e isso é o que self será dentro do corpo do método call quando m.call() for executado.

Vamos olhar agora para outro enum da biblioteca padrão que é extremamente comum e útil: Option.

O Enum Option

Esta seção explora um estudo de caso de Option, que é outro enum definido pela biblioteca padrão. O tipo Option codifica o cenário muito comum em que um valor pode ser alguma coisa ou pode não ser nada.

Por exemplo, se você pedir o primeiro item de uma lista não vazia, receberá um valor. Se pedir o primeiro item de uma lista vazia, não receberá nada. Expressar esse conceito em termos do sistema de tipos significa que o compilador pode verificar se você tratou todos os casos que deveria tratar. Esse recurso pode evitar bugs extremamente comuns em outras linguagens de programação.

O design de uma linguagem de programação costuma ser pensado em termos dos recursos que ela inclui, mas os recursos que ela exclui também são importantes. O Rust não tem o recurso de nulo que muitas outras linguagens têm. Null é um valor que significa que não há valor ali. Em linguagens com null, variáveis sempre podem estar em um de dois estados: null ou não null.

Na sua apresentação de 2009, “Null References: The Billion Dollar Mistake”, Tony Hoare, o inventor do null, disse o seguinte:

Eu chamo isso de meu erro de um bilhão de dólares. Na época, eu estava projetando o primeiro sistema de tipos abrangente para referências em uma linguagem orientada a objetos. Meu objetivo era garantir que todo uso de referências fosse absolutamente seguro, com a verificação realizada automaticamente pelo compilador. Mas eu não consegui resistir à tentação de incluir uma referência nula, simplesmente porque era muito fácil implementá-la. Isso levou a inúmeros erros, vulnerabilidades e falhas de sistema, que provavelmente causaram um bilhão de dólares em dor e prejuízo ao longo dos últimos quarenta anos.

O problema com valores null é que, se você tentar usar um valor null como se fosse um valor não null, vai receber algum tipo de erro. Como essa propriedade de ser null ou não null é disseminada, é extremamente fácil cometer esse tipo de erro.

No entanto, o conceito que null tenta expressar ainda é útil: null é um valor que, por algum motivo, está ausente ou inválido no momento.

O problema não está realmente no conceito, e sim na implementação específica. Por isso, o Rust não tem nulls, mas tem um enum que pode codificar a ideia de um valor estar presente ou ausente. Esse enum é Option<T>, e ele é definido pela biblioteca padrão assim:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

O enum Option<T> é tão útil que ele inclusive faz parte do prelude; você não precisa trazê-lo explicitamente para o escopo. Suas variantes também fazem parte do prelude: você pode usar Some e None diretamente, sem o prefixo Option::. O enum Option<T> continua sendo apenas um enum normal, e Some(T) e None continuam sendo variantes do tipo Option<T>.

A sintaxe <T> é um recurso do Rust sobre o qual ainda não falamos. Trata-se de um parâmetro de tipo genérico, e veremos genéricos em mais detalhes no Capítulo 10. Por enquanto, tudo o que você precisa saber é que <T> significa que a variante Some do enum Option pode conter um valor de qualquer tipo e que cada tipo concreto usado no lugar de T transforma o tipo geral Option<T> em um tipo diferente. Aqui estão alguns exemplos de uso de valores Option para armazenar tipos numéricos e caracteres:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

O tipo de some_number é Option<i32>. O tipo de some_char é Option<char>, que é um tipo diferente. O Rust consegue inferir esses tipos porque especificamos um valor dentro da variante Some. Para absent_number, o Rust exige que anotemos o tipo Option como um todo: o compilador não consegue inferir qual tipo a variante Some correspondente conteria olhando apenas para um valor None. Aqui, estamos dizendo ao Rust que queremos que absent_number seja do tipo Option<i32>.

Quando temos um valor Some, sabemos que um valor está presente e que ele está armazenado dentro de Some. Quando temos um valor None, em certo sentido isso significa a mesma coisa que null: não temos um valor válido. Então por que ter Option<T> é melhor do que ter null?

Em resumo, porque Option<T> e T, em que T pode ser qualquer tipo, são tipos diferentes, o compilador não nos deixa usar um valor Option<T> como se ele certamente fosse um valor válido. Por exemplo, este código não compila, porque tenta somar um i8 a um Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

Se executarmos esse código, receberemos uma mensagem de erro como esta:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `enums` (bin "enums") due to 1 previous error

Pesado! Na prática, essa mensagem de erro quer dizer que o Rust não sabe como somar um i8 e um Option<i8>, porque eles são tipos diferentes. Quando temos um valor de um tipo como i8 em Rust, o compilador garante que sempre teremos um valor válido. Podemos prosseguir com confiança, sem precisar verificar se o valor é null antes de usá-lo. Só quando temos um Option<i8>, ou qualquer outro Option com que estejamos trabalhando, é que precisamos nos preocupar com a possibilidade de não haver valor, e o compilador garantirá que trataremos esse caso antes de usar o valor.

Em outras palavras, você precisa converter um Option<T> em um T antes de poder realizar operações de T com ele. Em geral, isso ajuda a capturar um dos problemas mais comuns envolvendo null: supor que algo não é null quando, na verdade, é.

Eliminar o risco de assumir incorretamente que um valor não é null ajuda você a ter mais confiança no seu código. Para ter um valor que possa ser null, você precisa optar explicitamente por isso, fazendo com que o tipo desse valor seja Option<T>. Depois, ao usar esse valor, você é obrigado a tratar explicitamente o caso em que ele é null. Em todo lugar em que um valor tenha um tipo que não seja Option<T>, você pode assumir com segurança que ele não é null. Essa foi uma decisão deliberada de design do Rust para limitar a disseminação de null e aumentar a segurança do código Rust.

Então, como você obtém o valor T de dentro de uma variante Some quando tem um valor do tipo Option<T> e quer usar esse valor? O enum Option<T> tem um grande número de métodos úteis em diversas situações; você pode consultá-los na documentação. Familiarizar-se com os métodos de Option<T> será extremamente útil na sua jornada com Rust.

Em geral, para usar um valor Option<T>, você precisa ter código que trate cada variante. Você vai querer um trecho de código que só execute quando tiver um Some(T), e esse código poderá usar o T interno. Também vai querer outro trecho que só execute quando tiver um valor None, e esse código não terá um valor T disponível. A expressão match é uma construção de controle de fluxo que faz exatamente isso quando usada com enums: ela executa códigos diferentes dependendo de qual variante do enum está presente, e esse código pode usar os dados contidos no valor correspondente.

A construção de fluxo de controle match

A construção de fluxo de controle match

Rust tem uma construção de fluxo de controle extremamente poderosa chamada match, que permite comparar um valor com uma série de padrões e então executar código com base em qual padrão corresponde. Padrões podem ser formados por valores literais, nomes de variáveis, curingas e muitas outras coisas; o Capítulo 19 aborda todos os tipos de padrões e o que eles fazem. O poder de match vem da expressividade desses padrões e do fato de o compilador confirmar que todos os casos possíveis foram tratados.

Pense em uma expressão match como uma máquina de classificar moedas: as moedas deslizam por uma trilha com buracos de tamanhos variados, e cada moeda cai no primeiro buraco em que ela cabe. Da mesma forma, valores passam por cada padrão de um match, e, no primeiro padrão em que o valor “se encaixa”, ele cai no bloco de código associado para ser usado durante a execução.

Já que falamos em moedas, vamos usá-las como exemplo com match! Podemos escrever uma função que recebe uma moeda americana desconhecida e, de forma parecida com uma máquina de contagem, determina qual moeda é e retorna seu valor em centavos, como mostra a Listagem 6-3.

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Vamos destrinchar o match da função value_in_cents. Primeiro, temos a palavra-chave match, seguida por uma expressão, que neste caso é o valor coin. Isso parece bastante com uma expressão condicional usada com if, mas há uma grande diferença: com if, a condição precisa ser avaliada para um valor booleano; aqui, ela pode ser de qualquer tipo. O tipo de coin, neste exemplo, é o enum Coin que definimos na primeira linha.

Depois vêm os braços do match. Um braço tem duas partes: um padrão e algum código. O primeiro braço aqui tem como padrão o valor Coin::Penny e, em seguida, o operador =>, que separa o padrão do código a ser executado. O código, neste caso, é apenas o valor 1. Cada braço é separado do seguinte por uma vírgula.

Quando a expressão match é executada, ela compara o valor resultante com o padrão de cada braço, em ordem. Se um padrão corresponder ao valor, o código associado a esse padrão é executado. Se esse padrão não corresponder, a execução continua para o próximo braço, como numa máquina de classificar moedas. Podemos ter quantos braços precisarmos: na Listagem 6-3, nosso match tem quatro braços.

O código associado a cada braço é uma expressão, e o valor resultante da expressão no braço correspondente é o valor retornado pela expressão match inteira.

Normalmente não usamos chaves quando o código do braço é curto, como na Listagem 6-3, em que cada braço apenas retorna um valor. Se você quiser executar várias linhas de código em um braço de match, deve usar chaves, e a vírgula após esse braço passa então a ser opcional. Por exemplo, o código a seguir imprime “Lucky penny!” toda vez que o método é chamado com Coin::Penny, mas ainda retorna o último valor do bloco, 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Padrões que se ligam a valores

Outro recurso útil dos braços de match é que eles podem se ligar às partes dos valores que correspondem ao padrão. É assim que podemos extrair valores de variantes de enum.

Como exemplo, vamos alterar uma das variantes do nosso enum para armazenar dados dentro dela. De 1999 a 2008, os Estados Unidos cunharam moedas de 25 centavos com desenhos diferentes para cada um dos 50 estados em um dos lados. Nenhuma outra moeda recebeu desenhos de estados, então apenas os quarters têm esse valor extra. Podemos adicionar essa informação ao nosso enum alterando a variante Quarter para incluir um valor UsState armazenado dentro dela, como fizemos na Listagem 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

Vamos imaginar que um amigo esteja tentando colecionar todos os 50 quarters de estados. Enquanto classificamos nosso troco por tipo de moeda, também diremos o nome do estado associado a cada quarter para que, se for um que nosso amigo não tenha, ele possa adicioná-lo à coleção.

Na expressão match deste código, adicionamos uma variável chamada state ao padrão que corresponde a valores da variante Coin::Quarter. Quando um Coin::Quarter corresponder, a variável state será ligada ao valor do estado daquele quarter. Depois, podemos usar state no código desse braço, assim:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

Se chamássemos value_in_cents(Coin::Quarter(UsState::Alaska)), coin seria Coin::Quarter(UsState::Alaska). Quando comparamos esse valor com cada um dos braços do match, nenhum deles corresponde até chegarmos a Coin::Quarter(state). Nesse ponto, a ligação state terá o valor UsState::Alaska. Podemos então usar essa ligação na expressão println!, obtendo assim o valor interno do estado da variante Coin::Quarter.

O padrão match com Option<T>

Na seção anterior, queríamos obter o valor interno T do caso Some ao usar Option<T>; também podemos tratar Option<T> com match, assim como fizemos com o enum Coin! Em vez de comparar moedas, vamos comparar as variantes de Option<T>, mas a forma como a expressão match funciona continua a mesma.

Digamos que queremos escrever uma função que recebe um Option<i32> e, se houver um valor dentro, soma 1 a esse valor. Se não houver valor algum, a função deve retornar None e não tentar executar operação nenhuma.

Essa função é muito fácil de escrever graças a match, e ficará como a Listagem 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Vamos examinar a primeira execução de plus_one com mais detalhes. Quando chamamos plus_one(five), a variável x no corpo de plus_one terá o valor Some(5). Em seguida, comparamos isso com cada braço do match:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

O valor Some(5) não corresponde ao padrão None, então seguimos para o próximo braço:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) corresponde a Some(i)? Sim! Temos a mesma variante. O i se liga ao valor contido em Some, então i recebe o valor 5. O código daquele braço do match é então executado, somamos 1 ao valor de i e criamos um novo valor Some com o total 6 dentro.

Agora vamos considerar a segunda chamada de plus_one na Listagem 6-5, em que x é None. Entramos no match e comparamos com o primeiro braço:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Ele corresponde! Não há valor a ser somado, então o programa para e retorna o valor None que está do lado direito de =>. Como o primeiro braço correspondeu, nenhum outro braço é comparado.

Combinar match e enums é útil em muitas situações. Você verá bastante esse padrão em código Rust: fazer match sobre um enum, ligar uma variável aos dados internos e então executar código com base nisso. No começo ele parece um pouco complicado, mas, depois que você se acostuma, acaba desejando ter isso em todas as linguagens. É consistentemente um dos recursos favoritos dos usuários.

Matches são exaustivos

Há outro aspecto de match que precisamos discutir: os padrões dos braços devem cobrir todas as possibilidades. Considere esta versão da nossa função plus_one, que tem um bug e não compila:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Não tratamos o caso None, então esse código causará um bug. Felizmente, esse é um bug que Rust sabe capturar. Se tentarmos compilar esse código, obteremos este erro:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` (bin "enums") due to 1 previous error

Rust sabe que não cobrimos todos os casos possíveis e até sabe qual padrão foi esquecido! Matches em Rust são exaustivos: precisamos cobrir até a última possibilidade para que o código seja válido. Especialmente no caso de Option<T>, quando Rust nos impede de esquecer de tratar explicitamente o caso None, ela nos protege de assumir que temos um valor quando na verdade poderíamos ter null, tornando impossível o erro de um bilhão de dólares discutido antes.

Padrões pega-tudo e o marcador _

Usando enums, também podemos realizar ações especiais para alguns valores específicos e, para todos os outros, executar uma ação padrão. Imagine que estamos implementando um jogo em que, se você tirar 3 em uma rolagem de dado, seu personagem não se move, mas ganha um chapéu novo e elegante. Se você tirar 7, seu personagem perde um chapéu elegante. Para todos os outros valores, seu personagem anda aquele número de casas no tabuleiro. Aqui está um match que implementa essa lógica, com o resultado do dado fixado no código em vez de ser um valor aleatório, e toda a outra lógica representada por funções sem corpo, porque implementá-las de verdade foge do escopo deste exemplo:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

Nos dois primeiros braços, os padrões são os valores literais 3 e 7. Para o último braço, que cobre todos os outros valores possíveis, o padrão é a variável que escolhemos chamar de other. O código executado para o braço other usa essa variável ao passá-la para a função move_player.

Esse código compila mesmo sem listarmos todos os valores possíveis de um u8, porque o último padrão corresponderá a todos os valores não listados explicitamente. Esse padrão pega-tudo atende ao requisito de que match deve ser exaustivo. Observe que precisamos colocar o braço pega-tudo por último, porque os padrões são avaliados em ordem. Se tivéssemos colocado o braço pega-tudo antes, os outros braços nunca seriam executados, então Rust nos avisará se adicionarmos braços depois de um pega-tudo.

Rust também tem um padrão que podemos usar quando queremos um pega-tudo, mas não queremos usar o valor capturado por ele: _ é um padrão especial que corresponde a qualquer valor e não se liga a ele. Isso diz ao Rust que não vamos usar o valor, então ela não nos avisará sobre uma variável não utilizada.

Vamos mudar as regras do jogo: agora, se você tirar qualquer valor diferente de 3 ou 7, deve rolar novamente. Não precisamos mais usar o valor pega-tudo, então podemos alterar o código para usar _ em vez da variável chamada other:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

Este exemplo também atende ao requisito de exaustividade porque estamos explicitamente ignorando todos os outros valores no último braço; não esquecemos nada.

Por fim, vamos mudar as regras do jogo mais uma vez, de modo que nada mais aconteça no turno se você tirar qualquer coisa diferente de 3 ou 7. Podemos expressar isso usando o valor unitário, o tipo de tupla vazia mencionado na seção “O tipo tupla”, como o código associado ao braço _:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

Aqui, estamos dizendo explicitamente ao Rust que não vamos usar nenhum outro valor que não corresponda a um padrão de um braço anterior e que também não queremos executar código algum nesse caso.

Há mais sobre padrões e correspondência no Capítulo 19. Por enquanto, vamos seguir para a sintaxe if let, que pode ser útil em situações em que a expressão match fica um pouco verbosa.

Fluxo de Controle Conciso com if let e let...else

Fluxo de Controle Conciso com if let e let...else

A sintaxe if let permite combinar if e let em uma forma menos verbosa de tratar valores que correspondem a um padrão, ignorando os demais. Considere o programa da Listagem 6-6, que usa match com um valor Option<u8> na variável config_max, mas só quer executar código se o valor for a variante Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

Se o valor for Some, imprimimos o valor dentro da variante Some, vinculando esse valor à variável max no padrão. Não queremos fazer nada com o valor None. Para satisfazer a expressão match, precisamos adicionar _ => () depois de tratar apenas uma variante, o que é um código repetitivo incômodo de incluir.

Em vez disso, poderíamos escrever isso de forma mais curta usando if let. O código a seguir se comporta da mesma maneira que o match da Listagem 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

A sintaxe if let recebe um padrão e uma expressão separados por um sinal de igual. Ela funciona da mesma forma que match, em que a expressão é fornecida ao match e o padrão aparece em seu primeiro braço. Neste caso, o padrão é Some(max), e max se vincula ao valor dentro de Some. Podemos então usar max no corpo do bloco if let da mesma forma que o usamos no braço correspondente do match. O código dentro do bloco if let só é executado se o valor corresponder ao padrão.

Usar if let significa menos digitação, menos indentação e menos código repetitivo. No entanto, você perde a verificação exaustiva que match impõe e que garante que nenhum caso foi esquecido. Escolher entre match e if let depende do que você está fazendo na situação concreta e se ganhar concisão é uma troca aceitável pela perda da verificação exaustiva.

Em outras palavras, você pode pensar em if let como açúcar sintático para um match que executa código quando o valor corresponde a um padrão e depois ignora todos os outros valores.

Podemos incluir um else com if let. O bloco de código que acompanha o else é o mesmo bloco que acompanharia o caso _ na expressão match equivalente ao if let com else. Lembre-se da definição do enum Coin na Listagem 6-4, em que a variante Quarter também armazenava um valor UsState. Se quiséssemos contar todas as moedas que não são quarters e, ao mesmo tempo, anunciar o estado dos quarters, poderíamos fazer isso com uma expressão match, assim:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

Ou poderíamos usar uma expressão if let com else, assim:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

Permanecendo no “Caminho Feliz” com let...else

Um padrão comum é realizar algum cálculo quando um valor está presente e retornar um valor padrão caso contrário. Continuando com nosso exemplo das moedas com um valor UsState, se quiséssemos dizer algo engraçado dependendo de quão antigo era o estado no quarter, poderíamos introduzir um método em UsState para verificar a idade de um estado, assim:

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Então poderíamos usar if let para verificar o tipo da moeda, introduzindo uma variável state dentro do corpo da condição, como na Listagem 6-7.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Isso resolve o problema, mas empurra o trabalho para dentro do corpo da instrução if let; se o trabalho a ser feito for mais complicado, pode ficar difícil acompanhar exatamente como os ramos de nível superior se relacionam. Também poderíamos aproveitar o fato de que expressões produzem valores para obter state a partir do if let ou retornar mais cedo, como na Listagem 6-8. Você também poderia fazer algo parecido com match.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Mesmo assim, essa abordagem também é um pouco chata de acompanhar. Um dos ramos do if let produz um valor, enquanto o outro retorna da função por completo.

Para tornar esse padrão comum mais agradável de expressar, o Rust tem let...else. A sintaxe let...else recebe um padrão do lado esquerdo e uma expressão do lado direito, muito parecida com if let, mas não tem um ramo if, apenas um ramo else. Se o padrão corresponder, ela vinculará o valor do padrão no escopo externo. Se o padrão não corresponder, o fluxo do programa seguirá para o braço else, que deve retornar da função.

Na Listagem 6-9, você pode ver como a Listagem 6-8 fica ao usar let...else no lugar de if let.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Observe que, dessa forma, o código permanece no “caminho feliz” no corpo principal da função, sem ter um fluxo de controle significativamente diferente entre dois ramos, como acontecia com if let.

Se você se deparar com uma situação em que a lógica do seu programa fique verbosa demais para ser expressa com match, lembre-se de que if let e let...else também fazem parte da sua caixa de ferramentas em Rust.

Resumo

Agora cobrimos como usar enums para criar tipos personalizados que podem ser um dentre um conjunto de valores enumerados. Mostramos como o tipo Option<T> da biblioteca padrão ajuda você a usar o sistema de tipos para prevenir erros. Quando valores de enum têm dados dentro deles, você pode usar match ou if let para extrair e usar esses valores, dependendo de quantos casos precisa tratar.

Seus programas em Rust agora podem expressar conceitos do seu domínio usando structs e enums. Criar tipos personalizados para usar na sua API garante segurança de tipos: o compilador assegurará que suas funções recebam apenas valores do tipo que cada função espera.

Para fornecer aos usuários uma API bem organizada, simples de usar e que exponha somente o que eles realmente precisam, vamos agora nos voltar para os módulos do Rust.

Pacotes, Crates e Módulos

À medida que você escreve programas maiores, organizar o código se torna cada vez mais importante. Ao agrupar funcionalidades relacionadas e separar o código por responsabilidades bem definidas, fica mais claro onde encontrar a implementação de um recurso e onde alterá-la quando necessário.

Até agora, os programas que escrevemos estavam em um único módulo, em um único arquivo. Conforme um projeto cresce, é natural dividir o código em vários módulos e, depois, em vários arquivos. Um pacote pode conter vários crates binários e, opcionalmente, um crate de biblioteca. À medida que um pacote evolui, você também pode extrair partes dele para crates separados, que passam a ser dependências externas. Este capítulo cobre todas essas técnicas. Para projetos muito grandes, formados por um conjunto de pacotes relacionados que evoluem juntos, o Cargo oferece workspaces, que veremos em “Cargo Workspaces” no Capítulo 14.

Também vamos discutir como encapsular detalhes de implementação, o que permite reutilizar código em um nível mais alto: depois que você implementa uma operação, outro código pode chamá-la por meio de sua interface pública sem precisar saber como a implementação funciona internamente. A forma como você escreve o código define quais partes são públicas e podem ser usadas por outros trechos, e quais partes permanecem privadas como detalhes de implementação que você se reserva o direito de alterar. Essa é outra maneira de limitar a quantidade de detalhes que você precisa manter na cabeça ao mesmo tempo.

Um conceito relacionado é o de escopo: o contexto aninhado em que o código é escrito define um conjunto de nomes que estão “em escopo”. Ao ler, escrever e compilar código, tanto programadores quanto compiladores precisam saber se um nome em um ponto específico se refere a uma variável, função, struct, enum, módulo, constante ou outro item, e qual é o significado desse item. Você pode criar novos escopos e alterar quais nomes estão ou não disponíveis em cada um deles. E não é possível ter dois itens com o mesmo nome no mesmo escopo; para isso, existem ferramentas para resolver conflitos de nomes.

O Rust oferece vários recursos para gerenciar a organização do código, incluindo quais detalhes são expostos, quais permanecem privados e quais nomes estão disponíveis em cada escopo do programa. Esses recursos, às vezes chamados em conjunto de sistema de módulos, incluem:

• Packages: um recurso do Cargo que permite compilar, testar e compartilhar crates
• Crates: uma árvore de módulos que produz uma biblioteca ou um executável
• Modules and use: permitem controlar a organização, o escopo e a privacidade dos caminhos
• Paths: uma forma de nomear um item, como uma struct, função ou módulo

Neste capítulo, vamos passar por todos esses recursos, discutir como eles se relacionam e mostrar como usá-los para gerenciar escopo. Ao final, você deve ter uma base sólida sobre o sistema de módulos e se sentir confortável para trabalhar com escopos em Rust.

Packages e Crates

Pacotes e Crates

As primeiras partes do sistema de módulos que vamos abordar são pacotes e crates.

Um crate é a menor unidade de código que o compilador Rust considera em um processo de compilação. Mesmo que você execute rustc diretamente em vez de usar cargo, passando um único arquivo-fonte, como fizemos em “Noções Básicas de um Programa Rust” no Capítulo 1, o compilador trata esse arquivo como um crate. Crates podem conter módulos, e os módulos podem ser definidos em outros arquivos que são compilados junto com o crate, como veremos nas próximas seções.

Um crate pode ser de um de dois tipos: crate binário ou crate de biblioteca. Crates binários são programas que podem ser compilados para um executável, por exemplo um programa de linha de comando ou um servidor. Cada crate binário precisa ter uma função chamada main, que define o que acontece quando o executável é executado. Todos os crates que criamos até agora eram crates binários.

Crates de biblioteca não têm função main e não são compilados em um executável. Em vez disso, eles definem funcionalidades destinadas a ser compartilhadas com outros projetos. Por exemplo, o crate rand, que usamos no Capítulo 2, fornece funcionalidades para gerar números aleatórios. Na maior parte do tempo, quando rustaceanos dizem “crate”, eles estão falando de um crate de biblioteca e usam “crate” quase como sinônimo da ideia geral de “biblioteca”.

O crate root é o arquivo-fonte a partir do qual o compilador Rust começa a análise e monta a árvore de módulos do crate. Vamos explorar módulos com mais profundidade em “Definindo Módulos para Controlar Escopo e Privacidade”.

Um pacote é um conjunto de um ou mais crates que oferece um grupo de funcionalidades. Um pacote contém um arquivo Cargo.toml que descreve como compilar esses crates. O próprio Cargo é, na verdade, um pacote que contém o crate binário da ferramenta de linha de comando que você usa para construir seu código. O pacote do Cargo também contém um crate de biblioteca do qual esse crate binário depende. Outros projetos podem depender desse crate de biblioteca do Cargo para reutilizar a mesma lógica que a ferramenta de linha de comando usa.

Um pacote pode conter quantos crates binários você quiser, mas no máximo um crate de biblioteca. E todo pacote precisa conter pelo menos um crate, seja ele binário, seja de biblioteca.

Vamos ver o que acontece quando criamos um pacote. Primeiro, executamos o comando cargo new my-project:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

Depois de executar cargo new my-project, usamos ls para ver o que o Cargo criou. No diretório my-project, há um arquivo Cargo.toml, que define o pacote. Também há um diretório src contendo main.rs. Se você abrir Cargo.toml no editor, verá que ele não menciona explicitamente src/main.rs. O Cargo segue uma convenção: src/main.rs é o crate root de um crate binário com o mesmo nome do pacote. Da mesma forma, se o pacote contiver src/lib.rs, o Cargo entende que ele também possui um crate de biblioteca com o mesmo nome do pacote, e que src/lib.rs é o crate root desse crate. O Cargo passa esses arquivos raiz para o rustc, que então compila a biblioteca ou o binário.

Aqui, temos um pacote que contém apenas src/main.rs, o que significa que ele contém apenas um crate binário chamado my-project. Se um pacote contiver tanto src/main.rs quanto src/lib.rs, ele terá dois crates: um binário e um de biblioteca, ambos com o mesmo nome do pacote. Um pacote também pode ter vários crates binários colocando arquivos no diretório src/bin: cada arquivo nesse diretório será um crate binário separado.

Controlando Escopo e Privacidade com Módulos

Controlando escopo e privacidade com módulos

Nesta seção, vamos falar sobre módulos e outras partes do sistema de módulos: paths, que permitem nomear itens; a palavra-chave use, que traz um caminho para o escopo; e a palavra-chave pub, que torna itens públicos. Também vamos discutir a palavra-chave as, pacotes externos e o operador glob.

Folha de referência de módulos

Antes de entrarmos nos detalhes de módulos e caminhos, aqui está uma referência rápida de como módulos, caminhos, a palavra-chave use e a palavra-chave pub funcionam no compilador, e de como a maior parte das pessoas organiza o código. Ao longo deste capítulo veremos exemplos de cada uma dessas regras, mas esta é uma ótima seção para consultar quando você quiser relembrar como módulos funcionam.

• Comece pela raiz da crate: ao compilar uma crate, o compilador primeiro procura código para compilar no arquivo raiz da crate, que geralmente é src/lib.rs para uma crate de biblioteca e src/main.rs para uma crate binária.
• Declarando módulos: no arquivo raiz da crate, você pode declarar novos módulos. Digamos que você declare um módulo garden com mod garden;. O compilador procurará o código desse módulo nestes lugares:
  • Inline, entre chaves que substituem o ponto e vírgula após mod garden
  • No arquivo src/garden.rs
  • No arquivo src/garden/mod.rs
• Declarando submódulos: em qualquer arquivo que não seja a raiz da crate, você pode declarar submódulos. Por exemplo, você poderia declarar mod vegetables; em src/garden.rs. O compilador procurará o código do submódulo dentro do diretório nomeado em função do módulo pai, nestes lugares:
  • Inline, logo após mod vegetables, entre chaves no lugar do ponto e vírgula
  • No arquivo src/garden/vegetables.rs
  • No arquivo src/garden/vegetables/mod.rs
• Caminhos para código em módulos: depois que um módulo passa a fazer parte da crate, você pode se referir ao código dele de qualquer outro lugar dessa mesma crate, desde que as regras de privacidade permitam, usando o caminho até esse código. Por exemplo, um tipo Asparagus no módulo garden::vegetables seria encontrado em crate::garden::vegetables::Asparagus.
• Privado versus público: por padrão, o código dentro de um módulo é privado para seus módulos pai. Para tornar um módulo público, declare-o com pub mod em vez de mod. Para tornar públicos também os itens contidos em um módulo público, use pub antes de suas declarações.
• A palavra-chave use: dentro de um escopo, a palavra-chave use cria atalhos para itens, reduzindo a repetição de caminhos longos. Em qualquer escopo que possa se referir a crate::garden::vegetables::Asparagus, você pode criar um atalho com use crate::garden::vegetables::Asparagus;, e a partir daí só precisa escrever Asparagus para usar esse tipo naquele escopo.

Aqui, criamos uma crate binária chamada backyard que ilustra essas regras. O diretório da crate, também chamado backyard, contém estes arquivos e diretórios:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

O arquivo raiz da crate, neste caso, é src/main.rs, e ele contém:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

A linha pub mod garden; diz ao compilador para incluir o código encontrado em src/garden.rs, que é:

pub mod vegetables;

Aqui, pub mod vegetables; também significa que o código em src/garden/vegetables.rs será incluído. Esse código é:

#[derive(Debug)]
pub struct Asparagus {}

Agora vamos entrar nos detalhes dessas regras e vê-las em ação!

Agrupando código relacionado em módulos

Módulos nos permitem organizar o código dentro de uma crate para facilitar a leitura e a reutilização. Eles também nos permitem controlar a privacidade dos itens, porque o código dentro de um módulo é privado por padrão. Itens privados são detalhes internos de implementação, não disponíveis para uso externo. Podemos optar por tornar públicos os módulos e os itens dentro deles, o que os expõe para que código externo possa usá-los e depender deles.

Como exemplo, vamos escrever uma crate de biblioteca que forneça a funcionalidade de um restaurante. Vamos definir as assinaturas das funções, mas deixaremos seus corpos vazios para nos concentrarmos na organização do código, e não na implementação de um restaurante.

Na indústria de restaurantes, algumas partes de um restaurante são chamadas de front of house e outras de back of house. Front of house é onde ficam os clientes; isso inclui onde as pessoas da recepção acomodam os clientes, onde os atendentes recebem pedidos e pagamentos e onde bartenders preparam bebidas. Back of house é onde chefs e cozinheiros trabalham na cozinha, onde a equipe lava a louça e onde gerentes fazem trabalho administrativo.

Para estruturar nossa crate dessa forma, podemos organizar suas funções em módulos aninhados. Crie uma nova biblioteca chamada restaurant executando cargo new restaurant --lib. Em seguida, insira o código da Listagem 7-1 em src/lib.rs para definir alguns módulos e assinaturas de função; esse código representa a seção de front of house.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Definimos um módulo com a palavra-chave mod, seguida do nome do módulo, neste caso front_of_house. O corpo do módulo vai entre chaves. Dentro de módulos, podemos colocar outros módulos, como hosting e serving neste exemplo. Módulos também podem conter definições de outros itens, como structs, enums, constantes, traits e, como na Listagem 7-1, funções.

Ao usar módulos, podemos agrupar definições relacionadas e dar nome ao motivo de essa relação existir. Pessoas que usam esse código podem navegar por ele com base nesses agrupamentos, em vez de ter de ler todas as definições, o que facilita encontrar os trechos relevantes. Pessoas adicionando novas funcionalidades a esse código também saberiam onde colocar o código para manter o programa organizado.

Antes, mencionamos que src/main.rs e src/lib.rs são chamados de raízes de crate. A razão desse nome é que o conteúdo de qualquer um desses dois arquivos forma um módulo chamado crate, na raiz da estrutura de módulos da crate, conhecida como árvore de módulos.

A Listagem 7-2 mostra a árvore de módulos da estrutura definida na Listagem 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Essa árvore mostra como alguns módulos se aninham dentro de outros; por exemplo, hosting está aninhado dentro de front_of_house. A árvore também mostra que alguns módulos são irmãos, ou seja, são definidos dentro do mesmo módulo; hosting e serving são irmãos definidos dentro de front_of_house. Se o módulo A estiver contido dentro do módulo B, dizemos que o módulo A é filho do módulo B e que o módulo B é o pai do módulo A. Observe que toda a árvore de módulos está enraizada sob o módulo implícito chamado crate.

A árvore de módulos pode lembrar a árvore de diretórios do sistema de arquivos do seu computador, e essa comparação é muito apropriada! Assim como usamos diretórios para organizar arquivos, usamos módulos para organizar código. E, assim como arquivos em um diretório, precisamos de um jeito de encontrar nossos módulos.

Caminhos para Referenciar um Item na Árvore de Módulos

Caminhos para se referir a um item na árvore de módulos

Para mostrar ao Rust onde encontrar um item em uma árvore de módulos, usamos um caminho da mesma forma que usamos um caminho ao navegar em um sistema de arquivos. Para chamar uma função, precisamos conhecer seu caminho.

Um caminho pode assumir duas formas:

• Um caminho absoluto é o caminho completo começando na raiz da crate. Para código vindo de uma crate externa, o caminho absoluto começa com o nome da crate. Para código da crate atual, começa com o literal crate.
• Um caminho relativo começa no módulo atual e usa self, super ou um identificador presente no módulo atual.

Tanto caminhos absolutos quanto relativos são seguidos por um ou mais identificadores separados por dois pontos duplos (::).

Voltando à Listagem 7-1, digamos que queremos chamar a função add_to_waitlist. Isso equivale a perguntar: qual é o caminho até a função add_to_waitlist? A Listagem 7-3 contém a Listagem 7-1 com alguns módulos e funções removidos.

Mostraremos duas formas de chamar a função add_to_waitlist a partir de uma nova função, eat_at_restaurant, definida na raiz da crate. Esses caminhos estão corretos, mas ainda existe outro problema que impedirá a compilação desse exemplo como está. Daqui a pouco explicaremos o motivo.

A função eat_at_restaurant faz parte da API pública da nossa crate de biblioteca, então nós a marcamos com a palavra-chave pub. Na seção “Expondo caminhos com a palavra-chave pub”, veremos pub com mais detalhes.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

A primeira vez que chamamos a função add_to_waitlist em eat_at_restaurant, usamos um caminho absoluto. A função add_to_waitlist está definida na mesma crate que eat_at_restaurant, o que significa que podemos usar a palavra-chave crate para começar um caminho absoluto. Em seguida, incluímos cada módulo sucessivo até chegar a add_to_waitlist. Você pode imaginar um sistema de arquivos com a mesma estrutura: especificaríamos o caminho /front_of_house/hosting/add_to_waitlist para executar o programa add_to_waitlist; usar o nome crate para começar da raiz da crate é como usar / para começar da raiz do sistema de arquivos no shell.

A segunda vez que chamamos add_to_waitlist em eat_at_restaurant, usamos um caminho relativo. O caminho começa com front_of_house, o nome do módulo definido no mesmo nível da árvore de módulos que eat_at_restaurant. O equivalente no sistema de arquivos seria usar o caminho front_of_house/hosting/add_to_waitlist. Começar com o nome de um módulo significa que o caminho é relativo.

Escolher entre usar um caminho relativo ou absoluto é uma decisão que você vai tomar com base no seu projeto. Essa escolha depende de ser mais provável que você mova o código que define o item separadamente ou junto com o código que o utiliza. Por exemplo, se movêssemos o módulo front_of_house e a função eat_at_restaurant para dentro de um módulo chamado customer_experience, teríamos que atualizar o caminho absoluto para add_to_waitlist, mas o caminho relativo continuaria válido. Porém, se movêssemos a função eat_at_restaurant separadamente para um módulo chamado dining, o caminho absoluto para add_to_waitlist permaneceria o mesmo, mas o caminho relativo precisaria ser atualizado. Nossa preferência, em geral, é especificar caminhos absolutos porque é mais provável que queiramos mover definições de código e chamadas de item independentemente umas das outras.

Vamos tentar compilar a Listagem 7-3 e descobrir por que ela ainda não compila! Os erros que recebemos são mostrados na Listagem 7-4.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
 2 |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

As mensagens de erro dizem que o módulo hosting é privado. Em outras palavras, temos os caminhos corretos para o módulo hosting e para a função add_to_waitlist, mas Rust não nos deixa usá-los porque não temos acesso às partes privadas. Em Rust, todos os itens, como funções, métodos, structs, enums, módulos e constantes, são privados para módulos pai por padrão. Se você quiser tornar um item como uma função ou struct privado, basta colocá-lo dentro de um módulo.

Itens em um módulo pai não podem usar itens privados dentro de módulos filhos, mas itens em módulos filhos podem usar itens em seus módulos ancestrais. Isso acontece porque módulos filhos encapsulam e escondem seus detalhes de implementação, mas ainda conseguem ver o contexto em que foram definidos. Para continuar com a nossa metáfora, pense nas regras de privacidade como se fossem o escritório interno de um restaurante: o que acontece lá é privado para os clientes, mas a gerência pode ver e fazer tudo no restaurante que administra.

Rust escolheu fazer o sistema de módulos funcionar desse jeito para que esconder detalhes internos de implementação seja o comportamento padrão. Assim, você sabe quais partes do código interno pode alterar sem quebrar o código externo. Ainda assim, Rust oferece a opção de expor partes internas do código de módulos filhos a módulos ancestrais externos usando a palavra-chave pub para tornar um item público.

Expondo caminhos com a palavra-chave pub

Vamos voltar ao erro da Listagem 7-4 que nos dizia que o módulo hosting é privado. Queremos que a função eat_at_restaurant, no módulo pai, tenha acesso à função add_to_waitlist, no módulo filho, então marcamos o módulo hosting com a palavra-chave pub, como mostra a Listagem 7-5.

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Infelizmente, o código da Listagem 7-5 ainda resulta em erros do compilador, como mostra a Listagem 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

O que aconteceu? Adicionar a palavra-chave pub antes de mod hosting torna o módulo público. Com essa mudança, se conseguirmos acessar front_of_house, conseguiremos acessar hosting. Mas o conteúdo de hosting continua privado; tornar o módulo público não torna automaticamente seu conteúdo público. A palavra-chave pub em um módulo só permite que código em seus módulos ancestrais se refira a ele, e não que acesse seu código interno. Como módulos são contêineres, não há muito o que fazer tornando apenas o módulo público; precisamos ir além e escolher tornar público um ou mais itens dentro dele.

Os erros da Listagem 7-6 dizem que a função add_to_waitlist é privada. As regras de privacidade se aplicam a structs, enums, funções e métodos, além de módulos.

Vamos também tornar pública a função add_to_waitlist, adicionando a palavra- chave pub antes de sua definição, como na Listagem 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Agora o código compilará! Para entender por que adicionar a palavra-chave pub nos permite usar esses caminhos em eat_at_restaurant em conformidade com as regras de privacidade, vamos observar os caminhos absoluto e relativo.

No caminho absoluto, começamos com crate, a raiz da árvore de módulos da nossa crate. O módulo front_of_house está definido na raiz da crate. Embora front_of_house não seja público, como a função eat_at_restaurant está definida no mesmo módulo que front_of_house, ou seja, eat_at_restaurant e front_of_house são irmãos, podemos nos referir a front_of_house a partir de eat_at_restaurant. Em seguida vem o módulo hosting, marcado com pub. Podemos acessar o módulo pai de hosting, então podemos acessar hosting. Por fim, a função add_to_waitlist está marcada com pub, e podemos acessar seu módulo pai, então essa chamada de função funciona.

No caminho relativo, a lógica é a mesma do caminho absoluto, com exceção do primeiro passo: em vez de começar na raiz da crate, o caminho começa em front_of_house. O módulo front_of_house está definido dentro do mesmo módulo que eat_at_restaurant, então o caminho relativo que começa no módulo em que eat_at_restaurant está definida funciona. Depois, como hosting e add_to_waitlist estão marcados com pub, o restante do caminho também funciona, e essa chamada é válida.

Se você pretende compartilhar sua crate de biblioteca para que outros projetos possam usar seu código, sua API pública é o contrato com as pessoas que usam a crate, e esse contrato determina como elas podem interagir com o seu código. Existem muitas considerações envolvidas em gerenciar mudanças na API pública para tornar mais fácil depender da sua crate. Essas considerações fogem do escopo deste livro; se esse assunto lhe interessar, consulte as Rust API Guidelines.

Iniciando caminhos relativos com super

Podemos construir caminhos relativos que começam no módulo pai, em vez do módulo atual ou da raiz da crate, usando super no início do caminho. Isso é como começar um caminho de sistema de arquivos com a sintaxe .., que significa ir para o diretório pai. Usar super nos permite referenciar um item que sabemos estar no módulo pai, o que pode facilitar a reorganização da árvore de módulos quando um módulo está intimamente relacionado ao pai, mas esse pai pode ser movido futuramente para outra posição na árvore.

Considere o código da Listagem 7-8, que modela a situação em que um chef corrige um pedido incorreto e o leva pessoalmente ao cliente. A função fix_incorrect_order, definida no módulo back_of_house, chama a função deliver_order, definida no módulo pai, especificando o caminho para deliver_order começando com super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

A função fix_incorrect_order está no módulo back_of_house, então podemos usar super para subir ao módulo pai de back_of_house, que neste caso é crate, a raiz. A partir daí, procuramos deliver_order e a encontramos. Sucesso! Achamos provável que o módulo back_of_house e a função deliver_order permaneçam na mesma relação entre si e sejam movidos juntos se um dia decidirmos reorganizar a árvore de módulos da crate. Por isso, usamos super, assim teremos menos lugares para atualizar no futuro caso esse código seja movido para outro módulo.

Tornando structs e enums públicos

Também podemos usar pub para designar structs e enums como públicos, mas há alguns detalhes extras no uso de pub com structs e enums. Se usarmos pub antes de uma definição de struct, tornamos a struct pública, mas seus campos continuarão privados. Podemos tornar cada campo público ou não caso a caso. Na Listagem 7-9, definimos uma struct pública back_of_house::Breakfast com um campo público toast, mas um campo privado seasonal_fruit. Isso modela o caso de um restaurante em que o cliente pode escolher o tipo de pão que acompanha a refeição, mas o chef decide qual fruta virá junto com base no que está na estação e disponível em estoque. As frutas disponíveis mudam rapidamente, então clientes não podem escolher a fruta nem sequer ver qual receberão.

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal.
    // meal.seasonal_fruit = String::from("blueberries");
}

Como o campo toast da struct back_of_house::Breakfast é público, em eat_at_restaurant podemos escrever e ler o campo toast usando a notação com ponto. Observe que não podemos usar o campo seasonal_fruit em eat_at_restaurant, porque seasonal_fruit é privado. Tente descomentar a linha que modifica seasonal_fruit para ver qual erro você recebe!

Além disso, note que, como back_of_house::Breakfast tem um campo privado, a struct precisa fornecer uma função associada pública que construa uma instância de Breakfast, que chamamos aqui de summer. Se Breakfast não tivesse essa função, não poderíamos criar uma instância de Breakfast em eat_at_restaurant, porque não conseguiríamos definir o valor do campo privado seasonal_fruit.

Em contraste, se tornarmos um enum público, todas as suas variantes passam a ser públicas. Só precisamos colocar pub antes da palavra-chave enum, como na Listagem 7-10.

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

Como tornamos o enum Appetizer público, podemos usar as variantes Soup e Salad em eat_at_restaurant.

Enums não são muito úteis se suas variantes não forem públicas; seria irritante ter de anotar todas as variantes de enum com pub em todos os casos, então o comportamento padrão das variantes de enum é serem públicas. Structs frequentemente continuam úteis mesmo sem campos públicos, então campos de struct seguem a regra geral de tudo ser privado por padrão, a menos que seja explicitamente anotado com pub.

Há mais uma situação envolvendo pub que ainda não cobrimos, e ela está ligada ao último recurso do sistema de módulos que veremos: a palavra-chave use. Primeiro vamos tratar de use por si só, e depois mostraremos como combinar pub e use.

Trazendo caminhos para o escopo com a palavra-chave use

Trazendo caminhos para o escopo com a palavra-chave use

Ter de escrever os caminhos completos para chamar funções pode parecer inconveniente e repetitivo. Na Listagem 7-7, independentemente de escolhermos o caminho absoluto ou relativo para a função add_to_waitlist, toda vez que queríamos chamar add_to_waitlist precisávamos especificar também front_of_house e hosting. Felizmente, há uma forma de simplificar esse processo: podemos criar um atalho para um caminho com a palavra-chave use uma única vez e então usar o nome mais curto em qualquer outro lugar daquele escopo.

Na Listagem 7-11, trazemos o módulo crate::front_of_house::hosting para o escopo da função eat_at_restaurant, de modo que só precisamos especificar hosting::add_to_waitlist para chamar a função add_to_waitlist dentro de eat_at_restaurant.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Adicionar use e um caminho dentro de um escopo é semelhante a criar um link simbólico no sistema de arquivos. Ao adicionar use crate::front_of_house::hosting na raiz da crate, hosting passa a ser um nome válido naquele escopo, como se o módulo hosting tivesse sido definido na raiz da crate. Caminhos trazidos para o escopo com use também respeitam as regras de privacidade, como quaisquer outros caminhos.

Observe que use cria o atalho apenas para o escopo específico em que aparece. A Listagem 7-12 move a função eat_at_restaurant para um novo módulo filho chamado customer, que então se torna um escopo diferente daquele da instrução use, e por isso o corpo da função não compilará.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

O erro do compilador mostra que o atalho já não se aplica dentro do módulo customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of unresolved module or unlinked crate `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   |
   = help: if you wanted to use a crate named `hosting`, use `cargo add hosting` to add it to your `Cargo.toml`
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

Observe também que há um aviso de que use não está mais sendo usada em seu escopo! Para corrigir esse problema, mova a use para dentro do módulo customer também, ou então faça referência ao atalho presente no módulo pai com super::hosting dentro do módulo filho customer.

Criando caminhos use idiomáticos

Na Listagem 7-11, você talvez tenha se perguntado por que especificamos use crate::front_of_house::hosting e então chamamos hosting::add_to_waitlist em eat_at_restaurant, em vez de especificar o caminho de use até a função add_to_waitlist para obter o mesmo resultado, como na Listagem 7-13.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

Embora a Listagem 7-11 e a Listagem 7-13 façam a mesma coisa, a Listagem 7-11 é a forma idiomática de trazer uma função para o escopo com use. Trazer o módulo pai da função para o escopo com use significa que precisamos especificar o módulo pai ao chamar a função. Especificar esse módulo pai ao chamar a função deixa claro que ela não foi definida localmente, enquanto ainda minimiza a repetição do caminho completo. O código da Listagem 7-13 torna menos claro onde add_to_waitlist está definida.

Por outro lado, ao trazer structs, enums e outros itens para o escopo com use, o idiomático é especificar o caminho completo. A Listagem 7-14 mostra a forma idiomática de trazer a struct HashMap da biblioteca padrão para o escopo de uma crate binária.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

Não há um motivo técnico forte por trás desse idiomatismo: é simplesmente a convenção que surgiu, e as pessoas se acostumaram a ler e escrever código Rust dessa maneira.

A exceção a esse idiomatismo aparece quando trazemos para o escopo dois itens com o mesmo nome por meio de instruções use, porque Rust não permite isso. A Listagem 7-15 mostra como trazer para o escopo dois tipos Result que têm o mesmo nome, mas módulos-pai diferentes, e como se referir a eles.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

Como você pode ver, usar os módulos-pai distingue os dois tipos Result. Se, em vez disso, tivéssemos especificado use std::fmt::Result e use std::io::Result, teríamos dois tipos Result no mesmo escopo, e Rust não saberia a qual deles estamos nos referindo ao usar Result.

Fornecendo novos nomes com a palavra-chave as

Existe outra solução para o problema de trazer para o mesmo escopo dois tipos com o mesmo nome usando use: depois do caminho, podemos especificar as e um novo nome local, ou alias, para o tipo. A Listagem 7-16 mostra outra maneira de escrever o código da Listagem 7-15, renomeando um dos dois tipos Result com as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

Na segunda instrução use, escolhemos o novo nome IoResult para o tipo std::io::Result, que não entrará em conflito com o Result de std::fmt que também trouxemos para o escopo. Tanto a Listagem 7-15 quanto a Listagem 7-16 são consideradas idiomáticas, então a escolha fica a seu critério!

Reexportando nomes com pub use

Quando trazemos um nome para o escopo com a palavra-chave use, esse nome fica privado ao escopo para o qual o importamos. Para permitir que código fora desse escopo se refira a esse nome como se ele tivesse sido definido ali, podemos combinar pub e use. Essa técnica é chamada de reexportação, porque estamos trazendo um item para o escopo, mas também tornando esse item disponível para que outras pessoas o tragam para seus próprios escopos.

A Listagem 7-17 mostra o código da Listagem 7-11 com use no módulo raiz alterado para pub use.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Antes dessa mudança, código externo teria de chamar a função add_to_waitlist usando o caminho restaurant::front_of_house::hosting::add_to_waitlist(), o que também exigiria que o módulo front_of_house fosse marcado como pub. Agora que esse pub use reexportou o módulo hosting a partir do módulo raiz, código externo pode usar o caminho restaurant::hosting::add_to_waitlist().

A reexportação é útil quando a estrutura interna do seu código difere da forma como pessoas chamando o seu código pensam no domínio do problema. Por exemplo, nesta metáfora do restaurante, as pessoas que trabalham no restaurante pensam em termos como “front of house” e “back of house”. Mas clientes visitando um restaurante provavelmente não pensariam nas partes do restaurante dessa forma. Com pub use, podemos escrever nosso código com uma estrutura e expor outra estrutura. Isso faz com que a biblioteca fique bem organizada tanto para quem trabalha nela quanto para quem a utiliza. Veremos outro exemplo de pub use e como isso afeta a documentação da crate em “Exportando uma API pública conveniente”, no Capítulo 14.

Usando pacotes externos

No Capítulo 2, programamos um projeto de jogo de adivinhação que usava um pacote externo chamado rand para obter números aleatórios. Para usar rand no nosso projeto, adicionamos esta linha a Cargo.toml:

rand = "0.8.5"

Adicionar rand como dependência em Cargo.toml informa ao Cargo para baixar o pacote rand e quaisquer dependências dele a partir de crates.io, além de disponibilizar rand ao nosso projeto.

Depois, para trazer definições de rand para o escopo do nosso pacote, adicionamos uma linha use começando com o nome da crate, rand, e listamos os itens que queríamos trazer para o escopo. Lembre-se de que, em “Gerando um número aleatório” no Capítulo 2, trouxemos a trait Rng para o escopo e chamamos a função rand::thread_rng:

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Membros da comunidade Rust disponibilizaram muitos pacotes em crates.io, e trazer qualquer um deles para o seu pacote envolve esses mesmos passos: listá-lo no arquivo Cargo.toml do pacote e usar use para trazer itens de suas crates para o escopo.

Observe que a biblioteca padrão std também é uma crate externa ao nosso pacote. Como a biblioteca padrão acompanha a linguagem Rust, não precisamos alterar Cargo.toml para incluir std. Mas precisamos nos referir a ela com use para trazer itens de lá para o escopo do nosso pacote. Por exemplo, com HashMap usaríamos esta linha:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Este é um caminho absoluto começando com std, o nome da crate da biblioteca padrão.

Usando caminhos aninhados para limpar listas de use

Se estivermos usando vários itens definidos na mesma crate ou no mesmo módulo, listar cada item em sua própria linha pode ocupar bastante espaço vertical em nossos arquivos. Por exemplo, estas duas instruções use que tínhamos no jogo de adivinhação da Listagem 2-4 trazem itens de std para o escopo:

use rand::Rng;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Em vez disso, podemos usar caminhos aninhados para trazer os mesmos itens para o escopo em uma única linha. Fazemos isso especificando a parte comum do caminho, seguida por dois pontos duplos, e depois chaves em torno de uma lista das partes do caminho que diferem, como mostra a Listagem 7-18.

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Em programas maiores, trazer muitos itens da mesma crate ou do mesmo módulo para o escopo usando caminhos aninhados pode reduzir bastante a quantidade de instruções use separadas necessárias!

Podemos usar um caminho aninhado em qualquer nível de um caminho, o que é útil ao combinar duas instruções use que compartilham um subcaminho. Por exemplo, a Listagem 7-19 mostra duas instruções use: uma que traz std::io para o escopo e outra que traz std::io::Write para o escopo.

use std::io;
use std::io::Write;

A parte comum desses dois caminhos é std::io, e esse é o primeiro caminho inteiro. Para mesclar esses dois caminhos em uma só instrução use, podemos usar self no caminho aninhado, como mostra a Listagem 7-20.

use std::io::{self, Write};

Essa linha traz std::io e std::io::Write para o escopo.

Importando itens com o operador glob

Se quisermos trazer para o escopo todos os itens públicos definidos em um caminho, podemos especificar esse caminho seguido pelo operador glob *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Essa instrução use traz todos os itens públicos definidos em std::collections para o escopo atual. Tenha cuidado ao usar o operador glob! Ele pode dificultar descobrir quais nomes estão no escopo e onde um nome usado no programa foi definido. Além disso, se a dependência mudar suas definições, aquilo que foi importado também muda, o que pode levar a erros de compilação ao atualizar a dependência, por exemplo se ela adicionar uma definição com o mesmo nome de uma definição sua no mesmo escopo.

O operador glob é frequentemente usado em testes para trazer tudo que está sendo testado para dentro do módulo tests; falaremos disso em “Como escrever testes” no Capítulo 11. O operador glob também é às vezes usado como parte do padrão prelude; veja a documentação da biblioteca padrão para mais informações sobre esse padrão.

Separando Módulos em Arquivos Diferentes

Separando módulos em arquivos diferentes

Até agora, todos os exemplos deste capítulo definiam vários módulos em um único arquivo. Quando os módulos ficam grandes, talvez você queira mover suas definições para arquivos separados, para que o código fique mais fácil de navegar.

Por exemplo, vamos partir do código da Listagem 7-17, que tinha vários módulos relacionados ao restaurante. Vamos extrair módulos para arquivos em vez de manter todos eles definidos no arquivo raiz da crate. Neste caso, o arquivo raiz da crate é src/lib.rs, mas esse procedimento também funciona com crates binárias cujo arquivo raiz é src/main.rs.

Primeiro, vamos extrair o módulo front_of_house para seu próprio arquivo. Remova o código de dentro das chaves do módulo front_of_house, deixando apenas a declaração mod front_of_house;, para que src/lib.rs contenha o código mostrado na Listagem 7-21. Observe que isso ainda não compilará até criarmos o arquivo src/front_of_house.rs mostrado na Listagem 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Em seguida, coloque o código que estava entre as chaves em um novo arquivo chamado src/front_of_house.rs, como mostra a Listagem 7-22. O compilador sabe que deve procurar nesse arquivo porque encontrou, na raiz da crate, a declaração de módulo com o nome front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Observe que você só precisa carregar um arquivo com uma declaração mod uma vez na árvore de módulos. Depois que o compilador sabe que o arquivo faz parte do projeto, e sabe em que ponto da árvore de módulos aquele código se encontra por causa do lugar onde você colocou a instrução mod, os outros arquivos do projeto devem se referir ao código carregado usando um caminho até o ponto onde ele foi declarado, como vimos na seção “Caminhos para se referir a um item na árvore de módulos”. Em outras palavras, mod não é uma operação de “include”, como você pode ter visto em outras linguagens de programação.

Em seguida, vamos extrair o módulo hosting para seu próprio arquivo. O processo é um pouco diferente porque hosting é um módulo filho de front_of_house, e não do módulo raiz. Vamos colocar o arquivo de hosting em um novo diretório nomeado de acordo com seus ancestrais na árvore de módulos; neste caso, src/front_of_house.

Para começar a mover hosting, alteramos src/front_of_house.rs para conter apenas a declaração do módulo hosting:

pub mod hosting;

Depois, criamos o diretório src/front_of_house e um arquivo hosting.rs para conter as definições feitas no módulo hosting:

pub fn add_to_waitlist() {}

Se, em vez disso, colocássemos hosting.rs no diretório src, o compilador esperaria que o código de hosting.rs estivesse em um módulo hosting declarado na raiz da crate, e não como filho do módulo front_of_house. As regras do compilador sobre quais arquivos verificar para o código de quais módulos fazem com que diretórios e arquivos correspondam de maneira mais próxima à árvore de módulos.

Movemos o código de cada módulo para um arquivo separado, e a árvore de módulos permanece a mesma. As chamadas de função em eat_at_restaurant continuarão funcionando sem nenhuma modificação, mesmo que as definições agora estejam em arquivos diferentes. Essa técnica permite mover módulos para novos arquivos à medida que eles crescem.

Observe que a instrução pub use crate::front_of_house::hosting em src/lib.rs também não mudou, e use tampouco tem qualquer impacto sobre quais arquivos são compilados como parte da crate. A palavra-chave mod declara módulos, e o Rust procura em um arquivo com o mesmo nome do módulo o código que deve ir para esse módulo.

Resumo

Rust permite dividir um pacote em várias crates e uma crate em módulos, para que você possa se referir a itens definidos em um módulo a partir de outro. Você pode fazer isso especificando caminhos absolutos ou relativos. Esses caminhos podem ser trazidos para o escopo com uma instrução use, para que você possa usar um caminho mais curto em múltiplos usos do item naquele escopo. O código de módulo é privado por padrão, mas você pode tornar definições públicas adicionando a palavra-chave pub.

No próximo capítulo, veremos algumas estruturas de dados de coleção da biblioteca padrão que você poderá usar no seu código bem organizado.

Coleções comuns

A biblioteca padrão de Rust inclui várias estruturas de dados muito úteis chamadas coleções. A maioria dos outros tipos de dados representa um valor específico, mas coleções podem conter vários valores. Diferentemente dos tipos internos array e tupla, os dados para os quais essas coleções apontam são armazenados no heap, o que significa que a quantidade de dados não precisa ser conhecida em tempo de compilação e pode crescer ou encolher à medida que o programa é executado. Cada tipo de coleção tem capacidades e custos diferentes, e escolher a coleção adequada para cada situação é uma habilidade que você vai desenvolver com o tempo. Neste capítulo, discutiremos três coleções muito usadas em programas Rust:

• Um vetor permite armazenar uma quantidade variável de valores lado a lado.
• Uma string é uma coleção de caracteres. Já mencionamos o tipo String, mas neste capítulo vamos estudá-lo com mais profundidade.
• Um hash map permite associar um valor a uma chave específica. Ele é uma implementação particular de uma estrutura de dados mais geral chamada mapa.

Para conhecer os outros tipos de coleção oferecidos pela biblioteca padrão, veja a documentação.

Vamos discutir como criar e atualizar vetores, strings e hash maps, além do que torna cada um deles especial.

Armazenando Listas de Valores com Vetores

Armazenando listas de valores com vetores

O primeiro tipo de coleção que veremos é Vec<T>, também conhecido como vetor. Vetores permitem armazenar mais de um valor em uma única estrutura de dados que coloca todos esses valores lado a lado na memória. Vetores só podem armazenar valores do mesmo tipo. Eles são úteis quando você tem uma lista de itens, como as linhas de texto de um arquivo ou os preços dos itens em um carrinho de compras.

Criando um novo vetor

Para criar um novo vetor vazio, chamamos a função Vec::new, como mostra a Listagem 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Observe que adicionamos aqui uma anotação de tipo. Como ainda não estamos inserindo nenhum valor nesse vetor, Rust não sabe que tipo de elemento pretendemos armazenar. Esse é um ponto importante. Vetores são implementados usando genéricos; veremos como usar genéricos com seus próprios tipos no Capítulo 10. Por enquanto, basta saber que o tipo Vec<T> fornecido pela biblioteca padrão pode armazenar qualquer tipo. Quando criamos um vetor para guardar um tipo específico, podemos especificar esse tipo entre colchetes angulares. Na Listagem 8-1, dissemos a Rust que o Vec<T> em v conterá elementos do tipo i32.

Mais frequentemente, você criará um Vec<T> com valores iniciais, e Rust inferirá o tipo do valor que você quer armazenar, então raramente precisará fazer essa anotação. Rust convenientemente fornece a macro vec!, que cria um novo vetor contendo os valores que você fornecer. A Listagem 8-2 cria um novo Vec<i32> com os valores 1, 2 e 3. O tipo inteiro é i32 porque esse é o tipo inteiro padrão, como discutimos na seção “Tipos de dados” do Capítulo 3.

fn main() {
    let v = vec![1, 2, 3];
}

Como fornecemos valores iniciais do tipo i32, Rust pode inferir que o tipo de v é Vec<i32>, e a anotação de tipo deixa de ser necessária. A seguir, veremos como modificar um vetor.

Atualizando um vetor

Para criar um vetor e depois adicionar elementos a ele, podemos usar o método push, como mostra a Listagem 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Como acontece com qualquer variável, se quisermos poder alterar seu valor, precisamos torná-la mutável usando a palavra-chave mut, como discutimos no Capítulo 3. Os números que colocamos dentro são todos do tipo i32, e Rust infere isso a partir dos dados, então não precisamos da anotação Vec<i32>.

Lendo elementos de vetores

Há duas formas de referenciar um valor armazenado em um vetor: por indexação ou usando o método get. Nos exemplos a seguir, anotamos os tipos dos valores retornados por essas funções para dar mais clareza.

A Listagem 8-4 mostra os dois jeitos de acessar um valor em um vetor: com a sintaxe de indexação e com o método get.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

Observe alguns detalhes aqui. Usamos o índice 2 para obter o terceiro elemento porque vetores são indexados por números começando em zero. Usar & e [] nos dá uma referência ao elemento naquele índice. Quando usamos o método get com o índice passado como argumento, recebemos um Option<&T>, que podemos usar com match.

Rust oferece essas duas maneiras de referenciar um elemento para que você possa escolher como o programa deve se comportar quando tentar usar um índice fora do intervalo de elementos existentes. Como exemplo, vamos ver o que acontece quando temos um vetor com cinco elementos e então tentamos acessar o elemento no índice 100 com cada uma dessas técnicas, como mostra a Listagem 8-5.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

Quando executamos esse código, o primeiro método, com [], fará o programa entrar em pânico porque ele referencia um elemento inexistente. Esse método é mais apropriado quando você quer que o programa falhe caso haja uma tentativa de acessar um elemento além do fim do vetor.

Quando o método get recebe um índice fora do intervalo do vetor, ele retorna None sem entrar em pânico. Você usaria esse método se acessar um elemento fora dos limites do vetor puder acontecer ocasionalmente em circunstâncias normais. Nesse caso, seu código terá a lógica para lidar com Some(&element) ou None, como discutimos no Capítulo 6. Por exemplo, o índice pode vir de uma pessoa digitando um número. Se ela acidentalmente informar um número grande demais e o programa receber None, você pode dizer à pessoa quantos itens há no vetor atual e dar outra chance de informar um valor válido. Isso seria mais amigável do que derrubar o programa por causa de um erro de digitação!

Quando o programa possui uma referência válida, o borrow checker aplica as regras de ownership e borrowing, abordadas no Capítulo 4, para garantir que essa referência e quaisquer outras referências ao conteúdo do vetor permaneçam válidas. Lembre-se da regra que diz que você não pode ter referências mutáveis e imutáveis ao mesmo tempo no mesmo escopo. Essa regra se aplica à Listagem 8-6, em que mantemos uma referência imutável ao primeiro elemento de um vetor e tentamos adicionar um elemento ao final. Esse programa não funcionará se também tentarmos usar esse elemento mais tarde na função.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

Compilar esse código resultará neste erro:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                      ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` (bin "collections") due to 1 previous error

O código da Listagem 8-6 pode parecer que deveria funcionar: por que uma referência ao primeiro elemento se importaria com mudanças no final do vetor? Esse erro existe por causa de como vetores funcionam: como vetores colocam os valores lado a lado na memória, adicionar um novo elemento ao final do vetor pode exigir alocar uma nova região de memória e copiar os elementos antigos para esse novo espaço, caso não haja espaço suficiente para manter todos os elementos juntos onde o vetor está armazenado atualmente. Nesse caso, a referência ao primeiro elemento apontaria para memória já desalocada. As regras de borrowing impedem que programas acabem nessa situação.

Nota: para mais detalhes sobre a implementação do tipo Vec<T>, veja “The Rustonomicon”.

Iterando sobre os valores de um vetor

Para acessar cada elemento de um vetor em sequência, iteramos por todos os elementos, em vez de usar índices para acessar um de cada vez. A Listagem 8-7 mostra como usar um laço for para obter referências imutáveis a cada elemento de um vetor de valores i32 e imprimi-los.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Também podemos iterar sobre referências mutáveis a cada elemento de um vetor mutável para alterar todos os elementos. O laço for da Listagem 8-8 adiciona 50 a cada elemento.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Para alterar o valor ao qual a referência mutável aponta, precisamos usar o operador de desreferência * para chegar ao valor em i antes de podermos usar o operador +=. Falaremos mais sobre o operador de desreferência na seção “Seguindo o ponteiro até o valor com o operador de desreferência” do Capítulo 15.

Iterar sobre um vetor, de forma imutável ou mutável, é seguro por causa das regras do borrow checker. Se tentássemos inserir ou remover itens dentro dos corpos dos laços for das Listagens 8-7 e 8-8, receberíamos um erro do compilador semelhante ao que vimos no código da Listagem 8-6. A referência ao vetor que o laço for mantém impede a modificação simultânea do vetor inteiro.

Usando um enum para armazenar vários tipos

Vetores só podem armazenar valores do mesmo tipo. Isso pode ser inconveniente: há, sem dúvida, casos de uso em que precisamos armazenar uma lista de itens de tipos diferentes. Felizmente, as variantes de um enum são definidas sob o mesmo tipo enum, então, quando precisamos que um único tipo represente elementos de tipos diferentes, podemos definir e usar um enum.

Por exemplo, digamos que queremos obter valores de uma linha em uma planilha, e algumas colunas dessa linha contêm inteiros, algumas contêm números de ponto flutuante e outras contêm strings. Podemos definir um enum cujas variantes armazenem esses diferentes tipos de valor, e todas as variantes do enum serão consideradas do mesmo tipo: o tipo do próprio enum. Então, podemos criar um vetor para armazenar esse enum e, no fim das contas, guardar tipos diferentes. Fizemos essa demonstração na Listagem 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust precisa saber, em tempo de compilação, quais tipos estarão no vetor para que saiba exatamente quanta memória no heap será necessária para armazenar cada elemento. Também precisamos ser explícitos sobre quais tipos são permitidos nesse vetor. Se Rust permitisse que um vetor armazenasse qualquer tipo, haveria a possibilidade de que um ou mais desses tipos causassem erros nas operações realizadas sobre os elementos do vetor. Usar um enum com uma expressão match significa que Rust garantirá em tempo de compilação que todos os casos possíveis serão tratados, como discutimos no Capítulo 6.

Se você não conhece, em tempo de compilação, o conjunto completo de tipos que um programa pode receber em tempo de execução para armazenar em um vetor, a técnica com enum não funcionará. Nesse caso, você pode usar um trait object, assunto que veremos no Capítulo 18.

Agora que discutimos algumas das formas mais comuns de usar vetores, não deixe de revisar a documentação da API para conhecer os muitos métodos úteis definidos para Vec<T> na biblioteca padrão. Por exemplo, além de push, existe também um método pop, que remove e retorna o último elemento.

Descartar um vetor descarta seus elementos

Como qualquer outro struct, um vetor é liberado quando sai de escopo, como indicado na Listagem 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

Quando o vetor é descartado, todo o seu conteúdo também é descartado, o que significa que os inteiros que ele contém serão limpos. O borrow checker garante que quaisquer referências ao conteúdo de um vetor só sejam usadas enquanto o próprio vetor for válido.

Vamos passar para o próximo tipo de coleção: String!

Armazenando Texto Codificado em UTF-8 com Strings

Armazenando texto codificado em UTF-8 com strings

Falamos sobre strings no Capítulo 4, mas agora vamos examiná-las com mais profundidade. Pessoas novas em Rust frequentemente travam em strings por uma combinação de três razões: a tendência de Rust a expor erros possíveis, o fato de strings serem uma estrutura de dados mais complexa do que muita gente imagina e o UTF-8. Esses fatores se combinam de um jeito que pode parecer difícil para quem vem de outras linguagens de programação.

Discutimos strings no contexto de coleções porque strings são implementadas como uma coleção de bytes, junto com alguns métodos que fornecem funcionalidades úteis quando esses bytes são interpretados como texto. Nesta seção, falaremos sobre as operações em String que todo tipo de coleção possui, como criar, atualizar e ler. Também discutiremos as maneiras pelas quais String difere das outras coleções, especialmente como a indexação em String é complicada pelas diferenças entre a forma como pessoas e computadores interpretam dados de String.

Definindo strings

Primeiro, vamos definir o que queremos dizer com o termo string. Rust tem apenas um tipo de string no núcleo da linguagem, que é o string slice str, geralmente visto em sua forma emprestada, &str. No Capítulo 4, falamos sobre string slices, que são referências a dados de string codificados em UTF-8 armazenados em algum outro lugar. Literais de string, por exemplo, ficam armazenados no binário do programa e, portanto, são string slices.

O tipo String, fornecido pela biblioteca padrão de Rust em vez de fazer parte do núcleo da linguagem, é um tipo de string expansível, mutável, com ownership e codificado em UTF-8. Quando pessoas da comunidade Rust se referem a “strings” em Rust, podem estar falando tanto do tipo String quanto do tipo string slice &str, e não apenas de um deles. Embora esta seção trate principalmente de String, os dois tipos são bastante usados na biblioteca padrão de Rust, e tanto String quanto string slices são codificados em UTF-8.

Criando uma nova string

Muitas das mesmas operações disponíveis para Vec<T> também estão disponíveis para String, porque String é implementada como um invólucro em torno de um vetor de bytes com algumas garantias, restrições e capacidades extras. Um exemplo de função que funciona da mesma forma em Vec<T> e em String é a função new, usada para criar uma instância, como mostra a Listagem 8-11.

fn main() {
    let mut s = String::new();
}

Essa linha cria uma nova string vazia chamada s, na qual depois podemos colocar dados. Muitas vezes, no entanto, já teremos alguns dados iniciais com os quais queremos começar a string. Para isso, usamos o método to_string, disponível em qualquer tipo que implemente a trait Display, como é o caso dos literais de string. A Listagem 8-12 mostra dois exemplos.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // The method also works on a literal directly:
    let s = "initial contents".to_string();
}

Esse código cria uma string contendo initial contents.

Também podemos usar a função String::from para criar uma String a partir de um literal de string. O código da Listagem 8-13 é equivalente ao código da Listagem 8-12 que usa to_string.

fn main() {
    let s = String::from("initial contents");
}

Como strings são usadas para muitas coisas, podemos usar muitas APIs genéricas diferentes para elas, o que nos dá bastante opção. Algumas podem parecer redundantes, mas todas têm seu lugar! Neste caso, String::from e to_string fazem a mesma coisa, então escolher entre uma e outra é uma questão de estilo e legibilidade.

Lembre-se de que strings são codificadas em UTF-8, então podemos incluir nelas quaisquer dados corretamente codificados, como mostra a Listagem 8-14.

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Todos esses são valores válidos de String.

Atualizando uma string

Uma String pode crescer de tamanho e seu conteúdo pode mudar, assim como o conteúdo de um Vec<T> muda se você empurrar mais dados para dentro dele. Além disso, também podemos usar convenientemente o operador + ou a macro format! para concatenar valores de String.

Anexando com push_str ou push

Podemos fazer uma String crescer usando o método push_str para anexar um string slice, como mostra a Listagem 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

Depois dessas duas linhas, s conterá foobar. O método push_str recebe um string slice porque não queremos necessariamente tomar ownership do parâmetro. Por exemplo, no código da Listagem 8-16, queremos continuar podendo usar s2 mesmo depois de anexar seu conteúdo a s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Se o método push_str tomasse ownership de s2, não poderíamos imprimir seu valor na última linha. No entanto, esse código funciona exatamente como esperávamos!

O método push recebe um único caractere como parâmetro e o adiciona à String. A Listagem 8-17 adiciona a letra l a uma String usando o método push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

Como resultado, s conterá lol.

Concatenando com + ou format!

Frequentemente você vai querer combinar duas strings existentes. Uma forma de fazer isso é usar o operador +, como mostra a Listagem 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

A string s3 conterá Hello, world!. O motivo pelo qual s1 deixa de ser válida após a adição, e o motivo pelo qual usamos uma referência para s2, têm a ver com a assinatura do método chamado quando usamos o operador +. O operador + usa o método add, cuja assinatura se parece com isto:

fn add(self, s: &str) -> String {

Na biblioteca padrão, você verá add definido usando genéricos e tipos associados. Aqui, substituímos isso por tipos concretos, que é o que acontece quando chamamos esse método com valores String. Veremos genéricos no Capítulo 10. Essa assinatura já nos dá as pistas necessárias para entender as partes mais complicadas do operador +.

Primeiro, s2 tem um &, o que significa que estamos adicionando uma referência da segunda string à primeira string. Isso acontece por causa do parâmetro s na função add: só podemos adicionar um string slice a uma String; não podemos somar diretamente dois valores String. Mas espere: o tipo de &s2 é &String, não &str, como especificado no segundo parâmetro de add. Então por que a Listagem 8-18 compila?

A razão pela qual conseguimos usar &s2 na chamada a add é que o compilador pode coagir o argumento &String para &str. Quando chamamos o método add, Rust usa uma coerção de deref, que aqui transforma &s2 em &s2[..]. Falaremos sobre coerção de deref com mais profundidade no Capítulo 15. Como add não toma ownership do parâmetro s, s2 continuará sendo uma String válida depois dessa operação.

Em segundo lugar, podemos ver na assinatura que add toma ownership de self porque self não tem &. Isso significa que s1, na Listagem 8-18, será movida para a chamada de add e não será mais válida depois disso. Então, embora let s3 = s1 + &s2; pareça que vai copiar as duas strings e criar uma nova, essa instrução, na verdade, toma ownership de s1, anexa uma cópia do conteúdo de s2 e então devolve ownership do resultado. Em outras palavras, parece que está fazendo muitas cópias, mas não está; a implementação é mais eficiente do que copiar.

Se precisarmos concatenar várias strings, o comportamento do operador + fica difícil de lidar:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

Nesse ponto, s será tic-tac-toe. Com todos os caracteres + e ", fica difícil enxergar o que está acontecendo. Para combinar strings de formas mais complicadas, podemos usar a macro format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Esse código também define s como tic-tac-toe. A macro format! funciona como println!, mas, em vez de imprimir a saída na tela, ela retorna uma String com o conteúdo. A versão do código que usa format! é bem mais fácil de ler, e o código gerado por format! usa referências, de modo que essa chamada não toma ownership de nenhum de seus parâmetros.

Indexando strings

Em muitas outras linguagens de programação, acessar caracteres individuais de uma string por índice é uma operação válida e comum. No entanto, se você tentar acessar partes de uma String com sintaxe de indexação em Rust, receberá um erro. Considere o código inválido da Listagem 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

Esse código produzirá o seguinte erro:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = help: the trait `SliceIndex<str>` is not implemented for `{integer}`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the following other types implement trait `SliceIndex<T>`:
            `usize` implements `SliceIndex<ByteStr>`
            `usize` implements `SliceIndex<[T]>`
  = note: required for `String` to implement `Index<{integer}>`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` (bin "collections") due to 1 previous error

A mensagem de erro conta a história: strings em Rust não dão suporte a indexação. Mas por que não? Para responder a essa pergunta, precisamos discutir como Rust armazena strings na memória.

Representação interna

Uma String é um invólucro sobre um Vec<u8>. Vamos olhar novamente para algumas das strings de exemplo codificadas corretamente em UTF-8 da Listagem 8-14. Primeiro, esta aqui:

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Nesse caso, len será 4, o que significa que o vetor que armazena a string "Hola" tem 4 bytes de comprimento. Cada uma dessas letras ocupa 1 byte quando codificada em UTF-8. Já a linha a seguir pode surpreender você; observe que essa string começa com a letra cirílica maiúscula Ze, e não com o número 3:

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Se alguém perguntasse o comprimento dessa string, você talvez dissesse 12. Na verdade, a resposta de Rust é 24: esse é o número de bytes necessários para codificar “Здравствуйте” em UTF-8, porque cada valor escalar Unicode nessa string ocupa 2 bytes de armazenamento. Portanto, um índice nos bytes da string nem sempre corresponderá a um valor escalar Unicode válido. Para demonstrar, considere este código Rust inválido:

let hello = "Здравствуйте";
let answer = &hello[0];

Você já sabe que answer não será З, a primeira letra. Quando codificado em UTF-8, o primeiro byte de З é 208 e o segundo é 151, então poderia parecer que answer deveria ser 208, mas 208 não é um caractere válido por si só. Retornar 208 provavelmente não é o que uma pessoa desejaria se pedisse a primeira letra dessa string; no entanto, esse é o único dado que Rust tem no índice de byte 0. Em geral, quem usa o programa não quer receber o valor do byte, mesmo quando a string contém apenas letras latinas: se &"hi"[0] fosse um código válido que retornasse o valor do byte, ele retornaria 104, e não h.

A resposta, então, é que, para evitar retornar um valor inesperado e causar bugs que talvez não fossem descobertos imediatamente, Rust simplesmente não compila esse código, evitando mal-entendidos logo no início do processo de desenvolvimento.

Bytes, valores escalares e clusters de grafemas

Outro ponto sobre UTF-8 é que existem, na verdade, três formas relevantes de olhar para strings do ponto de vista de Rust: como bytes, como valores escalares e como clusters de grafemas, que são a coisa mais próxima do que chamaríamos de letras.

Se olharmos para a palavra hindi “नमस्ते”, escrita na escrita devanágari, ela é armazenada como um vetor de valores u8 que se parece com isto:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Isso representa 18 bytes e é a forma como os computadores armazenam esses dados em última instância. Se olharmos para esses dados como valores escalares Unicode, que é o que o tipo char de Rust representa, esses bytes ficam assim:

['न', 'म', 'स', '्', 'त', 'े']

Temos aqui seis valores char, mas o quarto e o sexto não são letras: são marcas diacríticas que não fazem sentido sozinhas. Por fim, se olharmos para isso como clusters de grafemas, obteremos o que uma pessoa consideraria as quatro letras que formam a palavra hindi:

["न", "म", "स्", "ते"]

Rust oferece formas diferentes de interpretar os dados brutos de string que os computadores armazenam, para que cada programa possa escolher a interpretação de que precisa, independentemente da linguagem humana em que os dados estejam.

Um último motivo pelo qual Rust não nos permite indexar uma String para obter um caractere é que se espera que operações de indexação sempre levem tempo constante, O(1). Mas não é possível garantir esse desempenho com uma String, porque Rust teria de percorrer o conteúdo desde o começo até o índice para determinar quantos caracteres válidos existem ali.

Fatiando strings

Indexar uma string costuma ser uma má ideia porque não está claro qual deveria ser o tipo de retorno da operação de indexação: um valor de byte, um caractere, um cluster de grafemas ou um string slice. Por isso, se você realmente precisa usar índices para criar string slices, Rust exige que você seja mais específico.

Em vez de indexar usando [] com um único número, você pode usar [] com um intervalo para criar um string slice contendo bytes específicos:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Aqui, s será um &str que contém os primeiros 4 bytes da string. Antes, mencionamos que cada um desses caracteres tinha 2 bytes, o que significa que s será Зд.

Se tentássemos fatiar apenas parte dos bytes de um caractere com algo como &hello[0..1], Rust entraria em pânico em tempo de execução, da mesma forma que faz quando acessamos um índice inválido em um vetor:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`

thread 'main' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Você deve tomar cuidado ao criar string slices com intervalos, porque isso pode fazer seu programa travar.

Iterando sobre strings

A melhor maneira de operar sobre partes de strings é ser explícito sobre se você quer caracteres ou bytes. Para valores escalares Unicode individuais, use o método chars. Chamar chars sobre “Зд” separa e retorna dois valores do tipo char, e você pode iterar sobre o resultado para acessar cada elemento:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Esse código imprimirá o seguinte:

З
д

Como alternativa, o método bytes retorna cada byte bruto, o que pode ser o mais apropriado para o seu domínio:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Esse código imprimirá os 4 bytes que compõem essa string:

208
151
208
180

Mas lembre-se sempre de que valores escalares Unicode válidos podem ser compostos de mais de 1 byte.

Obter clusters de grafemas a partir de strings, como acontece com a escrita devanágari, é algo complexo, então essa funcionalidade não é fornecida pela biblioteca padrão. Há crates disponíveis em crates.io caso isso seja a funcionalidade de que você precisa.

Lidando com as complexidades das strings

Resumindo, strings são complicadas. Diferentes linguagens de programação fazem escolhas diferentes sobre como apresentar essa complexidade para quem programa. Rust escolheu tornar o tratamento correto de dados String o comportamento padrão de todos os programas Rust, o que significa que programadores precisam pensar mais cedo sobre como lidar com dados UTF-8. Essa troca expõe mais da complexidade das strings do que fica aparente em outras linguagens, mas evita que você tenha de lidar, mais tarde no ciclo de desenvolvimento, com erros envolvendo caracteres não ASCII.

A boa notícia é que a biblioteca padrão oferece bastante funcionalidade construída sobre os tipos String e &str para ajudar a tratar corretamente essas situações complexas. Não deixe de consultar a documentação de métodos úteis como contains, para procurar em uma string, e replace, para substituir partes de uma string por outra.

Vamos mudar para algo um pouco menos complexo: hash maps!

Armazenando Chaves com Valores Associados em Hash Maps

Armazenando Chaves com Valores Associados em Hash Maps

A última das nossas coleções comuns é o hash map. O tipo HashMap<K, V> armazena um mapeamento de chaves do tipo K para valores do tipo V usando uma hashing function, que determina como essas chaves e valores são organizados na memória. Muitas linguagens de programação oferecem esse tipo de estrutura de dados, mas frequentemente com nomes diferentes, como hash, map, object, hash table, dictionary ou associative array, para citar alguns.

Hash maps são úteis quando você quer procurar dados não por índice, como faz com vetores, mas por meio de uma chave que pode ser de qualquer tipo. Por exemplo, em um jogo, você pode acompanhar a pontuação de cada time em um hash map, em que cada chave é o nome de um time e os valores são suas respectivas pontuações. Dado o nome de um time, você pode recuperar sua pontuação.

Nesta seção, veremos a API básica de hash maps, mas há muito mais funcionalidades escondidas nas funções definidas em HashMap<K, V> pela biblioteca padrão. Como sempre, consulte a documentação da biblioteca padrão para mais informações.

Criando um Novo Hash Map

Uma forma de criar um hash map vazio é usar new e adicionar elementos com insert. Na Listagem 8-20, estamos acompanhando as pontuações de dois times, Blue e Yellow. O time Blue começa com 10 pontos, e o time Yellow começa com 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Observe que primeiro precisamos usar use para trazer HashMap da parte de coleções da biblioteca padrão. Das nossas três coleções comuns, esta é a menos usada com frequência, então não faz parte dos itens colocados automaticamente em escopo pelo prelude. Hash maps também recebem menos suporte direto da biblioteca padrão; por exemplo, não existe uma macro embutida para construí-los.

Assim como vetores, hash maps armazenam seus dados na heap. Esse HashMap tem chaves do tipo String e valores do tipo i32. Como vetores, hash maps são homogêneos: todas as chaves precisam ter o mesmo tipo, e todos os valores também precisam ter o mesmo tipo.

Acessando Valores em um Hash Map

Podemos obter um valor de um hash map fornecendo sua chave ao método get, como mostra a Listagem 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Aqui, score terá o valor associado ao time Blue, e o resultado será 10. O método get retorna um Option<&V>; se não houver valor para aquela chave no hash map, get retornará None. Este programa lida com o Option chamando copied para obter um Option<i32> em vez de um Option<&i32> e, em seguida, unwrap_or para definir score como zero caso scores não tenha uma entrada para aquela chave.

Podemos iterar sobre cada par chave-valor em um hash map de maneira parecida com o que fazemos com vetores, usando um loop for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Esse código imprimirá cada par em uma ordem arbitrária:

Yellow: 50
Blue: 10

Gerenciando Ownership em Hash Maps

Para tipos que implementam a trait Copy, como i32, os valores são copiados para dentro do hash map. Para valores próprios, como String, os valores são movidos, e o hash map passa a ser o proprietário desses valores, como mostra a Listagem 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

Não podemos mais usar as variáveis field_name e field_value depois que elas forem movidas para dentro do hash map pela chamada a insert.

Se inserirmos referências a valores no hash map, os valores em si não serão movidos para dentro dele. Os valores apontados por essas referências precisam continuar válidos por pelo menos tanto tempo quanto o hash map for válido. Falaremos mais sobre essas questões em “Validando Referências com Lifetimes” no Capítulo 10.

Atualizando um Hash Map

Embora o número de pares chave-valor possa crescer, cada chave única só pode ter um valor associado por vez, embora o inverso não seja verdadeiro. Por exemplo, tanto o time Blue quanto o time Yellow podem ter o valor 10 armazenado no hash map scores.

Quando você quer alterar os dados em um hash map, precisa decidir como tratar o caso em que uma chave já possui um valor associado. Você pode substituir o valor antigo pelo novo, ignorando completamente o valor anterior. Pode manter o valor antigo e ignorar o novo, adicionando o novo valor apenas se a chave ainda não tiver um valor. Ou pode combinar o valor antigo com o novo. Vamos ver como fazer cada uma dessas coisas!

Sobrescrevendo um Valor

Se inserirmos uma chave e um valor em um hash map e depois inserirmos essa mesma chave com um valor diferente, o valor associado a ela será substituído. Mesmo que o código da Listagem 8-23 chame insert duas vezes, o hash map conterá apenas um par chave-valor, porque estamos inserindo valor para a chave do time Blue nas duas vezes.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

    println!("{scores:?}");
}

Esse código imprimirá {"Blue": 25}. O valor original, 10, foi sobrescrito.

Adicionando uma Chave e um Valor Somente se a Chave Ainda Não Estiver Presente

É comum verificar se uma determinada chave já existe no hash map com algum valor e então tomar as seguintes ações: se a chave já existir, o valor atual deve permanecer como está; se a chave não existir, inserimos a chave e um valor para ela.

Hash maps têm uma API especial para isso chamada entry, que recebe como parâmetro a chave que você quer verificar. O valor retornado pelo método entry é um enum chamado Entry, que representa um valor que pode ou não existir. Digamos que queremos verificar se a chave do time Yellow tem um valor associado. Se não tiver, queremos inserir o valor 50, e o mesmo vale para o time Blue. Usando a API entry, o código fica como na Listagem 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

    println!("{scores:?}");
}

O método or_insert em Entry foi definido para retornar uma referência mutável ao valor da chave correspondente caso essa chave exista; se não existir, ele insere o parâmetro como novo valor dessa chave e retorna uma referência mutável a esse novo valor. Essa técnica é bem mais limpa do que escrever toda a lógica manualmente e, além disso, funciona melhor com o borrow checker.

Executar o código da Listagem 8-24 imprimirá {"Yellow": 50, "Blue": 10}. A primeira chamada a entry vai inserir a chave do time Yellow com o valor 50, porque o time Yellow ainda não tem um valor. A segunda chamada a entry não vai alterar o hash map, porque o time Blue já tem o valor 10.

Atualizando um Valor com Base no Valor Antigo

Outro caso de uso comum para hash maps é procurar o valor de uma chave e, em seguida, atualizá-lo com base no valor anterior. Por exemplo, a Listagem 8-25 mostra um código que conta quantas vezes cada palavra aparece em um texto. Usamos um hash map com as palavras como chaves e incrementamos o valor para acompanhar quantas vezes vimos cada palavra. Se for a primeira vez que vemos uma palavra, primeiro inserimos o valor 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{map:?}");
}

Esse código imprimirá {"world": 2, "hello": 1, "wonderful": 1}. Você pode ver os mesmos pares chave-valor impressos em outra ordem. Lembre-se, pela seção “Acessando Valores em um Hash Map”, que iterar sobre um hash map acontece em ordem arbitrária.

O método split_whitespace retorna um iterador sobre subfatias do valor em text, separadas por espaço em branco. O método or_insert retorna uma referência mutável (&mut V) ao valor da chave especificada. Aqui, armazenamos essa referência mutável na variável count, então, para atribuir um valor a ela, primeiro precisamos desreferenciar count usando o asterisco (*). A referência mutável sai de escopo no fim do loop for, então todas essas mudanças são seguras e permitidas pelas regras de borrowing.

Funções de Hash

Por padrão, HashMap usa uma função de hash chamada SipHash, que pode oferecer resistência a ataques de negação de serviço (DoS) envolvendo tabelas hash¹. Esse não é o algoritmo de hash mais rápido disponível, mas o trade-off por maior segurança, mesmo com a queda de desempenho, vale a pena. Se você fizer profiling do seu código e descobrir que a função de hash padrão é lenta demais para o seu caso, pode trocar por outra, especificando um hasher diferente. Um hasher é um tipo que implementa a trait BuildHasher. Falaremos sobre traits e sobre como implementá-las no Capítulo 10. Você não precisa necessariamente implementar seu próprio hasher do zero; crates.io tem bibliotecas compartilhadas por outros usuários de Rust que fornecem hashers com vários algoritmos de hash comuns.

Resumo

Vetores, strings e hash maps oferecem grande parte da funcionalidade necessária em programas quando você precisa armazenar, acessar e modificar dados. Aqui estão alguns exercícios para os quais você já deve estar preparado:

1. Dada uma lista de inteiros, use um vetor e retorne a mediana, isto é, o valor na posição do meio após ordenar, e a moda, o valor que ocorre com mais frequência. Um hash map será útil aqui.
2. Converta strings para Pig Latin. A primeira consoante de cada palavra vai para o final da palavra, e adicionamos ay; assim, first vira irst-fay. Palavras que começam com vogal recebem hay no final, então apple vira apple-hay. Tenha em mente os detalhes da codificação UTF-8!
3. Usando um hash map e vetores, crie uma interface de texto para permitir que a pessoa usuária adicione nomes de funcionários a um departamento de uma empresa; por exemplo, “Add Sally to Engineering” ou “Add Amir to Sales”. Depois, permita que a pessoa usuária recupere uma lista de todas as pessoas de um departamento ou de todas as pessoas da empresa agrupadas por departamento, em ordem alfabética.

A documentação da API da biblioteca padrão descreve métodos de vetores, strings e hash maps que serão úteis para esses exercícios!

Estamos entrando em programas mais complexos, nos quais operações podem falhar, então este é um momento perfeito para discutir tratamento de erros. É o que veremos a seguir!

1. https://en.wikipedia.org/wiki/SipHash ↩

Tratamento de Erros

Erros são um fato da vida no software, então Rust oferece vários recursos para lidar com situações em que algo dá errado. Em muitos casos, Rust exige que você reconheça a possibilidade de erro e tome alguma ação antes que seu código compile. Esse requisito torna o programa mais robusto, garantindo que você descubra e trate os erros adequadamente antes de colocá-lo em produção!

Rust agrupa os erros em duas grandes categorias: erros recuperáveis e irrecuperáveis. Para um erro recuperável, como arquivo não encontrado, o mais provável é que queiramos apenas informar o problema à pessoa usuária e tentar novamente a operação. Já erros irrecuperáveis são sempre sintomas de bugs, como tentar acessar uma posição além do fim de um array, então queremos interromper imediatamente o programa.

A maioria das linguagens não distingue entre esses dois tipos de erro e trata ambos da mesma forma, usando mecanismos como exceções. Rust não tem exceções. Em vez disso, ele tem o tipo Result<T, E> para erros recuperáveis e a macro panic!, que interrompe a execução quando o programa encontra um erro irrecuperável. Neste capítulo, veremos primeiro chamadas a panic! e depois falaremos sobre retornar valores Result<T, E>. Além disso, exploraremos critérios para decidir se é melhor tentar se recuperar de um erro ou encerrar a execução.

Erros Irrecuperáveis com panic!

Erros Irrecuperáveis com panic!

Às vezes, coisas ruins acontecem no seu código, e não há nada que você possa fazer a respeito. Nesses casos, Rust oferece a macro panic!. Na prática, existem duas formas de causar um panic: executando uma ação que faça o código entrar em panic, como acessar um array além do fim, ou chamando explicitamente a macro panic!. Em ambos os casos, provocamos um panic no programa. Por padrão, esses panics exibem uma mensagem de falha, fazem unwind, limpam a stack e encerram o programa. Por meio de uma variável de ambiente, você também pode fazer Rust exibir a call stack quando ocorre um panic, para facilitar a localização da origem do problema.

[profile.release]
panic = 'abort'

Vamos tentar chamar panic! em um programa simples:

fn main() {
    panic!("crash and burn");
}

Ao executar o programa, você verá algo assim:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

A chamada a panic! causa a mensagem de erro contida nas duas últimas linhas. A primeira linha mostra nossa mensagem de panic e o local do código-fonte em que ele ocorreu: src/main.rs:2:5 indica a segunda linha e o quinto caractere do nosso arquivo src/main.rs.

Neste caso, a linha indicada faz parte do nosso código e, se formos até ela, veremos a chamada à macro panic!. Em outros casos, a chamada a panic! pode estar no código que o nosso código chamou, e o nome do arquivo e o número da linha informados pela mensagem de erro serão do código de outra pessoa onde a macro panic! foi chamada, e não da linha do nosso código que acabou levando até essa chamada.

Podemos usar o backtrace das funções de onde veio a chamada panic! para descobrir qual parte do nosso código está causando o problema. Para entender como usar um backtrace de panic!, vamos analisar outro exemplo e ver como é quando uma chamada panic! vem de uma biblioteca por causa de um bug no nosso código, em vez de vir diretamente de uma chamada nossa à macro. A Listagem 9-1 tem um código que tenta acessar um índice de um vetor além do intervalo de índices válidos.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Aqui, estamos tentando acessar o centésimo elemento do nosso vetor, que está no índice 99, porque a indexação começa em zero, mas o vetor tem apenas três elementos. Nessa situação, Rust entra em panic. Usar [] deveria retornar um elemento, mas, se você passar um índice inválido, não existe nenhum elemento que Rust pudesse retornar aqui de forma correta.

Em C, tentar ler além do fim de uma estrutura de dados é um comportamento indefinido. Você pode acabar obtendo qualquer coisa que esteja naquela posição de memória correspondente ao elemento na estrutura, mesmo que a memória não pertença a ela. Isso é chamado de buffer overread e pode levar a vulnerabilidades de segurança se uma pessoa atacante conseguir manipular o índice de maneira a ler dados que não deveria ter permissão para acessar e que estejam armazenados depois da estrutura de dados.

Para proteger seu programa contra esse tipo de vulnerabilidade, se você tentar ler um elemento em um índice inexistente, Rust vai interromper a execução e se recusar a continuar. Vamos tentar para ver:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Esse erro aponta para a linha 4 do nosso main.rs, onde tentamos acessar o índice 99 do vetor v.

A linha note: nos diz que podemos definir a variável de ambiente RUST_BACKTRACE para obter um backtrace exato do que aconteceu para causar o erro. Um backtrace é uma lista de todas as funções chamadas até chegar a esse ponto. Backtraces em Rust funcionam como em outras linguagens: a chave para lê-los é começar do topo e continuar até encontrar arquivos que você escreveu. Esse é o ponto onde o problema se originou. As linhas acima desse ponto são códigos que seu código chamou; as linhas abaixo são códigos que chamaram o seu código. Essas linhas antes e depois podem incluir código interno do Rust, código da biblioteca padrão ou crates que você está usando. Vamos tentar obter um backtrace definindo a variável de ambiente RUST_BACKTRACE para qualquer valor diferente de 0. A Listagem 9-2 mostra uma saída parecida com a que você verá.

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:274:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/alloc/src/vec/mod.rs:3361:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

É bastante saída! A saída exata pode ser diferente dependendo do seu sistema operacional e da versão do Rust. Para obter backtraces com essas informações, os símbolos de depuração precisam estar habilitados. Eles ficam habilitados por padrão ao usar cargo build ou cargo run sem a flag --release, como estamos fazendo aqui.

Na saída da Listagem 9-2, a linha 6 do backtrace aponta para a linha do nosso projeto que está causando o problema: a linha 4 de src/main.rs. Se não quisermos que o programa entre em panic, devemos começar a investigação no local indicado pela primeira linha que menciona um arquivo escrito por nós. Na Listagem 9-1, em que escrevemos deliberadamente um código que causaria panic, a forma de corrigir o problema é não solicitar um elemento além do intervalo de índices do vetor. Quando seu código entrar em panic no futuro, você vai precisar descobrir que ação ele está realizando, com quais valores, para causar o panic, e o que ele deveria fazer em vez disso.

Voltaremos a panic! e a quando devemos ou não usá-lo para lidar com condições de erro na seção “Para panic! ou não para panic!” mais adiante neste capítulo. A seguir, veremos como se recuperar de um erro usando Result.

Erros Recuperáveis com Result

Erros Recuperáveis com Result

A maioria dos erros não é séria o bastante para exigir que o programa pare por completo. Às vezes, quando uma função falha, é por um motivo que você consegue interpretar facilmente e ao qual consegue responder. Por exemplo, se você tentar abrir um arquivo e essa operação falhar porque o arquivo não existe, talvez queira criar o arquivo em vez de encerrar o processo.

Lembre-se, da seção “Lidando com Falhas Potenciais com Result” no Capítulo 2, que o enum Result é definido com duas variantes, Ok e Err, assim:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T e E são parâmetros de tipo genérico. Vamos discutir genéricos com mais detalhe no Capítulo 10. Por enquanto, o que você precisa saber é que T representa o tipo do valor retornado em caso de sucesso, dentro da variante Ok, e E representa o tipo do erro retornado em caso de falha, dentro da variante Err. Como Result tem esses parâmetros genéricos, podemos usar o tipo Result e as funções definidas nele em muitas situações diferentes nas quais o valor de sucesso e o valor de erro podem variar.

Vamos chamar uma função que retorna um valor Result, porque ela pode falhar. Na Listagem 9-3, tentamos abrir um arquivo.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

O tipo de retorno de File::open é Result<T, E>. O parâmetro genérico T foi preenchido pela implementação de File::open com o tipo do valor de sucesso, std::fs::File, que é um handle de arquivo. O tipo de E usado no valor de erro é std::io::Error. Esse tipo de retorno significa que a chamada a File::open pode dar certo e retornar um handle de arquivo do qual podemos ler ou no qual podemos escrever. Mas a chamada também pode falhar: por exemplo, o arquivo pode não existir, ou talvez não tenhamos permissão para acessá-lo. A função File::open precisa de uma maneira de nos dizer se funcionou ou falhou e, ao mesmo tempo, nos fornecer ou o handle de arquivo ou as informações de erro. Isso é exatamente o que o enum Result transmite.

No caso em que File::open tiver sucesso, o valor da variável greeting_file_result será uma instância de Ok contendo um handle de arquivo. No caso em que falhar, o valor em greeting_file_result será uma instância de Err contendo mais informações sobre o tipo de erro ocorrido.

Precisamos acrescentar código à Listagem 9-3 para executar ações diferentes dependendo do valor retornado por File::open. A Listagem 9-4 mostra uma forma de tratar Result usando uma ferramenta básica: a expressão match, que discutimos no Capítulo 6.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {error:?}"),
    };
}

Observe que, assim como o enum Option, o enum Result e suas variantes foram trazidos para o escopo pelo prelude, então não precisamos escrever Result:: antes de Ok e Err nos braços do match.

Quando o resultado é Ok, esse código devolve o valor interno file para fora da variante Ok, e então atribuímos esse handle de arquivo à variável greeting_file. Depois do match, podemos usar o handle para leitura ou escrita.

O outro braço do match lida com o caso em que recebemos um valor Err de File::open. Neste exemplo, escolhemos chamar a macro panic!. Se não houver um arquivo chamado hello.txt no diretório atual e executarmos esse código, veremos a seguinte saída da macro panic!:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`

thread 'main' panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Como sempre, essa saída nos diz exatamente o que deu errado.

Dando match em Erros Diferentes

O código da Listagem 9-4 vai dar panic! independentemente do motivo pelo qual File::open falhou. No entanto, queremos tomar ações diferentes para motivos de falha diferentes. Se File::open falhou porque o arquivo não existe, queremos criar o arquivo e retornar o handle do novo arquivo. Se File::open falhou por qualquer outro motivo, por exemplo, porque não temos permissão para abri-lo, ainda queremos que o código dê panic! da mesma maneira que na Listagem 9-4. Para isso, adicionamos uma expressão match interna, mostrada na Listagem 9-5.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            _ => {
                panic!("Problem opening the file: {error:?}");
            }
        },
    };
}

O tipo do valor retornado por File::open dentro da variante Err é io::Error, que é uma struct fornecida pela biblioteca padrão. Essa struct tem um método, kind, que podemos chamar para obter um valor io::ErrorKind. O enum io::ErrorKind também é fornecido pela biblioteca padrão e tem variantes que representam os diferentes tipos de erro que uma operação de io pode produzir. A variante que queremos usar é ErrorKind::NotFound, que indica que o arquivo que estamos tentando abrir ainda não existe. Então, damos match em greeting_file_result, mas também temos um match interno em error.kind().

A condição que queremos verificar no match interno é se o valor retornado por error.kind() é a variante NotFound do enum ErrorKind. Se for, tentamos criar o arquivo com File::create. No entanto, como File::create também pode falhar, precisamos de um segundo braço nessa expressão match interna. Quando o arquivo não pode ser criado, uma mensagem de erro diferente é impressa. O segundo braço do match externo permanece o mesmo, então o programa entra em pânico em qualquer erro que não seja o de arquivo ausente.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

Atalhos para Pânico em Caso de Erro

Usar match funciona bem, mas pode ser um pouco verboso e nem sempre comunica bem a intenção. O tipo Result<T, E> tem muitos métodos auxiliares definidos nele para executar tarefas mais específicas. O método unwrap é um atalho implementado exatamente como a expressão match que escrevemos na Listagem 9-4. Se o valor Result for a variante Ok, unwrap devolverá o valor dentro de Ok. Se Result for a variante Err, unwrap chamará a macro panic! por nós. Aqui está um exemplo de unwrap em ação:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Se executarmos esse código sem um arquivo hello.txt, veremos uma mensagem de erro vinda da chamada a panic! que o método unwrap faz:

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Da mesma forma, o método expect também nos permite escolher a mensagem de erro usada em panic!. Usar expect em vez de unwrap e fornecer boas mensagens de erro pode transmitir melhor sua intenção e tornar mais fácil rastrear a origem de um pânico. A sintaxe de expect é assim:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

Usamos expect da mesma forma que unwrap: para devolver o handle de arquivo ou chamar a macro panic!. A mensagem de erro usada por expect em sua chamada a panic! será o parâmetro que passarmos para expect, em vez da mensagem padrão de panic! usada por unwrap. Ela fica assim:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Em código de qualidade de produção, a maioria dos rustaceanos prefere expect a unwrap e fornece mais contexto sobre por que a operação deveria sempre ter sucesso. Assim, se suas suposições se mostrarem erradas, você terá mais informações para usar na depuração.

Propagando Erros

Quando a implementação de uma função chama algo que pode falhar, em vez de tratar o erro dentro da própria função, você pode devolver o erro ao código chamador para que ele decida o que fazer. Isso é conhecido como propagar o erro e dá mais controle ao código chamador, onde pode haver mais informação ou lógica ditando como o erro deve ser tratado do que aquela disponível no contexto da função.

Por exemplo, a Listagem 9-6 mostra uma função que lê um nome de usuário a partir de um arquivo. Se o arquivo não existir ou não puder ser lido, essa função devolverá esses erros ao código que a chamou.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}
}

Essa função pode ser escrita de um jeito muito mais curto, mas vamos começar fazendo bastante coisa manualmente para explorar o tratamento de erros; no final, mostraremos o jeito mais curto. Primeiro, vamos olhar o tipo de retorno da função: Result<String, io::Error>. Isso significa que a função está retornando um valor do tipo Result<T, E>, em que o parâmetro genérico T foi preenchido com o tipo concreto String e o tipo genérico E foi preenchido com o tipo concreto io::Error.

Se essa função tiver sucesso sem problemas, o código que a chama receberá um valor Ok contendo uma String, o username que a função leu do arquivo. Se essa função encontrar algum problema, o código chamador receberá um valor Err contendo uma instância de io::Error, que traz mais informações sobre o que deu errado. Escolhemos io::Error como tipo de retorno dessa função porque esse é justamente o tipo do valor de erro retornado pelas duas operações do corpo da função que podem falhar: a função File::open e o método read_to_string.

O corpo da função começa chamando File::open. Em seguida, tratamos o valor Result com um match semelhante ao da Listagem 9-4. Se File::open tiver sucesso, o handle de arquivo presente na variável de padrão file se torna o valor da variável mutável username_file, e a função continua. No caso de Err, em vez de chamar panic!, usamos a palavra-chave return para sair da função imediatamente e passar o valor de erro de File::open, agora na variável de padrão e, de volta ao código chamador como o valor de erro dessa função.

Então, se tivermos um handle de arquivo em username_file, a função cria uma nova String na variável username e chama o método read_to_string no handle de arquivo em username_file para ler o conteúdo do arquivo para dentro de username. O método read_to_string também retorna um Result, porque ele pode falhar mesmo que File::open tenha funcionado. Portanto, precisamos de outro match para tratar esse Result: se read_to_string tiver sucesso, então a função também terá tido sucesso, e retornaremos o nome de usuário do arquivo, agora armazenado em username, empacotado em Ok. Se read_to_string falhar, retornamos o valor de erro da mesma forma que no match que tratou o valor de retorno de File::open. No entanto, não precisamos escrever return explicitamente, porque esta é a última expressão da função.

O código que chama essa função então terá de lidar com receber um valor Ok contendo um nome de usuário ou um valor Err contendo um io::Error. Cabe ao código chamador decidir o que fazer com esses valores. Se ele receber um valor Err, pode chamar panic! e encerrar o programa, usar um nome de usuário padrão ou buscar esse nome em outro lugar além de um arquivo, por exemplo. Não temos informação suficiente sobre o que o código chamador realmente está tentando fazer, então propagamos todas as informações de sucesso ou erro para cima, para que ele as trate adequadamente.

Esse padrão de propagação de erros é tão comum em Rust que a linguagem fornece o operador ponto de interrogação ? para tornar isso mais fácil.

O Atalho do Operador ?

A Listagem 9-7 mostra uma implementação de read_username_from_file com a mesma funcionalidade da Listagem 9-6, mas essa implementação usa o operador ?.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

O ? colocado depois de um valor Result foi definido para funcionar quase da mesma maneira que as expressões match que criamos para tratar os valores Result na Listagem 9-6. Se o valor de Result for Ok, o valor dentro de Ok será devolvido por essa expressão, e o programa continuará. Se o valor for Err, esse Err será retornado da função inteira, como se tivéssemos usado a palavra-chave return, para que o valor de erro seja propagado para o código chamador.

Existe uma diferença entre o que a expressão match da Listagem 9-6 faz e o que o operador ? faz: os valores de erro sobre os quais ? é chamado passam pela função from, definida na trait From da biblioteca padrão, usada para converter valores de um tipo em outro. Quando o operador ? chama a função from, o tipo de erro recebido é convertido no tipo de erro definido no tipo de retorno da função atual. Isso é útil quando uma função retorna um único tipo de erro para representar todas as formas pelas quais ela pode falhar, mesmo que partes diferentes possam falhar por razões distintas.

Por exemplo, poderíamos alterar a função read_username_from_file da Listagem 9-7 para retornar um tipo de erro personalizado chamado OurError, definido por nós. Se também definíssemos impl From<io::Error> for OurError para construir uma instância de OurError a partir de um io::Error, então as chamadas de ? no corpo de read_username_from_file chamariam from e converteriam os tipos de erro sem que precisássemos acrescentar mais código à função.

No contexto da Listagem 9-7, o ? no final da chamada a File::open retornará o valor dentro de Ok para a variável username_file. Se ocorrer um erro, o operador ? retornará imediatamente da função inteira e entregará qualquer valor Err ao código chamador. O mesmo vale para o ? no final da chamada a read_to_string.

O operador ? elimina bastante código repetitivo e torna a implementação dessa função mais simples. Poderíamos até encurtar ainda mais o código encadeando chamadas de método logo depois do ?, como mostra a Listagem 9-8.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

Movemos a criação da nova String em username para o início da função; essa parte não mudou. Em vez de criar uma variável username_file, encadeamos a chamada para read_to_string diretamente sobre o resultado de File::open("hello.txt")?. Continuamos tendo um ? no final da chamada a read_to_string, e ainda retornamos um valor Ok contendo username quando File::open e read_to_string têm sucesso, em vez de retornar erros. A funcionalidade é, mais uma vez, a mesma das Listagens 9-6 e 9-7; esta é apenas uma forma diferente e mais ergonômica de escrever.

A Listagem 9-9 mostra uma maneira de deixar isso ainda mais curto usando fs::read_to_string.

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

Ler um arquivo para dentro de uma string é uma operação bastante comum, então a biblioteca padrão fornece a conveniente função fs::read_to_string, que abre o arquivo, cria uma nova String, lê o conteúdo do arquivo, coloca esse conteúdo nessa String e a retorna. Claro, usar fs::read_to_string não nos dá a oportunidade de explicar todo o tratamento de erros, então primeiro seguimos pelo caminho mais longo.

Onde o Operador ? Pode Ser Usado

O operador ? só pode ser usado em funções cujo tipo de retorno seja compatível com o valor sobre o qual ? é usado. Isso acontece porque o operador ? foi definido para realizar um retorno antecipado de um valor para fora da função, da mesma maneira que a expressão match que definimos na Listagem 9-6. Na Listagem 9-6, o match estava lidando com um valor Result, e o braço de retorno antecipado retornava um valor Err(e). O tipo de retorno da função precisa ser Result para que isso seja compatível com esse return.

Na Listagem 9-10, vejamos o erro que obteremos se usarmos o operador ? em uma função main com um tipo de retorno incompatível com o tipo do valor sobre o qual usamos ?.

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Esse código abre um arquivo, o que pode falhar. O operador ? acompanha o valor Result retornado por File::open, mas essa função main tem tipo de retorno (), e não Result. Quando compilamos esse código, recebemos a seguinte mensagem de erro:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
help: consider adding return type
  |
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 |     let greeting_file = File::open("hello.txt")?;
5 +     Ok(())
  |

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` (bin "error-handling") due to 1 previous error

Esse erro indica que só podemos usar o operador ? em uma função que retorne Result, Option ou outro tipo que implemente FromResidual.

Para corrigir o erro, você tem duas opções. Uma delas é alterar o tipo de retorno da função para que ele seja compatível com o valor sobre o qual você está usando ?, desde que não haja nenhuma restrição que impeça isso. A outra opção é usar match ou um dos métodos de Result<T, E> para tratar Result<T, E> da maneira mais apropriada.

A mensagem de erro também mencionou que ? pode ser usado com valores Option<T>. Assim como acontece com Result, você só pode usar ? em Option dentro de uma função que retorne Option. O comportamento do operador ? quando chamado em Option<T> é semelhante ao seu comportamento quando chamado em Result<T, E>: se o valor for None, None será retornado antecipadamente da função naquele ponto. Se o valor for Some, o valor dentro de Some será o valor resultante da expressão, e a função continuará. A Listagem 9-11 traz um exemplo de função que encontra o último caractere da primeira linha do texto fornecido.

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

Essa função retorna Option<char> porque é possível que haja um caractere ali, mas também é possível que não haja. Esse código recebe o argumento text, uma fatia de string, e chama o método lines sobre ele, que retorna um iterador sobre as linhas da string. Como essa função quer examinar a primeira linha, ela chama next no iterador para obter o primeiro valor. Se text for a string vazia, essa chamada a next retornará None; nesse caso, usamos ? para parar e retornar None de last_char_of_first_line. Se text não for a string vazia, next retornará um valor Some contendo uma fatia de string da primeira linha de text.

O ? extrai a fatia de string, e podemos chamar chars nessa fatia para obter um iterador sobre seus caracteres. Como estamos interessados no último caractere da primeira linha, chamamos last para retornar o último item do iterador. Isso resulta em um Option, porque é possível que a primeira linha seja a string vazia, por exemplo, se text começar com uma linha em branco, mas tiver caracteres em outras linhas, como em "\nhi". No entanto, se houver um último caractere na primeira linha, ele será retornado dentro da variante Some. O operador ? no meio nos dá uma forma concisa de expressar essa lógica, permitindo implementar a função em uma única linha. Se não pudéssemos usar o operador ? com Option, teríamos de implementar essa lógica usando mais chamadas de método ou uma expressão match.

Observe que você pode usar o operador ? sobre um Result em uma função que retorna Result, e pode usar o operador ? sobre um Option em uma função que retorna Option, mas não pode misturar os dois casos livremente. O operador ? não converte automaticamente Result em Option, nem vice-versa. Nesses casos, você pode usar métodos como ok em Result ou ok_or em Option para fazer a conversão explicitamente.

Até aqui, todas as funções main que usamos retornaram (). A função main é especial porque é o ponto de entrada e o ponto de saída de um programa executável, e há restrições sobre qual pode ser seu tipo de retorno para que o programa se comporte como esperado.

Felizmente, main também pode retornar Result<(), E>. A Listagem 9-12 traz o código da Listagem 9-10, mas com o tipo de retorno de main alterado para Result<(), Box<dyn Error>> e com um valor de retorno Ok(()) adicionado ao fim. Esse código agora compila.

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

O tipo Box<dyn Error> é um trait object, assunto sobre o qual falaremos em “Usando Trait Objects para Abstrair sobre Comportamento Compartilhado” no Capítulo 18. Por enquanto, você pode ler Box<dyn Error> como “qualquer tipo de erro”. Usar ? em um valor Result dentro de uma função main cujo tipo de erro é Box<dyn Error> é permitido porque isso deixa qualquer valor Err ser retornado antecipadamente. Mesmo que o corpo dessa função main retorne apenas erros do tipo std::io::Error, ao especificar Box<dyn Error> essa assinatura continuará correta mesmo se mais código que retorne outros erros for adicionado ao corpo de main.

Quando uma função main retorna Result<(), E>, o executável sai com valor 0 se main retornar Ok(()) e sai com um valor diferente de zero se main retornar um valor Err. Executáveis escritos em C retornam inteiros quando encerram: programas que terminam com sucesso retornam o inteiro 0, e programas que falham retornam algum inteiro diferente de 0. O Rust também retorna inteiros a partir de executáveis para ser compatível com essa convenção.

A função main pode retornar qualquer tipo que implemente a trait std::process::Termination, que contém uma função report que retorna um ExitCode. Consulte a documentação da biblioteca padrão para mais informações sobre como implementar a trait Termination para seus próprios tipos.

Agora que discutimos os detalhes de chamar panic! ou retornar Result, vamos voltar ao tópico de como decidir qual dessas abordagens é a apropriada em cada caso.

Usar ou Não Usar panic!

Para panic! ou não para panic!

Então, como decidir quando você deve chamar panic! e quando deve retornar Result? Quando o código entra em panic, não há como se recuperar. Você até poderia chamar panic! para qualquer situação de erro, exista ou não uma forma possível de recuperação, mas aí estaria tomando a decisão de que uma situação é irrecuperável em nome do código chamador. Quando você escolhe retornar um valor Result, oferece opções ao código chamador. O código chamador pode optar por tentar se recuperar de uma maneira adequada ao seu contexto ou decidir que um valor Err, naquele caso, é irrecuperável e então chamar panic!, transformando o erro recuperável em irrecuperável. Por isso, retornar Result costuma ser a melhor escolha padrão ao definir uma função que pode falhar.

Em situações como exemplos, código de protótipo e testes, é mais apropriado escrever código que entra em panic em vez de retornar Result. Vamos explorar o porquê e, depois, discutir situações em que o compilador não consegue saber que uma falha é impossível, mas você, como humano, consegue. O capítulo termina com algumas diretrizes gerais sobre como decidir se deve entrar em panic em código de biblioteca.

Exemplos, Código de Protótipo e Testes

Quando você está escrevendo um exemplo para ilustrar algum conceito, incluir também um código robusto de tratamento de erros pode tornar o exemplo menos claro. Em exemplos, entende-se que uma chamada a um método como unwrap, que pode entrar em panic, serve como marcador do modo como sua aplicação deverá tratar erros, o que pode variar de acordo com o restante do código.

Da mesma forma, os métodos unwrap e expect são muito úteis quando você está prototipando e ainda não está pronto para decidir como tratar erros. Eles deixam marcadores claros no código para o momento em que você estiver pronto para tornar o programa mais robusto.

Se uma chamada de método falhar em um teste, você vai querer que o teste inteiro falhe, mesmo que aquele método não seja a funcionalidade que está sendo testada. Como panic! é a forma de um teste ser marcado como falho, chamar unwrap ou expect é exatamente o comportamento desejado.

Quando Você Tem Mais Informações que o Compilador

Também pode ser apropriado chamar expect quando você tiver alguma outra lógica que garanta que o Result terá um valor Ok, mas essa lógica não seja algo que o compilador consiga entender. Você ainda terá um valor Result que precisa tratar: a operação que você está chamando ainda tem a possibilidade de falhar em termos gerais, mesmo que isso seja logicamente impossível no seu caso específico. Se você puder garantir, inspecionando o código manualmente, que nunca terá uma variante Err, é perfeitamente aceitável chamar expect e documentar, no texto do argumento, por que você acredita que nunca haverá uma variante Err. Veja um exemplo:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

Estamos criando uma instância de IpAddr fazendo o parse de uma string fixa no código. Podemos ver que 127.0.0.1 é um endereço IP válido, então é aceitável usar expect aqui. No entanto, ter uma string válida e hardcoded não altera o tipo de retorno do método parse: continuamos recebendo um valor Result, e o compilador continua exigindo que o tratemos como se a variante Err fosse uma possibilidade, porque ele não é inteligente o bastante para perceber que essa string é sempre um endereço IP válido. Se a string do endereço IP viesse de uma pessoa usuária em vez de estar hardcoded no programa e, portanto, pudesse falhar, com certeza quereríamos tratar o Result de forma mais robusta. Mencionar a suposição de que esse endereço IP está fixo no código nos lembrará de substituir expect por um tratamento de erro melhor se, no futuro, precisarmos obter o endereço IP de outra fonte.

Diretrizes para Tratamento de Erros

É recomendável que seu código entre em panic quando houver a possibilidade de ele acabar em um estado ruim. Nesse contexto, um estado ruim é quando alguma suposição, garantia, contrato ou invariante foi quebrado, como quando valores inválidos, contraditórios ou ausentes são passados para o seu código, somado a uma ou mais das condições a seguir:

• O estado ruim é algo inesperado, em oposição a algo que provavelmente acontecerá de vez em quando, como uma pessoa usuária digitando dados no formato errado.
• O seu código, depois desse ponto, precisa confiar no fato de não estar nesse estado ruim, em vez de checar o problema a cada etapa.
• Não existe uma boa forma de codificar essa informação nos tipos que você usa. Veremos um exemplo do que isso significa em “Encoding States and Behavior as Types” no Capítulo 18.

Se alguém chamar seu código e passar valores que não fazem sentido, o melhor é retornar um erro, se possível, para que a pessoa usuária da biblioteca possa decidir o que deseja fazer naquele caso. No entanto, quando continuar possa ser inseguro ou prejudicial, a melhor escolha pode ser chamar panic! e alertar quem estiver usando sua biblioteca de que há um bug no código chamador, para que ele possa ser corrigido durante o desenvolvimento. Do mesmo modo, panic! costuma ser apropriado quando você chama código externo, fora do seu controle, e ele retorna um estado inválido que você não tem como corrigir.

No entanto, quando a falha é esperada, é mais apropriado retornar um Result do que chamar panic!. Exemplos disso incluem um parser recebendo dados mal formados ou uma requisição HTTP retornando um status que indique que você atingiu um limite de taxa. Nesses casos, retornar Result indica que a falha é uma possibilidade esperada e que o código chamador precisa decidir como tratá-la.

Quando seu código executa uma operação que pode colocar uma pessoa usuária em risco se for chamada com valores inválidos, ele deve primeiro verificar se os valores são válidos e entrar em panic se não forem. Isso acontece principalmente por razões de segurança: tentar operar com dados inválidos pode expor o código a vulnerabilidades. Essa é a principal razão pela qual a biblioteca padrão chama panic! se você tentar acessar memória fora dos limites: tentar acessar memória que não pertence à estrutura de dados atual é um problema de segurança comum. Funções frequentemente têm contratos: seu comportamento só é garantido se as entradas atenderem a determinados requisitos. Entrar em panic quando o contrato é violado faz sentido porque uma violação de contrato sempre indica um bug do lado do chamador, e não é um tipo de erro que você queira que o código chamador tenha de tratar explicitamente. Na prática, não existe uma forma razoável de o código chamador se recuperar; os programadores que o escrevem é que precisam corrigir o código. Contratos de uma função, especialmente quando sua violação causar um panic, devem ser explicados na documentação da API dessa função.

No entanto, ter muitas verificações de erro em todas as funções seria verboso e cansativo. Felizmente, você pode usar o sistema de tipos do Rust, e portanto a verificação de tipos feita pelo compilador, para que muitas dessas checagens sejam feitas por você. Se a sua função recebe um tipo específico como parâmetro, você pode seguir com a lógica do código sabendo que o compilador já garantiu a validade desse valor. Por exemplo, se você tem um tipo em vez de um Option, o programa espera ter alguma coisa em vez de nada. Assim, o seu código não precisa tratar dois casos, Some e None: ele só terá o caso em que há definitivamente um valor. Código que tente passar “nada” para a sua função simplesmente nem compilará, então a sua função não precisa verificar esse caso em tempo de execução. Outro exemplo é usar um tipo inteiro sem sinal, como u32, o que garante que o parâmetro nunca seja negativo.

Tipos Personalizados para Validação

Vamos levar um passo adiante a ideia de usar o sistema de tipos do Rust para garantir que temos um valor válido e ver como criar um tipo personalizado para validação. Lembre-se do jogo de adivinhação do Capítulo 2, no qual nosso código pedia que a pessoa usuária adivinhasse um número entre 1 e 100. Nunca validamos se o palpite da pessoa usuária estava entre esses números antes de compará-lo com o número secreto; apenas validamos que o palpite era positivo. Nesse caso, as consequências não eram tão graves: a saída “Muito alto” ou “Muito baixo” ainda estaria correta. Mas seria uma melhoria útil orientar a pessoa usuária para palpites válidos e ter um comportamento diferente quando o palpite estiver fora do intervalo, em vez de quando a pessoa digitar, por exemplo, letras.

Uma maneira de fazer isso seria converter o palpite para i32 em vez de apenas u32, para permitir números potencialmente negativos, e então adicionar uma checagem para ver se o número está no intervalo, assim:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        // --snip--

        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: i32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --snip--
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

A expressão if verifica se o valor está fora do intervalo, informa a pessoa usuária sobre o problema e chama continue para iniciar a próxima iteração do loop e pedir outro palpite. Depois da expressão if, podemos seguir com as comparações entre guess e o número secreto sabendo que guess está entre 1 e 100.

No entanto, essa não é uma solução ideal: se fosse absolutamente crítico que o programa operasse apenas com valores entre 1 e 100 e tivesse muitas funções com esse requisito, repetir uma checagem como essa em todas elas seria tedioso, e talvez até afetasse o desempenho.

Em vez disso, podemos criar um novo tipo em um módulo dedicado e colocar as validações em uma função que cria uma instância desse tipo, em vez de repetir as validações em todo lugar. Dessa forma, as funções podem usar com segurança o novo tipo em suas assinaturas e confiar nos valores que recebem. A Listagem 9-13 mostra uma forma de definir um tipo Guess que só cria uma instância de Guess se a função new receber um valor entre 1 e 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Observe que esse código em src/guessing_game.rs depende da adição de uma declaração de módulo mod guessing_game; em src/lib.rs, que não mostramos aqui. Dentro do arquivo desse novo módulo, definimos uma struct chamada Guess, que tem um campo chamado value contendo um i32. É ali que o número ficará armazenado.

Em seguida, implementamos em Guess uma função associada chamada new, que cria instâncias de valores Guess. A função new recebe um parâmetro chamado value, do tipo i32, e retorna um Guess. O código dentro de new testa value para garantir que ele está entre 1 e 100. Se value não passar nesse teste, fazemos uma chamada a panic!, o que alertará a pessoa programadora que está escrevendo o código chamador de que existe um bug a corrigir, porque criar um Guess com um value fora desse intervalo violaria o contrato do qual Guess::new depende. As condições em que Guess::new pode entrar em panic devem ser discutidas na documentação pública de sua API; veremos convenções de documentação que indicam a possibilidade de panic! na documentação de API que você escrever no Capítulo 14. Se value passar no teste, criamos um novo Guess com seu campo value definido com base no parâmetro value e retornamos esse Guess.

A seguir, implementamos um método chamado value, que toma emprestado self, não recebe outros parâmetros e retorna um i32. Esse tipo de método às vezes é chamado de getter, porque seu propósito é obter algum dado dos campos e retorná-lo. Esse método público é necessário porque o campo value da struct Guess é privado. É importante que value seja privado para que o código que usa a struct Guess não possa defini-lo diretamente: código fora do módulo guessing_game deve usar a função Guess::new para criar uma instância de Guess, garantindo assim que não exista maneira de um Guess ter um value que não tenha sido validado pelas condições da função Guess::new.

Uma função que receba um parâmetro ou retorne apenas números entre 1 e 100 pode então declarar em sua assinatura que recebe ou retorna um Guess em vez de um i32, sem precisar fazer qualquer checagem adicional no corpo.

Resumo

Os recursos de tratamento de erros do Rust foram projetados para ajudar você a escrever código mais robusto. A macro panic! sinaliza que o programa está em um estado com o qual não consegue lidar e permite que você mande o processo parar, em vez de tentar continuar com dados inválidos ou incorretos. O enum Result usa o sistema de tipos do Rust para indicar que certas operações podem falhar de um modo do qual o seu código pode se recuperar. Você pode usar Result para dizer ao código que chama o seu que ele também precisa lidar com a possibilidade de sucesso ou falha. Usar panic! e Result nas situações apropriadas tornará seu código mais confiável diante dos problemas inevitáveis.

Agora que você viu maneiras úteis pelas quais a biblioteca padrão usa genéricos com os enums Option e Result, vamos falar sobre como genéricos funcionam e como você pode usá-los no seu próprio código.

Tipos Genéricos, Traits e Lifetimes

Toda linguagem de programação tem ferramentas para lidar de forma eficaz com a duplicação de conceitos. Em Rust, uma dessas ferramentas são os genéricos: substitutos abstratos para tipos concretos ou outras propriedades. Podemos expressar o comportamento de genéricos ou como eles se relacionam com outros genéricos sem saber o que estará em seu lugar quando o código for compilado e executado.

Funções podem receber parâmetros de algum tipo genérico, em vez de um tipo concreto como i32 ou String, da mesma forma que recebem parâmetros com valores desconhecidos para executar o mesmo código sobre vários valores concretos. Na verdade, já usamos genéricos no Capítulo 6 com Option<T>, no Capítulo 8 com Vec<T> e HashMap<K, V>, e no Capítulo 9 com Result<T, E>. Neste capítulo, você vai explorar como definir seus próprios tipos, funções e métodos com genéricos!

Primeiro, vamos revisar como extrair uma função para reduzir duplicação de código. Em seguida, usaremos a mesma técnica para criar uma função genérica a partir de duas funções que diferem apenas nos tipos de seus parâmetros. Também explicaremos como usar tipos genéricos em definições de structs e enums.

Depois, você vai aprender a usar traits para definir comportamento de maneira genérica. Você pode combinar traits com tipos genéricos para restringir um tipo genérico a aceitar apenas tipos que tenham um comportamento específico, em vez de aceitar qualquer tipo.

Por fim, discutiremos lifetimes: uma variedade de genéricos que fornece ao compilador informações sobre como referências se relacionam entre si. Lifetimes nos permitem dar ao compilador informações suficientes sobre valores emprestados para que ele possa garantir que referências serão válidas em mais situacões do que conseguiria sem a nossa ajuda.

Removendo Duplicação Extraindo uma Função

Genéricos nos permitem substituir tipos específicos por um placeholder que representa múltiplos tipos, removendo duplicação de código. Antes de mergulhar na sintaxe dos genéricos, vamos primeiro ver como remover duplicação de uma forma que não envolva tipos genéricos, extraindo uma função que substitui valores específicos por um placeholder que representa vários valores. Depois, vamos aplicar a mesma técnica para extrair uma função genérica! Ao observar como reconhecer código duplicado que pode ser extraído para uma função, você começará a reconhecer código duplicado que pode usar genéricos.

Vamos começar com o pequeno programa da Listagem 10-1, que encontra o maior número em uma lista.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
    assert_eq!(*largest, 100);
}

Armazenamos uma lista de inteiros na variável number_list e colocamos uma referência ao primeiro número da lista em uma variável chamada largest. Depois, iteramos por todos os números da lista e, se o número atual for maior do que o número armazenado em largest, substituímos a referência nessa variável. No entanto, se o número atual for menor ou igual ao maior número visto até aquele momento, a variável não muda, e o código segue para o próximo número da lista. Depois de considerar todos os números da lista, largest deverá se referir ao maior número, que neste caso é 100.

Agora recebemos a tarefa de encontrar o maior número em duas listas diferentes de números. Para isso, podemos escolher duplicar o código da Listagem 10-1 e usar a mesma lógica em dois lugares diferentes do programa, como mostrado na Listagem 10-2.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
}

Embora esse código funcione, duplicar código é tedioso e propenso a erros. Também precisamos lembrar de atualizar o código em vários lugares quando quisermos mudá-lo.

Para eliminar essa duplicação, vamos criar uma abstração definindo uma função que opere sobre qualquer lista de inteiros passada como parâmetro. Essa solução deixa nosso código mais claro e nos permite expressar de forma abstrata o conceito de encontrar o maior número de uma lista.

Na Listagem 10-3, extraímos o código que encontra o maior número para uma função chamada largest. Depois, chamamos essa função para encontrar o maior número nas duas listas da Listagem 10-2. Também poderíamos usar a função em qualquer outra lista de valores i32 que venhamos a ter no futuro.

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 6000);
}

A função largest tem um parâmetro chamado list, que representa qualquer fatia concreta de valores i32 que possamos passar para a função. Como resultado, quando chamamos a função, o código é executado sobre os valores específicos que fornecemos.

Em resumo, estas foram as etapas que usamos para transformar o código da Listagem 10-2 em código como o da Listagem 10-3:

1. Identificar código duplicado.
2. Extrair o código duplicado para o corpo de uma função e especificar as entradas e os valores de retorno desse código na assinatura da função.
3. Atualizar as duas instâncias do código duplicado para chamar a função.

A seguir, vamos usar essas mesmas etapas com genéricos para reduzir duplicação de código. Da mesma forma que o corpo da função pode operar sobre uma list abstrata em vez de valores específicos, genéricos permitem que o código opere sobre tipos abstratos.

Por exemplo, digamos que tivéssemos duas funções: uma encontra o maior item em uma fatia de valores i32, e a outra encontra o maior item em uma fatia de valores char. Como eliminaríamos essa duplicação? Vamos descobrir!

Tipos de Dados Genéricos

Tipos de Dados Genéricos

Usamos genéricos para criar definições de itens como assinaturas de função ou structs, que depois podemos usar com muitos tipos concretos de dados. Vamos primeiro ver como definir funções, structs, enums e métodos usando genéricos. Depois, discutiremos como os genéricos afetam o desempenho do código.

Em Definições de Função

Ao definir uma função que usa genéricos, colocamos os genéricos na assinatura da função, onde normalmente especificaríamos os tipos de dados dos parâmetros e do valor de retorno. Fazer isso torna nosso código mais flexível e oferece mais funcionalidade para quem chama a função, evitando duplicação de código.

Continuando com nossa função largest, a Listagem 10-4 mostra duas funções que ambas encontram o maior valor em uma fatia. Em seguida, vamos combiná-las em uma única função usando genéricos.

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
    assert_eq!(*result, 'y');
}

A função largest_i32 é aquela que extraímos na Listagem 10-3, que encontra o maior i32 em uma fatia. A função largest_char encontra o maior char em uma fatia. Os corpos das duas funções têm o mesmo código, então vamos eliminar a duplicação introduzindo um parâmetro de tipo genérico em uma única função.

Para parametrizar os tipos nessa nova função única, precisamos dar um nome ao parâmetro de tipo, assim como fazemos com parâmetros de valor de uma função. Você pode usar qualquer identificador como nome do parâmetro de tipo. Mas vamos usar T porque, por convenção, nomes de parâmetros de tipo em Rust são curtos, geralmente com apenas uma letra, e a convenção de nomenclatura de tipos em Rust é UpperCamelCase. Como abreviação de type, T é a escolha padrão da maioria dos programadores Rust.

Quando usamos um parâmetro no corpo da função, precisamos declarar seu nome na assinatura para que o compilador saiba o que ele significa. Da mesma forma, quando usamos um nome de parâmetro de tipo em uma assinatura de função, precisamos declarar esse nome antes de usá-lo. Para definir a função genérica largest, colocamos as declarações de nome de tipo dentro de colchetes angulares, <>, entre o nome da função e a lista de parâmetros, assim:

fn largest<T>(list: &[T]) -> &T {

Lemos essa definição como: “A função largest é genérica sobre algum tipo T.” Essa função tem um parâmetro chamado list, que é uma fatia de valores do tipo T. A função largest retornará uma referência a um valor do mesmo tipo T.

A Listagem 10-5 mostra a definição combinada da função largest usando o tipo de dado genérico em sua assinatura. A listagem também mostra como podemos chamar a função tanto com uma fatia de valores i32 quanto com valores char. Observe que esse código ainda não compila.

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

Se compilarmos esse código agora, obteremos este erro:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T` with trait `PartialOrd`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

For more information about this error, try `rustc --explain E0369`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

O texto de ajuda menciona std::cmp::PartialOrd, que é uma trait, e vamos falar sobre traits na próxima seção. Por enquanto, basta saber que esse erro afirma que o corpo de largest não funciona para todos os tipos possíveis que T poderia representar. Como queremos comparar valores do tipo T dentro do corpo, só podemos usar tipos cujos valores possam ser ordenados. Para habilitar comparações, a biblioteca padrão fornece a trait std::cmp::PartialOrd, que você pode implementar em tipos. Veja o Apêndice C para mais informações sobre essa trait. Para corrigir a Listagem 10-5, podemos seguir a sugestão do texto de ajuda e restringir os tipos válidos para T apenas àqueles que implementam PartialOrd. A listagem então compilará, porque a biblioteca padrão implementa PartialOrd tanto em i32 quanto em char.

Em Definições de Struct

Também podemos definir structs para usar um parâmetro de tipo genérico em um ou mais campos usando a sintaxe <>. A Listagem 10-6 define uma struct Point<T> para armazenar valores de coordenadas x e y de qualquer tipo.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

A sintaxe para usar genéricos em definições de struct é parecida com a usada em definições de função. Primeiro, declaramos o nome do parâmetro de tipo entre colchetes angulares logo após o nome da struct. Depois, usamos o tipo genérico na definição da struct onde, de outra forma, especificaríamos tipos concretos.

Observe que, como usamos apenas um tipo genérico para definir Point<T>, essa definição diz que a struct Point<T> é genérica sobre algum tipo T, e que os campos x e y são ambos desse mesmo tipo, seja ele qual for. Se criarmos uma instância de Point<T> com valores de tipos diferentes, como na Listagem 10-7, nosso código não compilará.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

Neste exemplo, quando atribuímos o valor inteiro 5 a x, deixamos o compilador saber que o tipo genérico T será um inteiro para essa instância de Point<T>. Depois, quando especificamos 4.0 para y, que definimos como tendo o mesmo tipo de x, receberemos um erro de incompatibilidade de tipos assim:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

For more information about this error, try `rustc --explain E0308`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

Para definir uma struct Point em que x e y sejam genéricos, mas possam ter tipos diferentes, podemos usar múltiplos parâmetros de tipo genérico. Por exemplo, na Listagem 10-8, alteramos a definição de Point para ser genérica sobre os tipos T e U, em que x é do tipo T e y é do tipo U.

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

Agora todas as instâncias de Point mostradas são permitidas! Você pode usar quantos parâmetros de tipo genérico quiser em uma definição, mas usar mais do que alguns torna o código difícil de ler. Se você perceber que precisa de muitos tipos genéricos no seu código, isso pode indicar que ele precisa ser reestruturado em partes menores.

Em Definições de Enum

Assim como fizemos com structs, podemos definir enums para armazenar tipos de dado genéricos em suas variantes. Vamos dar outra olhada no enum Option<T> fornecido pela biblioteca padrão, que usamos no Capítulo 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Essa definição agora deve fazer mais sentido para você. Como pode ver, o enum Option<T> é genérico sobre o tipo T e tem duas variantes: Some, que contém um valor do tipo T, e None, que não contém valor algum. Usando o enum Option<T>, podemos expressar o conceito abstrato de um valor opcional, e, como Option<T> é genérico, podemos usar essa abstração independentemente do tipo do valor opcional.

Enums também podem usar vários tipos genéricos. A definição do enum Result, que usamos no Capítulo 9, é um exemplo:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

O enum Result é genérico sobre dois tipos, T e E, e tem duas variantes: Ok, que contém um valor do tipo T, e Err, que contém um valor do tipo E. Essa definição torna conveniente usar o enum Result em qualquer lugar em que temos uma operação que pode ter sucesso, retornando um valor de algum tipo T, ou falhar, retornando um erro de algum tipo E. Na verdade, foi isso que usamos para abrir um arquivo na Listagem 9-3, em que T foi preenchido com o tipo std::fs::File quando o arquivo foi aberto com sucesso, e E foi preenchido com o tipo std::io::Error quando houve problemas ao abrir o arquivo.

Quando você reconhece situações no código com múltiplas definições de structs ou enums que diferem apenas nos tipos de valores que armazenam, pode evitar duplicação usando tipos genéricos.

Em Definições de Método

Podemos implementar métodos em structs e enums, como fizemos no Capítulo 5, e usar tipos genéricos em suas definições também. A Listagem 10-9 mostra a struct Point<T> que definimos na Listagem 10-6 com um método chamado x implementado nela.

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Aqui, definimos um método chamado x em Point<T> que retorna uma referência aos dados no campo x.

Observe que precisamos declarar T logo após impl para que possamos usar T e especificar que estamos implementando métodos no tipo Point<T>. Ao declarar T como tipo genérico depois de impl, o Rust consegue identificar que o tipo entre colchetes angulares em Point é um tipo genérico e não um tipo concreto. Poderíamos ter escolhido um nome diferente para esse parâmetro genérico em relação ao declarado na definição da struct, mas usar o mesmo nome é convencional. Se você escrever um método dentro de um impl que declare um tipo genérico, esse método será definido em qualquer instância do tipo, não importa qual tipo concreto acabe substituindo o tipo genérico.

Também podemos especificar restrições sobre tipos genéricos ao definir métodos no tipo. Poderíamos, por exemplo, implementar métodos apenas em instâncias Point<f32>, em vez de em instâncias Point<T> com qualquer tipo genérico. Na Listagem 10-10, usamos o tipo concreto f32, o que significa que não declaramos nenhum tipo depois de impl.

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Esse código significa que o tipo Point<f32> terá um método distance_from_origin; outras instâncias de Point<T> em que T não seja do tipo f32 não terão esse método definido. O método mede a distância do ponto até a origem, nas coordenadas (0.0, 0.0), e usa operações matemáticas disponíveis apenas para tipos de ponto flutuante.

Os parâmetros de tipo genérico em uma definição de struct nem sempre são os mesmos que você usa nas assinaturas de métodos dessa mesma struct. A Listagem 10-11 usa os tipos genéricos X1 e Y1 para a struct Point e X2 e Y2 para a assinatura do método mixup, para deixar o exemplo mais claro. O método cria uma nova instância de Point com o valor x do Point de self, do tipo X1, e o valor y do Point passado como argumento, do tipo Y2.

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

Em main, definimos um Point que tem um i32 para x, com valor 5, e um f64 para y, com valor 10.4. A variável p2 é uma struct Point que tem uma fatia de string para x, com valor "Hello", e um char para y, com valor c. Chamar mixup em p1 com o argumento p2 nos dá p3, que terá um i32 para x porque x veio de p1. A variável p3 terá um char para y porque y veio de p2. A chamada da macro println! imprimirá p3.x = 5, p3.y = c.

O objetivo desse exemplo é demonstrar uma situação em que alguns parâmetros genéricos são declarados em impl e outros são declarados na definição do método. Aqui, os parâmetros genéricos X1 e Y1 são declarados após impl porque pertencem à definição da struct. Já os parâmetros genéricos X2 e Y2 são declarados após fn mixup porque só são relevantes para esse método.

Desempenho de Código Usando Genéricos

Você talvez esteja se perguntando se existe algum custo em tempo de execução ao usar parâmetros de tipo genérico. A boa notícia é que usar tipos genéricos não fará seu programa rodar mais lentamente do que faria com tipos concretos.

O Rust consegue isso realizando monomorfização do código que usa genéricos em tempo de compilação. Monomorfização é o processo de transformar código genérico em código específico, preenchendo os tipos concretos que são usados na compilação. Nesse processo, o compilador faz o oposto das etapas que usamos para criar a função genérica da Listagem 10-5: ele observa todos os lugares em que o código genérico é chamado e gera código para os tipos concretos com os quais ele foi usado.

Vamos ver como isso funciona usando o enum genérico Option<T> da biblioteca padrão:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Quando o Rust compila esse código, ele realiza monomorfização. Durante esse processo, o compilador lê os valores usados nas instâncias de Option<T> e identifica duas formas de Option<T>: uma é i32, e a outra é f64. Assim, ele expande a definição genérica de Option<T> em duas definições especializadas para i32 e f64, substituindo a definição genérica pelas específicas.

A versão monomorfizada do código é parecida com a seguinte, embora o compilador use nomes diferentes dos que estamos usando aqui apenas para ilustração:

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

O genérico Option<T> é substituído pelas definições específicas criadas pelo compilador. Como o Rust compila código genérico em código que especifica o tipo em cada instância, não pagamos custo de tempo de execução por usar genéricos. Quando o código roda, ele se comporta exatamente como se tivéssemos duplicado cada definição manualmente. O processo de monomorfização torna os genéricos do Rust extremamente eficientes em tempo de execução.

Definindo Comportamento Compartilhado com Traits

Definindo Comportamento Compartilhado com Características

Uma trait define a funcionalidade que um tipo específico possui e pode compartilhar com outros tipos. Podemos usar traits para descrever comportamento compartilhado de forma abstrata. Também podemos usar trait bounds para especificar que um tipo genérico pode ser qualquer tipo que tenha determinado comportamento.

Nota: traits são parecidas com um recurso frequentemente chamado de interfaces em outras linguagens, embora existam algumas diferenças.

Definindo uma Trait

O comportamento de um tipo consiste nos métodos que podemos chamar nesse tipo. Tipos diferentes compartilham o mesmo comportamento quando podemos chamar os mesmos métodos em todos eles. Definições de trait são uma forma de agrupar assinaturas de métodos para definir um conjunto de comportamentos necessários para atingir algum objetivo.

Por exemplo, digamos que temos várias structs que armazenam tipos e quantidades diferentes de texto: uma struct NewsArticle, que representa uma notícia publicada em algum local, e um SocialPost, que pode ter no máximo 280 caracteres, além de metadados indicando se se trata de uma nova postagem, um repost ou uma resposta a outra postagem.

Queremos criar um crate de biblioteca agregador de mídia chamado aggregator, capaz de exibir resumos de dados que podem estar armazenados em uma instância de NewsArticle ou SocialPost. Para isso, precisamos de um resumo de cada tipo e vamos solicitá-lo chamando um método summarize na instância. A Listagem 10-12 mostra a definição de uma trait pública Summary que expressa esse comportamento.

pub trait Summary {
    fn summarize(&self) -> String;
}

Aqui, declaramos uma trait usando a palavra-chave trait seguida do nome da trait, que neste caso é Summary. Também a declaramos como pub, para que crates que dependam deste crate possam usá-la, como veremos em alguns exemplos. Dentro das chaves, declaramos as assinaturas dos métodos que descrevem os comportamentos dos tipos que implementam essa trait; neste caso, temos fn summarize(&self) -> String.

Depois da assinatura do método, em vez de fornecer uma implementação entre chaves, usamos um ponto e vírgula. Cada tipo que implementar essa trait deverá fornecer seu próprio comportamento para o corpo do método. O compilador garante que qualquer tipo que implemente Summary terá o método summarize definido exatamente com essa assinatura.

Uma trait pode ter vários métodos no corpo: as assinaturas são listadas uma por linha, e cada linha termina com ponto e vírgula.

Implementando uma Trait em um Tipo

Agora que definimos as assinaturas desejadas para os métodos da trait Summary, podemos implementá-la nos tipos do nosso agregador de mídia. A Listagem 10-13 mostra uma implementação de Summary para a struct NewsArticle, usando título, autor e local para construir o valor retornado por summarize. Para a struct SocialPost, definimos summarize como o nome de usuário seguido do texto inteiro da postagem, assumindo que esse conteúdo já está limitado a 280 caracteres.

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Implementar uma trait em um tipo é parecido com implementar métodos comuns. A diferença é que, depois de impl, colocamos o nome da trait que queremos implementar, usamos a palavra-chave for e então especificamos o nome do tipo para o qual queremos implementar a trait. Dentro do bloco impl, colocamos as assinaturas dos métodos definidos pela trait. Em vez de terminar cada assinatura com ponto e vírgula, usamos chaves e preenchemos o corpo do método com o comportamento específico que queremos para aquele tipo.

Agora que a biblioteca implementa a trait Summary em NewsArticle e SocialPost, usuários do crate podem chamar os métodos da trait em instâncias desses tipos da mesma forma que chamamos métodos comuns. A única diferença é que o usuário precisa trazer para o escopo tanto a trait quanto os tipos. Aqui está um exemplo de como um crate binário poderia usar nosso crate de biblioteca aggregator:

use aggregator::{SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

Esse código imprime 1 new post: horse_ebooks: of course, as you probably already know, people.

Outros crates que dependem de aggregator também podem trazer a trait Summary para o escopo e implementá-la em seus próprios tipos. Há, porém, uma restrição importante: só podemos implementar uma trait em um tipo se a trait, o tipo, ou ambos, forem locais ao nosso crate. Por exemplo, podemos implementar traits da biblioteca padrão, como Display, em um tipo personalizado como SocialPost dentro do nosso crate aggregator, porque o tipo SocialPost é local. Também podemos implementar Summary em Vec<T> em nosso crate aggregator, porque a trait Summary é local ao crate.

Mas não podemos implementar traits externas em tipos externos. Por exemplo, não podemos implementar Display para Vec<T> dentro do crate aggregator, porque tanto Display quanto Vec<T> são definidos na biblioteca padrão e, portanto, não são locais ao nosso crate. Essa restrição faz parte de uma propriedade chamada coerência e, mais especificamente, da chamada regra órfã (orphan rule). Essa regra garante que o código de outras pessoas não quebrará o seu, e vice-versa. Sem ela, dois crates poderiam implementar a mesma trait para o mesmo tipo, e o Rust não saberia qual implementação usar.

Usando Implementações Padrão

Às vezes é útil ter um comportamento padrão para alguns ou todos os métodos de uma trait, em vez de exigir implementações para todos os métodos em todos os tipos. Assim, ao implementar a trait em um tipo específico, podemos manter ou substituir o comportamento padrão de cada método.

Na Listagem 10-14, especificamos uma string padrão para o método summarize da trait Summary, em vez de definir apenas sua assinatura, como fizemos na Listagem 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Para usar uma implementação padrão para resumir instâncias de NewsArticle, basta especificar um bloco impl vazio com impl Summary for NewsArticle {}.

Mesmo sem definir summarize diretamente em NewsArticle, fornecemos uma implementação padrão e especificamos que NewsArticle implementa a trait Summary. Como resultado, ainda podemos chamar summarize em uma instância de NewsArticle, assim:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

Esse código imprime New article available! (Read more...).

Criar uma implementação padrão não exige que mudemos nada na implementação de Summary em SocialPost na Listagem 10-13. Isso porque a sintaxe para substituir uma implementação padrão é a mesma usada para implementar um método de trait que não tem implementação padrão.

Implementações padrão podem chamar outros métodos da mesma trait, mesmo que esses outros métodos não tenham implementação padrão. Dessa forma, uma trait pode oferecer bastante funcionalidade útil e exigir que os implementadores especifiquem apenas uma pequena parte dela. Por exemplo, poderíamos definir a trait Summary com um método summarize_author, cuja implementação seria obrigatória, e depois definir um método summarize com implementação padrão que chama summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Para usar essa versão de Summary, precisamos apenas definir summarize_author ao implementar a trait em um tipo:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Depois de definir summarize_author, podemos chamar summarize em instâncias da struct SocialPost, e a implementação padrão de summarize chamará a definição de summarize_author que fornecemos. Como implementamos summarize_author, a trait Summary nos fornece o comportamento de summarize sem exigir nenhum código extra. O resultado fica assim:

use aggregator::{self, SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

Esse código imprime 1 new post: (Read more from @horse_ebooks...).

Observe que não é possível chamar a implementação padrão a partir de uma implementação que substitui esse mesmo método.

Usando Traits como Parâmetros

Agora que você já sabe como definir e implementar traits, podemos explorar como usá-las para definir funções que aceitam muitos tipos diferentes. Usaremos a trait Summary, implementada para NewsArticle e SocialPost na Listagem 10-13, para definir uma função notify que chama o método summarize em seu parâmetro item, que é de algum tipo que implementa Summary. Para fazer isso, usamos a sintaxe impl Trait, assim:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

Em vez de um tipo concreto para o parâmetro item, especificamos a palavra- chave impl e o nome da trait. Esse parâmetro aceita qualquer tipo que implemente a trait especificada. No corpo de notify, podemos chamar em item qualquer método proveniente da trait Summary, como summarize. Podemos chamar notify passando qualquer instância de NewsArticle ou SocialPost. Já um código que tente chamar a função com qualquer outro tipo, como String ou i32, não compilará, porque esses tipos não implementam Summary.

Sintaxe de Trait Bounds

A sintaxe impl Trait funciona bem em casos simples, mas na verdade é um syntax sugar para uma forma mais longa, conhecida como trait bound:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

Essa forma mais longa é equivalente ao exemplo da seção anterior, apenas mais verbosa. Colocamos o trait bound na declaração do parâmetro de tipo genérico, depois de dois-pontos e dentro dos colchetes angulares.

A sintaxe impl Trait é conveniente e gera código mais conciso em casos simples, enquanto a forma completa com trait bounds pode expressar situações mais complexas. Por exemplo, podemos ter dois parâmetros que implementam Summary. Com a sintaxe impl Trait, isso fica assim:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

Usar impl Trait é apropriado se quisermos permitir que item1 e item2 tenham tipos diferentes, contanto que ambos implementem Summary. Se quisermos forçar que ambos os parâmetros tenham o mesmo tipo, porém, devemos usar um trait bound, assim:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

O tipo genérico T, usado tanto em item1 quanto em item2, restringe a função de modo que o tipo concreto passado como argumento para ambos os parâmetros precisa ser o mesmo.

Múltiplos Trait Bounds com a Sintaxe +

Também podemos especificar mais de um trait bound. Digamos que queremos que notify use formatação de exibição, além de summarize em item: nesse caso, especificamos na definição de notify que item deve implementar Display e Summary. Podemos fazer isso usando a sintaxe +:

pub fn notify(item: &(impl Summary + Display)) {

A sintaxe + também funciona com trait bounds em tipos genéricos:

pub fn notify<T: Summary + Display>(item: &T) {

Com os dois trait bounds especificados, o corpo de notify pode chamar summarize e usar {} para formatar item.

Trait Bounds Mais Claros com Cláusulas where

Usar muitos trait bounds tem suas desvantagens. Cada tipo genérico recebe seus próprios limites, então funções com vários parâmetros genéricos podem acabar com muita informação espremida entre o nome da função e a lista de parâmetros, o que torna a assinatura difícil de ler. Por isso, o Rust oferece uma sintaxe alternativa para especificar trait bounds dentro de uma cláusula where, após a assinatura da função. Assim, em vez de escrever isto:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

podemos usar uma cláusula where, assim:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

A assinatura dessa função fica menos confusa: o nome da função, a lista de parâmetros e o tipo de retorno ficam próximos uns dos outros, como em uma função sem muitos trait bounds.

Retornando Tipos que Implementam Traits

Também podemos usar a sintaxe impl Trait na posição de retorno para devolver um valor de algum tipo que implemente uma trait, como mostrado aqui:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    }
}

Ao usar impl Summary como tipo de retorno, estamos especificando que a função returns_summarizable retorna algum tipo que implementa a trait Summary, sem nomear qual é esse tipo concreto. Neste caso, returns_summarizable retorna SocialPost, mas o código que chama a função não precisa saber disso.

A capacidade de especificar um tipo de retorno apenas pela trait que ele implementa é especialmente útil no contexto de closures e iteradores, que veremos no Capítulo 13. Closures e iteradores produzem tipos que só o compilador conhece ou que seriam longos demais para escrever. A sintaxe impl Trait permite declarar de forma concisa que uma função retorna algum tipo que implementa a trait Iterator, sem precisar escrever um tipo enorme.

No entanto, só podemos usar impl Trait quando a função retorna um único tipo. Por exemplo, este código, que retorna NewsArticle ou SocialPost com o tipo de retorno especificado como impl Summary, não funcionaria:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        SocialPost {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            repost: false,
        }
    }
}

Não é permitido retornar NewsArticle ou SocialPost por causa das restrições de como impl Trait é implementado no compilador. Veremos como escrever uma função com esse comportamento na seção “Usando Trait Objects para Abstrair Comportamento Compartilhado” do Capítulo 18.

Usando Trait Bounds para Implementar Métodos Condicionalmente

Ao usar trait bounds em um bloco impl com parâmetros de tipo genérico, podemos implementar métodos condicionalmente para tipos que satisfaçam os limites especificados. Por exemplo, o tipo Pair<T> da Listagem 10-15 sempre implementa o método new, que retorna uma nova instância de Pair<T>. Lembre-se, da seção “Sintaxe de Método” do Capítulo 5, que Self é um alias para o tipo do bloco impl, que aqui é Pair<T>. Mas, no bloco impl seguinte, Pair<T> só implementa o método cmp_display se seu tipo interno T implementar PartialOrd, que permite comparação, e Display, que permite impressão.

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

Também podemos implementar condicionalmente uma trait para qualquer tipo que implemente outra trait. Implementações de uma trait para qualquer tipo que satisfaça determinados trait bounds são chamadas de implementações gerais e são muito usadas na biblioteca padrão do Rust. Por exemplo, a biblioteca padrão implementa a trait ToString para qualquer tipo que implemente Display. O bloco impl correspondente na biblioteca padrão se parece com algo assim:

impl<T: Display> ToString for T {
    // --snip--
}

Como a biblioteca padrão tem essa implementação geral, podemos chamar o método to_string, definido pela trait ToString, em qualquer tipo que implemente Display. Por exemplo, podemos transformar inteiros em seus valores String correspondentes porque inteiros implementam Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Implementações gerais aparecem na documentação da trait na seção “Implementors”.

Traits e trait bounds nos permitem escrever código com parâmetros de tipo genérico para reduzir duplicação e, ao mesmo tempo, especificar ao compilador que queremos que o tipo genérico tenha determinado comportamento. O compilador pode então usar essas informações para verificar se todos os tipos concretos usados no código fornecem o comportamento correto. Em linguagens de tipagem dinâmica, receberíamos um erro em tempo de execução se chamássemos um método em um tipo que não o define. Em Rust, esses erros são antecipados para o tempo de compilação, de modo que somos obrigados a corrigi-los antes mesmo de executar o código. Além disso, não precisamos escrever checagens de comportamento em tempo de execução, porque tudo já foi validado na compilação. Isso melhora o desempenho sem abrir mão da flexibilidade oferecida pelos genéricos.

Validando Referências com Lifetimes

Validando Referências com Lifetimes

Lifetimes são outro tipo de genérico que já vimos em uso. Em vez de garantir que um tipo tenha o comportamento que queremos, lifetimes garantem que referências continuem válidas pelo tempo que precisamos delas.

Um detalhe que não discutimos na seção “Referências e Empréstimos”, no Capítulo 4, é que toda referência em Rust tem um lifetime, que é o escopo durante o qual essa referência é válida. Na maior parte do tempo, lifetimes são implícitos e inferidos, assim como geralmente acontece com tipos. Só precisamos anotar tipos quando mais de um tipo é possível. De forma parecida, precisamos anotar lifetimes quando os lifetimes de referências podem se relacionar de algumas maneiras diferentes. O Rust exige que anotemos essas relações usando parâmetros genéricos de lifetime, para garantir que as referências concretas usadas em tempo de execução sejam de fato válidas.

Anotar lifetimes não é sequer um conceito presente na maioria das outras linguagens de programação, então isso provavelmente vai parecer pouco familiar. Embora não cubramos lifetimes por completo neste capítulo, vamos discutir as formas mais comuns em que essa sintaxe aparece para que você se acostume com a ideia.

Referências Pendentes

O principal objetivo dos lifetimes é evitar referências pendentes, que, se fossem permitidas, fariam um programa referenciar dados diferentes daqueles que ele pretendia referenciar. Considere o programa da Listagem 10-16, que tem um escopo externo e um escopo interno.

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

Nota: os exemplos das Listagens 10-16, 10-17 e 10-23 declaram variáveis sem lhes dar um valor inicial, de modo que o nome da variável existe no escopo externo. À primeira vista, isso pode parecer entrar em conflito com o fato de Rust não ter valores nulos. No entanto, se tentarmos usar uma variável antes de lhe atribuir um valor, receberemos um erro em tempo de compilação, o que mostra que Rust realmente não permite valores nulos.

O escopo externo declara uma variável chamada r sem valor inicial, e o escopo interno declara uma variável chamada x com o valor inicial 5. Dentro do escopo interno, tentamos definir o valor de r como uma referência a x. Depois, o escopo interno termina e tentamos imprimir o valor em r. Esse código não compila, porque o valor ao qual r se refere saiu de escopo antes de tentarmos usá-lo. Aqui está a mensagem de erro:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
5 |         let x = 5;
  |             - binding `x` declared here
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {r}");
  |                   - borrow later used here

For more information about this error, try `rustc --explain E0597`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

A mensagem de erro diz que a variável x “não vive tempo suficiente”. O motivo é que x sai de escopo quando o escopo interno termina na linha 7. Mas r ainda é válido no escopo externo; como seu escopo é maior, dizemos que ele “vive mais”. Se Rust permitisse esse código, r ficaria apontando para uma região de memória que já teria sido desalocada quando x saísse de escopo, e qualquer tentativa de usar r produziria comportamento incorreto. Como o Rust determina que esse código é inválido? Ele usa o borrow checker.

O Borrow Checker

O compilador Rust possui um borrow checker que compara escopos para determinar se todos os empréstimos são válidos. A Listagem 10-17 mostra o mesmo código da Listagem 10-16, mas com anotações exibindo os lifetimes das variáveis.

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {r}");   //          |
}                         // ---------+

Aqui, anotamos o lifetime de r com 'a e o de x com 'b. Como você pode ver, o bloco interno 'b é muito menor que o bloco externo 'a. Em tempo de compilação, o Rust compara o tamanho desses dois lifetimes e percebe que r tem lifetime 'a, mas aponta para uma memória com lifetime 'b. O programa é rejeitado porque 'b é menor que 'a: o valor referenciado não vive tanto quanto a referência.

A Listagem 10-18 corrige o código para que ele não tenha uma referência pendente, e então ele compila sem erros.

fn main() {
    let x = 5;            // ----------+-- 'b
                          //           |
    let r = &x;           // --+-- 'a  |
                          //   |       |
    println!("r: {r}");   //   |       |
                          // --+       |
}                         // ----------+

Aqui, x tem lifetime 'b, que neste caso é maior que 'a. Isso significa que r pode referenciar x, porque o Rust sabe que a referência em r continuará válida enquanto x for válido.

Agora que você sabe onde estão os lifetimes das referências e como o Rust os analisa para garantir que as referências sejam sempre válidas, vamos explorar lifetimes genéricos em parâmetros de função e valores de retorno.

Lifetimes Genéricos em Funções

Vamos escrever uma função que retorna o mais longo entre dois string slices. Essa função receberá dois string slices e retornará um único string slice. Depois de implementarmos a função longest, o código da Listagem 10-19 deverá imprimir The longest string is abcd.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

Observe que queremos que a função receba string slices, que são referências, em vez de strings, porque não queremos que a função longest assuma ownership de seus parâmetros. Consulte “String Slices como Parâmetros” no Capítulo 4 para uma discussão mais detalhada sobre por que os parâmetros da Listagem 10-19 são os que queremos.

Se tentarmos implementar a função longest como mostrado na Listagem 10-20, ela não compilará.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() { x } else { y }
}