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

Программирование игры «Угадай число»

Давайте окунёмся в Rust, вместе проработав практический проект! Эта глава познакомит вас с несколькими общими концепциями Rust, показав, как использовать их в реальной программе. Вы узнаете о let, match, методах, ассоциированных функциях, внешних крейтах и многом другом! В последующих главах мы рассмотрим эти идеи более подробно. В этой главе вы просто попрактикуетесь в основах.

Мы реализуем классическую учебную задачу по программированию: игру по угадыванию числа. Вот как она работает: программа генерирует случайное целое число от 1 до 100. Затем она предлагает игроку ввести догадку. После ввода догадки программа сообщает, слишком ли она мала или слишком велика. Если догадка верна, игра выводит поздравление и завершается.

Настройка нового проекта

Чтобы настроить новый проект, перейдите в каталог projects, который вы создали в главе 1, и создайте новый проект с помощью Cargo, вот так:

$ cargo new guessing_game
$ cd guessing_game

Первая команда, cargo new, принимает имя проекта (guessing_game) в качестве первого аргумента. Вторая команда переходит в каталог нового проекта.

Взгляните на сгенерированный файл Cargo.toml:

Имя файла: Cargo.toml

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

[dependencies]

Как вы видели в главе 1, cargo new генерирует для вас программу «Hello, world!». Взгляните на файл src/main.rs:

Имя файла: src/main.rs

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

Теперь скомпилируем эту программу «Hello, world!» и запустим её за один шаг с помощью команды 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!

Команда run удобна, когда нужно быстро итерировать по проекту, как мы будем делать в этой игре, быстро проверяя каждую итерацию перед переходом к следующей.

Снова откройте файл src/main.rs. Весь код в этой главе вы будете писать в этом файле.

Обработка догадки

Первая часть программы игры по угадыванию будет запрашивать ввод пользователя, обрабатывать этот ввод и проверять, что ввод имеет ожидаемую форму. Для начала мы позволим игроку ввести догадку. Введите код из листинга 2-1 в src/main.rs.

Имя файла: 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}");
}
Листинг 2-1: Код, который получает догадку от пользователя и выводит её

Этот код содержит много информации, поэтому давайте разберём его строка за строкой. Чтобы получить пользовательский ввод и затем вывести результат, нам нужно подключить библиотеку ввода-вывода io. Библиотека io происходит из стандартной библиотеки, известной как 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}");
}

По умолчанию Rust имеет набор элементов, определённых в стандартной библиотеке, которые он подключает в область видимости каждой программы. Этот набор называется прелюдией, и вы можете увидеть всё в нём в документации стандартной библиотеки.

Если тип, который вы хотите использовать, не входит в прелюдию, вам нужно явно подключить этот тип в область видимости с помощью инструкции use. Использование библиотеки std::io предоставляет вам ряд полезных возможностей, включая возможность принимать пользовательский ввод.

Как вы видели в главе 1, функция main является точкой входа в программу:

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}");
}

Синтаксис fn объявляет новую функцию; круглые скобки () указывают, что параметров нет; а фигурная скобка { открывает тело функции.

Как вы также узнали в главе 1, println! — это макрос, который выводит строку на экран:

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}");
}

Этот код выводит приглашение, сообщающее, что это за игра, и запрашивает ввод от пользователя.

Хранение значений с помощью переменных

Далее мы создадим переменную для хранения пользовательского ввода, вот так:

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}");
}

Теперь программа становится интересной! В этой маленькой строке много всего происходит. Мы используем инструкцию let для создания переменной. Вот ещё пример:

let apples = 5;

Эта строка создаёт новую переменную с именем apples и привязывает её к значению 5. В Rust переменные по умолчанию неизменяемы, что означает, что после присвоения переменной значения оно не изменится. Мы подробно обсудим эту концепцию в разделе «Переменные и изменяемость» главы 3. Чтобы сделать переменную изменяемой, мы добавляем mut перед именем переменной:

let apples = 5; // неизменяемая
let mut bananas = 5; // изменяемая

Примечание: Синтаксис // начинает комментарий, который продолжается до конца строки. Rust игнорирует всё в комментариях. Мы обсудим комментарии более подробно в главе 3.

