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

от Стива Клабника, Кэрол Николс и Криса Кричо, при поддержке Сообщества Rust

Эта версия книги предполагает, что вы используете Rust 1.82.0 (выпущен 17.10.2024) или более позднюю версию. Смотрите раздел "Установка" Главы 1 чтобы установить или обновить Rust.

Оригинальная английская веб-версия доступна онлайн на https://doc.rust-lang.org/stable/book/ и оффлайн, если вы установили Rust с помощью rustup. Выполните команду rustup doc --book, чтобы открыть вашу локальную копию книги.

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

Эта книга (английский оригинал) также доступна в печатном и электронном формате в издательстве No Starch Press.

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

Предисловие

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

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

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

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

Однако возможности Rust не заканчиваются на системном программировании. Он достаточно выразителен и эргономичен, чтобы создавать консольные приложения, веб-серверы, и многое другое: вы найдёте прекрасные примеры далее в книге. Использование Rust позволит вам получить знания, которые пригодятся и в других областях. Например, вы можете изучить Rust, написав веб-приложение, а затем применить изученные идеи в работе с Raspberry Pi.

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

— Николас Матсакис и Аарон Турон

Введение

Примечание: эта редакция книги такая же, как и книга The Rust Programming Language, доступная в печати в электронном формате в издательстве No Starch Press.

Добро пожаловать в The Rust Programming Language — ознакомительную книгу о Rust. Язык программирования Rust поможет вам быстро писать более надёжное программное обеспечение. Высокоуровневая эргономика и низкоуровневый контроль часто становятся несовместимыми целями при разработке нового языка программирования. Rust бросает вызов этому противоречию. Балансируя между мощной технической выразительностью и простотой логики программ, Rust даёт вам возможность управлять низкоуровневыми деталями (например, использованием памяти) без хлопот, обычно ожидаемых от необходимости подобного контроля.

Кому Rust придётся по душе

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

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

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

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

• Cargo — встроенный менеджер зависимостей и инструмент сборки, делающий добавление,компиляцию и управление зависимостей безпроблемным и согласованным в рамках всей экосистемыRust.
• Rustfmt — инструмент форматирования, гарантирующий единообразие стиля программ, написанных разными людьми.
• rust-analyzer — средство интеграции в интегрированные среды разработки (IDE) автодополнения и отображения ошибок.

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

Учащиеся

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

Компании

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

Разработчики открытого программного обеспечения

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

Люди, ценящие скорость и устойчивость

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

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

Кому будет полезна эта книга

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

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

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

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

Глава 1 объясняет, как установить Rust, написать "Hello, world!" и использовать Cargo — пакетный менеджер и систему сборки Rust. Глава 2 — это практическое введение в написание программ на Rust, в рамках которого вы напишете игру в угадайку. В ней мы поверхностно рассмотрим самые основы, а в следующих частях мы будем изучать дополнительные детали. Если вы хотите сразу приступить к работе, вы можете начать прямо с Главы 2. Глава 3 раскроет тот функционал Rust, который вы привыкли видеть в других подобных языках программирования, а в Главе 4 вы изучите механизм владения. Если вы хотели бы сначала изучить теорию, то вы можете сначала прочесть Главу 3, а потом вернуться к Главе 2, когда захотите захотите поработать над проектом, применяя изученное.

В Главе 5 обсуждаются структуры и методы. Глава 6 охватывает перечисления, выражение match и конструкцию управления if let. Структуры и перечисления пригодятся вам для создания собственных типов данных.

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

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

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

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

В Главе 18 сравниваются широко известные идеи из парадигмы объектно-ориентированного программирования и аналогичные им реализации на Rust.

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

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

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

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

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

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

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

Исходный код

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

Начало

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

• Установку Rust на Linux, macOS и Windows
• Создание программы, печатающей Hello, world!
• Применение cargo — пакетного менеджера и системы сборки Rust

Установка

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

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

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

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

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

Установка 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] (https://www.rust-lang.org/tools/install) и выполните инструкцию по установке Rust. В какой-то момент установки, вам может понадобится установить Visual Studio. С ней вы получите компоновщик и библиотеки, необходимые для компиляции. Если на данном шаге вам нужна помощь, посетите [https://rust-lang.github.io/" "rustup/installation/windows-msvc.html](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 всё ещё не работает, есть несколько мест, где вам могут помочь. Вы можете найти площадки для общения с другими программистами на Rust на странице Сообщества.

Обновление и деинсталляция

Однажды установив Rust через rustup, вы можете легко его обновить. Откройте консоль и выполните следующую команду:

$ rustup update

Для удаления Rust и rustup запустите скрипт деинсталляции:

$ rustup self uninstall

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

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

Если вы встречаете тип или функцию, предоставляемые стандартной библиотекой, и не знаете, как их использовать, изучите их API в документации!

Текстовые редакторы и интегрированные среды разработки (IDE)

Эта книга не подразумевает использование какого-либо конкретного инструмента для разбработки на Rust. Вам будет достаточно даже лишь любого текстового редактора! Тем не менее, многие текстовые редакторы и IDE (integrated development environment) имеют встроенную поддержку Rust. Вы можете список различных редакторов и IDE на странице инструментов разработки.

Hello, World!

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

Примечание: эта книга предполагает некоторые базовые навыки работы с командной строкой. Rust предъявляет особых требований к вашему инструментарию или размещению кода, так что если вы предпочитаеле использовать IDE вместо командной строки — используйте любимую. Многие IDE в той или иной мере поддерживают Rust; подробности можете узнать в документации вашей IDE. Команда Rust поддерживает систему rust-analyzer, обеспечивающую превосходную поддержку Rust во многих IDE. Ищите подробности в Приложении D .

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

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

Откройте терминал и введите следующие команды, чтобы создать директорию "projects" и директорию для проекта "Hello, world!" внутри директории projects.

Для 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. Если вы используете больше одного слова в названии файла, следует отбивать слова друг от друга нижним подчёркиванием. Например, вместо helloworld.rs лучше напишите hello_world.rs.

Теперь откройте только что созданный файл main.rs и заполните его кодом из Листинга 1-1.

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

Сохраните файл и вернитесь к консоли. Убедитесь, что вы находитесь в директории ~/projects/hello_world. На Linux и macOS, введите следующие команды, чтобы скомпилировать и запустить файл:

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

На Windows, введите команду .\main.exe вместо ./main:

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

Независимо от вашей операционной системы, в консоли должна напечататься строка Hello, world!. Если этого не произошло, обратитесь к пункту "Решение проблем" раздела "Установка", чтобы найти возможное решение.

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

Устройство программы на Rust

Давайте детально рассмотрим нашу программу. Вот первая деталька пазла:

fn main() {

}

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

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

Примечание: Если вы хотите всюду соблюдать стандартный единообразный стиль, вы можете воспользоваться инструментом форматирования rustfmt. (больше о rustfmt можно узнать в Приложении D ). Это инструмент поставляется вместе с rustc, так что он должен быть уже на вашем компьютере!

Тело функции main содержит следующий код:

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

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

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

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

Third, we end the line with a semicolon (;), which indicates that this expression is over and the next one is ready to begin. Most lines of Rust code end with a semicolon.

Компилирование и исполнение — это разные шаги

Давайте рассмотрим каждый шаг процесса запуска программы.

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

$ rustc main.rs

If you have a C or C++ background, you’ll notice that this is similar to gcc or clang. After compiling successfully, Rust outputs a binary executable.

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

$ ls
main  main.rs

На Linux и macOS вы увидите два файла. На Windows вы увидите три. Если вы используете CMD на Windows, введите это:

> dir /B %= the /B option says to only show the file names =%
main.exe
main.pdb
main.rs

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

$ ./main # or .\main.exe on Windows

Если ваш main.rs содержит программу "Hello, world!", то исполняемый файл выведет Hello, world! в консоль.

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

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

Hello, Cargo!

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

Простейшие программы на Rust (вроде той, что мы написали), не имеют никаких зависимостей. Если бы мы использовали Cargo для сборки нашего проекта "Hello, world!", он использовал бы лишь тот функционал Cargo, который отвечает за сборку кода. По мере того, как вы будете писать всё более сложные программы на Rust, вы начнёте использовать зависимости; так что если вы будете во всех своих проектах использовать Cargo с самого начала, вам будет легче добавлять зависимости.

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

$ cargo --version

Если вы видите номер версии, то Cargo у вас есть! Если же видите ошибку, вроде command not found, обратитесь к документации вашего метода установки, чтобы узнать, как отдельно установить Cargo.

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

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

$ cargo new hello_cargo
$ cd hello_cargo

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

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

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

Примечание: По умолчанию, в качестве системы версионирования используется Git. Вы изменить cargo new и использовать другую систему версионирования (version control system) или вовсе отказаться от использования системы версионирования, используя флаг --vcs. Выполните cargo new --help, чтобы увидеть доступные варианты.

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

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

[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! Вообще, вся разница между нашим проектом и проектом, созданным Cargo, состоит лишь в том, что Cargo поместил код в директории src и создал конфигурационный файл Cargo.toml в корневой директории проекта.

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

Если вы создали свой проект без Cargo (например, как мы ранее сделали с проектом "Hello, world!"), вы можете преобразовать его в проект, использующий Cargo. Переместите код проекта в директорию src и создайте правильный файл 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 (или target\debug\hello_cargo.exe на Windows), а не корневой директории проекта. Поскольку по умолчанию используется сборка в режиме отладки (debug), Cargo положил бинарный файл в директорию под названием debug. Вы можете запустить исполняемый файл, написав в консоли:

$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!

Если всё хорошо, вы увидите Hello, world! в терминале. Запуск cargo build в первый раз приводит к появлению нового файла в директории проекта: 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 run.

Отметим, что в этот раз мы не увидели сообщений 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 позволит без больших трат времени убеждаться, что проект всё ещё компилируется! Поэтому, многие программисты на Rust периодически запускают cargo check по мере работы над программой. А cargo build применяется тогда, когда программа готова к использованию.

Повторим то, что мы узнали о Cargo:

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

Дополнительным преимуществом использования Cargo является то, что его команды будут одинаковы для любых операционных систем. Так что с этого моменты мы более не будем предоставлять инструкции, специфичные для Linux и macOS или Windows.

Создание релизной версии

Когда ваш проект наконец-то готов в релизу, вы можете использовать cargo build --release, чтобы собрать его с оптимизациями. Эта команда создаст исполняемый файл не в target/debug, а в target/release. Оптимизации делают ваш код на Rust более быстрым, но их включение также увеличивает время компиляции. Поэтому есть два профиля компиляции: один для разработки, когда вы хотите быстро и часто пересобирать проект; и другой, для сборки окончательной версии программы, которая будет распространяться среди конечных пользователей и которая потому должна работать предельно быстро. Если вы замеряете быстродействие своего кода, не забудьте собрать его через 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 = "2021"

[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.20s
     Running `target/debug/guessing_game`
Hello, world!

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

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

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

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

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

В этом коде много нового, так что давайте изучим его строчка за строчкой. Чтобы получить пользовательский ввод и затем (по возможности) напечатать его, нам нужно подключить библиотеку ввода-вывода io в область видимости. Библиотека io входит в стандартную библиотеку, также известную как std:

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

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

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

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

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

Новая функция объявляется ключевым словом fn. Пустые круглые скобки () обозначают, что эта функция не имеет параметов. Открывающая игурная скобка { определяет начало тела функции.

Как вы также узнали в Главе 1, println! — это макрос, печатающий строку на экран:

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

Этот код печатает фразы: сообщающую о сути игры и запрашивающую ввод от пользователя

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

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

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

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

let apples = 5;

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

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

Примечание: символы // обозначают начало комментария, продолжающегося до конца строки. Rust игнорирует весь текст в комментариях. Мы детальнее обсудим комментирование в Главе 3.

Вернёмся к программе игры в угадайку. Теперь вы знаете, что let mut guess создаёт изменяемую переменную guess. Знак равенства (=) говорит о том, что мы хотим связать что бы то ни было с данной переменной. Значение, с которым связывается переменная guess, располагается справа от знака равенства; оно является результатом вызова функции String::new — функции, возвращающей новое значение типа String. [String](https://doc.rust-lang.org/std/string/struct. String.html) — это тип строки, предоставляемый стандартной библиотекой. Он представляет собой строку текста переменной длины в кодировке 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!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

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

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

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

Обработка возможных ошибок с помощью Result

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

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

Мы могли бы переписать всю строку кода вот так:

io::stdin().read_line(&mut guess).expect("Не удалось прочесть ввод.");

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

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

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

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

Для значений типа Result реализовано несколько методов. Например — метод expect method. Если этот метод вызывается на Err, он вызовет сбой программы и выведет на экран сообщение, переданное ему как аргумент. (Если метод read_line возвращает Err, то скорее всего, произошла какая-то системная ошибка.) Если метод expect будет вызван на Ok, он вернёт значение, хранимое в 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)]` 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 предупреждает вас, что: 1) вы не используете значение типа Result, возвращаемое методом read_line, и 2) вы не обрабатываете возможную ошибку, с которой может завершиться вызов этого метода.

Правильный способ избавиться от таких предупреждений — это писать код с обработками ошибок. Однако, в нашем случае, мы хотим просто аварийно завершить нашу программу, если что-то пойдёт не так, поэтому использование expect допустимо. Больше об обработке ошибок вы узнаете в [Главе 9] (ch09-02-recoverable-errors-with-result.html).

Печать значений переменных с помощью меток подстановки println!

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

use std::io;

fn main() {
    println!("Угадайте число!");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {}", guess);
}

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

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

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

Этот код напечатает x = 5 и 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`
Угадайте число!
Введите свою догадку.
6
Вы предположили: 6

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

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

Далее! Нам нужно сгенерировать секретное число, которое пользователь и будет пытаться угадать. Секретное число должно быть разным от игры к игре, чтобы в неё действительно можно было играть. Мы будем использовать случайное число от 1 до 100, так что игра не будет сильно сложной. Функционал работы со случайными числами всё ещё не входит в стандартную библиотеку Rust, однако Команда Rust предоставляет крейт rand, реализующий всё нужное.

Использование крейтов для расширения возможностей

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

Управление внешними крейтами — это конёк Cargo. Чтобы получить возможность использовать крейт rand, нам нужно отредактировать файл Cargo.toml, чтобы включить этот крейт как зависимость. Откройте этот файл и добавьте строчки ниже в его конец (то есть под [dependencies] — заголовком раздела зависимостей). Убедитесь, что вы подключили версию rand ровно такую же, что и мы, иначе наши примеры могут не заработать у вас.

Файл: Cargo.toml

[dependencies]
rand = "0.8.5"

К разделам в файле Cargo.toml относится всё, что находится между заголовком раздела и заголовком следующего раздела. В [dependencies] вы указываете, какие внешние крейты каких версий требует ваш проект. В данном случае, мы конкретизируем версию крейта rand с помощью спецификатора 0.8.5. Cargo опирается на Семантическое версионирование (Semantic Versioning, SemVer) — систему записи версий программ. Спецификатор версии 0.8.5 на самом деле является сокращением для ^0.8.5, означающего любую версию программы не более раннюю, чем 0.8.5, но не более новую, чем 0.9.0.

Cargo рассчитывает, что версии, входящие в данный промежуток, имеют API, совместимый с API крейта версии 0.8.5. Это позволяет подключать более новые версии крейта, и при этом даёт гарантию, что приведённые в этой главе примеры будут компилироваться. Любая версия от 0.9.0 и выше не обязательно будет иметь такой же API, как используемый в примерах далее.

Теперь, ничего не меняя в программе, давайте соберём проект, как показано в Листинге 2-2.

$ cargo build
    Updating crates.io index
     Locking 16 packages to latest compatible versions
      Adding wasi v0.11.0+wasi-snapshot-preview1 (latest: v0.13.3+wasi-0.2.2)
      Adding zerocopy v0.7.35 (latest: v0.8.9)
      Adding zerocopy-derive v0.7.35 (latest: v0.8.9)
  Downloaded syn v2.0.87
  Downloaded 1 crate (278.1 KB) in 0.16s
   Compiling proc-macro2 v1.0.89
   Compiling unicode-ident v1.0.13
   Compiling libc v0.2.161
   Compiling cfg-if v1.0.0
   Compiling byteorder v1.5.0
   Compiling getrandom v0.2.15
   Compiling rand_core v0.6.4
   Compiling quote v1.0.37
   Compiling syn v2.0.87
   Compiling zerocopy-derive v0.7.35
   Compiling zerocopy v0.7.35
   Compiling ppv-lite86 v0.2.20
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.69s

Если вы проделаете всё на своей машине, вы можете увидеть другие (но всё ещё обратно совместимые; спасибо 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.lock

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

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

Обновление крейта до новейшей версии

Когда вы захотите обновить используемый крейт, вы можете воспользоваться комадой Cargo update. Она, игнорируя файл Cargo.lock, заново отыщет последние версии, подходящие вашим спецификациям в Cargo.toml. Cargo затем перепишет эти версии в файл Cargo.lock. В нашем случае, Cargo будет искать только те версии, что будут старше 0.8.5 и младше 0.9.0. Если rand получил две новые версии — 0.8.6 и 0.9.0, — то, запустив cargo update, вы увидите подобный вывод:

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

Cargo игнорирует релиз 0.9.0. Если вы посмотрите в файл Cargo.lock, вы также увидите, что используемая теперь версия крейта rand — 0.8.6. Чтобыц использовать версию 0.9.0 (или любую другую версию 0.9.x), вам нужно обновить файл Cargo.toml, чтобы он выглядел вот так:

[dependencies]
rand = "0.9.0"

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

Мы оставим подробности о [Cargo](https://rust-lang-translations.org/ cargo/) и [его экосистеме](https://rust-lang-translations.org/cargo/ reference/publishing.html) до Главы 14. Cargo делает переиспользование вашего кода другими людьми (и наоборот) значительно более простым, так что у программистов на Rust есть отличная возможность писать небольшие проекты, собранные на основе нескольких пакетов.

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

Применим rand для загадывания числа. Обновите файл src/main.rs, поместив в него код Листинга 2-3.

use std::io;
use rand::Rng;

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {guess}");
}

Во-первых, мы добавили строчку use rand::Rng;. Трейт Rng определяет методы, реализуемые генератором случайных чисел, так что чтобы использовать эти методы, этот трейт должен быть в области видимости. Трейты будут рассмотрены в Главе 10.

Во-вторых, мы добавили две строчки в середине. В первой строчке мы вызываем функцию rand::thread_rng, возвращающую нам генератор случайных чисел (локальный для текущего потока исполнения и запущенный операционной системой). Затем мы вызываем метод gen_range генератора случайных чисел. Этот метод определён трейтом Rng, который мы добавили в область видимости инструкцией use rand::Rng;. Метод gen_range принимает в качестве аргумента выражение диапазона значений и возвращает случайное число из этого диапазона. Использованное выражение диапазона значений имеет вид start..=end; оно включает в себя как нижнюю, так и верхнюю границы. Выражение 1..=100 тем самым означает, что нам требуется случайное число от 1 до 100, включая и 1, и 100.

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

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

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

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Угадайте число!
Загаданное число: 7
Введите свою догадку.
4
Вы предположили: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Угадайте число!
Загаданное число: 83
Введите свою догадку.
5
Вы предположили: 5

Вы должны увидеть разные случайные числа, и они должны быть в пределах от 1 до 100. Отличная работа!

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

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

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    // --код сокращён--
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Слишком маленькое!"),
        Ordering::Greater => println!("Слишком большое!"),
        Ordering::Equal => println!("Вы победили!"),
    }
}

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

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

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

Рассмотрим наш вышеприведённый пример с выражением 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.86
   Compiling getrandom v0.2.2
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.10
   Compiling rand_core v0.6.2
   Compiling rand_chacha v0.3.0
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
   --> src/main.rs:22:21
    |
22  |     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
   --> file:///home/.rustup/toolchains/1.82/lib/rustlib/src/rust/library/core/src/cmp.rs:838:8
    |
838 |     fn cmp(&self, other: &Self) -> Ordering;
    |        ^^^

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

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

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

Файл: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    // --код сокращён--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    let guess: u32 = guess.trim().parse().expect("Пожалуйста, введите число!");

    println!("Вы предположили: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Слишком маленькое!"),
        Ordering::Greater => println!("Слишком большое!"),
        Ordering::Equal => println!("Вы победили!"),
    }
}

