Язык программирования Rust

Авторы: Стив Клабник, Кэрол Николс и Крис Крычо при участии сообщества Rust

Этот текст рассчитан на Rust 1.98.0 (выпущен 20 августа 2026 года) или новее, причём во всех проектах в файле Cargo.toml должно стоять edition = "2024", чтобы использовались идиомы редакции Rust 2024. Как установить или обновить Rust, рассказано в разделе «Установка» главы 1, а что такое редакции — в приложении E.

Оригинал книги на английском доступен онлайн по адресу https://doc.rust-lang.org/stable/book/, а также оффлайн — он ставится вместе с Rust через rustup; откройте его командой rustup doc --book.

Существуют и другие переводы, сделанные сообществом.

Бумажная и электронная версии оригинала выходят в издательстве No Starch Press.

🚨 Хотите учиться интерактивнее? Попробуйте другую версию Rust Book — с тестами, выделением текста, визуализациями и не только (на английском): https://rust-book.cs.brown.edu

О переводе. Это вольный перевод: мы старались передать смысл так, чтобы текст легко читался по-русски, а не следовать английскому оригиналу слово в слово. Термины при этом взяты те, что приняты в русскоязычном сообществе Rust; при первом появлении рядом дан английский оригинал. Текст распространяется на тех же условиях, что и оригинал, — под лицензиями MIT и Apache 2.0.

Предисловие

За несколько лет Rust проделал огромный путь. Начинался он как проект небольшого, только зарождавшегося сообщества энтузиастов, а сегодня это один из самых любимых и востребованных языков программирования в мире. Оглядываясь назад, можно сказать, что мощь и возможности Rust неизбежно должны были привлечь внимание и закрепить его в системном программировании. Но вот чего никто не мог предсказать — так это того, что интерес к языку и новые идеи вокруг него разойдутся по всему миру через open source-сообщества и что Rust начнут массово применять в самых разных отраслях.

Сегодня этот взрыв интереса легко объяснить прекрасными возможностями языка. Кто откажется от безопасной работы с памятью, и высокой скорости, и дружелюбного компилятора, и отличных инструментов — и это далеко не полный список? Rust, каким вы видите его сейчас, — это годы исследований в области системного программирования плюс практический опыт живого и увлечённого сообщества. Язык проектировали осмысленно и делали тщательно, чтобы дать разработчикам инструмент, с которым проще писать безопасный, быстрый и надёжный код.

Но по-настоящему особенным Rust делает то, что он изначально создавался, чтобы помочь вам, пользователю, добиться своих целей. Этот язык хочет, чтобы у вас всё получилось, и этот принцип лежит в основе сообщества, которое разрабатывает, поддерживает и продвигает Rust. Со времени предыдущего издания этой книги Rust стал по-настоящему глобальным языком, которому доверяют. Теперь у проекта Rust есть надёжная опора — фонд Rust Foundation, который к тому же вкладывается в ключевые инициативы, чтобы Rust оставался безопасным, стабильным и жизнеспособным.

Это издание «Языка программирования Rust» полностью обновлено: оно отражает то, как язык менялся за эти годы, и содержит много нового и полезного. Но это не просто справочник по синтаксису и библиотекам — это приглашение в сообщество, которое ценит качество, производительность и продуманный дизайн. Пробуете ли вы Rust впервые, имея за плечами большой опыт разработки, или уже давно пишете на Rust и хотите отточить навыки — каждый найдёт здесь что-то для себя.

Путь Rust — это совместная работа, обучение и постоянное улучшение. Рост языка и его экосистемы прямо отражает то, насколько живое и разнообразное сообщество за ним стоит. Именно вклад тысяч разработчиков — от тех, кто проектирует ядро языка, до тех, кто изредка присылает исправления, — делает Rust таким уникальным и мощным инструментом. Открыв эту книгу, вы не просто изучаете новый язык программирования: вы присоединяетесь к движению за то, чтобы программы становились лучше, безопаснее, а работать с ними было приятнее.

Добро пожаловать в сообщество Rust!

• Бек Рамбул, исполнительный директор Rust Foundation

Введение

Добро пожаловать в «Язык программирования Rust» — вводную книгу о Rust. Rust помогает писать более быстрые и надёжные программы. Обычно при проектировании языка приходится выбирать: либо удобство высокого уровня, либо контроль над низкоуровневыми деталями. Rust с этим выбором не согласен. Он сочетает серьёзные технические возможности с удобством для разработчика и позволяет управлять низкоуровневыми вещами (например, использованием памяти) без той головной боли, которая обычно с этим связана.

Для кого Rust

Rust подходит очень многим, и по разным причинам. Рассмотрим несколько самых важных групп.

Команды разработчиков

Rust хорошо показывает себя в больших командах, где у людей разный опыт в системном программировании. В низкоуровневом коде легко допустить коварные ошибки, и в большинстве языков их ловят только обширным тестированием и внимательным ревью кода опытными разработчиками. В Rust роль такого привратника берёт на себя компилятор: код с подобными трудноуловимыми ошибками, включая ошибки многопоточности, он просто не скомпилирует. Работая в паре с компилятором, команда может заниматься логикой программы, а не охотой за багами.

Кроме того, Rust приносит в системное программирование современные инструменты разработки:

• Cargo — встроенный менеджер зависимостей и система сборки. С ним добавлять, собирать и обновлять зависимости просто, и делается это одинаково во всей экосистеме Rust.
• Утилита форматирования rustfmt следит за тем, чтобы код у всех разработчиков был оформлен в едином стиле.
• Rust Language Server обеспечивает поддержку в среде разработки (IDE): автодополнение и сообщения об ошибках прямо в коде.

С этими и другими инструментами экосистемы Rust разработчики могут продуктивно работать даже над системным кодом.

Студенты

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

Компании

Сотни компаний, больших и маленьких, используют Rust в продакшене для самых разных задач: утилиты командной строки, веб-сервисы, инструменты DevOps, встраиваемые устройства, анализ и перекодирование аудио и видео, криптовалюты, биоинформатика, поисковые системы, интернет вещей, машинное обучение и даже значительные части браузера Firefox.

Разработчики open source

Rust — для тех, кто хочет развивать сам язык Rust, его сообщество, инструменты разработки и библиотеки. Мы будем рады вашему вкладу в язык.

Те, кому важны скорость и стабильность

Rust — для тех, кому нужен быстрый и стабильный язык. Под скоростью мы понимаем и то, насколько быстро работает код на Rust, и то, насколько быстро Rust позволяет писать программы. Компилятор проверяет код при каждой сборке, поэтому новые возможности и рефакторинг не ломают незаметно то, что уже работало. Сравните это с хрупким legacy-кодом на языках без таких проверок: его часто просто боятся трогать. Rust стремится к абстракциям с нулевой стоимостью (zero-cost abstractions): высокоуровневые конструкции компилируются в такой же быстрый низкоуровневый код, какой вы написали бы вручную. Цель — чтобы безопасный код был ещё и быстрым.

Rust надеется помочь и многим другим — здесь перечислены лишь самые крупные группы заинтересованных. В целом главная амбиция Rust — избавить программистов от компромиссов, с которыми они мирились десятилетиями: дать безопасность и продуктивность, скорость и удобство. Попробуйте Rust и посмотрите, подходит ли вам его подход.

Для кого эта книга

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

Как читать эту книгу

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

В книге есть главы двух видов: теоретические и практические. В теоретических главах вы знакомитесь с какой-то частью Rust. В практических мы вместе пишем небольшие программы и применяем то, что уже изучили. Практические главы — это главы 2, 12 и 21, остальные — теоретические.

Глава 1 рассказывает, как установить Rust, написать программу «Hello, world!» и пользоваться Cargo — менеджером пакетов и системой сборки Rust. Глава 2 — практическое знакомство с Rust: вы напишете игру «Угадай число». Здесь мы проходимся по понятиям поверхностно, а подробности будут в следующих главах. Если хочется сразу взяться за дело, глава 2 — как раз для этого. Если же вы из тех, кто любит сперва разобраться во всех деталях, можете пропустить главу 2 и сразу перейти к главе 3. Она рассказывает о возможностях Rust, похожих на то, что есть в других языках. А к главе 2 можно вернуться потом, когда захочется применить изученное на практике.

В главе 4 вы познакомитесь с системой владения (ownership) в Rust. Глава 5 посвящена структурам и методам. Глава 6 рассказывает о перечислениях, выражениях match и конструкциях управления потоком if let и let...else. Структуры и перечисления нужны, чтобы создавать собственные типы.

В главе 7 вы узнаете о системе модулей Rust и о правилах приватности, с помощью которых организуют код и его публичный интерфейс (API). Глава 8 рассказывает о распространённых коллекциях из стандартной библиотеки: векторах, строках и хеш-таблицах. Глава 9 объясняет, как Rust подходит к обработке ошибок и какие для этого есть приёмы.

Глава 10 подробно разбирает обобщения (generics), трейты и времена жизни — всё это позволяет писать код, который работает с разными типами. Глава 11 целиком посвящена тестированию: даже с гарантиями безопасности Rust тесты нужны, чтобы убедиться, что логика программы верна. В главе 12 мы сами напишем упрощённую версию утилиты командной строки grep, которая ищет текст в файлах. Для этого пригодятся многие понятия из предыдущих глав.

Глава 13 рассказывает о замыканиях и итераторах — возможностях Rust, пришедших из функциональных языков. В главе 14 мы глубже разберём Cargo и поговорим о том, как лучше делиться своими библиотеками с другими. Глава 15 посвящена умным указателям из стандартной библиотеки и трейтам, на которых они построены.

В главе 16 мы рассмотрим разные модели конкурентного программирования и поговорим о том, как Rust позволяет без страха писать многопоточный код. В главе 17 мы продолжим эту тему: разберём синтаксис async и await, а также задачи, футуры и стримы и ту лёгкую модель конкурентности, которую они дают.

Глава 18 сравнивает идиомы Rust с принципами объектно-ориентированного программирования, которые вам, возможно, знакомы. Глава 19 — справочник по образцам и сопоставлению с образцом: это мощный способ выражать мысли в программах на Rust. Глава 20 — сборная солянка продвинутых тем: небезопасный Rust, макросы и ещё немного о временах жизни, трейтах, типах, функциях и замыканиях.

В главе 21 мы доведём до конца проект: напишем низкоуровневый многопоточный веб-сервер!

Наконец, в приложениях собраны полезные сведения о языке в формате справочника. Приложение A — ключевые слова Rust, приложение B — операторы и символы, приложение C — выводимые трейты из стандартной библиотеки, приложение D — полезные инструменты разработки, приложение E объясняет, что такое редакции Rust. В приложении F перечислены переводы книги, а в приложении G рассказано, как создаётся Rust и что такое nightly Rust.

Неправильного способа читать эту книгу нет: хотите забежать вперёд — пожалуйста! Если что-то окажется непонятным, возможно, придётся вернуться к предыдущим главам. Но делайте так, как удобно вам.

Важная часть изучения Rust — научиться читать сообщения об ошибках, которые выдаёт компилятор: они подскажут, как довести код до рабочего состояния. Поэтому мы будем приводить много примеров, которые не компилируются, вместе с сообщением об ошибке, которое в каждом случае покажет компилятор. Имейте в виду: если вы возьмёте случайный пример и запустите его, он может и не скомпилироваться! Обязательно читайте окружающий текст, чтобы понять, должен ли пример, который вы запускаете, завершиться ошибкой. Отличить код, который и не должен работать, поможет Феррис:

Феррис	Что это значит
	Этот код не компилируется!
	Этот код паникует!
	Этот код работает не так, как задумано.

Почти всегда мы потом покажем исправленную версию кода, который не компилируется.

Исходный код

Исходные файлы, из которых собирается оригинал этой книги, лежат на GitHub.

С чего начать

Начнём ваше путешествие в Rust! Изучить предстоит многое, но любой путь начинается с первого шага. В этой главе мы:

• установим Rust на Linux, macOS и Windows;
• напишем программу, которая выводит Hello, world!;
• познакомимся с cargo — менеджером пакетов и системой сборки Rust.

Установка

Установка

Первым делом нужно установить Rust. Скачивать его мы будем через rustup — утилиту командной строки, которая управляет версиями Rust и связанными с ним инструментами. Для загрузки понадобится интернет.

Следующие шаги устанавливают последнюю стабильную версию компилятора Rust. Rust гарантирует стабильность: все примеры из книги, которые компилируются сейчас, будут компилироваться и в более новых версиях. Вывод может немного отличаться от версии к версии, потому что в Rust постоянно улучшают сообщения об ошибках и предупреждения. Иными словами, любая более новая стабильная версия Rust, установленная по этой инструкции, будет работать с материалом книги так, как ожидается.

Установка rustup в Linux и macOS

Если у вас Linux или macOS, откройте терминал и выполните команду:

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

Она скачает скрипт и запустит установку утилиты rustup, а та, в свою очередь, установит последнюю стабильную версию Rust. Возможно, у вас спросят пароль. Если всё прошло успешно, появится строка:

Rust is installed now. Great!

Вам также понадобится компоновщик (linker) — программа, которой Rust собирает результаты компиляции в один файл. Скорее всего, он у вас уже есть. Если же появляются ошибки компоновки, установите компилятор C — обычно компоновщик идёт вместе с ним. Компилятор C пригодится и по другой причине: некоторые популярные пакеты Rust зависят от кода на C, и для их сборки он нужен.

В macOS компилятор C можно получить так:

$ xcode-select --install

В Linux обычно ставят GCC или Clang — как именно, описано в документации вашего дистрибутива. Например, в Ubuntu достаточно установить пакет build-essential.

Установка rustup в Windows

В Windows откройте https://www.rust-lang.org/tools/install и следуйте инструкции по установке Rust. В какой-то момент установщик предложит поставить Visual Studio: она содержит компоновщик и системные библиотеки, без которых программы не скомпилировать. Если с этим шагом нужна помощь, загляните на https://rust-lang.github.io/rustup/installation/windows-msvc.html.

Дальше в книге используются команды, которые работают и в cmd.exe, и в PowerShell. Если где-то есть разница, мы скажем, что использовать.

Решение проблем

Чтобы проверить, правильно ли установлен Rust, откройте терминал и введите:

$ rustc --version

Вы должны увидеть номер последней вышедшей стабильной версии, хеш коммита и дату коммита в таком формате:

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

Если видите эту строку — Rust успешно установлен! Если нет, проверьте, что Rust есть в системной переменной %PATH%.

В Windows CMD:

> echo %PATH%

В PowerShell:

> echo $env:Path

В Linux и macOS:

$ echo $PATH

Если всё в порядке, а Rust всё равно не работает, помощь можно найти во многих местах. Как связаться с другими растацеанами (Rustaceans — так мы в шутку себя называем), смотрите на странице сообщества.

Обновление и удаление

Если Rust установлен через rustup, обновиться до свежей версии очень просто. Выполните в терминале:

$ rustup update

Чтобы удалить Rust вместе с rustup, выполните:

$ rustup self uninstall

Локальная документация

Вместе с Rust устанавливается и локальная копия документации, так что читать её можно без интернета. Команда rustup doc откроет её в браузере.

Если вам попался тип или функция из стандартной библиотеки и вы не уверены, что они делают или как ими пользоваться, — загляните в документацию по API (application programming interface, программный интерфейс приложения)!

Текстовые редакторы и IDE

Книга не навязывает вам никаких инструментов для написания кода на Rust — подойдёт практически любой текстовый редактор! Впрочем, во многих редакторах и интегрированных средах разработки (IDE) есть встроенная поддержка Rust. Довольно свежий список редакторов и IDE всегда можно найти на странице инструментов сайта Rust.

Работа с книгой без интернета

В некоторых примерах мы будем использовать пакеты Rust, которых нет в стандартной библиотеке. Чтобы проработать эти примеры, нужен либо интернет, либо заранее скачанные зависимости. Скачать их заранее можно такими командами (что такое cargo и что делает каждая команда, мы подробно объясним позже):

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

Скачанные пакеты сохранятся в кеше, и потом загружать их уже не придётся. После этого папку get-dependencies можно удалить. Дальше в книге ко всем командам cargo можно добавлять флаг --offline — тогда Cargo возьмёт закешированные версии и не будет лезть в сеть.

Hello, World!

Hello, World!

Rust установлен — пора написать первую программу. По традиции, изучая новый язык, первым делом пишут маленькую программу, которая выводит на экран текст Hello, world!. Так поступим и мы!

Папка для проекта

Начнём с папки, где будет лежать код на Rust. Самому Rust всё равно, где находится ваш код, но для упражнений и проектов из этой книги мы советуем создать в домашнем каталоге папку projects и держать все проекты в ней.

Откройте терминал и введите следующие команды: они создадут папку projects, а внутри неё — папку для проекта «Hello, world!».

В Linux, macOS и PowerShell в Windows:

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

В Windows CMD:

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

Основы программы на Rust

Теперь создайте файл с исходным кодом и назовите его main.rs. Файлы Rust всегда имеют расширение .rs. Если в имени файла несколько слов, их принято разделять подчёркиванием: например, hello_world.rs, а не helloworld.rs.

Откройте только что созданный файл main.rs и введите код из листинга 1-1.

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

Сохраните файл и вернитесь в терминал, в папку ~/projects/hello_world. В Linux или macOS скомпилируйте и запустите программу так:

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

В Windows вместо ./main введите .\main:

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

В какой бы ОС вы ни работали, в терминале должна появиться строка Hello, world!. Если её нет, загляните в часть «Решение проблем» раздела об установке — там написано, где искать помощь.

Если Hello, world! появилась — поздравляем! Вы официально написали программу на Rust, а значит, стали программистом на Rust. Добро пожаловать!

Из чего состоит программа на Rust

Разберём программу «Hello, world!» по частям. Вот первый кусочек:

fn main() {

}

Эти строки определяют функцию с именем main. Функция main особенная: в любой исполняемой программе на Rust она запускается первой. Здесь первая строка объявляет функцию main, у которой нет параметров и которая ничего не возвращает. Если бы параметры были, они бы стояли в круглых скобках (()).

Тело функции заключено в фигурные скобки {}. В Rust они обязательны вокруг тела любой функции. Хорошим тоном считается ставить открывающую скобку на той же строке, что и объявление функции, через один пробел.

В теле функции main находится такой код:

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

Эта строка и делает всю работу в нашей маленькой программе — выводит текст на экран. Здесь стоит обратить внимание на три важные детали.

Во-первых, println! — это вызов макроса Rust. Если бы вызывалась функция, мы бы написали println (без !). Макросы в Rust — это способ писать код, который генерирует другой код и тем самым расширяет синтаксис языка. Подробнее мы поговорим о них в главе 20. А пока достаточно знать: ! означает, что вызывается макрос, а не обычная функция, и что макросы подчиняются не совсем тем же правилам, что функции.

Во-вторых, в коде есть строка "Hello, world!". Мы передаём её как аргумент в println!, и макрос выводит её на экран.

В-третьих, строка кода заканчивается точкой с запятой (;). Она означает, что это выражение закончилось и можно начинать следующее. Большинство строк кода на Rust заканчиваются точкой с запятой.

Компиляция и запуск

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

Прежде чем запустить программу на Rust, её нужно скомпилировать компилятором Rust: выполнить команду rustc и передать ей имя файла с исходным кодом:

$ rustc main.rs

Если вы писали на C или C++, то заметите, что это похоже на gcc или clang. После успешной компиляции Rust создаёт исполняемый бинарный файл.

В Linux, macOS и PowerShell в Windows исполняемый файл можно увидеть командой ls:

$ ls
main  main.rs

В Linux и macOS вы увидите два файла. В Windows файлов будет три — и в PowerShell, и в CMD. В CMD вместо ls нужно ввести:

> dir /B %= ключ /B говорит выводить только имена файлов =%
main.exe
main.pdb
main.rs

Здесь мы видим файл с исходным кодом (расширение .rs), исполняемый файл (main.exe в Windows и просто main на остальных платформах), а в Windows ещё и файл с отладочной информацией с расширением .pdb. Теперь запустите main или main.exe:

$ ./main # или .\main в Windows

Если в main.rs лежит программа «Hello, world!», эта команда выведет в терминал Hello, world!.

Если вы больше привыкли к динамическим языкам вроде Ruby, Python или JavaScript, вам может быть непривычно, что компиляция и запуск — это отдельные шаги. Rust — язык с предварительной компиляцией (ahead-of-time compiled): вы один раз компилируете программу и получаете исполняемый файл. Его можно отдать кому угодно, и он запустится даже там, где Rust не установлен. А вот если отдать кому-то файл .rb, .py или .js, у него должен быть установлен Ruby, Python или JavaScript соответственно. Зато в этих языках достаточно одной команды, чтобы и скомпилировать, и запустить программу. В дизайне языков всё — компромисс.

Для простых программ вполне хватит одного rustc. Но когда проект разрастётся, вам понадобится управлять множеством настроек и удобно делиться кодом с другими. Дальше мы познакомимся с Cargo — инструментом, который поможет писать настоящие, «боевые» программы на Rust.

Hello, Cargo!

Hello, Cargo!

Cargo — это система сборки и менеджер пакетов Rust. Большинство растацеанов управляют своими проектами именно через Cargo, потому что он берёт на себя массу рутины: собирает ваш код, а также скачивает и собирает библиотеки, которые нужны этому коду. (Библиотеки, которые нужны вашему коду, называют зависимостями.)

У простейших программ вроде той, что мы только что написали, зависимостей нет. Если бы мы собирали «Hello, world!» через Cargo, задействовалась бы только та его часть, что отвечает за сборку. Но когда программы станут сложнее, вы начнёте добавлять зависимости — и если проект с самого начала создан через Cargo, делать это будет гораздо проще.

Подавляющее большинство проектов на Rust используют Cargo, поэтому дальше в книге мы считаем, что и вы им пользуетесь. Если вы ставили Rust официальным установщиком, как описано в разделе «Установка», Cargo у вас уже есть. Если Rust установлен каким-то другим способом, проверьте, есть ли Cargo, такой командой:

$ cargo --version

Если появился номер версии — всё в порядке! Если же видите ошибку вроде command not found, загляните в документацию к своему способу установки и узнайте, как поставить Cargo отдельно.

Создание проекта с Cargo

Создадим новый проект с помощью Cargo и посмотрим, чем он отличается от нашего первого «Hello, world!». Вернитесь в папку projects (или туда, где вы решили хранить код) и в любой ОС выполните:

$ cargo new hello_cargo
$ cd hello_cargo

Первая команда создаёт новый проект с именем hello_cargo. Cargo создаёт его файлы в одноимённой папке.

Перейдите в папку hello_cargo и посмотрите, что в ней лежит. Cargo сгенерировал для нас два файла и одну папку: файл Cargo.toml и папку src с файлом main.rs внутри.

Кроме того, он инициализировал новый Git-репозиторий и создал файл .gitignore. Если запустить cargo new внутри уже существующего Git-репозитория, файлы Git создаваться не будут; это поведение можно переопределить командой cargo new --vcs=git.

Откройте Cargo.toml в любимом редакторе. Он должен выглядеть примерно как в листинге 1-2.

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

[dependencies]

Файл записан в формате TOML (Tom’s Obvious, Minimal Language — «очевидный минималистичный язык Тома»). В этом формате Cargo хранит настройки.

Первая строка, [package], — заголовок секции: следующие за ним строки настраивают пакет. Когда мы будем добавлять в файл новую информацию, появятся и другие секции.

Следующие три строки задают то, что нужно Cargo для компиляции программы: имя, версию и редакцию Rust. О ключе edition мы поговорим в приложении E.

Последняя строка, [dependencies], открывает секцию, где перечисляются зависимости проекта. Пакеты кода в Rust называются крейтами (crates). Для этого проекта другие крейты не нужны, а вот в первом проекте из главы 2 они понадобятся — тогда мы этой секцией и воспользуемся.

Теперь откройте src/main.rs:

Файл: src/main.rs

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

Cargo сгенерировал для вас программу «Hello, world!» — точно такую же, как мы написали в листинге 1-1! От нашего первого проекта этот отличается только двумя вещами: код лежит в папке src, а в корне проекта есть файл настроек Cargo.toml.

Cargo ожидает, что исходный код находится в папке src. Корневая папка проекта — для README, информации о лицензии, файлов настроек и всего прочего, что не относится к коду. Cargo помогает держать проект в порядке: у каждой вещи своё место, и каждая вещь на своём месте.

Если вы начали проект без Cargo, как мы с «Hello, world!», его можно перевести на Cargo: перенесите код в папку src и создайте подходящий Cargo.toml. Проще всего получить этот Cargo.toml командой cargo init — она создаст его автоматически.

Сборка и запуск проекта Cargo

Посмотрим, что меняется, когда программу «Hello, world!» собирает и запускает Cargo! Находясь в папке hello_cargo, соберите проект командой:

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

Эта команда создаёт исполняемый файл не в текущей папке, а в target/debug/hello_cargo (в Windows — target\debug\hello_cargo.exe). По умолчанию сборка отладочная, поэтому Cargo кладёт бинарник в папку debug. Запустить его можно так:

$ ./target/debug/hello_cargo # или .\target\debug\hello_cargo.exe в Windows
Hello, world!

Если всё прошло хорошо, в терминале появится Hello, world!. При первом запуске cargo build Cargo также создаёт в корне проекта новый файл — Cargo.lock. В нём записаны точные версии зависимостей проекта. У нашего проекта зависимостей нет, поэтому файл почти пустой. Править его вручную никогда не понадобится: его содержимым управляет Cargo.

Мы собрали проект через cargo build и запустили через ./target/debug/hello_cargo. Но можно сделать и то и другое одной командой — cargo run скомпилирует код и сразу запустит получившийся файл:

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

cargo run удобнее, чем помнить про cargo build и потом набирать полный путь к бинарнику, поэтому большинство разработчиков пользуются именно ею.

Обратите внимание: на этот раз в выводе нет строки о том, что Cargo компилирует hello_cargo. Cargo понял, что файлы не менялись, поэтому не стал пересобирать проект, а просто запустил бинарник. Если бы вы изменили исходный код, Cargo пересобрал бы проект перед запуском, и вывод был бы таким:

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

Есть у Cargo и команда cargo check. Она быстро проверяет, что код компилируется, но исполняемый файл не создаёт:

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

Зачем может понадобиться сборка без исполняемого файла? Дело в том, что cargo check обычно работает намного быстрее cargo build — как раз потому, что пропускает создание исполняемого файла. Если вы постоянно проверяете код, пока его пишете, cargo check гораздо быстрее скажет, компилируется ли ещё ваш проект! Поэтому многие растацеаны по ходу работы то и дело запускают cargo check, а cargo build — только когда исполняемый файл действительно нужен.

Подведём итог тому, что мы узнали о Cargo:

• Создать проект можно командой cargo new.
• Собрать проект — командой cargo build.
• Собрать и сразу запустить — командой cargo run.
• Проверить проект на ошибки, не создавая бинарник, — командой cargo check.
• Cargo складывает результат сборки не рядом с кодом, а в папку target/debug.

Ещё одно преимущество Cargo — его команды одинаковы в любой операционной системе. Поэтому дальше мы уже не будем давать отдельные инструкции для Linux и macOS и для Windows.

Сборка релиза

Когда проект наконец готов к выпуску, скомпилируйте его с оптимизациями командой cargo build --release. Исполняемый файл окажется в target/release, а не в target/debug. С оптимизациями программа работает быстрее, но компилируется дольше. Поэтому профилей сборки два. Отладочный — для разработки: код пересобирается часто, и сборка должна быть быстрой. Релизный — для финальной версии, которую вы отдадите пользователям: её собирают редко, а работать она должна как можно быстрее. Если вы замеряете время работы своего кода, обязательно собирайте его через cargo build --release и измеряйте исполняемый файл из target/release.

Опираемся на соглашения Cargo

В простых проектах Cargo не даёт заметного выигрыша по сравнению с голым rustc, но чем сложнее программа, тем больше от него пользы. Как только в программе становится несколько файлов или появляются зависимости, гораздо проще доверить организацию сборки Cargo.

Хоть проект hello_cargo и простой, в нём уже задействована большая часть настоящих инструментов, с которыми вы будете работать в Rust и дальше. По сути, чтобы начать работу над любым существующим проектом, достаточно скачать код через Git, перейти в папку проекта и собрать его:

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

Подробнее о Cargo читайте в его документации.

Итоги

Вы отлично начали путь в Rust! В этой главе вы научились:

• устанавливать последнюю стабильную версию Rust через rustup;
• обновлять Rust до новой версии;
• открывать локальную документацию;
• писать и запускать программу «Hello, world!» напрямую через rustc;
• создавать и запускать новый проект по соглашениям Cargo.

Самое время написать программу посерьёзнее, чтобы привыкнуть читать и писать код на Rust. Поэтому в главе 2 мы напишем игру «Угадай число». Если же вам хочется сначала разобраться, как в Rust устроены базовые понятия программирования, прочитайте главу 3, а потом вернитесь к главе 2.

Пишем игру «Угадай число»

Давайте сразу окунёмся в 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!");
}

Теперь скомпилируем и сразу запустим эту программу командой 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. Весь код игры мы будем писать в нём.

Обрабатываем догадку игрока

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

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. Она входит в стандартную библиотеку, которая называется 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 автоматически подключает в область видимости любой программы. Этот набор называется прелюдией (prelude), и его полный состав можно посмотреть в документации стандартной библиотеки.

Если нужного типа в прелюдии нет, его придётся явно подключить инструкцией 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; // изменяемая

Вернёмся к нашей игре. Теперь вы знаете, что let mut guess создаёт изменяемую переменную с именем guess. Знак равенства (=) говорит Rust, что мы сразу привязываем к переменной какое-то значение. Справа от знака равенства — то самое значение: результат вызова 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 — это тип, представляющий дескриптор (handle) стандартного ввода вашего терминала.

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

& означает, что аргумент — это ссылка (reference). Ссылки позволяют разным частям кода обращаться к одним и тем же данным, не копируя их в памяти много раз. Ссылки — сложная тема, и одно из главных преимуществ 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");

Но одну длинную строку тяжело читать, поэтому лучше её разбить. Когда вызываете методы через .имя_метода(), разумно переносить длинную цепочку на новые строки и добавлять отступы. Теперь разберёмся, что же делает эта строка.

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

Подробнее перечисления разбираются в главе 6. Типы Result нужны для того, чтобы передавать информацию об ошибках.

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

У значений типа Result, как и у значений любого другого типа, есть методы. Например, у Result есть метод expect. Если значение Result — это Err, то 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}");
}

Она выводит строку, в которой теперь лежит ввод пользователя. Пара фигурных скобок {} — это заполнитель (placeholder): представьте, что {} — это маленькие крабьи клешни, которые держат значение на месте. Чтобы вывести значение переменной, можно написать её имя прямо внутри фигурных скобок. А чтобы вывести результат вычисления выражения, поставьте в строке формата пустые фигурные скобки, а после строки через запятую перечислите выражения — они по порядку подставятся в пустые заполнители. Вот как вывести переменную и результат выражения одним вызовом 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 по-настоящему блистает. Прежде чем писать код с rand, нужно добавить этот крейт в зависимости в файле Cargo.toml. Откройте файл и допишите в самый конец, под заголовком секции [dependencies], который Cargo уже создал, следующую строку. Укажите rand именно так, как у нас, с этим номером версии, — иначе примеры кода из этой главы могут не заработать:

Файл: Cargo.toml

[dependencies]
rand = "0.10.1"

В Cargo.toml всё, что идёт после заголовка, относится к его секции — до тех пор, пока не начнётся следующая. В [dependencies] вы перечисляете, от каких внешних крейтов зависит проект и какие их версии нужны. Здесь мы указали крейт 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

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

Когда мы добавляем внешнюю зависимость, Cargo скачивает последние версии всего, что ей нужно, из реестра (registry) — копии данных с Crates.io. Crates.io — это место, где участники экосистемы 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. В ней исправлена важная ошибка, но заодно появилась регрессия, которая ломает ваш код. На этот случай при первом запуске cargo build Rust создаёт файл Cargo.lock — он уже лежит у нас в папке guessing_game.

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

Обновляем крейт до новой версии

Когда вы всё-таки хотите обновить крейт, воспользуйтесь командой Cargo update. Она проигнорирует Cargo.lock, подберёт самые свежие версии, подходящие под условия из Cargo.toml, и запишет их в 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)

Версию 0.999.0 Cargo проигнорирует. Заодно вы заметите, что в 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.

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

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

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

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

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

$ 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. Обратите внимание: пока этот код не скомпилируется — почему, мы сейчас объясним.

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

    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!"),
    }
}

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

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

