Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Programando um Jogo de Adivinhação

Vamos mergulhar no Rust trabalhando juntos em um projeto prático! Este capítulo apresenta alguns conceitos comuns do Rust, mostrando como usá-los em um programa real. Você vai aprender sobre let, match, métodos, funções associadas, crates externos e muito mais! Nos capítulos seguintes, vamos explorar essas ideias com mais detalhes. Neste capítulo, você vai apenas praticar os fundamentos.

Vamos implementar um problema clássico de programação para iniciantes: um jogo de adivinhação. Veja como ele funciona: o programa vai gerar um número inteiro aleatório entre 1 e 100. Depois, vai pedir que o jogador digite um palpite. Após um palpite ser digitado, o programa vai indicar se o palpite é baixo ou alto demais. Se o palpite estiver certo, o jogo vai exibir uma mensagem de parabéns e encerrar.

Criando um Novo Projeto

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

$ 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 muda para o diretório do novo projeto.

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, o cargo new gera um programa “Hello, world!” para você. Dê uma olhada no arquivo src/main.rs:

Nome do arquivo: src/main.rs

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

Agora vamos compilar este programa “Hello, world!” e executá-lo na mesma 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 vamos fazer neste jogo, testando rapidamente cada iteração antes de passar para a próxima.

Reabra o arquivo src/main.rs. Você vai escrever todo o código neste arquivo.

Processando um Palpite

A primeira parte do programa do jogo de adivinhação vai pedir a entrada do usuário, processar essa entrada e verificar se ela está na forma esperada. Para começar, vamos permitir que o jogador digite um palpite. Digite o código da Listagem 2-1 em src/main.rs.

Nome do arquivo: 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}");
}
Listagem 2-1: Código que obtém um palpite do usuário e o imprime

Este código contém muitas informações, então vamos examiná-lo linha por linha. Para obter a entrada do usuário e depois imprimir o resultado como saída, precisamos trazer para o escopo a biblioteca de entrada/saída io. A biblioteca io vem 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, o Rust tem um conjunto de itens definidos na biblioteca padrão que ele traz para o escopo de todo programa. Esse conjunto é chamado de prelúdio (em inglês, prelude), e você pode ver tudo o que ele contém na documentação da biblioteca padrão.

Se um tipo que você quer usar não estiver no prelúdio, você precisa trazê-lo para o escopo explicitamente com uma instrução use. Usar a biblioteca std::io oferece várias funcionalidades úteis, incluindo a capacidade de aceitar a entrada do usuário.

Como você viu no Capítulo 1, a função main é o ponto de entrada do 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}");
}

Este código imprime uma mensagem que informa qual é o jogo e pede que o usuário digite algo.

Armazenando Valores com Variáveis

Em seguida, vamos criar 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 está ficando interessante! Acontece muita coisa nesta pequena linha. Usamos a instrução let para criar a variável. Aqui está outro exemplo:

let apples = 5;

Esta linha cria uma nova variável chamada apples e a associa ao valor 5. No Rust, as variáveis são imutáveis por padrão, o que significa que, depois de dar um valor à variável, esse valor não muda. Vamos discutir 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 continua até o fim da linha. O Rust ignora tudo o que está em comentários. Vamos discutir os comentários com mais detalhes 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 agora. À direita do sinal de igual está o valor ao qual guess será associada, que é o resultado da chamada de String::new, uma função que retorna uma nova instância de uma String. String é um tipo de string fornecido pela biblioteca padrão, um texto expansível, codificado em UTF-8.

A sintaxe :: na linha ::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. Esta função new cria uma nova string vazia. Você vai encontrar uma função new em muitos tipos, porque é um nome comum para uma função que cria um novo valor de algum tipo.

Ao todo, a linha let mut guess = String::new(); criou uma variável mutável que, no momento, está associada a uma nova instância vazia de String. Puxa!

Recebendo a Entrada do Usuário

Lembre que incluímos a funcionalidade de entrada/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 vai nos permitir tratar 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 esta chamada como std::io::stdin. A função stdin retorna uma instância de std::io::Stdin, que é um tipo que representa uma alça (handle) para a entrada padrão do seu terminal.