Возвращаясь к программе игры по угадыванию, вы теперь знаете, что let mut guess введёт изменяемую переменную с именем guess. Знак равенства (=) сообщает Rust, что мы хотим привязать что-то к переменной сейчас. Справа от знака равенства находится значение, к которому привязана guess, — это результат вызова String::new, функции, которая возвращает новый экземпляр String. String — это строковый тип, предоставляемый стандартной библиотекой, который является расширяемым фрагментом текста в кодировке UTF-8.

Синтаксис :: в строке ::new указывает, что new — это ассоциированная функция типа String. Ассоциированная функция — это функция, реализованная для типа, в данном случае для String. Эта функция new создаёт новую пустую строку. Вы найдёте функцию new у многих типов, потому что это распространённое имя для функции, создающей новое значение какого-либо рода.

Полностью строка let mut guess = String::new(); создала изменяемую переменную, которая в настоящее время привязана к новому, пустому экземпляру String. Ух!

Получение пользовательского ввода

Вспомните, что мы подключили функциональность ввода-вывода из стандартной библиотеки с помощью use std::io; в первой строке программы. Теперь мы вызовем функцию stdin из модуля io, которая позволит нам обрабатывать пользовательский ввод:

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}");
}

Если бы мы не импортировали модуль io с помощью use std::io; в начале программы, мы всё равно могли бы использовать функцию, записав этот вызов как std::io::stdin. Функция stdin возвращает экземпляр std::io::Stdin, который является типом, представляющим дескриптор стандартного ввода для вашего терминала.

Далее, строка .read_line(&mut guess) вызывает метод read_line у дескриптора стандартного ввода, чтобы получить ввод от пользователя. Мы также передаём &mut guess в качестве аргумента в read_line, чтобы сообщить ей, в какую строку сохранить ввод пользователя. Полная задача read_line — принять всё, что пользователь вводит в стандартный ввод, и добавить это в строку (без перезаписи её содержимого), поэтому мы передаём эту строку в качестве аргумента. Строковый аргумент должен быть изменяемым, чтобы метод мог изменить содержимое строки.

Символ & указывает, что этот аргумент является ссылкой, которая даёт вам способ позволить нескольким частям вашего кода обращаться к одному фрагменту данных без необходимости копировать эти данные в память несколько раз. Ссылки — сложная функция, и одно из главных преимуществ Rust — это то, насколько безопасно и просто использовать ссылки. Вам не нужно знать много этих деталей, чтобы закончить эту программу. Пока всё, что вам нужно знать, — это то, что, как и переменные, ссылки по умолчанию неизменяемы. Следова­ тельно, вам нужно написать &mut guess, а не &guess, чтобы сделать её изменяемой. (глава 4 более подробно объяснит ссылки.)

Обработка потенциальной ошибки с помощью Result

Мы всё ещё работаем над этой строкой кода. Сейчас мы обсуждаем третью строку текста, но обратите внимание, что это всё ещё часть одной логической строки кода. Следующая часть — это метод:

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}");
}

Мы могли бы написать этот код так:

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

Однако одну длинную строку трудно читать, поэтому лучше разделить её. Часто разумно вводить перевод строки и другие пробельные символы, чтобы разбить длинные строки, когда вы вызываете метод с синтаксисом .method_name(). Теперь давайте обсудим, что делает эта строка.

Как упоминалось ранее, read_line помещает всё, что вводит пользователь, в строку, которую мы ей передаём, но она также возвращает значение Result. Result — это перечисление, часто называемое enum, то есть тип, который может находиться в одном из нескольких возможных состояний. Мы называем каждое возможное состояние вариантом.

Глава 6 более подробно рассмотрит перечисления. Назначение этих типов Result — кодировать информацию об обработке ошибок.

Варианты Result — это Ok и Err. Вариант Ok указывает, что операция успешна, и содержит успешно сгенерированное значение. Вариант Err означает, что операция не удалась, и содержит информацию о том, как или почему операция не удалась.

Значения типа Result, как и значения любого типа, имеют определённые на них методы. Экземпляр Result имеет метод expect, который вы можете вызвать. Если этот экземпляр Result является значением Err, expect вызовет сбой программы и отобразит сообщение, которое вы передали в качестве аргумента в expect. Если метод read_line возвращает Err, это, вероятно, будет результатом ошибки, исходящей от базовой операционной системы. Если этот экземпляр Result является значением Ok, expect возьмёт возвращаемое значение, которое хранит Ok, и вернёт вам только это значение, чтобы вы могли его использовать. В данном случае это значение — количество байтов во вводе пользователя.