Выражение match состоит из веток (arms). Каждая ветка — это пара: образец (pattern) и код. Если значение, переданное в 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::Greater, и он совпадает с Ordering::Greater! Выполняется код этой ветки, и на экран выводится Too big!. Выражение match завершается после первого же совпадения, так что последнюю ветку в этом случае оно даже не проверяет.

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

$ cargo build
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling cfg-if v1.0.0
   Compiling getrandom v0.4.3
   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/88d9e12ae178fab0fb5cc050a94da85685d449ea/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

Суть ошибки — несовпадение типов (mismatched types). В Rust сильная статическая система типов, но при этом в нём есть выведение типов. Когда мы написали let mut guess = String::new(), Rust сам понял, что guess должна быть типа String, и не заставил нас указывать тип. А вот secret_number — числового типа. Значение от 1 до 100 могут хранить несколько числовых типов Rust: 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.");

    // --пропуск--

    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 любезно позволяет затенить (shadow) прежнее значение guess новым. Затенение позволяет снова использовать имя guess, а не заводить две разные переменные вроде guess_str и guess. Подробнее мы поговорим об этом в главе 3, а пока просто запомните: этим часто пользуются, когда нужно преобразовать значение из одного типа в другой.

Новую переменную мы привязываем к выражению guess.trim().parse(). guess в этом выражении — это исходная переменная, в которой лежит ввод в виде строки. Метод trim у экземпляра String убирает пробельные символы в начале и в конце строки. Это обязательно нужно сделать, прежде чем превращать строку в u32: тип u32 может хранить только число. Чтобы read_line принял догадку, пользователь должен нажать enter, а это добавляет в строку символ перевода строки. Например, если пользователь ввёл 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 и сравниваем guess с secret_number, Rust выведет, что secret_number тоже должна быть типа u32. Так что теперь сравниваются два значения одного типа!

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

Запустим программу:

$ 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);

    // --пропуск--

    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!"),
        }
    }
}

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

Конечно, пользователь всегда может прервать программу сочетанием клавиш 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 после You win! выводит программу из цикла, когда пользователь угадал число. А раз цикл — последнее, что есть в main, выход из цикла означает и выход из программы.

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

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

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

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

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

Если же parse не удалось превратить строку в число, он вернёт значение Err с подробностями об ошибке. Err не совпадает с образцом Ok(num) из первой ветки, зато совпадает с образцом Err(_) из второй. Подчёркивание _ — это «подходит что угодно»: здесь мы говорим, что нас устраивает любое значение Err, что бы у него ни было внутри. Поэтому программа выполнит код второй ветки — continue, то есть перейдёт к следующей итерации цикла loop и попросит новую догадку. В итоге программа просто игнорирует любые ошибки, которые может вернуть 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!

Потрясающе! Осталась последняя мелочь — и игра готова. Помните, что программа всё ещё выводит загаданное число? Для проверки это было удобно, но игру портит. Удалим println!, который выводит загаданное число. Финальный код — в листинге 2-6.

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

Вот и всё — вы написали игру «Угадай число». Поздравляем!

Итоги

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

Основные понятия программирования

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

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

Переменные и изменяемость

Переменные и изменяемость

Как мы уже говорили в разделе «Храним значения в переменных», по умолчанию переменные неизменяемые. Так Rust подталкивает вас к коду, который безопаснее и который проще сделать конкурентным. Тем не менее вы всё равно можете сделать переменную изменяемой. Давайте разберёмся, как и почему Rust советует предпочитать неизменяемость и когда от неё имеет смысл отказаться.

Если переменная неизменяемая, то после того, как значение привязано к имени, изменить это значение уже нельзя. Чтобы это увидеть, создайте в папке projects новый проект variables командой cargo new variables.

Затем в новой папке variables откройте src/main.rs и замените код в нём на следующий (пока он не скомпилируется):

Файл: src/main.rs

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

Сохраните файл и запустите программу командой cargo run. Вы получите сообщение об ошибке, связанной с неизменяемостью:

$ 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

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

Сообщение cannot assign twice to immutable variable `x` («нельзя дважды присвоить значение неизменяемой переменной x») появилось потому, что вы попытались присвоить второе значение неизменяемой переменной x.

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

Но и изменяемость бывает очень полезна: с ней некоторый код писать удобнее. Хотя переменные по умолчанию неизменяемые, их можно сделать изменяемыми, добавив mut перед именем, — как вы делали в главе 2. Кроме того, mut сообщает будущим читателям кода о вашем намерении: другие части кода будут менять значение этой переменной.

Например, изменим src/main.rs так:

Файл: 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}");
}

Теперь программа выводит:

$ 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

Благодаря mut мы можем поменять значение, привязанное к x, с 5 на 6. В конечном счёте решать, использовать изменяемость или нет, — вам: выбирайте то, что в конкретной ситуации делает код понятнее.

Константы

Константы, как и неизменяемые переменные, — это значения, привязанные к имени, которые нельзя менять. Но между константами и переменными есть несколько различий.

Во-первых, с константами нельзя использовать mut. Константы не просто неизменяемы по умолчанию — они неизменяемы всегда. Объявляются они ключевым словом const, а не let, и тип значения обязательно нужно указать. О типах и их аннотациях мы поговорим в следующем разделе, «Типы данных», так что пока не беспокойтесь о подробностях. Просто запомните: тип константы указывается всегда.

Во-вторых, константы можно объявлять в любой области видимости, в том числе в глобальной. Поэтому они удобны для значений, которые нужны многим частям кода.

И последнее отличие: значением константы может быть только константное выражение — то, что можно вычислить при компиляции, а не то, что становится известно лишь во время работы программы.

Вот пример объявления константы:

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

Константа называется THREE_HOURS_IN_SECONDS (три часа в секундах), а её значение — произведение 60 (секунд в минуте) на 60 (минут в часе) и на 3 (столько часов нам нужно посчитать в этой программе). По соглашению имена констант в Rust пишут заглавными буквами, разделяя слова подчёркиваниями. Компилятор умеет вычислять при компиляции ограниченный набор операций. Поэтому мы можем записать значение в виде, который проще понять и проверить, а не просто вписать 10 800. Какие операции допустимы при объявлении констант, описано в разделе о вычислении констант в справочнике Rust.

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

Если значение зашито в код и используется по всей программе, лучше объявить его константой с понятным именем: тем, кто будет читать код после вас, будет проще понять, что это за число. Кроме того, если когда-нибудь его понадобится поменять, это придётся сделать лишь в одном месте.

Затенение

Как вы видели в игре «Угадай число» в главе 2, можно объявить новую переменную с тем же именем, что и у предыдущей. Растацеаны говорят, что вторая переменная затеняет (shadows) первую. Это значит, что, когда вы используете это имя, компилятор видит вторую переменную. По сути, вторая переменная заслоняет первую и забирает все обращения к этому имени себе — пока её саму не затенят или пока не закончится область видимости. Чтобы затенить переменную, достаточно ещё раз написать let с тем же именем:

Файл: 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}");
}

Сначала программа привязывает x к значению 5. Затем повторное let x = создаёт новую переменную x: берёт исходное значение и прибавляет 1, так что теперь x равно 6. Дальше, во внутренней области видимости, созданной фигурными скобками, третья инструкция let снова затеняет x и создаёт новую переменную, умножая предыдущее значение на 2, — теперь x равно 12. Когда внутренняя область видимости заканчивается, заканчивается и это затенение, и x снова равно 6. Программа выведет:

$ 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

Затенение — не то же самое, что mut. Если мы случайно попробуем присвоить этой переменной новое значение без let, то получим ошибку компиляции. Используя let, мы можем выполнить над значением несколько преобразований, а после них переменная останется неизменяемой.

Есть и второе отличие от mut: при повторном let мы фактически создаём новую переменную, поэтому можем поменять тип значения, сохранив прежнее имя. Допустим, программа просит пользователя ввести столько пробелов, сколько он хочет видеть между фрагментами текста. Получив ввод, мы хотим хранить уже не сами пробелы, а их количество:

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

Первая переменная spaces — строкового типа, а вторая — числового. Благодаря затенению не нужно придумывать разные имена вроде spaces_str и spaces_num: можно снова использовать простое spaces. А вот если попытаться сделать то же самое с mut, получим ошибку компиляции:

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

Ошибка говорит, что тип переменной менять нельзя:

$ 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

Теперь, когда мы разобрались, как работают переменные, посмотрим, какие типы данных у них бывают.

Типы данных

Типы данных

Каждое значение в Rust имеет определённый тип данных. Тип говорит Rust, что это за данные, а значит, как с ними работать. Мы рассмотрим две группы типов: скалярные и составные.

Помните, что Rust — язык со статической типизацией: типы всех переменных должны быть известны уже при компиляции. Обычно компилятор сам выводит нужный тип по значению и по тому, как оно используется. Но если подходит сразу несколько типов — как в разделе «Сравниваем догадку с загаданным числом» главы 2, когда мы превращали String в число методом parse, — нужно добавить аннотацию типа:

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

Если убрать аннотацию : u32, Rust выдаст следующую ошибку. Она означает, что компилятору не хватает информации, чтобы понять, какой тип мы имеем в виду:

$ 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

Для других типов данных аннотации выглядят по-разному — вы это ещё увидите.

Скалярные типы

Скалярный тип представляет одно значение. В Rust четыре основных скалярных типа: целые числа, числа с плавающей точкой, логические значения и символы. Скорее всего, вы встречали их и в других языках. Посмотрим, как они устроены в Rust.

Целочисленные типы

Целое число — это число без дробной части. В главе 2 мы уже пользовались одним целочисленным типом — u32. Такое объявление типа говорит, что значение — беззнаковое целое (у знаковых типов вместо u в начале стоит i) и занимает 32 бита. В таблице 3-1 перечислены встроенные целочисленные типы Rust. Любой из них можно указать как тип целого числа.

Таблица 3-1: Целочисленные типы в Rust

Каждый вариант бывает знаковым или беззнаковым и имеет явно заданный размер. Знаковый и беззнаковый — это о том, может ли число быть отрицательным. Иными словами, нужен ли числу знак (знаковое) или оно всегда положительное, и знак можно не хранить (беззнаковое). Это как запись чисел на бумаге: когда знак важен, мы пишем перед числом плюс или минус, а когда и так понятно, что число положительное, знак не пишем. Знаковые числа хранятся в дополнительном коде (two’s complement).

Знаковый тип может хранить числа от −(2^{n − 1}) до 2^{n − 1} − 1 включительно, где n — количество бит в типе. Так, i8 хранит числа от −(2⁷) до 2⁷ − 1, то есть от −128 до 127. Беззнаковые типы хранят числа от 0 до 2ⁿ − 1, так что u8 хранит числа от 0 до 2⁸ − 1, то есть от 0 до 255.

Размер типов isize и usize зависит от архитектуры компьютера, на котором работает программа: 64 бита на 64-битной архитектуре и 32 бита на 32-битной.

Целочисленные литералы можно записывать в любой из форм из таблицы 3-2. Если литерал подходит под несколько числовых типов, к нему можно приписать суффикс типа — например, 57u8. Кроме того, в числовых литералах можно ставить _ в качестве визуального разделителя, чтобы число легче читалось: 1_000 — это то же самое, что 1000.

Таблица 3-2: Целочисленные литералы в Rust

Как же понять, какой целочисленный тип выбрать? Если сомневаетесь, начните с того, что Rust выбирает по умолчанию, — обычно это хороший вариант. По умолчанию целые числа имеют тип i32. isize и usize в основном нужны для индексации коллекций.

Числа с плавающей точкой

Ещё в Rust есть два примитивных типа для чисел с плавающей точкой, то есть дробных чисел: f32 и f64 — 32 и 64 бита соответственно. По умолчанию используется f64: на современных процессорах он работает примерно так же быстро, как f32, но точнее. Все типы с плавающей точкой знаковые.

Вот пример работы с числами с плавающей точкой:

Файл: src/main.rs

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

    let y: f32 = 3.0; // f32
}

Числа с плавающей точкой представлены по стандарту IEEE-754.

Арифметические операции

Для всех числовых типов Rust поддерживает привычные математические операции: сложение, вычитание, умножение, деление и остаток от деления. Целочисленное деление отбрасывает дробную часть (округляет к нулю). Вот как каждая операция выглядит в инструкции let:

Файл: src/main.rs

fn main() {
    // сложение
    let sum = 5 + 10;

    // вычитание
    let difference = 95.5 - 4.3;

    // умножение
    let product = 4 * 30;

    // деление
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Получится -1

    // остаток от деления
    let remainder = 43 % 5;
}

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

Логический тип

Как и в большинстве других языков, у логического типа в Rust два возможных значения: true и false. Занимает он один байт и обозначается bool. Например:

Файл: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // с явной аннотацией типа
}

Чаще всего логические значения используются в условиях, например в выражении if. Как работает if в Rust, мы разберём в разделе «Управление потоком выполнения».

Символьный тип

Тип char — самый примитивный «буквенный» тип в Rust. Вот несколько примеров объявления значений char:

Файл: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // с явной аннотацией типа
    let heart_eyed_cat = '😻';
}

Обратите внимание: литералы char записываются в одинарных кавычках, а строковые литералы — в двойных. Тип char в Rust занимает 4 байта и представляет скалярное значение Юникода (Unicode scalar value), а значит, умеет гораздо больше, чем просто ASCII. Буквы с диакритикой, китайские, японские и корейские иероглифы, эмодзи, пробелы нулевой ширины — всё это допустимые значения char. Скалярные значения Юникода лежат в диапазонах от U+0000 до U+D7FF и от U+E000 до U+10FFFF включительно. Однако понятия «символ» в Юникоде на самом деле нет, поэтому ваше интуитивное представление о «символе» может не совпадать с тем, что такое char в Rust. Подробно мы обсудим это в разделе «Строки: текст в UTF-8» главы 8.

Составные типы

Составные типы объединяют несколько значений в один тип. В Rust два примитивных составных типа: кортежи и массивы.

Кортежи

Кортеж (tuple) — универсальный способ собрать несколько значений разных типов в одно составное значение. Длина кортежа фиксирована: после объявления он не может ни вырасти, ни уменьшиться.

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

Файл: src/main.rs

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

Переменная tup привязана ко всему кортежу целиком: кортеж считается одним составным элементом. Чтобы достать из кортежа отдельные значения, можно разобрать его с помощью сопоставления с образцом:

Файл: src/main.rs

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

    let (x, y, z) = tup;

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

Сначала программа создаёт кортеж и привязывает его к переменной tup. Затем let с образцом раскладывает tup на три отдельные переменные: x, y и z. Это называется деструктуризацией (destructuring): один кортеж разбивается на три части. В конце программа выводит значение y, то есть 6.4.

К элементу кортежа можно обратиться и напрямую: через точку (.) и индекс нужного значения. Например:

Файл: 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;
}

Программа создаёт кортеж x, а затем обращается к каждому его элементу по индексу. Как и в большинстве языков программирования, индексы в кортеже начинаются с 0.

У кортежа без единого значения есть особое название — unit («единичный тип»). И само значение, и его тип записываются как (); они обозначают пустое значение или отсутствие возвращаемого значения. Если выражение не возвращает никакого другого значения, оно неявно возвращает ().

Массивы

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

Значения массива записываются через запятую в квадратных скобках:

Файл: src/main.rs

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

Массив пригодится, когда данные должны лежать на стеке, а не в куче (как и значения всех типов, что мы видели до сих пор; о стеке и куче подробно поговорим в главе 4). Или когда нужно гарантировать, что элементов всегда одно и то же количество. Но массив не так гибок, как вектор. Вектор — это похожая коллекция из стандартной библиотеки, которая может расти и уменьшаться, потому что её содержимое хранится в куче. Если не уверены, что выбрать — массив или вектор, — скорее всего, нужен вектор. Подробнее о векторах — в главе 8.

Зато массивы хороши, когда вы точно знаете, что количество элементов меняться не будет. Например, если программе нужны названия месяцев, лучше взять массив, а не вектор: месяцев всегда 12.

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

Тип массива записывается в квадратных скобках: тип элементов, точка с запятой и количество элементов:

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

Здесь i32 — тип каждого элемента, а число 5 после точки с запятой говорит, что в массиве пять элементов.

Можно также создать массив, все элементы которого одинаковы: в квадратных скобках укажите начальное значение, точку с запятой и длину массива:

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

Массив a будет содержать 5 элементов, и все они изначально равны 3. Это то же самое, что let a = [3, 3, 3, 3, 3];, только короче.

Доступ к элементам массива

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

Файл: src/main.rs

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

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

Здесь переменная first получит значение 1 — оно лежит в массиве по индексу [0]. А переменная second получит значение 2 по индексу [1].

Обращение за пределы массива

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

Файл: 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}");
}

Этот код успешно компилируется. Если запустить его через cargo run и ввести 0, 1, 2, 3 или 4, программа выведет элемент массива с этим индексом. А если ввести число за пределами массива, например 10, вывод будет таким:

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

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

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

Функции

Функции

Функции в коде на Rust встречаются повсюду. Одну из самых важных функций языка вы уже видели — это main, точка входа во многие программы. Видели вы и ключевое слово fn, которым объявляются новые функции.

Имена функций и переменных в Rust принято писать в стиле snake case: все буквы строчные, а слова разделяются подчёркиваниями. Вот программа с примером определения функции:

Файл: src/main.rs

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

    another_function();
}

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

Функция в Rust определяется так: fn, затем имя функции и круглые скобки. Фигурные скобки показывают компилятору, где начинается и где заканчивается тело функции.

Чтобы вызвать любую определённую нами функцию, достаточно написать её имя и круглые скобки. Функция another_function определена в программе, поэтому её можно вызвать из main. Обратите внимание: в исходном коде мы определили another_function после main, но могли бы определить и до. Rust не важно, в каком порядке идут функции, — важно лишь, чтобы вызывающий код их видел (чтобы функция была в доступной ему области видимости).

Чтобы поэкспериментировать с функциями, создайте новый бинарный проект functions. Поместите пример с another_function в src/main.rs и запустите. Вывод должен быть таким:

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

Строки выполняются в том порядке, в каком они записаны в main. Сначала выводится «Hello, world!», затем вызывается another_function и выводит своё сообщение.

Параметры

У функций могут быть параметры — особые переменные, которые являются частью сигнатуры функции. Если у функции есть параметры, при вызове в них можно передать конкретные значения. Строго говоря, сами конкретные значения называются аргументами, но в разговоре слова «параметр» и «аргумент» часто используют как синонимы — и для переменных в определении функции, и для значений, которые передаются при вызове.

В этой версии another_function мы добавили параметр:

Файл: src/main.rs

fn main() {
    another_function(5);
}

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

Запустите программу — вывод должен быть таким:

$ 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

У another_function один параметр с именем x и типом i32. Когда мы передаём в another_function значение 5, макрос println! подставляет 5 в строку формата на место фигурных скобок с x.

В сигнатуре функции тип каждого параметра указывать обязательно. Это сознательное решение в дизайне Rust: когда типы параметров записаны в определении функции, компилятор почти всегда может сам вывести остальные типы в коде, и вам не придётся расставлять аннотации где-то ещё. К тому же, зная, какие типы ожидает функция, компилятор может выдавать более полезные сообщения об ошибках.

Если параметров несколько, их объявления разделяются запятыми:

Файл: 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}");
}

Здесь создаётся функция print_labeled_measurement с двумя параметрами. Первый называется value и имеет тип i32. Второй — unit_label типа char. Функция выводит текст, в котором есть и value, и unit_label.

Запустим этот код. Замените программу в src/main.rs проекта functions на пример выше и запустите её через 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

Мы вызвали функцию со значением 5 для value и 'h' для unit_label, и именно эти значения появились в выводе.

Инструкции и выражения

Тело функции состоит из последовательности инструкций, которая может заканчиваться выражением. У функций, которые мы видели до сих пор, такого завершающего выражения не было, но выражения внутри инструкций вам уже встречались. Rust — язык, основанный на выражениях (expression-based), поэтому разница между инструкциями и выражениями здесь важна. В других языках такого разделения нет, так что давайте разберёмся, что такое инструкции и выражения и как их различие сказывается на теле функций.

• Инструкции (statements) выполняют какое-то действие и не возвращают значения.
• Выражения (expressions) вычисляются в итоговое значение.

Посмотрим на примеры.

На самом деле мы уже пользовались и инструкциями, и выражениями. Создать переменную и присвоить ей значение с помощью let — это инструкция. В листинге 3-1 let y = 6; — инструкция.

fn main() {
    let y = 6;
}

Определение функции — тоже инструкция: весь пример выше сам по себе является инструкцией. (А вот вызов функции, как мы скоро увидим, — уже не инструкция.)

Инструкции не возвращают значений. Поэтому инструкцию let нельзя присвоить другой переменной, как пытается сделать следующий код, — получится ошибка:

Файл: src/main.rs

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

Если запустить эту программу, ошибка будет такой:

$ 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)]` (part of `#[warn(unused)]`) 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

Инструкция let y = 6 не возвращает значения, так что привязывать к x нечего. В этом Rust отличается от других языков, например C и Ruby, где присваивание возвращает присвоенное значение. Там можно написать x = y = 6, и обе переменные, x и y, получат значение 6. В Rust так не получится.

Выражения вычисляются в значение, и из них состоит большая часть остального кода, который вы будете писать на Rust. Возьмём математическую операцию, например 5 + 6: это выражение, которое вычисляется в 11. Выражения могут входить в инструкции: в листинге 3-1 6 в инструкции let y = 6; — это выражение, которое вычисляется в значение 6. Вызов функции — выражение. Вызов макроса — выражение. Новый блок области видимости, созданный фигурными скобками, — тоже выражение. Например:

Файл: src/main.rs

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

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

Вот это выражение:

{
    let x = 3;
    x + 1
}

— блок, который в данном случае вычисляется в 4. Это значение и привязывается к y в инструкции let. Обратите внимание на строку x + 1: в отличие от большинства строк, которые вы видели до сих пор, в конце у неё нет точки с запятой. Выражения не заканчиваются точкой с запятой. Если поставить точку с запятой в конце выражения, оно превратится в инструкцию и перестанет возвращать значение. Помните об этом — дальше мы будем разбирать возвращаемые значения функций и выражения.

Функции, возвращающие значения

Функции могут возвращать значения вызвавшему их коду. Возвращаемым значениям мы не даём имён, но их тип нужно объявить после стрелки (->). В Rust возвращаемое значение функции — это значение последнего выражения в её теле. Из функции можно выйти и раньше, с помощью ключевого слова return и значения, но большинство функций неявно возвращают последнее выражение. Вот пример функции, которая возвращает значение:

Файл: src/main.rs

fn five() -> i32 {
    5
}

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

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

В функции five нет ни вызовов функций, ни макросов, ни даже инструкций let — только число 5. И это совершенно нормальная функция на Rust. Заметьте, что тип возвращаемого значения тоже указан: -> i32. Запустите этот код — вывод должен быть таким:

$ 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

5 в функции five — это её возвращаемое значение, поэтому тип возвращаемого значения — i32. Разберём подробнее. Здесь важны два момента. Во-первых, строка let x = five(); показывает, что мы инициализируем переменную значением, которое вернула функция. Функция five возвращает 5, так что эта строка равносильна такой:

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

Во-вторых, у функции five нет параметров, зато указан тип возвращаемого значения, а её тело — одинокое 5 без точки с запятой. Точки с запятой нет, потому что это выражение, значение которого мы хотим вернуть.

Посмотрим на другой пример:

Файл: 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
}

Этот код выведет The value of x is: 6. А что будет, если поставить точку с запятой в конце строки x + 1 и тем самым превратить выражение в инструкцию?

Файл: 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;
}

Компиляция завершится ошибкой:

$ 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

Главное сообщение, mismatched types («несовпадение типов»), указывает на суть проблемы. Функция plus_one по определению должна вернуть i32, но инструкция ни во что не вычисляется — это обозначается (), единичным типом. Получается, функция ничего не возвращает, а это противоречит её определению — отсюда и ошибка. В выводе Rust даже подсказывает, как, скорее всего, это исправить: убрать точку с запятой. И это действительно устранит ошибку.

Комментарии

Комментарии

Все программисты стараются писать понятный код, но иногда без дополнительных пояснений не обойтись. Для этого в исходном коде оставляют комментарии: компилятор их игнорирует, а людям, читающим код, они могут пригодиться.

Вот простой комментарий:

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

В Rust принято начинать комментарий с двух косых черт; комментарий продолжается до конца строки. Если комментарий занимает несколько строк, // нужно ставить в начале каждой:

#![allow(unused)]
fn main() {
// Здесь мы делаем что-то сложное — настолько, что для объяснения
// понадобилось несколько строк комментария! Уф! Надеюсь, этот комментарий
// объяснит, что тут происходит.
}

Комментарий можно поставить и в конце строки с кодом:

Файл: src/main.rs

fn main() {
    let lucky_number = 7; // Сегодня мне повезёт
}

Но чаще комментарий пишут на отдельной строке над тем кодом, к которому он относится:

Файл: src/main.rs

fn main() {
    // Сегодня мне повезёт
    let lucky_number = 7;
}

Есть в Rust и другой вид комментариев — документационные. О них мы поговорим в разделе «Публикация крейта на Crates.io» главы 14.

Управление потоком выполнения

Управление потоком выполнения

Выполнять код в зависимости от того, истинно ли условие, и повторять код, пока условие истинно, — это базовые строительные блоки большинства языков программирования. Чаще всего управлять потоком выполнения кода на Rust приходится с помощью выражений if и циклов.

Выражения if

Выражение if позволяет разветвить код в зависимости от условий. Вы задаёте условие и говорите: «Если условие выполняется, запусти этот блок кода. Если нет — не запускай».

Чтобы поэкспериментировать с if, создайте в папке projects новый проект branches. В файл src/main.rs введите следующее:

Файл: src/main.rs