Em seguida, a linha .read_line(&mut guess) chama o método read_line da alça da entrada padrão para obter a entrada do usuário. Também estamos passando &mut guess como argumento para read_line para indicar em qual string a entrada do usuário deve ser armazenada. O trabalho completo de read_line é pegar tudo o que o usuário digitar na entrada padrão e acrescentar isso a uma string (sem sobrescrever o conteúdo dela), por isso passamos essa string como argumento. O argumento string precisa ser mutável para que o método possa alterar o conteúdo da string.

O & indica que este argumento é uma referência, que oferece uma forma de permitir que várias partes do seu código acessem um mesmo dado sem precisar copiar esse dado para a memória várias vezes. Referências são uma funcionalidade complexa, e uma das grandes vantagens do Rust é quão seguro e fácil é usar referências. Você não precisa conhecer muitos desses detalhes para terminar este programa. Por enquanto, basta saber que, assim como as variáveis, as 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 vai explicar as referências com mais profundidade.)

Tratando Possíveis Falhas com Result

Ainda estamos trabalhando nesta 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 assim:

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

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

Como mencionado antes, read_line coloca o que o usuário digitar na string que passamos para ele, mas também retorna um valor Result. Result é uma enumeração, muitas vezes chamada de enum, que é um tipo que pode estar em um de vários estados possíveis. Chamamos cada estado possível de variante.

O Capítulo 6 vai tratar de enums com mais detalhes. A finalidade desses tipos Result é codificar informações de 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 a operação falhou.

Valores do tipo Result, assim como valores de qualquer tipo, têm métodos definidos neles. Uma instância de Result tem um método expect que você pode chamar. Se esta instância de Result for um valor Err, expect vai fazer o programa travar 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. Se esta instância de Result for um valor Ok, expect vai pegar o valor que Ok está guardando e retornar apenas esse valor para você, para que você possa usá-lo. Nesse caso, esse valor é o número de bytes da entrada do usuário.

Se você não chamar expect, o programa vai compilar, mas você vai 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)]` (part of `#[warn(unused)]`) 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

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

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

Imprimindo Valores com Marcadores em 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}");
}

Esta linha imprime a string que agora contém a entrada do usuário. O conjunto {} de chaves é um marcador: pense em {} como pequenas pinças de caranguejo que seguram um valor no lugar. Ao imprimir o valor de uma variável, o nome da variável pode ir dentro das chaves. Ao imprimir o resultado da avaliação de uma expressão, coloque chaves vazias na string de formato, depois siga a string de formato com uma lista de expressões separadas por vírgula, para serem impressas em cada marcador de chaves vazias, na mesma ordem. Imprimir uma variável e o resultado de uma expressão em uma única chamada de println! ficaria assim:

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

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

Este 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á pronta: estamos recebendo a entrada do teclado e depois imprimindo-a.

Gerando um Número Secreto

Em seguida, precisamos gerar um número secreto que o usuário vai 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 difícil demais. O Rust ainda não inclui funcionalidades de números aleatórios em sua biblioteca padrão. No entanto, a equipe do Rust fornece um crate rand com essa funcionalidade.

Ampliando as Funcionalidades com um Crate

Lembre-se de que um crate é uma coleção de arquivos de código-fonte Rust. O projeto que estamos construindo é um crate binário, ou seja, um executável. O crate rand é um crate de biblioteca, que contém código feito para ser usado em outros programas e que não pode ser executado sozinho.

A coordenação de crates externos pelo Cargo é onde o Cargo realmente brilha. Antes de escrevermos código que usa rand, precisamos modificar o arquivo Cargo.toml para incluir o crate rand como dependência. Abra esse arquivo agora e adicione a linha a seguir no final, abaixo do cabeçalho de seção [dependencies] que o Cargo criou para você. Certifique-se de especificar rand exatamente como fizemos aqui, com este 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.10.1"