... вот эту строчку:

let guess: u32 = guess.trim().parse().expect("Пожалуйста, введите число!");

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

Мы связываем эту новую переменную со значением выражения guess.trim().parse(). В нём, guess — это название уже ранее существующей переменной: нашей изначальной guess, содержащей ввод в виде строки. Метод trim, реализованный для экземпляров String, убирает начальные и конечные пробелы — нам нужно это сделать перед конвертацией строки в число типа u32 (целое, беззнаковое, 32-битное). Пользователь должен нажать Enter, чтобы read_line исполнился и считал введённую информацию. Однако считанная строка будет включать в себя символ начала новой строки. Например, если пользователь напечатает 5 и потом нажмёт Enter, guess будет выглядеть вот так: 5\n. \n — это обозначение для символа начала новой строки. (Стоит отметить, что на Windows нажатие Enter сопровождается возвратом каретки, и только потом символом начала новой строки, что всё вместе даёт \r\n.) Метод trim сможет убрать как \n, так и \r\n, и вернёт просто строку 5.

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

В добавок, аннотирование guess типом u32 и сравнение с secret_number позволяют Rust вывести, что secret_number тоже должна иметь тип u32. Теперь мы наконец-то сравниваем значения одинаковых типов!

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

Теперь запустим нашу программу:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Угадайте число!
Загаданное число: 58
Введите свою догадку.
  76
Вы предположили: 76
Слишком большое!

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

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

Возможность дать догадку не один раз с помощью циклов

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

Файл: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    // --код сокращён--

    println!("Загаданное число: {secret_number}");

    loop {
        println!("Введите свою догадку.");

        // --код сокращён--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Не удалось прочесть ввод.");

        let guess: u32 = guess.trim().parse().expect("Пожалуйста, введите число!");

        println!("Вы предположили: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Слишком маленькое!"),
            Ordering::Greater => println!("Слишком большое!"),
            Ordering::Equal => println!("Вы победили!"),
        }
    }
}

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

Пользователь, конечно, всегда может прервать исполнение программы сочетанием клавиш 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`
Угадайте число!
Загаданное число: 59
Введите свою догадку.
45
Вы предположили: 45
Слишком маленькое!
Введите свою догадку.
60
Вы предположили: 60
Слишком большое!
Введите свою догадку.
59
Вы предположили: 59
Вы победили!
Введите свою догадку.
quit
thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

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

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

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

Файл: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    loop {
        println!("Введите свою догадку.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Не удалось прочесть ввод.");

        let guess: u32 = guess.trim().parse().expect("Пожалуйста, введите число!");

        println!("Вы предположили: {guess}");

        // --код сокращён--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Слишком маленькое!"),
            Ordering::Greater => println!("Слишком большое!"),
            Ordering::Equal => {
                println!("Вы победили!");
                break;
            }
        }
    }
}

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

Обработка неправильного ввода

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

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    loop {
        println!("Введите свою догадку.");

        let mut guess = String::new();

        // --код сокращён--

        io::stdin()
            .read_line(&mut guess)
            .expect("Не удалось прочесть ввод.");

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

        println!("Вы предположили: {guess}");

        // --код сокращён--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Слишком маленькое!"),
            Ordering::Greater => println!("Слишком большое!"),
            Ordering::Equal => {
                println!("Вы победили!");
                break;
            }
        }
    }
}

We switch from an expect call to a match expression to move from crashing on an error to handling the error. Remember that parse returns a Result type and Result is an enum that has the variants Ok and Err. We’re using a match expression here, as we did with the Ordering result of the cmp method.

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

Если parse не сможет сделать из строки число, он вернёт значение Err, содержащее информацию об ошибке. Значение Err не сопоставится с шаблоном Ok(num) первой ветви match, но сопоставится с шаблоном 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`
Угадайте число!
Загаданное число: 61
Введите свою догадку.
10
Вы предположили: 10
Слишком маленькое!
Введите свою догадку.
99
Вы предположили: 99
Слишком большое!
Введите свою догадку.
foo
Введите свою догадку.
61
Вы предположили: 61
Вы победили!

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

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    loop {
        println!("Введите свою догадку.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Не удалось прочесть ввод.");

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

        println!("Вы предположили: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Слишком маленькое!"),
            Ordering::Greater => println!("Слишком большое!"),
            Ordering::Equal => {
                println!("Вы победили!");
                break;
            }
        }
    }
}

Игра готова. Хорошая работа, поздравляем!

Подведём итоги

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

Общие понятия программирования

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

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

Ключевые слова

В Rust, как и в любом другом языке, определён набор ключевых слов — слов, выделенных специально для записи конструкций языка. Помните, что вы не можете использовать их в качестве имён переменных или функций. Многие ключевые слова имеют более одного случая применения; вы будете их использовать для множества разных задач в Rust. Некоторые ключевые слова не имеют никакой функциональности — они зарезервированы для возможностей, которые могут быть добавлены в Rust в будущем. Вы можете найти список ключевых слов в Приложении А.

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

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

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

Затем, в вашей новой директории variables, откройте src/main.rs и замените его код тем, что ниже (пока что он не будет компилироваться):

Файл: src/main.rs

fn main() {
    let x = 5;
    println!("Значение x: {x}");
    x = 6;
    println!("Значение x: {x}");
}

Save and run the program using cargo run. You should receive an error message regarding an immutability error, as shown in this output:

$ 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!("Значение x: {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

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

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

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

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

Например, давайте поменяем src/main.rs вот так:

Файл: src/main.rs

fn main() {
    let mut x = 5;
    println!("Значение x: {x}");
    x = 6;
    println!("Значение x: {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`
Значение x: 5
Значение x: 6

Мы смогли поменять значение, связанное с x, с 5 на 6, поскольку использовали mut. В конечном счёте, вопрос об использовании изменяемости остаётся за вами и определяется тем, какое решение, по вашему мнению, будет чище.

Константы

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

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

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

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

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

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

The constant’s name is THREE_HOURS_IN_SECONDS and its value is set to the result of multiplying 60 (the number of seconds in a minute) by 60 (the number of minutes in an hour) by 3 (the number of hours we want to count in this program). Rust’s naming convention for constants is to use all uppercase with underscores between words. The compiler is able to evaluate a limited set of operations at compile time, which lets us choose to write out this value in a way that’s easier to understand and verify, rather than setting this constant to the value 10,800. See the Rust Reference’s section on constant evaluation for more information on what operations can be used when declaring constants.

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

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

Затенение

Как вы увидели в Главе 2 ,вы можете объявить новую переменную с тем же именем, которое носит уже существующая переменная. Считается, что старая переменная затеняется новой, что означает, что при использовании данного имени компилятор будет искать значение именно в новой переменной. Старая переменная не будет видна до тех пор, пока не закончится область видимости новой. Кроме того, затеняющая переменная сама может быть затенённой. Мы можем затенить переменную, использовав её же имя и повторно использовав его с ключевым словом let; вот так:

Файл: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("Значение x во внутренней области видимости: {x}");
    }

    println!("Значение x: {x}");
}

Сначала, эта программа связывает x со значением 5. Затем она создаёт новую переменную x, повторно используя конструкцию let x =, присваивая нового 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`
Значение x во внутренней области видимости: 12
Значение x: 6

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

Другим отличием между mut и затенением является то, что поскольку мы, по сути, создаём новую переменную (поскольку используем ключевое слово let), мы можем поменять тип значения, но использовать то же самое имя для связанной с ним переменной. Например, допустим, наша программа спрашивает пользователя, скольким количеством пробелов пользователь хочет отбить некоторый текст, и просит для этого у пользователя непосредственно нужные несколько знаков пробела. Мы можем сохранить количество введённых пробелов в виде числа вот таким образом:

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

Первая переменная spaces имеет строковый тип, а вторая переменная 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 — язык со статической типизацией. Это означает, что типы всех переменных должны быть известны уже на этапе компиляции. Компилятор обычно может самостоятельно вывести тип переменной, основываясь на её значении и том, как она используется. В тех случаях, когда компилятор не может вывести конкретный тип (например, как в том случае, когда мы преобразовывали String к численному типу данных методом parse в разделе "Сравнение догадки с загаданным числом" Главы 2), мы должны явно аннотировать тип; вот так:

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Не число!");
}

Если мы не добавим аннотацию типа (: 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("Не число!");
  |         ^^^^^        ----- 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("Не число!");
  |              ++++++++++++

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

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

Каждый знаковый тип может хранить значения от −(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 — обращение к элементам коллекции по индексу.

Целочисленное переполнение

Допустим, у вас есть переменная типа u8, которая может принимать значения от 0 до 255. Если вы попытаетесь приписать этой переменной значение за этими пределами (например, 270), произойдёт целочисленное переполнение, которое может привести к двум различным ситуациям. Если вы скомпилировали программу в режиме отладки, Rust включил в неё проверки на целочисленное переполнение, которые вызовут панику, если переполнение произойдёт. В Rust под термином паника понимается завершение программы с ошибкой. Больше о панике мы поговорим в разделе "Неустранимые ошибки с panic!" Главы 9.

Когда вы компилируете программу в релизном режиме (используя флаг --release), Rust не включает проверки на целочисленное переполнение и не вызывает паники в его случае. Вместо этого, Rust выполняет обращение по модулю. Кратко говоря, значения, превышающие максимальное значение типа, "оборачиваются" по модулю до числа, которое будет находиться в пределах типа. В случае типа u8, значение 256 станет 0, значение 257 станет 1, и так далее. Программа не вызовет панику, но в переменной будет сохранено не то значение, которое вы, скорее всего, ожидаете. Полагаться на обращение переполнения по модулю считается ошибкой.

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

• Методы wrapping_* (например, wrapping_add) обратят переполнение по модулю — как в релизном режиме, так и в режиме отладки.
• Методы checked_* вернут значение None, если произойдёт переполнение.
• Методы overflowing_* вернут число и логическое значение, сообщающее о том, произошло ли переполнение.
• Методы saturating_* вернут минимальное или максимальное значение типа (в зависимости от того, меньше ли переполнение, чем минимум типа, или переполнение больше, чем максимум).

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

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

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

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

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

Файл: src/main.rs

fn main() {
    let t = true;

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

Основным местом, где используются логические значения, являются условные выражения, вроде выражения if. Мы расскажем о том, как раюотают выражения if, в разделе "Управление потоком".

Тип символа

Тип char — это простейший тип, реализующий символ. Вот несколько примеров объявления значений типа char:

Файл: src/main.rs

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

Обратите внимание, что мы заключаем литерал char в одиночные кавычки, тогда как строки обрамляются двойными кавычками. Тип char занимает в памяти четыре байта и представляет собой символ Unicode, то есть он может представлять значительно больше символов, чем ASCII. Диакритические знаки, китайские иероглифы, японские кандзи, катакану и хирагану, корейский хангыль, эмодзи, пробелы нулевой ширины — всё это допустимые значения типа char в Rust. Символы Unicode принадлежат промежутку от U+0000 до U+D7FF и от U+E000 до U+10FFFF включительно. Однако, как такового, понятия "символ" в Unicode нет, так что ваше интуитивное представление о том, что такое "символ", может не соответствовать тому, чем может являться значение типа char. Мы обсудим это подробнее в разделе "Хранение текста в кодировке UTF-8 с помощью строк" Главы 8.

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

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

Тип кортежа

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

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

Файл: 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!("Значение y: {y}");
}

Эта программа создаёт кортеж и связывает с ним переменную tup. Затем она использует let и применяет шаблон, чтобы извлечь из tup три отдельных переменных: x, y и z. Это называется деструктуризацией, поскольку разбивает единый кортеж на три части. Наконец, программа печатает значение 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 и затем получает каждый его элемент, используя обращение по индексу. Как и в большинстве языков программирования, индексация начинается с нуля.

Кортеж без элементов — особенный, он называется unit. Значение этого типа записывается так же, как и сам тип: (). Unit представляет собой отсутствие значения или отсутствие возвращаемого значения. Выражения неявно возвращают unit, если не возвращают что-либо другое.

Тип массива

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

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

Файл: src/main.rs

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

Массивы нужны тогда, когда вам необходимо разместить некоторые данные на стеке (подобно типам, рассмотренным нами ранее), а не в куче (кучу и стек мы обсудим подробнее в Главе 4), или когда вам нужно точно быть уверенным, что количество элементов строго постоянно. Более гибким типом, чем массив, является вектор. Вектор — это похожий на массив тип коллекции данных, предоставляемый стандартной библиотекой. Вектор можно сокращать или удлинять. Если вы сомневаетесь, что использовать: массив или вектор, возможно, вам нужен вектор. Векторы будут рассмотрены подробнее в Главе 8.

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

#![allow(unused)]
fn main() {
let months = ["Январь", "Февраль", "Март", "Апрель", "Май", "Июнь", "Июль",
              "Август", "Сентябрь", "Октябрь", "Ноябрь", "Декабрь"];
}

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

#![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!("Пожалуйста, введите индекс элемента массива.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Не удалось прочесть ввод.");

    let index: usize = index
        .trim()
        .parse()
        .expect("Введено не число");

    let element = a[index];

    println!("Значение элемента массива по индексу {index}: {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!("Другая функция.");
}

Функция в 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!
Другая функция.

Выражения исполняются в том порядке, в каком они записаны в функции main. Первым печатается сообщение "Hello, world!", и только потом вызывается another_function и печатается её сообщение.

Параметры

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

Добавим функции another_function параметр:

Файл: src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("Значение x: {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`
Значение x: 5

Функция another_function имеет один параметр под названием x. Тип x определён как i32. Когда мы вызываем функцию another_function с аргументом 5, макрос println! принимает переменную x нашей функции и помещает вместо неё её значение 5 на место метки подстановки.

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

Чтобы определить функцию с несколькими параметрами, разделите их запятыми; вот так:

Файл: src/main.rs

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

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("Физическая величина: {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`
Физическая величина: 5ч

Поскольку мы вызвали функцию с аргументами 5 и 'ч' (соответственно параметрам value и unit_label), вывод программы содержит эти значения.

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

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

• Инструкция — это некоторое действие; она не возвращает значение.
• Выражение — это последовательность вычислений, производящая некоторое значение.

На самом деле, мы уже использовали инструкции и выражения. Создание переменной и приписывание ей значения с помощью ключегового слова 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)]` 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 не с чем связывать. Это отличается от того, что обычно происходит в других языках, вроде C или Ruby: в них присвоение значения возвращает присвоенное значение. В таких языках возможны конструкции вроде x = y = 6: переменной y будет присвоена 6, и это присвоение само по себе вернёт ту же 6 и присвоит её переменной x. В Rust такое сделать не выйдет.

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

Файл: src/main.rs

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

    println!("Значение y: {y}");
}

Это выражение ...

{
    let x = 3;
    x + 1
}

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

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

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

Файл: src/main.rs

fn five() -> i32 {
    5
}

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

    println!("Значение x: {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`
Значение x: 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!("Значение x: {x}");
}

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

Запуск этого кода напечатает Значение x: 6. Но есть мы поставим точку с запятой в конце строки x + 1 (превратив её тем самым из выражения в инструкцию), мы получим ошибку:

Файл: src/main.rs

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

    println!("Значение x: {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, но инструкция ни во что не вычисляется, что выражается возвращением типа () — unit. Следовательно, функции нечего возвращать, и это противоречит её определению, что и вызывает ошибку компиляции. В выводе выше, 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. В нём мы будем изучать выражение if. Заполните файл src/main.rs этим кодом:

Файл: src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("условие оказалось истинно");
    } else {
        println!("условие оказалось ложно");
    }
}

Все выражения if состоят с ключевого слова if и следующего за ним условия. В нашем случае, условие проверяет, меньше ли, чем 5, переменная number. В фигурных скобках, сразу после условия, мы размещаем код, который надо исполнить, если условие истинно. Блоки кода, связанные с условиями в выражениях if, иногда называются ветвями — аналогично ветвям в выражении match, которое мы обсуждали в разделе ["Сравнение догадки с загаданным числом"] (ch02-00-guessing-game-tutorial.html#Сравнение-догадки-с-загаданным-числом) Главы 2.

Это не обязательно, но мы можем добавить выражение else, которое указывает на код, который нужно запустить в случае, если условие оказалось ложным. Если вы не напишете выражение 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`
условие оказалось истинно

Изменим значение number на значение, которое сделает условие ложным:

fn main() {
    let number = 7;

    if number < 5 {
        println!("условие оказалось истинно");
    } else {
        println!("условие оказалось ложно");
    }
}

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

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
условие оказалось ложным

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

Файл: src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("number было тройкой");
    }
}

Условие при 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 условие, являющееся выражением, которое вычисляется в логическое значение. Если вы хотите запустить блок кода только если number не равно 0, нужно предоставить выражению if вот такое условие:

Файл: src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number оказалось не равно нулю");
    }
}

Запустив этот код, вы увидите текст number оказалось не равно нулю.

Обработка нескольких условий с помощью else if

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

Файл: src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("number делится на 4");
    } else if number % 3 == 0 {
        println!("number делится на 3");
    } else if number % 2 == 0 {
        println!("number делится на 2");
    } else {
        println!("number не делится ни на 4, ни на 3, ни на 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 делится 3

В этой программе происходит поочерёдная проверка каждого выражения if. Как только программа встретит условие, вычисляющееся в true, исполнится соответствующий блок кода. Обратите внимание, что хотя 6 делится на 2, мы не видим ни number делится на 2 (сообщение предпоследней ветви), ни number не делится ни на 4, ни на 3, ни на 2 (сообщение ветви else). Причина в том, что на первом же истинном условии проверка и останавливается — идущие далее условия не проверяются.

Использование большого количества выражений else if — верный способ сделать свой код запутанным и непонятным. Если вы используете больше одного такого оператора, возможно, вашей программе нужен рефакторинг. Глава 6 расскажет вам об операторе ветвления match, который отлично подойдёт для подобных случаев.

Использование if в инструкции let

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

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

    println!("Значение number: {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`
Значение number: 5

Помните, что 1) блоки кода вычисляются в значение последнего их выражения и 2) числа сами по себе тоже являются выражениями. В нашем случае, значение всего выражения if зависит от того, какой исполнится блок кода. Из этого следует, что значение каждого блока кода должно иметь один и тот же тип. В Листинге 3-2 всё имеенно так: обе ветви if и ветвь else вычисляются в целое число типа i32. Если ветви будут вычисляться в значения разных типов (как показано в примере ниже), вы получите ошибку:

Файл: src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "шесть" };

    println!("Значение number: {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 { "шесть" };
  |                                 -          ^^^^^^^ 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 — в строку. Такое недопустимо, поскольку типы переменных должны быть постоянны и известны уже на этапе компиляции. Компилятор должен знать тип number, чтобы иметь возможность проверить, корректно ли мы применяем переменную number дальше в программе. Поддержка неопределённости типов сделала бы компилятор Rust значительно более сложным, лишила бы нас многих гарантий формальной корректности кода, и позволила бы писать крайне запутанные программы — даже когда мы того не хотим.

Повторное исполнение кода с помощью циклов

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

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

Повторение кода с помощью loop

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

Замените код в файле src/main.rs в директории loops на код из примера ниже:

Файл: src/main.rs

fn main() {
    loop {
        println!("и ещё раз,");
    }
}

Запустив эту программу, мы увидим строку и ещё раз,, одну за другой, бесконечно. Мы можем остановить это, вручную прервав исполнение программы. Большинство консолей поддерживают сочетание клавиш 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`
и ещё раз,
и ещё раз,
и ещё раз,
и ещё раз,
^Cи ещё раз,

Символ ^C означает, что вы нажали Ctrl-C. Возможно, вы не увидите строчку и ещё раз, после ^C — всё зависит от того, в какой момент программа воспримет сигнал остановки.

Естественно, в Rust есть способ программно выйти из цикла. Если вы напишете ключевое слово break внутри цикла, то когда исполнение до него дойдёт, цикл завершится. К слову, мы уже его использовали: вспомните, как мы реализовали "Завершение игры после правильной догадки" в нашей игре в угадайку из Главы 2.

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

Вычисление циклов в значения

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

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

    println!("result равна {result}");
}

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

Вы также можете использовать в цикле ключевое слово return. В отличие от break (которое завершит исполнение только своего цикла), return завершит исполнение сразу всей функции.

Указание на конкретный цикл с помощью меток циклов

Если вы работаете во вложенных циклах, break и continue будут относиться только к тому циклу, в которых они написаны. При необходимости вы можете уточнить, с каким из вложенных циклов они должны работать, написав метку цикла после 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!("Окончательное значение 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
Окончательное значение count = 2

Условные циклы с while

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

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

    println!("ПОЕХАЛИ!!!");
}

Эта конструкция серьёзно облегчает создание циклов с условием остановки: код получается проще и чище. Пока условие вычисляется в true, код запускается; иначе, цикл прерывается.

Перебор элементов коллекции с for

Вы также можете использовать конструкцию while, чтобы пройтись по элементам коллекций (например, массива). Например, цикл в Листинге 3-4 напечатает каждый элемент массива a.

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

    while index < 5 {
        println!("элемент: {}", a[index]);

        index += 1;
    }
}

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

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
элемент: 10
элемент: 20
элемент: 30
элемент: 40
элемент: 50

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

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

Более лакончиным способом перебрать элементы коллекции является цикл for. Пример цикла for приведён в Листинге 3-5.

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

    for element in a {
        println!("элемент: {element}");
    }
}

Запустив этот код, мы увидим тот же вывод, что и в случае Листинга 3-4. Но куда более важно то, что мы повысили надёжность нашего кода, избавив его от возможных ошибок, связанных как с попытками получить элемент за пределами массива, так и с преждевременной остановкой перебора.

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

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

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

Файл: src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("ПОЕХАЛИ!!!");
}

Этот код чуть приятнее; не так ли?

Подведём итоги

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

• Конвертер температур из градусов Фаренгейта в Цельсия (и наоборот).
• Функция генерации _n_ого числа Фибоначчи.
• Программа, печатающая текст рождественской английской народной песни "The Twelve Days of Christmas".

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

Понимание владения

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

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

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

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

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

Стек и куча

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

И стек, и куча — это участки памяти, доступные вашей программе для использования, однако устроены они по-разному. Стек хранит значения в порядке их добавления и удаляет их в обратном. Это называется принципом "первым вошёл — последним вышел". Думайте о стеке как о стопке тарелок: если вы добавляете больше тарелок, вы ставите их наверх; когда вам нужно взять тарелку, вы берёте её сверху. Добавить или убрать тарелку снизу или из середины не выйдет! Помещение данных в стек называется push, а извлечение — pop. Всё, что хранится на стеке, должно иметь постоянный и известный размер. Если же для ваших данных нельзя узнать длину до компиляции, или если их размер может поменяться, следует воспользоваться кучей.

Куча менее организована: когда вы помещаете данные в кучу, вы получаете немного места в ней и туда размещаете свои данные. Распределитель памяти (синоним: "аллокатор") ищет в памяти свободное место достаточного размера, помечает его как задействованное вашей программой, и возвращает вам указатель на этот участок памяти. Этот процесс называется аллокацией памяти в куче или просто аллокацией (примечание: размещение данных в стеке не считается аллокацией). Поскольку указатель на кучу имеет известный и постоянный размер, вы можете хранить его на стеке; но если вам потребуются непосредственно данные, вам нужно будет обратиться по указателю. Думайте об этом как о порядке рассадки в ресторане: когда вы входите, вы сообщаете о том, сколько человек в вашей группе, и официант ищет для вас столик подходящего размера; если же кто-то из вашей группы опаздывает, вы сообщаете ему, где вас разместили.

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

Доступ к данным в куче медленнее, чем к данным на стеке, поскольку вам нужно сначала отыскать нужный участок памяти по указателю. Современные процессоры работают быстрее, если не нагружать их частыми обращениями к памяти. Продолжая аналогию с ресторанами: подумайте о приёме официантом заказов посетителей. Эффективнее всего будет взять все заказы с одного столика перед тем, как идти к следующему. Если же пытаться взять заказ у столика A, потом у столика B, потом снова у A, а потом ещё раз у B... Это будет значительно медленнее. Точно так же процессору легче и быстрее выполнить свою работу, если необходимые данные будут лежать рядом (как на стеке), а не разрозненно по всей памяти (как в куче).

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

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

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

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

• Каждое значение в Rust имеет владельца.
• В один момент у значения может быть только один владелец.
• Когда владелец покидает свою область видимости, значение высвобождается.

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

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

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

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

Переменная s связана с литералом строки, записанным непосредственно в коде нашей программы. Переменная действительна с тех пор, как она объявлена, и до конца её области видимости. Листинг 4-1 содержит программу с комментариями о действительности переменной в разные моменты.

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, его реализация запрашивает необходимую память. Такое довольно знакомо многим языкам программирования.

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

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

fn main() {
    {
        let s = String::from("hello"); // отсюда и далее s действительна

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

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

Примечание: В C++ этот шаблон освобождения ресурсов в конце времени жизни данных иногда называется "Получение ресурса есть инициализация" (Resource Acquisition Is Initialization — RAII). Функция drop в Rust покажется вам знакомой, если вы использовали шаблоны RAII.

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

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

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

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 также копировал данные кучи. Если бы Rust делал это, операция s2 = s1 могла бы быть очень дорогой с точки зрения производительности исполнения, если бы копируемые данные в куче были большими.

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

Ранее мы сказали, что когда переменная выходит за пределы области видимости, Rust автоматически вызывает функцию drop и очищает память данной переменной, выделенную в куче. Но на Рисунке 4-2 оба указателя данных указывают на одно и то же место. Это проблема: когда переменные s2 и s1 будут выходить из области видимости, они обе будут пытаться освободить одну и ту же память. Это известно как ошибка двойного освобождения — она является одной из ошибок безопасности памяти, упоминаемых ранее. Повторное свобождение памяти может привести к повреждению памяти, что потенциально может привести к уязвимостям.

Чтобы обеспечить безопасность памяти, после строки let s2 = s1; Rust считает s1 более не инициализированной. Следовательно, Rust не нужно ничего освобождать, когда s1 выходит из области видимости. Посмотрите, что произойдёт, если вы попытаетесь использовать 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:15
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, world!");
  |               ^^^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

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

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

Рисунок 4-4: Вид памяти после того, как s1 была деинициализирована

Это решает нашу проблему! Действительной остаётся только переменная s2. Когда она покинет область видимости, то лишь она одна будет освобождать память в куче.

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

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

The inverse of this is true for the relationship between scoping, ownership, and memory being freed via the drop function as well. When you assign a completely new value to an existing variable, Rust will call drop and free the original value’s memory immediately. Consider this code, for example:

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

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

Сначала мы объявляем переменную s и связываем её со значением "hello" типа String. Затем мы немедленно создаем новую строку типа String со значением "ahoy" и присваиваем её переменной s. После этого ничто больше не ссылается на изначальные данные в куче.

Рисунок 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, вы сразу можете понять, что исполняемый здесь некоторый код наверняка будет затратным. В то же время, использование 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. Вот некоторые типы, которые реализуют 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 перемещается в функцию...
                                    // ... а потому оно здесь больше не доступно

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

    makes_copy(x);                  // поскольку i32 реализует трейт Copy,
                                    // x НЕ переместится в функцию,
    println!("{}", 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("твоё"); // some_string входит в область видимости

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

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

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

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

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

Rust позволяет нам возвращать из функции несколько значений, используя кортеж, как показано в Листинге 4-5.

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

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

    println!("Длина '{s2}' равна {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() возвращает длину String

    (s, length)
}

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

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

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

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

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

    let len = calculate_length(&s1);

    println!("Длина '{s1}' равна {len}.");
}

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

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

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

Примечание: Противоположностью взятия ссылки с оператором & является разыменование, выполняемое с помощью оператора разыменования *. Мы увидим некоторые варианты использования оператора разыменования в Главе 8 и обсудим детали этого процесса в Главе 15.

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

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

    let len = calculate_length(&s1);

    println!("Длина '{s1}' равна {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!("Длина '{s1}' равна {len}.");
}

fn calculate_length(s: &String) -> usize { // s — ссылка на String
    s.len()
} // Здесь s входит в область видимости. Но поскольку s не владеет тем, на что
  // ссылается, значение не удаляется.

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

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

А что произойдёт, если попытаться изменить заимствованные данные? Попробуйте запустить код из Листинга 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 the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn change(some_string: &mut String) {
  |                         +++

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

Как и переменные, ссылки по умолчанию неизменяемы. Мы не можем поменять значение по ссылке.

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

Мы можем исправить код из Листинга 4-6, чтобы позволить себе изменять заимствованное значение: внеся небольшие правки, мы можем получить изменяемую ссылку:

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

    change(&mut s);
}

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

Во-первых, мы меняем объявление s, чтобы сделать её mut. Затем мы создаём изменяемую ссылку с помощью &mut s и передаём её функции change. Во-вторых, мы соответственно обновляем сигнатуру функции, чтобы мочь принять изменяемую ссылку: 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, и записать её в r2.

The restriction preventing multiple mutable references to the same data at the same time allows for mutation but in a very controlled fashion. It’s something that new Rustaceans struggle with because most languages let you mutate whenever you’d like. The benefit of having this restriction is that Rust can prevent data races at compile time. A data race is similar to a race condition and happens when these three behaviors occur:

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

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

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

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

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

    let r2 = &mut s;
}

В Rust действует аналогичное правило для случаев использования нескольких изменяемых и неизменяемых ссылок. Этот код не скомпилируется:

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

    let r1 = &s; // всё хорошо
    let r2 = &s; // всё хорошо
    let r3 = &mut s; // ВСЁ ПЛОХО

    println!("{}, {} и {}", r1, r2, 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, 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} и {r2}");
    // Переменные r1 и r2 далее не используются.

    let r3 = &mut s; // всё хорошо
    println!("{r3}");
}

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

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

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

В языках с указателями весьма легко ошибочно создать "висячую" ссылку — ссылку, указывающую на участок памяти, который был освобождён. Компилятор 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 {
  |

error[E0515]: cannot return reference to local variable `s`
 --> src/main.rs:8:5
  |
8 |     &s
  |     ^^ returns a reference to data owned by the current function

Some errors have detailed explanations: E0106, E0515.
For more information about an error, try `rustc --explain E0106`.
error: could not compile `ownership` (bin "ownership") due to 2 previous errors

Это сообщение об ошибке относится к особенности языка, которую мы ещё не рассмотрели: "времена жизни". Мы подробно обсудим времена жизни в Главе 10. Но даже если не обращать внимание на строки об ошибках о времени жизни, всё равно можно заметить самую главную ошибку:

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

Давайте подробнее рассмотрим, что происходит на каждом этапе нашего примера:

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

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

    let s = String::from("hello"); // в s записывается новое значение типа String

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

Поскольку s создаётся внутри dangle, то когда тело dangle закончится, s будет освобождена. Но мы попытались вернуть ссылку на неё. Это означает, что эта ссылка будет указывать на недействительную String. Это, очевидно, проблема! Однако Rust нас от неё защищает.

Решением будет вернуть непосредственно само значение String:

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

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

    s
}

Это работает без изъянов. Владение перемещается, и ничего не высвобождается.

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

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

• В любой момент времени вы можете иметь либо а) одну изменяемую ссылку, либо б) неограниченно много неизменяемых ссылок.
• Значение должно существовать дольше, чем любая ссылка, которая на него указывает.

В следующем разделе мы рассмотрим другой тип ссылок — срезы.

Срезы

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

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

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

fn first_word(s: &String) -> ?

The first_word function has a &String as a parameter. We don’t need ownership, so this is fine. (In idiomatic Rust, functions do not take ownership of their arguments unless they need to, and the reasons for that will become clear as we keep going!) But what should we return? We don’t really have a way to talk about part of a string. However, we could return the index of the end of the word, indicated by a space. Let’s try that, as shown in Listing 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() {}

Because we need to go through the String element by element and check whether a value is a space, we’ll convert our String to an array of bytes using the as_bytes method.

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` теперь пуста, а значение
    // `5` не имеет с ней никакого смысла, так что `word` теперь
    // полностью бессмысленна!
}

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

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

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

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

К счастью, в Rust есть решение данной проблемы: строковые срезы.

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

Строковый срез — это ссылка на часть строки String. Он выглядит вот так:

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

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

Вместо того, чтобы ссылаться на всю String, hello ссылается лишь на часть String, определяемую приписанным справа промежутком [0..5]. Срезы создаются указанием диапазона в квадратных скобках: [starting_index..ending_index], где starting_index — это первая позиция в срезе, а ending_index — это на единицу больше, чем последняя позиция в срезе. Внутри себя срез хранит начальную позицию и длину среза, что соответствует ending_index минус starting_index. Итак, в строчке let world = &s[6..11];, world будет срезом, содержащим указатель на байт строки s по индексу 6, и значение 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[..];
}

Примечание: Индексы диапазона среза строки должны соблюдать байтовое членение символов в кодировке UTF-8. Если вы попытаетесь создать срез строки, в котором начало или конец будет указывать на кусок символа, программа завершится с ошибкой. В целях объяснения работы срезов строк мы предполагаем, что в этом разделе используется только кодировка ASCII; более подробное обработка текста в UTF-8 обсуждается в разделе Главы 8 "Хранение текста в кодировке UTF-8 с помощью строк".

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

Теперь, когда мы вызываем first_word, мы возвращаем единственное значение, привязанное к обрабатываемым данным. Значение состоит из ссылки на первый символ строки, с которого начинается срез, и количества элементов в срезе.

Аналогичным образом можно переписать и функцмю second_word:

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

Теперь у нас есть простой API, который гораздо сложнее испортить, поскольку что компилятор гарантирует, что ссылки на String останутся действительными. Помните ошибку в программе Листинга 4-8, когда мы получили индекс конца первого слова, но затем очистили строку, так что наш индекс стал недействительным? Этот код был неправильным логически, но не формально. Его проблемы могли проявиться позже, если бы мы попытались использовать индекс первого слова с пустой строкой. Срезы делают эту ошибку невозможной и сообщают нам о проблеме с нашим кодом гораздо раньше. Например, код ниже не скомпилируется:

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!("первое слово: {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!("первое слово: {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

Напомним из правил заимствования, что если у нас есть неизменяемая ссылка на что-то, мы не можем также взять изменяемую ссылку. Поскольку методу clear необходимо очистить String, необходимо получить изменяемую ссылку на неё. Макрос println! (после вызова clear) использует ссылку, сохранённую в word, а потому неизменяемая ссылка в этот момент всё ещё должна быть действительной. Rust запрещает одновременное существование изменяемой ссылки в clear и неизменяемой ссылки в word, и компиляция завершается ошибкой. Rust не только упростил использование нашего API, но и устранил целый класс ошибок сразу на этапе компиляции!

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

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

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

Тип переменной s — это &str, то есть срез, указывающий на конкретную точку бинарного файла. Вот почему строковые литералы неизменяемы; почему &str — ссылка именно неизменяемая.

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

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

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

Более опытный программист на Rust вместо этого написал бы сигнатуру, показанную в Листинге 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 или ссылку на String. Эта гибкость работает за счёт функциональности приведения ссылок при разыменовывании, что мы рассмотрим в разделе "Неявное приведение при разыменовании с функциями и методами" Главы 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 и рассмотрим группировку данных в структуры.

Использование структур для организации данных

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

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

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

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

Чтобы определить структуры, мы вводим ключевое слово struct и название структуры. Название должно описывать значение частей данных, сгруппированных вместе. Далее, в фигурных скобках для каждого поля поочерёдно определяются имя и тип. Листинг 5-1 показывает структуру, которая хранит информацию об учётной записи пользователя:

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

fn main() {}

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

Создание экземпляра структуры из экземпляра другой структуры с помощью синтаксиса обновления структуры

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

В Листинге 5-6 показано, как в user2 записывается новый экземпляр User без синтаксиса обновления. Мы задаём новое значение для 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, но перед этим мы можем указать свои значения для любых полей в любом порядке, независимо от порядка полей в определении структуры.

Стоит отметить, что синтаксис обновления структуры использует оператор = как оператор присваивания, потому что он перемещает данные, как мы видели в разделе "Взаимодействие переменных и данных с помощью перемещения". В примере выше мы больше не можем использовать user1 после создания user2, потому что String в поле username из user1 было перемещено в user2. Если бы мы задали user2 новые значения String для email и username, и, таким образом, использовали только значения active и sign_in_count из user1, то user1 всё ещё была бы действительной после создания user2. Оба типа active и sign_in_count реализуют трейт Copy, поэтому они ведут себя так, как мы обсуждали в разделе "Данные, размещающиеся только на стеке, всегда копируются". Однако, в нашем примере мы всё ещё можем использовать запись user1.email, поскольку значение этого поля не было перемещено.

Использование кортежных структур без имён для создания разных типов

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

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

Unit-подобные структуры

Также можно определять структуры, не имеющие полей! Они называются unit-подобными структурами, поскольку ведут себя аналогично (), unit, о котором мы говорили в разделе ["Тип кортежа"] (ch03-02-data-types.html#Тип-кортежа). Unit-подобные структуры могут быть полезны, когда требуется реализовать трейт для некоторого типа, но у вас нет данных, которые нужно было бы хранить в самом типе. Мы обсудим трейты в Главе 10. Вот пример объявления и создания экземпляра unit-структуры с именем AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

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

Владение данными структуры

В определении структуры User в Листинге 5-1 мы использовали "владеемый" тип String, а не тип &str среза строки. Это осознанный выбор, поскольку мы хотим, чтобы каждый экземпляр этой структуры владел всеми своими данными и чтобы эти данные были действительны до тех пор, пока действительна вся структура.

Структуры также могут хранить ссылки, но для этого необходимо определить времена жизни — особенность Rust, которую мы обсудим в Главе 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

В Главе 10 мы обсудим, как исправлять эти ошибки, чтобы иметь возможность хранить ссылки в структурах, а до тех пор мы будем обходить подобные ошибки, используя владеемые типы вроде String вместо ссылок вроде &str.

Пример программы, использующей структуры

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

Давайте создадим новый проект программы при помощи Cargo и назовём его rectangles. Наша программа будет получать на вход длину и ширину прямоугольника в пикселях и затем рассчитывать площадь прямоугольника. Листинг 5-8 показывает один из коротких вариантов кода, который позволит нам сделать именно то, что надо.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "Площадь прямоугольника равна {} квадратных пикселей.",
        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`
Площадь прямоугольника равна 1500 квадратных пикселей.

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

Проблема данного метода очевидна, если взглянуть на сигнатуру area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "Площадь прямоугольника равна {} квадратных пикселей.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

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

Рефакторинг внедрением кортежей

Листинг 5-9 — это другая версия программы, использующая кортежи.

fn main() {
    let rect1 = (30, 50);

    println!(
        "Площадь прямоугольника равна {} квадратных пикселей.",
        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!(
        "Площадь прямоугольника равна {} квадратных пикселей.",
        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: {}", rect1);
}

При компиляции этого кода мы получаем ошибку. Главное в ней вот что:

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

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

Продолжив чтение текста ошибки, мы найдём полезный совет:

   = help: the trait `std::fmt::Display` is not implemented for `Rectangle`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead

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

Скомпилируем код с этими изменениями. Упс! Мы всё ещё получаем ошибку:

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

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

   = help: the trait `Debug` is not implemented for `Rectangle`
   = note: add `#[derive(Debug)]` to `Rectangle` or manually `impl Debug for Rectangle`

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

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

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

    println!("rect1: {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: 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: Rectangle {
    width: 30,
    height: 50,
}

Другой способ распечатать значение в формате Debug — использовать макрос dbg!, который печатает название файла и номер строки, где происходит вызов макроса dbg!, плюс переданное в него выражение со значением, в которое то вычисляется. Макрос dbg! принимает владение над переданным в него выражением (в отличие от макроса println!, использующего ссылки), но возвращает результат переданного выражения.

Примечание: При вызове макроса dbg! выполняется печать в стандартный поток ошибок (stderr), в отличие от println!, который использует стандартный поток вывода в консоль (stdout). Подробнее о stderr и stdout мы поговорим в разделе "Вывод сообщений об ошибках в стандартный поток ошибок" Главы 12.

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

Мы можем обернуть выражение 30 * scale макросом dbg!, потому что dbg! возвращает владение значением выражения. Поле width получит то же значение, как если бы у нас не было вызова dbg!. Далее, мы не хотим, чтобы макрос dbg! становился владельцем rect1, поэтому используем ссылку на 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. Для получения дополнительной информации, ознакомьтесь с разделом "Атрибуты" Справочника Rust.

Функция area является довольно специфичной: она считает только площадь прямоугольников. Было бы полезно привязать данное поведение как можно ближе к структуре Rectangle, потому что наш специфичный код не будет работать с любым другим типом. Давайте рассмотрим, как можно улучшить наш код, превратив функцию area в метод area, определённый для типа Rectangle.

Синтаксис метода

Методы похожи на функции: мы объявляем их с помощью ключевого слова fn и имени; они могут иметь параметры и возвращаемое значение; они содержат код, запускающийся при вызове метода. В отличие от функций, методы определяются в контексте структуры (или перечисления или трейт-объекта, которые мы рассмотрим в Главе 6 и Главе 17 соответственно), а их первым параметром всегда является 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!(
        "Площадь прямоугольника равна {} квадратных пикселей.",
        rect1.area()
    );
}

Чтобы определить функцию в контексте Rectangle, мы создаём блок impl (сокр. от implementation) для Rectangle. Всё, что находится в impl, будет связано с типом 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: неизменяемо или (как мы поступили в данном случае) изменяемо.

Мы выбрали &self здесь по той же причине, по которой использовали &Rectangle в версии с функцией: мы не хотим брать структуру во владение, мы просто хотим прочитать данные в структуре, а не писать в неё. Если бы мы хотели изменить экземпляр, на котором мы вызывали метод, то мы бы использовали &mut 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!("Длина прямоугольника ненулевая и равна {}", rect1.width);
    }
}