fn main() {
    let number = 3;

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

Любое выражение if начинается с ключевого слова if, за которым следует условие. Здесь условие проверяет, меньше ли значение переменной number, чем 5. Блок кода, который должен выполниться, если условие истинно (true), мы пишем сразу после условия в фигурных скобках. Блоки кода, связанные с условиями в if, иногда называют ветками — так же, как ветки выражения match, о которых мы говорили в разделе «Сравниваем догадку с загаданным числом» главы 2.

При желании можно добавить и выражение else — что мы здесь и сделали. Оно задаёт альтернативный блок кода, который выполнится, если условие окажется ложным (false). Если else нет, а условие ложно, программа просто пропустит блок if и перейдёт к следующему коду.

Запустите этот код — вывод должен быть таким:

$ 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

Давайте поменяем значение number так, чтобы условие стало ложным, и посмотрим, что получится:

fn main() {
    let number = 7;

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

Снова запустите программу и посмотрите на вывод:

$ 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

Стоит отметить, что условие в этом коде обязательно должно иметь тип bool. Если это не bool, будет ошибка. Попробуйте, например, запустить такой код:

Файл: src/main.rs

fn main() {
    let number = 3;

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

На этот раз условие if вычисляется в 3, и Rust выдаёт ошибку:

$ 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

Ошибка говорит, что Rust ожидал bool, а получил целое число. В отличие от Ruby или JavaScript, Rust не пытается автоматически превратить не-логическое значение в логическое. Нужно писать явно и всегда передавать if в качестве условия логическое значение. Если, например, мы хотим, чтобы блок if выполнялся, только когда число не равно 0, выражение нужно переписать так:

Файл: src/main.rs

fn main() {
    let number = 3;

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

Этот код выведет number was something other than zero.

Несколько условий: else if

Несколько условий можно проверить, соединив if и else в выражение else if. Например:

Файл: 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");
    }
}

У этой программы четыре возможных пути выполнения. Запустив её, вы увидите:

$ 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

Программа по очереди проверяет каждое условие if и выполняет тело первого, которое окажется истинным. Обратите внимание: хотя 6 делится на 2, мы не видим ни number is divisible by 2, ни текста number is not divisible by 4, 3, or 2 из блока else. Дело в том, что Rust выполняет блок только для первого истинного условия, а найдя его, остальные даже не проверяет.

Если else if слишком много, код становится запутанным. Так что если их больше одного, возможно, стоит переписать код. Для таких случаев в главе 6 описана мощная конструкция ветвления Rust — match.

if в инструкции let

Раз if — это выражение, его можно поставить справа в инструкции let и присвоить результат переменной, как в листинге 3-2.

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

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

Переменная number получит значение в зависимости от результата выражения if. Запустите код и посмотрите, что получится:

$ 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

Напомним, что блок кода вычисляется в своё последнее выражение, а число само по себе — тоже выражение. В нашем случае значение всего выражения if зависит от того, какой блок выполнится. Значит, все значения, которые может вернуть каждая ветка if, должны быть одного типа. В листинге 3-2 и ветка if, и ветка else давали целые числа типа i32. Если типы не совпадают, как в следующем примере, будет ошибка:

Файл: src/main.rs

fn main() {
    let condition = true;

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

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

При компиляции этого кода мы получим ошибку. Ветки if и else возвращают значения несовместимых типов, и Rust точно указывает, где в программе проблема:

$ 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

Выражение в блоке if вычисляется в целое число, а выражение в блоке else — в строку. Так нельзя: у переменной может быть только один тип, и Rust должен ещё при компиляции точно знать, какого типа переменная number. Зная её тип, компилятор может проверить, что везде, где используется number, тип подходит. Если бы тип number становился известен только во время выполнения, такой проверки бы не было. Компилятору пришлось бы держать в уме сразу несколько возможных типов для каждой переменной — он стал бы сложнее, а гарантий о коде давал бы меньше.

Повторение: циклы

Часто бывает нужно выполнить блок кода несколько раз. Для этого в Rust есть несколько видов циклов: цикл выполняет код в своём теле до конца и сразу же начинает сначала. Чтобы поэкспериментировать с циклами, создадим новый проект loops.

В Rust три вида циклов: loop, while и for. Попробуем каждый.

Повторение кода с loop

Ключевое слово loop говорит Rust выполнять блок кода снова и снова — бесконечно или пока вы явно не скажете остановиться.

Для примера замените содержимое src/main.rs в папке loops на такое:

Файл: src/main.rs

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

Если запустить эту программу, again! будет выводиться снова и снова, пока мы не остановим её вручную. Большинство терминалов поддерживают сочетание ctrl-C, которое прерывает зациклившуюся программу. Попробуйте:

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

^C отмечает момент, когда вы нажали ctrl-C.

После ^C слово again! может появиться, а может и нет — это зависит от того, в каком месте цикла был код, когда пришёл сигнал прерывания.

К счастью, выйти из цикла можно и из кода. Для этого внутри цикла ставят ключевое слово break — оно говорит программе, когда прекратить выполнение цикла. Вспомните: мы уже делали так в игре «Угадай число», в разделе «Выход после правильного ответа» главы 2, — чтобы программа завершалась, когда пользователь угадал число.

В той же игре мы использовали и continue. В цикле оно говорит программе пропустить весь оставшийся код текущей итерации и перейти к следующей.

Возврат значений из цикла

Одно из применений loop — повторять операцию, которая может не удаться, например проверять, закончил ли поток свою работу. При этом результат операции может понадобиться вынести из цикла в остальной код. Для этого добавьте нужное значение после выражения break, которым вы останавливаете цикл: это значение вернётся из цикла, и его можно будет использовать. Вот так:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

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

Перед циклом мы объявляем переменную counter и инициализируем её значением 0. Затем объявляем переменную result, в которую попадёт значение, возвращённое циклом. На каждой итерации мы прибавляем к counter единицу и проверяем, не равен ли counter десяти. Когда равен, вызываем break со значением counter * 2. После цикла стоит точка с запятой — она завершает инструкцию, которая присваивает значение result. В конце мы выводим значение result — в данном случае 20.

Из цикла можно выйти и через return. Разница в том, что break выходит только из текущего цикла, а return — всегда из текущей функции.

Метки циклов

Если циклы вложены друг в друга, break и continue относятся к самому внутреннему циклу в этом месте. Но циклу можно дать метку (loop label) и затем указать её в break или continue — тогда они будут относиться к помеченному циклу, а не к самому внутреннему. Метка цикла должна начинаться с одинарной кавычки. Вот пример с двумя вложенными циклами:

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

У внешнего цикла метка 'counting_up, он считает от 0 до 2. Внутренний цикл без метки считает от 10 до 9. Первый break без метки выходит только из внутреннего цикла, а инструкция break 'counting_up; выходит из внешнего. Этот код выведет:

$ 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

Циклы с условием: while

Программе часто нужно проверять условие внутри цикла: пока оно истинно, цикл работает, а как только перестаёт быть истинным, программа вызывает break и цикл останавливается. Такое поведение можно собрать из loop, if, else и break — если хотите, попробуйте прямо сейчас. Но этот шаблон встречается настолько часто, что в Rust для него есть встроенная конструкция — цикл while. В листинге 3-3 с помощью while программа трижды проходит цикл, каждый раз уменьшая счётчик, а после цикла выводит сообщение и завершается.

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

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

Эта конструкция избавляет от лишней вложенности, которая понадобилась бы с loop, if, else и break, и читается понятнее. Пока условие истинно, код выполняется; как только станет ложным — цикл завершается.

Обход коллекции с for

Перебрать элементы коллекции, например массива, можно и с помощью while. Скажем, цикл в листинге 3-4 выводит каждый элемент массива 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;
    }
}

Здесь код перебирает элементы массива по индексу: начинает с 0 и крутится, пока не дойдёт до последнего индекса (то есть пока index < 5 не перестанет быть истинным). Код выведет все элементы массива:

$ 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

Как и ожидалось, в терминале появились все пять значений. Хотя index в какой-то момент становится равным 5, цикл останавливается раньше, чем программа попытается достать из массива шестое значение.

Но такой подход чреват ошибками: если индекс или условие окажутся неверными, программа может запаниковать. Например, если сократить массив a до четырёх элементов и забыть поменять условие на while index < 4, код запаникует. К тому же он медленный: компилятор добавляет код, который на каждой итерации во время выполнения проверяет, не вышел ли индекс за границы массива.

Более лаконичная альтернатива — цикл for, который выполняет код для каждого элемента коллекции. Он выглядит как в листинге 3-5.

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

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

Вывод будет таким же, как в листинге 3-4. Но, что важнее, код стал безопаснее: исчезла возможность ошибиться — выйти за конец массива или, наоборот, не дойти до конца и пропустить элементы. Машинный код для циклов for к тому же может быть эффективнее, ведь индекс не нужно сравнивать с длиной массива на каждой итерации.

С циклом for вам не придётся помнить, что нужно поменять ещё какой-то код, если в массиве изменится количество элементов, — а со способом из листинга 3-4 пришлось бы.

Благодаря безопасности и лаконичности for — самый популярный вид цикла в Rust. Даже когда нужно выполнить код определённое число раз, как в примере с обратным отсчётом через while из листинга 3-3, большинство растацеанов возьмут for. Для этого используют Range (диапазон) из стандартной библиотеки: он по порядку выдаёт числа от начального значения до конечного, не включая само конечное.

Вот как выглядит обратный отсчёт с циклом for и ещё одним методом, о котором мы пока не говорили, — rev, который разворачивает диапазон:

Файл: src/main.rs

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

Так ведь приятнее, правда?

Итоги

Вы справились! Глава была немаленькая: вы узнали о переменных, скалярных и составных типах данных, функциях, комментариях, выражениях if и циклах. Чтобы потренироваться, попробуйте написать программы, которые:

• переводят температуру из градусов Фаренгейта в градусы Цельсия и обратно;
• вычисляют n-е число Фибоначчи;
• выводят текст рождественской песни «The Twelve Days of Christmas» («Двенадцать дней Рождества»), используя то, что куплеты в ней повторяются.

Когда будете готовы двигаться дальше, мы поговорим о понятии, которого в других языках программирования обычно нет, — о владении.

Что такое владение

Владение (ownership) — самая необычная особенность Rust, и она глубоко влияет на весь остальной язык. Именно владение позволяет Rust гарантировать безопасную работу с памятью без сборщика мусора, поэтому так важно понять, как оно устроено. В этой главе мы поговорим о владении и нескольких связанных с ним вещах: заимствовании, срезах и о том, как Rust располагает данные в памяти.

Владение

Владение

Владение — это набор правил, по которым программа на Rust управляет памятью. Любой программе во время работы приходится как-то распоряжаться памятью компьютера. В некоторых языках есть сборщик мусора: пока программа работает, он регулярно ищет память, которая больше не используется. В других языках программист должен сам явно выделять и освобождать память. Rust идёт третьим путём: памятью управляет система владения — набор правил, которые проверяет компилятор. Если хоть одно правило нарушено, программа не скомпилируется. При этом никакая часть механизма владения не замедляет программу во время работы.

Для многих программистов владение — новое понятие, и к нему нужно привыкнуть. Хорошая новость: чем больше у вас опыта с Rust и правилами владения, тем естественнее у вас будет получаться безопасный и эффективный код. Не сдавайтесь!

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

Правила владения

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

• У каждого значения в Rust есть владелец (owner).
• В каждый момент времени владелец может быть только один.
• Когда владелец выходит из области видимости, значение уничтожается (dropped).

Область видимости переменной

С базовым синтаксисом Rust мы разобрались, поэтому дальше в примерах не будем писать fn main() {. Если вы повторяете примеры, не забывайте сами помещать их внутрь функции main. Так примеры получатся короче, и мы сможем сосредоточиться на сути, а не на шаблонном коде.

Первым примером владения будет область видимости переменных. Область видимости (scope) — это участок программы, в пределах которого элемент действителен. Возьмём такую переменную:

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

Переменная s ссылается на строковый литерал — строку, значение которой вписано прямо в текст программы. Переменная действительна с момента объявления и до конца текущей области видимости. В листинге 4-1 комментарии показывают, где переменная s действительна.

fn main() {
    {                      // здесь s ещё нет: она пока не объявлена
        let s = "hello";   // с этого места s можно использовать

        // что-то делаем с s
    }                      // область видимости закончилась, s больше нельзя использовать
}

Иными словами, здесь есть два важных момента:

• Когда s входит в область видимости, она становится действительной.
• Она остаётся действительной, пока не выйдет из области видимости.

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

Тип String

Чтобы показать правила владения в действии, нам нужен тип посложнее тех, что мы рассматривали в разделе «Типы данных» главы 3. Размер тех типов известен заранее. Поэтому их значения можно хранить на стеке и снимать со стека, когда заканчивается область видимости. А если такое же значение понадобится другой части кода, его легко и быстро скопировать в новый независимый экземпляр. Нам же интересны данные в куче: как Rust понимает, что их пора освобождать? Тип String — отличный пример.

Мы сосредоточимся на тех свойствах String, которые связаны с владением. Они относятся и к другим сложным типам данных — как из стандартной библиотеки, так и созданным вами. Об остальных свойствах String мы поговорим в главе 8.

Строковые литералы, у которых значение вписано прямо в программу, мы уже видели. Они удобны, но годятся не для всех задач, связанных с текстом. Во-первых, они неизменяемые. Во-вторых, не любое строковое значение известно заранее, когда мы пишем код: например, что если нужно получить ввод пользователя и сохранить его? Для таких случаев в Rust есть тип String. Он управляет данными, выделенными в куче, и поэтому может хранить текст, объём которого неизвестен при компиляции. String можно создать из строкового литерала функцией from:

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

Оператор :: позволяет поместить функцию from в пространство имён типа String, а не придумывать ей имя вроде string_from. Подробнее об этом синтаксисе мы поговорим в разделе «Методы» главы 5, а также когда будем обсуждать пространства имён и модули в разделе «Пути к элементам в дереве модулей» главы 7.

Такую строку можно изменять:

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

    s.push_str(", world!"); // push_str() дописывает литерал в конец String

    println!("{s}"); // выведет `hello, world!`
}

В чём же разница? Почему String можно менять, а литералы — нет? Всё дело в том, как эти два типа работают с памятью.

Память и её выделение

Содержимое строкового литерала известно при компиляции, поэтому текст вписывается прямо в итоговый исполняемый файл. Отсюда скорость и эффективность строковых литералов. Но эти свойства — следствие их неизменяемости. К сожалению, невозможно заранее зашить в бинарник кусок памяти под каждый текст, размер которого неизвестен при компиляции и может меняться во время работы программы.

Чтобы String мог хранить изменяемый текст, способный расти, ему нужна память в куче — заранее неизвестного размера. Это означает следующее:

• Память нужно запросить у распределителя во время выполнения программы.
• Нужен способ вернуть эту память распределителю, когда String нам больше не нужна.

Первую часть делаем мы сами: когда мы вызываем String::from, его реализация запрашивает нужную память. Так устроено практически во всех языках программирования.

А вот со второй частью всё иначе. В языках со сборщиком мусора (garbage collector, GC) сборщик сам отслеживает и освобождает память, которая больше не используется, и думать об этом не нужно. В большинстве языков без сборщика мусора мы сами должны определить, когда память больше не нужна, и явно вызвать код, который её освободит, — так же, как явно её запрашивали. Делать это правильно исторически было непростой задачей. Забудем освободить — память утечёт. Освободим слишком рано — получим недействительную переменную. Освободим дважды — тоже баг. Каждому выделению (allocate) должно соответствовать ровно одно освобождение (free).

Rust идёт другим путём: память автоматически возвращается, как только переменная, которая ею владеет, выходит из области видимости. Вот наш пример с областью видимости из листинга 4-1, только с String вместо строкового литерала:

fn main() {
    {
        let s = String::from("hello"); // с этого места s можно использовать

        // что-то делаем с s
    }                                  // область видимости закончилась, s больше
                                       // нельзя использовать
}

Есть естественный момент, когда память, нужную нашей String, можно вернуть распределителю, — когда s выходит из области видимости. В этот момент Rust вызывает для нас специальную функцию. Она называется drop, и именно в неё автор типа String может поместить код, возвращающий память. Rust вызывает drop автоматически на закрывающей фигурной скобке.

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

Переменные и данные: перемещение

Что происходит, когда значение одной переменной присваивают другой? В Rust ответ зависит от типа данных. Начнём с целого числа — листинг 4-2.

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

Нетрудно догадаться, что здесь происходит: «привязать значение 5 к x; затем скопировать значение из x и привязать копию к y». Теперь у нас две переменные, x и y, и обе равны 5. Так и есть: целые числа — простые значения известного фиксированного размера, и оба значения 5 кладутся на стек.

Теперь посмотрим на версию со String:

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

Код очень похож, и можно подумать, что работает он так же: вторая строка копирует значение из s1 и привязывает его к s2. Но на самом деле происходит не совсем это.

Посмотрите на рисунок 4-1 — там показано, что творится со String «под капотом». String состоит из трёх частей (они слева): указателя на память, в которой лежит содержимое строки, длины и ёмкости. Эта группа данных хранится на стеке. Справа — память в куче, где лежит само содержимое.

Рисунок 4-1: Представление в памяти String со значением "hello", привязанной к s1

Длина — это сколько памяти (в байтах) сейчас занимает содержимое String. Ёмкость — сколько всего памяти (в байтах) String получила от распределителя. Разница между длиной и ёмкостью важна, но не здесь, так что пока про ёмкость можно забыть.

Когда мы присваиваем s1 переменной s2, копируются данные String на стеке — указатель, длина и ёмкость. Данные в куче, на которые указывает указатель, не копируются. Иначе говоря, в памяти получается то, что показано на рисунке 4-2.

Рисунок 4-2: Представление в памяти переменной s2, у которой копия указателя, длины и ёмкости из s1

А вот так, как на рисунке 4-3, память не выглядит. Так было бы, если бы Rust копировал ещё и данные в куче. Тогда при больших данных в куче операция s2 = s1 могла бы обходиться очень дорого.

Рисунок 4-3: Другой возможный вариант s2 = s1 — если бы Rust копировал и данные в куче

Выше мы говорили, что, когда переменная выходит из области видимости, Rust автоматически вызывает drop и освобождает память в куче, принадлежащую этой переменной. Но на рисунке 4-2 оба указателя ведут в одно и то же место. В этом и проблема: когда s2 и s1 выйдут из области видимости, обе попытаются освободить одну и ту же память. Это называется ошибкой двойного освобождения (double free) — одна из тех ошибок безопасности памяти, о которых мы говорили раньше. Двойное освобождение может повредить память, а это, в свою очередь, может привести к уязвимостям.

Чтобы обеспечить безопасность памяти, после строки let s2 = s1; Rust считает s1 недействительной. Поэтому, когда s1 выходит из области видимости, освобождать ничего не нужно: память теперь принадлежит только s2. Посмотрите, что будет, если попытаться использовать s1 после того, как создана s2, — ничего не выйдет:

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

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

Вы получите примерно такую ошибку — Rust не даёт использовать недействительную ссылку:

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

Если в других языках вам встречались понятия поверхностного копирования (shallow copy) и глубокого копирования (deep copy), то копирование указателя, длины и ёмкости без самих данных, скорее всего, напомнит вам поверхностное копирование. Но поскольку Rust к тому же делает первую переменную недействительной, это называют не поверхностным копированием, а перемещением (move). В нашем примере говорят, что s1 переместилась в s2. На самом деле происходит то, что показано на рисунке 4-4.

Рисунок 4-4: Представление в памяти после того, как s1 стала недействительной

Проблема решена! Действительна только s2, поэтому, когда она выйдет из области видимости, память освободит она одна — и всё.

Из этого вытекает ещё одно проектное решение: Rust никогда автоматически не создаёт «глубоких» копий ваших данных. Поэтому любое автоматическое копирование можно считать дешёвым с точки зрения производительности.

Область видимости и присваивание

Есть и обратная ситуация, где тоже видна связь между областью видимости, владением и drop. Если присвоить уже существующей переменной новое значение, Rust сразу вызовет drop для старого значения и освободит его память. Например:

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

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

Сначала мы объявляем переменную s и привязываем к ней String со значением "hello". Затем сразу создаём новую String со значением "ahoy" и присваиваем её s. В этот момент на исходное значение в куче уже ничто не ссылается. Рисунок 4-5 показывает, что теперь на стеке и в куче:

Рисунок 4-5: Представление в памяти после того, как исходное значение полностью заменено

Таким образом, исходная строка сразу выходит из области видимости. Rust вызывает для неё drop, и её память тут же освобождается. Когда в конце мы выводим значение, получаем "ahoy, world!".

Переменные и данные: клонирование

Если же мы действительно хотим глубоко скопировать данные String из кучи, а не только данные на стеке, можно воспользоваться распространённым методом clone. Синтаксис методов мы обсудим в главе 5, но методы есть во многих языках, так что вы наверняка с ними уже встречались.

Вот как работает метод clone:

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

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

Этот код прекрасно работает и явно делает то, что показано на рисунке 4-3: данные в куче действительно копируются.

Увидев вызов clone, вы понимаете, что выполняется какой-то произвольный код и он может быть дорогим. Это наглядный сигнал: здесь происходит что-то особенное.

Данные только на стеке: копирование

Есть ещё одна тонкость, о которой мы пока не говорили. Вот код с целыми числами (часть его была в листинге 4-2) — он работает и корректен:

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

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

Но он вроде бы противоречит тому, что мы только что узнали: clone не вызывается, а x по-прежнему действительна и не переместилась в y.

Дело в том, что типы вроде целых чисел, размер которых известен при компиляции, целиком хранятся на стеке, и скопировать само значение очень быстро. Значит, нет никаких причин делать x недействительной после создания y. Иными словами, здесь нет разницы между глубоким и поверхностным копированием: clone сделал бы то же самое, что и обычное копирование, так что его можно не писать.

В Rust есть специальная пометка — трейт Copy, который можно реализовать для типов, хранящихся на стеке, как целые числа (подробнее о трейтах — в главе 10). Если тип реализует трейт Copy, его переменные не перемещаются, а просто копируются, и после присваивания другой переменной остаются действительными.

Rust не позволит пометить тип как Copy, если сам тип или любая его часть реализует трейт Drop. Если при выходе значения из области видимости для типа должно происходить что-то особенное, а вы добавите ему пометку Copy, будет ошибка компиляции. О том, как добавить пометку Copy к своему типу и тем самым реализовать этот трейт, читайте в разделе «Выводимые трейты» приложения C.

Так какие же типы реализуют Copy? Точно можно узнать в документации к конкретному типу, но общее правило такое: Copy может реализовать любая группа простых скалярных значений, и не может — ничто, что требует выделения памяти или является каким-либо ресурсом. Вот некоторые типы, реализующие Copy:

• Все целочисленные типы, например u32.
• Логический тип bool со значениями true и false.
• Все типы с плавающей точкой, например f64.
• Символьный тип char.
• Кортежи, если все их элементы тоже реализуют Copy. Например, (i32, i32) реализует Copy, а (i32, String) — нет.

Владение и функции

Передача значения в функцию устроена так же, как присваивание значения переменной: значение либо перемещается, либо копируется. В листинге 4-3 пример с комментариями о том, где переменные входят в область видимости и выходят из неё.

fn main() {
    let s = String::from("hello");  // s входит в область видимости

    takes_ownership(s);             // значение s перемещается в функцию...
                                    // ...поэтому дальше s использовать нельзя

    let x = 5;                      // x входит в область видимости

    makes_copy(x);                  // i32 реализует трейт Copy,
                                    // поэтому x НЕ перемещается в функцию,
                                    // и x можно использовать и дальше.

} // Здесь из области видимости выходит x, затем s. Но значение s уже
  // перемещено, поэтому ничего особенного не происходит.

fn takes_ownership(some_string: String) { // some_string входит в область видимости
    println!("{some_string}");
} // Здесь some_string выходит из области видимости, вызывается `drop`,
  // и память, где лежала строка, освобождается.

fn makes_copy(some_integer: i32) { // some_integer входит в область видимости
    println!("{some_integer}");
} // Здесь some_integer выходит из области видимости. Ничего особенного не происходит.

Если бы мы попытались использовать s после вызова takes_ownership, Rust выдал бы ошибку компиляции. Такие статические проверки уберегают нас от ошибок. Попробуйте добавить в main код, который использует s и x, и посмотрите, где их использовать можно, а где правила владения не позволяют.

Возвращаемые значения и область видимости

Возврат значения тоже может передавать владение. В листинге 4-4 пример функции, которая возвращает значение, — с такими же пометками, как в листинге 4-3.

fn main() {
    let s1 = gives_ownership();        // gives_ownership перемещает своё
                                       // возвращаемое значение в s1

    let s2 = String::from("hello");    // s2 входит в область видимости

    let s3 = takes_and_gives_back(s2); // s2 перемещается в
                                       // takes_and_gives_back, а та
                                       // перемещает своё возвращаемое значение в s3
} // Здесь s3 выходит из области видимости и уничтожается. s2 уже перемещена,
  // с ней ничего не происходит. s1 выходит из области видимости и уничтожается.

fn gives_ownership() -> String {       // gives_ownership переместит своё
                                       // возвращаемое значение в ту функцию,
                                       // которая её вызвала

    let some_string = String::from("yours"); // some_string входит в область видимости

    some_string                        // some_string возвращается и
                                       // перемещается в вызывающую
                                       // функцию
}

// Эта функция принимает String и возвращает String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string входит в
    // область видимости

    a_string  // a_string возвращается и перемещается в вызывающую функцию
}

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

Так работать можно, но забирать владение и возвращать его в каждой функции утомительно. А что, если мы хотим, чтобы функция воспользовалась значением, но не забирала его себе? Довольно неудобно, что всё переданное в функцию нужно ещё и возвращать обратно, если мы хотим пользоваться им дальше, — да ещё вместе с результатом работы самой функции, если он нам тоже нужен.

Вернуть несколько значений Rust позволяет с помощью кортежа, как показано в листинге 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() возвращает длину String

    (s, length)
}

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

Ссылки и заимствование

Ссылки и заимствование

Проблема с кортежем в листинге 4-5 в том, что String приходится возвращать обратно вызывающей функции. Иначе после вызова calculate_length мы не смогли бы пользоваться этой строкой — ведь она переместилась в calculate_length. Вместо этого можно передать ссылку на значение String. Ссылка похожа на указатель: это адрес, по которому можно добраться до данных, а владеет этими данными какая-то другая переменная. Но, в отличие от указателя, ссылка гарантированно указывает на действительное значение определённого типа всё время, пока сама ссылка существует.

Вот как определить и использовать функцию calculate_length, которая принимает параметром не само значение (и не забирает владение), а ссылку на него:

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()
}

Во-первых, заметьте: весь код с кортежами — и в объявлении переменной, и в возвращаемом значении функции — исчез. Во-вторых, в calculate_length мы передаём &s1, а в её определении принимаем &String, а не String. Эти амперсанды и обозначают ссылки: они позволяют обратиться к значению, не забирая владения им. Это показано на рисунке 4-6.

Рисунок 4-6: Схема: &String s указывает на String s1

Посмотрим внимательнее на вызов функции:

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()
}

Запись &s1 создаёт ссылку, которая указывает на значение s1, но не владеет им. Раз ссылка не владеет значением, оно не будет уничтожено, когда ссылка перестанет использоваться.

Сигнатура функции тоже использует &, показывая, что параметр s — ссылка. Добавим поясняющие комментарии:

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 — ссылка на String
    s.len()
} // Здесь s выходит из области видимости. Но s не владеет строкой, на которую
  // ссылается, поэтому строка не уничтожается.

Переменная s действительна в той же области видимости, что и любой параметр функции. Но когда s перестаёт использоваться, значение, на которое она ссылается, не уничтожается — потому что s им не владеет. Если функция принимает параметрами ссылки, а не сами значения, ей не нужно возвращать значения, чтобы вернуть владение: владения у неё никогда и не было.

Создание ссылки называется заимствованием (borrowing). Как и в жизни: если у кого-то есть вещь, вы можете взять её взаймы. Попользовались — нужно вернуть. Вещь не ваша.

А что будет, если попытаться изменить то, что мы позаимствовали? Попробуйте код из листинга 4-6. Спойлер: не сработает!

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

    change(&s);
}

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

Вот ошибка:

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

Ссылки, как и переменные, по умолчанию неизменяемые. Изменить то, на что у нас есть (обычная) ссылка, нельзя.

Изменяемые ссылки

Код из листинга 4-6 можно исправить так, чтобы заимствованное значение можно было менять. Для этого достаточно пары небольших правок — и использовать изменяемую ссылку (mutable reference):

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

    change(&mut s);
}

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

Сначала мы делаем саму переменную s изменяемой (mut). Затем там, где вызывается функция change, создаём изменяемую ссылку &mut s, а в сигнатуре функции указываем, что она принимает изменяемую ссылку: some_string: &mut String. Теперь сразу видно, что функция change будет менять значение, которое заимствует.

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

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

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

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

Вот ошибка:

$ 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

Ошибка говорит, что код некорректен: нельзя заимствовать s как изменяемую больше одного раза одновременно. Первое изменяемое заимствование — r1. Оно действует до строки с println!, где r1 используется. А мы как раз в этом промежутке, между созданием r1 и её использованием, создаём вторую изменяемую ссылку на те же данные — r2.

Запрет на несколько одновременных изменяемых ссылок на одни и те же данные позволяет изменять данные, но под строгим контролем. Новичкам в Rust это поначалу даётся тяжело: в большинстве языков менять данные можно когда угодно. Зато благодаря этому ограничению Rust предотвращает гонки данных (data races) ещё на этапе компиляции. Гонка данных похожа на состояние гонки и возникает, когда одновременно выполняются три условия:

• Два или больше указателя одновременно обращаются к одним и тем же данным.
• Хотя бы один из указателей используется для записи.
• Нет никакого механизма синхронизации доступа к данным.

Гонки данных приводят к неопределённому поведению, и их трудно отловить и исправить во время выполнения. Rust решает эту проблему радикально: код с гонками данных он просто не компилирует!

Как обычно, с помощью фигурных скобок можно создать новую область видимости. Так можно завести несколько изменяемых ссылок — главное, чтобы они не существовали одновременно:

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

    {
        let r1 = &mut s;
    } // здесь r1 выходит из области видимости, так что можно спокойно создать новую ссылку

    let r2 = &mut s;
}

Похожее правило действует и для сочетания изменяемых и неизменяемых ссылок. Этот код вызовет ошибку:

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

    let r1 = &s; // без проблем
    let r2 = &s; // без проблем
    let r3 = &mut s; // БОЛЬШАЯ ПРОБЛЕМА

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

Вот ошибка:

$ 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; // без проблем
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // без проблем
6 |     let r3 = &mut s; // БОЛЬШАЯ ПРОБЛЕМА
  |              ^^^^^^ 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

Ух! Получается, что изменяемую ссылку нельзя создать и тогда, когда на то же значение уже есть неизменяемая.

Те, кто пользуется неизменяемой ссылкой, вовсе не ждут, что значение вдруг поменяется у них под носом! А вот несколько неизменяемых ссылок одновременно — можно: кто просто читает данные, никак не мешает читать другим.

Учтите, что область действия ссылки начинается там, где ссылку создали, и длится до места, где ссылка используется в последний раз. Например, следующий код скомпилируется: неизменяемые ссылки последний раз используются в println!, а изменяемая ссылка создаётся уже после этого:

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

    let r1 = &s; // без проблем
    let r2 = &s; // без проблем
    println!("{r1} and {r2}");
    // Дальше r1 и r2 больше не используются.

    let r3 = &mut s; // без проблем
    println!("{r3}");
}

Область действия неизменяемых ссылок r1 и r2 заканчивается после println!, где они используются последний раз, — то есть ещё до того, как создаётся изменяемая ссылка r3. Эти области не пересекаются, поэтому код допустим: компилятор видит, что ссылка больше не используется, ещё до конца области видимости.

Ошибки заимствования временами раздражают, но помните: это компилятор Rust заранее указывает на потенциальный баг (при компиляции, а не во время работы) и показывает, где именно проблема. И вам не придётся выяснять, почему данные оказались не такими, как вы думали.

Висячие ссылки

В языках с указателями легко по ошибке создать висячий указатель (dangling pointer) — указатель на участок памяти, который, возможно, уже отдан кому-то другому. Для этого достаточно освободить память, но сохранить указатель на неё. В Rust же компилятор гарантирует, что ссылки никогда не станут висячими: если у вас есть ссылка на какие-то данные, компилятор проследит, чтобы данные не вышли из области видимости раньше, чем ссылка на них.

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

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

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

    &s
}

Вот ошибка:

$ 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

Это сообщение упоминает возможность, которую мы ещё не разбирали, — времена жизни (lifetimes). Подробно о них мы поговорим в главе 10. Но если не обращать внимания на части про времена жизни, в сообщении есть ключ к тому, почему этот код проблемный:

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

(«возвращаемый тип этой функции содержит заимствованное значение, но заимствовать его не у чего».)

Разберём по шагам, что происходит в нашей функции dangle:

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

fn dangle() -> &String { // dangle возвращает ссылку на String

    let s = String::from("hello"); // s — новая String

    &s // возвращаем ссылку на String s
} // Здесь s выходит из области видимости и уничтожается, её память освобождается.
  // Опасно!

Строка s создаётся внутри dangle, поэтому, когда код dangle завершится, память s будет освобождена. А мы пытаемся вернуть ссылку на неё. Значит, эта ссылка указывала бы на уже недействительную String. Так не пойдёт! Rust этого не допустит.

Решение — вернуть саму String:

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

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

    s
}

Так всё работает без проблем: владение перемещается наружу, и ничего не освобождается.

Правила ссылок

Подытожим, что мы узнали о ссылках:

• В каждый момент времени может быть либо одна изменяемая ссылка, либо сколько угодно неизменяемых.
• Ссылки всегда должны быть действительными.

Дальше мы рассмотрим другой вид ссылок — срезы.

Срезы

Срезы

Срезы (slices) позволяют сослаться на непрерывную последовательность элементов коллекции, а не на всю коллекцию целиком. Срез — это разновидность ссылки, поэтому владения у него нет.

Вот небольшая задачка: написать функцию, которая принимает строку из слов, разделённых пробелами, и возвращает первое слово. Если в строке нет пробела, значит, вся строка — одно слово, и вернуть нужно её целиком.

Чтобы понять, какую проблему решают срезы, сначала попробуем написать сигнатуру такой функции без них:

fn first_word(s: &String) -> ?

Параметр функции first_word имеет тип &String. Владение нам не нужно, так что это нормально. (В идиоматичном Rust функции не забирают владение аргументами без необходимости — почему, станет понятно дальше.) Но что возвращать? У нас пока нет способа описать часть строки. Зато можно вернуть индекс конца слова — то есть позицию пробела. Попробуем, как в листинге 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() {}

Нам нужно пройтись по String элемент за элементом и проверить, не пробел ли это. Поэтому сначала превращаем String в массив байтов методом 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() {}

Затем методом 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() {}

Подробно итераторы разбираются в главе 13. Пока достаточно знать, что iter — метод, который по очереди выдаёт каждый элемент коллекции, а enumerate оборачивает результат iter и выдаёт каждый элемент в составе кортежа. Первый элемент кортежа из enumerate — индекс, второй — ссылка на сам элемент. Так удобнее, чем считать индекс вручную.

Раз enumerate возвращает кортеж, его можно разобрать с помощью образца. Подробнее об образцах мы поговорим в главе 6. В цикле for мы указываем образец, где i — индекс из кортежа, а &item — байт из кортежа. Поскольку .iter().enumerate() даёт нам ссылку на элемент, в образце стоит &.

Внутри цикла for мы ищем байт пробела, записав его как байтовый литерал. Если пробел нашёлся, возвращаем его позицию. Если нет — возвращаем длину строки, 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() {}

Теперь мы умеем находить индекс конца первого слова, но есть проблема. Мы возвращаем отдельное число usize, а смысл у него есть только в связке с конкретной строкой &String. Иначе говоря, это значение живёт отдельно от String, и нет никакой гарантии, что оно останется верным в будущем. Посмотрите на программу из листинга 4-8, которая использует first_word из листинга 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 получит значение 5

    s.clear(); // очищаем String: теперь она равна ""

    // word по-прежнему равно 5, но в s больше нет текста, к которому это
    // число имело бы смысл, так что word теперь совершенно бесполезно!
}

Эта программа компилируется без ошибок — и скомпилировалась бы, даже если бы мы использовали word после вызова s.clear(). Переменная word никак не связана с состоянием s, поэтому в ней по-прежнему лежит 5. Мы могли бы попытаться вырезать из s первое слово с помощью этой пятёрки, но это был бы баг: с тех пор как мы сохранили 5 в word, содержимое s изменилось.

Следить за тем, чтобы индекс в word не разошёлся с данными в s, — утомительно, и легко ошибиться! А если написать ещё и функцию second_word, всё станет ещё хрупче. Её сигнатура выглядела бы так:

fn second_word(s: &String) -> (usize, usize) {

Теперь нужно отслеживать и начальный, и конечный индекс. Оба числа вычислены по строке в какой-то момент, но если строка потом изменится, сами числа об этом не узнают. Получается три независимые переменные — строка и два индекса, — и следить, чтобы они не разошлись, приходится вручную.

К счастью, у Rust есть решение — строковые срезы.

Строковые срезы

Строковый срез (string slice) — это ссылка на непрерывную часть String. Выглядит он так:

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

    let hello = &s[0..5];
    let world = &s[6..11];
}

Здесь hello ссылается не на всю String, а только на её часть, заданную добавкой [0..5]. Срез создаётся указанием диапазона в квадратных скобках: [начальный_индекс..конечный_индекс], где начальный_индекс — первая позиция среза, а конечный_индекс — позиция, следующая за последней. Внутри срез хранит начальную позицию и длину, равную конечный_индекс минус начальный_индекс. Так, в let world = &s[6..11]; срез world содержит указатель на байт с индексом 6 в s и длину 5.

На рисунке 4-7 это показано схематично.

Рисунок 4-7: Строковый срез, ссылающийся на часть String

Если диапазон .. начинается с индекса 0, число перед двумя точками можно не писать. То есть эти две строки равнозначны:

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

let slice = &s[0..2];
let slice = &s[..2];
}

Точно так же, если срез доходит до последнего байта String, можно не писать число в конце. Эти строки тоже равнозначны:

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

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

А если опустить оба числа, получится срез всей строки. Эти строки равнозначны:

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

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

Теперь перепишем first_word так, чтобы она возвращала срез. Тип «строковый срез» записывается как &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() {}

Индекс конца слова мы находим так же, как в листинге 4-7, — ищем первый пробел. Найдя его, возвращаем строковый срез: от начала строки до индекса пробела.

Теперь first_word возвращает одно значение, которое привязано к исходным данным. Оно состоит из ссылки на начало среза и количества элементов в нём.

Для функции second_word возврат среза тоже подойдёт:

fn second_word(s: &String) -> &str {

Теперь у нас простой API, который гораздо сложнее использовать неправильно: компилятор сам следит, чтобы ссылки внутрь String оставались действительными. Помните баг из листинга 4-8? Мы получили индекс конца первого слова, а потом очистили строку, и индекс стал бессмысленным. Код был логически неверным, но никаких ошибок сразу не показывал. Проблемы всплыли бы позже — если бы мы продолжили пользоваться индексом первого слова с уже пустой строкой. Срезы делают такой баг невозможным и сообщают о проблеме гораздо раньше. Версия first_word со срезом приведёт к ошибке компиляции:

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(); // ошибка!

    println!("the first word is: {word}");
}

Вот ошибка компиляции:

$ 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(); // ошибка!
   |     ^^^^^^^^^ 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