Если вы не вызовете expect, программа скомпилируется, но вы получите предупреждение:

$ 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

Rust предупреждает, что вы не использовали значение Result, возвращённое из read_line, указывая, что программа не обработала возможную ошибку.

Правильный способ подавить предупреждение — действительно написать код обработки ошибок, но в нашем случае мы просто хотим, чтобы программа завершилась при возникновении проблемы, поэтому мы можем использовать expect. Вы узнаете о восстановлении после ошибок в главе 9.

Вывод значений с помощью заполнителей println!

Помимо закрывающей фигурной скобки, в коде на данный момент осталась только одна строка для обсуждения:

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}");
}

Эта строка выводит строку, которая теперь содержит пользовательский ввод. Набор фигурных скобок {} — это заполнитель: думайте о {} как о маленьких клешнях краба, которые удерживают значение на месте. При выводе значения переменной имя переменной может находиться внутри фигурных скобок. При выводе результата вычисления выражения поместите пустые фигурные скобки в строку формата, а затем следуйте за строкой формата списком выражений, разделённых запятыми, для вывода в каждый пустой заполнитель фигурных скобок в том же порядке. Вывод переменной и результата выражения в одном вызове println! выглядел бы так:

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

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

Этот код вывел бы x = 5 and y + 2 = 12.

Тестирование первой части

Давайте протестируем первую часть игры по угадыванию. Запустите её с помощью 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

На этом первая часть игры завершена: мы получаем ввод с клавиатуры и затем выводим его.

Генерация секретного числа

Далее нам нужно сгенерировать секретное число, которое пользователь будет пытаться угадать. Секретное число должно быть разным каждый раз, чтобы в игру было интересно играть больше одного раза. Мы будем использовать случайное число от 1 до 100, чтобы игра не была слишком сложной. Rust пока не включает функциональность случайных чисел в свою стандартную библиотеку. Однако команда Rust предоставляет крейт rand с этой функциональностью.

Расширение функциональности с помощью крейта

Помните, что крейт — это набор файлов исходного кода Rust. Проект, который мы строим, — это бинарный крейт, то есть исполняемый файл. Крейт rand — это библиотечный крейт, который содержит код, предназначенный для использования в других программах и не может выполняться сам по себе.

Координация внешних крейтов в Cargo — вот где Cargo действительно блистает. Прежде чем мы сможем написать код, использующий rand, нам нужно изменить файл Cargo.toml, чтобы включить крейт rand в качестве зависимости. Откройте этот файл сейчас и добавьте следующую строку внизу, под заголовком раздела [dependencies], который Cargo создал для вас. Обязательно укажите rand точно так, как мы здесь, с этим номером версии, иначе примеры кода в этом руководстве могут не работать:

Имя файла: Cargo.toml

[dependencies]
rand = "0.10.1"

В файле Cargo.toml всё, что следует за заголовком, является частью этого раздела, который продолжается до начала другого раздела. В [dependencies] вы сообщаете Cargo, от каких внешних крейтов зависит ваш проект и какие версии этих крейтов вам нужны. В данном случае мы указываем крейт rand с описателем семантической версии 0.10.1. Cargo понимает семантическое версионирование (иногда называемое SemVer), которое является стандартом для записи номеров версий. Описатель 0.10.1 на самом деле является сокращением для ^0.10.1, что означает любую версию не ниже 0.10.1, но ниже 0.11.0.

Cargo считает эти версии имеющими публичные API, совместимые с версией 0.10.1, и эта спецификация гарантирует, что вы получите последний патч-релиз, который всё ещё будет компилироваться с кодом в этой главе. Любая версия 0.11.0 или выше не гарантирует тот же API, что используют следующие примеры.

Теперь, не меняя никакого кода, давайте соберём проект, как показано в листинге 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
Листинг 2-2: Вывод после запуска cargo build после добавления крейта rand в качестве зависимости

Вы можете увидеть другие номера версий (но все они будут совместимы с кодом, благодаря SemVer!) и другие строки (в зависимости от операционной системы), и строки могут быть в другом порядке.

Когда мы включаем внешнюю зависимость, Cargo извлекает последние версии всего, что нужно этой зависимости, из реестра, который является копией данных с Crates.io. Crates.io — это место, где люди в экосистеме Rust публикуют свои проекты с открытым исходным кодом на Rust, чтобы другие могли их использовать.