Здесь мы определили, что метод width возвращает значение true, если значение в поле width экземпляра больше 0, и возвращает значение false, если значение равно 0: мы можем создавать методы с теми же именами, что и поля, и даже затем использовать любые поля в теле методов. В main, когда мы ставим после rect1.width круглые скобки, Rust понимает, что мы имеем в виду метод width. Если же мы не используем круглые скобки, Rust понимает, что мы имеем в виду поле width.

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

Есть ли тут оператор ->?

В C и C++ используются два разных оператора для вызова методов: . используется, если метод вызывается непосредственно у экземпляра структуры; -> используется, если метод вызывается на указателе на структуру, и потому которую необходимо разыменовать перед вызовом метода. Другими словами, если object — это указатель, то вызовы метода object->something() и (*object).something() являются, по сути, одним и тем же.

Rust не имеет эквивалента оператора ->. Вместо него в Rust есть механизм автоматического взятия ссылок и их разыменования. Вызов методов является одним из немногих мест в Rust, в котором есть такое поведение.

Вот как это работает: когда вы вызываете метод конструкцией object.something(), Rust автоматически добавляет &, &mut или *, таким образом, чтобы object соответствовал сигнатуре метода. Записи ниже равны друг другу:

#![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);
}

Первый пример выглядит намного понятнее. Автоматическое взятие ссылки работает потому, что методу известно, на чём он вызывается — на self. Учитывая вызывающее значения и имя метода, Rust может точно определить, что в данном случае делает код: читает ли метод (&self), делает ли изменение (&mut self) или поглощает значение (self). Тот факт, что Rust может неявно заимствовать вызывающее значение, в значительной степени способствует тому, чтобы делать владение эргономичным и практичным.

Методы с несколькими параметрами

Давайте попрактикуемся в использовании методов, реализовав второй метод на структуре Rectangle. На этот раз мы хотим, чтобы экземпляр Rectangle брал другой экземпляр Rectangle и возвращал true, если второй Rectangle может полностью поместиться внутри self (то есть, первого Rectangle); в противном случае он должен вернуть false. С таким методом мы могли бы написать программу как в Листинге 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!("Вместится ли rect2 в rect1? {}", rect1.can_hold(&rect2));
    println!("Вместится ли rect3 в rect1? {}", rect1.can_hold(&rect3));
}

Ожидаемый результат будет выглядеть так, как ниже: 1) оба измерения экземпляра rect2 меньше, чем измерения экземпляра rect1, и 2) rect3 шире, чем rect1.

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Мы знаем, что хотим определить именно метод, поэтому он будет находится в блоке impl Rectangle. Имя метода будет can_hold, и оно будет принимать в качестве параметра неизменяемое заимствование на другой Rectangle. Мы можем сказать, какой будет тип параметра, посмотрев на код вызова метода: rect1.can_hold(&rect2) передаёт в метод &rect2, что является неизменяемым заимствованием экземпляра rect2 типа Rectangle. В этом есть смысл, потому что нам нужно лишь читать rect2 (а не писать, что означало бы, что нужно изменяемое заимствование), и мы хотим, чтобы main сохранила владение экземпляром rect2, чтобы мы могли использовать его снова после вызова метода can_hold. Возвращаемое значение can_hold имеет логический тип, а реализация проверяет, являются ли ширина и высота self больше, чем, соответственно, ширина и высота другого Rectangle. В Листинге 5-15 приведено определение нового метода can_hold, добавленного в блок impl из Листинга 5-13.

#[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!("Вместится ли rect2 в rect1? {}", rect1.can_hold(&rect2));
    println!("Вместится ли rect3 в rect1? {}", rect1.can_hold(&rect3));
}

Если мы запустим код с функцией main из Листинга 5-14, мы получим желаемый вывод. Методы могут принимать несколько параметров: мы добавляем их в сигнатуру после первого параметра self. Дополнительные параметры методов работают точно так же, как параметры функции.

Ассоциированные функции

Все функции, определяемые в блоке impl, называются ассоциированными функциями, потому что они ассоциированы с типом, указанным после ключевого слова 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!("Вместится ли rect2 в rect1? {}", rect1.can_hold(&rect2));
    println!("Вместится ли rect3 в rect1? {}", rect1.can_hold(&rect3));
}

В данном случае, нет причин разбивать методы на несколько блоков impl, однако это всё-таки реализуемо. Мы увидим случай, когда несколько impl могут оказаться полезными, в Главе 10, рассматривающей обобщённые типы и трейты.

Подведём итоги

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

Но структуры — не единственный способ создавать собственные типы. Давайте посмотрим на перечисления — ещё один инструмент в вашем арсенале.

Перечисления и соспоставление с шаблоном

В этой главе мы рассмотрим перечисления. Перечисления позволяют определить тип путём перечисления его возможных вариантов. Сначала мы определим и используем перечисление, чтобы показать, как оно может объединять смысл и данные. Далее мы рассмотрим особенно полезное перечисление под названием Option, которое выражает, что значение может быть либо чем-то, либо ничем. Затем мы рассмотрим, как сопоставление с образцом в выражении match позволяет легко запускать разный код для разных значений перечисления. Наконец, мы узнаем, насколько конструкция if let удобна и лаконична для обработки перечислений в вашем коде.

Определение перечисления

Там, где структуры дают вам возможность группировать связанные поля и данные (например, Rectangle с его width и height), перечисления дают вам способ сказать, что данное значение является лишь одним из возможных наборов значений. Например, мы можем захотеть сказать, что Rectangle — это одна из множества возможных фигур, в которую также входят Circle и Triangle. Rust позволяет нам записать эту множественность в виде перечисления.

Давайте рассмотрим ситуацию, которую мы могли бы захотеть отразить в коде, и поймём, почему в этом случае перечисления полезны и более уместны, чем структуры. Допустим, нам нужно работать с IP-адресами. В настоящее время для обозначения 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-адреса, то выяснится, что на данный момент у нас нет возможности хранить собственно сам 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, который представляет адрес типа IpAddrKind::V4 (в соответствии со своим значением kind) с соответствующим адресом 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. Эту функцию-конструктор мы получаем автоматически, когда определяем перечисление.

Ещё одно преимущество использования перечисления вместо структуры заключается в том, что каждый вариант перечисления может иметь разное количество связанных с ним данных, представленных в разных типах. IP-адреса 4ой версии всегда будет содержать четыре цифровых компонента, которые будут иметь значения между 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-адреса и указывать их тип настолько распространена, что в стандартной библиотеке уже есть готовое определение! В нём есть точно такое же перечисление с вариантами, которое определили и использовали мы, но она помещает данные об адресе внутрь этих вариантов в виде двух различных структур, которые имеют различные определения для каждого из вариантов:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --код сокращён--
}

struct Ipv6Addr {
    // --код сокращён--
}

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

Это перечисление имеет 4 варианта:

• Quit — вариант без каких-либо связанных с ним значений.
• Move — вариант с именованными значениями, как у структуры.
• Write — вариант, имеющий лишь String.
• ChangeColor — вариант, имеющий три числа i32.

Определение перечисления с вариантами (такими, как в Листинге 6-2) похоже на определение значений разных возможных структур, за исключением того, что перечисление не использует ключевое слово struct и все варианты сгруппированы внутри типа Message. Следующие структуры могут содержать те же данные, что и предыдущие варианты перечислений:

struct QuitMessage; // unit-подобная структура
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 и его преимущества перед значениями Null

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

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

Дизайн языка программирования часто рассматривается с точки зрения того, какие функции вы включаете в него, но также важно то, какие функции вы в него не включаете. Например, в Rust нет понятия "null", однако оно есть во многих других языках. Null — это значение, которое означает, что значения нет. В языках с null переменные всегда могут находиться в одном из двух состояний: null или не-null.

В своей презентации 2009 года "Null References: The Billion Dollar Mistake" Тони Хоар, автор концепции null, сказал следующее:

Я называю это своей ошибкой на миллиард долларов. В то время я разрабатывал первую комплексную систему типов для ссылок в объектно-ориентированном языке. Моя цель состояла в том, чтобы гарантировать, что любое использование ссылок будет абсолютно безопасным, с автоматической проверкой компилятором. Но я не смог устоять перед соблазном внедрить в язык пустую ссылку — просто потому, что это было так легко реализовать. Это привело к бесчисленным ошибкам, уязвимостям и системным сбоям, которые, вероятно, причинили боль и ущерб на миллиард долларов за последние сорок лет.

Проблема с null заключается в том, что если вы попытаетесь использовать null в качестве не-null значения, вы получите ошибку определённого рода. Поскольку эта возможность (быть null или не-null) распространена повсеместно, сделать такую ошибку очень просто.

Тем не менее, концепция, которую null пытается выразить, является полезной: null — это значение, которое в настоящее время по какой-то причине недействительно или отсутствует.

Проблема на самом деле не в концепции, а в конкретной реализации. В Rust нет значений null, но есть перечисление, которое может выразить концепцию присутствия или отсутствия значения. Это перечисление Option<T>, и оно определено стандартной библиотекой следующим образом:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Перечисление Option<T> настолько полезно, что оно даже включено в prelude; вам не нужно самому вводить его в область видимости. Его варианты также включены в prelude: вы можете использовать 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: компилятор не может вывести тип, который будет в Some, глядя только на значение None. Здесь мы сообщаем 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>`:
            `&'a i8` implements `Add<i8>`
            `&i8` implements `Add<&i8>`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

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

Оно большое! Фактически, это сообщение об ошибке означает, что Rust не понимает, как сложить i8 и Option<i8>, потому что это разные типы. Когда у нас есть значение типа вроде i8, компилятор гарантирует, что оно всегда действительно. Мы можем уверенно продолжать работу, не проверяя его на null перед использованием. Лишь когда мы имеем значение типа Option<i8> (или любого другого конкретного типового параметра), у нас есть повод беспокоиться о том, что мы можем и не иметь значения; однако, компилятор обеспечит проверку нами обоих случаев перед тем, как давать использовать (возможное) значение.

Другими словами, вы должны преобразовать Option<T> в T, прежде чем вы сможете исполнять операции с этим T. Как правило, это помогает выявить одну из наиболее распространённых проблем с null: действия с чем-то в предположении, что это что-то не равно null, когда оно на самом деле равно null.

Устранение риска ошибочного предположения касательно не-null значения помогает вам быть более уверенным в своём коде. Чтобы иметь значение, которое может быть null, вы должны явно описать тип этого значения с помощью Option<T>. Затем, когда вы используете это неопределённое значение, вы обязаны явно обрабатывать случай, когда значение — null. Везде, где значение имеет тип, отличный от Option<T>, вы можете смело рассчитывать на то, что значение не равно null. Это — продуманное решение архитектуры Rust, ограничивающее распространение null и увеличивающее безопасность кода на этом языке.

Итак, как же получить значение T из варианта Some, если у вас на руках есть только значение Option<T>? Перечисление Option<T> имеет большое количество методов, полезных в различных ситуациях; вы можете ознакомиться с ними в его документации. Знакомство с методами перечисления Option<T> в вашем путешествии с Rust будет чрезвычайно полезным.

В общем случае, чтобы использовать значение Option<T>, нужен код, который будет обрабатывать все варианты этого перечисления. Если у вас есть значение Some(T), вам нужен один код для его обработки, и этому коду должно быть разрешено работать с этим внутренним T. Если же у вас есть значение None, то вам захочется обрабатывать его иначе, при этом у этого кода не будет никакого значения T для обработки. Выражение 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 состоит из четырёх ветвей.

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

Обычно фигурные скобки не используются, если код совпадающей ветви невелик (как в Листинге 6-3, где каждая ветвь просто возвращает значение). Если вы хотите выполнить несколько строк кода в одной ветви, вы должны использовать фигурные скобки; запятая после этой ветви необязательна. Например, следующий код печатает "Счастливый пенни!" каждый раз, когда метод вызывается с Coin::Penny, но при этом он возвращает последнее значение блока — 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Счастливый пенни!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Связывание со значениями с помощью шаблонов

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

В качестве демонстрации, давайте изменим один из вариантов перечисления так, чтобы он хранил в себе данные. С 1999 по 2008, Соединённые Штаты чеканили особенные четвертаки: с уникальными дизайнами для каждого из 50 штатов. Ни одна другая монета не получила дизайна, особенного для отдельных штатов, только четверть доллара имела эту особенность. Мы можем добавить эту информацию в наш enum путём изменения варианта Quarter и включения в него значения UsState, как сделано в Листинге 6-4.

#[derive(Debug)] // нужно, чтобы мы могли легко посмотреть конкретный штат
enum UsState {
    Alabama,
    Alaska,
    // --код сокращён--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

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

В выражении match мы добавляем переменную с именем state в шаблон, который соответствует значениям варианта Coin::Quarter. Когда 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:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

Если мы сделаем вызов функции value_in_cents(Coin::Quarter(UsState::Alaska)), то coin будет иметь значение Coin::Quarter(UsState::Alaska). Когда мы будем сравнивать это значение с шаблонами каждой из ветвей, ни одному из них оно не будет отвечать, пока мы не достигнем 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);
}

Let’s examine the first execution of plus_one in more detail. When we call plus_one(five), the variable x in the body of plus_one will have the value Some(5). We then compare that against each match arm:

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, то есть i получает значение 5. Затем исполняется код, связанный с данной ветвью: мы добавляем 1 к значению 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);
}

Оно совпадает! Данное значение ничего в себе не хранит, так что выражение просто возвращает значение None, находящееся справа от =>. Поскольку шаблон первой ветви совпал, сравнений с оставшимися шаблонами не происходит.

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

Ветви 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
   --> file:///home/.rustup/toolchains/1.82/lib/rustlib/src/rust/library/core/src/option.rs:571:1
    |
571 | pub enum Option<T> {
    | ^^^^^^^^^^^^^^^^^^
...
575 |     None,
    |     ---- 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 знает, что мы не описали все возможные случаи, и даже знает, какой именно из шаблонов мы упустили! Сопоставления в Rust являются исчерпывающими: мы обязаны покрыть все возможные варианты, чтобы код был корректным. Особенно — в случае Option<T>, когда Rust не даёт нам забыть обработать явным образом значение None, тем самым защищая нас от ложного предположения о наличии не-null значения, и оберегая нас от опасности совершить ошибку на миллиард долларов, о которой говорилось ранее.

Универсальные шаблоны и заполнитель _

Используя перечисления, мы также можем выполнять специальные действия для нескольких определённых значений, а для всех остальных значений выполнять одно общее действие по умолчанию. Представьте, что мы реализуем игру, в которой при выпадении 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. Код, выполняемый для ветки other, использует эту переменную, передавая её в функцию move_player.

Этот код компилируется, даже хотя мы не перечислили все возможные случаи: всё потому что последний шаблон будет соответствовать всем значениям, не указанным в конкретном списке. Этот универсальный шаблон удовлетворяет требованию, что сопоставление должно быть исчерпывающим. Обратите внимание, что мы должны поместить ветвь с универсальным шаблоном последней, потому что сопоставление с шаблонами происходит по порядку. 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. Мы можем реализовать это, используя unit (тип пустого кортежа, который мы упоминали в разделе "Тип кортежа") на месте кода, который соответствует ветви _:

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 позволяет скомбинировать if и let в конструкцию, менее многословно обрабатывающую значения, соответствующие только одному шаблону, одновременно игнорируя все остальные варианты. Рассмотрим программу в Листинге 6-6, которая проводит сопоставление значения Option<u8> переменной config_max, но которая собирается выполнять код только в том случае, если значение является Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("Максимум выставлен на {max}"),
        _ => (),
    }
}

Если значение равно Some, мы распечатываем значение в варианте Some, привязывая его значение к переменной max в шаблоне. Мы ничего не хотим делать со значением None. Чтобы удовлетворить выражение match, мы должны добавить _ => () после обработки первой и единственной ветви. Однако сразу возникает чувство, что для этой задачи хорошо бы иметь инструмент попроще и покороче.

Собственно, мы могли бы написать всё более кратко, воспользовавшись if let. Следующий код ведёт себя так же, как выражение match в Листинге 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("Максимум выставлен на {max}");
    }
}

Синтаксис if let принимает шаблон и выражение, разделённые знаком равенства. Он работает так же, как match, которому на вход подают выражение, отвечающее шаблону первой ветви. В данном случае шаблоном является Some(max), где max привязывается к значению внутри Some. После сопоставления, мы можем использовать max в теле блока if let так же, как мы использовали max в соответствующей ветке match. Код в блоке if let не запускается, если значение не отвечает шаблону.

Используя if let, мы печатаем меньше, делаем меньше отступов и получаем меньше повторяющегося кода. Тем не менее, мы теряем полную проверку всех вариантов, предоставляемую выражением match. Выбор между match и if let зависит от того, что вы делаете в вашем конкретном случае и удовлетворяет ли вас потеря полноты сопоставления ради лаконичности.

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