Почему так? Вспомните правило заимствования: пока на значение есть неизменяемая ссылка, изменяемую ссылку на него взять нельзя. Теперь посмотрим, что происходит в коде:

• word — это срез строки s, то есть неизменяемая ссылка на s.
• Метод clear очищает строку s, а значит, меняет её. Для этого ему нужна изменяемая ссылка на s.
• После clear идёт println!, который использует word. Значит, в момент вызова clear неизменяемая ссылка word всё ещё нужна — она «жива».

Выходит, что в момент вызова clear на строку s должны одновременно существовать и неизменяемая ссылка (word), и изменяемая (для clear). Rust это запрещает, и компиляция завершается ошибкой. Так Rust не только сделал наш API удобнее, но и избавил нас от целого класса ошибок — ещё до запуска программы!

Строковые литералы — это срезы

Мы говорили, что строковые литералы хранятся прямо внутри бинарного файла. Теперь, зная о срезах, можно как следует понять, что такое строковый литерал:

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

Тип s здесь — &str: это срез, указывающий на определённое место в бинарном файле. Поэтому строковые литералы и неизменяемы: &str — неизменяемая ссылка.

Строковые срезы как параметры

Раз срезы можно брать и у литералов, и у значений String, сигнатуру first_word можно улучшить ещё. Сейчас она такая:

fn first_word(s: &String) -> &str {

Более опытный растацеан написал бы сигнатуру из листинга 4-9: с ней одна и та же функция работает и со значениями &String, и со значениями &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` принимает срезы `String` — как части, так и целой строки.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` принимает и ссылки на `String` — они равнозначны
    // срезам всей `String`.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` принимает срезы строковых литералов — как части,
    // так и целого литерала.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Строковые литералы *уже* являются срезами строк,
    // поэтому сработает и так, без синтаксиса срезов!
    let word = first_word(my_string_literal);
}

Если у нас есть строковый срез, его можно передать напрямую. Если есть String, можно передать срез этой String или ссылку на неё. Такая гибкость возможна благодаря неявному разыменованию (deref coercion) — мы разберём его в разделе «Неявное разыменование в функциях и методах» главы 15.

Если функция принимает строковый срез, а не ссылку на String, её API становится универсальнее и полезнее, а возможностей мы при этом не теряем:

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` принимает срезы `String` — как части, так и целой строки.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` принимает и ссылки на `String` — они равнозначны
    // срезам всей `String`.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` принимает срезы строковых литералов — как части,
    // так и целого литерала.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Строковые литералы *уже* являются срезами строк,
    // поэтому сработает и так, без синтаксиса срезов!
    let word = first_word(my_string_literal);
}

Другие срезы

Строковые срезы, как нетрудно догадаться, бывают только у строк. Но есть и более общий вид среза. Возьмём массив:

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

Точно так же, как может понадобиться сослаться на часть строки, может понадобиться сослаться на часть массива. Делается это так:

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

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

Тип этого среза — &[i32]. Работает он так же, как строковый срез: хранит ссылку на первый элемент и длину. Такие срезы вы будете использовать с самыми разными коллекциями. Подробно о коллекциях мы поговорим, когда дойдём до векторов в главе 8.

Итоги

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

Владение влияет на то, как работают многие другие части Rust, поэтому мы ещё не раз вернёмся к этим понятиям на протяжении книги. А теперь перейдём к главе 5 и посмотрим, как объединять данные в структуры (struct).

Структуры для связанных данных

Структура (struct) — это пользовательский тип данных, который позволяет собрать вместе и назвать несколько связанных значений, образующих осмысленную группу. Если вы знакомы с объектно-ориентированными языками, структура похожа на набор полей (атрибутов данных) объекта. В этой главе мы сравним структуры с кортежами, чтобы опереться на то, что вы уже знаете, и показать, когда структуры лучше подходят для группировки данных.

Мы покажем, как определять структуры и создавать их экземпляры. Поговорим о том, как определять ассоциированные функции, и особенно об их разновидности — методах, которые задают поведение, связанное с типом структуры. Структуры и перечисления (о них — в главе 6) — это строительные блоки для создания новых типов из предметной области вашей программы. С ними вы сможете в полной мере пользоваться проверкой типов, которую Rust выполняет при компиляции.

Определение и создание структур

Определение и создание структур

Структуры похожи на кортежи, о которых шла речь в разделе «Кортежи»: и те и другие хранят несколько связанных значений. Как и в кортеже, части структуры могут быть разных типов. Но, в отличие от кортежа, в структуре у каждой части данных есть имя, поэтому сразу понятно, что означает каждое значение. Благодаря именам структуры гибче кортежей: чтобы задать или прочитать значение экземпляра, не нужно помнить порядок данных.

Чтобы определить структуру, пишем ключевое слово struct и даём имя всей структуре. Имя должно отражать смысл данных, которые в ней сгруппированы. Затем в фигурных скобках перечисляем имена и типы частей данных — они называются полями (fields). Например, в листинге 5-1 показана структура, которая хранит сведения об учётной записи пользователя.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

Чтобы пользоваться определённой структурой, нужно создать её экземпляр (instance), указав конкретные значения всех полей. Для этого пишем имя структуры, а за ним — фигурные скобки с парами ключ: значение, где ключ — имя поля, а значение — данные, которые мы хотим в нём хранить. Порядок полей не обязан совпадать с порядком в объявлении структуры. Иначе говоря, определение структуры — это общий шаблон типа, а экземпляры заполняют шаблон конкретными данными и так создают значения этого типа. Например, конкретного пользователя можно объявить так, как в листинге 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,
    };
}

Чтобы получить конкретное значение из структуры, используется точечная нотация. Например, адрес электронной почты этого пользователя — это user1.email. Если экземпляр изменяемый, значение можно поменять, обратившись к полю через точку и присвоив ему новое значение. В листинге 5-3 показано, как изменить поле email у изменяемого экземпляра 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");
}

Обратите внимание: изменяемым должен быть весь экземпляр целиком — пометить изменяемыми только отдельные поля Rust не позволяет. Как и любое другое выражение, новый экземпляр структуры можно создать последним выражением в теле функции — тогда функция неявно вернёт его.

В листинге 5-4 показана функция build_user, которая возвращает экземпляр User с переданными адресом почты и именем пользователя. Поле active получает значение true, а sign_in_count — 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"),
    );
}

Называть параметры функции так же, как поля структуры, вполне логично, но повторять email и username дважды — и как имена полей, и как имена переменных — немного утомительно. А будь у структуры больше полей, это раздражало бы ещё сильнее. К счастью, есть удобное сокращение!

Сокращённая инициализация полей

В листинге 5-4 имена параметров и имена полей структуры полностью совпадают. Поэтому build_user можно переписать с помощью сокращённой инициализации полей (field init shorthand): функция будет вести себя точно так же, но без повторения username и email, как в листинге 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"),
    );
}

Здесь мы создаём новый экземпляр структуры User, у которой есть поле email. В это поле мы хотим записать значение параметра email функции build_user. Раз поле и параметр называются одинаково, достаточно написать email вместо email: email.

Создание экземпляров с синтаксисом обновления

Часто бывает нужно создать новый экземпляр структуры, взяв большую часть значений из другого экземпляра того же типа и поменяв лишь некоторые. Для этого есть синтаксис обновления структуры (struct update syntax).

Сначала в листинге 5-6 покажем, как создать новый экземпляр User в user2 обычным способом, без синтаксиса обновления. Мы задаём новое значение email, а остальные значения берём из user1, созданного в листинге 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --пропуск--

    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,
    };
}

С синтаксисом обновления того же можно добиться меньшим количеством кода, как в листинге 5-7. Запись .. означает, что все остальные поля, которые не заданы явно, получат те же значения, что и в указанном экземпляре.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --пропуск--

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

Код в листинге 5-7 тоже создаёт экземпляр user2 с другим значением email, но с теми же значениями полей username, active и sign_in_count, что и у user1. ..user1 должно стоять последним: оно говорит, что все оставшиеся поля берут значения из соответствующих полей user1. При этом явно задать можно сколько угодно полей и в любом порядке, независимо от порядка полей в определении структуры.

Обратите внимание: синтаксис обновления работает как присваивание через =, то есть перемещает данные (см. раздел «Переменные и данные: перемещение»). Что из этого следует в нашем примере:

• Поле username — это String, и её значение переместилось из user1 в user2. Поэтому user1 целиком использовать больше нельзя.
• Поле email мы задали для user2 заново, так что user1.email никуда не перемещалось — к нему по-прежнему можно обращаться.
• Поля active и sign_in_count имеют типы, реализующие трейт Copy, поэтому они не перемещаются, а копируются (см. раздел «Данные только на стеке: копирование»).

Если бы мы задали для user2 новые String и в email, и в username, а из user1 взяли бы только active и sign_in_count, то user1 осталась бы полностью действительной и после создания user2.

Кортежные структуры: разные типы из похожих кортежей

Rust поддерживает и структуры, похожие на кортежи, — кортежные структуры (tuple structs). У кортежной структуры есть имя, которое придаёт ей смысл, но у её полей имён нет — только типы. Кортежные структуры удобны, когда нужно дать имя всему кортежу и сделать его отдельным типом, отличным от других кортежей, а давать имя каждому полю, как в обычной структуре, было бы многословно или излишне.

Чтобы определить кортежную структуру, напишите ключевое слово struct, имя структуры, а за ним — типы в кортеже. Например, вот определение и использование двух кортежных структур — Color и 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);
}

Обратите внимание: значения black и origin — разных типов, потому что это экземпляры разных кортежных структур. Каждая определённая вами структура — это отдельный тип, даже если типы полей у структур совпадают. Например, функция, принимающая параметр типа Color, не примет аргумент типа Point, хотя оба типа состоят из трёх значений i32. В остальном экземпляры кортежных структур ведут себя как кортежи: их можно разобрать на отдельные части и обращаться к отдельному значению через . и индекс. Но, в отличие от кортежей, при деструктуризации кортежной структуры нужно указывать её тип. Например, чтобы разложить значения точки origin по переменным x, y и z, мы бы написали let Point(x, y, z) = origin;.

Единичные структуры без полей

Можно определить и структуру вообще без полей! Такие структуры называют единичными (unit-like structs), потому что они ведут себя похоже на () — единичный тип, который мы упоминали в разделе «Кортежи». Единичные структуры пригодятся, когда нужно реализовать для какого-то типа трейт, но хранить в самом типе никаких данных не требуется. Трейты мы обсудим в главе 10. Вот пример объявления и создания экземпляра единичной структуры AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Чтобы определить AlwaysEqual, пишем ключевое слово struct, нужное имя и точку с запятой. Ни фигурных, ни круглых скобок не нужно! Экземпляр AlwaysEqual в переменной subject получаем так же просто — по имени, без всяких скобок. Представьте, что позже мы реализуем для этого типа поведение, при котором любой экземпляр AlwaysEqual всегда равен любому экземпляру любого другого типа, — например, чтобы получать заранее известный результат в тестах. Для такого поведения никакие данные не нужны! В главе 10 вы увидите, как определять трейты и реализовывать их для любых типов, в том числе для единичных структур.

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

Пример программы со структурами

Пример программы со структурами

Чтобы понять, когда пригодятся структуры, напишем программу, которая вычисляет площадь прямоугольника. Начнём с отдельных переменных, а потом будем переделывать программу, пока не придём к структурам.

Создадим через Cargo новый бинарный проект rectangles. Программа будет брать ширину и высоту прямоугольника в пикселях и вычислять его площадь. В листинге 5-8 короткая программа в 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
}

Запустим программу командой 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.

Код справляется с задачей: вызывает функцию area с обоими размерами и получает площадь. Но его можно сделать понятнее и читабельнее.

Проблема хорошо видна по сигнатуре 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
}

Функция area должна вычислять площадь одного прямоугольника, но параметров у неё два, и нигде в программе не сказано, что эти параметры связаны между собой. Было бы понятнее и удобнее держать ширину и высоту вместе. Один способ сделать это мы уже обсуждали в разделе «Кортежи» главы 3 — использовать кортеж.

Рефакторинг с кортежами

В листинге 5-9 — версия программы с кортежем.

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
}

С одной стороны, программа стала лучше. Кортеж добавляет немного структуры, и теперь мы передаём всего один аргумент. Но с другой стороны, эта версия менее понятна: у элементов кортежа нет имён, приходится обращаться к ним по индексам, и вычисление становится не таким очевидным.

Для площади неважно, где ширина, а где высота, — но если мы захотим нарисовать прямоугольник на экране, путаница станет ошибкой! Придётся держать в голове, что width — это элемент кортежа с индексом 0, а height — с индексом 1. Тому, кто будет пользоваться нашим кодом, разобраться в этом и запомнить будет ещё сложнее. Мы не выразили в коде смысл наших данных, и теперь в нём легче ошибиться.

Рефакторинг со структурами

Структуры позволяют придать данным смысл, снабдив их подписями. Кортеж можно превратить в структуру, у которой есть имя и у целого, и у частей, как в листинге 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
}

Здесь мы определили структуру Rectangle (прямоугольник). В фигурных скобках объявлены поля width и height, оба типа u32. Затем в main мы создали конкретный экземпляр Rectangle шириной 30 и высотой 50.

Теперь у функции area один параметр, rectangle, и его тип — неизменяемое заимствование экземпляра структуры Rectangle. Как мы говорили в главе 4, лучше позаимствовать структуру, чем забирать владение ею. Тогда main сохраняет владение и может дальше пользоваться rect1 — для этого мы и пишем & и в сигнатуре функции, и в месте её вызова.

Функция area обращается к полям width и height экземпляра Rectangle. (Заметьте: обращение к полям заимствованного экземпляра структуры не перемещает значения полей — поэтому структуры так часто и передают по ссылке.) Сигнатура area теперь говорит ровно то, что мы имеем в виду: вычислить площадь Rectangle по его полям width и height. Видно, что ширина и высота связаны друг с другом, а у значений понятные имена вместо индексов кортежа 0 и 1. Ясность только выиграла.

Добавляем возможности с помощью выводимых трейтов

Во время отладки было бы удобно вывести экземпляр Rectangle и увидеть значения всех его полей. В листинге 5-11 мы пробуем сделать это макросом println!, как в предыдущих главах. Но так не получится.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1}");
}

При компиляции получаем ошибку, главное в которой — вот это сообщение:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

Макрос println! умеет форматировать вывод по-разному. По умолчанию фигурные скобки говорят ему использовать форматирование Display — вывод для конечного пользователя. Примитивные типы, которые мы видели до сих пор, реализуют Display по умолчанию: показать пользователю 1 или любое другое примитивное значение можно, по сути, только одним способом. А вот со структурами неясно, как println! должен форматировать вывод: вариантов слишком много. Нужны ли запятые? Выводить ли фигурные скобки? Показывать ли все поля? Из-за этой неоднозначности Rust не пытается угадать, чего мы хотим, и у структур нет готовой реализации Display для println! и заполнителя {}.

Если читать ошибки дальше, найдётся полезная подсказка:

help: the trait `std::fmt::Display` is not implemented for `Rectangle`
  --> src/main.rs:1:1

Попробуем! Теперь вызов println! будет выглядеть так: println!("rect1 is {rect1:?}");. Спецификатор :? внутри фигурных скобок говорит println!, что нужен формат вывода Debug. Трейт Debug позволяет выводить структуру в виде, удобном для разработчика, — чтобы видеть её значение во время отладки.

Скомпилируйте код с этим изменением. Вот незадача! Ошибка всё равно есть:

error[E0277]: `Rectangle` doesn't implement `Debug`

Но компилятор снова даёт полезную подсказку:

   |                        required by this formatting parameter
   |

Возможность выводить отладочную информацию в Rust есть, но для своей структуры её нужно явно включить. Для этого прямо перед определением структуры добавляем внешний атрибут #[derive(Debug)], как в листинге 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

Теперь программа запускается без ошибок, и мы видим:

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

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

$ 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,
}

Другой способ вывести значение в формате Debug — макрос dbg!. В отличие от println!, который принимает ссылку, dbg! забирает владение выражением. Он выводит имя файла и номер строки, где в коде стоит вызов dbg!, вместе со значением выражения, а потом возвращает владение этим значением обратно.

Вот пример, где нас интересует значение, которое присваивается полю width, и значение всей структуры в 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);
}

Мы оборачиваем в dbg! выражение 30 * scale. Поскольку dbg! возвращает владение значением выражения, поле width получит то же значение, что и без dbg!. А вот владение rect1 отдавать dbg! мы не хотим, поэтому в следующем вызове передаём ссылку на rect1. Вывод примера выглядит так:

$ 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,
}

Первая часть вывода пришла из строки 10 файла src/main.rs, где мы отлаживаем выражение 30 * scale; его значение — 60 (форматирование Debug для целых чисел выводит просто их значение). Вызов dbg! в строке 14 файла src/main.rs выводит значение &rect1, то есть структуру Rectangle, — в «красивом» формате Debug для типа Rectangle. Макрос dbg! очень выручает, когда пытаешься понять, что на самом деле делает твой код!

Кроме Debug, Rust предоставляет ещё ряд трейтов, которые можно использовать с атрибутом derive, чтобы добавить своим типам полезное поведение. Эти трейты и их поведение перечислены в приложении C. Как реализовывать такие трейты со своим поведением и как создавать собственные трейты, мы разберём в главе 10. Есть и много других атрибутов, помимо derive; подробнее — в разделе «Attributes» справочника Rust.

Наша функция area очень узкоспециализированная: она умеет считать только площадь прямоугольника. Раз ни с каким другим типом она работать не будет, было бы полезно теснее связать это поведение со структурой Rectangle. Посмотрим, как продолжить рефакторинг и превратить функцию area в метод area, определённый для типа Rectangle.

Методы

Методы

Методы похожи на функции: они объявляются ключевым словом fn и именем, у них могут быть параметры и возвращаемое значение, и в них есть код, который выполняется, когда метод вызывают. Но, в отличие от функций, методы определяются в контексте структуры (или перечисления, или трейт-объекта — о них мы поговорим в главе 6 и главе 18 соответственно), а их первый параметр — всегда self: это экземпляр структуры, у которого вызван метод.

Синтаксис методов

Превратим функцию area, которая принимает экземпляр Rectangle параметром, в метод area, определённый для структуры Rectangle, как в листинге 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()
    );
}

Чтобы определить функцию в контексте Rectangle, открываем для Rectangle блок impl (от implementation — реализация). Всё, что внутри этого блока, будет связано с типом Rectangle. Затем переносим функцию area в фигурные скобки impl и меняем первый (а здесь и единственный) параметр на self — и в сигнатуре, и везде в теле. В main, где мы вызывали функцию area и передавали ей rect1, теперь можно воспользоваться синтаксисом методов и вызвать метод area у экземпляра Rectangle. Вызов метода пишется после экземпляра: точка, имя метода, круглые скобки и аргументы, если они есть.

В сигнатуре area мы пишем &self вместо rectangle: &Rectangle. На самом деле &self — это сокращение от self: &Self. Внутри блока impl тип Self — это псевдоним того типа, для которого написан блок impl. Первым параметром у метода обязательно должен быть параметр с именем self типа Self, поэтому Rust разрешает на месте первого параметра писать просто self. Обратите внимание: перед self всё равно нужен &, чтобы показать, что метод заимствует экземпляр Self, — так же, как мы писали rectangle: &Rectangle. С self, как и с любым другим параметром, метод может поступить по-разному: забрать во владение, позаимствовать неизменяемо (как здесь) или позаимствовать изменяемо.

&self мы выбрали по той же причине, по которой в версии с функцией писали &Rectangle: владение нам не нужно, мы хотим только читать данные структуры, а не менять их. Если бы метод должен был менять экземпляр, у которого его вызвали, первым параметром был бы &mut self. Методы, которые забирают владение экземпляром, принимая первым параметром просто self, встречаются редко. Обычно так делают, когда метод превращает self во что-то другое и нужно, чтобы после этого превращения вызывающий код больше не мог пользоваться исходным экземпляром.

Помимо удобного синтаксиса вызова и того, что не нужно повторять тип self в сигнатуре каждого метода, главная причина использовать методы вместо функций — организация кода. Всё, что можно делать с экземпляром типа, собрано в одном блоке impl. Будущим пользователям нашего кода не придётся искать возможности Rectangle по разным местам библиотеки.

Методу можно дать то же имя, что и одному из полей структуры. Например, определим для Rectangle метод, который тоже называется 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);
    }
}

Здесь метод width возвращает true, если значение в поле width экземпляра больше 0, и false, если оно равно 0: внутри метода с тем же именем поле можно использовать для чего угодно. Когда в main после rect1.width стоят круглые скобки, Rust понимает, что имеется в виду метод width. Без скобок — что поле width.

Часто (хотя и не всегда) метод с тем же именем, что и поле, просто возвращает значение этого поля и больше ничего не делает. Такие методы называются геттерами (getters), и Rust, в отличие от некоторых других языков, не создаёт их для полей структуры автоматически. Геттеры полезны тем, что поле можно сделать приватным, а метод — публичным и таким образом дать в публичном API типа доступ к полю только на чтение. Что такое публичность и приватность и как сделать поле или метод публичным или приватным, мы обсудим в главе 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);
}

Методы с несколькими параметрами

Потренируемся и напишем для структуры Rectangle второй метод. Он будет принимать другой экземпляр Rectangle и возвращать true, если этот второй прямоугольник целиком помещается внутри self (первого прямоугольника), а иначе — false. То есть, определив метод can_hold («может вместить»), мы хотим иметь возможность написать программу из листинга 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));
}

Ожидаемый вывод будет таким: оба размера rect2 меньше размеров rect1, а вот rect3 шире, чем rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Раз мы определяем метод, он будет в блоке impl Rectangle. Назовём его can_hold; параметром он примет неизменяемое заимствование другого Rectangle. Каким должен быть тип параметра, видно из вызывающего кода: rect1.can_hold(&rect2) передаёт &rect2 — неизменяемое заимствование экземпляра Rectangle. Это логично: rect2 нам нужно только читать (а не менять — тогда понадобилось бы изменяемое заимствование), и мы хотим, чтобы main сохранила владение rect2 и могла пользоваться им после вызова can_hold. Метод can_hold возвращает логическое значение, а внутри проверяет, больше ли ширина и высота self соответственно ширины и высоты другого Rectangle. Добавим новый метод can_hold в блок impl из листинга 5-13 — см. листинг 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));
}

Если запустить этот код с функцией main из листинга 5-14, получим нужный вывод. Методы могут принимать несколько параметров — они добавляются в сигнатуру после self и работают точно так же, как параметры функций.

Ассоциированные функции

Все функции, определённые в блоке impl, называются ассоциированными функциями (associated functions), потому что они связаны с типом, указанным после impl. Можно определять ассоциированные функции, у которых первый параметр — не self (а значит, это не методы): им для работы не нужен экземпляр типа. Одной такой функцией мы уже пользовались — это String::from, определённая для типа String.

Ассоциированные функции, которые не являются методами, часто служат конструкторами — возвращают новый экземпляр структуры. Их часто называют new, но new — не какое-то особое имя и не встроено в язык. Например, можно сделать ассоциированную функцию square («квадрат») с одним параметром — размером стороны, который будет и шириной, и высотой. Так проще создать квадратный Rectangle, не указывая одно и то же значение дважды:

Файл: 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);
}

Ключевое слово Self в возвращаемом типе и в теле функции — псевдоним типа, указанного после impl, то есть в данном случае Rectangle.

Чтобы вызвать такую ассоциированную функцию, пишем имя структуры и ::, например: let sq = Rectangle::square(3);. Функция находится в пространстве имён структуры: синтаксис :: используется и для ассоциированных функций, и для пространств имён, которые создают модули. О модулях мы поговорим в главе 7.

Несколько блоков impl

У одной структуры может быть несколько блоков impl. Например, листинг 5-15 равнозначен коду из листинга 5-16, где каждый метод находится в отдельном блоке 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));
}

Здесь разносить методы по разным блокам impl незачем, но синтаксис это допускает. Случай, когда несколько блоков impl действительно полезны, мы увидим в главе 10, где пойдёт речь об обобщённых типах и трейтах.

Итоги

Структуры позволяют создавать собственные типы, которые имеют смысл в вашей предметной области. Со структурами связанные между собой данные остаются вместе, а у каждой части есть имя, и код становится понятнее. В блоках impl можно определять функции, связанные с вашим типом, а методы — это разновидность ассоциированных функций, которая задаёт поведение экземпляров ваших структур.

Но структуры — не единственный способ создавать собственные типы. Перейдём к перечислениям Rust и добавим в ваш арсенал ещё один инструмент.

Перечисления и сопоставление с образцом

В этой главе мы рассмотрим перечисления (enumerations, или коротко enums). Перечисление позволяет определить тип, перечислив все его возможные варианты. Сначала мы определим и используем перечисление, чтобы показать, как оно может хранить смысл вместе с данными. Затем разберём особенно полезное перечисление — Option, которое выражает, что значение либо есть, либо его нет. Потом посмотрим, как сопоставление с образцом в выражении match позволяет легко выполнять разный код для разных вариантов перечисления. И наконец, познакомимся с конструкцией if let — ещё одной удобной и лаконичной идиомой для работы с перечислениями.

Определение перечисления

Определение перечисления

Структуры позволяют сгруппировать связанные поля и данные — как Rectangle со своими width и height. А перечисления позволяют сказать, что значение — одно из заранее известного набора. Например, мы можем захотеть сказать, что Rectangle — одна из возможных фигур, наряду с Circle (кругом) и Triangle (треугольником). Для этого Rust позволяет описать все варианты в виде перечисления.

Рассмотрим ситуацию, которую нужно выразить в коде, и посмотрим, почему здесь перечисления полезнее и уместнее структур. Допустим, нам нужно работать с IP-адресами. Сейчас используются два основных стандарта IP-адресов: четвёртая и шестая версии. Других вариантов наша программа не встретит, поэтому все возможные варианты можно перечислить — отсюда и название «перечисление».

Любой IP-адрес — либо четвёртой версии, либо шестой, но не обоих сразу. Это свойство IP-адресов как раз и делает перечисление подходящей структурой данных: значение перечисления может быть только одним из его вариантов. При этом адреса и четвёртой, и шестой версии — по сути всё равно IP-адреса, поэтому в коде, который работает с любыми IP-адресами, их нужно считать одним типом.

Выразим это в коде: определим перечисление IpAddrKind и перечислим, какими могут быть IP-адреса, — V4 и V6. Это и есть варианты перечисления:

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 — пользовательский тип данных, которым можно пользоваться в других местах кода.

Значения перечисления

Экземпляры обоих вариантов 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) {}

Обратите внимание: варианты находятся в пространстве имён перечисления, поэтому вариант записывается через двойное двоеточие после имени перечисления. Это удобно: теперь оба значения, IpAddrKind::V4 и IpAddrKind::V6, имеют один и тот же тип — IpAddrKind. Значит, можно, например, определить функцию, которая принимает любой 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) {}

И вызывать её с любым из вариантов:

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) {}

Но у перечислений есть и другие преимущества. Подумаем ещё о нашем типе для IP-адресов: сейчас у нас нет способа хранить сами данные адреса — мы знаем только его вид. Вы только что изучили структуры в главе 5, и, возможно, вам захочется решить задачу с их помощью, как в листинге 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"),
    };
}

Здесь мы определили структуру IpAddr с двумя полями: kind типа IpAddrKind (перечисление, определённое выше) и address типа String. У нас два экземпляра этой структуры. Первый — home: у него kind равно IpAddrKind::V4, а адрес — 127.0.0.1. Второй — loopback: у него kind — другой вариант IpAddrKind, V6, а адрес — ::1. Мы использовали структуру, чтобы связать kind и address вместе, так что теперь вариант привязан к значению.

Однако то же самое можно выразить короче — одним только перечислением. Вместо перечисления внутри структуры можно положить данные прямо в каждый вариант перечисления. Новое определение перечисления IpAddr говорит, что у обоих вариантов, V4 и V6, есть связанное значение String:

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

Мы прикрепляем данные прямо к каждому варианту перечисления, так что дополнительная структура не нужна. Здесь заодно легче увидеть ещё одну деталь работы перечислений: имя каждого варианта, который мы определяем, становится также функцией, создающей экземпляр перечисления. То есть IpAddr::V4() — это вызов функции, которая принимает аргумент String и возвращает экземпляр типа IpAddr. Эту функцию-конструктор мы получаем автоматически, просто определив перечисление.

Есть у перечисления перед структурой и ещё одно преимущество: у каждого варианта могут быть данные разных типов и в разном количестве. В адресе четвёртой версии всегда четыре числа от 0 до 255. Если бы мы захотели хранить адреса V4 как четыре значения u8, а адреса V6 — по-прежнему как одно значение String, со структурой так бы не получилось. А перечисление справляется с этим легко:

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

Мы показали несколько разных способов описать структуры данных для хранения IP-адресов четвёртой и шестой версий. Но, как оказалось, хранить IP-адреса вместе с их видом нужно настолько часто, что в стандартной библиотеке уже есть готовое определение! Посмотрим, как стандартная библиотека определяет IpAddr. Там ровно такое же перечисление с такими же вариантами, но данные адреса хранятся внутри вариантов в виде двух разных структур, по-своему устроенных для каждого варианта:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

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

Заметьте: хотя в стандартной библиотеке есть определение IpAddr, мы всё равно можем создавать и использовать собственное, и конфликта не будет — ведь определение из стандартной библиотеки мы не подключали в свою область видимости. Подробнее о подключении типов в область видимости мы поговорим в главе 7.

Рассмотрим ещё один пример перечисления — в листинге 6-2. В его вариантах хранятся самые разные типы.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

У этого перечисления четыре варианта с разными типами:

• Quit — никаких связанных данных нет вообще;
• Move — именованные поля, как у структуры;
• Write — одна String;
• ChangeColor — три значения i32.

Определить перечисление с вариантами, как в листинге 6-2, — почти то же, что определить несколько разных структур. Разница в том, что у перечисления нет ключевого слова struct и все варианты собраны вместе под типом Message. Те же данные, что хранят варианты перечисления, можно было бы хранить в таких структурах:

struct QuitMessage; // единичная структура
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // кортежная структура
struct ChangeColorMessage(i32, i32, i32); // кортежная структура

fn main() {}

Но у каждой из этих структур был бы свой тип, и написать функцию, которая принимает любое такое сообщение, было бы не так просто, как с перечислением Message из листинга 6-2 — ведь это один тип.

Есть у перечислений и структур ещё одно сходство: точно так же, как для структур определяют методы через impl, их можно определять и для перечислений. Вот метод call, который можно определить для нашего перечисления Message:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // здесь было бы тело метода
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

В теле метода self даёт доступ к значению, у которого метод вызван. В этом примере мы создали переменную m со значением Message::Write(String::from("hello")) — именно оно и будет self в теле метода call, когда выполнится m.call().

Теперь посмотрим на другое перечисление из стандартной библиотеки — очень распространённое и полезное: Option.

Перечисление Option

В этом разделе мы подробно разберём Option — ещё одно перечисление из стандартной библиотеки. Тип Option описывает очень частую ситуацию: значение может быть, а может и не быть.

Например, если попросить первый элемент непустого списка, вы получите значение. А если попросить первый элемент пустого списка — ничего не получите. Если выразить это через систему типов, компилятор сможет проверить, что вы обработали все нужные случаи. Это предотвращает ошибки, которые крайне часто встречаются в других языках программирования.

О дизайне языка программирования обычно судят по тому, какие возможности в нём есть, но не менее важно, каких в нём нет. В Rust нет значения null, которое есть во многих других языках. Null — это значение, которое означает, что значения нет. В языках с null переменная всегда находится в одном из двух состояний: null или не null.

В своём выступлении 2009 года «Null References: The Billion Dollar Mistake» («Нулевые ссылки: ошибка на миллиард долларов») изобретатель null Тони Хоар сказал:

Я называю это своей ошибкой на миллиард долларов. Тогда я проектировал первую полноценную систему типов для ссылок в объектно-ориентированном языке. Моей целью было сделать любое использование ссылок абсолютно безопасным, чтобы проверки автоматически выполнял компилятор. Но я не смог устоять перед соблазном добавить нулевую ссылку — просто потому, что её было так легко реализовать. Это привело к бесчисленным ошибкам, уязвимостям и сбоям систем, которые за последние сорок лет, вероятно, принесли боли и ущерба на миллиард долларов.

Проблема с null в том, что если попытаться использовать null как обычное значение, получится какая-нибудь ошибка. А поскольку любое значение может оказаться null или не null, ошибиться таким образом очень легко.

При этом сама идея, которую пытается выразить null, полезна: null — это значение, которое по какой-то причине сейчас недействительно или отсутствует.