No arquivo Cargo.toml, tudo o que segue um cabeçalho faz parte dessa seção, que continua até que outra seção comece. Em [dependencies], você diz ao Cargo de quais crates externos o seu projeto depende e quais versões desses crates você requer. Neste caso, especificamos o crate rand com o especificador de versão semântica 0.10.1. O Cargo entende o Versionamento Semântico (chamado às vezes de SemVer), que é um padrão para escrever números de versão. O especificador 0.10.1 é, na verdade, uma abreviação de ^0.10.1, o que significa qualquer versão que seja pelo menos 0.10.1 e abaixo de 0.11.0.

O Cargo considera que essas versões têm APIs públicas compatíveis com a versão 0.10.1, e essa especificação garante que você vai obter a versão de correção (patch) mais recente que ainda compile com o código deste capítulo. Qualquer versão 0.11.0 ou superior não tem garantia de ter a mesma API que os exemplos a seguir usam.

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

$ cargo build
    Updating crates.io index
     Locking 8 packages to latest Rust 1.96.0 compatible versions
  Downloaded rand_core v0.10.1
  Downloaded chacha20 v0.10.1
  Downloaded rand v0.10.1
  Downloaded 3 crates (162.9KiB) in 0.59s
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling getrandom v0.4.3
   Compiling cfg-if v1.0.4
   Compiling chacha20 v0.10.1
   Compiling rand v0.10.1
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.03s
Listagem 2-2: A saída da execução de cargo build depois de adicionar o crate rand como dependência

Você pode ver números de versão diferentes (mas todos serão compatíveis com o código, graças ao SemVer) e linhas diferentes (dependendo do sistema operacional), e as linhas podem aparecer em outra ordem.

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

Depois de atualizar o registro, o Cargo verifica a seção [dependencies] e baixa quaisquer crates listados que ainda não foram baixados. Neste caso, embora tenhamos listado apenas rand como dependência, o Cargo também baixou outros crates de que rand depende para funcionar. Depois de baixar os crates, o Rust os compila e depois compila o projeto com as dependências disponíveis.

Se você executar cargo build de novo imediatamente, 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 você não alterou nada sobre elas no seu arquivo Cargo.toml. O Cargo também sabe que você não alterou nada no seu código, então também não o recompila. Sem nada a fazer, ele simplesmente encerra.

Se você abrir o arquivo src/main.rs, fizer uma alteração trivial, salvar 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 só atualiza a compilação com a sua pequena alteração no arquivo src/main.rs. Suas dependências não mudaram, então o Cargo sabe que pode reutilizar o que já baixou e compilou para elas.

Garantindo Builds Reprodutíveis

O Cargo tem um mecanismo que garante que você possa recompilar o mesmo artefato toda vez que você ou qualquer outra pessoa compilar o seu código: o Cargo vai usar apenas as versões das dependências que você especificou, até que você indique o contrário. Por exemplo, suponha que, na semana que vem, a versão 0.10.2 do crate rand seja lançada, e que essa versão contenha uma correção de bug importante, mas também uma regressão que quebre o seu código. Para lidar com isso, o 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 as grava no arquivo Cargo.lock. Quando você compilar o seu projeto no futuro, o Cargo vai ver que o arquivo Cargo.lock existe e vai usar as versões especificadas ali, em vez de refazer todo o trabalho de descobrir as versões de novo. Isso permite que você tenha um build reprodutível automaticamente. Em outras palavras, o seu projeto vai continuar na 0.10.1 até que você faça uma atualização explícita, graças ao arquivo Cargo.lock. Como o arquivo Cargo.lock é importante para builds reprodutíveis, ele costuma ser versionado junto com o restante do código do projeto.

Atualizando um Crate para Obter uma Nova Versão

Quando você quer atualizar um crate, o Cargo oferece o comando update, que ignora o arquivo Cargo.lock e descobre todas as versões mais recentes que atendem às suas especificações no Cargo.toml. Em seguida, o Cargo grava essas versões no arquivo Cargo.lock. Caso contrário, por padrão, o Cargo só vai procurar versões maiores que 0.10.1 e menores que 0.11.0. Se o crate rand tiver lançado as duas novas versões 0.10.2 e 0.999.0, você veria o seguinte ao executar cargo update:

$ cargo update
    Updating crates.io index
     Locking 1 package to latest Rust 1.96.0 compatible version
    Updating rand v0.10.1 -> v0.10.2 (available: v0.999.0)

O Cargo ignora a versão 0.999.0. Nesse momento, você também notaria uma mudança no seu arquivo Cargo.lock indicando que a versão do crate rand que você está usando agora é a 0.10.2. Para usar a versão 0.999.0 do rand, ou qualquer versão da série 0.999.x, você precisaria atualizar o arquivo Cargo.toml para ficar assim (não faça essa alteração de fato, porque os exemplos a seguir pressupõem que você está usando o rand 0.10):

[dependencies]
rand = "0.999.0"

Na próxima vez que você executar cargo build, o Cargo vai atualizar o registro de crates disponíveis e reavaliar os seus requisitos de rand de acordo com a nova versão que você especificou.

Há muito mais a dizer sobre o Cargo e o seu ecossistema, que vamos discutir no Capítulo 14, mas, por enquanto, isso é tudo o que você precisa saber. O Cargo torna muito fácil reutilizar bibliotecas, então os Rustaceans conseguem escrever projetos menores montados a partir de vários pacotes.

Gerando um Número Aleatório

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

Nome do arquivo: src/main.rs
use std::io;

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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}");
}
Listagem 2-3: Adicionando código para gerar um número aleatório

Primeiro, adicionamos a linha use rand::prelude::*;. O módulo prelude contém as partes mais usadas do crate rand, e use deixa esses itens disponíveis no escopo do nosso programa.

Em seguida, estamos adicionando duas linhas no meio. Na primeira linha, chamamos a função rand::rng, que nos dá o gerador de números aleatórios que vamos usar: um que é local à thread de execução atual e que é inicializado (seeded) pelo sistema operacional. Depois, chamamos o método random_range no gerador de números aleatórios. Esse método é definido pelo trait RngExt, que faz parte do módulo rand::prelude que trouxemos para o escopo com a instrução use rand::prelude::*;. O método random_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 é inclusivo nos limites inferior e superior, então precisamos especificar 1..=100 para pedir um número entre 1 e 100.

Nota: Você não vai saber, apenas por intuição, o que trazer para o escopo e quais métodos e funções chamar de um crate, por isso cada crate tem documentação com instruções para usá-lo. Outro recurso interessante do Cargo é que executar o comando cargo doc --open vai gerar localmente a documentação fornecida por todas as suas dependências e abri-la no navegador. Se você tiver interesse em outras funcionalidades do crate rand, por exemplo, execute cargo doc --open e clique em rand na barra lateral à esquerda.

A segunda linha nova imprime o número secreto. Isso é útil enquanto desenvolvemos o programa, para podermos testá-lo, mas vamos apagá-la na versão final. Não seria muito divertido se o programa mostrasse a resposta assim que começasse!

Experimente 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 devem estar entre 1 e 100. Se aparecerem avisos (warnings), pode ignorá-los com segurança. Se aparecerem erros, verifique se você tem rand = "0.10.1" no seu Cargo.toml, já que versões futuras do rand podem ter uma API diferente, mas qualquer versão da série 0.10 deve funcionar com o código deste capítulo.

Comparando o Palpite com o Número Secreto

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

Nome do arquivo: src/main.rs
use std::cmp::Ordering;
use std::io;

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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!"),
    }
}
Listagem 2-4: Tratando os possíveis valores de retorno da comparação entre dois números

Primeiro, adicionamos mais uma instrução use, trazendo para o escopo um tipo chamado std::cmp::Ordering da biblioteca padrão. 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.

Depois, adicionamos cinco novas linhas no final 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: aqui, 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 em seguida, com base em qual variante de Ordering foi retornada pela chamada de cmp com os valores em guess e secret_number.