Можно добавлять else к if let. Блок кода, который находится внутри else, аналогичен по смыслу блоку кода ветви выражения match (если оно эквивалентно сборной конструкции if let и else), связанной с шаблоном _. Вспомним объявление перечисления 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:?}!"),
        _ => 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:?}!");
    } 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:?} довольно староват для Америки!"))
        } else {
            Some(format!("Штат {state:?} относительно молодой."))
        }
    } 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:?} довольно староват для Америки!"))
        } else {
            Some(format!("Штат {state:?} относительно молодой."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Этого достаточно для желаемого нами результата. Однако нам пришлось поместить всю работу кода в тело инструкции if let. Если работа, которую необходимо выполнить, окажется более сложной, может быть трудно распутать, к чему именно относятся вложенные операторы if и else. Мы могли бы решить нашу задачу и иначе: воспользоваться тем фактом, что выражения возвращают значения, чтобы вернуть значение переменной state из if let (либо сразу, не дожидаясь, вернуть в блоке else значение None, если мы получили не четвертак). Это альтернативное решение приведено в Листинге 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:?} довольно староват для Америки!"))
    } else {
        Some(format!("Штат {state:?} относительно молодой."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Однако и это решение несколько раздражает, поскольку каждая ветвь if let ведёт себя совершенно по-своему! Одна ветвь лишь вычисляется в значение, а другая прерывает всю функцию и сразу из неё что-то возвращает.

Для упрощения подобных выражений в Rust есть let-else. Конструкции let-else предоставляются шаблон слева и выражение справа (что очень похоже на if let — но у let-else нет ветви if, лишь else). Если значение сопоставится, то значение из шаблона свяжется с переменной из внешней области видимости. Если значение не сопоставится, исполнение перейдёт в ветвь else, которая должна вернуть значение из функции.

В Листинге 6-9 вы можете увидеть, как выглядит Листинг 6-8 с использованием let-else вместо if let. Обратите внимание, что таким образом, мы выносим всю обработку особых случаев в начало функции, а весь её последующий остаток спокойно будет делать самую важную работу, без необходимости отвлекаться на что-либо ещё. С if let наш поток пришлось делить на две ветви, и только одна из них выполняла настоящую работу.

#[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:?} довольно староват для Америки!"))
    } else {
        Some(format!("Штат {state:?} относительно молодой."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Если у вас возникла ситуация, в которой логика вашей программы слишком многословна, если выражать её через match, помните о том, что в вашем арсенале есть ещё if let и let else.

Подведём итоги

Мы рассмотрели, как использовать перечисления для создания пользовательских типов, представляющий перечень возможных вариантов. Мы показали, как тип стандартной библиотеки Option<T> помогает использовать систему типов для предотвращения ошибок. Если варианты перечисления имеют данные внутри них, можно использовать match или if let (смотря, сколько случаев вам нужно обработать), чтобы извлечь их и воспользоваться ими.

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

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

Упарвление разрастающимися проектами с помощью пакетов, крейтов и модулей

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

Программы, которые мы писали до сих пор, располагались в одном файле одного модуля. По мере роста проекта, мы можем организовывать код иначе, разделяя его на несколько модулей и несколько файлов. Пакет может содержать несколько бинарных крейтов и (опционально) один библиотечный крейт. По мере роста пакета, вы можете выносить части программы в отдельные крейты, которые затем станут внешними зависимостями для основного кода нашей программы. Эта глава охватывает все эти техники. Для очень крупных проектов, состоящих из набора взаимосвязанных пакетов, развивающихся вместе, Cargo предоставляет рабочие пространства; мы рассмотрим их в разделе "Рабочие пространства Cargo" Главы 14.

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

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

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

• Пакеты — механизм Cargo, позволяющий собирать, тестировать и делиться крейтами
• Крейты — дерево модулей, которое создаёт библиотеку или исполняемый файл
• Модули и use — позволяют контролировать организацию частей кода, области видимости и скрытие путей
• Пути: способ именования элемента, такого как структура, функция или модуль

В этой главе мы рассмотрим всё перечисленное, обсудим их взаимодействие и объясним, как использовать их для управления областями видимости. К концу у вас должно появиться солидное понимание системы модулей и умение работать с областями видимости на уровне профессионала! (Примечание переводчика: материал этой главы может сломать вам мозг. Настоятельно рекомендуется самостоятельный поиск дополнительных материалов. Hang in there!)

Пакеты и крейты

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

Крейт — это наименьший объем кода, который компилятор Rust рассматривает за раз. Даже если вы запустите rustc вместо cargo и передадите один файл с исходным кодом (как мы уже делали в разделе "Написание и запуск программы на Rust" Главы 1), компилятор посчитает этот файл крейтом. Крейты могут содержать модули, и модули могут быть определены в других файлах, которые компилируются вместе с крейтом, как мы увидим в следующих разделах.

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

Library crates don’t have a main function, and they don’t compile to an executable. Instead, they define functionality intended to be shared with multiple projects. For example, the rand crate we used in Chapter 2 provides functionality that generates random numbers. Most of the time when Rustaceans say “crate”, they mean library crate, and they use “crate” interchangeably with the general programming concept of a “library”.

Корень крейта — это исходный файл, из которого компилятор Rust начинает собирать корневой модуль вашего крейта (мы подробно объясним модули в разделе "Использование модулей для управления областью видимости и приватностью").

Пакет — это набор из одного или нескольких крейтов, предоставляющий набор функциональности. Пакет содержит файл 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. В директории проекта есть файл 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, внешние пакеты и оператор *.

Шпаргалка по модулям

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

• Старт с корня крейта. В начале компиляции крейта, компилятор ищет в корне крейта (обычно это src/lib.rs для библиотечного крейта или src/main.rs для бинарного крейта) код для компиляции.
• Объявление модулей. В файле корня крейта вы можете объявлять новые модули. Скажем, вы объявляете модуль "garden" с помощью mod garden;. Компилятор будет искать код модуля в следующих местах:
  • В этом же файле между фигурных скобок, которые заменяют точку с запятой после mod garden
  • В файле src/garden.rs
  • В файле src/garden/mod.rs
• Объявление подмодулей. В любом файле, кроме корня крейта, вы можете объявлять подмодули. К примеру, вы можете объявить mod vegetables; в src/garden.rs. Компилятор будет искать код подмодуля в каталоге с именем родительского модуля в следующих местах:
  • В этом же файле, сразу после mod vegetables и между фигурных скобок, которые заменяют точку с запятой
  • В файле src/garden/vegetables.rs
  • В файле src/garden/vegetables/mod.rs
• Пути к коду в модулях. После того, как модуль станет частью вашего крейта, и если допускают правила приватности, вы можете ссылаться на код в этом модуле из любого места вашего крейта, используя путь к коду. Например, тип Asparagus в подмодуле vegetables модуля garden будет доступен по пути 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!("Здесь растёт {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. Front of house — это там, где находятся клиенты; здесь размещаются места клиентов, официанты принимают заказы и оплаты, а бармены делают напитки. Back of house — там, это где повара работают на кухне, работают посудомоечные машины, а менеджеры занимаются хозяйственной деятельностью.

Чтобы структурировать крейт аналогично ресторанной модели, можно организовать размещение его функций во вложенных модулях. Создадим новую библиотеку с именем restaurant выполнив команду cargo new restaurant --lib. Затем вставим код из Листинга 7-1 в src/lib.rs для определения некоторых модулей и сигнатур функций. Это front of house:

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Мы определяем модуль ключевым словом mod, затем пишем название модуля (в данном случае — front_of_house) и размещаем фигурные скобки вокруг тела модуля. Внутри модулей можно иметь другие модули, как мы это сделали с модулями hosting и serving. Модули также могут содержать определения других элементов, таких как структуры, перечисления, константы, трейты или (как в Листинге 7-1) функции.

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

Earlier, we mentioned that src/main.rs and src/lib.rs are called crate roots. The reason for their name is that the contents of either of these two files form a module named crate at the root of the crate’s module structure, known as the 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. Дерево также показывает, что некоторые модули являются "братьями", то есть они определены в одном модуле; hosting и serving — это "братья", которые определены внутри front_of_house. Если модуль A содержится внутри модуля B, мы говорим, что модуль A является потомком модуля B, а модуль B является родителем модуля 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. Вы можете представить себе файловую систему с такой же структурой: мы указываем путь /front_of_house/hosting/add_to_waitlist для запуска программы add_to_waitlist; использование имени crate в качестве корня крейта аналогично использованию / для указания корня файловой системы в вашей оболочке (shell).

Во втором вызове add_to_waitlist из eat_at_restaurant мы используем относительный путь. Путь начинается с имени модуля front_of_house, определённого на том же уровне дерева модулей, что и eat_at_restaurant. Аналогом пути в файловой системе было бы front_of_house/hosting/add_to_waitlist. Начало пути с имени модуля означает, что путь является относительным.

Выбор, использовать относительный или абсолютный путь, является решением, которое вы примете на основании вашего проекта. Решение зависит от того, с какой вероятностью вы переместите объявление элемента отдельно от или вместе с кодом, использующим этот элемент. Например, в случае перемещения модуля front_of_house и его функции eat_at_restaurant в другой модуль с именем customer_experience, будет необходимо обновить абсолютный путь до add_to_waitlist, но относительный путь всё равно будет действителен. Однако, если мы переместим отдельно функцию eat_at_restaurant в модуль с именем dining, то абсолютный путь вызова 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:9:37
  |
9 |     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:12:30
   |
12 |     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 позволяет нам использовать эти пути для add_to_waitlist в соответствии с правилами приватности, давайте рассмотрим абсолютный и относительный пути.

В случае абсолютного пути, мы начинаем с crate, корня дерева модулей нашего крейта. Модуль front_of_house определён в корне крейта. Хотя front_of_house не является общедоступным, но поскольку функция eat_at_restaurant определена в том же модуле, что и front_of_house (то есть, eat_at_restaurant и front_of_house являются потомками одного родителя), мы можем ссылаться на front_of_house из eat_at_restaurant. Далее идёт модуль 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, чтобы сделать зависимость от вашего крейта необременительной. Эти соображения выходят за рамки этой книги; если вам интересна эта тема, ознакомьтесь с The Rust API Guidelines.

Лучшие практики для пакетов с бинарным и библиотечным крейтами

Мы упоминали, что пакет может содержать как корневой модуль бинарного крейта src/main.rs, так и корневой модуль библиотечного крейта src/lib.rs, и оба крейта будут по умолчанию иметь имя пакета. Как правило, пакеты с таким шаблоном, содержащим как библиотечный, так и бинарный крейт, будут иметь достаточно кода в бинарном крейте, чтобы запустить исполняемый файл, который вызывает код из библиотечного крейта. Это позволяет другим проектам извлечь выгоду из большей части функциональности, предоставляемой пакетом, поскольку код библиотечного крейта могут использовать и другие.

Дерево модулей должно быть определено в src/lib.rs. После этого, любые общедоступные элементы можно использовать в бинарном крейте, начав пути с имени пакета. Бинарный крейт становится пользователем библиотечного крейта точно так же, как полностью внешний крейт использует библиотечный крейт: он может использовать только общедоступный API. Это поможет вам разрабатывать хороший API, так как вы не только автор, но и пользователь!

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

Определение относительных путей с помощью super

Также можно построить относительные пути, которые начинаются в родительском (а не текущем) модуле, используя ключевое слово super в начале пути. Это похоже на синтаксис .. пути файловой системы. Использование super позволяет нам сослаться на элемент, который, как мы знаем, находится в родительском модуле, что может упростить переупорядочение дерева модулей, чем когда модуль тесно связан с родителем, но родитель может когда-нибудь быть перемещён в другое место в дереве модулей.

Рассмотрим код в Листинге 7-8, где моделируется ситуация, в которой повар исправляет неправильный заказ и лично приносит его клиенту. Функция fix_incorrect_order вызывает функцию 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 со структурами и перечислениями. Если мы используем 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("персики"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Заказываем летом завтрак с ржаным хлебом.
    let mut meal = back_of_house::Breakfast::summer("ржаной");
    // Передумали насчёт хлеба, который мы хотим.
    meal.toast = String::from("пшеничный");
    println!("Я хочу {} тост, пожалуйста.", meal.toast);

    // Следующая строчка, если мы раскомментируем её, не скомпилируется:
    // нам не разрешено знать или изменять сезонный фрукт, который нам подадут.
    // meal.seasonal_fruit = String::from("черника");
}

Поскольку поле toast в структуре back_of_house::Breakfast является открытым, то в функции eat_at_restaurant можно писать и читать поле toast, используя обращение через точку. Обратите внимание, что мы не можем использовать поле seasonal_fruit в eat_at_restaurant, потому что seasonal_fruit является приватным. Попробуйте раскомментировать последнюю строчку, пытающуюся использовать значение поля seasonal_fruit, чтобы увидеть, какую ошибку вы получите!

Также обратите внимание, что поскольку back_of_house::Breakfast имеет приватное поле, то структура должна предоставить публичную ассоциированную функцию, которая создаёт экземпляр Breakfast (мы назвали её summer). Если бы Breakfast не имел такой функции, мы бы не могли создать экземпляр Breakfast внутри eat_at_restaurant, потому что мы не смогли бы установить значение приватного поля seasonal_fruit в функции eat_at_restaurant.

В отличие от структуры, если мы сделаем общедоступным перечисление, то все его варианты будут общедоступными. Нужно только указать 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 общедоступным, мы можем использовать варианты Soup и Salad в функции eat_at_restaurant.

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

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

Добавление путей в область видимости ключевым словом use

Необходимость записывать пути к функциям вызова может показаться неудобной и многословной. В Листинге 7-7 независимо от того, выбирали ли мы абсолютный или относительный путь к функции add_to_waitlist, каждый раз, когда мы хотели вызвать add_to_waitlist, нам приходилось также указывать front_of_house и hosting. К счастью, есть способ упростить этот процесс: мы можем один раз создать псевдоним на путь при помощи ключевого слова use, а затем использовать более короткое имя везде в области видимости.

В Листинге 7-11 мы подключили модуль crate::front_of_house::hosting в область видимости функции eat_at_restaurant, поэтому нам достаточно только указать hosting::add_to_waitlist для вызова функции add_to_waitlist внутри eat_at_restaurant.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Добавление use и пути в область видимости аналогично созданию символической ссылки в файловой системе. С добавлением use crate::front_of_house::hosting в корневой модуль крейта, hosting становится допустимым именем в этой области, как если бы модуль hosting был определён в корне крейта. Пути, подключённые в область видимости с помощью use, также проверяются на приватность, как и любые другие пути.

Обратите внимание, что 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]: failed to resolve: use of undeclared crate or module `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of undeclared crate or module `hosting`
   |
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

Обратите внимание, что есть также предупреждение о том, что 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 выполняют одну и ту же задачу, Листинг 7-11 является идиоматическим способом подключения функции в область видимости с помощью use. Подключение родительского модуля функции в область видимости при помощи use означает, что мы должны указывать родительский модуль при вызове функции. Указание родительского модуля при вызове функции даёт понять, что функция не определена локально, но в то же время сводя к минимуму повторение полного пути. В коде Листинга 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

Есть другое решение проблемы добавления словом use двух типов с одинаковыми именами в одну и ту же область видимости: после пути можно указать as и новое локальное имя (или псевдоним) для типа. Листинг 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 мы выбрали новое имя IoResult для типа std::io::Result, которое теперь не будет конфликтовать с типом Result из std::fmt, который также подключён в область видимости. Оба Листинга 7-15 и 7-16 считаются идиоматичными, так что выбор за вами!

Реэкспорт имён с pub use

Когда мы подключаем имя в область видимости, используя ключевое слово use, то имя, доступное в новой области видимости, является приватным. Чтобы позволить коду, который вызывает наш код, ссылаться на это имя, как если бы оно было определено в области видимости данного кода, можно объединить pub и use. Этот метод называется реэкспортом, потому что мы подключаем элемент в область видимости, но также делаем этот элемент доступным для подключения в других областях видимости.

Листинг 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(). Теперь, поскольку это объявление pub use реэкспортировало модуль hosting из корневого модуля, внешний код теперь может использовать вместо него путь restaurant::hosting::add_to_waitlist().

Реэкспорт полезен, когда внутренняя структура вашего кода отличается от того, как программисты, вызывающие ваш код, думают о предметной области. Например, по аналогии с рестораном люди, управляющие им, думают о "front of house" и "back of house". Но клиенты, посещающие ресторан, вероятно, не будут думать о частях ресторана в таких терминах. Используя pub use, мы можем написать наш код с одной структурой, но сделать общедоступной другую структуру. Благодаря этому наша библиотека хорошо организована и для программистов, работающих над библиотекой, и для программистов, вызывающих библиотеку. Мы рассмотрим ещё один пример pub use и его влияние на документацию вашего крейта в разделе "Экспорт удобного общедоступного API с pub use" Главы 14.

Использование внешних пакетов

В Главе 2 мы запрограммировали игру в угадайку, где использовался внешний пакет с именем rand для генерации случайного числа. Чтобы использовать rand в нашем проекте, мы добавили эту строку в Cargo.toml.

rand = "0.8.5"

Добавление rand в качестве зависимости в Cargo.toml указывает Cargo загрузить пакет rand и все его зависимости с crates.io и сделать rand доступным для нашего проекта.

Затем, чтобы подключить определения rand в область видимости нашего пакета, мы добавили строку use, начинающуюся с названия пакета rand и списка элементов, которые мы хотим подключить в область видимости. Напомним, что в разделе "Генерация секретного числа"Главы 2 мы подключили трейт Rng в область видимости и вызвали функцию rand::thread_rng:

use std::io;
use rand::Rng;

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {guess}");
}

Участники Сообщества Rust создали множество пакетов, доступных на crates.io, и добавление любого из них в ваш пакет включает в себя одни и те же шаги: нужно перечислить их в файле Cargo.toml вашего пакета и использовать use для подключения элементов внешних пакетов в область видимости.

Обратите внимание, что стандартная библиотека std также является крейтом, внешним по отношению к нашему пакету. Поскольку стандартная библиотека поставляется с языком Rust, нам не нужно изменять Cargo.toml для подключения std. Но нам нужно ссылаться на неё при помощи use, чтобы добавить элементы оттуда в область видимости нашего пакета. Например, с HashMap мы использовали бы эту строку:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Это абсолютный путь, начинающийся с std, имени крейта стандартной библиотеки.

Использование перечисления путей для сокращения строчек use

Если мы используем несколько элементов, определённых в одном крейте или в том же модуле, то перечисление каждого элемента в отдельной строке может занимать много вертикального пространства в файле. Например, эти две инструкции use используются в нашей игре в угадайку (Листинг 2-4) для подключения элементов из std в область видимости:

use rand::Rng;
// --код сокращён--
use std::cmp::Ordering;
use std::io;
// --код сокращён--

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    println!("Вы предположили: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Слишком маленькое!"),
        Ordering::Greater => println!("Слишком большое!"),
        Ordering::Equal => println!("Вы победили!"),
    }
}

Вместо этого, мы можем использовать перечисление путей, чтобы добавить эти элементы в область видимости одной строкой. Это делается, как показано в Листинге 7-18: указывается общая часть пути, за которой следуют два двоеточия, а затем фигурные скобки вокруг списка тех частей пути, которые отличаются.

use rand::Rng;
// --код сокращён--
use std::{cmp::Ordering, io};
// --код сокращён--

fn main() {
    println!("Угадайте число!");

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

    println!("Загаданное число: {secret_number}");

    println!("Введите свою догадку.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Не удалось прочесть ввод.");

    let guess: u32 = guess.trim().parse().expect("Пожалуйста, введите число!");

    println!("Вы предположили: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Слишком маленькое!"),
        Ordering::Greater => println!("Слишком большое!"),
        Ordering::Equal => println!("Вы победили!"),
    }
}

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

Оператор *

If we want to bring all public items defined in a path into scope, we can specify that path followed by the * glob operator:

#![allow(unused)]
fn main() {
use std::collections::*;
}

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

Оператор * часто используется при тестировании для подключения всего, что есть в модуле tests; мы поговорим об этом в разделе "Как писать тесты" Главы 11. Оператор * также иногда используется как часть шаблона prelude: обратитесь к документации стандартной библиотеки для получения дополнительной информации.

Размещение модулей в разных файлах

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

Для начала, давайте рассмотрим код Листинга 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 — это не операция "подключения", которую вы могли видеть в других языках программирования.

Далее мы извлечём модуль 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. Правила компилятора для проверки того, какие файлы содержат код каких модулей, предполагают, что каталоги и файлы точно соответствуют дереву модулей.

Альтернативные пути к файлам

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

• src/front_of_house.rs (современный стиль; использовался нами до сих пор)
• src/front_of_house/mod.rs (старый стиль; всё ещё поддерживается)

Для модуля с именем hosting, который является подмодулем front_of_house, компилятор будет искать код модуля в:

• src/front_of_house/hosting.rs (современный стиль; использовался нами до сих пор)
• src/front_of_house/hosting/mod.rs (старый стиль; всё ещё поддерживается)

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

Основным недостатком стиля, в котором используются файлы с именами mod.rs, является то, что в вашем проекте может оказаться много файлов с именами mod.rs, что может привести к путанице, если вы одновременно откроете их в редакторе.

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

Обратите внимание, что инструкция pub use crate::front_of_house::hosting в src/lib.rs также не изменилась, и use не влияет на то, какие файлы компилируются как часть крейта. Ключевое слово mod объявляет модули, и Rust ищет код, который входит в этот модуль, в файле с тем же именем, что и у модуля.

Подведём итоги

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

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

Стандартные коллекции данных

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

• Вектор — последовательный, перменной длины список значений.
• Строка — последовательность символов. Мы ранее уже говорили о типе String, но в этой главе мы обсудим строки подробнее.
• Хеш-таблица — набор пар ключ-значение. Является конкретной реализацией более общей структуры данных, известной как ассоциативный массив.

Для того, чтобы узнать о других видах коллекций, предоставляемых стандартной библиотекой, посмотрите в [документацию] (https://doc.rust-lang.org/std/collections/index.html).

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

Хранение списка значений с помощью векторов

Первым типом коллекции, который мы разберём, будет 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!("Третий элемент: {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("Третий элемент: {third}"),
        None => println!("Третьего элемента не содержится."),
    }
}

Обратите внимание на пару деталей. Мы используем значение индекса 2 для получения третьего элемента, так как векторы индексируются с нуля. Указывая &и [], мы получаем ссылку на элемент по указанному индексу. Когда мы используем метод get, мы получаем тип Option<&T>, который мы можем обработать в match.

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

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

Если у программы есть действительная ссылка, анализатор заимствований обеспечивает соблюдение правил владения и заимствования (описанные в Главе 4), чтобы гарантировать, что эта ссылка и любые другие ссылки на содержимое вектора остаются действительными. Вспомните правило, которое гласит, что у вас не может быть изменяемых и неизменяемых ссылок в одной и той же области. Именно его нарушает код в Листинге 8-6, где мы пытаемся хранить неизменяемую ссылку на первый элемент вектора и затем пытаемся добавить элемент в конец вектора. Эта программа не будет работать, если мы также попытаемся обратиться к этому элементу позже в функции.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("Первый элемент: {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!("Первый элемент: {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 может выглядеть так, как будто он должен работать: в конце концов, как ссылке на первый элемент могут помешать изменения в конце вектора? Эта ошибка возникает из-за особенности того, как векторы работают: поскольку векторы размещают значения в памяти друг за другом, добавление нового элемента в конец вектора может потребовать выделения новой памяти и копирования старых элементов в новое пространство, если нет достаточного места, чтобы разместить все элементы друг за другом там, где в данный момент хранится вектор. В этом случае ссылка на первый элемент окажется указывающей на высвобождённую память. Правила заимствования предотвращают попадание программ в такую ситуацию.

Примечание: Дополнительные сведения о реализации типа Vec<T> можно найти в пособии "The Rustonomicon".

Итерирование по содержимому вектора

Чтобы получить доступ к каждому значению в векторе, мы можем проитерироваться по всем элементам, вместо того, чтобы использовать индексы для доступа к одному элементу за раз. В Листинге 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("синий")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust должен знать во время компиляции, какие типы будут в векторе, чтобы точно знать сколько, памяти в куче потребуется для хранения каждого элемента. Мы также должны чётко указать, какие типы разрешены в этом векторе. Если бы Rust позволял вектору содержать любой тип, то был бы шанс, что один или несколько типов вызовут ошибки при выполнении операций над элементами вектора. Использование перечисления вместе с выражением match означает, что во время компиляции Rust гарантирует, что все возможные случаи будут обработаны, как обсуждалось в Главе 6.

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

Теперь, когда мы обсудили некоторые из наиболее распространённых способов использования векторов, обязательно ознакомьтесь с документацией API, чтобы узнать о множестве полезных методов, определённых для Vec<T> стандартной библиотекой. Например, в дополнение к методу push, существует метод pop, который удаляет и возвращает последний элемент.

Высвобождение вектора высвобождает его элементы

Подобно структурам, вектор высвобождает свою память, когда выходит из области видимости, как показано в Листинге 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // какая-нибудь работа с v
    } // <- здесь v покидает область видимости и высвобождается
}

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

Перейдём к следующей коллекции: String.

Хранение текста в кодировке UTF-8 с помощью строк

Мы уже говорили о строках в Главе 4, но пришло время рассмотреть их более подробно. Новички в Rust обычно застревают на строках из-за трёх причин: 1) пристрастие компилятора Rust к выявлению возможных ошибок, 2) строки сложнее, чем (как многим программистам кажется) могли бы быть, и 3) UTF-8. Эти факторы объединяются таким образом, что текущая тема может показаться сложной, если вы пришли из других языков программирования.

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

Что такое строка?

Сначала мы определим значение термина строка. В ядре языка Rust есть лишь один строковый тип — срез строки str, обычно используемый в заимствованном виде как &str. В Главе 4 мы говорили о срезах строк, которые являются ссылками на некоторые строковые данные в кодировке UTF-8. Например, строковые литералы хранятся в двоичном файле программы и потому являются срезами строк.

Тип String, предоставляемый стандартной библиотекой Rust, не встроен в ядро языка. Он является расширяемым, изменяемым, владеющим строковым типом текста в кодировке 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 = "исходный текст";

    let s = data.to_string();

    // Этот метод также можно вызвать напрямую на литерале:
    let s = "исходный текст".to_string();
}

Этот код создаёт строку с текстом исходный текст.

Мы также можем использовать функцию String::from для создания String из строкового литерала. Код Листинга 8-13 является эквивалентным коду из Листинга 8-12, использующему функцию to_string:

fn main() {
    let s = String::from("исходный текст");
}

Поскольку строки используются для очень многих вещей, для них есть много инструментов, решающих одну и ту же задачу. Некоторые из них могут показаться избыточными, но у всех них есть свой смысл! В данном случае, 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> при вставке в него дополнительных данных. Кроме того, можно использовать оператор + или макрос format! для объединения нескольких String в одну.

Присоединение к строке с помощью 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: {s2}");
}

Если бы метод push_str стал владельцем переменной s2, мы не смогли бы напечатать его значение в последней строке. Однако этот код работает так, как мы ожидали!

Метод push принимает один символ в качестве параметра и добавляет его к String. В Листинге 8-17 показан код, добавляющий букву e к String, используя метод push.

fn main() {
    let mut s = String::from("not");
    s.push('e');
}

В результате s будет содержать note.

Объединение строк с помощью оператора + или макроса 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: мы можем добавить только &str к String; мы не можем сложить два значения String. Но подождите: тип &s2 — это &String, а не &str, который мы определили во втором параметре add. Так почему код в Листинге 8-18 компилируется?

Причина, по которой мы можем использовать &s2 в вызове add заключается в том, что компилятор может привести аргумент типа &String к типу &str. Когда мы вызываем метод add, Rust использует приведение ссылок при разыменовывании, которое превращает &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!, использует ссылки, а значит не забирает во владение ни одну из переданных строк.

Обращение к строке по индексу

Доступ к отдельным символам в строке с помощью взятия ссылки на них по индексу является допустимой и распространённой операцией во многих других языках программирования. Тем не менее, если вы попытаетесь получить доступ к частям String, используя синтаксис индексации, то получите ошибку. Рассмотрим неверный код Листинга 8-19.

fn main() {
    let s1 = String::from("hello");
    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}`, which is required by `String: Index<_>`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the trait `SliceIndex<[_]>` is implemented for `usize`
  = help: for that trait implementation, expected `[_]`, found `str`
  = 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. Но как насчёт следующей строки?

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. Так происходит потому, что каждый символ Unicode в этой строке занимает 2 байта памяти. Следовательно, обращение по индексу к отдельным байтам строки не всегда бы соответствовало полноценному символу Unicode. Для демонстрации рассмотрим этот (недопустимый) код Rust:

let hello = "Здравствуйте";
let answer = &hello[0];

Вы уже знаете, что answer не будет содержать З — первую букву строки, но не первый байт. При кодировке в UTF-8, первый байт буквы З равен 208, а второй — 151, поэтому значение в answer на самом деле должно быть 208, но само по себе 208 не является действительным символом. Число 208 — это, скорее всего, не то, что хотел бы получить пользователь: ведь он ожидает первую букву этой строки; тем не менее, именно это является лучшим, что Rust мог бы предоставлять по индексу 0. Пользователи обычно не хотят получать сырые байты, даже если строка содержит только латинские буквы: если бы &"hi"[0] было допустимым кодом, который возвращал байтовое значение, он возвращал бы 104, а не h.

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

Байты, символы Unicode и кластеры графем

Another point about UTF-8 is that there are actually three relevant ways to look at strings from Rust’s perspective: as bytes, scalar values, and grapheme clusters (the closest thing to what we would call letters).

Если посмотреть на слово "नमस्ते" языка хинди, написанное письмом деванагари, то оно хранится как вектор значений u8, который выглядит следующим образом:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Эти 18 байт являются именно тем, как компьютеры в конечном итоге сохранят в памяти эту строку. Если мы посмотрим на это слово как на символы Unicode (которыми и является тип char), то байты предстанут перед нами в таком виде:

['न', 'म', 'स', '्', 'त', 'े']

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

["न", "म", "स्", "ते"]

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

Последняя причина, по которой Rust не позволяет нам обращаться к String по индексу для получения символов, является то, что программисты ожидают, что операции индексирования всегда имеют постоянное время выполнения — O(1). Но невозможно гарантировать такую производительность для String, потому что Rust понадобилось бы проходиться по содержимому от начала до индекса, чтобы определить, сколько было действительных символов.

Взятие срезов строк

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

Вместо индексации с помощью указания индекса в [], вы можете использовать в [] оператор диапазона, чтобы создавать срез строки:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Здесь переменная s будет иметь тип &str и содержаит первые четыре байта строки. Ранее мы упоминали, что каждый из этих символов занимал по два байта, что означает, что 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' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

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

Методы для перебора строк

Лучший способ работать с фрагментами строк — чётко указать, нужны ли вам символы или байты. Для получения символов Unicode используйте метод chars. Вызов chars на "Зд" выделит и вернёт два значения типа char, и вы можете проитерироваться по результату для доступа к каждому элементу:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Код напечатает следующее:

З
д

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

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Этот код выведет четыре байта, составляющих эту строку:

208
151
208
180

Но делая так, обязательно помните, что символы Unicode могут состоять более чем из одного байта.

Извлечение кластеров графем из строк, как в случае с письмом деванагари, является сложным, поэтому эта функциональность не предусмотрена стандартной библиотекой. На crates.io можно найти крейты с необходимыми вам инструментами.

Строки не так просты

Подводя итог, становится ясно, что строки сложны. Различные языки программирования реализуют строки по-своему, и все — по-своему сложно. В Rust решили сделать правильную обработку данных String поведением по умолчанию для всех программ Rust, что означает, что программисты должны заранее продумать обработку текста в кодировке UTF-8. Этот компромисс раскрывает большую сложность строк, чем в других языках программирования, но это предотвращает от необходимости обрабатывать ошибки, связанные с не-ASCII символами, которые могут появиться позже в ходе разработки.

Хорошая новость состоит в том, что стандартная библиотека предлагает множество инструментов для типов String и &str, которые могут помочь правильно обрабатывать эти сложные ситуации. Обязательно ознакомьтесь с документацией, чтобы узнать о таких полезных методах, как contains (для поиска в строке) и replace (для замены частей строки другой строкой).

Давайте переключимся на что-то немного менее сложное: хеш-таблицы!

Хранение пар ключ-значение с помощью хеш-таблиц

Последней коллекцией, которую мы рассмотрим, будет хеш-таблица. Тип HashMap<K, V> хранит ключи типа K ко значениям типа V, используя функцию хеширования. Во множестве языков программирования есть данная структура, но часто она по-разному называется: hash_, map, object, словарь или ассоциативный массив.

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

В этом разделе мы рассмотрим лишь основной API хеш-таблиц, но стандартная библиотека содержит ещё очень много полезного для HashMap<K, V>. Как и прежде, советуем обращаться к документации стандартной библиотеки для получения дополнительной информации.

Создание хеш-таблицы

One way to create an empty hash map is to use new and to add elements with insert. In Listing 8-20, we’re keeping track of the scores of two teams whose names are Blue and Yellow. The Blue team starts with 10 points, and the Yellow team starts with 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Синяя"), 10);
    scores.insert(String::from("Жёлтая"), 50);
}

Обратите внимание, что сначала нужно подключить HashMap из стандартной библиотеки с помощью use. Из трёх коллекций данная является наименее используемой, поэтому она не входит в функционал, по умолчанию подключаемый к области видимости (коротко говоря, в prelude). Хеш-таблицы также слабее поддерживаются стандартной библиотекой; например, нет встроенного макроса для их конструирования.

Подобно векторам, хеш-таблицы хранят свои данные в куче. Здесь тип HashMap имеет в качестве типа ключей String, а в качестве типа значений — i32. Как и векторы, HashMap однородны: все ключи должны иметь одинаковый тип, и все значения тоже должны иметь одинаковый тип.

Получение данных из хеш-таблицы

Мы можем получить значение из хеш-таблицы, использовав метод get и передав ему ключ, как показано в Листинге 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Синяя"), 10);
    scores.insert(String::from("Жёлтая"), 50);

    let team_name = String::from("Синяя");
    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("Синяя"), 10);
    scores.insert(String::from("Жёлтая"), 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("Любимая команда:");
    let field_value = String::from("Синяя");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name и field_value отсюда и далее недоступны. Но вы попробуйте использовать
    // их и посмотрите, что за ошибку компиляции получите!
}

Мы не можем использовать переменные field_name и field_value после того, как их значения были перемещены в хеш-таблицу вызовом метода insert.

Если мы вставим в хеш-таблицу ссылки на значения, то значения не будут перемещены в хеш-таблицу. Значения, на которые указывают ссылки, должны быть действительными как минимум пока действительна хеш-таблица. Мы поговорим подробнее об этих вопросах в разделе "Валидация ссылок по времени жизни" Главы 10.

Обновление данных в хеш-таблице

Хотя количество ключей и значений в хеш-таблице может быть изменено, каждый ключ в один момент может иметь только одно значение (обратное утверждение неверно: команды "Синяя" и "Жёлтая" могут хранить в хеш-таблице scores одинаковое количество очков: например, 10).

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

Перезапись значения

Если мы вставим ключ и значение в хеш-таблицу, а затем вставим такой же ключ с новым значением, то старое значение, связанное с этим ключом, будет заменено на новое. Даже несмотря на то, что код в Листинге 8-23 вызывает insert дважды, хеш-таблица будет содержать только одну пару ключ-значение, потому что мы вставляем значения для одного и того же ключа — ключа синей команды.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Синяя"), 10);
    scores.insert(String::from("Синяя"), 25);

    println!("{scores:?}");
}

Код напечатает {"Синяя": 25}. Начальное значение 10 было перезаписано.

Вставка значения только в том случае, если ключ вводится впервые

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

Хеш-таблицы имеют для этого специальный метод entry, который принимает ключ, наличие которого нужно проверить. Возвращаемое значение метода entry — это перечисление Entry, представляющего значение, которое может как присутствовать, так и отсутствовать. Допустим, мы хотим проверить, имеется ли ключ и связанное с ним значение для жёлтой команды. Если хеш-таблица не имеет значения для такого ключа, то мы хотим вставить значение 50. То же самое мы хотим проделать и для синей команды. Использование entry показано в коде Листинга 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Синяя"), 10);

    scores.entry(String::from("Жёлтая")).or_insert(50);
    scores.entry(String::from("Синяя")).or_insert(50);

    println!("{scores:?}");
}

Метод or_insert определён в Entry так, чтобы возвращать изменяемую ссылку на соответствующее значение ключа внутри варианта перечисления Entry, когда этот ключ существует, а если его нет, то вставлять параметр в качестве нового значения этого ключа и возвращать изменяемую ссылку на новое значение. Эта техника намного чище, чем самостоятельное написание логики и, кроме того, она более безопасна и согласуется с правилами заимствования.

При выполнении кода Листинга 8-24 будет напечатано {"Жёлтая": 50, "Синяя": 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, которая может противостоять атакам класса Denial of Service (DoS) с использованием хеш-таблиц¹. Это не самый быстрый из возможных алгоритмов хеширования, но в данном случае производительность идёт на компромисс с обеспечением лучшей безопасности. Если после профилирования вашего кода окажется, что хеш-функция, используемая по умолчанию, очень медленная, вы можете заменить её используя другой хешер. Хешер — это тип, реализующий трейт BuildHasher. Подробнее о трейтах мы поговорим в Главе 10. Вам совсем не обязательно реализовывать свою собственную функцию хеширования; на crates.io есть достаточное количество библиотек, предоставляющих разные реализации хешеров с множеством общих алгоритмов хеширования.

Подведём итоги

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

1. Дан список целых чисел. Использовав вектор, напишите функции получения медианы (значение элемента из середины списка после его сортировки) и моды (наиболее частое значение; подсказка: используйте хеш-таблицы) списка чисел.
2. Переведите текст с английского на поросячью латынь. Первая согласная каждого слова перемещается в конец и к ней добавляется окончание ay (пример: first станет irst-fay). К слову, начинающемуся на гласную, в конец добавляется hay (пример: apple становится apple-hay). Помните о деталях работы с кодировкой UTF-8!
3. Используя хеш-таблицу и векторы, создайте текстовый интерфейс, позволяющий пользователю приписывать сотрудников по их именам к отделам компании. Например, Add Sally to Engineering или Add Amir to Sales. Затем позвольте пользователю получить список всех людей из отдела или всех людей в компании, отсортированный по отделам в алфавитном порядке.

Документация API стандартной библиотеки содержит описания методов векторов, строк и хеш-таблиц. Рекомендуем пользоваться ей при решении упражнений!

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

Обработка ошибок

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

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

Большинство языков не различают эти два вида ошибок и обрабатывают их одинаково, используя такие механизмы, как исключения. В Rust нет исключений. В качестве альтернативы в нём есть тип Result<T, E> (для исправимых ошибок) и макрос panic!, который останавливает исполнение, когда программа встречает неисправимую ошибку. Сначала речь пойдёт про вызов макроса panic!, а потом — о возврате значений Result<T, E>. Кроме того, мы рассмотрим, что нужно учитывать при принятии решения о том, следует ли попытаться исправить ошибку или остановить исполнение.

Неисправимые ошибки с panic!

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

Раскрутить стек или прервать исполнение программы?

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

Память, которую использовала программа, должна быть очищена операционной системой. Если в вашем проекте нужно сделать исполняемый файл маленьким настолько, насколько это возможно, вы можете прямо указать программе прерывать исполнение в случае паники, добавив panic = 'abort' в соответствующие разделы [profile] вашего файла Cargo.toml. Например, если вы хотите прерывать панику в релизном режиме, добавьте это:

[profile.release]
panic = 'abort'

Давайте попробуем вызвать panic! в простой программе:

fn main() {
    panic!("критическая ошибка");
}

При запуске программы вы увидите подобный вывод:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`
thread 'main' panicked at src/main.rs:2:5:
критическая ошибка
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Выполнение макроса panic! вызывает сообщение об ошибке, представленное в двух последних строчках выше. Первая строчка содержит сообщение паники и место в исходном коде, где возникла паника: запись src/main.rs:2:5 указывает на второй строчки пятый символ внутри файла src/main.rs.

В нашем случае, сообщение об ошибке указывает на наш собственный код, и если мы перейдём к этой строке, мы увидим вызов макроса panic!. В других случаях вызов panic! мог бы произойти в стороннем коде, вызываемом нашим, и тогда имя файла и номер строки указывали бы именно туда, где конкретно вызывается макрос panic!, а не на тот код, вызов которого привёл к вызову panic!.

Мы можем использовать развёртку вызовов функций, приводящих к вызову panic!, чтобы выяснить, какая часть нашего кода вызывает проблему. Чтобы понять, как использовать развёртку вызова panic!, давайте рассмотрим другой пример и посмотрим, каково это, когда panic! вызывается не напрямую через вызов макроса, а в библиотечном коде, содержащем баг. В Листинге 9-1 приведен некоторый код, который пытается получить доступ элементу вектора по индексу, лежащему за пределами вектора.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Здесь мы пытаемся получить доступ к 100му элементу вектора (который находится по индексу 99, потому что индексирование начинается с нуля), но вектор имеет только 3 элемента. В этой ситуации, 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' 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/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/std/src/panicking.rs:662:5
   1: core::panicking::panic_fmt
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/panicking.rs:74:14
   2: core::panicking::panic_bounds_check
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/panicking.rs:276:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/slice/index.rs:302:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/vec/mod.rs:2920:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/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! и того, когда нам следует и не следует его использовать для обработки ошибок, в разделе "Когда следует использовать panic!?" этой главы. Далее мы рассмотрим, как можно продолжить исполнение программы после ошибки, воспользовавшись типом Result.

Исправимые ошибки с Result

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

Вспомните про перечисление Result и его варианты Ok и Err, которыми мы пользовались в разделе "Обработка возможных ошибок с помощью Result" Главы 2. Его определение выглядит так:

#![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, содержащий дескриптор файла. В случае неудачи, значение в переменной greeting_file_result будет экземпляром 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!("При открытии файла произошла ошибка: {error:?}"),
    };
}

Обратите внимание, что как перечисление Option, так и перечисление Result и его варианты подключаются в область видимости по умолчанию, поэтому не нужно указывать Result:: перед использованием вариантов Ok и Err в ветках выражения match.

Если результатом будет Ok, этот код вернёт значение file из варианта Ok, а мы затем присвоим переменной greeting_file полученный дескриптор файла. После match мы сможем его для чтения или записи.

Другая ветвь match обрабатывает случай, когда мы получаем значение Err после вызова File::open. В этом примере мы решили вызвать макрос 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' panicked at src/main.rs:8:23:
При открытии файла произошла ошибка: 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 не удалось из-за отсутствия файла, то файл создавался и возвращался его дескриптор. Если же вызов 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!("При создании файла произошла ошибка: {e:?}"),
            },
            other_error => {
                panic!("При открытии файла произошла ошибка: {other_error:?}");
            }
        },
    };
}

Типом значения ошибки, возвращаемого функцией File::open в варианте Err, является io::Error — структура из стандартной библиотеки. Данная структура имеет метод kind, который можно вызвать для получения значения io::ErrorKind. Перечисление io::ErrorKind имеет варианты, представляющие различные типы ошибок, которые могут появиться при выполнении операций ввода-вывода. Вариант, который мы хотим сейчас использовать — ErrorKind::NotFound. Он сообщает о том, что файл, который мы пытаемся открыть, не существует. Во второй строчке нашей программы мы передаём greeting_file_result в выражение match; если произойдёт ошибка, мы вызовем на ней метод kind() и передадим возвращаемое значение во вложенный match.

Во вложенном match мы хотим проверить, не является ли значение, возвращаемое функцией error.kind(), вариантом NotFound перечисления ErrorKind. Если оно является, то мы пытаемся создать файл с помощью File::create. Однако, поскольку File::create тоже может завершиться с ошибкой, нам нужна вторая ветвь во вложенном match. Если файл не может быть создан, выводится иное сообщение об ошибке. Вторую ветвь внешнего match мы не меняем. Итого, программа паникует при любой ошибке, кроме ошибки отсутствия файла.

Альтернативы использованию match с Result<T, E>

Как много match! Выражение match является очень полезным, но в то же время довольно примитивным. В Главе 13 вы узнаете о замыканиях, которые используются со многими методами типа Result<T, E>. Эти методы куда лаконичнее, чем прямая обработка значений Result<T, E> через match.

Например, программу из Листинга 9-5 можно вот так переписать с использованием замыканий и метода unwrap_or_else:

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!("При создании файла произошла ошибка: {error:?}");
            })
        } else {
            panic!("При открытии файла произошла ошибка: {error:?}");
        }
    });
}

Хотя данный код имеет такое же поведение, как и код Листинга 9-5, он не содержит ни одного выражения match и, плюсом, легче читается. Рекомендуем вам вернуться к этому примеру после того, как прочитаете Главу 13 и заглянете в документацию метода unwrap_or_else. С этими методами вы сможете обрабатывать ошибки без необходимости писать многоуровневые выражения match.

Простая паника при ошибке: методы unwrap и expect

Использование match работает достаточно хорошо, но оно может быть довольно многословным и не всегда хорошо передавать смысл. Тип Result<T, E> имеет множество вспомогательных методов для выполнения различных, более специфических задач. Метод unwrap — это метод, реализованный так же, как и выражение match, которое мы написали в Листинге 9-4. Если значение Result является вариантом Ok, unwrap возвращает значение внутри Ok. Если значение Result — вариант 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" }

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

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt должен быть доступен этому проекту");
}

Метод expect используется так же, как unwrap: либо возвращается дескриптор файла, либо вызывается макрос panic!. Наше сообщение об ошибке, переданное expect, будет передано в panic! и заменит стандартное используемое сообщение. Вот как это выглядит:

thread 'main' panicked at src/main.rs:5:10:
hello.txt должен быть доступен этому проекту: Os { code: 2, kind: NotFound, message: "No such file or directory" }

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

Проброс ошибок

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

Например, код Листинга 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 — имя пользователя, прочитанное этой функцией из файла. Если функция столкнётся с какими-либо проблемами, вызывающий код получит значение Err, содержащее экземпляр io::Error, который содержит дополнительную информацию о том, какие проблемы возникли. Мы выбрали io::Error в качестве возвращаемого типа этой функции, поскольку он — тип значения ошибки, возвращаемого из обеих операций, которые мы вызываем в теле этой функции и которые могут завершиться неудачей: функции File::open и метода read_to_string.

Тело функции начинается с вызова File::open. Затем мы обрабатываем значение Result с помощью match, аналогично match из Дистинга 9-4. Если File::open завершается успешно, то дескриптор файла в file (переменной шаблона) становится значением в изменяемой переменной username_file, и функция продолжает свою работу. В случае неудачи, вместо вызова panic! мы используем ключевое слово return для досрочного возвращения значения ошибки из File::open (которое было сохранено в e — переменной шаблона) обратно в вызывающий код как значение ошибки этой функции.

Таким образом, если у нас есть файловый дескриптор в username_file, функция создаёт новую String в переменной username и вызывает метод read_to_string на файловом дескрипторе (который в username_file), чтобы записать содержимое файла в username. Метод read_to_string также возвращает Result, потому что он может потерпеть неудачу, даже если File::open завершился успешно. Поэтому нам нужен ещё один match для обработки этого Result. Если 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, читает содержимое файла, размещает его в String и возвращает её. Конечно, использование функции fs::read_to_string не даёт возможности объяснить обработку всех ошибок, поэтому мы сначала изучили длинный способ.

Где можно использовать оператор ?

Оператор ? может использоваться только в функциях, тип возвращаемого значения которых совместим со значением, для которого используется ?. Это потому что оператор ? определён так, чтобы выполнять преждевременный возврат значения из функции таким же образом, как и выражение match, определённое в Листинге 9-6. В Листинге 9-6 match использовало значение Result, а ветвь с преждевременным возвратом значения вернула значение Err(e). Тип возвращаемого значения функции должен быть Result, чтобы он был совместим с этим return.

Давайте посмотрим на ошибку, которую мы получим, если воспользуемся оператором ? в функции main с типом возвращаемого значения, несовместимым с типом значения, для которого мы используем ?. Взгляните на Листинг 9-10:

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: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not implemented for `()`
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.

Для исправления ошибки есть два варианта. Один — изменить возвращаемый тип вашей функции так, чтобы он был совместим со значением, для которого вы используете оператор ?, если ничто этому не препятствует. Другой — использовать match или один из методов Result<T, E> для обработки 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("Привет!\nКак ты?"),
        Some('!')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nсойдёт"), None);
}

Эта функция возвращает Option<char>, потому что может быть, что строка будет не пустой и символ будет найден, а может быть, что его и не будет. Этот код принимает строковый срез text и вызывает на нём метод lines, который возвращает итератор всех строчек в строке. Поскольку эта функция хочет проверить первую строку, она вызывает next у итератора, чтобы получить первое значение от итератора. Если text является пустой строкой, этот вызов next вернёт None, и в этом случае мы используем ? чтобы остановить и вернуть None из last_char_of_first_line. Если text не является пустой строкой, next вернёт значение Some, содержащее строковый срез первой строки в text.

Символ ? извлекает строковый срез, и мы можем вызвать на нём метод chars, чтобы получить итератор символов. Нас интересует последний символ в первой строке, поэтому мы вызываем last, чтобы вернуть последний элемент в итераторе. Вернётся Option, потому что возможно, что первая строка пуста: например, если text начинается с пустой строки, но имеет символы в других строках, как в "\nсойдёт". Однако, если в первой строке есть последний символ, он будет возвращён в варианте 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, а программы с ошибкой возвращают целое число, отличное от 0. Rust также возвращает целые числа из программ, чтобы быть совместимым с этим соглашением.

Функция main может возвращать любые типы, реализующие трейт std::process::Termination, который содержит функцию report, возвращающую ExitCode. Обратитесь к документации стандартной библиотеки за дополнительной информацией о реализации трейта Termination для ваших собственных типов.

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

Когда следует использовать panic!?

Итак, как принять решение о том, когда следует вызывать panic!, а когда вернуть Result? После паники восстановить исполнение уже нельзя. Можно было бы вызывать panic! для любой ошибочной ситуации, независимо от того, имеется ли способ обработать случившуюся проблему, но таким образом вы отбираете у вызывающего кода право определять, критична ли ситуация или нет. Если же вы возвращаете значение Result, вы отдаёте принятие решения вызывающему коду. Вызывающий код может попытаться устранить ошибку способом, который подходит в данной ситуации, или же он может решить, что ошибка в Err неисправима, и вызовет panic!, превратив вашу исправимую ошибку в неисправимую. Следовательно, из функции, вызов которой может завершиться неудачей, лучше возвращать Result.

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

Примеры, прототипы и тесты

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

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

Если в тесте происходит сбой при вызове метода, то вы бы хотели, чтобы весь тест не прошёл, даже если этот метод не является тестируемой функциональностью. Поскольку вызов panic! — это способ, которым тест помечается как провалившийся, использование unwrap или expect — именно то, что нужно.

Случаи, когда вы знаете больше, чем компилятор

Также было бы целесообразно вызывать unwrap или expect, когда у вас есть какая-то другая логика, которая гарантирует, что Result будет иметь значение Ok, но вашу логику не понимает компилятор. У вас по-прежнему будет значение Result, которое нужно обработать: любая операция, которую вы вызываете, все ещё имеет возможность неудачи в целом, хотя это логически невозможно в вашей конкретной ситуации. Если, проверяя код вручную, вы можете убедиться, что никогда не возникнет значение Err, то вполне допустимо вызывать unwrap, а ещё лучше задокументировать в тексте 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-адрес. Если строка IP-адреса пришла от пользователя, то мы ничего не знаем заранее о её корректности, и, следовательно, можем с ней получить ошибку. В таком случае мы определённо хотели бы обработать Result более надёжным способом. Упоминание предположения о том, что текущий используемый IP-адрес однозначно корректный — это метка, указывающая нам на необходимость изменить expect для лучшей обработки ошибок, если в будущем нам потребуется вместо этого получить IP-адрес из какого-либо другого источника.

Руководство по обработке ошибок

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

• Некорректное состояние неожиданно (не следует путать с "редкими случаями" — например, если пользователь ввёл данные в некорректном формате, это не будет неожиданностью; такое следует обрабатывать).
• Весь следующий код не проводит проверок на данное (плохое) состояние, рассчитывая, что оно не происходит.
• Нет хорошего способа закодировать данную информацию в типах, которые вы используете. Мы рассмотрим пример того, что мы имеем в виду, в разделе "Кодирование в типах состояний и поведения" Главы 18.

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

Однако, когда сбой ождиаем, лучше вернуть Result, чем выполнить вызов panic!. В качестве примера можно привести синтаксический анализатор, которому передали неправильно сформированные данные, или HTTP-запрос, возвращающий статус, указывающий на то, что вы достигли ограничения на частоту запросов. В этих случаях возврат Result означает, что ошибка является ожидаемой и вызывающий код должен решить, как её обрабатывать.

Если ваш код выполняет операцию, которая может подвергнуть пользователя риску (если она вызывается с использованием недопустимых значений), ваш код должен сначала проверить допустимость значений и паниковать, если значения недопустимы. Так рекомендуется делать в основном из соображений безопасности: попытка оперировать некорректными данными может привести к уязвимостям. Это основная причина, по которой стандартная библиотека будет вызывать panic!, если пытаться получить доступ к памяти вне границ структуры данных: доступ к памяти, не относящейся к текущей структуре данных, является известной проблемой безопасности. Функции часто имеют контракты: их поведение гарантируется, только если входные данные отвечают определённым требованиям. Паника при нарушении контракта имеет смысл, потому что это всегда указывает на дефект со стороны вызывающего кода, и это не та ошибка, обработку которой вы хотели бы отдать вызывающему коду. В этом случае нет разумного способа для восстановления вызывающего кода: программисты, вызывающие ваш код, должны исправить свой. Контракты для функции (особенно когда их нарушение вызывает панику) следует описывать в документации API функции.

Тем не менее, наличие множества проверок ошибок во всех ваших функциях было бы многословным и раздражительным. К счастью, можно использовать систему типов Rust и её проверку компилятором, чтобы она сделала множество проверок вместо вас. Если ваша функция имеет определённый тип в качестве параметра, вы можете работать непосредственно над логикой программы, зная, что компилятор уже обеспечил правильное значение. Например, если используется обычный тип, а не тип Option, то ваша программа ожидает наличие чего-то, а не ничего. Ваш код не должен будет обрабатывать оба варианта Some и None: он будет иметь только один вариант для определённого значения. Код, пытающийся ничего не передавать в функцию, не будет даже компилироваться, поэтому ваша функция не должна проверять такой случай во время выполнения. Другой пример — это использование беззнакового целочисленного типа, такого как u32, который гарантирует, что параметр никогда не будет отрицательным.

Creating Custom Types for Validation

Давайте рассмотрим идею использования системы типов Rust для получения возможности проверять корректность значения. Вспомним игру в угадайку из Главы 2, в которой наш код просил пользователя угадать число от 1 до 100. Мы никогда не проверяли, находится ли догадка пользователя между этими числами, прежде чем сверять его с нашим загаданным числом; мы только удостоверялись, что догадка была больше нуля. В этом случае мы ничего не потеряли: наши сообщения "Слишком маленькое!" и "Слишком большое!" всё равно были правильными. Но было бы лучше подталкивать пользователя к правильным догадкам и иметь различное поведение для случаев, когда пользователь предлагает число за пределами диапазона, и когда пользователь вводит, например, буквы вместо цифр.

Один из способов добиться этого — пытаться разобрать введённое значение как i32, а не как u32, чтобы разрешить отрицательные числа, а затем добавить проверку на принадлежность числа диапазону; например, так:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Угадайте число!");

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

    loop {
        // --код сокращён--

        println!("Введите свою догадку.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Не удалось прочесть ввод.");

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

        if guess < 1 || guess > 100 {
            println!("Загаданное число находится в пределах от 1 до 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --код сокращён--
            Ordering::Less => println!("Слишком маленькое!"),
            Ordering::Greater => println!("Слишком большое!"),
            Ordering::Equal => {
                println!("Вы победили!");
                break;
            }
        }
    }
}

Выражение if проверяет, находится ли наше значение вне диапазона, сообщает пользователю о проблеме и вызывает continue, чтобы начать следующую итерацию цикла и попросить ввести другое число. После выражения if мы можем продолжить сравнение значения guess с загаданным числом, зная, что guess лежит в диапазоне от 1 до 100.

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

Вместо этого можно создать новый тип и поместить проверки в функцию создания экземпляра этого типа, не повторяя их повсюду. Таким образом, функции могут использовать новый тип в своих сигнатурах и быть уверенными в значениях, которые им передают. Листинг 9-13 показывает один из способов, как определить тип Guess, чтобы экземпляр 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!("Догадка {value} не принадлежит пределу от 1 до 100.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Сначала мы определяем структуру с именем Guess, которая имеет поле с именем value типа i32, в котором будет храниться догадка.

Затем мы реализуем ассоциированную функцию new, создающую экземпляры значений типа Guess. Функция new имеет один параметр value типа i32 и возвращает Guess. Код в теле функции new проверяет, что значение value находится между 1 и 100. Если value не проходит эту проверку, мы вызываем panic!, которая оповестит программиста, написавшего вызывающий код, что в его коде есть ошибка, которую необходимо исправить, поскольку попытка создания Guess со значением value вне заданного диапазона нарушает контракт, на который полагается Guess::new. Условия, в которых Guess::new паникует, должны быть описаны в документации API; мы рассмотрим документирование возможности вызова panic! на примере документации API, которую вы создадите в Главе 14. Если value проходит проверку, мы создаём новый экземпляр Guess, у которого значение поля value равно значению параметра value, и возвращаем Guess.

Затем мы реализуем метод с названием value, который только заимствует self и возвращает значение типа i32. Этот метод иногда называют геттером (англ. getter), потому что его цель состоит в том, чтобы извлечь данные из полей структуры и вернуть их. Этот публичный метод является необходимым, поскольку поле value структуры Guess является приватным. Важно, чтобы поле value было приватным, для того чтобы код, использующий структуру Guess, не мог устанавливать value напрямую: код снаружи модуля должен использовать функцию Guess::new для создания экземпляра Guess, таким образом гарантируя, что у Guess нет возможности получить value, не проверенное условиями в функции Guess::new.

Функция, которая принимает или возвращает только числа от 1 до 100, может объявить в своей сигнатуре, что она принимает или возвращает Guess, а не i32. Таким образом, не будет необходимости делать дополнительные проверки в теле такой функции.

Подведём итоги

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

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

Обобщённые типы, трейты и времена жизни

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

Функции могут принимать параметры некоторого обобщённого, а не конкретного типа (вроде i32 или String), аналогично тому, что функция принимает параметры с неизвестными заранее значениями, чтобы выполнять одинаковые действия над различными конкретными значениями. На самом деле, мы уже использовали обобщённые типы данных в Главе 6 (Option<T>), в Главе 8 (Vec<T> и HashMap<K, V>) и в Главе 9 (Result<T, E>). В этой главе вы узнаете, как определять собственные обобщённые типы данных, функции и методы.

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

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

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

Избавление от дублирования кода с помощью выделения общей функциональности

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

Начнём с короткой программы в Листинге 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!("Наибольшее число: {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!("Наибольшее число: {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!("Наибольшее число: {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!("Наибольшее число: {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("Наибольшее число: {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!("Наибольшее число: {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("Наибольший символ: {result}");
    assert_eq!(*result, 'y');
}

Функция largest_i32 уже встречалась нам: мы извлекли её в Листинге 10-3, когда боролись с дублированием кода; она находит наибольшее значение типа i32 в срезе. Функция largest_char находит самое большое значение типа char в срезе. Тело у этих функций одинаковое, поэтому давайте избавимся от дублируемого кода, используя параметр обобщённого типа в одной функции.

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

Когда мы используем параметр в теле функции, мы должны объявить имя параметра в сигнатуре, чтобы компилятор знал, что означает это имя. Аналогично, когда мы используем имя типа параметра в сигнатуре функции, мы должны объявить это имя раньше, чем мы его используем. Чтобы определить обобщённую функцию 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!("Наибольшее число: {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("Наибольший символ: {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`
  |
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). Следуя совету в сообщении компилятора, ограничим тип 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 };
}