Проблема не в самой идее, а в конкретной реализации. Поэтому в Rust нет null, зато есть перечисление, которое выражает, что значение есть или его нет. Это перечисление называется Option<T>, и в стандартной библиотеке оно определено так:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Перечисление Option<T> настолько полезно, что входит в прелюдию: подключать его в область видимости явно не нужно. Его варианты тоже входят в прелюдию: Some и None можно использовать напрямую, без префикса Option::. При этом Option<T> — самое обычное перечисление, а Some(T) и None — его варианты типа Option<T>.

Синтаксис <T> — это возможность Rust, о которой мы ещё не говорили. Это обобщённый параметр типа, и подробно обобщения мы разберём в главе 10. Пока достаточно знать, что <T> означает: вариант Some перечисления Option может хранить одно значение любого типа, и каждый конкретный тип, подставленный вместо T, делает Option<T> отдельным типом. Вот несколько примеров значений Option, хранящих числа и символы:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

Тип some_number — Option<i32>. Тип some_char — Option<char>, и это уже другой тип. Rust может вывести эти типы, потому что внутри варианта Some мы указали значение. А вот для absent_number Rust требует указать тип Option целиком: по одному лишь значению None компилятор не может понять, что хранил бы соответствующий вариант Some. Здесь мы говорим Rust, что absent_number должна иметь тип Option<i32>.

Если у нас значение Some, мы знаем, что значение есть и лежит внутри Some. Если же у нас None, то в каком-то смысле это то же самое, что null: действительного значения нет. Так чем же Option<T> лучше null?

Коротко: Option<T> и T (где T — любой тип) — это разные типы, поэтому компилятор не даст использовать значение Option<T> так, будто в нём точно есть действительное значение. Например, этот код не скомпилируется — он пытается сложить i8 с Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

Если запустить этот код, получим примерно такое сообщение об ошибке:

$ 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>`
 --> /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/ops/arith.rs:98:8
  |
  = note: `i8` implements `Add`
 ::: /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/ops/arith.rs:113:0
  |
  = note: in this macro invocation
 --> /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/internal_macros.rs:22:8
  |
  = note: `&i8` implements `Add<i8>`
 ::: /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/internal_macros.rs:33:8
  |
  = note: `i8` implements `Add<&i8>`
 ::: /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/internal_macros.rs:44:8
  |
  = note: `&i8` implements `Add`
  = note: this error originates in the macro `add_impl` (in Nightly builds, run with -Z macro-backtrace for more info)

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

Сурово! По сути, сообщение говорит, что Rust не понимает, как сложить i8 и Option<i8>, потому что это разные типы. Когда у нас значение типа вроде i8, компилятор гарантирует, что значение всегда действительное. Можно спокойно им пользоваться, не проверяя перед этим на null. Беспокоиться о том, что значения может не быть, приходится, только когда у нас Option<i8> (или Option с другим нужным типом), — и компилятор проследит, чтобы мы обработали этот случай, прежде чем пользоваться значением.

Иначе говоря, прежде чем выполнять с Option<T> операции типа T, его нужно превратить в T. Как правило, это помогает поймать одну из самых частых проблем с null: когда предполагаешь, что что-то не null, а оно на самом деле null.

Когда исчезает риск ошибочно посчитать значение не-null, код становится надёжнее. Чтобы значение могло отсутствовать, нужно явно на это согласиться и сделать его тип Option<T>. А пользуясь таким значением, вы обязаны явно обработать случай, когда его нет. Везде, где у значения тип не Option<T>, можно смело считать, что оно не null. Это сознательное решение в дизайне Rust: ограничить распространение null и повысить безопасность кода.

Как же достать значение T из варианта Some, если у вас значение типа Option<T>? У перечисления Option<T> множество методов на все случаи жизни — посмотрите их в документации. Знакомство с методами Option<T> очень пригодится вам в работе с Rust.

В целом, чтобы использовать значение Option<T>, нужен код, который обработает каждый вариант. Какой-то код должен выполняться, только когда значение — Some(T), и этот код может пользоваться внутренним T. А другой код должен выполняться, только когда значение — None, и значения T у него нет. Выражение match — конструкция управления потоком, которая с перечислениями делает ровно это: выполняет разный код в зависимости от варианта перечисления, и этот код может пользоваться данными внутри совпавшего значения.

Конструкция match

Конструкция match

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

Выражение match можно представить как автомат для сортировки монет: монеты катятся по жёлобу с отверстиями разного размера, и каждая проваливается в первое же отверстие, в которое пролезает. Так же и значение в match по очереди проходит мимо образцов. Как только оно подходит под какой-то образец, выполняется код этой ветки.

Раз уж речь зашла о монетах, на них и разберём match! Напишем функцию, которая принимает неизвестную американскую монету и, подобно счётному автомату, определяет, что это за монета, и возвращает её достоинство в центах, как в листинге 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() {}

Разберём match в функции value_in_cents. Сначала идёт ключевое слово match, а за ним — выражение, в нашем случае значение coin. Похоже на условие в if, но есть большая разница: условие if должно давать логическое значение, а здесь может быть значение любого типа. Тип coin в этом примере — перечисление Coin, которое мы определили в первой строке.

Дальше идут ветки match. У ветки две части: образец и код. В первой ветке образец — значение Coin::Penny, а за ним оператор =>, который отделяет образец от кода. Код в данном случае — просто значение 1. Ветки отделяются друг от друга запятыми.

Когда выполняется выражение match, оно по порядку сравнивает значение с образцом каждой ветки. Если образец совпал, выполняется код этой ветки. Если нет, проверяется следующая ветка — совсем как в автомате для сортировки монет. Веток может быть сколько угодно: в листинге 6-3 их четыре.

Код каждой ветки — это выражение, и значение выражения в совпавшей ветке становится значением всего выражения match.

Если код в ветке короткий, фигурные скобки обычно не пишут — как в листинге 6-3, где каждая ветка просто возвращает значение. Если же в ветке нужно выполнить несколько строк кода, фигурные скобки обязательны, а запятая после такой ветки становится необязательной. Например, следующий код выводит «Lucky penny!» при каждом вызове с Coin::Penny, но всё равно возвращает последнее значение блока — 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() {}

Образцы, привязывающие значения

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

Для примера изменим один из вариантов перечисления, чтобы он хранил данные. С 1999 по 2008 год в США чеканили 25-центовые монеты (quarters), на одной стороне которых было изображение, своё для каждого из 50 штатов. Другим монетам такие изображения не достались, так что это дополнительное значение есть только у четвертаков. Добавим эту информацию в наше enum: пусть вариант Quarter хранит внутри значение UsState, как в листинге 6-4.

#[derive(Debug)] // чтобы чуть позже посмотреть на штат
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

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

В образец ветки для варианта Coin::Quarter мы добавляем переменную state. Когда совпадает Coin::Quarter, переменная state привязывается к штату этого четвертака. Теперь state можно использовать в коде ветки:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

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

Если вызвать value_in_cents(Coin::Quarter(UsState::Alaska)), то coin будет равно Coin::Quarter(UsState::Alaska). Сравнивая это значение с ветками, match не найдёт совпадений, пока не дойдёт до Coin::Quarter(state). Тут state привяжется к значению UsState::Alaska. Эту привязку можно использовать в println! — так мы и достаём штат из варианта Quarter перечисления Coin.

Сопоставление с Option<T>

В предыдущем разделе мы хотели достать внутреннее значение T из варианта Some у Option<T>. С Option<T> можно работать через match точно так же, как с перечислением Coin! Только сравнивать мы будем не монеты, а варианты Option<T>, — а работает выражение match всё так же.

Допустим, нужно написать функцию, которая принимает Option<i32> и, если внутри есть значение, прибавляет к нему 1. Если значения внутри нет, функция должна вернуть None и ничего не делать.

Благодаря match такую функцию написать очень просто — она будет выглядеть как в листинге 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);
}

Разберём подробнее первый вызов plus_one. Когда мы вызываем plus_one(five), переменная x в теле plus_one имеет значение Some(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);
}

Some(5) не совпадает с образцом None, так что переходим к следующей ветке:

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) с Some(i)? Да! Вариант тот же. i привязывается к значению внутри Some, то есть получает значение 5. Затем выполняется код ветки: прибавляем к i единицу и создаём новое значение Some, внутри которого лежит результат — 6.

Теперь второй вызов plus_one в листинге 6-5, где x равно None. Входим в 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);
}

Совпало! Прибавлять не к чему, поэтому match сразу возвращает None, стоящее справа от =>. Раз первая ветка совпала, остальные уже не проверяются.

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

match охватывает все варианты

Есть ещё один аспект match, который нужно обсудить: образцы веток должны покрывать все возможные случаи. Посмотрите на эту версию функции plus_one — в ней баг, и она не скомпилируется:

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

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

$ 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/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/option.rs:598:0
 ::: /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/option.rs:602:4
  |
  = 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 знает, что мы покрыли не все возможные случаи, и даже знает, какой именно образец мы забыли! Выражения match в Rust исчерпывающие (exhaustive): чтобы код был корректным, нужно перебрать все без исключения варианты. Особенно это важно для Option<T>: не давая забыть про явную обработку None, Rust защищает нас от предположения, что значение есть, когда его может не быть. Так та самая ошибка на миллиард долларов становится невозможной.

Образцы «для всего остального» и заполнитель _

С перечислениями можно делать что-то особенное для нескольких конкретных значений, а для всех остальных — одно действие по умолчанию. Представьте, что мы пишем игру: если на кубике выпало 3, игрок не ходит, а получает новую модную шляпу. Если выпало 7 — игрок модную шляпу теряет. При любом другом значении игрок перемещается по полю на столько клеток. Вот match, который реализует эту логику. Результат броска здесь вписан в код, а не случайный, а вся остальная логика представлена функциями без тела — их настоящая реализация выходит за рамки примера:

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) {}
}

В первых двух ветках образцы — литералы 3 и 7. В последней ветке, которая покрывает все остальные возможные значения, образец — переменная, которую мы назвали other. Код этой ветки использует переменную, передавая её в функцию move_player.

Этот код компилируется, хотя мы перечислили не все возможные значения u8: последний образец совпадает со всеми значениями, не перечисленными явно. Такой образец «для всего остального» (catch-all) удовлетворяет требованию исчерпывающей проверки. Заметьте, что ветку «для всего остального» нужно ставить последней: образцы проверяются по порядку. Если поставить её раньше, остальные ветки никогда не выполнятся, поэтому Rust предупредит, если после неё есть ещё ветки!

Есть в Rust и образец на случай, когда «всё остальное» нужно поймать, но использовать само значение не нужно: _ — особый образец, который совпадает с любым значением и не привязывает его к переменной. Так мы сообщаем Rust, что значение использовать не будем, и Rust не станет предупреждать о неиспользуемой переменной.

Изменим правила игры: теперь если выпало что-то кроме 3 или 7, нужно бросать ещё раз. Значение «всего остального» нам больше не нужно, поэтому вместо переменной 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() {}
}

Этот пример тоже удовлетворяет требованию исчерпывающей проверки: в последней ветке мы явно игнорируем все прочие значения — ничего не забыто.

И наконец, ещё раз поменяем правила: если выпало что-то кроме 3 или 7, в этот ход вообще ничего не происходит. Выразить это можно, указав в качестве кода ветки _ единичное значение (пустой кортеж, о котором мы говорили в разделе «Кортежи»):

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() {}
}

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

Об образцах и сопоставлении можно рассказать ещё много — мы займёмся этим в главе 19. А сейчас перейдём к синтаксису if let, который выручает там, где выражение match получается многословным.

Краткое управление потоком: if let и let...else

Краткое управление потоком: if let и let...else

Синтаксис if let объединяет if и let и позволяет короче записать обработку значений, которые совпадают с одним образцом, игнорируя все остальные. Посмотрите на программу из листинга 6-6: она сопоставляет значение Option<u8> из переменной config_max, но выполнять код хочет только тогда, когда значение — вариант Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

Если значение — Some, мы выводим лежащее в нём значение, привязав его в образце к переменной max. Со значением None мы ничего делать не хотим. Но чтобы удовлетворить match, после обработки единственного варианта приходится дописывать _ => () — раздражающий шаблонный код.

Вместо этого можно написать то же короче, с помощью if let. Следующий код ведёт себя точно так же, как match из листинга 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

if let принимает образец и выражение, разделённые знаком равенства. Работает это так же, как match, которому передали это выражение и у которого этот образец — первая ветка. Здесь образец — Some(max), и max привязывается к значению внутри Some. Дальше max можно использовать в теле блока if let точно так же, как в соответствующей ветке match. Код в блоке if let выполняется, только если значение совпало с образцом.

С if let меньше набирать, меньше отступов и шаблонного кода. Но вы теряете исчерпывающую проверку, которую обеспечивает match и которая гарантирует, что вы не забыли обработать какой-то случай. Что выбрать — match или if let, — зависит от конкретной ситуации: стоит ли краткость потери исчерпывающей проверки.

Иначе говоря, if let можно считать синтаксическим сахаром для match, который выполняет код, когда значение совпадает с одним образцом, и игнорирует все остальные значения.

К if let можно добавить else. Блок кода после else — то же самое, что код ветки _ в равнозначном выражении match. Вспомните определение перечисления Coin из листинга 6-4, где вариант Quarter хранил ещё и значение UsState. Если бы мы хотели посчитать все монеты, кроме четвертаков, и при этом называть штат на каждом четвертаке, это можно было бы сделать выражением match:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

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,
    }
}

А можно — выражением if let с else:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

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

Остаёмся на «счастливом пути» с let...else

Частая ситуация: если значение есть — выполнить с ним какие-то вычисления, а если нет — вернуть значение по умолчанию. Продолжим пример с монетами и UsState. Допустим, мы хотим сказать что-нибудь забавное в зависимости от того, насколько старый штат изображён на четвертаке. Для этого можно добавить к UsState метод, проверяющий возраст штата:

#[derive(Debug)] // чтобы чуть позже посмотреть на штат
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- пропуск --
        }
    }
}

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

Затем с помощью if let можно сопоставить тип монеты и получить переменную state в теле условия, как в листинге 6-7.

#[derive(Debug)] // чтобы чуть позже посмотреть на штат
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- пропуск --
        }
    }
}

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

Задачу это решает, но вся работа оказалась внутри тела if let. Если бы работа была сложнее, было бы трудно уследить, как связаны между собой ветки верхнего уровня. Можно воспользоваться тем, что выражения возвращают значение: либо получить state из if let, либо досрочно выйти из функции, как в листинге 6-8. (С match можно сделать нечто похожее.)

#[derive(Debug)] // чтобы чуть позже посмотреть на штат
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- пропуск --
        }
    }
}

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

Но и за этим по-своему неудобно следить! Одна ветка if let выдаёт значение, а другая вообще выходит из функции.

Чтобы такой частый случай записывался приятнее, в Rust есть let...else. Синтаксис let...else очень похож на if let: слева образец, справа выражение. Но ветки if у него нет — только ветка else. Если образец совпал, значение из образца привязывается к переменной во внешней области видимости. Если не совпал, выполнение переходит в ветку else, которая обязана выйти из функции.

В листинге 6-9 показано, как выглядит листинг 6-8, если вместо if let использовать let...else.

#[derive(Debug)] // чтобы чуть позже посмотреть на штат
enum UsState {
    Alabama,
    Alaska,
    // --пропуск--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- пропуск --
        }
    }
}

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

Обратите внимание: основной код функции остаётся на «счастливом пути» (happy path). В нём больше нет развилки, где одна ветка выдаёт значение, а другая выходит из функции, как было с if let.

Если логику программы слишком многословно выражать через match, помните, что в вашем арсенале есть ещё if let и let...else.

Итоги

Мы разобрали, как с помощью перечислений создавать собственные типы, значение которых — одно из заранее перечисленных. Мы показали, как тип Option<T> из стандартной библиотеки помогает с помощью системы типов предотвращать ошибки. Если внутри значений перечисления есть данные, достать и использовать их можно через match или if let — в зависимости от того, сколько случаев нужно обработать.

Теперь ваши программы на Rust могут выражать понятия предметной области с помощью структур и перечислений. Собственные типы в вашем API обеспечивают типобезопасность: компилятор проследит, чтобы каждая функция получала только значения того типа, который она ожидает.

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

Пакеты, крейты и модули

Чем больше программа, тем важнее становится организация кода. Если группировать связанную функциональность и разделять код с разными задачами, будет понятно, где искать код, реализующий нужную возможность, и куда идти, чтобы поменять её поведение.

Все программы, которые мы писали до сих пор, умещались в одном модуле в одном файле. Когда проект растёт, код стоит разбивать на несколько модулей, а затем и на несколько файлов. Пакет может содержать несколько бинарных крейтов и, при желании, один библиотечный крейт. По мере роста пакета его части можно выносить в отдельные крейты, которые становятся внешними зависимостями. Обо всех этих приёмах и пойдёт речь в этой главе. Для совсем больших проектов, состоящих из нескольких связанных пакетов, которые развиваются вместе, в Cargo есть рабочие пространства — о них мы поговорим в разделе «Рабочие пространства Cargo» главы 14.

Ещё мы обсудим инкапсуляцию деталей реализации, которая позволяет повторно использовать код на более высоком уровне: реализовав какую-то операцию, вы даёте другому коду вызывать её через публичный интерфейс, и этому коду не нужно знать, как она устроена внутри. То, как вы пишете код, определяет, какие его части публичны и доступны другому коду, а какие — приватные детали реализации, которые вы оставляете за собой право менять. Это ещё один способ уменьшить количество деталей, которые приходится держать в голове.

С этим связано понятие области видимости: у каждого вложенного контекста, в котором написан код, есть набор имён, которые в нём «видны». И программисту, и компилятору нужно понимать, на что указывает конкретное имя в конкретном месте кода — на переменную, функцию, структуру, перечисление, модуль, константу или что-то ещё — и что этот элемент означает. Области видимости можно создавать и решать, какие имена в них будут видны, а какие нет. Двух элементов с одинаковым именем в одной области видимости быть не может, но для разрешения конфликтов имён есть свои инструменты.

В Rust есть ряд возможностей для организации кода: что открыто наружу, что скрыто и какие имена видны в каждой области видимости программы. Вместе их иногда называют системой модулей (module system). В неё входят:

• Пакеты (packages) — возможность Cargo, которая позволяет собирать, тестировать и распространять крейты;
• Крейты (crates) — дерево модулей, из которого получается библиотека или исполняемый файл;
• Модули (modules) и use — позволяют управлять организацией, областью видимости и приватностью путей;
• Пути (paths) — способ назвать элемент, например структуру, функцию или модуль.

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

Пакеты и крейты

Пакеты и крейты

Первыми из частей системы модулей мы разберём пакеты и крейты.

Крейт (crate) — это минимальный объём кода, который компилятор Rust рассматривает за один раз. Даже если запустить не cargo, а rustc и передать ему один файл с исходным кодом (как мы делали ещё в разделе «Основы программы на Rust» главы 1), компилятор посчитает этот файл крейтом. Крейт может содержать модули, а модули могут быть определены в других файлах, которые компилируются вместе с крейтом, — это мы увидим в следующих разделах.

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

У библиотечных крейтов нет функции main, и они не компилируются в исполняемый файл. Вместо этого они содержат функциональность, которой можно пользоваться из разных проектов. Например, крейт rand, который мы использовали в главе 2, умеет генерировать случайные числа. Говоря «крейт», растацеаны чаще всего имеют в виду именно библиотечный крейт и используют слово «крейт» как синоним общепрограммистского понятия «библиотека».

Корень крейта (crate root) — это исходный файл, с которого компилятор Rust начинает работу и который образует корневой модуль крейта (подробно модули разберём в разделе «Модули: область видимости и приватность»).

Пакет (package) — это набор из одного или нескольких крейтов, реализующий некоторую функциональность. В пакете есть файл Cargo.toml, который описывает, как собирать эти крейты. Сам Cargo — тоже пакет: в нём есть бинарный крейт, то есть та утилита командной строки, которой вы собираете свой код. А ещё в пакете Cargo есть библиотечный крейт, от которого зависит бинарный. Другие проекты могут подключить библиотечный крейт Cargo и пользоваться той же логикой, что и утилита командной строки Cargo.

Бинарных крейтов в пакете может быть сколько угодно, а библиотечный — не больше одного. И хотя бы один крейт — библиотечный или бинарный — в пакете быть должен.

Посмотрим, что происходит при создании пакета. Введём команду 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

После cargo new my-project мы смотрим через ls, что создал Cargo. В папке my-project есть файл Cargo.toml — значит, у нас есть пакет. Есть и папка src с файлом main.rs. Откройте Cargo.toml в редакторе: про src/main.rs там ничего не сказано. Дело в том, что Cargo следует соглашению: src/main.rs — корень бинарного крейта с тем же именем, что и у пакета. Точно так же Cargo знает: если в папке пакета есть src/lib.rs, то в пакете есть библиотечный крейт с тем же именем, что и у пакета, а src/lib.rs — его корень. Файлы корней крейтов Cargo передаёт rustc, чтобы собрать библиотеку или бинарник.

У нас пакет, в котором есть только src/main.rs, — значит, в нём только один бинарный крейт с именем my-project. Если в пакете есть и src/main.rs, и src/lib.rs, то в нём два крейта — бинарный и библиотечный, оба с именем пакета. Чтобы в пакете было несколько бинарных крейтов, положите файлы в папку src/bin: каждый файл станет отдельным бинарным крейтом.

Модули: область видимости и приватность

Модули: область видимости и приватность

В этом разделе мы поговорим о модулях и других частях системы модулей: о путях, которые позволяют называть элементы; о ключевом слове use, которое подключает путь в область видимости; и о ключевом слове pub, которое делает элементы публичными. Ещё мы обсудим ключевое слово as, внешние пакеты и оператор * (glob).

Шпаргалка по модулям

Прежде чем углубляться в модули и пути, приведём краткую справку: как компилятор обрабатывает модули, пути и ключевые слова use и pub и как большинство разработчиков организуют код. На протяжении главы мы разберём каждое из этих правил на примерах, а сюда удобно возвращаться, чтобы освежить в памяти, как работают модули.

• Начало — корень крейта. Компилируя крейт, компилятор сначала ищет код в файле корня крейта (обычно это src/lib.rs для библиотечного крейта и src/main.rs для бинарного).
• Объявление модулей. В файле корня крейта можно объявлять новые модули. Допустим, вы объявили модуль «garden» (сад) строкой mod garden;. Компилятор будет искать код модуля в следующих местах:
  • прямо в этом файле, в фигурных скобках, которые стоят вместо точки с запятой после mod garden;
  • в файле src/garden.rs;
  • в файле src/garden/mod.rs.
• Объявление подмодулей. В любом файле, кроме корня крейта, можно объявлять подмодули. Например, в src/garden.rs можно объявить mod vegetables; (овощи). Компилятор будет искать код подмодуля в папке с именем родительского модуля, в следующих местах:
  • прямо в этом файле, сразу после mod vegetables, в фигурных скобках вместо точки с запятой;
  • в файле src/garden/vegetables.rs;
  • в файле src/garden/vegetables/mod.rs.
• Пути к коду в модулях. Когда модуль стал частью крейта, на его код можно ссылаться из любого места этого крейта (если позволяют правила приватности) — по пути к этому коду. Например, тип Asparagus (спаржа) из модуля овощей в саду будет доступен по пути crate::garden::vegetables::Asparagus.
• Приватное и публичное. По умолчанию код модуля скрыт от родительских модулей. Чтобы сделать модуль публичным, объявите его через pub mod вместо mod. Чтобы сделать публичными и элементы внутри публичного модуля, поставьте pub перед их объявлениями.
• Ключевое слово use. Внутри области видимости use создаёт ярлыки для элементов, чтобы не повторять длинные пути. В любой области видимости, где можно сослаться на crate::garden::vegetables::Asparagus, можно создать ярлык use crate::garden::vegetables::Asparagus; — и дальше в этой области видимости достаточно писать просто Asparagus.

Создадим бинарный крейт backyard (задний двор) и посмотрим на эти правила в деле. В папке крейта, которая тоже называется backyard, такие файлы и папки:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Корень крейта здесь — src/main.rs, и в нём вот что:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

Строка pub mod garden; говорит компилятору подключить код из src/garden.rs, а там вот что:

pub mod vegetables;

А pub mod vegetables; здесь означает, что подключается ещё и код из src/garden/vegetables.rs:

#[derive(Debug)]
pub struct Asparagus {}

А теперь разберём эти правила подробно и посмотрим на них в действии!

Группировка связанного кода в модули

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

Для примера напишем библиотечный крейт, моделирующий работу ресторана. Мы определим сигнатуры функций, но оставим их тела пустыми, чтобы сосредоточиться на организации кода, а не на реализации ресторана.

В ресторанном деле заведение делят на зал (front of house) и служебную часть (back of house). Зал — это место, где находятся посетители: администратор рассаживает гостей, официанты принимают заказы и оплату, бармены готовят напитки. Служебная часть — это кухня, где работают шеф-повар и повара, мойщики посуды наводят чистоту, а менеджеры занимаются административной работой.

Чтобы устроить крейт так же, разложим его функции по вложенным модулям. Создайте новую библиотеку restaurant командой cargo new restaurant --lib. Затем введите в src/lib.rs код из листинга 7-1 — он определяет несколько модулей и сигнатур функций. Это «зал».

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() {}
    }
}

Модуль определяется ключевым словом mod, за которым идёт имя модуля (здесь — front_of_house). Тело модуля пишется в фигурных скобках. Внутри модуля можно размещать другие модули — как здесь модули hosting (встреча гостей) и serving (обслуживание). Ещё в модулях могут быть определения других элементов: структур, перечислений, констант, трейтов и, как в листинге 7-1, функций.

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

Выше мы говорили, что src/main.rs и src/lib.rs называются корнями крейта. Название объясняется так: содержимое любого из этих двух файлов образует модуль с именем crate, который находится в корне структуры модулей крейта — так называемого дерева модулей (module tree).

В листинге 7-2 показано дерево модулей для структуры из листинга 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Дерево показывает, какие модули вложены в другие: например, hosting вложен в front_of_house. Видно и то, что некоторые модули — соседи (siblings), то есть определены в одном и том же модуле: hosting и serving — соседи внутри front_of_house. Если модуль A находится внутри модуля B, говорят, что модуль A — потомок (child) модуля B, а B — родитель (parent) модуля A. Обратите внимание: корнем всего дерева модулей служит неявный модуль с именем crate.

Дерево модулей может напомнить вам дерево папок в файловой системе — и это очень удачное сравнение! Как папки в файловой системе, модули служат для организации кода. И точно так же, как файлы в папках, модули нужно уметь находить.

Пути к элементам в дереве модулей

Пути к элементам в дереве модулей

Чтобы показать Rust, где в дереве модулей искать элемент, мы указываем путь — так же, как путь в файловой системе. Чтобы вызвать функцию, нужно знать путь к ней.

Путь бывает двух видов:

• Абсолютный путь — полный путь от корня крейта. Для кода из внешнего крейта абсолютный путь начинается с имени этого крейта, а для кода из текущего крейта — со слова crate.
• Относительный путь начинается от текущего модуля и использует self, super или имя элемента из текущего модуля.

И в абсолютном, и в относительном пути за началом следуют один или несколько идентификаторов, разделённых двойным двоеточием (::).

Вернёмся к листингу 7-1. Допустим, мы хотим вызвать функцию add_to_waitlist (добавить в список ожидания). Это то же самое, что спросить: какой путь у функции add_to_waitlist? В листинге 7-3 — листинг 7-1, из которого убраны некоторые модули и функции.

Мы покажем два способа вызвать add_to_waitlist из новой функции eat_at_restaurant («поесть в ресторане»), определённой в корне крейта. Оба пути правильные, но остаётся ещё одна проблема, из-за которой этот пример в таком виде не скомпилируется. Почему — объясним чуть позже.

Функция eat_at_restaurant — часть публичного API нашего библиотечного крейта, поэтому мы помечаем её ключевым словом pub. Подробнее о pub — в разделе «Открываем пути ключевым словом pub».

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}

В первый раз add_to_waitlist вызывается из eat_at_restaurant по абсолютному пути. Функция add_to_waitlist определена в том же крейте, что и eat_at_restaurant, поэтому абсолютный путь можно начать с ключевого слова crate. Дальше по очереди перечисляем все модули, пока не дойдём до add_to_waitlist. Представьте файловую систему с такой же структурой: чтобы запустить программу add_to_waitlist, мы бы указали путь /front_of_house/hosting/add_to_waitlist. Начать путь с crate, то есть от корня крейта, — всё равно что начать путь в терминале с /, то есть от корня файловой системы.

Во второй раз add_to_waitlist вызывается по относительному пути. Он начинается с front_of_house — имени модуля, определённого на том же уровне дерева модулей, что и eat_at_restaurant. В файловой системе это был бы путь front_of_house/hosting/add_to_waitlist. Если путь начинается с имени модуля, он относительный.

Какой путь выбрать — относительный или абсолютный, — зависит от проекта, а точнее от того, как вы скорее будете переносить код: определение элемента отдельно от кода, который этот элемент использует, или вместе с ним. Например, если перенести модуль front_of_house и функцию eat_at_restaurant в модуль customer_experience, придётся обновить абсолютный путь к add_to_waitlist, а относительный останется верным. А если перенести в модуль dining одну лишь функцию eat_at_restaurant, то абсолютный путь в вызове add_to_waitlist не изменится, а относительный придётся поправить. Мы обычно предпочитаем абсолютные пути: чаще всего определения и вызовы элементов переносят независимо друг от друга.

Попробуем скомпилировать листинг 7-3 и выясним, почему он пока не компилируется! Ошибки — в листинге 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

Сообщения говорят, что модуль hosting приватный. Иными словами, пути к модулю hosting и к функции add_to_waitlist у нас правильные, но Rust не даёт ими воспользоваться: у нас нет доступа к приватным частям. В Rust все элементы (функции, методы, структуры, перечисления, модули и константы) по умолчанию скрыты от родительских модулей. Чтобы сделать элемент вроде функции или структуры приватным, достаточно поместить его в модуль.

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

Rust сделал систему модулей такой, чтобы детали внутренней реализации по умолчанию были скрыты. Так вы знаете, какие части внутреннего кода можно менять, не ломая внешний код. Но Rust позволяет и открыть внутренние части дочерних модулей внешним модулям-предкам — для этого элемент делают публичным ключевым словом pub.

Открываем пути ключевым словом pub

Вернёмся к ошибке из листинга 7-4, которая сообщала, что модуль hosting приватный. Мы хотим, чтобы функция eat_at_restaurant в родительском модуле имела доступ к функции add_to_waitlist в дочернем, поэтому помечаем модуль hosting ключевым словом pub, как в листинге 7-5.

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- пропуск --
pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}

К сожалению, код из листинга 7-5 всё равно не компилируется — ошибки в листинге 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

Что произошло? pub перед mod hosting делает публичным сам модуль. Теперь, если у нас есть доступ к front_of_house, есть доступ и к hosting. Но содержимое hosting по-прежнему приватно: публичный модуль не делает публичным своё содержимое. pub у модуля лишь позволяет коду в модулях-предках ссылаться на сам модуль, но не обращаться к его внутреннему коду. Модули — это контейнеры, и от одного лишь публичного модуля толку мало: нужно пойти дальше и сделать публичными и какие-то элементы внутри него.

Ошибки в листинге 7-6 говорят, что приватна функция add_to_waitlist. Правила приватности распространяются не только на модули, но и на структуры, перечисления, функции и методы.

Сделаем публичной и функцию add_to_waitlist, добавив pub перед её определением, как в листинге 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- пропуск --
pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}

Теперь код компилируется! Чтобы понять, почему после добавления pub правила приватности позволяют использовать эти пути в eat_at_restaurant, разберём абсолютный и относительный пути.

Абсолютный путь начинается с crate — корня дерева модулей нашего крейта. Модуль front_of_house определён в корне крейта. Он не публичный, но функция eat_at_restaurant определена в том же модуле, что и front_of_house (то есть они соседи), поэтому из eat_at_restaurant на front_of_house ссылаться можно. Дальше идёт модуль hosting, помеченный pub. К родителю hosting доступ у нас есть, значит, есть доступ и к hosting. Наконец, функция add_to_waitlist помечена pub, а к её родительскому модулю доступ есть — значит, вызов работает!

С относительным путём логика та же, кроме первого шага: путь начинается не от корня крейта, а от front_of_house. Модуль front_of_house определён в том же модуле, что и eat_at_restaurant, поэтому относительный путь от модуля, в котором определена eat_at_restaurant, работает. А раз hosting и add_to_waitlist помечены pub, остальная часть пути тоже работает — и вызов корректен!

Если вы собираетесь поделиться своим библиотечным крейтом, чтобы другие проекты могли пользоваться вашим кодом, то публичный API — это ваш договор с пользователями крейта: он определяет, как они могут работать с вашим кодом. Вопросов о том, как менять публичный API так, чтобы людям было проще зависеть от вашего крейта, очень много, и они выходят за рамки этой книги. Если тема вам интересна, загляните в Rust API Guidelines (рекомендации по проектированию API на Rust).

Относительные пути, начинающиеся с super

Относительный путь можно начать не от текущего модуля и не от корня крейта, а от родительского модуля — для этого в начале пути пишут super. Это как начать путь в файловой системе с .., что означает «перейти в родительскую папку». super позволяет сослаться на элемент, который точно находится в родительском модуле. Это упрощает перестройку дерева модулей, если модуль тесно связан с родителем, но родителя когда-нибудь могут перенести в другое место дерева.

Посмотрите на код в листинге 7-8. Он моделирует ситуацию, когда шеф-повар исправляет ошибочный заказ и сам выносит его посетителю. Функция fix_incorrect_order (исправить ошибочный заказ), определённая в модуле back_of_house, вызывает функцию deliver_order (подать заказ) из родительского модуля, указывая путь к deliver_order, который начинается с super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

Функция fix_incorrect_order находится в модуле back_of_house, поэтому с помощью super можно перейти в родительский модуль back_of_house — в данном случае это корень, crate. Там мы ищем deliver_order — и находим. Успех! Мы считаем, что модуль back_of_house и функция deliver_order, скорее всего, так и останутся в тех же отношениях друг с другом и при перестройке дерева модулей крейта будут переноситься вместе. Поэтому мы и использовали super: если этот код когда-нибудь переедет в другой модуль, править придётся меньше мест.

Публичные структуры и перечисления

С помощью pub можно сделать публичными и структуры с перечислениями, но тут есть несколько тонкостей. Если поставить pub перед определением структуры, публичной станет сама структура, но её поля останутся приватными. Каждое поле можно сделать публичным или нет по отдельности. В листинге 7-9 определена публичная структура back_of_house::Breakfast (завтрак) с публичным полем toast (тост) и приватным полем seasonal_fruit (сезонные фрукты). Это моделирует ситуацию в ресторане, когда посетитель может выбрать хлеб к блюду, а вот какие фрукты к нему подать, решает шеф-повар — в зависимости от сезона и того, что есть на складе. Набор фруктов быстро меняется, поэтому посетители не могут ни выбрать фрукты, ни даже увидеть, какие им достанутся.

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() {
    // Заказываем летний завтрак с ржаным тостом.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Передумали насчёт хлеба.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // Если раскомментировать следующую строку, код не скомпилируется: нам нельзя
    // ни узнать, ни поменять сезонный фрукт, который подают к завтраку.
    // meal.seasonal_fruit = String::from("blueberries");
}

Поле toast в структуре back_of_house::Breakfast публичное, поэтому в eat_at_restaurant его можно читать и записывать через точку. А вот поле seasonal_fruit в eat_at_restaurant использовать нельзя — оно приватное. Попробуйте раскомментировать строку, которая меняет значение seasonal_fruit, и посмотрите, какая будет ошибка!

Заметьте также: раз у back_of_house::Breakfast есть приватное поле, структуре нужна публичная ассоциированная функция, которая создаёт экземпляр Breakfast (здесь она называется summer — «летний»). Без такой функции создать экземпляр Breakfast в eat_at_restaurant было бы невозможно: мы не смогли бы задать значение приватного поля seasonal_fruit.

С перечислениями всё наоборот: если сделать перечисление публичным, публичными становятся все его варианты. Достаточно поставить pub перед ключевым словом enum, как в листинге 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;
}

Перечисление Appetizer (закуска) публичное, поэтому в eat_at_restaurant можно использовать варианты Soup (суп) и Salad (салат).

От перечисления мало толку, если его варианты не публичны, и было бы утомительно каждый раз помечать pub все варианты. Поэтому варианты перечислений по умолчанию публичны. А вот структуры часто полезны и без публичных полей, поэтому для полей структур действует общее правило: всё приватно, если не помечено pub.

Остался ещё один случай с pub, который мы не разобрали, — он связан с последней частью системы модулей, ключевым словом use. Сначала разберём use само по себе, а потом покажем, как сочетать pub и use.

Подключение путей ключевым словом use

Подключение путей ключевым словом use

Выписывать полные пути при каждом вызове функции неудобно и однообразно. В листинге 7-7, какой бы путь к add_to_waitlist мы ни выбрали — абсолютный или относительный, — при каждом вызове приходилось указывать ещё и front_of_house с hosting. К счастью, это можно упростить: один раз создать ярлык для пути с помощью ключевого слова use, а дальше во всей области видимости пользоваться коротким именем.

В листинге 7-11 мы подключаем модуль crate::front_of_house::hosting в область видимости функции eat_at_restaurant, и теперь, чтобы вызвать add_to_waitlist в eat_at_restaurant, достаточно написать hosting::add_to_waitlist.

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

Добавить в область видимости use с путём — примерно то же, что создать символическую ссылку в файловой системе. После строки use crate::front_of_house::hosting в корне крейта имя hosting становится в этой области видимости допустимым — как будто модуль hosting определён прямо в корне крейта. Пути, подключённые через use, проходят проверку приватности, как и любые другие.

Учтите, что use создаёт ярлык только в той области видимости, где он написан. В листинге 7-12 функция eat_at_restaurant перенесена в новый дочерний модуль customer. Это уже другая область видимости, не та, где стоит use, поэтому тело функции не скомпилируется.

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

Ошибка компиляции показывает, что внутри модуля customer ярлык уже не действует:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: cannot find module or crate `hosting` in this scope
  --> 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)]` (part of `#[warn(unused)]`) 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