Uma expressão match é formada por braços. Um braço consiste em um padrão com o qual comparar e no código que deve ser executado se o valor passado para match corresponder ao padrão desse braço. O Rust pega o valor passado para match e percorre o padrão de cada braço, um por vez. Padrões e a construção match são recursos poderosos do Rust: eles permitem expressar uma variedade de situações que o seu código pode encontrar e garantem que você trate todas elas. Esses recursos serão cobertos em detalhes no Capítulo 6 e no Capítulo 19, respectivamente.

Vamos percorrer um exemplo com a expressão match que usamos aqui. Suponha que o usuário 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 vai retornar 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 passa para o próximo. O padrão do próximo braço é Ordering::Greater, que corresponde a Ordering::Greater! O código associado a esse braço vai ser executado e imprimir Too big! na tela. A expressão match termina após a primeira correspondência bem-sucedida, então, neste cenário, ela não olha para o último braço.

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

$ cargo build
   Compiling libc v0.2.186
   Compiling getrandom v0.4.3
   Compiling rand_core v0.10.1
   Compiling cfg-if v1.0.0
   Compiling chacha20 v0.10.1
   Compiling rand v0.10.1
   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/58cf8f9c35b355199727627d07ae34a4e2846d67/library/core/src/cmp.rs:1012:7

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

O núcleo do erro afirma que há tipos incompatíveis (mismatched types). O Rust tem um sistema de tipos forte e estático. No entanto, ele também tem inferência de tipos. Quando escrevemos let mut guess = String::new(), o Rust conseguiu inferir que guess deveria ser uma String e não nos fez escrever o tipo. Já secret_number é um tipo numérico. Alguns dos tipos numéricos do Rust podem ter um valor entre 1 e 100: i32, um número de 32 bits; u32, um número sem sinal de 32 bits; i64, um número de 64 bits; além de outros. Salvo indicação em contrário, o Rust usa i32 por padrão, que é o tipo de secret_number, a menos que você adicione informação de tipo em outro lugar que faça o Rust inferir um tipo numérico diferente. O motivo do erro é que o Rust não consegue comparar um tipo string com um tipo numérico.

No fim das contas, queremos converter a String que o programa lê como entrada em um tipo numérico, para podermos compará-la numericamente com o número secreto. Fazemos isso adicionando esta linha ao corpo da função main:

Nome do arquivo: src/main.rs

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

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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 chamada guess? Tem, mas, de forma útil, o Rust permite sombrear (shadow) o valor anterior de guess com um novo. O sombreamento (shadowing) nos permite reutilizar o nome da variável guess em vez de forçar a criação de duas variáveis únicas, como guess_str e guess, por exemplo. Vamos cobrir isso com mais detalhes no Capítulo 3, mas, por enquanto, saiba que esse recurso costuma ser usado quando você quer converter um valor de um tipo para outro tipo.

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 elimina qualquer espaço em branco no início e no fim, o que precisamos fazer antes de converter a string para um u32, que só pode conter dados numéricos. O usuário precisa pressionar enter para satisfazer o read_line e enviar o seu palpite, o que adiciona um caractere de nova linha à string. Por exemplo, se o usuário digitar 5 e pressionar enter, guess fica assim: 5\n. O \n representa “nova linha”. (No Windows, pressionar enter resulta em um retorno de carro e uma nova linha, \r\n.) O método trim elimina \n ou \r\n, resultando apenas em 5.

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

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

O método parse só funciona com caracteres que podem ser convertidos logicamente em números e, por isso, pode facilmente causar erros. Se, por exemplo, a string contiver A👍%, não haveria como converter isso em um número. Como pode falhar, o método parse retorna um tipo Result, assim como o método read_line faz (discutido anteriormente em “Tratando Possíveis Falhas com Result”). Vamos tratar esse Result da mesma forma, usando o método expect novamente. Se parse retornar a variante Err de Result por não conseguir criar um número a partir da string, a chamada de expect vai travar o jogo e imprimir a mensagem que passamos a ele. Se parse conseguir converter a string em um número com sucesso, ele vai retornar a variante Ok de Result, e expect vai 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 adicionados antes do palpite, o programa conseguiu descobrir que o usuário chutou 76. Execute o programa algumas vezes para verificar o comportamento diferente com diferentes tipos de entrada: acertar o número, chutar um número alto demais e chutar um número baixo demais.