После обновления реестра Cargo проверяет раздел [dependencies] и загружает любые перечисленные крейты, которые ещё не были загружены. В этом случае, хотя мы указали только rand в качестве зависимости, Cargo также захватил другие крейты, от которых зависит rand для работы. После загрузки крейтов Rust компилирует их, а затем компилирует проект с доступными зависимостями.

Если вы сразу запустите cargo build снова, не внося никаких изменений, вы не получите никакого вывода, кроме строки Finished. Cargo знает, что он уже загрузил и скомпилировал зависимости, и вы ничего не меняли в них в вашем файле Cargo.toml. Cargo также знает, что вы ничего не меняли в вашем коде, поэтому он не перекомпилирует и его. Когда делать нечего, он просто выходит.

Если вы откроете файл src/main.rs, внесёте незначительное изменение, а затем сохраните его и снова соберёте, вы увидите только две строки вывода:

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

Эти строки показывают, что Cargo обновляет сборку только с вашим небольшим изменением в файле src/main.rs. Ваши зависимости не изменились, поэтому Cargo знает, что может повторно использовать то, что он уже загрузил и скомпилировал для них.

Обеспечение воспроизводимых сборок

Cargo имеет механизм, который гарантирует, что вы можете пересобрать тот же артефакт каждый раз, когда вы или кто-либо другой собирает ваш код: Cargo будет использовать только те версии зависимостей, которые вы указали, пока вы не укажете иное. Например, предположим, что на следующей неделе выйдет версия 0.10.2 крейта rand, и эта версия содержит важное исправление ошибки, но она также содержит регрессию, которая сломает ваш код. Чтобы справиться с этим, Rust создаёт файл Cargo.lock при первом запуске cargo build, поэтому теперь у нас есть этот файл в каталоге guessing_game.

Когда вы собираете проект впервые, Cargo выясняет все версии зависимостей, которые соответствуют критериям, а затем записывает их в файл Cargo.lock. Когда вы соберёте свой проект в будущем, Cargo увидит, что файл Cargo.lock существует, и будет использовать указанные там версии вместо того, чтобы проделывать всю работу по определению версий заново. Это позволяет вам автоматически получать воспроизводимую сборку. Другими словами, ваш проект останется на версии 0.10.1, пока вы явно не обновите её, благодаря файлу Cargo.lock. Поскольку файл Cargo.lock важен для воспроизводимых сборок, его часто добавляют в систему контроля версий вместе с остальным кодом вашего проекта.

Обновление крейта для получения новой версии

Когда вы действительно хотите обновить крейт, Cargo предоставляет команду update, которая проигнорирует файл Cargo.lock и выяснит все последние версии, которые соответствуют вашим спецификациям в Cargo.toml. Затем Cargo запишет эти версии в файл Cargo.lock. В противном случае по умолчанию Cargo будет искать только версии больше 0.10.1 и меньше 0.11.0. Если крейт rand выпустил две новые версии 0.10.2 и 0.999.0, вы увидели бы следующее, если бы запустили 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)

Cargo игнорирует релиз 0.999.0. В этот момент вы также заметите изменение в вашем файле Cargo.lock, отмечающее, что версия крейта rand, которую вы теперь используете, — 0.10.2. Чтобы использовать rand версии 0.999.0 или любую версию в серии 0.999.x, вам нужно было бы изменить файл Cargo.toml, чтобы он выглядел так (не делайте это изменение на самом деле, потому что следующие примеры предполагают, что вы используете rand 0.10):

[dependencies]
rand = "0.999.0"

В следующий раз, когда вы запустите cargo build, Cargo обновит реестр доступных крейтов и переоценит ваши требования к rand в соответствии с новой версией, которую вы указали.

Можно многое сказать о Cargo и его экосистеме, что мы обсудим в главе 14, но пока это всё, что вам нужно знать. Cargo делает повторное использование библиотек очень простым, поэтому растацеане могут писать меньшие проекты, собираемые из ряда пакетов.

Генерация случайного числа

Давайте начнём использовать rand для генерации числа, которое нужно угадать. Следующий шаг — обновить src/main.rs, как показано в листинге 2-3.

Имя файла: 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}");
}
Листинг 2-3: Добавление кода для генерации случайного числа

Сначала мы добавляем строку use rand::prelude::*;. Модуль prelude содержит наиболее часто используемые части крейта rand, и use делает эти элементы доступными в области видимости нашей программы.