Заметьте, что есть ещё и предупреждение: use в своей области видимости больше не используется! Чтобы исправить проблему, перенесите use тоже в модуль customer или обращайтесь к ярлыку родительского модуля через super::hosting внутри дочернего модуля customer.

Идиоматичные пути в use

Глядя на листинг 7-11, вы, возможно, задались вопросом: зачем мы написали use crate::front_of_house::hosting и вызываем hosting::add_to_waitlist в eat_at_restaurant, а не довели путь в use до самой функции add_to_waitlist, как в листинге 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();
}

Листинги 7-11 и 7-13 делают одно и то же, но идиоматичный способ подключить функцию через use — как в листинге 7-11. Если подключить родительский модуль функции, то при вызове придётся указывать этот модуль. А это сразу показывает, что функция определена не здесь, и при этом полный путь повторять не нужно. По коду из листинга 7-13 непонятно, где определена add_to_waitlist.

А вот структуры, перечисления и прочие элементы через use идиоматично подключать по полному пути. В листинге 7-14 показан идиоматичный способ подключить структуру HashMap из стандартной библиотеки в область видимости бинарного крейта.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

Серьёзной причины у этой идиомы нет: просто так сложилось, и люди привыкли читать и писать код на Rust именно так.

Исключение — когда нужно подключить через use два элемента с одинаковым именем: Rust такого не допускает. В листинге 7-15 показано, как подключить в область видимости два типа Result с одинаковым именем, но из разных родительских модулей, и как к ним обращаться.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --пропуск--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --пропуск--
    Ok(())
}

Как видите, родительские модули позволяют различить два типа Result. Если бы мы написали use std::fmt::Result и use std::io::Result, в одной области видимости оказались бы два типа Result, и Rust не понял бы, какой из них мы имеем в виду, когда пишем Result.

Новые имена с помощью as

Есть и другое решение проблемы двух одноимённых типов в одной области видимости: после пути можно написать as и новое локальное имя — псевдоним (alias) — для типа. В листинге 7-16 показан другой вариант кода из листинга 7-15: один из двух типов Result переименован с помощью as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --пропуск--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --пропуск--
    Ok(())
}

Во второй инструкции use мы дали типу std::io::Result новое имя — IoResult. Оно не конфликтует с Result из std::fmt, который мы тоже подключили. И листинг 7-15, и листинг 7-16 считаются идиоматичными, так что выбирайте сами!

Реэкспорт имён с помощью pub use

Когда мы подключаем имя через use, оно приватно для той области видимости, куда мы его импортировали. Чтобы код за пределами этой области мог обращаться к имени так, будто оно определено в ней, можно объединить pub и use. Такой приём называется реэкспортом (re-exporting): мы подключаем элемент в свою область видимости и одновременно делаем его доступным другим, чтобы они могли подключить его в свою.

В листинге 7-17 — код из листинга 7-11, где use в корневом модуле заменено на 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();
}

До этого изменения внешнему коду пришлось бы вызывать функцию add_to_waitlist по пути restaurant::front_of_house::hosting::add_to_waitlist(), да ещё и модуль front_of_house пришлось бы пометить pub. Теперь, когда pub use реэкспортировал модуль hosting из корневого модуля, внешний код может пользоваться путём restaurant::hosting::add_to_waitlist().

Реэкспорт полезен, когда внутренняя структура кода отличается от того, как видят предметную область программисты, вызывающие ваш код. Например, в нашей ресторанной метафоре те, кто управляет рестораном, думают категориями «зал» и «служебная часть». А посетители, скорее всего, о ресторане так не думают. С помощью pub use можно написать код с одной структурой, а наружу открыть другую. Так библиотека получается хорошо организованной и для тех, кто над ней работает, и для тех, кто её вызывает. Ещё один пример pub use и того, как он влияет на документацию крейта, мы рассмотрим в разделе «Экспорт удобного публичного API» главы 14.

Внешние пакеты

В главе 2 мы написали игру «Угадай число», в которой использовали внешний пакет rand для получения случайных чисел. Чтобы подключить rand к проекту, мы добавили в Cargo.toml строку:

rand = "0.10.1"

Добавив rand в зависимости в Cargo.toml, мы говорим Cargo скачать пакет rand и все его зависимости с crates.io и сделать rand доступным в нашем проекте.

Затем, чтобы подключить определения из rand в область видимости нашего пакета, мы добавили строку use, которая начинается с имени крейта, rand, и перечислили элементы, которые хотим подключить. Вспомните: в разделе «Генерируем случайное число» главы 2 мы подключили элементы из модуля rand::prelude и вызвали функцию rand::rng:

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

Участники сообщества Rust опубликовали на crates.io огромное количество пакетов, и подключить любой из них к своему пакету можно теми же шагами: указать его в Cargo.toml своего пакета и подключить нужные элементы из его крейтов через use.

Учтите, что стандартная библиотека std — тоже крейт, внешний по отношению к нашему пакету. Стандартная библиотека поставляется вместе с Rust, поэтому добавлять std в Cargo.toml не нужно. Но чтобы подключить из неё элементы в область видимости нашего пакета, нужно сослаться на неё через use. Например, для HashMap строка будет такой:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Это абсолютный путь, который начинается с std — имени крейта стандартной библиотеки.

Вложенные пути для аккуратных списков use

Если мы используем несколько элементов из одного крейта или модуля и пишем каждый на отдельной строке, это занимает много места по вертикали. Например, эти две инструкции use из игры в листинге 2-4 подключают элементы из std:

// --пропуск--
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.");

    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!"),
    }
}

Вместо этого можно подключить те же элементы одной строкой с помощью вложенных путей: пишем общую часть пути, два двоеточия, а затем в фигурных скобках — список различающихся частей, как в листинге 7-18.

use rand::prelude::*;
// --пропуск--
use std::{cmp::Ordering, io};
// --пропуск--

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

    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!"),
    }
}

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

Вложенный путь можно использовать на любом уровне пути. Это пригодится, когда нужно объединить две инструкции use с общей частью. Например, в листинге 7-19 две инструкции use: одна подключает std::io, другая — std::io::Write.

use std::io;
use std::io::Write;

Общая часть этих двух путей — std::io, и это целиком первый путь. Чтобы объединить их в одну инструкцию use, во вложенном пути можно использовать self, как в листинге 7-20.

use std::io::{self, Write};

Эта строка подключает и std::io, и std::io::Write.

Импорт всего подряд оператором *

Если нужно подключить все публичные элементы, определённые по какому-то пути, после пути ставят оператор * (glob):

#![allow(unused)]
fn main() {
use std::collections::*;
}

Эта инструкция use подключает в текущую область видимости все публичные элементы из std::collections. Будьте осторожны с этим оператором! С ним труднее понять, какие имена видны в области видимости и где определено имя, которое используется в программе. Кроме того, если в зависимости изменятся определения, изменится и то, что вы импортировали. Например, при обновлении зависимости могут появиться ошибки компиляции, если в ней добавится определение с тем же именем, что и ваше в той же области видимости.

Оператор * часто используют в тестах, чтобы подключить всё тестируемое в модуль tests, — об этом мы поговорим в разделе «Как писать тесты» главы 11. Ещё его иногда используют в шаблоне «прелюдии» — подробнее см. документацию стандартной библиотеки.

Разделение модулей на файлы

Разделение модулей на файлы

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

Возьмём для примера код из листинга 7-17 с несколькими модулями ресторана. Вынесем модули в отдельные файлы, чтобы не держать их все в файле корня крейта. Здесь корень крейта — src/lib.rs, но так же можно поступить и с бинарным крейтом, у которого корень — src/main.rs.

Сначала вынесем в отдельный файл модуль front_of_house. Удалите код внутри фигурных скобок модуля front_of_house, оставив только объявление mod front_of_house;, чтобы в src/lib.rs остался код из листинга 7-21. Учтите: он не скомпилируется, пока мы не создадим файл src/front_of_house.rs из листинга 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Затем перенесите код, который был в фигурных скобках, в новый файл src/front_of_house.rs, как в листинге 7-22. Компилятор знает, что искать нужно в этом файле, потому что в корне крейта он встретил объявление модуля с именем front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Обратите внимание: загружать файл объявлением mod нужно лишь один раз во всём дереве модулей. Как только компилятор знает, что файл — часть проекта (и знает, где в дереве модулей находится его код, — по тому, где стоит инструкция mod), остальные файлы проекта должны обращаться к коду загруженного файла по пути к месту его объявления, как описано в разделе «Пути к элементам в дереве модулей». Иными словами, mod — это не операция «include», которая может быть вам знакома по другим языкам программирования.

Теперь вынесем в отдельный файл модуль hosting. Тут всё немного иначе: hosting — дочерний модуль front_of_house, а не корневого модуля. Файл для hosting положим в новую папку, названную по его предкам в дереве модулей, — в данном случае src/front_of_house.

Чтобы начать перенос hosting, оставим в src/front_of_house.rs только объявление модуля hosting:

pub mod hosting;

Затем создадим папку src/front_of_house и в ней файл hosting.rs с определениями из модуля hosting:

pub fn add_to_waitlist() {}

Если бы мы положили hosting.rs прямо в папку src, компилятор решил бы, что код из hosting.rs относится к модулю hosting, объявленному в корне крейта, а не к дочернему модулю front_of_house. Благодаря правилам, по которым компилятор ищет код модулей в файлах, структура папок и файлов близко повторяет дерево модулей.

Мы перенесли код каждого модуля в отдельный файл, а дерево модулей осталось прежним. Вызовы функций в eat_at_restaurant работают без всяких изменений, хотя определения теперь лежат в разных файлах. Так модули можно выносить в новые файлы по мере того, как они растут.

Заметьте, что инструкция pub use crate::front_of_house::hosting в src/lib.rs тоже не изменилась, и use никак не влияет на то, какие файлы компилируются в составе крейта. Модули объявляет ключевое слово mod, а код модуля Rust ищет в файле с тем же именем, что и модуль.

Итоги

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

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

Основные коллекции

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

• Вектор (vector) хранит переменное количество значений подряд, одно за другим.
• Строка (string) — это коллекция символов. Тип String мы уже упоминали, а в этой главе разберём его подробно.
• Хеш-таблица (hash map) позволяет связать значение с определённым ключом. Это конкретная реализация более общей структуры данных, которая называется отображением (map).

О других коллекциях из стандартной библиотеки читайте в документации.

Мы разберём, как создавать и изменять векторы, строки и хеш-таблицы и чем каждая из этих коллекций особенна.

Векторы: списки значений

Векторы: списки значений

Первая коллекция, которую мы рассмотрим, — Vec<T>, или просто вектор. Вектор позволяет хранить несколько значений в одной структуре данных, которая располагает их в памяти подряд, одно за другим. Хранить вектор может только значения одного типа. Векторы удобны, когда у вас список элементов: например, строки текстового файла или цены товаров в корзине.

Создание вектора

Чтобы создать новый пустой вектор, вызывается функция Vec::new, как в листинге 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Заметьте, что здесь мы указали аннотацию типа. Раз мы ничего не кладём в этот вектор, Rust не знает, элементы какого типа мы собираемся в нём хранить. Это важный момент. Векторы реализованы с помощью обобщений; как использовать обобщения со своими типами, мы разберём в главе 10. Пока достаточно знать, что тип Vec<T> из стандартной библиотеки может хранить значения любого типа. Если вектор создаётся для конкретного типа, этот тип указывают в угловых скобках. В листинге 8-1 мы сообщили Rust, что Vec<T> в v будет хранить элементы типа i32.

Чаще вектор Vec<T> создают сразу с начальными значениями, и Rust сам выводит тип хранимых значений, так что аннотация типа нужна редко. Для этого в Rust есть удобный макрос vec!: он создаёт новый вектор с переданными значениями. В листинге 8-2 создаётся новый Vec<i32> со значениями 1, 2 и 3. Целочисленный тип здесь i32, потому что это тип целых чисел по умолчанию, как мы обсуждали в разделе «Типы данных» главы 3.

fn main() {
    let v = vec![1, 2, 3];
}

Мы задали начальные значения типа i32, поэтому Rust может вывести, что v имеет тип Vec<i32>, и аннотация типа не нужна. Теперь посмотрим, как менять вектор.

Изменение вектора

Чтобы создать вектор, а затем добавить в него элементы, можно воспользоваться методом push, как в листинге 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Как и с любой переменной, чтобы значение можно было менять, вектор нужно сделать изменяемым с помощью mut, как говорилось в главе 3. Все числа, которые мы кладём в вектор, имеют тип i32, и Rust выводит это из самих данных, так что аннотация Vec<i32> не нужна.

Чтение элементов вектора

Сослаться на значение, хранящееся в векторе, можно двумя способами: по индексу или методом get. В следующих примерах для наглядности указаны типы значений, которые возвращают эти способы.

В листинге 8-4 показаны оба способа обратиться к значению в векторе — через индексацию и через метод 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."),
    }
}

Обратите внимание на несколько деталей. Чтобы получить третий элемент, мы используем индекс 2: элементы вектора нумеруются с нуля. & и [] дают ссылку на элемент с этим индексом. А метод get, которому индекс передаётся аргументом, возвращает Option<&T>, который можно обработать через match.

Rust даёт два способа сослаться на элемент, чтобы вы могли выбрать, как программа поведёт себя при попытке обратиться по индексу за пределами существующих элементов. Для примера посмотрим, что будет, если в векторе из пяти элементов обратиться каждым из способов к элементу с индексом 100, как в листинге 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);
}

При запуске этого кода первый способ, [], вызовет панику: он ссылается на несуществующий элемент. Этот способ лучше всего подходит, когда вы хотите, чтобы программа упала при попытке обратиться за конец вектора.

Если передать методу get индекс за пределами вектора, он вернёт None и не будет паниковать. Этим методом стоит пользоваться, если обращение за пределы вектора иногда может случиться и в нормальной ситуации. Тогда в вашем коде будет логика, обрабатывающая и Some(&element), и None, как мы обсуждали в главе 6. Например, индекс может вводить человек. Если он случайно введёт слишком большое число и программа получит None, можно сообщить пользователю, сколько элементов в векторе, и дать ещё одну попытку ввести правильное значение. Это куда дружелюбнее, чем ронять программу из-за опечатки!

Когда у программы есть действительная ссылка, анализатор заимствований (borrow checker) следит за соблюдением правил владения и заимствования (о них — в главе 4), чтобы эта ссылка и все другие ссылки на содержимое вектора оставались действительными. Вспомните правило: в одной области видимости не может быть одновременно изменяемых и неизменяемых ссылок. Это правило срабатывает в листинге 8-6: мы держим неизменяемую ссылку на первый элемент вектора и пытаемся добавить элемент в конец. Программа не скомпилируется, если дальше в функции мы снова обратимся к этому первому элементу.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

При компиляции получим ошибку:

$ 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

Может показаться, что код из листинга 8-6 должен работать: какое дело ссылке на первый элемент до изменений в конце вектора? Ошибка связана с тем, как устроены векторы. Вектор хранит значения в памяти подряд. Если в уже выделенном участке памяти не хватит места для нового элемента, вектор выделит новый, больший участок и скопирует туда все старые элементы. И тогда ссылка на первый элемент указывала бы на уже освобождённую память. Правила заимствования не дают программе попасть в такую ситуацию.

Перебор значений вектора

Чтобы по очереди обратиться к каждому элементу вектора, удобнее перебрать все элементы, чем обращаться к ним по одному по индексу. В листинге 8-7 показано, как циклом for получить неизменяемые ссылки на каждый элемент вектора значений i32 и вывести их.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Можно перебирать и изменяемые ссылки на элементы изменяемого вектора, чтобы изменить все элементы. Цикл for в листинге 8-8 прибавит к каждому элементу 50.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Чтобы изменить значение, на которое указывает изменяемая ссылка, нужно сначала добраться до значения в i оператором разыменования *, и только потом применять +=. Подробнее об операторе разыменования — в разделе «Переход по ссылке к значению» главы 15.

Перебирать вектор безопасно — и неизменяемо, и изменяемо — благодаря правилам анализатора заимствований. Если бы в теле циклов for из листингов 8-7 и 8-8 мы попытались вставить или удалить элементы, получили бы ошибку компиляции, похожую на ошибку из листинга 8-6. Ссылка на вектор, которую держит цикл for, не даёт одновременно изменить вектор целиком.

Хранение разных типов с помощью перечисления

Вектор может хранить только значения одного типа. Это бывает неудобно: иногда действительно нужно хранить список элементов разных типов. К счастью, все варианты перечисления относятся к одному типу — типу перечисления. Так что если нужно одним типом представить элементы разных типов, можно определить перечисление!

Допустим, мы хотим получить значения из строки электронной таблицы, где в одних столбцах целые числа, в других — числа с плавающей точкой, а в третьих — строки. Определим перечисление, варианты которого хранят значения разных типов, — при этом все варианты считаются одним типом, типом перечисления. Затем создадим вектор, который хранит это перечисление, а значит, в конечном счёте хранит значения разных типов. Это показано в листинге 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 должен знать при компиляции, какие типы будут в векторе, чтобы точно знать, сколько памяти в куче понадобится для каждого элемента. Кроме того, нужно явно указать, какие типы допустимы в векторе. Если бы Rust позволял вектору хранить что угодно, какой-нибудь из типов мог бы вызвать ошибку при операциях над элементами вектора. Перечисление вместе с выражением match гарантирует, что Rust ещё при компиляции проверит обработку всех возможных случаев, как говорилось в главе 6.

Если заранее неизвестен полный набор типов, которые программа получит во время работы и будет хранить в векторе, приём с перечислением не сработает. Тогда можно использовать трейт-объект — о них мы поговорим в главе 18.

Мы рассмотрели самые распространённые способы работы с векторами, но обязательно загляните в документацию по API: в стандартной библиотеке для Vec<T> определено множество полезных методов. Например, кроме push есть метод pop, который удаляет и возвращает последний элемент.

Вместе с вектором уничтожаются и его элементы

Как и любая другая структура (struct), вектор освобождается, когда выходит из области видимости, — это показано в листинге 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // что-то делаем с v
    } // <- здесь v выходит из области видимости, и память освобождается
}

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

Перейдём к следующей коллекции — String!

Строки: текст в UTF-8

Строки: текст в UTF-8

О строках мы уже говорили в главе 4, а теперь разберём их подробнее. Новички в Rust часто спотыкаются о строки по трём причинам сразу: Rust любит показывать возможные ошибки; строки — более сложная структура данных, чем считают многие программисты; и наконец, UTF-8. Вместе это может показаться трудным, если вы пришли из других языков.

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

Что такое строка

Сначала определимся, что мы называем строкой. В самом ядре языка Rust есть только один строковый тип — строковый срез str, который обычно встречается в заимствованной форме, &str. В главе 4 мы говорили о строковых срезах: это ссылки на данные строки в кодировке UTF-8, хранящиеся где-то ещё. Например, строковые литералы хранятся в бинарном файле программы и поэтому являются строковыми срезами.

Тип String предоставляется стандартной библиотекой, а не встроен в ядро языка. Это растущий, изменяемый строковый тип в кодировке UTF-8, который владеет своими данными. Когда растацеаны говорят о «строках» в Rust, они могут иметь в виду как String, так и строковый срез &str, а не какой-то один из них. Хотя этот раздел в основном про String, оба типа активно используются в стандартной библиотеке Rust, и оба — и String, и строковые срезы — хранят текст в UTF-8.

Создание строки

Многие операции, доступные для Vec<T>, есть и у String: на самом деле String реализован как обёртка над вектором байтов с дополнительными гарантиями, ограничениями и возможностями. Пример функции, которая одинаково работает и с Vec<T>, и со String, — функция new, создающая экземпляр, как в листинге 8-11.

fn main() {
    let mut s = String::new();
}

Эта строка кода создаёт новую пустую строку s, в которую потом можно загрузить данные. Часто строку хочется сразу создать с какими-то начальными данными. Для этого есть метод to_string, доступный у любого типа, который реализует трейт Display, — в том числе у строковых литералов. В листинге 8-12 два примера.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // Метод можно вызвать и прямо у литерала:
    let s = "initial contents".to_string();
}

Этот код создаёт строку с содержимым initial contents.

Создать String из строкового литерала можно и функцией String::from. Код в листинге 8-13 равнозначен коду из листинга 8-12 с to_string.

fn main() {
    let s = String::from("initial contents");
}

Строки используются для очень многих задач, поэтому для них есть множество разных обобщённых API, и выбор вариантов большой. Некоторые из них могут показаться избыточными, но у каждого своё место! В нашем случае String::from и to_string делают одно и то же, так что выбор между ними — вопрос стиля и читабельности.

Помните, что строки хранятся в UTF-8, поэтому в них можно положить любые корректно закодированные данные, как в листинге 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");
}

Всё это — допустимые значения String.

Изменение строки

String может расти, а её содержимое — меняться, как у Vec<T>, если добавлять в неё данные. Кроме того, значения String удобно склеивать оператором + или макросом format!.

Дописывание через push_str и push

Нарастить String можно методом push_str, который дописывает в конец строковый срез, как в листинге 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

После этих двух строк в s будет foobar. Метод push_str принимает строковый срез, потому что забирать владение параметром нам вовсе не обязательно. Например, в коде из листинга 8-16 мы хотим пользоваться s2 и после того, как дописали её содержимое в s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Если бы метод push_str забирал владение s2, мы не смогли бы вывести её значение в последней строке. Но этот код работает так, как мы и ожидаем!

Метод push принимает параметром один символ и добавляет его в String. В листинге 8-17 мы добавляем в String букву l методом push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

В результате в s будет lol.

Склеивание через + и format!

Часто нужно соединить две существующие строки. Один из способов — оператор +, как в листинге 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // обратите внимание: s1 перемещена сюда, и использовать её больше нельзя
}

В строке s3 будет Hello, world!. Почему после сложения s1 перестаёт быть действительной и почему мы взяли ссылку на s2 — объясняется сигнатурой метода, который вызывается при использовании оператора +. Оператор + вызывает метод add, сигнатура которого выглядит примерно так:

fn add(self, s: &str) -> String {

В стандартной библиотеке add определён через обобщения и ассоциированные типы. Здесь мы подставили конкретные типы — именно они получаются, когда этот метод вызывается со значениями String. Обобщения мы обсудим в главе 10. А эта сигнатура даёт нам подсказки, нужные, чтобы разобраться в хитростях оператора +.

Во-первых, перед s2 стоит &, то есть к первой строке мы прибавляем ссылку на вторую. Так получается из-за параметра s в функции add: к String можно прибавить только строковый срез, сложить два значения String напрямую нельзя. Но постойте: тип &s2 — это &String, а не &str, как указано во втором параметре add. Почему же листинг 8-18 компилируется?

Использовать &s2 в вызове add можно потому, что компилятор умеет привести аргумент &String к типу &str. При вызове add Rust применяет неявное разыменование (deref coercion), которое здесь превращает &s2 в &s2[..]. Подробнее о неявном разыменовании мы поговорим в главе 15. Метод add не забирает владение параметром s, поэтому после этой операции s2 остаётся действительной String.

Во-вторых, из сигнатуры видно, что add забирает владение self: перед self нет &. Значит, s1 из листинга 8-18 перемещается в вызов add и после него становится недействительной. Так что хотя let s3 = s1 + &s2; выглядит так, будто копирует обе строки и создаёт новую, на самом деле эта инструкция забирает владение s1, дописывает в её конец копию содержимого s2 и возвращает владение результатом. Иначе говоря, кажется, что тут много копирования, а его нет: реализация эффективнее, чем копирование.

Если нужно склеить несколько строк, с оператором + становится неудобно:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

В итоге в s будет tic-tac-toe. Из-за всех этих + и " трудно понять, что происходит. Для более сложного соединения строк лучше подходит макрос format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Этот код тоже записывает в s значение tic-tac-toe. Макрос format! работает как println!, только не выводит результат на экран, а возвращает String с этим содержимым. Версию с format! читать гораздо проще, а код, который генерирует макрос format!, использует ссылки, так что этот вызов не забирает владение ни одним из своих параметров.

Обращение к строке по индексу

Во многих языках программирования обращение к отдельным символам строки по индексу — нормальная и распространённая операция. Но если в Rust попытаться обратиться к части String через индекс, получится ошибка. Посмотрите на некорректный код из листинга 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

Этот код приведёт к ошибке:

$ 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: `usize` implements trait `SliceIndex<T>`
 --> /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/slice/index.rs:179:0
  |
  = note: `SliceIndex<[T]>`
 --> /rustc/88d9e12ae178fab0fb5cc050a94da85685d449ea/library/core/src/bstr/traits.rs:197:0
  |
  = note: `SliceIndex<ByteStr>`
  = 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

Ошибка говорит сама за себя: строки в Rust не поддерживают индексацию. Но почему? Чтобы ответить на этот вопрос, нужно разобраться, как Rust хранит строки в памяти.

Внутреннее представление

String — это обёртка над Vec<u8>. Посмотрим на несколько корректно закодированных в UTF-8 строк из листинга 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");
}

Здесь len будет равно 4: вектор, хранящий строку "Hola", занимает 4 байта. Каждая из этих букв в UTF-8 занимает 1 байт. А вот следующая строка может вас удивить:

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

На вопрос, какой длины эта строка, вы, скорее всего, ответите: 12. А Rust ответит: 24. Столько байтов нужно, чтобы закодировать «Здравствуйте» в UTF-8: каждое скалярное значение Юникода в этой строке занимает 2 байта. Поэтому индекс байта в строке не всегда соответствует целому скалярному значению Юникода. Чтобы это показать, рассмотрим такой некорректный код на Rust:

let hello = "Здравствуйте";
let answer = &hello[0];

Вы уже знаете, что answer не будет равно З, первой букве. В UTF-8 первый байт З — это 208, а второй — 151. Казалось бы, тогда answer должно быть 208, но 208 сам по себе — не символ. Пользователь, который попросил первую букву строки, вряд ли хотел получить 208, но других данных по индексу 0 у Rust нет. Обычно пользователям не нужно значение байта, даже если в строке только латиница: если бы &"hi"[0] был допустимым кодом, возвращающим байт, он вернул бы 104, а не h.

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

Байты, скалярные значения и графемные кластеры

Ещё одна особенность UTF-8: с точки зрения Rust на строку можно смотреть тремя способами — как на байты, как на скалярные значения и как на графемные кластеры (они ближе всего к тому, что мы называем буквами).

Возьмём слово на хинди «नमस्ते», записанное письмом деванагари. Оно хранится как вектор значений u8, который выглядит так:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Это 18 байт — именно так компьютер в конечном счёте хранит эти данные. Если смотреть на них как на скалярные значения Юникода, то есть на значения типа char в Rust, байты выглядят так:

['न', 'म', 'स', '्', 'त', 'े']

Здесь шесть значений char, но четвёртое и шестое — не буквы: это диакритические знаки, которые сами по себе смысла не имеют. И наконец, если смотреть на них как на графемные кластеры, получится то, что человек назвал бы четырьмя буквами, из которых состоит это слово:

["न", "म", "स्", "ते"]

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