В этом примере, когда мы присваиваем целочисленное значение 5 переменной x, мы сообщаем компилятору, что обобщённый тип T будет целым числом для этого экземпляра Point<T>. Затем, когда мы указываем значение 4.0 для y, который по нашему определению должен иметь тот же тип, что и x, мы получаем ошибку несоответствия типов:

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

Здесь мы определили метод x на структуре Point<T>, который возвращает ссылку на данные в поле x.

Обратите внимание, что мы должны объявить T сразу после impl, чтобы мы могли использовать T для указания на то, что мы реализуем методы для типа 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; в нём используются обобщённые типы X1 и Y1 для определения структуры Point и типы X2 и Y2 для сигнатуры метода mixup. Метод создаёт новый экземпляр структуры Point, где значение x берётся из 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 это достигается во время компиляции при помощи мономорфизации кода, использующего обобщённые типы. Мономорфизация — это процесс превращения обобщённого кода в конкретный код путём подстановки конкретных типов, использующихся при компиляции. В этом процессе компилятор выполняет шаги, противоположные тем, которые мы использовали для создания обобщённой функции в Листинге 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 чрезвычайно эффективными во время выполнения.

Трейты: определение схожего поведения

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

Примечание: Трейты схожи с таким механизмом как интерфейсы, но всё же они различаются.