Далее мы добавляем две строки посередине. В первой строке мы вызываем функцию rand::rng, которая даёт нам конкретный генератор случайных чисел, который мы будем использовать: локальный для текущего потока выполнения и инициализируемый операционной системой. Затем мы вызываем метод random_range у генератора случайных чисел. Этот метод определяется трейтом RngExt, который является частью модуля rand::prelude, который мы подключили в область видимости с помощью инструкции use rand::prelude::*;. Метод random_range принимает выражение диапазона в качестве аргумента и генерирует случайное число в диапазоне. Вид выражения диапазона, который мы здесь используем, имеет форму start..=end и является включающим как для нижней, так и для верхней границы, поэтому нам нужно указать 1..=100, чтобы запросить число от 1 до 100.

Примечание: Вы не просто узнаете, что подключить в область видимости и какие методы и функции вызывать из крейта, поэтому каждый крейт имеет документацию с инструкциями по его использованию. Ещё одна замечательная особенность Cargo заключается в том, что запуск команды cargo doc --open создаст документацию, предоставленную всеми вашими зависимостями локально, и откроет её в вашем браузере. Если вас интересует другая функциональность в крейте rand, например, запустите cargo doc --open и щёлкните rand на боковой панели слева.

Вторая новая строка выводит секретное число. Это полезно, пока мы разрабатываем программу, чтобы иметь возможность её тестировать, но мы удалим её из окончательной версии. Это не очень-то игра, если программа выводит ответ, как только начинается!

Попробуйте запустить программу несколько раз:

$ 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

Вы должны получать разные случайные числа, и все они должны быть числами от 1 до 100. Если вы получаете предупреждения, их можно безопасно игнорировать. Если вы получаете ошибки, пожалуйста, проверьте, что у вас в Cargo.toml указано rand = "0.10.1", так как будущие версии rand могут иметь другой API, но любая версия в серии 0.10 должна работать с кодом в этой главе.

Сравнение догадки с секретным числом

Теперь, когда у нас есть пользовательский ввод и случайное число, мы можем их сравнить. Этот шаг показан в листинге 2-4. Обратите внимание, что этот код пока не скомпилируется, как мы объясним.

Имя файла: 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!"),
    }
}
Листинг 2-4: Обработка возможных возвращаемых значений при сравнении двух чисел

Сначала мы добавляем ещё одну инструкцию use, подключая тип под названием std::cmp::Ordering в область видимости из стандартной библиотеки. Тип Ordering — это ещё одно перечисление, имеющее варианты Less, Greater и Equal. Это три возможных исхода при сравнении двух значений.

Затем мы добавляем пять новых строк внизу, которые используют тип Ordering. Метод cmp сравнивает два значения и может быть вызван для чего угодно, что можно сравнивать. Он принимает ссылку на то, с чем вы хотите сравнить: здесь он сравнивает guess с secret_number. Затем он возвращает вариант перечисления Ordering, которое мы подключили в область видимости с помощью инструкции use. Мы используем выражение match, чтобы решить, что делать дальше, основываясь на том, какой вариант Ordering был возвращён из вызова cmp со значениями guess и secret_number.

Выражение match состоит из ветвей. Ветвь состоит из шаблона, с которым нужно сопоставить, и кода, который должен быть выполнен, если значение, переданное в match, соответствует шаблону этой ветви. Rust берёт значение, переданное в match, и по очереди просматривает шаблон каждой ветви. Шаблоны и конструкция match — мощные возможности Rust: они позволяют вам выражать различные ситуации, с которыми может столкнуться ваш код, и гарантируют, что вы их все обработаете. Эти возможности будут подробно рассмотрены в главе 6 и главе 19 соответственно.

Давайте пройдёмся по примеру с выражением match, которое мы здесь используем. Скажем, пользователь угадал 50, а случайно сгенерированное секретное число в этот раз — 38.

Когда код сравнивает 50 с 38, метод cmp вернёт Ordering::Greater, потому что 50 больше 38. Выражение match получает значение Ordering::Greater и начинает проверять шаблон каждой ветви. Оно смотрит на шаблон первой ветви, Ordering::Less, и видит, что значение Ordering::Greater не соответствует Ordering::Less, поэтому игнорирует код в этой ветви и переходит к следующей. Шаблон следующей ветви — Ordering::Greater, который соответствует Ordering::Greater! Связанный код в этой ветви выполнится и выведет Too big! на экран. Выражение match завершается после первого успешного сопоставления, поэтому оно не будет смотреть на последнюю ветвь в этом сценарии.