И последняя причина, по которой Rust не позволяет получить символ из String по индексу: от операции индексации ожидается, что она всегда выполняется за константное время (O(1)). Но со String такую производительность гарантировать невозможно: Rust пришлось бы пройти содержимое от начала до индекса, чтобы определить, сколько там корректных символов.

Срезы строк

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

Вместо [] с одним числом можно использовать [] с диапазоном — так получится строковый срез, содержащий определённые байты:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Здесь s будет &str с первыми 4 байтами строки. Мы уже говорили, что каждый из этих символов занимает 2 байта, значит, s будет равно Зд.

Если попытаться вырезать только часть байтов символа, например &hello[0..1], Rust запаникует во время выполнения — так же, как при обращении к вектору по недопустимому индексу:

$ 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' (6017738) panicked at src/main.rs:4:19:
end byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2 of string)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Создавая строковые срезы по диапазонам, будьте осторожны: это может уронить программу.

Перебор строк

Работать с частями строк лучше всего, явно указывая, что вам нужно — символы или байты. Для отдельных скалярных значений Юникода есть метод chars. Вызов chars у «Зд» разделяет строку и возвращает два значения типа char, а результат можно перебрать и обратиться к каждому элементу:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Этот код выведет:

З
д

Можно воспользоваться и методом bytes, который возвращает каждый «сырой» байт, — возможно, в вашей задаче нужно именно это:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Этот код выведет 4 байта, из которых состоит строка:

208
151
208
180

Но обязательно помните, что корректное скалярное значение Юникода может состоять из нескольких байтов.

Получить из строки графемные кластеры, как в случае с деванагари, — сложная задача, поэтому стандартная библиотека этого не умеет. Если вам нужна такая функциональность, поищите подходящий крейт на crates.io.

Строки — это непросто

Подведём итог: строки — штука сложная. Разные языки программирования по-разному решают, как показать эту сложность программисту. Rust выбрал путь, при котором корректная обработка данных String — это поведение по умолчанию во всех программах на Rust. Значит, программистам приходится заранее продумывать работу с UTF-8. Из-за этого сложность строк в Rust заметнее, чем в других языках, зато вам не придётся потом, на поздних этапах разработки, разбираться с ошибками из-за не-ASCII-символов.

Хорошая новость: в стандартной библиотеке много функциональности на основе типов String и &str, которая помогает правильно справляться с такими сложными ситуациями. Обязательно загляните в документацию — там есть полезные методы вроде contains для поиска в строке и replace для замены частей строки другой строкой.

А теперь перейдём к чему-нибудь чуть попроще — к хеш-таблицам!

Хеш-таблицы: ключи и значения

Хеш-таблицы: ключи и значения

Последняя из наших основных коллекций — хеш-таблица. Тип HashMap<K, V> хранит соответствие ключей типа K значениям типа V и использует для этого хеш-функцию, которая определяет, как ключи и значения размещаются в памяти. Такая структура данных есть во многих языках, но называется по-разному: hash, map, object, hash table, dictionary (словарь) или associative array (ассоциативный массив) — и это далеко не всё.

Хеш-таблицы удобны, когда данные нужно искать не по индексу, как в векторе, а по ключу, который может быть любого типа. Например, в игре можно хранить счёт каждой команды в хеш-таблице, где ключ — название команды, а значение — её счёт. Зная название команды, можно получить её счёт.

В этом разделе мы рассмотрим основной API хеш-таблиц, но в функциях, которые стандартная библиотека определяет для HashMap<K, V>, спрятано ещё много полезного. Как обычно, подробности ищите в документации стандартной библиотеки.

Создание хеш-таблицы

Один из способов создать пустую хеш-таблицу — вызвать new, а элементы добавлять методом insert. В листинге 8-20 мы отслеживаем счёт двух команд — Blue (синих) и Yellow (жёлтых). У синих сначала 10 очков, у жёлтых — 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Обратите внимание: сначала нужно подключить HashMap через use из раздела коллекций стандартной библиотеки. Из трёх наших основных коллекций эта используется реже всего, поэтому её нет среди того, что прелюдия автоматически подключает в область видимости. Да и поддержки в стандартной библиотеке у хеш-таблиц меньше: например, нет встроенного макроса для их создания.

Как и векторы, хеш-таблицы хранят данные в куче. У этой HashMap ключи типа String и значения типа i32. И, как векторы, хеш-таблицы однородны: все ключи должны быть одного типа, и все значения — тоже одного типа.

Доступ к значениям в хеш-таблице

Получить значение из хеш-таблицы можно, передав его ключ методу get, как в листинге 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);
}

Здесь score получит значение, связанное с синей командой, — то есть 10. Метод get возвращает Option<&V>: если в хеш-таблице нет значения для этого ключа, get вернёт None. Программа обрабатывает Option так: сначала вызывает copied, чтобы получить Option<i32> вместо Option<&i32>, а затем unwrap_or, чтобы записать в score ноль, если в scores нет записи для этого ключа.

Перебрать все пары «ключ — значение» в хеш-таблице можно так же, как элементы вектора, — циклом 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}");
    }
}

Этот код выведет все пары в произвольном порядке:

Yellow: 50
Blue: 10

Хеш-таблицы и владение

Значения типов, реализующих трейт Copy, вроде i32, копируются в хеш-таблицу. А значения, которые владеют своими данными, вроде String, перемещаются, и владельцем этих значений становится хеш-таблица, как показано в листинге 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 и field_value уже недействительны; попробуйте их
    // использовать и посмотрите, какую ошибку выдаст компилятор!
}

После того как вызов insert переместил переменные field_name и field_value в хеш-таблицу, пользоваться ими уже нельзя.

Если вставлять в хеш-таблицу ссылки на значения, сами значения в неё перемещаться не будут. Но значения, на которые указывают ссылки, должны оставаться действительными как минимум столько же, сколько и хеш-таблица. Подробнее об этом мы поговорим в разделе «Проверка ссылок с помощью времён жизни» главы 10.

Изменение хеш-таблицы

Количество пар «ключ — значение» может расти, но с каждым уникальным ключом в каждый момент связано только одно значение (обратное неверно: например, и у синих, и у жёлтых в хеш-таблице scores может храниться значение 10).

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

Перезапись значения

Если вставить в хеш-таблицу ключ со значением, а потом вставить тот же ключ с другим значением, значение, связанное с ключом, будет заменено. Хотя код в листинге 8-23 вызывает insert дважды, в хеш-таблице окажется только одна пара «ключ — значение»: оба раза мы вставляем значение для ключа синей команды.

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

Этот код выведет {"Blue": 25}. Исходное значение 10 перезаписано.

Добавление ключа, только если его ещё нет

Часто нужно проверить, есть ли уже в хеш-таблице такой ключ со значением, и дальше поступить так: если ключ есть — оставить существующее значение как есть; если нет — вставить ключ и значение для него.

Для этого у хеш-таблиц есть специальный API — метод entry, который принимает параметром ключ, который нужно проверить. Метод entry возвращает перечисление Entry, представляющее значение, которое может существовать, а может и нет. Допустим, мы хотим проверить, есть ли значение у ключа жёлтой команды. Если нет — вставить значение 50; то же самое для синей команды. С API entry код выглядит как в листинге 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:?}");
}

Метод or_insert у Entry устроен так: если ключ существует, он возвращает изменяемую ссылку на значение этого ключа; если нет — вставляет свой параметр как новое значение для ключа и возвращает изменяемую ссылку на это новое значение. Это куда чище, чем писать такую логику самим, да и с анализатором заимствований так ладить проще.

Код из листинга 8-24 выведет {"Yellow": 50, "Blue": 10}. Первый вызов entry вставит ключ жёлтой команды со значением 50, потому что значения у жёлтых ещё нет. Второй вызов entry хеш-таблицу не изменит: у синих уже есть значение 10.

Обновление значения на основе старого

Ещё один частый сценарий — найти значение по ключу и обновить его, опираясь на старое значение. Например, в листинге 8-25 код подсчитывает, сколько раз каждое слово встречается в тексте. Мы используем хеш-таблицу, где ключи — слова, и увеличиваем значение, чтобы отслеживать, сколько раз нам встретилось это слово. Если слово встретилось впервые, сначала вставляем значение 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:?}");
}

Этот код выведет {"world": 2, "hello": 1, "wonderful": 1}. У вас пары могут появиться в другом порядке: как мы говорили в разделе «Доступ к значениям в хеш-таблице», хеш-таблица перебирается в произвольном порядке.

Метод split_whitespace возвращает итератор по фрагментам строки text, разделённым пробельными символами. Метод or_insert возвращает изменяемую ссылку (&mut V) на значение указанного ключа. Мы сохраняем эту ссылку в переменной count, поэтому, чтобы присвоить значение, сначала нужно разыменовать count звёздочкой (*). Изменяемая ссылка выходит из области видимости в конце итерации цикла for, так что все эти изменения безопасны и разрешены правилами заимствования.

Хеш-функции

По умолчанию HashMap использует хеш-функцию SipHash, которая устойчива к атакам типа «отказ в обслуживании» (DoS), направленным на хеш-таблицы¹. Это не самый быстрый алгоритм хеширования, но выигрыш в безопасности стоит потери в производительности. Если вы профилируете код и обнаружите, что хеш-функция по умолчанию для ваших задач слишком медленная, можно переключиться на другую, указав другой хешер (hasher) — тип, реализующий трейт BuildHasher. О трейтах и о том, как их реализовывать, мы поговорим в главе 10. Писать свой хешер с нуля не обязательно: на crates.io есть библиотеки от других пользователей Rust с хешерами для многих распространённых алгоритмов хеширования.

Итоги

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

1. Дан список целых чисел. С помощью вектора найдите медиану (значение, которое окажется посередине после сортировки) и моду (значение, которое встречается чаще всего; здесь пригодится хеш-таблица).
2. Переведите строки на «поросячью латынь» (Pig Latin). Первая согласная каждого слова переносится в конец слова, и к ней добавляется ay: first превращается в irst-fay. К словам, которые начинаются с гласной, в конец добавляется hay (apple превращается в apple-hay). Не забывайте про особенности кодировки UTF-8!
3. С помощью хеш-таблицы и векторов сделайте текстовый интерфейс, через который пользователь может добавлять сотрудников в отделы компании: например, «Add Sally to Engineering» или «Add Amir to Sales». Затем дайте пользователю возможность получить список всех сотрудников отдела или всех сотрудников компании по отделам, отсортированный по алфавиту.

В документации по API стандартной библиотеки описаны методы векторов, строк и хеш-таблиц, которые пригодятся для этих упражнений!

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

1. https://en.wikipedia.org/wiki/SipHash ↩

Обработка ошибок

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

Rust делит ошибки на две большие категории: исправимые и неисправимые. При исправимой ошибке (recoverable error), например файл не найден, скорее всего, достаточно сообщить пользователю о проблеме и повторить операцию. Неисправимые ошибки (unrecoverable errors) — это всегда признак бага, например попытки обратиться за конец массива, и в таких случаях программу нужно немедленно остановить.

Большинство языков не различают эти два вида ошибок и обрабатывают их одинаково — например, с помощью исключений. В Rust исключений нет. Вместо них есть тип Result<T, E> для исправимых ошибок и макрос panic!, который останавливает выполнение, когда программа сталкивается с неисправимой ошибкой. В этой главе мы сначала разберём вызов panic!, а потом поговорим о возврате значений Result<T, E>. А ещё обсудим, как решить, пытаться ли восстановиться после ошибки или остановить выполнение.

Неисправимые ошибки и panic!

Неисправимые ошибки и panic!

Иногда в коде случается что-то плохое, и с этим ничего не поделать. На такие случаи в Rust есть макрос panic!. На практике вызвать панику можно двумя способами: сделать что-то, отчего код запаникует (например, обратиться за конец массива), или явно вызвать макрос panic!. В обоих случаях в программе возникает паника. По умолчанию при панике программа выводит сообщение об ошибке, раскручивает и очищает стек и завершается. С помощью переменной окружения можно также попросить Rust при панике показывать стек вызовов — так проще найти её источник.

[profile.release]
panic = 'abort'

Попробуем вызвать panic! в простой программе:

fn main() {
    panic!("crash and burn");
}

Запустив программу, вы увидите примерно такое:

$ 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' (6018279) panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Вызов panic! порождает сообщение об ошибке в двух последних строках. Первая строка показывает наше сообщение паники и место в исходном коде, где она произошла: src/main.rs:2:5 означает вторую строку, пятый символ файла src/main.rs.

В данном случае указанная строка — часть нашего кода, и, перейдя к ней, мы увидим вызов макроса panic!. Но бывает, что panic! вызывается не в нашем коде, а в коде, который вызывается из нашего, — например, в библиотеке. Тогда в сообщении будет файл и строка из этого чужого кода, а не строка нашего кода, которая в итоге привела к панике.

Чтобы найти часть нашего кода, которая вызывает проблему, можно воспользоваться трассировкой (backtrace) функций, из которых пришёл вызов panic!. Чтобы понять, как с ней работать, рассмотрим другой пример: на этот раз panic! вызывается не нашим кодом напрямую, а библиотекой — из-за бага в нашем коде. В листинге 9-1 код пытается обратиться к элементу вектора по индексу за пределами допустимых.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Здесь мы пытаемся получить сотый элемент вектора (с индексом 99, ведь нумерация начинается с нуля), а в векторе всего три элемента. В такой ситуации Rust запаникует. [] должен вернуть элемент, но если индекс недопустимый, никакого правильного элемента, который Rust мог бы вернуть, просто нет.

В C попытка прочитать данные за концом структуры данных — это неопределённое поведение. Вы можете получить то, что лежит в памяти там, где был бы этот элемент, хотя эта память структуре не принадлежит. Это называется чтением за границей буфера (buffer overread) и может привести к уязвимостям: злоумышленник, сумев подобрать индекс, прочитает данные, лежащие после структуры, к которым у него не должно быть доступа.

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

$ 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' (6017887) 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

Ошибка указывает на строку 4 файла main.rs, где мы пытаемся обратиться к индексу 99 вектора v.

Строка note: подсказывает, что можно задать переменную окружения RUST_BACKTRACE и получить трассировку того, что именно привело к ошибке. Трассировка (backtrace) — это список всех функций, вызванных на пути к этой точке. Трассировки в Rust работают так же, как в других языках: читайте сверху вниз, пока не встретите файл, который написали вы. Именно там и возникла проблема. Строки выше этого места — функции, которые были вызваны из вашего кода (например, из стандартной библиотеки). Строки ниже — функции, из которых был вызван ваш код. Среди этих строк может быть код ядра Rust, стандартной библиотеки или крейтов, которыми вы пользуетесь. Попробуем получить трассировку, задав переменной окружения RUST_BACKTRACE любое значение, кроме 0. В листинге 9-2 — вывод, похожий на тот, что увидите вы.

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

Вывода много! Точный вид зависит от операционной системы и версии Rust. Чтобы трассировка содержала эту информацию, должны быть включены отладочные символы. Они включены по умолчанию, если запускать cargo build или cargo run без флага --release, как здесь.

В выводе из листинга 9-2 строка 6 трассировки указывает на строку нашего проекта, которая вызывает проблему: строку 4 файла src/main.rs. Если мы не хотим, чтобы программа паниковала, начинать расследование нужно с места, на которое указывает первая строка с упоминанием нашего файла. В листинге 9-1 мы нарочно написали код, который паникует, и исправить это можно, просто не запрашивая элемент за пределами индексов вектора. Когда ваш код запаникует в будущем, нужно будет разобраться, какое действие и с какими значениями приводит к панике и что код должен делать вместо этого.

Мы ещё вернёмся к panic! и обсудим, когда стоит, а когда не стоит обрабатывать ошибки с его помощью, в разделе «Паниковать или не паниковать» этой главы. А дальше посмотрим, как восстанавливаться после ошибок с помощью Result.

Исправимые ошибки и Result

Исправимые ошибки и Result

Большинство ошибок не настолько серьёзны, чтобы останавливать программу целиком. Часто функция не срабатывает по причине, которую легко понять и на которую можно отреагировать. Например, если вы пытаетесь открыть файл, а его нет, возможно, разумнее создать файл, а не завершать процесс.

Вспомните раздел «Обрабатываем возможный сбой с помощью Result» главы 2: перечисление Result определено с двумя вариантами, Ok и Err:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T и E — обобщённые параметры типа; подробно обобщения мы обсудим в главе 10. Сейчас достаточно знать, что T — это тип значения, которое вернётся в случае успеха внутри варианта Ok, а E — тип ошибки, которая вернётся в случае неудачи внутри варианта Err. Благодаря этим обобщённым параметрам тип Result и его функции можно использовать в самых разных ситуациях, где значения успеха и ошибки бывают разными.

Вызовем функцию, которая возвращает Result, потому что может не сработать. В листинге 9-3 мы пытаемся открыть файл.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

File::open возвращает Result<T, E>. Вместо обобщённого параметра T реализация File::open подставила тип значения успеха — std::fs::File, то есть дескриптор файла. А тип ошибки E — std::io::Error. Такой возвращаемый тип означает, что вызов File::open может пройти успешно и вернуть дескриптор файла, из которого можно читать или в который можно писать. Но может и не сработать: например, файла может не быть или у нас может не хватать прав на доступ к нему. Функции File::open нужно как-то сообщить, получилось у неё или нет, и заодно отдать либо дескриптор файла, либо сведения об ошибке. Именно это и передаёт перечисление Result.

Если File::open сработает, в переменной greeting_file_result окажется экземпляр Ok с дескриптором файла. Если нет — экземпляр Err с подробностями о том, какая ошибка произошла.

Код из листинга 9-3 нужно дополнить, чтобы он вёл себя по-разному в зависимости от того, что вернула File::open. В листинге 9-4 показан один из способов обработать Result с помощью базового инструмента — выражения match, которое мы обсуждали в главе 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:?}"),
    };
}

Заметьте, что перечисление Result и его варианты, как и Option, уже подключены прелюдией, поэтому в ветках match не нужно писать Result:: перед Ok и Err.

Если результат — Ok, этот код достаёт из варианта Ok внутреннее значение file, и мы присваиваем этот дескриптор переменной greeting_file. После match дескриптором можно пользоваться для чтения или записи.

Вторая ветка match обрабатывает случай, когда File::open вернула Err. В этом примере мы решили вызвать макрос panic!. Если в текущей папке нет файла hello.txt, то при запуске кода макрос 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' (6018048) 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

Как обычно, вывод точно говорит, что пошло не так.

Разная реакция на разные ошибки

Код из листинга 9-4 вызовет panic!, по какой бы причине File::open ни вернула ошибку. Но мы хотим реагировать на разные причины по-разному. Если файла нет, мы хотим создать его и вернуть дескриптор нового файла. Если же File::open не сработала по любой другой причине — например, не хватает прав на открытие файла, — код по-прежнему должен вызывать panic!, как в листинге 9-4. Для этого добавим внутреннее выражение match, как в листинге 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:?}");
            }
        },
    };
}

Внутри варианта Err, который возвращает File::open, лежит значение типа io::Error — это структура из стандартной библиотеки. У неё есть метод kind, который возвращает значение io::ErrorKind. Перечисление io::ErrorKind тоже из стандартной библиотеки, его варианты описывают разные виды ошибок, которые могут возникнуть при операциях ввода-вывода. Нам нужен вариант ErrorKind::NotFound: он означает, что файла, который мы пытаемся открыть, ещё нет. Так что мы сопоставляем greeting_file_result, а внутри — ещё и error.kind().

Во внутреннем match мы проверяем, является ли значение, которое вернул error.kind(), вариантом NotFound перечисления ErrorKind. Если да, пробуем создать файл через File::create. Но File::create тоже может не сработать, поэтому во внутреннем match нужна вторая ветка: если файл создать не удалось, выводится другое сообщение об ошибке. Вторая ветка внешнего match остаётся прежней, так что при любой ошибке, кроме отсутствия файла, программа паникует.

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

Краткие способы паниковать при ошибке

match работает неплохо, но многословно и не всегда хорошо передаёт намерение. У типа Result<T, E> есть множество вспомогательных методов для разных, более конкретных задач. Метод unwrap — сокращение, которое реализовано ровно как выражение match из листинга 9-4. Если значение Result — вариант Ok, unwrap вернёт значение внутри Ok. Если Err — unwrap сам вызовет для нас макрос panic!. Вот unwrap в действии:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Если запустить этот код без файла hello.txt, мы увидим сообщение от вызова panic!, который делает метод unwrap:

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

Похожий метод expect позволяет ещё и задать сообщение для panic!. Если использовать expect вместо unwrap и писать хорошие сообщения об ошибках, это передаст ваше намерение и упростит поиск источника паники. Синтаксис expect выглядит так:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

expect используется так же, как unwrap: возвращает дескриптор файла или вызывает макрос panic!. Только сообщением при вызове panic! будет не стандартный текст, который использует unwrap, а параметр, переданный в expect. Выглядит это так:

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

В коде продакшен-качества большинство растацеанов выбирают expect, а не unwrap, и поясняют в сообщении, почему операция должна всегда проходить успешно. Тогда, если ваши предположения однажды окажутся неверными, при отладке у вас будет больше информации.

Проброс ошибок

Когда функция вызывает что-то, что может не сработать, ошибку не обязательно обрабатывать внутри самой функции: её можно вернуть вызывающему коду, и пусть он решает, что делать. Это называется пробросом ошибки (propagating). Так у вызывающего кода больше контроля: у него может быть больше информации или логики, определяющей, как обработать ошибку, чем есть в контексте вашего кода.

Например, в листинге 9-6 функция читает имя пользователя из файла. Если файла нет или его не удаётся прочитать, функция вернёт эти ошибки коду, который её вызвал.

#![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),
    }
}
}

Эту функцию можно записать гораздо короче, но сначала мы сделаем многое вручную, чтобы разобраться в обработке ошибок, а короткий вариант покажем в конце. Начнём с возвращаемого типа функции: Result<String, io::Error>. Это значит, что функция возвращает значение типа Result<T, E>, где вместо обобщённого параметра T подставлен конкретный тип String, а вместо E — конкретный тип io::Error.

Если функция отработает без проблем, вызывающий код получит значение Ok со String внутри — именем пользователя (username), которое функция прочитала из файла. Если возникнут проблемы, вызывающий код получит значение Err с экземпляром io::Error, в котором есть подробности о проблеме. Мы выбрали io::Error типом ошибки потому, что именно такой тип ошибки возвращают обе операции в теле функции, которые могут не сработать: функция File::open и метод read_to_string.

Тело функции начинается с вызова File::open. Затем мы обрабатываем Result выражением match, похожим на match из листинга 9-4. Если File::open сработала, дескриптор файла из переменной образца file становится значением изменяемой переменной username_file, и функция продолжает работу. В случае Err вместо panic! мы с помощью return досрочно выходим из функции и передаём значение ошибки из File::open (теперь оно в переменной образца e) вызывающему коду как ошибку нашей функции.

Итак, если в username_file есть дескриптор файла, функция создаёт новую String в переменной username и вызывает у дескриптора username_file метод read_to_string, чтобы прочитать содержимое файла в username. Метод read_to_string тоже возвращает Result: он может не сработать, даже если File::open прошла успешно. Поэтому нужен ещё один match. Если read_to_string сработал, то и вся функция сработала, и мы возвращаем имя пользователя из файла, которое теперь лежит в username, обёрнутое в Ok. Если read_to_string не сработал, возвращаем значение ошибки — так же, как в match, обрабатывавшем результат File::open. Только писать return явно не нужно: это последнее выражение в функции.

Код, который вызывает эту функцию, получит либо Ok с именем пользователя, либо Err с io::Error и сам решит, что с ними делать. Получив Err, он может, например, вызвать panic! и уронить программу, использовать имя пользователя по умолчанию или поискать имя пользователя где-то, кроме файла. Мы не знаем, что именно пытается сделать вызывающий код, поэтому передаём наверх всю информацию — и об успехе, и об ошибке, — чтобы он обработал её подходящим образом.

Такой проброс ошибок встречается в Rust настолько часто, что для него есть специальный оператор — вопросительный знак ?.

Сокращение: оператор ?

В листинге 9-7 — реализация read_username_from_file, которая работает так же, как в листинге 9-6, но использует оператор ?.

#![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)
}
}

? после значения Result работает почти так же, как выражения match, которыми мы обрабатывали значения Result в листинге 9-6. Если значение Result — это Ok, выражение вернёт значение изнутри Ok, и программа продолжит работу. Если это Err, то Err вернётся из всей функции, как будто мы написали return, — и ошибка будет проброшена вызывающему коду.

Но между тем, что делает match из листинга 9-6, и тем, что делает оператор ?, есть разница. Значения ошибок, к которым применён ?, проходят через функцию from из трейта From стандартной библиотеки — она служит для преобразования значений из одного типа в другой. Когда оператор ? вызывает from, полученный тип ошибки преобразуется в тип ошибки, указанный в возвращаемом типе текущей функции. Это удобно, когда функция возвращает один тип ошибки, описывающий все возможные неудачи, даже если отдельные её части могут ломаться по самым разным причинам.

Например, функцию read_username_from_file из листинга 9-7 можно изменить так, чтобы она возвращала наш собственный тип ошибки OurError. Если ещё и определить impl From<io::Error> for OurError, чтобы создавать OurError из io::Error, то вызовы оператора ? в теле read_username_from_file сами вызовут from и преобразуют типы ошибок — без всякого дополнительного кода в функции.

В листинге 9-7 ? в конце вызова File::open положит значение изнутри Ok в переменную username_file. Если произойдёт ошибка, оператор ? досрочно выйдет из всей функции и отдаст значение Err вызывающему коду. То же самое относится к ? в конце вызова read_to_string.

Оператор ? избавляет от кучи шаблонного кода и упрощает реализацию функции. Её можно сократить ещё сильнее, если сразу после ? продолжить цепочку вызовов методов, как в листинге 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)
}
}

Создание новой String в username мы перенесли в начало функции; сам этот код остался прежним. Вместо переменной username_file мы вызываем read_to_string прямо у результата File::open("hello.txt")?. В конце вызова read_to_string по-прежнему стоит ?, и мы по-прежнему возвращаем Ok с username, если и File::open, и read_to_string сработали без ошибок. Функциональность та же, что в листингах 9-6 и 9-7, — просто запись другая, более удобная.

В листинге 9-9 показано, как сделать ещё короче с помощью 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")
}
}

Прочитать файл в строку — довольно частая операция, поэтому в стандартной библиотеке есть удобная функция fs::read_to_string: она открывает файл, создаёт новую String, читает в неё содержимое файла и возвращает её. Конечно, с fs::read_to_string не получилось бы объяснить всю обработку ошибок, поэтому сначала мы пошли длинным путём.

Где можно использовать оператор ?

Оператор ? можно использовать только в функциях, возвращаемый тип которых совместим со значением, к которому применяется ?. Ведь оператор ? досрочно возвращает значение из функции — так же, как выражение match из листинга 9-6. Там match работал со значением Result, а ветка досрочного выхода возвращала Err(e). Чтобы такой return был допустим, функция должна возвращать Result.

В листинге 9-10 посмотрим, какая будет ошибка, если использовать ? в функции main, возвращаемый тип которой несовместим с типом значения, к которому применяется ?.

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Этот код открывает файл, что может не сработать. Оператор ? стоит после значения Result, которое вернула File::open, но функция main возвращает (), а не Result. При компиляции получаем сообщение об ошибке:

$ 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

Ошибка говорит, что оператор ? можно использовать только в функции, которая возвращает Result, Option или другой тип, реализующий FromResidual.

Исправить это можно двумя способами. Первый — поменять возвращаемый тип функции на совместимый со значением, к которому применяется ?, если ничто этому не мешает. Второй — обработать Result<T, E> выражением match или одним из методов Result<T, E> так, как подходит в вашей ситуации.

В сообщении об ошибке упоминалось, что ? можно применять и к значениям Option<T>. Как и с Result, использовать ? с Option можно только в функции, которая возвращает Option. Ведёт себя оператор ? с Option<T> так же, как с Result<T, E>: если значение — None, в этом месте None досрочно возвращается из функции. Если Some — значение внутри Some становится результатом выражения, и функция продолжает работу. В листинге 9-11 пример функции, которая находит последний символ первой строки переданного текста.

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

Функция возвращает Option<char>, потому что символ там может быть, а может и не быть. Код берёт аргумент — строковый срез text — и вызывает у него метод lines, который возвращает итератор по строкам текста. Функции нужна первая строка, поэтому она вызывает у итератора next и получает первое значение. Если text — пустая строка, next вернёт None, и тогда ? сразу вернёт None из last_char_of_first_line. Если text не пустая, next вернёт значение Some со строковым срезом первой строки text.

? достаёт этот строковый срез, и у него можно вызвать chars, чтобы получить итератор по символам. Нам нужен последний символ первой строки, поэтому вызываем last — он возвращает последний элемент итератора. Это тоже Option, ведь первая строка может оказаться пустой: например, если text начинается с пустой строки, а символы есть на других строках, как в "\nhi". Если же последний символ в первой строке есть, он вернётся в варианте Some. Оператор ? посередине позволяет выразить эту логику кратко и уложить всю функцию в одну строку. Если бы ? нельзя было применять к Option, пришлось бы писать больше вызовов методов или выражение match.

Обратите внимание: ? можно применять к Result в функции, которая возвращает Result, и к Option в функции, которая возвращает Option, но смешивать их нельзя. Оператор ? не преобразует Result в Option и наоборот автоматически. Для этого есть методы — например, ok у Result или ok_or у Option, — с их помощью преобразование делают явно.

До сих пор все наши функции main возвращали (). Функция main особенная: это точка входа в исполняемую программу и точка выхода из неё, поэтому на её возвращаемый тип есть ограничения, чтобы программа вела себя как ожидается.

К счастью, main может возвращать и Result<(), E>. В листинге 9-12 — код из листинга 9-10, но возвращаемый тип main изменён на Result<(), Box<dyn Error>>, а в конце добавлено возвращаемое значение Ok(()). Теперь код скомпилируется.

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

Тип Box<dyn Error> — это трейт-объект; о них мы поговорим в разделе «Трейт-объекты: абстракция над общим поведением» главы 18. Пока можно читать Box<dyn Error> как «ошибка любого вида». Применять ? к Result в такой main можно, потому что тип ошибки Box<dyn Error> позволяет досрочно вернуть из функции любое значение Err. Хотя тело этой main возвращает только ошибки типа std::io::Error, благодаря Box<dyn Error> сигнатура останется правильной, даже если в тело main добавить код, возвращающий другие ошибки.

Когда main возвращает Result<(), E>, исполняемый файл завершается с кодом 0, если main вернула Ok(()), и с ненулевым кодом, если main вернула Err. Исполняемые файлы на C при завершении возвращают целые числа: программы, завершившиеся успешно, возвращают 0, а завершившиеся с ошибкой — какое-то другое число. Rust тоже возвращает из исполняемых файлов целые числа, чтобы соответствовать этому соглашению.

Функция main может возвращать любые типы, реализующие трейт std::process::Termination. В нём есть функция report, которая возвращает ExitCode. О том, как реализовать трейт Termination для своих типов, читайте в документации стандартной библиотеки.

Теперь, когда мы разобрали подробности вызова panic! и возврата Result, вернёмся к вопросу о том, как решить, что уместнее в том или ином случае.

Паниковать или не паниковать

Паниковать или не паниковать

Как же решить, когда вызывать panic!, а когда возвращать Result? Если код паникует, восстановиться уже нельзя. Можно вызывать panic! при любой ошибке, есть ли способ восстановиться или нет, — но тогда вы сами решаете за вызывающий код, что ситуация неисправима. А возвращая Result, вы даёте вызывающему коду выбор. Он может попробовать восстановиться так, как подходит в его ситуации, а может решить, что эта ошибка неисправима, вызвать panic! и тем самым превратить исправимую ошибку в неисправимую. Поэтому, если функция может не сработать, возвращать Result — хороший выбор по умолчанию.

В примерах, прототипах и тестах уместнее писать код, который паникует, а не возвращает Result. Разберёмся, почему, а потом обсудим ситуации, когда компилятор не может понять, что ошибка невозможна, а вы как человек — можете. В конце главы — общие рекомендации о том, когда паниковать в коде библиотеки.

Примеры, прототипы и тесты

Если вы пишете пример, иллюстрирующий какую-то идею, надёжная обработка ошибок может сделать его менее понятным. В примерах подразумевается, что вызов метода вроде unwrap, который может запаниковать, — это заглушка на месте той обработки ошибок, которую вы захотите сделать в своём приложении. А она может быть разной в зависимости от того, что делает остальной код.

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

Если в тесте не сработал вызов какого-то метода, весь тест должен провалиться, даже если этот метод — не то, что тестируется. Тест помечается как проваленный именно через panic!, так что вызов unwrap или expect — ровно то, что нужно.

Когда вы знаете больше компилятора

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

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