Определение трейта

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

Например, пусть есть несколько структур, которые имеют различные структуру и объём текста: структура NewsArticle, которая содержит новость, напечатанную в каком-то месте мира, и структура Tweet, которая содержит 280 символов текста твита плюс мета-данные, обозначающие, является ли твит новым или ответом на другой твит.

Мы хотим создать библиотечный крейт новостного агрегатора aggregator, который может отображать сводку данных, сохранённых в экземплярах структур NewsArticle или Tweet. Чтобы реализовать это, нам необходимо иметь возможность получить сводку на основе данных структуры, и мы можем запросить эту сводку, вызвав метод 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 заголовок, автора и место публикации статьи. Для структуры Tweet мы определяем реализацию 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!("{} ({} из {})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Реализация трейта для типа аналогична реализации обычных методов. Разница в том, что после impl мы указываем имя трейта, который мы хотим реализовать, затем используем ключевое слово for, а затем указываем имя типа, для которого мы хотим сделать реализацию трейта. Внутри блока impl мы помещаем сигнатуру метода, объявленную в трейте. Вместо точки с запятой в конце, после каждой сигнатуры пишутся фигурные скобки, и тело метода заполняется конкретным кодом, реализующим поведение, которое мы хотим получить от методов трейта для конкретного типа.

Теперь, когда наш библиотечный крейт реализовывает трейт Summary для NewsArticle и Tweet, программисты, использующие наш крейт, могут вызывать методы трейта у экземпляров типов NewsArticle и Tweet точно так же, как если бы это были обычные методы. Единственное отличие состоит в том, что программист должен ввести трейт в область видимости точно так же, как и типы. Вот пример того как бинарный крейт может использовать наш новостной агрегатор:

use aggregator::{Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "конечно, вы уже наверное знаете, народ, ...",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 новый твит: {}", tweet.summarize());
}

Данный код напечатает: 1 новый твит: horse_ebooks: конечно, вы уже наверное знаете, народ, ....

Другие крейты, которые зависят от aggregator, также могут включать трейт Summary в область видимости для реализации Summary для своих собственных типов. Одно ограничение, на которое следует обратить внимание, заключается в том, что мы можем реализовать трейт для типа только в том случае, если хотя бы или трейт, или тип определяются нашим крейтом. Например, мы можем реализовать стандартный библиотечный трейт Display на собственном типе Tweet как часть функциональности нашего крейта aggregator, потому что тип Tweet является локальным для крейта aggregator. Также мы можем реализовать Summary для Vec<T> в нашем крейте aggregator, потому что трейт Summary является локальным для нашего крейта aggregator.

Но мы не можем реализовать чужие трейты для чужих типов. Например, мы не можем реализовать трейт Display для Vec<T> внутри нашего крейта aggregator, потому что и Display, и Vec<T> оба определены в стандартной библиотеке, а не в нашем крейте aggregator. Это ограничение является частью свойства, называемого последовательностью (англ. coherence), а точнее — правила сироты (англ. orphan rule), которое называется так потому, что не представлен родительский тип. Это правило гарантирует, что код других людей не может сломать ваш код, и наоборот. Без этого правила два крейта могли бы реализовать один трейт для одного типа, и Rust не смог бы понять, какой реализацией нужно пользоваться.

Реализация поведения по умолчанию

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

В Листинге 10-14 показано, мы определяем сводку по умолчанию для метода summarize трейта Summary, вместо того, чтобы определять лишь сигнатуру метода, как мы делали ранее в Листинге 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Читать далее...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Для использования реализации по умолчанию при создании сводки экземпляров NewsArticle, мы указываем пустой блок при impl Summary for NewsArticle {}.

Хотя мы больше не определяем метод summarize непосредственно на NewsArticle, мы предоставили реализацию по умолчанию и указали, что NewsArticle реализует трейт Summary. В результате мы всё ещё можем вызвать метод summarize у экземпляра NewsArticle; например, вот так:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("«Питтсбург Пингвинз» выиграли Кубок Стэнли!"),
        location: String::from("Питтсбург, штат Пенсильвания, США"),
        author: String::from("Пингвин Айсбург"),
        content: String::from(
            "«Питтсбург Пингвинз» вновь оказалась лучшей \
             хоккейной командой в НХЛ.",
        ),
    };

    println!("Новости! {}", article.summarize());
}