Однако код в листинге 2-4 пока не скомпилируется. Давайте попробуем:

$ cargo build
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling getrandom v0.4.3
   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/2d8144b7880597b6e6d3dfd63a9a9efae3f533d3/library/core/src/cmp.rs:1000: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

Суть ошибки в том, что есть несовпадающие типы. Rust имеет сильную, статическую систему типов. Однако у него также есть вывод типов. Когда мы написали let mut guess = String::new(), Rust смог вывести, что guess должен быть String, и не заставил нас писать тип. secret_number, с другой стороны, имеет числовой тип. Несколько числовых типов Rust могут иметь значение от 1 до 100: i32, 32-битное число; u32, беззнаковое 32-битное число; i64, 64-битное число; а также другие. Если не указано иное, Rust по умолчанию использует i32, который является типом secret_number, если вы не добавите информацию о типе где-либо ещё, что заставило бы Rust вывести другой числовой тип. Причина ошибки в том, что Rust не может сравнивать строку и числовой тип.

В конечном счёте, мы хотим преобразовать String, которую программа читает как ввод, в числовой тип, чтобы можно было сравнить её численно с секретным числом. Мы делаем это, добавляя эту строку в тело функции main:

Имя файла: 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!"),
    }
}

Строка такая:

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

Мы создаём переменную с именем guess. Но подождите, разве у программы уже нет переменной с именем guess? Да, но, что полезно, Rust позволяет нам затенять предыдущее значение guess новым. Затенение позволяет нам повторно использовать имя переменной guess, а не заставлять нас создавать две уникальные переменные, такие как guess_str и guess, например. Мы рассмотрим это более подробно в главе 3, но пока знайте, что эта возможность часто используется, когда вы хотите преобразовать значение из одного типа в другой.

Мы привязываем эту новую переменную к выражению guess.trim().parse(). guess в выражении относится к исходной переменной guess, которая содержала ввод в виде строки. Метод trim у экземпляра String удалит любые пробельные символы в начале и конце, что мы должны сделать, прежде чем преобразовать строку в u32, который может содержать только числовые данные. Пользователь должен нажать enter, чтобы удовлетворить read_line и ввести свою догадку, что добавляет символ новой строки в строку. Например, если пользователь вводит 5 и нажимает enter, guess выглядит так: 5\n. Символ \n представляет «новую строку». (В Windows нажатие enter приводит к возврату каретки и новой строке, \r\n.) Метод trim удаляет \n или \r\n, оставляя только 5.

Метод parse у строк преобразует строку в другой тип. Здесь мы используем его для преобразования из строки в число. Нам нужно сообщить Rust точный числовой тип, который мы хотим, используя let guess: u32. Двоеточие (:) после guess сообщает Rust, что мы будем аннотировать тип переменной. Rust имеет несколько встроенных числовых типов; u32, видимый здесь, — это беззнаковое 32-битное целое число. Это хороший выбор по умолчанию для небольшого положительного числа. Вы узнаете о других числовых типах в главе 3.

Кроме того, аннотация u32 в этом примере программы и сравнение с secret_number означает, что Rust выведет, что secret_number также должен быть u32. Итак, теперь сравнение будет между двумя значениями одного типа!

Метод parse будет работать только с символами, которые можно логически преобразовать в числа, и поэтому может легко вызывать ошибки. Если, например, строка содержала A👍%, не было бы способа преобразовать её в число. Поскольку это может не удаться, метод parse возвращает тип Result, так же как и метод read_line (обсуждавшийся ранее в разделе «Обработка потенциальной ошибки с помощью Result»). Мы будем обрабатывать этот Result так же, снова используя метод expect. Если parse возвращает вариант Err Result, потому что он не смог создать число из строки, вызов expect завершит игру и выведет сообщение, которое мы ему дали. Если parse успешно преобразует строку в число, он вернёт вариант Ok Result, и expect вернёт число, которое мы хотим, из значения Ok.

Давайте запустим программу сейчас:

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

Отлично! Даже несмотря на то, что перед догадкой были добавлены пробелы, программа всё равно поняла, что пользователь угадал 76. Запустите программу несколько раз, чтобы проверить различное поведение с разными видами ввода: угадайте число правильно, угадайте число, которое слишком велико, и угадайте число, которое слишком мало.