Já temos a maior parte do jogo funcionando, mas o usuário só pode fazer um palpite. Vamos mudar isso adicionando um laço (loop)!

Permitindo Vários Palpites com Laços

A palavra-chave loop cria um laço infinito. Vamos adicionar um laço para dar aos usuários mais chances de adivinhar o número:

Nome do arquivo: src/main.rs

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

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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, desde o pedido de palpite até o final, para dentro de um laço. Certifique-se de indentar as linhas dentro do laço mais quatro espaços cada uma e execute o programa novamente. Agora o programa vai pedir outro palpite para sempre, o que na verdade introduz um novo problema. Parece que o usuário não consegue sair!

O usuário sempre pode interromper o programa usando o atalho de teclado ctrl-C. Mas há outra forma de escapar desse monstro insaciável, como mencionado na discussão do parse em “Comparando o Palpite com o Número Secreto”: se o usuário digitar uma resposta que não seja um número, o programa vai travar. Podemos aproveitar isso para permitir que o usuário saia, como mostrado aqui:

$ 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' (6694925) 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 vai encerrar o jogo, mas, como você vai notar, qualquer outra entrada que não seja um número também vai. Isso é, no mínimo, subótimo; queremos que o jogo também pare quando o número correto for adivinhado.

Saindo Depois de um Palpite Correto

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

Nome do arquivo: src/main.rs

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

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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 depois de You win! faz o programa sair do laço quando o usuário acerta o número secreto. Sair do laço também significa sair do programa, porque o laço é a última parte de main.

Tratando Entradas Inválidas

Para refinar ainda mais o comportamento do jogo, em vez de travar o programa quando o usuário digita algo que não é um número, vamos fazer o jogo ignorar entradas que não sejam números, para que o usuário possa continuar tentando. Podemos fazer isso alterando a linha em que guess é convertida de String para u32, como mostrado na Listagem 2-5.

Nome do arquivo: src/main.rs
use std::cmp::Ordering;
use std::io;

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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;
            }
        }
    }
}
Listagem 2-5: Ignorando um palpite que não é número e pedindo outro palpite em vez de travar o programa

Trocamos uma chamada de expect por uma expressão match para passar de travar diante de um erro para tratar o erro. Lembre-se de que parse retorna um tipo Result, e Result é um enum que tem as variantes Ok e Err. Estamos usando uma expressão match aqui, assim como fizemos com o resultado Ordering do método cmp.

Se parse conseguir transformar a string em um número com sucesso, vai retornar um valor Ok que contém o número resultante. Esse valor Ok vai corresponder ao padrão do primeiro braço, e a expressão match simplesmente vai retornar o valor num que parse produziu e colocou dentro do valor Ok. Esse número vai acabar exatamente onde queremos, na nova variável guess que estamos criando.

Se parse não conseguir transformar a string em um número, vai retornar um valor Err que contém mais informações sobre o erro. O valor Err não corresponde ao padrão Ok(num) do primeiro braço, mas corresponde ao padrão Err(_) do segundo braço. O sublinhado, _, é um valor coringa; neste exemplo, estamos dizendo que queremos corresponder a todos os valores Err, não importa qual informação eles tenham dentro. Então, o programa vai executar o código do segundo braço, continue, que diz ao programa para ir para a próxima iteração do loop e pedir outro palpite. Ou seja, na prática, o programa ignora todos os erros que parse possa encontrar!

Agora tudo no programa deve funcionar como esperado. Vamos testar:

$ 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!

Ótimo! Com mais um pequeno ajuste final, terminamos o jogo de adivinhação. Lembre que o programa ainda imprime o número secreto. Isso funcionou bem para testar, mas estraga o jogo. Vamos apagar o println! que imprime o número secreto. A Listagem 2-6 mostra o código final.

Nome do arquivo: src/main.rs
use std::cmp::Ordering;
use std::io;

use rand::prelude::*;

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

    let secret_number = rand::rng().random_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;
            }
        }
    }
}
Listagem 2-6: Código completo do jogo de adivinhação

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

Resumo

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