Этот код печатает Новости! (Читать далее...).

Создание реализации по умолчанию не требует от нас изменений чего-либо в реализации Summary для Tweet из Листинга 10-13. Причина заключается в том, что синтаксис для переопределения реализации по умолчанию является таким же, как синтаксис для реализации метода трейта, который не имеет реализации по умолчанию.

Реализации по умолчанию могут вызывать другие методы в том же трейте, даже если эти другие методы не имеют реализации по умолчанию. Таким образом, трейт может предоставить много полезной функциональности, а от разработчиков требует указывать только небольшую его часть. Например, мы могли бы определить трейт Summary, имеющий метод summarize_author без реализации по умолчанию, а затем определить метод summarize который имеет реализацию по умолчанию, вызывающую метод summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Читать далее, от {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Чтобы использовать такую версию трейта Summary, при реализации трейта для типа нужно определить только метод summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Читать далее, от {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

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

use aggregator::{self, Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "конечно, вы уже наверное знаете, народ, ...",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 новый твит: {}", tweet.summarize());
}

Этот код печатает 1 новый твит: (Читать далее, от @horse_ebooks...)

Обратите внимание, что невозможно вызвать реализацию по умолчанию из переопределённой реализации того же метода.

Трейты как параметры

Теперь, когда вы знаете, как определять и реализовывать трейты, мы можем изучить, как использовать трейты, чтобы определить функции, которые принимают много различных типов. Мы используем трейт Summary (реализованный для типов NewsArticle и Tweet) в Листинге 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!("{} ({} из {})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Срочные новости! {}", item.summarize());
}

Вместо конкретного типа у параметра item указывается ключевое слово impl и имя трейта. Этот параметр может принимать любой тип, который реализует указанный трейт. В теле notify мы можем вызывать любые методы у экземпляра item, которые приходят с трейтом Summary, такие как метод summarize. Мы можем вызвать notify и передать в него любой экземпляр NewsArticle или Tweet. Код, который вызывает данную функцию с любым другим типом, таким как String или i32, не будет компилироваться, потому что эти типы не реализуют трейт Summary.

Ограничение по трейтам

Синтаксис impl Trait работает для простых случаев, но на самом деле является синтаксическим сахаром для более длинной конструкции — ограничения по трейтам:

pub fn notify<T: Summary>(item: &T) {
    println!("Срочные новости! {}", 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 могла содержимое свеого аргумента и выводить на экран целиком, и получать его сводку с помощью метода summarize. Для этого мы указываем, что параметр item функции notify должен реализовывать два трейта: 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 {

можно использовать where, вот так:

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!("{} ({} из {})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "конечно, вы уже наверное знаете, народ, ...",
        ),
        reply: false,
        retweet: false,
    }
}

Используя impl Summary для типа возвращаемого значения, мы указываем, что функция returns_summarizable возвращает некоторый тип, который реализует трейт Summary, не обозначая конкретный тип. В этом случае returns_summarizable возвращает Tweet, но код, вызывающий эту функцию, этого не знает.

Возможность возвращать тип, который определяется только реализуемым им трейтом, особенно полезна в контексте замыканий и итераторов, которые мы рассмотрим в Главе 13. Замыкания и итераторы создают типы, которые знает только компилятор, или же типы, которые очень долго указывать. Запись impl Trait позволяет кратко указать, что функция возвращает некоторый тип, который реализует трейт Iterator без необходимости писать очень длинный тип.

Однако, impl Trait можно использовать, только если функция всегда возвращает значение одного типа. Например, данный код, который возвращает значение или типа NewsArticle, или типа Tweet, но в качестве возвращаемого типа объявляет 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!("{} ({} из {})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "«Питтсбург Пингвинз» выиграли Кубок Стэнли!",
            ),
            location: String::from("Питтсбург, штат Пенсильвания, США"),
            author: String::from("Пингвин Айсбург"),
            content: String::from(
                "«Питтсбург Пингвинз» вновь оказалась лучшей \
                 хоккейной командой в НХЛ.",
            ),
        }
    } else {
        Tweet {
            username: String::from("horse_ebooks"),
            content: String::from(
                "конечно, вы уже наверное знаете, народ, ...",
            ),
            reply: false,
            retweet: false,
        }
    }
}

Неоднозначность возвращаемого типа не допустима из-за того, как синтаксис impl Trait реализован в компиляторе. Мы рассмотрим, как (всё же) написать функцию с подобным поведением в разделе "Использование трейт-объектов, позволяющих использовать значения разных типов" Главы 18.

Использование ограничений по трейту для избирательной реализации методов

Ограничив по трейту обобщённый тип при блоке impl, мы можем избирательно реализовать методы для тех типов, которые реализуют указанные трейты. Например, тип Pair<T> в Листинге 10-15 всегда реализует функцию new, возвращающую новый экземпляр Pair<T> (напомним из раздела "Определение методов" Главы 5, что Self — это псевдоним типа при блоке impl; в нашем случае этим типом является Pair<T>). Но в следующем блоке impl Pair<T> реализует метод cmp_display только в том случае, если его тип 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!("Слева ({}) — наибольшее", self.x);
        } else {
            println!("Справа ({}) — наибольшее", self.y);
        }
    }
}

Мы также можем избирательно реализовать трейт для всех типов, которые реализуют другой трейт. Реализация трейта для всех типов, которые удовлетворяют ограничениям по трейтам, называются сплошной реализацией, и она широко используется в стандартной библиотеке Rust. Например, стандартная библиотека реализует трейт ToString для всех типов, которые реализуют трейт Display. Блок impl, делающий это, выглядит примерно так:

impl<T: Display> ToString for T {
    // --код сокращён--
}

Благодаря такой сплошной реализации можно вызвать метод to_string, определённый трейтом ToString, для любого типа, который реализует трейт Display. Например, мы можем превратить целые числа в их соответствующие значения String, потому что целые числа реализуют трейт Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

В документации к трейтам, их сплошные реализации можно увидеть в разделе "Implementors".

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

Валидация ссылок по времени жизни

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

В разделе ["Ссылки и заимствование"](ch04-02-references-and-borrowing.html #Ссылки-и-заимствование) Главы 4 мы кое о чём умолчали: у каждой ссылки в Rust есть своё время жизни — промежуток программы, в котором данная ссылка действительна. В большинстве случаев времена жизни выводятся неявно — так же, как и типы. Точно так же мы должны явно объявлять времена жизни тех ссылок, которые комплятор не может самостоятельно однозначно определить. Rust требует от нас объявлять взаимосвязи посредством обобщённых параметров времени жизни, чтобы убедиться в том, что во время исполнения все используемые ссылки будут корректными.

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

Защита от висячих ссылок с помощью времён жизни

Основное предназначение времён жизни — предотвращать появление так называемых висячих ссылок — ссылок, указывающих не на те данные, на которые предполагалось указывать. Рассмотрим программу из Листинга 10-16, имеющую внешнюю и внутреннюю области видимости.

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

Примечание: Примеры в Листингах 10-16, 10-17 и 10-23 объявляют переменные без указания их начального значения, поэтому имя переменной существует во внешней области видимости. На первый взгляд может показаться, что это противоречит отсутствию в Rust значений null. Однако, если мы попытаемся использовать переменную, прежде чем присвоить ей значение, мы получим ошибку компиляции, которая показывает, что Rust действительно не разрешает значения null.

Внешняя область видимости объявляет переменную r без начального значения, а внутренняя область объявляет переменную x с начальным значением 5. Во внутренней области мы пытаемся установить значение r как ссылку на x. Затем внутренняя область видимости заканчивается, и мы пытаемся напечатать значение из r. Этот код не будет скомпилирован, потому что значение, на которое ссылается r, исчезает из области видимости раньше, чем мы пытаемся использовать его. Вот сообщение об ошибке:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
5 |         let x = 5;
  |             - binding `x` declared here
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {r}");
  |                  --- borrow later used here

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

Ошибка сообщает, что переменная x "живёт недостаточно долго". Причина в том, что x выйдет из области видимости, когда эта внутренняя область закончится в строке 7. Но r всё ещё останется действительной во внешней области видимости; поскольку её охват больше, мы говорим, что она "живёт дольше". Если бы Rust позволил такому коду работать, то переменная r смогла бы ссылаться на память, которая уже была освобождена (в тот момент, когда x вышла из внутренней области видимости), и всё, что мы попытались бы сделать с r, работало бы неправильно. Как же Rust определяет, что этот код некорректен? Он использует для этого анализатор заимствований.

Анализатор заимствований

Компилятор Rust включает в себя анализатор заимствований, который сравнивает области видимости для того, чтобы проверить, являются ли все заимствования действительными. В Листинге 10-17 показан тот же код, что и в Листинге 10-16, но с комментариями, показывающими времена жизни переменных.

fn main() {
    let r;                // ─────────┬── 'a
                          //          │
    {                     //          │
        let x = 5;        // ━┳━━ 'b  │
        r = &x;           //  ┃       │
    }                     // ━┛       │
                          //          │
    println!("r: {r}");   //          │
}                         // ─────────┘

Время жизни r здесь указано как 'a, а x — как 'b. Как видите, время жизни 'b внутреннего блока гораздо меньше, чем время жизни 'a внешнего блока. Во время компиляции Rust сравнивает продолжительность двух времён жизни и видит, что r имеет время жизни 'a, но ссылается на память со временем жизни 'b. Программа отбраковывается, потому что 'b короче, чем 'a: объект ссылки не живёт так же долго, как сама ссылка.

Листинг 10-18 содержит исправленный код без висячей ссылки, и он компилируется без ошибок.

fn main() {
    let x = 5;            // ━━━━━━━━━━┳━━ 'b
                          //           ┃
    let r = &x;           // ──┬── 'a  ┃
                          //   │       ┃
    println!("r: {r}");   //   │       ┃
                          // ──┘       ┃
}                         // ━━━━━━━━━━┛

Здесь переменная x имеет время жизни 'b, которое больше, чем время жизни 'a. Это означает, что переменная r может ссылаться на переменную x, потому что Rust знает, что ссылка в переменной r будет всегда действительной до тех пор, пока действительна переменная x.

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

Обобщённые времена жизни в функциях

We’ll write a function that returns the longer of two string slices. This function will take two string slices and return a single string slice. After we’ve implemented the longest function, the code in Listing 10-19 should print The longest string is abcd.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("Самая длинная строка: {result}");
}

Обратите внимание, что мы хотим, чтобы функция принимала строковые срезы (которые являются ссылками), а не сами строки, потому что мы не хотим, чтобы функция longest забирала во владение свои параметры. Обратитесь к разделу "Строковые срезы как параметры" Главы 4, чтобы вспомнить, почему параметры функции в Листинге 10-19 имеют именно такой тип.

Если мы попробуем реализовать функцию longest так, как это показано в Листинге 10-20, то программа не скомпилируется:

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("Самая длинная строка: {result}");
}

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

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

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0106]: missing lifetime specifier
 --> src/main.rs:9:33
  |
9 | fn longest(x: &str, y: &str) -> &str {
  |               ----     ----     ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`
help: consider introducing a named lifetime parameter
  |
9 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
  |           ++++     ++          ++          ++

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

Текст ошибки показывает, что возвращаемому типу нужен обобщённый параметр времени жизни, потому что Rust не может определить, на что указывает возвращаемая ссылка — на x или на y. На самом деле, мы тоже не знаем! — блок if в теле функции возвращает ссылку на x, а блок else — на y.

Когда мы определяем эту функцию, мы не знаем конкретных значений, которые будут переданы в эту функцию, поэтому мы не знаем, какая из ветвей (if или else) будет исполнена. Мы также не знаем конкретных сроков жизни ссылок, которые будут переданы, поэтому мы не можем просмотреть области видимости, как мы это делали в Листингах 10-17 и 10-18, чтобы определить, всегда ли возвращаемая ссылка будет действительной. Анализатор заимствований тоже бессилен, поскольку он не знает, как времена жизни x и y соотносятся с временем жизни возвращаемого значения. Чтобы исправить эту ошибку, мы добавим обобщённые параметры времени жизни, которые указывают анализатору заимствований то, как ссылки относятся друг к другу.

Аннотирование времени жизни

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

Аннотации времени жизни имеют немного необычный синтаксис: имена параметров времени жизни должны начинаться с апострофа ('), пишутся маленькими буквами, и обычно очень короткие, как и имена обобщённых типов. Большинство людей использует имя 'a в качестве первой аннотации времени жизни. Аннотации параметров времени жизни следуют после символа & и отделяются пробелом от типа значения ссылки.

Приведём несколько примеров: у нас есть ссылка на i32 без указания времени жизни, ссылка на i32 с временем жизни 'a и изменяемая ссылка на i32, которая также имеет время жизни 'a.

&i32        // ссылка
&'a i32     // ссылка с явно указанным временем жизни
&'a mut i32 // изменяемая ссылка с явно указанным временем жизни

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

Аннотации времени жизни в сигнатурах функций

Чтобы использовать аннотации времени жизни в сигнатурах функций, нам нужно объявить параметры обобщённого времени жизни внутри угловых скобок между именем функции и списком параметров, как мы это делали с параметрами обобщённого типа.

Мы хотим, чтобы сигнатура отражала следующее ограничение: возвращаемая ссылка будет действительна до тех пор, пока действительны оба параметра. Это и есть связь между временами жизни параметров и возвращаемого значения. Мы назовём это время жизни 'a, а затем припишем его каждой ссылке, как показано в Листинге 10-21.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("Самая длинная строка: {result}");
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

Теперь наша функция будет работать, а код из Листинга 10-19 — скомпилируется.

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

Помните, что когда мы указываем параметры времени жизни в этой сигнатуре функции, мы не меняем времена жизни каких-либо передаваемых или возвращаемых значений. Скорее, мы указываем, что анализатор заимствований должен отклонять любые значения, которые не соответствуют этим ограничениям. Обратите внимание, что самой функции longest не нужно точно знать, как долго будут жить x и y, достаточно того, что некоторая область может быть заменена на 'a, которая будет удовлетворять этой сигнатуре.

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

Когда мы передаём longest конкретные ссылки, конкретное время жизни, которое подставляется вместо 'a, становится частью области видимости x, которая перекрывается с областью видимости y. Другими словами, общее время жизни 'a получит конкретное время жизни, равное меньшему из времён жизни x и y. Поскольку мы указали возвращаемой ссылке тот же параметр времени жизни ('a), время жизни возвращаемой ссылки будет не меньшим, чем минимальное из времён жизни x и y.

Давайте посмотрим, как аннотации времени жизни ограничивают функцию longest путём передачи в неё ссылок, которые имеют разные конкретные времена жизни. Посмотрите на Листинг 10-22:

fn main() {
    let string1 = String::from("длинная строка такая длинная");

    {
        let string2 = String::from("xyz");
        let result = longest(string1.as_str(), string2.as_str());
        println!("Самая длинная строка: {result}");
    }
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

В этом примере переменная string1 действительна до конца внешней области видимости string2 действует до конца внутренней области видимости, а result ссылается на что-то, что является действительным до конца внутренней области видимости. Запустите этот код, и вы увидите что анализатор заимствований разрешает такой код; он скомпилируется и напечатает Самая длинная строка: длинная строка такая длинная.

Теперь давайте рассмотрим пример, который показывает, что время жизни ссылки в result должно быть меньшим временем жизни одного из двух аргументов. Мы переместим объявление переменной result за пределы внутренней области видимости, но оставим присвоение значения переменной result в области видимости string2. Затем мы переместим println!, который использует result, за пределы внутренней области видимости — после того как внутренняя область видимости закончилась. Код в Листинге 10-23 не скомпилируется.

fn main() {
    let string1 = String::from("длинная строка такая длинная");
    let result;
    {
        let string2 = String::from("xyz");
        result = longest(string1.as_str(), string2.as_str());
    }
    println!("Самая длинная строка: {result}");
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

При попытке скомпилировать этот код, мы получим такую ошибку:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `string2` does not live long enough
 --> src/main.rs:6:44
  |
5 |         let string2 = String::from("xyz");
  |             ------- binding `string2` declared here
6 |         result = longest(string1.as_str(), string2.as_str());
  |                                            ^^^^^^^ borrowed value does not live long enough
7 |     }
  |     - `string2` dropped here while still borrowed
8 |     println!("The longest string is {result}");
  |                                     -------- borrow later used here

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

Эта ошибка говорит о том, что если мы хотим использовать result в инструкции println!, переменная string2 должна быть действительной до конца внешней области видимости. Rust знает об этом, потому что мы аннотировали параметры функции и её возвращаемое значение одинаковым временем жизни 'a.