Теперь у нас работает большая часть игры, но пользователь может сделать только одну догадку. Давайте изменим это, добавив цикл!

Разрешение нескольких догадок с помощью цикла

Ключевое слово loop создаёт бесконечный цикл. Мы добавим цикл, чтобы дать пользователям больше шансов угадать число:

Имя файла: 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!"),
        }
    }
}

Как видите, мы переместили всё, начиная с приглашения ввода догадки, в цикл. Обязательно сделайте отступ в строках внутри цикла ещё на четыре пробела и снова запустите программу. Теперь программа будет запрашивать ещё одну догадку вечно, что на самом деле создаёт новую проблему. Похоже, что пользователь не может выйти!

Пользователь всегда может прервать программу, используя сочетание клавиш ctrl-C. Но есть другой способ сбежать от этого ненасытного монстра, как упоминалось в обсуждении parse в разделе «Сравнение догадки с секретным числом»: если пользователь введёт нечисловой ответ, программа завершится. Мы можем воспользоваться этим, чтобы позволить пользователю выйти, как показано здесь:

$ 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

Ввод quit завершит игру, но, как вы заметите, ввод любого другого нечислового ввода тоже. Это, мягко говоря, неоптимально; мы хотим, чтобы игра также останавливалась, когда угадано правильное число.

Выход после правильной догадки

Давайте запрограммируем игру так, чтобы она завершалась, когда пользователь выигрывает, добавив инструкцию break:

Имя файла: 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}");

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

Добавление строки break после println!("You win!"); заставляет программу выйти из цикла, когда пользователь правильно угадывает секретное число. Выход из цикла также означает выход из программы, потому что цикл является последней частью main.

Обработка неверного ввода

Чтобы ещё больше улучшить игру, вместо того чтобы завершать программу при вводе пользователем нечислового значения, давайте заставим игру игнорировать нечисловое значение, чтобы пользователь мог продолжать угадывать. Мы можем сделать это, изменив строку, где guess преобразуется из String в u32, как показано в листинге 2-5.

Имя файла: 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 = 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;
            }
        }
    }
}
Листинг 2-5: Игнорирование нечислового ввода вместо сбоя программы

Мы переходим от вызова expect к выражению match, чтобы перейти от аварийного завершения при ошибке к её обработке. Помните, что parse возвращает тип Result, а Result — это перечисление с вариантами Ok и Err. Здесь мы используем выражение match, как и с результатом Ordering метода cmp.

Если parse удаётся успешно превратить строку в число, он вернёт значение Ok, содержащее полученное число. Это значение Ok совпадёт с шаблоном первой ветви, и выражение match просто вернёт значение num, которое parse произвёл и поместил внутрь Ok. Это число окажется именно там, где нам нужно, — в новой переменной guess, которую мы создаём.

Если же parse не удаётся превратить строку в число, он вернёт значение Err, содержащее более подробную информацию об ошибке. Значение Err не совпадает с шаблоном Ok(num) в первой ветви match, но совпадает с шаблоном Err(_) во второй ветви. Подчёркивание _ — это универсальный шаблон; в этом примере мы говорим, что хотим сопоставить все значения Err, независимо от того, какая информация находится внутри них. Поэтому программа выполнит код второй ветви, continue, который говорит программе перейти к следующей итерации цикла и запросить ещё одну догадку. Таким образом, программа фактически игнорирует все ошибки, с которыми может столкнуться parse!

Теперь всё в программе должно работать как задумано. Давайте попробуем:

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

Отлично! С одной небольшой доработкой игра по угадыванию завершена. Вспомните, что программа всё ещё выводит секретное число. Это было полезно для тестирования, но портит игру. Удалите строку, которая выводит секретное число. В листинге 2-6 показан окончательный код.

Имя файла: 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;
            }
        }
    }
}
Листинг 2-6: Полный код игры по угадыванию

Итоги

На этом этапе вы успешно построили игру по угадыванию. Поздравляем!

Этот проект был практическим способом познакомить вас со многими новыми концепциями Rust: let, match, функции, использование внешних крейтов, и многое другое. В следующих нескольких главах вы узнаете об этих концепциях более подробно. Глава 3 охватывает концепции, которые есть в большинстве языков программирования, такие как переменные, типы данных и функции, и показывает, как их использовать в Rust. Глава 4 исследует владение — функцию, которая отличает Rust от других языков. Глава 5 обсуждает структуры и методы, а глава 6 объясняет, как работают перечисления.