Мы создаём экземпляр IpAddr, разбирая строку, вписанную прямо в код. Мы видим, что 127.0.0.1 — корректный IP-адрес, поэтому expect здесь допустим. Но то, что строка задана в коде и корректна, не меняет возвращаемый тип метода parse: мы всё равно получаем Result, и компилятор всё равно заставит нас обработать Result так, будто Err возможен, — ему не хватает ума понять, что эта строка всегда будет корректным IP-адресом. Если бы строка с адресом приходила от пользователя, а не была вписана в программу, и ошибка была бы возможна, мы бы, конечно, обработали Result надёжнее. А упоминание в сообщении, что IP-адрес задан в коде, подскажет нам заменить expect на нормальную обработку ошибок, если когда-нибудь адрес придётся брать из другого источника.

Рекомендации по обработке ошибок

Пусть ваш код паникует, если он может оказаться в плохом состоянии. Здесь плохое состояние — это когда нарушено какое-то допущение, гарантия, договор или инвариант: например, в код переданы недопустимые, противоречивые или отсутствующие значения. И при этом выполняется хотя бы одно из условий:

• Плохое состояние неожиданно — в отличие от того, что время от времени наверняка будет случаться, вроде ввода пользователем данных в неправильном формате.
• Код после этой точки должен опираться на то, что плохого состояния нет, а не проверять проблему на каждом шагу.
• Нет хорошего способа выразить эту информацию в используемых типах. Что мы имеем в виду, разберём на примере в разделе «Состояния и поведение как типы» главы 18.

Если кто-то вызывает ваш код и передаёт бессмысленные значения, лучше по возможности вернуть ошибку, чтобы пользователь библиотеки сам решил, что делать. Но если продолжать работу небезопасно или вредно, лучше вызвать panic! и сообщить тому, кто пользуется вашей библиотекой, о баге в его коде, — чтобы он исправил его ещё на этапе разработки. Точно так же panic! часто уместен, если вы вызываете внешний код, который вам неподконтролен, и он возвращает некорректное состояние, исправить которое вы никак не можете.

А вот когда сбой ожидаем, лучше вернуть Result, чем вызывать panic!. Например, парсер получил некорректные данные или HTTP-запрос вернул статус, означающий, что вы превысили лимит запросов. В таких случаях Result показывает, что неудача — ожидаемая возможность, и решать, как её обработать, должен вызывающий код.

Если ваш код выполняет операцию, которая при недопустимых значениях может подвергнуть пользователя риску, код должен сначала проверить значения и запаниковать, если они недопустимы. В основном это нужно ради безопасности: работа с некорректными данными может открыть уязвимости. Именно поэтому стандартная библиотека вызывает panic! при попытке обратиться к памяти за пределами границ: доступ к памяти, которая не принадлежит текущей структуре данных, — распространённая проблема безопасности. У функций часто есть договоры (contracts): их поведение гарантировано, только если входные данные отвечают определённым требованиям. Паниковать при нарушении договора разумно: нарушение договора всегда означает баг на стороне вызывающего, и это не та ошибка, которую вызывающий код должен явно обрабатывать. Вызывающий код всё равно не может разумно восстановиться: исправлять нужно сам код, и сделать это должен программист, который его написал. Договор функции, особенно если его нарушение приводит к панике, стоит описывать в документации к её API.

Впрочем, если в каждой функции будет куча проверок на ошибки, код станет многословным и неприятным. К счастью, многие проверки за вас может сделать система типов Rust (то есть проверка типов, которую выполняет компилятор). Если параметр функции имеет определённый тип, можно спокойно писать логику, зная, что компилятор уже гарантировал корректность значения. Например, если у вас конкретный тип, а не Option, программа ожидает что-то, а не ничего. Тогда коду не нужно обрабатывать два случая для вариантов Some и None — только один, когда значение точно есть. Код, который попытается передать в вашу функцию «ничего», просто не скомпилируется, так что проверять этот случай во время выполнения не нужно. Другой пример — беззнаковый целочисленный тип вроде u32, который гарантирует, что параметр никогда не будет отрицательным.

Собственные типы для проверки значений

Разовьём идею о том, чтобы гарантировать корректность значения с помощью системы типов Rust, и посмотрим, как создать для проверки собственный тип. Вспомните игру из главы 2, где код просил пользователя угадать число от 1 до 100. Мы ни разу не проверили, что догадка пользователя лежит в этих пределах, прежде чем сравнивать её с загаданным числом, — проверили лишь, что она положительная. Последствия тут не страшные: вывод «Too high» или «Too low» всё равно будет верным. Но было бы полезно подсказывать пользователю, какие догадки допустимы, и по-разному реагировать на число вне диапазона и, скажем, на буквы вместо числа.

Можно, например, разбирать догадку не как u32, а как i32, чтобы допустить отрицательные числа, а затем добавить проверку, что число в диапазоне:

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: 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) {
            // --пропуск--
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Выражение if проверяет, не вышло ли значение за пределы диапазона, сообщает пользователю о проблеме и вызывает continue, чтобы начать следующую итерацию цикла и попросить новую догадку. После if можно сравнивать guess с загаданным числом, зная, что guess лежит между 1 и 100.

Но это не идеальное решение. Если программе абсолютно необходимо работать только со значениями от 1 до 100 и таких функций у неё много, повторять проверку в каждой функции утомительно (да и на производительности это может сказаться).

Вместо этого можно создать новый тип в отдельном модуле и поместить проверку в функцию, создающую экземпляр этого типа, — а не повторять проверку везде. Тогда функции смогут смело использовать новый тип в своих сигнатурах и доверять получаемым значениям. В листинге 9-13 показан один из способов определить тип Guess, экземпляр которого создаётся, только если функция new получила значение от 1 до 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
    }
}
}

Обратите внимание: этот код в src/guessing_game.rs предполагает, что в src/lib.rs добавлено объявление модуля mod guessing_game; — здесь мы его не показываем. В файле нового модуля мы определяем структуру Guess с полем value типа i32. В нём и будет храниться число.

Затем реализуем для Guess ассоциированную функцию new, которая создаёт значения Guess. Функция new принимает один параметр value типа i32 и возвращает Guess. Код в её теле проверяет, что value лежит между 1 и 100. Если проверка не пройдена, мы вызываем panic! — это сообщит программисту, пишущему вызывающий код, что у него баг, который нужно исправить: создание Guess со значением value вне диапазона нарушило бы договор, на который опирается Guess::new. Условия, при которых Guess::new может паниковать, стоит описать в её публичной документации к API; о соглашениях, как отмечать в документации возможность panic!, мы поговорим в главе 14. Если же проверка пройдена, мы создаём новый Guess, записываем в поле value параметр value и возвращаем Guess.

Дальше мы реализуем метод value, который заимствует self, не принимает других параметров и возвращает i32. Такие методы иногда называют геттерами: их задача — получить данные из полей и вернуть их. Этот публичный метод нужен потому, что поле value структуры Guess приватное. И важно, чтобы оно было приватным: тогда код, использующий структуру Guess, не сможет задать value напрямую. Код за пределами модуля guessing_game обязан создавать экземпляры Guess через функцию Guess::new, и значит, у Guess никак не может оказаться значения value, не прошедшего проверку в Guess::new.

Теперь функция, которая принимает или возвращает только числа от 1 до 100, может объявить в сигнатуре, что принимает или возвращает Guess, а не i32, и никаких дополнительных проверок в её теле не понадобится.

Итоги

Средства обработки ошибок в Rust помогают писать более надёжный код. Макрос panic! сигнализирует, что программа оказалась в состоянии, с которым не может справиться, и позволяет остановить процесс, а не продолжать работу с некорректными значениями. Перечисление Result с помощью системы типов показывает, что операции могут завершиться неудачей, от которой код может восстановиться. Возвращая Result, вы сообщаете вызывающему коду, что ему нужно обработать и успех, и возможную неудачу. Если использовать panic! и Result там, где они уместны, код станет надёжнее перед лицом неизбежных проблем.

Вы увидели, как стандартная библиотека с пользой применяет обобщения в перечислениях Option и Result. Теперь поговорим о том, как устроены обобщения и как пользоваться ими в своём коде.

Обобщённые типы, трейты и времена жизни

В любом языке программирования есть инструменты, которые помогают бороться с дублированием. В Rust один из таких инструментов — обобщения (generics): абстрактные заменители конкретных типов или других свойств. Мы можем описать поведение обобщений и их связь с другими обобщениями, не зная, что именно окажется на их месте при компиляции и запуске кода.

Функции могут принимать параметры не конкретного типа вроде i32 или String, а какого-то обобщённого — точно так же, как они принимают параметры с заранее неизвестными значениями, чтобы выполнять один и тот же код для разных значений. На самом деле обобщениями мы уже пользовались: в главе 6 — Option<T>, в главе 8 — Vec<T> и HashMap<K, V>, в главе 9 — Result<T, E>. В этой главе вы научитесь определять с помощью обобщений собственные типы, функции и методы!

Сначала мы вспомним, как вынести код в функцию, чтобы избавиться от дублирования. Затем тем же приёмом сделаем из двух функций, которые отличаются только типами параметров, одну обобщённую. Ещё мы объясним, как использовать обобщённые типы в определениях структур и перечислений.

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

И наконец, мы обсудим времена жизни (lifetimes) — разновидность обобщений, которая сообщает компилятору, как ссылки связаны друг с другом. Времена жизни позволяют дать компилятору достаточно сведений о заимствованных значениях, чтобы он мог убедиться в действительности ссылок в большем числе ситуаций, чем без нашей помощи.

Убираем дублирование, вынося код в функцию

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

Начнём с короткой программы из листинга 10-1, которая находит наибольшее число в списке.

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

Мы храним список целых чисел в переменной number_list и кладём ссылку на первое число списка в переменную largest. Затем перебираем все числа списка, и если текущее число больше того, на которое указывает largest, заменяем ссылку в этой переменной. Если же текущее число меньше или равно наибольшему из встреченных, переменная не меняется, и код переходит к следующему числу. Когда все числа перебраны, largest указывает на наибольшее — в нашем случае на 100.

Теперь нам поручили найти наибольшее число в двух разных списках. Можно скопировать код из листинга 10-1 и использовать ту же логику в двух местах программы, как в листинге 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}");
}

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

Чтобы избавиться от дублирования, создадим абстракцию — функцию, которая работает с любым списком целых чисел, переданным ей параметром. Так код станет понятнее, а идея «найти наибольшее число в списке» будет выражена абстрактно.

В листинге 10-3 мы выносим код поиска наибольшего числа в функцию largest. Затем вызываем её, чтобы найти наибольшее число в двух списках из листинга 10-2. Эту функцию можно будет применить и к любому другому списку значений i32, который может появиться в будущем.

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

У функции largest есть параметр list — любой конкретный срез значений i32, который мы можем передать в функцию. Поэтому при вызове функции код выполняется для тех конкретных значений, которые мы передали.

Подведём итог: чтобы превратить код из листинга 10-2 в код из листинга 10-3, мы сделали следующее:

1. Нашли повторяющийся код.
2. Перенесли повторяющийся код в тело функции, а в сигнатуре функции указали, что этот код принимает на вход и что возвращает.
3. Заменили оба места с повторяющимся кодом вызовами функции.

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

Допустим, у нас две функции: одна находит наибольший элемент в срезе значений i32, а другая — в срезе значений char. Как избавиться от такого дублирования? Давайте выясним!

Обобщённые типы данных

Обобщённые типы данных

С помощью обобщений мы создаём определения — например, сигнатуры функций или структуры, — которые потом можно использовать с множеством разных конкретных типов данных. Сначала посмотрим, как определять с обобщениями функции, структуры, перечисления и методы. А потом обсудим, как обобщения влияют на производительность кода.

В определениях функций

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

Продолжим с функцией largest. В листинге 10-4 две функции, каждая из которых находит наибольшее значение в срезе. Затем мы объединим их в одну обобщённую функцию.

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

Функция largest_i32 — та самая, что мы выделили в листинге 10-3: она находит наибольшее i32 в срезе. Функция largest_char находит наибольший char в срезе. Тела у функций одинаковые, так что избавимся от дублирования, введя в единственную функцию обобщённый параметр типа.

Чтобы параметризовать типы в новой функции, нужно дать имя параметру типа — так же, как мы даём имена параметрам-значениям. Именем параметра типа может быть любой идентификатор. Но мы возьмём T: по соглашению имена параметров типа в Rust короткие, часто из одной буквы, а типы в Rust называют в стиле UpperCamelCase. T — сокращение от type (тип), и большинство программистов на Rust выбирают именно его.

Когда мы используем параметр в теле функции, его имя нужно объявить в сигнатуре, чтобы компилятор знал, что оно означает. Точно так же, прежде чем использовать в сигнатуре имя параметра типа, его нужно объявить. Чтобы определить обобщённую функцию largest, объявления имён типов ставят в угловых скобках <> между именем функции и списком параметров:

fn largest<T>(list: &[T]) -> &T {

Читается это так: «функция largest обобщена по некоторому типу T». У неё один параметр list — срез значений типа T. Функция largest вернёт ссылку на значение того же типа T.

В листинге 10-5 — объединённое определение функции largest с обобщённым типом данных в сигнатуре. Там же показано, как вызывать функцию и со срезом значений i32, и со срезом значений char. Учтите, что этот код пока не компилируется.

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

Если скомпилировать этот код сейчас, получим ошибку:

$ 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

В подсказке упоминается std::cmp::PartialOrd — это трейт, о трейтах мы поговорим в следующем разделе. Пока достаточно понимать, что ошибка говорит: тело largest будет работать не со всеми типами, которыми может оказаться T. Мы хотим сравнивать в теле функции значения типа T, а значит, годятся только типы, значения которых можно упорядочить. Для сравнения в стандартной библиотеке есть трейт std::cmp::PartialOrd, который можно реализовать для типов (подробнее о нём — в приложении C). Чтобы исправить листинг 10-5, можно последовать подсказке и ограничить допустимые для T типы теми, что реализуют PartialOrd. Тогда код скомпилируется: стандартная библиотека реализует PartialOrd и для i32, и для char.

В определениях структур

Структуры тоже можно определять так, чтобы одно или несколько полей имели обобщённый тип, — с помощью того же синтаксиса <>. В листинге 10-6 определена структура Point<T>, которая хранит координаты x и y любого типа.

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

Синтаксис обобщений в определениях структур похож на синтаксис в определениях функций. Сначала объявляем имя параметра типа в угловых скобках сразу после имени структуры. Затем используем обобщённый тип в определении структуры там, где иначе указали бы конкретные типы данных.

Обратите внимание: раз в определении Point<T> только один обобщённый тип, это определение говорит, что структура Point<T> обобщена по некоторому типу T, и поля x и y — оба этого типа, каким бы он ни был. Если создать экземпляр Point<T> со значениями разных типов, как в листинге 10-7, код не скомпилируется.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

Присваивая x целое число 5, мы сообщаем компилятору, что для этого экземпляра Point<T> обобщённый тип T — целое число. А когда для y, которое по определению того же типа, что и x, мы указываем 4.0, получаем ошибку несовпадения типов:

$ 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

Чтобы определить структуру Point, где и x, и y обобщённые, но могут быть разных типов, можно использовать несколько обобщённых параметров типа. Например, в листинге 10-8 мы делаем Point обобщённой по типам T и U: x имеет тип T, а y — тип 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 };
}

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

В определениях перечислений

Как и структуры, перечисления можно определять так, чтобы их варианты хранили обобщённые типы данных. Ещё раз взглянем на перечисление Option<T> из стандартной библиотеки, которым мы пользовались в главе 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Теперь это определение должно быть вам понятнее. Перечисление Option<T> обобщено по типу T, и у него два варианта: Some, который хранит одно значение типа T, и None, который не хранит ничего. С помощью Option<T> можно выразить абстрактную идею необязательного значения, а раз Option<T> обобщённое, этой абстракцией можно пользоваться, какого бы типа ни было необязательное значение.

Перечисления тоже могут использовать несколько обобщённых типов. Пример — определение перечисления Result, которым мы пользовались в главе 9:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Перечисление Result обобщено по двум типам, T и E, и у него два варианта: Ok, который хранит значение типа T, и Err, который хранит значение типа E. Благодаря этому Result удобно использовать везде, где операция может завершиться успехом (вернуть значение некоторого типа T) или неудачей (вернуть ошибку некоторого типа E). Именно так мы открывали файл в листинге 9-3: при успешном открытии вместо T был тип std::fs::File, а при проблемах с открытием вместо E был тип std::io::Error.

Если вы замечаете в коде несколько определений структур или перечислений, которые отличаются только типами хранимых значений, дублирования можно избежать с помощью обобщённых типов.

В определениях методов

Для структур и перечислений можно реализовывать методы (как мы делали в главе 5) и использовать в их определениях обобщённые типы. В листинге 10-9 — структура Point<T> из листинга 10-6, для которой реализован метод x.

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

Здесь мы определили для Point<T> метод x, который возвращает ссылку на данные в поле x.

Обратите внимание: T нужно объявить сразу после impl, чтобы с его помощью указать, что мы реализуем методы для типа Point<T>. Объявив T обобщённым типом после impl, мы даём Rust понять, что тип в угловых скобках у Point — обобщённый, а не конкретный. Этому обобщённому параметру можно было дать и другое имя, не такое, как в определении структуры, но по соглашению имя используют то же. Метод, написанный внутри impl с объявленным обобщённым типом, будет определён для любого экземпляра типа — какой бы конкретный тип ни подставился вместо обобщённого.

Определяя методы для типа, можно также накладывать ограничения на обобщённые типы. Например, можно реализовать методы только для экземпляров Point<f32>, а не для Point<T> с любым обобщённым типом. В листинге 10-10 используется конкретный тип f32, поэтому после 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());
}

Этот код означает, что у типа Point<f32> будет метод distance_from_origin, а у остальных экземпляров Point<T>, где T — не f32, такого метода не будет. Метод вычисляет, насколько наша точка удалена от точки с координатами (0.0, 0.0), и использует математические операции, доступные только для типов с плавающей точкой.

Обобщённые параметры типа в определении структуры не всегда совпадают с теми, что используются в сигнатурах её методов. В листинге 10-11 для структуры Point используются обобщённые типы X1 и Y1, а для сигнатуры метода mixup — X2 и Y2, чтобы пример был нагляднее. Метод создаёт новый экземпляр Point, взяв значение x из Point в self (типа X1) и значение y из переданного Point (типа 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);
}

В main мы определили Point, у которой x — i32 (со значением 5), а y — f64 (со значением 10.4). Переменная p2 — структура Point, у которой x — строковый срез (со значением "Hello"), а y — char (со значением c). Вызов mixup у p1 с аргументом p2 даёт p3, у которой x будет i32, потому что x взят из p1, а y — char, потому что y взят из p2. Макрос println! выведет p3.x = 5, p3.y = c.

Этот пример показывает ситуацию, когда часть обобщённых параметров объявляется в impl, а часть — в определении метода. Здесь X1 и Y1 объявлены после impl, потому что относятся к определению структуры. А X2 и Y2 объявлены после fn mixup, потому что нужны только этому методу.

Производительность кода с обобщениями

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

Rust добивается этого с помощью мономорфизации кода с обобщениями при компиляции. Мономорфизация (monomorphization) — это превращение обобщённого кода в конкретный путём подстановки тех конкретных типов, которые используются при компиляции. При этом компилятор делает обратное тому, что мы делали, создавая обобщённую функцию в листинге 10-5: он смотрит на все места, где вызывается обобщённый код, и генерирует код для конкретных типов, с которыми его вызывают.

Посмотрим, как это работает, на примере обобщённого перечисления Option<T> из стандартной библиотеки:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Компилируя этот код, Rust выполняет мономорфизацию. Компилятор читает значения, использованные в экземплярах Option<T>, и находит два вида Option<T>: с i32 и с f64. Поэтому он разворачивает обобщённое определение Option<T> в два определения, специализированных для i32 и f64, и заменяет ими обобщённое.

Мономорфизированная версия кода выглядит примерно так (компилятор использует другие имена — эти мы взяли для наглядности):

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

Обобщённый Option<T> заменяется конкретными определениями, которые создал компилятор. Rust компилирует обобщённый код в код, где для каждого случая указан конкретный тип, поэтому за обобщения мы ничего не платим во время выполнения. Работающий код ведёт себя так же быстро, как если бы мы продублировали каждое определение вручную. Благодаря мономорфизации обобщения в Rust чрезвычайно эффективны во время выполнения.

Трейты: общее поведение

Трейты: общее поведение

Трейт (trait) описывает функциональность, которая может быть общей для нескольких типов. С помощью трейтов можно абстрактно описывать общее поведение. А с помощью ограничений трейтами (trait bounds) можно указать, что обобщённый тип — это любой тип с определённым поведением.

Определение трейта

Поведение типа — это методы, которые можно у него вызвать. Разные типы ведут себя одинаково, если у всех этих типов можно вызвать одни и те же методы. Определение трейта — способ собрать вместе сигнатуры методов и описать набор поведения, необходимый для какой-то цели.

Допустим, у нас есть несколько структур, хранящих текст разного вида и объёма: структура NewsArticle хранит новостную заметку из определённого места, а SocialPost — пост длиной не больше 280 символов плюс метаданные: новый ли это пост, репост или ответ на другой пост.

Мы хотим сделать библиотечный крейт aggregator — агрегатор медиа, который умеет показывать краткое изложение (summary) данных из экземпляра NewsArticle или SocialPost. Для этого от каждого типа нам нужно краткое изложение, и получать его мы будем, вызывая у экземпляра метод summarize. В листинге 10-12 определён публичный трейт Summary, который выражает это поведение.

pub trait Summary {
    fn summarize(&self) -> String;
}

Трейт объявляется ключевым словом trait и именем трейта — здесь Summary. Ещё мы объявляем трейт как pub, чтобы им могли пользоваться и крейты, которые зависят от нашего, — это мы увидим в паре примеров. В фигурных скобках объявляются сигнатуры методов, описывающие поведение типов, которые реализуют трейт, — в нашем случае fn summarize(&self) -> String.

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

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

Реализация трейта для типа

Мы определили нужные сигнатуры методов трейта Summary и теперь можем реализовать его для типов нашего агрегатора. В листинге 10-13 — реализация трейта Summary для структуры NewsArticle: метод summarize собирает возвращаемое значение из заголовка, автора и места. А для структуры SocialPost метод summarize возвращает имя пользователя и весь текст поста — считаем, что содержимое поста и так ограничено 280 символами.

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

Реализация трейта для типа похожа на реализацию обычных методов. Разница в том, что после impl пишется имя реализуемого трейта, затем ключевое слово for, а затем имя типа, для которого реализуется трейт. Внутри блока impl пишутся сигнатуры методов из определения трейта. Только вместо точки с запятой после каждой сигнатуры ставятся фигурные скобки, а в них — тело метода: то конкретное поведение, которое методы трейта должны иметь для этого типа.

Теперь, когда библиотека реализовала трейт Summary для NewsArticle и SocialPost, пользователи крейта могут вызывать методы трейта у экземпляров NewsArticle и SocialPost так же, как обычные методы. Единственное отличие: пользователю нужно подключить в область видимости не только типы, но и сам трейт. Вот пример того, как бинарный крейт мог бы использовать наш библиотечный крейт 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());
}

Этот код выведет 1 new post: horse_ebooks: of course, as you probably already know, people.

Другие крейты, зависящие от aggregator, тоже могут подключить трейт Summary и реализовать его для своих типов. Есть одно ограничение: реализовать трейт для типа можно, только если трейт, тип или оба они локальны для нашего крейта. Например, мы можем реализовать трейты стандартной библиотеки, вроде Display, для собственного типа вроде SocialPost в рамках крейта aggregator, потому что тип SocialPost локален для нашего крейта. Можем мы реализовать и Summary для Vec<T> в крейте aggregator, потому что локален трейт Summary.

А вот реализовать внешний трейт для внешнего типа нельзя. Например, нельзя в крейте aggregator реализовать трейт Display для Vec<T>: и Display, и Vec<T> определены в стандартной библиотеке и не локальны для нашего крейта. Это ограничение — часть свойства под названием согласованность (coherence), а конкретнее — так называемое правило сироты (orphan rule): реализация оказывается «сиротой», потому что ни трейт, ни тип не принадлежат нашему крейту. Это правило гарантирует, что чужой код не сломает ваш, и наоборот. Без него два крейта могли бы реализовать один и тот же трейт для одного и того же типа, и Rust не знал бы, какую реализацию использовать.

Реализации по умолчанию

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

В листинге 10-14 мы задаём для метода summarize трейта Summary строку по умолчанию, а не только сигнатуру, как в листинге 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)
    }
}

Чтобы экземпляры NewsArticle использовали реализацию по умолчанию, пишем пустой блок impl: impl Summary for NewsArticle {}.

Мы больше не определяем summarize для NewsArticle напрямую. Но у этого метода есть реализация по умолчанию, а NewsArticle, как мы указали, реализует трейт Summary. Поэтому метод summarize у экземпляра NewsArticle по-прежнему можно вызвать:

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

Этот код выведет New article available! (Read more...).

Появление реализации по умолчанию не требует ничего менять в реализации Summary для SocialPost из листинга 10-13. Дело в том, что синтаксис переопределения реализации по умолчанию такой же, как синтаксис реализации метода трейта, у которого реализации по умолчанию нет.

Реализации по умолчанию могут вызывать другие методы того же трейта, даже если у тех нет реализации по умолчанию. Так трейт может давать много полезной функциональности, требуя от реализующих типов лишь малую её часть. Например, можно определить в трейте Summary метод summarize_author, реализация которого обязательна, и метод summarize с реализацией по умолчанию, которая вызывает 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)
    }
}

Чтобы пользоваться такой версией Summary, при реализации трейта для типа достаточно определить 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)
    }
}

Определив summarize_author, можно вызывать summarize у экземпляров структуры SocialPost, и реализация summarize по умолчанию вызовет нашу реализацию summarize_author. Мы реализовали summarize_author — и трейт Summary дал нам поведение метода summarize без единой лишней строчки кода. Вот как это выглядит:

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

Этот код выведет 1 new post: (Read more from @horse_ebooks...).

Учтите: вызвать реализацию по умолчанию из переопределяющей реализации того же метода нельзя.

Трейты как параметры

Теперь, когда вы умеете определять и реализовывать трейты, посмотрим, как с их помощью определять функции, которые принимают значения множества разных типов. Воспользуемся трейтом Summary, который мы реализовали для типов NewsArticle и SocialPost в листинге 10-13, и определим функцию notify, которая вызывает метод summarize у своего параметра item — значения некоторого типа, реализующего трейт Summary. Для этого используется синтаксис impl Trait:

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

Вместо конкретного типа параметра item мы пишем ключевое слово impl и имя трейта. Такой параметр принимает любой тип, реализующий указанный трейт. В теле notify у item можно вызывать любые методы трейта Summary, например summarize. Вызвать notify можно с любым экземпляром NewsArticle или SocialPost. А код, который вызовет функцию с любым другим типом, например String или i32, не скомпилируется: эти типы не реализуют Summary.

Синтаксис ограничений трейтами

Синтаксис impl Trait хорош в простых случаях, но на самом деле это синтаксический сахар для более длинной формы — ограничения трейтом (trait bound). Выглядит она так:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

Эта длинная форма равнозначна примеру из предыдущего раздела, просто многословнее. Ограничения трейтами пишут вместе с объявлением обобщённого параметра типа — после двоеточия, внутри угловых скобок.

Синтаксис impl Trait удобен и в простых случаях даёт более лаконичный код, а полный синтаксис ограничений трейтами позволяет выразить более сложные вещи. Например, пусть у функции два параметра, реализующих Summary. С impl Trait это выглядит так:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

impl Trait подходит, если мы допускаем, что у item1 и item2 могут быть разные типы (лишь бы оба реализовывали Summary). А если мы хотим, чтобы оба параметра были одного типа, нужно ограничение трейтом:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

Обобщённый тип T, указанный типом обоих параметров item1 и item2, требует, чтобы значения, переданные аргументами в item1 и item2, были одного и того же конкретного типа.

Несколько ограничений через +

Ограничений трейтами можно указать несколько. Допустим, в notify мы хотим использовать для item и форматирование для вывода, и summarize: тогда в определении notify укажем, что item должен реализовывать и Display, и Summary. Делается это через +:

pub fn notify(item: &(impl Summary + Display)) {

+ работает и с ограничениями обобщённых типов:

pub fn notify<T: Summary + Display>(item: &T) {

С двумя ограничениями тело notify может и вызывать summarize, и форматировать item через {}.

Понятнее с where

У слишком большого числа ограничений трейтами есть недостатки. У каждого обобщения свои ограничения, поэтому в функциях с несколькими обобщёнными параметрами между именем функции и списком параметров может скопиться масса информации об ограничениях, и сигнатуру станет трудно читать. Поэтому в Rust есть альтернативный синтаксис: ограничения можно указать в конструкции where после сигнатуры функции. Вместо такого:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

можно написать так:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

Сигнатура этой функции не так загромождена: имя функции, список параметров и возвращаемый тип стоят рядом, как у функции без кучи ограничений трейтами.

Возврат типов, реализующих трейты

Синтаксис impl Trait можно использовать и на месте возвращаемого типа, чтобы вернуть значение некоторого типа, реализующего трейт:

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,
    }
}

Указав возвращаемым типом impl Summary, мы говорим, что функция returns_summarizable возвращает некий тип, реализующий трейт Summary, не называя конкретный тип. Здесь returns_summarizable возвращает SocialPost, но вызывающему коду знать об этом не нужно.

Возможность указать возвращаемый тип только через трейт, который он реализует, особенно полезна в контексте замыканий и итераторов — о них мы поговорим в главе 13. Замыкания и итераторы создают типы, которые знает только компилятор, или типы, которые очень долго выписывать. Синтаксис impl Trait позволяет коротко сказать, что функция возвращает некий тип, реализующий трейт Iterator, не выписывая очень длинный тип.

Но использовать impl Trait можно, только если возвращается один-единственный тип. Например, этот код, который возвращает либо NewsArticle, либо SocialPost, а возвращаемым типом указывает impl Summary, работать не будет:

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,
        }
    }
}

Возвращать то NewsArticle, то SocialPost нельзя из-за ограничений того, как синтаксис impl Trait реализован в компиляторе. Как написать функцию с таким поведением, мы разберём в разделе «Трейт-объекты: абстракция над общим поведением» главы 18.

Условная реализация методов с ограничениями трейтами

Если в блоке impl с обобщёнными параметрами типа использовать ограничения трейтами, можно реализовать методы условно — только для типов, реализующих указанные трейты. Например, у типа Pair<T> из листинга 10-15 функция new, возвращающая новый экземпляр Pair<T>, реализована всегда (напомним из раздела «Синтаксис методов» главы 5, что Self — псевдоним типа блока impl, в данном случае Pair<T>). А вот в следующем блоке impl метод cmp_display реализован для Pair<T>, только если внутренний тип T реализует трейт PartialOrd, позволяющий сравнивать, и трейт Display, позволяющий выводить.

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

Условно можно реализовать и трейт — для любого типа, который реализует другой трейт. Реализации трейта для любого типа, удовлетворяющего ограничениям, называются обобщёнными реализациями (blanket implementations), и в стандартной библиотеке Rust они используются повсеместно. Например, стандартная библиотека реализует трейт ToString для любого типа, который реализует трейт Display. Блок impl в стандартной библиотеке выглядит примерно так:

impl<T: Display> ToString for T {
    // --snip--
}

Благодаря этой обобщённой реализации у любого типа, реализующего Display, можно вызвать метод to_string из трейта ToString. Например, так можно превратить целое число в соответствующее значение String — ведь целые числа реализуют Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Обобщённые реализации перечислены в документации трейта в разделе «Implementors».

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

Проверка ссылок с помощью времён жизни

Проверка ссылок с помощью времён жизни

Времена жизни (lifetimes) — ещё одна разновидность обобщений, которой мы, сами того не зная, уже пользовались. Только они гарантируют не то, что у типа есть нужное нам поведение, а то, что ссылки остаются действительными столько, сколько они нам нужны.

В разделе «Ссылки и заимствование» главы 4 мы не упомянули одну деталь: у каждой ссылки в Rust есть время жизни — та область, в пределах которой ссылка действительна. Чаще всего времена жизни неявные и выводятся сами — так же, как чаще всего сами выводятся типы. Аннотировать типы приходится, только когда подходит сразу несколько. Точно так же и времена жизни приходится аннотировать, только когда времена жизни ссылок могут быть связаны между собой несколькими разными способами. В таких случаях Rust требует описать эту связь с помощью обобщённых параметров времени жизни — чтобы ссылки, которые реально используются во время работы программы, были гарантированно действительны.

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