Введение в эксперимент

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

1. Викторины

Основная механика — викторины: на каждой странице есть несколько вопросов по её содержанию. У нас есть два правила относительно викторин в этом эксперименте:

1. Проходите викторину сразу, как до неё доберётесь.
2. Не пропускайте викторины.

(Мы не контролируем выполнение этих правил, но просим вас следовать им!)

Каждая викторина выглядит так, как показано ниже. Попробуйте, нажав «Start».

Если вы ответили на вопрос неправильно, вы можете либо повторить попытку, либо увидеть правильные ответы. Мы рекомендуем повторять викторину, пока не получите 100% — не стесняйтесь перечитать материал перед повторной попыткой. Обратите внимание, что как только вы увидите правильные ответы, повторную попытку пройти нельзя.

Если вы обнаружили проблему в викторине или в другой части книги, вы можете сообщить о ней в нашем репозитории на GitHub: https://github.com/cognitive-engineering-lab/rust-book

2. Выделение текста

Другая механика — выделение текста: вы можете выделить любой фрагмент текста и либо выделить его цветом, либо оставить комментарий. После выделения текста нажмите кнопку ✏️ и оставьте необязательный комментарий.

👉 Попробуйте выделить этот текст! 👈

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

Примечание: ваши выделения исчезнут, если мы изменим выделенный вами контент. Также ваши выделения хранятся в файле cookie. Если вы блокируете файлы cookie или меняете браузер, вы не увидите предыдущие выделения.

3. …и не только!

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

• 26 сентября 2024 г.
  • Добавлена глава Криса Кричо об асинхронном Rust, а также новые вопросы для викторин.
• 16 февраля 2023 г.
  • Новая глава о владении заменила предыдущую главу 4.
• 18 января 2023 г.
  • Вопросы добавлены для оставшихся глав книги.
• 15 декабря 2022 г.
  • В книге добавлены новые разделы под названием «Инвентаризация владения» со сложными вопросами, связанными с владением.
• 7 ноября 2022 г.
  • При повторной попытке будут показаны только вопросы с неправильными ответами.
  • В большинстве вопросов с множественным выбором варианты будут случайным образом перемешаны.
  • Некоторые вопросы теперь будут запрашивать ваше обоснование.
  • Многие вопросы обновлены на основе ваших отзывов. Продолжайте в том же духе!

Заинтересованы в участии в других экспериментах по упрощению изучения Rust? Пожалуйста, зарегистрируйтесь здесь: https://forms.gle/U3jEUkb2fGXykp1DA

4. Публикации

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

• Profiling Programming Language Learning
  Уилл Кричтон и Шрирам Кришнамурти. OOPSLA 2024. (Отличительная статья.)

• A Grounded Conceptual Model for Ownership Types in Rust
  Уилл Кричтон, Гэвин Грей и Шрирам Кришнамурти. OOPSLA 2023. (Награда SIGPLAN Research Highlight и Communications of the ACM Research Highlight.)

5. Благодарности

Эта работа частично поддержана DARPA по соглашению № HR00112420354, частично поддержана NSF по гранту № CCF-2227863 и частично поддержана Amazon Web Services. Любые мнения, выводы и рекомендации, выраженные в этом материале, принадлежат авторам и не отражают взгляды наших спонсоров. Кэрол Николс и Rust Foundation помогли с публикацией эксперимента. TRPL — это результат усердной работы многих людей до начала нашего эксперимента.

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

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

(а также с экспериментальными изменениями!)

Эта версия текста предполагает, что вы используете Rust 1.85.0 (выпущен 2025-02-17) или новее с edition = "2024" в файле Cargo.toml всех проектов, чтобы настроить их на использование идиом Rust 2024 издания. См. раздел «Установка» главы 1 для установки или обновления Rust.

Экспериментальная версия доступна только онлайн и на английском языке. Неэкспериментальная версия доступна оффлайн с установками Rust, сделанными через rustup; выполните rustup doc --book, чтобы открыть.

Также доступно несколько переводов [неэкспериментальной версии], сделанных сообществом. Неэкспериментальный текст доступен в формате бумажной и электронной книги от No Starch Press.

Предисловие

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

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

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

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

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

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

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

Введение

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

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

Для кого предназначен Rust

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

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

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

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

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

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

Студенты

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

Компании

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

Разработчики открытого исходного кода

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

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

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

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

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

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

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

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

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

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

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

Ferris	Значение
	Этот код не компилируется!
	Этот код вызывает панику!
	Этот код не даёт желаемого поведения.

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

Исходный код

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

Начало работы

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

• Установку Rust на Linux, macOS и Windows
• Написание программы, выводящей Hello, world!
• Использование cargo — менеджера пакетов и системы сборки Rust

Установка

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

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

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

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

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

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

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

Rust is installed now. Great!

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

В macOS вы можете получить компилятор C, выполнив:

$ xcode-select --install

Пользователи Linux, как правило, должны установить GCC или Clang в соответствии с документацией своего дистрибутива. Например, если вы используете Ubuntu, вы можете установить пакет build-essential.

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

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

Остальная часть книги использует команды, которые работают как в cmd.exe, так и в PowerShell. Если есть конкретные различия, мы объясним, какой вариант использовать.

Устранение неполадок

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

$ rustc --version

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

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

Если вы видите эту информацию, значит, Rust установлен успешно! Если вы не видите эту информацию, проверьте, что Rust находится в вашей системной переменной PATH, как описано ниже.

В Windows CMD используйте:

> echo %PATH%

В PowerShell используйте:

> echo $env:Path

В Linux и macOS используйте:

$ echo $PATH

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

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

После установки Rust через rustup обновление до новой выпущенной версии просто. Из вашей оболочки выполните следующий скрипт обновления:

$ rustup update

Чтобы удалить Rust и rustup, выполните следующий скрипт удаления из вашей оболочки:

$ rustup self uninstall

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

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

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

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

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

Работа в автономном режиме с этой книгой

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

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

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

Привет, мир!

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

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

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

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

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

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

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

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

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

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

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

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

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

Анатомия программы на Rust

Давайте подробно рассмотрим эту программу «Hello, world!». Вот первая часть головоломки:

fn main() {

}

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

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

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

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

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

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

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

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

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

Компиляция и запуск — это отдельные шаги

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

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

$ rustc main.rs

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

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

$ ls
main  main.rs

На Linux и macOS вы увидите два файла. С PowerShell в Windows вы увидите те же три файла, что и при использовании CMD. С CMD в Windows вы бы ввели следующее:

> dir /B %= опция /B говорит показывать только имена файлов =%
main.exe
main.pdb
main.rs

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

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

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

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

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

Привет, Cargo!

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

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

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

$ cargo --version

Если вы видите номер версии — отлично! Если вы видите ошибку, например 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 внутри.

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

Примечание: Git — это распространённая система контроля версий. Вы можете изменить cargo new на использование другой системы контроля версий или отключить её, используя флаг --vcs. Запустите cargo new --help, чтобы увидеть доступные параметры.

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

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

[dependencies]

Этот файл имеет формат TOML (Tom’s Obvious, Minimal Language), который является форматом конфигурации Cargo.

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

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

Последняя строка, [dependencies], — это начало раздела, в котором вы перечисляете все зависимости вашего проекта. В Rust пакеты кода называются крейтами. Нам не понадобятся другие крейты для этого проекта, но они понадобятся в первом проекте в Главе 2, поэтому мы используем этот раздел зависимостей тогда.

Теперь откройте src/main.rs и посмотрите на него:

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

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

Cargo сгенерировал для вас программу «Hello, world!», точно такую же, какую мы написали в Листинге 1-1! Пока что различия между нашим проектом и проектом, сгенерированным Cargo, consist в том, что Cargo поместил код в каталог src, и у нас есть файл конфигурации Cargo.toml в верхнем каталоге.

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

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

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

Теперь давайте посмотрим, что меняется, когда мы собираем и запускаем программу «Hello, world!» с помощью Cargo! Из каталога hello_cargo соберите свой проект, введя следующую команду:

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

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

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

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

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

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

Использование cargo run удобнее, чем запоминать, запускать cargo build, а затем использовать весь путь к бинарному файлу, поэтому большинство разработчиков используют cargo 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/release вместо target/debug. Оптимизации заставляют ваш код на 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 = "2024"

[dependencies]

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

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

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

Теперь скомпилируем эту программу «Hello, world!» и запустим её в одном шаге с помощью команды cargo run:

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

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

let apples = 5;

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

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

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

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

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

В целом, строка let mut guess = String::new(); создала изменяемую переменную, которая в данный момент связана с новым пустым экземпляром String. Уф!

Получение ввода пользователя

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

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

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

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

Давайте протестируем первую часть игры «Угадай число». Запустите её с помощью cargo run:

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

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

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

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

Использование крейта для получения дополнительной функциональности

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

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

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

[dependencies]
rand = "0.8.5"

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

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

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

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

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

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

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

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

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

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

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

Обеспечение воспроизводимых сборок с помощью файла Cargo.lock

У Cargo есть механизм, который гарантирует, что вы можете пересобирать тот же артефакт каждый раз, когда вы или кто-либо ещё собираете ваш код: Cargo будет использовать только версии зависимостей, которые вы указали, пока вы не укажете иное. Например, предположим, что на следующей неделе выходит версия 0.8.6 крейта rand, и эта версия содержит важное исправление ошибки, но также содержит регрессию, которая сломает ваш код. Чтобы справиться с этим, 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
     Locking 1 package to latest Rust 1.85.0 compatible version
    Updating rand v0.8.5 -> v0.8.6 (available: v0.9.0)

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

[dependencies]
rand = "0.9.0"

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

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

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

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

use std::io;

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

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

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

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

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

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

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

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

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

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

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

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

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

use rand::Rng;

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

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

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

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

    // --snip--

    let mut guess = String::new();

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

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

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

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

Строка:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

use rand::Rng;

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

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

    // --snip--

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

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

        // --snip--


        let mut guess = String::new();

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

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

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

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

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

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

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

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

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

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

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

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

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

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

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

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

        // --snip--

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

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

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

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

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

        // --snip--

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

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

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

        // --snip--

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

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

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

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

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

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

Отлично! С одним последним небольшим изменением мы завершим игру «Угадай число». Напомним, что программа всё ещё выводит секретное число. Это хорошо работало для тестирования, но это портит игру. Давайте удалим println!, который выводит секретное число. Листинг 2-6 показывает окончательный код.

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

use rand::Rng;

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

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

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

        let mut guess = String::new();

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

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

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

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

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

Резюме

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, давайте изменим src/main.rs на следующий код:

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

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

Когда мы теперь запускаем программу, мы получаем:

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

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

Константы

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

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

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

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

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

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

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

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

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

Затенение

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

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

fn main() {
    let x = 5;

    let x = x + 1;

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

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

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

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

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

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

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

Первая переменная spaces имеет строковый тип, а вторая переменная spaces имеет числовой тип. Таким образом, затенение избавляет нас от необходимости придумывать разные имена, такие как spaces_str и spaces_num; вместо этого мы можем повторно использовать более простое имя spaces. Однако если мы попытаемся использовать mut для этого, как показано здесь, мы получим ошибку на этапе компиляции:

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

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

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

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

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

Типы данных

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

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

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

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

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

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

Вы увидите разные аннотации типов для других типов данных.

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

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

Целые числа

Целое число — это число без дробной части. Мы использовали один тип целых чисел в главе 2, тип u32. Это объявление типа указывает, что значение, с которым оно связано, должно быть беззнаковым целым числом (типы знаковых целых чисел начинаются с i вместо u), занимающим 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, — это при индексации какой-либо коллекции.

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

Rust также имеет два примитивных типа для чисел с плавающей точкой, которые являются числами с десятичными точками. Типы с плавающей точкой в 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() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

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

    // remainder
    let remainder = 43 % 5;
}

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

Булев тип

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

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

fn main() {
    let t = true;

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

Основной способ использования булевых значений — через условные выражения, такие как выражение if. Мы рассмотрим, как работают выражения if в Rust, в разделе «Управление потоком».

Тип символа

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

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

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

Обратите внимание, что мы указываем литералы char с помощью одинарных кавычек, в отличие от строковых литералов, которые используют двойные кавычки. Тип char в Rust имеет размер четыре байта и представляет скалярное значение Unicode, что означает, что он может представлять гораздо больше, чем просто ASCII. Буквы с диакритическими знаками; китайские, японские и корейские символы; эмодзи; и нулевые пробелы — все это допустимые значения char в Rust. Скалярные значения Unicode находятся в диапазоне от U+0000 до U+D7FF и от U+E000 до U+10FFFF включительно. Однако «символ» — это на самом деле не концепция в Unicode, поэтому ваша человеческая интуиция о том, что такое «символ», может не совпадать с тем, что такое char в Rust. Мы обсудим эту тему подробно в «Хранение текста в кодировке 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!("The value of y is: {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, а затем получает доступ к каждому элементу кортежа, используя соответствующие индексы. Как и в большинстве языков программирования, первый индекс в кортеже равен 0.

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

Кроме того, мы можем изменять отдельные элементы изменяемого кортежа. Например:

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

fn main() {
    let mut x: (i32, i32) = (1, 2);
    x.0 = 0;
    x.1 += 5;
}

Эта программа устанавливает первый элемент в ноль и добавляет пять ко второму элементу. Конечное значение x равно (0, 7).

Тип массива

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этом примере переменная с именем first получит значение 1, потому что это значение по индексу [0] в массиве. Переменная с именем second получит значение 2 из индекса [1] в массиве.

Недопустимый доступ к элементу массива

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

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

use std::io;

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

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

    let mut index = String::new();

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

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

    let element = a[index];

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

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

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

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

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

Функции

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

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

Filename: src/main.rs

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

    another_function();
}

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

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

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

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

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

Строки выполняются в порядке их появления в функции main. Сначала выводится сообщение “Hello, world!”, а затем вызывается another_function и выводится её сообщение.

Параметры

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

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

Filename: src/main.rs

fn main() {
    another_function(5);
}

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

Попробуйте запустить эту программу; вы должны получить следующий вывод:

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

Объявление another_function имеет один параметр с именем x. Тип x указан как i32. Когда мы передаем 5 в another_function, макрос println! подставляет 5 на место пары фигурных скобок, содержащих x, в строке формата.

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

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

Filename: src/main.rs

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

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

Этот пример создает функцию с именем print_labeled_measurement с двумя параметрами. Первый параметр называется value и имеет тип i32. Второй называется unit_label и имеет тип char. Затем функция выводит текст, содержащий и value, и unit_label.

Давайте попробуем запустить этот код. Замените программу, которая сейчас находится в файле src/main.rs вашего проекта functions, приведенным выше примером и запустите его с помощью cargo run:

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

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

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

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

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

Давайте рассмотрим несколько примеров.

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

fn main() {
    let y = 6;
}

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

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

Filename: 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 и получить, что и x, и y имеют значение 6; в Rust это не так.

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

Filename: src/main.rs

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

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

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

{
    let x = 3;
    x + 1
}

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

Функции с возвращаемыми значениями

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

Filename: src/main.rs

fn five() -> i32 {
    5
}

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

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

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

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

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

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

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

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

Filename: src/main.rs

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

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

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

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

Filename: src/main.rs

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

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

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

Компиляция этого кода производит ошибку, как показано ниже:

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

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

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

Комментарии

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

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

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

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

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

Или можно использовать синтаксис многострочных комментариев с /* и */:

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

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

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

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

Но чаще вы увидите их в таком формате, с комментарием на отдельной строке над кодом, который они комментируют:

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

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

В Rust также есть другой вид комментариев — комментарии документации, которые мы обсудим в разделе 14 «Публикация крейта на Crates.io» publishing.

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

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

Выражения if

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

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

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

fn main() {
    let number = 3;

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

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

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

Попробуйте запустить этот код; вы должны увидеть следующий вывод:

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

Давайте попробуем изменить значение number на значение, которое делает условие false, чтобы увидеть, что произойдёт:

fn main() {
    let number = 7;

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

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

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

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

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

fn main() {
    let number = 3;

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

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

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

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

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

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

fn main() {
    let number = 3;

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

Запуск этого кода выведет number was something other than zero.

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

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

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

fn main() {
    let number = 6;

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

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

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

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

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

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

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

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

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

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

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

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

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

fn main() {
    let condition = true;

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

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

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

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

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

Выражение в блоке if оценивается в целое число, а выражение в блоке else оценивается в строку. Это не сработает, потому что переменные должны иметь один тип, и Rust должен знать на этапе компиляции, каким типом definitively является переменная number. Знание типа number позволяет компилятору проверить, что тип действителен везде, где мы используем number. Rust не смог бы этого сделать, если бы тип number определялся только во время выполнения; компилятор был бы более сложным и давал бы меньше гарантий о коде, если бы ему пришлось отслеживать несколько гипотетических типов для любой переменной.

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

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

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

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

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

В качестве примера измените файл src/main.rs в вашем каталоге loops так, чтобы он выглядел следующим образом:

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

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

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

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

Символ ^C представляет место, где вы нажали ctrl-c.

Вы можете или не увидеть слово again! напечатанным после ^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!("The result is {result}");
}

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

Вы также можете использовать return внутри цикла. Хотя break выходит только из текущего цикла, return всегда выходит из текущей функции.

Примечание: точка с запятой после break counter * 2 технически необязательна. break очень похож на return в том смысле, что оба могут необязательно принимать выражение в качестве аргумента, оба вызывают изменение потока управления. Код после break или return никогда не выполняется, поэтому компилятор Rust рассматривает выражение break и выражение return как имеющие значение единицы, или ().

Метки циклов для устранения неоднозначности между несколькими циклами

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

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

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

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

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

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

Условные циклы с помощью while

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

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

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

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

Цикл по коллекции с помощью for

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

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

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

        index += 1;
    }
}

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

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

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

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

В качестве более краткой альтернативы вы можете использовать цикл for и выполнять некоторый код для каждого элемента в коллекции. Цикл for выглядит как код в Листинге 3-5.

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

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

Когда мы запускаем этот код, мы увидим тот же вывод, что и в Листинге 3-4. Что более важно, мы теперь повысили безопасность кода и устранили шанс ошибок, которые могли бы возникнуть из-за выхода за конец массива или недостаточного прохода и пропуска некоторых элементов. Машинный код, сгенерированный из циклов for, также может быть более эффективным, потому что индекс не нужно сравнивать с длиной массива на каждой итерации.

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

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

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

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

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

Этот код немного приятнее, не так ли?

Резюме

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

• Преобразование температур между Фаренгейтом и Цельсием.
• Генерация n-го числа Фибоначчи.
• Печать текста рождественской колядки «Двенадцать дней Рождества», используя повторение в песне.

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

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

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

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

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

Безопасность — это отсутствие неопределённого поведения

Начнём с примера. Эта программа безопасна для выполнения:

fn read(y: bool) {
    if y {
        println!("y is true!");
    }
}

fn main() {
    let x = true;
    read(x);
}

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

fn read(y: bool) {
    if y {
        println!("y is true!");
    }
}

fn main() {
    read(x); // oh no! x isn't defined!
    let x = true;
}

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

Вторая программа небезопасна, потому что read(x) ожидает, что x имеет значение типа bool, но x ещё не имеет значения.

Когда такая программа выполняется интерпретатором, чтение x до её определения вызывает исключение, например NameError в Python или ReferenceError в JavaScript. Но исключения имеют стоимость. Каждый раз, когда интерпретируемая программа читает переменную, интерпретатор должен проверить, определена ли эта переменная.

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

error[E0425]: cannot find value `x` in this scope
 --> src/main.rs:8:10
  |
8 |     read(x); // oh no! x isn't defined!
  |          ^ not found in this scope

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

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

main:
    ; ...
    mov     edi, 1
    call    read
    ; ...

Примечание: если вы не знакомы с ассемблерным кодом, это нормально! Этот раздел содержит несколько примеров ассемблера, чтобы показать, как Rust работает на самом деле. Для понимания Rust обычно не нужно знать ассемблер.

Этот ассемблерный код:

• Перемещает число 1, представляющее true, в регистр (вид переменной в ассемблере) под названием edi.
• Вызывает функцию read, которая ожидает, что её первый аргумент y будет в регистре edi.

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

main:
    ; ...
    call    read
    mov     edi, 1    ; mov после call
    ; ...

Эта программа небезопасна, потому что read ожидает, что edi будет логическим значением, то есть числом 0 или 1. Но edi может быть чем угодно: 2, 100, 0x1337BEEF. Когда read попытается использовать свой аргумент y для любой цели, это немедленно вызовет НЕОПРЕДЕЛЁННОЕ ПОВЕДЕНИЕ!

Rust не определяет, что происходит, если попытаться выполнить if y { .. }, когда y не равно true или false. Это поведение, или то, что происходит после выполнения инструкции, является неопределённым. Может произойти что-то, например:

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

Фундаментальная цель Rust — гарантировать, что ваши программы никогда не имеют неопределённого поведения. Вот что значит “безопасность”. Неопределённое поведение особенно опасно для низкоуровневых программ с прямым доступом к памяти. Около 70% сообщённых уязвимостей безопасности в низкоуровневых системах вызвано повреждением памяти, что является одной из форм неопределённого поведения.

Вторичная цель Rust — предотвращать неопределённое поведение на этапе компиляции, а не выполнения. У этой цели две мотивации:

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

Rust не может предотвратить все ошибки. Если приложение предоставляет публичный и неаутентифицированный endpoint /delete-production-database, то злоумышленнику не нужна подозрительная инструкция if для удаления базы данных. Но защиты Rust всё ещё могут сделать программы безопаснее по сравнению с использованием языка с меньшим количеством защит, как показала, например, команда Android от Google.

Владение как дисциплина для безопасности памяти

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

Память — это пространство, где хранятся данные во время выполнения программы. Есть много способов думать о памяти:

• Если вы не знакомы с системным программированием, вы можете думать о памяти на высоком уровне, например “память — это ОЗУ в моём компьютере” или “память — это то, что заканчивается, если я загружаю слишком много данных”.
• Если вы знакомы с системным программированием, вы можете думать о памяти на низком уровне, например “память — это массив байтов” или “память — это указатели, которые я получаю от malloc”.

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

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

Переменные живут в стеке

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

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

• Кадр для main в точке L1 содержит n = 5.
• Кадр для plus_one в L2 содержит x = 5.
• Кадр для main в точке L3 содержит n = 5; y = 6.

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

Примечание: эта модель памяти не полностью описывает, как Rust работает на самом деле! Как мы видели ранее с ассемблерным кодом, компилятор Rust может поместить n или x в регистр, а не в кадр стека. Но это различие — деталь реализации. Это не должно менять ваше понимание безопасности в Rust, поэтому мы можем сосредоточиться на более простом случае переменных только в кадрах.

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

Значение a копируется в b, и a остаётся неизменным, даже после изменения b.

Box’ы живут в куче

Однако копирование данных может занимать много памяти. Например, вот немного другая программа. Эта программа копирует массив с 1 миллионом элементов:

Заметьте, что копирование a в b приводит к тому, что кадр main содержит 2 миллиона элементов.

Чтобы передать доступ к данным без их копирования, Rust использует указатели. Указатель — это значение, описывающее расположение в памяти. Значение, на которое указывает указатель, называется объектом указателя. Один из распространённых способов создать указатель — выделить память в куче. Куча — это отдельная область памяти, где данные могут существовать неограниченно долго. Данные в куче не привязаны к конкретному кадру стека. Rust предоставляет конструкцию под названием Box для размещения данных в куче. Например, мы можем обернуть массив из миллиона элементов в Box::new так:

Заметьте, что теперь существует только один массив за раз. В L1 значение a — это указатель (представлен точкой со стрелкой) на массив внутри кучи. Инструкция let b = a копирует указатель из a в b, но данные, на которые указывает указатель, не копируются. Обратите внимание, что a теперь серое, потому что оно было перемещено — мы увидим, что это значит, через мгновение.

Rust не разрешает ручное управление памятью

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

Как мы видели выше, данные в куче выделяются при вызове Box::new(..). Но когда данные в куче освобождаются? Представьте, что у Rust есть функция free(), которая освобождает выделение в куче. Представьте, что Rust позволяет программисту вызывать free когда угодно. Такой “ручной” способ управления памятью легко приводит к ошибкам. Например, мы могли бы прочитать указатель на освобождённую память:

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

Здесь мы выделяем массив в куче. Затем вызываем free(b), которая освобождает память кучи для b. Поэтому значение b — это указатель на недействительную память, которую мы представляем иконкой “⦻”. Неопределённое поведение ещё не произошло! Программа всё ещё безопасна в L2. Не обязательно проблема иметь недействительный указатель.

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

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

Владелец Box’а управляет освобождением

Вместо этого Rust автоматически освобождает память кучи для box’а. Вот почти правильное описание политики Rust для освобождения box’ов:

Принцип освобождения Box’а (почти правильно): Если переменная связана с box’ом, когда Rust освобождает кадр переменной, тогда Rust освобождает память кучи box’а.

Например, давайте проследим программу, которая выделяет и освобождает box:

В L1, перед вызовом make_and_drop, состояние памяти — это просто кадр стека для main. Затем в L2, во время вызова make_and_drop, a_box указывает на 5 в куче. Как только make_and_drop завершается, Rust освобождает его кадр стека. make_and_drop содержит переменную a_box, поэтому Rust также освобождает данные в куче в a_box. Поэтому куча пуста в L3.

Память кучи для box’а была успешно управлена. Но что, если мы злоупотребим этой системой? Возвращаясь к нашему предыдущему примеру, что происходит, когда мы связываем две переменные с box’ом?

fn main() {
let a = Box::new([0; 1_000_000]);
let b = a;
}

Массивированный массив теперь связан как с a, так и с b. Согласно нашему “почти правильному” принципу, Rust попытается освободить память кучи box’а дважды от имени обеих переменных. Это тоже неопределённое поведение!

Чтобы избежать этой ситуации, мы наконец приходим к владению. Когда a связывается с Box::new([0; 1_000_000]), мы говорим, что a владеет box’ом. Инструкция let b = a перемещает владение box’ом из a в b. Учитывая эти концепции, политика Rust для освобождения box’ов более точно описывается так:

Принцип освобождения Box’а (полностью правильно): Если переменная владеет box’ом, когда Rust освобождает кадр переменной, тогда Rust освобождает память кучи box’ом.

В примере выше b владеет box’ом с массивом. Поэтому когда область видимости заканчивается, Rust освобождает box только один раз от имени b, а не a.

Коллекции используют Box’ы

Box’ы используются структурами данных Rust¹ такими как Vec, String и HashMap для хранения переменного числа элементов. Например, вот программа, которая создаёт, перемещает и изменяет строку:

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

1. В L1 строка “Ferris” была выделена в куче. Её владеет first.
2. В L2 была вызвана функция add_suffix(first). Это перемещает владение строкой из first в name. Данные строки не копируются, но указатель на данные копируется.
3. В L3 функция name.push_str(" Jr.") изменяет размер выделения кучи для строки. Это делает три вещи. Во-первых, создаётся новое большее выделение. Во-вторых, в новое выделение записывается “Ferris Jr.”. В-третьих, освобождается исходная память кучи. first теперь указывает на освобождённую память.
4. В L4 кадр для add_suffix исчез. Эта функция вернула name, передавая владение строкой full.

Переменные нельзя использовать после перемещения

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

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

К счастью, Rust откажется компилировать эту программу, выдавая следующую ошибку:

error[E0382]: borrow of moved value: `first`
 --> test.rs:4:35
  |
2 |     let first = String::from("Ferris");
  |         ----- move occurs because `first` has type `String`, which does not implement the `Copy` trait
3 |     let full = add_suffix(first);
  |                           ----- value moved here
4 |     println!("{full}, originally {first}"); // first is now used here
  |                                   ^^^^^ value borrowed here after move

Давайте пройдёмся по шагам этой ошибки. Rust говорит, что first перемещена при вызове add_suffix(first) в строке 3. Ошибка уточняет, что first перемещена, потому что имеет тип String, который не реализует Copy. Мы обсудим Copy скоро — вкратце, вы не получили бы эту ошибку, если бы использовали i32 вместо String. Наконец, ошибка говорит, что мы используем first после перемещения (она “заимствована”, что мы обсуждаем в следующем разделе).

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

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

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

Клонирование избегает перемещений

Один из способов избежать перемещения данных — клонировать их, используя метод .clone(). Например, мы можем исправить проблему безопасности в предыдущей программе с клоном:

Заметьте, что в L1 first_clone не “поверхностно” скопировал указатель в first, а вместо этого “глубоко” скопировал данные строки в новое выделение кучи. Поэтому в L2, пока first_clone была перемещена и сделана недействительной add_suffix, исходная переменная first остаётся неизменной. Безопасно продолжать использовать first.

Резюме

Владение в первую очередь является дисциплиной управления кучей:²

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

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

1. Эти структуры данных не используют буквальный тип Box. Например, String реализован с Vec, а Vec реализован с RawVec, а не с Box. Но типы вроде RawVec всё ещё похожи на box: они владеют памятью в куче. ↩

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

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

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

В этом примере вызов greet перемещает данные из m1 и m2 в параметры greet. Обе строки удаляются в конце greet, и поэтому не могут быть использованы в main. Если попытаться прочитать их, как в операции format!(..), это приведёт к неопределённому поведению. Компилятор Rust поэтому отклоняет эту программу с той же ошибкой, что и в предыдущем разделе:

error[E0382]: borrow of moved value: `m1`
 --> test.rs:5:30
 (...rest of the error...)

Такое поведение с перемещением крайне неудобно. Программы часто должны использовать строку более одного раза. Альтернативный greet мог бы возвращать владение строками, например так:

Однако такой стиль программирования довольно многословен. Rust предоставляет лаконичный стиль чтения и записи без перемещений через ссылки.

Ссылки — это указатели, не владеющие данными

Ссылка — это вид указателя. Вот пример ссылки, который переписывает нашу программу greet более удобным способом:

Выражение &m1 использует оператор амперсанда для создания ссылки на (или “заимствования”) m1. Тип параметра g1 в greet изменён на &String, что означает “ссылка на String”.

Обратите внимание, что на L2 есть два шага от g1 до строки “Hello”. g1 — это ссылка, указывающая на m1 в стеке, а m1 — это String, содержащая коробку, которая указывает на “Hello” в куче.

Хотя m1 владеет данными в куче “Hello”, g1 не владеет ни m1, ни “Hello”. Поэтому после завершения greet и достижения программы L3 никакие данные в куче не освобождаются. Исчезает только стековый фрейм для greet. Этот факт согласуется с нашим Принципом освобождения коробок. Поскольку g1 не владел “Hello”, Rust не освободил “Hello” от имени g1.

Ссылки — это невладеющие указатели, потому что они не владеют данными, на которые указывают.

Разыменование указателя даёт доступ к его данным

Предыдущие примеры с коробками и строками не показывали, как Rust “следует” за указателем к его данным. Например, макрос println! таинственным образом работал как для владеющих строк типа String, так и для ссылок на строки типа &String. Основной механизм — это оператор разыменования, обозначаемый звёздочкой (*). Например, вот программа, использующая разыменования несколькими способами:

Обратите внимание на разницу между r1, указывающим на x в стеке, и r2, указывающим на значение в куче 2.

Вы, вероятно, не увидите оператор разыменования очень часто при чтении кода Rust. Rust неявно вставляет разыменования и ссылки в определённых случаях, например при вызове метода с точечным оператором. Например, эта программа показывает два эквивалентных способа вызова функций i32::abs (абсолютное значение) и str::len (длина строки):

fn main()  {
let x: Box<i32> = Box::new(-1);
let x_abs1 = i32::abs(*x); // явное разыменование
let x_abs2 = x.abs();      // неявное разыменование
assert_eq!(x_abs1, x_abs2);

let r: &Box<i32> = &x;
let r_abs1 = i32::abs(**r); // явное разыменование (дважды)
let r_abs2 = r.abs();       // неявное разыменование (дважды)
assert_eq!(r_abs1, r_abs2);

let s = String::from("Hello");
let s_len1 = str::len(&s); // явная ссылка
let s_len2 = s.len();      // неявная ссылка
assert_eq!(s_len1, s_len2);
}

Этот пример показывает неявные преобразования тремя способами:

1. Функция i32::abs ожидает на вход тип i32. Чтобы вызвать abs с Box<i32>, можно явно разыменовать коробку, как i32::abs(*x). Можно также неявно разыменовать коробку, используя синтаксис вызова метода, как x.abs(). Точечный синтаксис — это синтаксический сахар для синтаксиса вызова функции.

2. Это неявное преобразование работает для нескольких слоёв указателей. Например, вызов abs на ссылке на коробку r: &Box<i32> вставит два разыменования.

3. Это преобразование также работает в обратном направлении. Функция str::len ожидает ссылку &str. Если вызвать len на владеющей String, то Rust вставит один оператор заимствования. (На самом деле, есть дальнейшее преобразование из String в str!)

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

Rust избегает одновременного алиасинга и мутации

Указатели — мощная и опасная особенность, потому что они позволяют алиасинг. Алиасинг — это доступ к одним и тем же данным через разные переменные. Сам по себе алиасинг безвреден. Но в сочетании с мутацией это рецепт для катастрофы. Одна переменная может “выдернуть ковёр” из-под другой переменной многими способами, например:

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

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

Макрос vec! создаёт вектор с элементами между скобками. Вектор v имеет тип Vec<i32>. Синтаксис <i32> означает, что элементы вектора имеют тип i32.

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

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

Обратите внимание, что вектор имеет длину (len) 3 и ёмкость (cap) 3. Вектор заполнен до ёмкости. Поэтому при push вектор должен создать новое выделение с большей ёмкостью, скопировать все элементы и освободить исходный массив в куче. На диаграмме выше массив 1 2 3 4 находится в (потенциально) другом месте памяти, чем исходный массив 1 2 3.

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

Изначально v указывает на массив с 3 элементами в куче. Затем num создаётся как ссылка на третий элемент, как видно на L1. Однако операция v.push(4) изменяет размер v. Изменение размера освободит предыдущий массив и выделит новый, больший массив. В процессе num остаётся указывать на недействительную память. Поэтому на L3 разыменование *num читает недействительную память, вызывая неопределённое поведение.

В более абстрактных терминах проблема в том, что вектор v одновременно алиасирован (ссылкой num) и мутируется (операцией v.push(4)). Поэтому чтобы избежать подобных проблем, Rust следует базовому принципу:

Принцип безопасности указателей: данные никогда не должны быть алиасированы и мутированы одновременно.

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

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

Ссылки изменяют разрешения на места

Основная идея проверки заимствований в том, что переменные имеют три вида разрешений на свои данные:

• Чтение (R): данные могут быть скопированы в другое место.
• Запись (W): данные могут быть изменены.
• Владение (O): данные могут быть перемещены или удалены.

Эти разрешения не существуют во время выполнения, только внутри компилятора. Они описывают, как компилятор “думает” о вашей программе до её выполнения.

По умолчанию переменная имеет разрешения чтение/владение (RO) на свои данные. Если переменная аннотирована let mut, то она также имеет разрешение запись (W). Ключевая идея в том, что ссылки могут временно снимать эти разрешения.

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

Давайте пройдёмся по каждой строке:

1. После let mut v = (...), переменная v была инициализирована (обозначено ). Она получает разрешения +R+W+O (знак плюс указывает на получение).
2. После let num = &v[2], данные в v были заимствованы num (обозначено ). Происходят три вещи:
   • Заимствование снимает разрешения
     W
     O с v (косая черта указывает на потерю). v не может быть записан или владеем, но всё ещё может быть прочитан.
   • Переменная num получила разрешения RO. num не является изменяемым (отсутствующее разрешение W показано как тире ‒), потому что оно не было отмечено let mut.
   • Место *num получило разрешение R.
3. После println!(...), num больше не используется, поэтому v больше не заимствован. Следовательно:
   • v восстанавливает свои разрешения WO (обозначено ).
   • num и *num потеряли все свои разрешения (обозначено ).
4. После v.push(4), v больше не используется, и он теряет все свои разрешения.

Далее рассмотрим несколько нюансов диаграммы. Во-первых, почему вы видите и num, и *num? Потому что доступ к данным через ссылку — это не то же самое, что манипулирование самой ссылкой. Например, допустим, мы объявили ссылку на число с let mut:

Обратите внимание, что x_ref имеет разрешение W, в то время как *x_ref — нет. Это означает, что мы можем присвоить другую ссылку переменной x_ref (например, x_ref = &y), но не можем изменить данные, на которые она указывает (например, *x_ref += 1).

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

• Переменные, такие как a.
• Разыменования мест, такие как *a.
• Доступы к массиву мест, такие как a[0].
• Поля мест, такие как a.0 для кортежей или a.field для структур (обсуждается в следующей главе).
• Любые комбинации вышеперечисленного, такие как *((*a)[0].1).

Во-вторых, почему места теряют разрешения, когда они становятся неиспользуемыми? Потому что некоторые разрешения взаимно исключают друг друга. Если вы пишете num = &v[2], то v не может быть изменён или удалён, пока num используется. Но это не значит, что использовать num снова недействительно. Например, если мы добавим ещё один println! в вышеприведённую программу, то num просто потеряет свои разрешения на строку позже:

Проблема возникает только при попытке использовать num снова после изменения v. Давайте рассмотрим это подробнее.

Проверка заимствований находит нарушения разрешений

Вспомним Принцип безопасности указателей: данные не должны быть алиасированы и мутированы. Цель этих разрешений — гарантировать, что данные не могут быть мутированы, если они алиасированы. Создание ссылки на данные (“заимствование”) приводит к тому, что эти данные временно становятся доступны только для чтения, пока ссылка не перестаёт использоваться.

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

Каждый раз, когда место используется, Rust ожидает, что у места будут определённые разрешения в зависимости от операции. Например, заимствование &v[2] требует, чтобы v было читаемым. Поэтому разрешение R показано между операцией & и местом v. Буква заполнена, потому что v имеет разрешение чтения на этой строке.

Напротив, мутирующая операция v.push(4) требует, чтобы v было читаемым и изменяемым. Оба разрешения R и W показаны. Однако v не имеет разрешения записи (оно заимствовано num). Поэтому буква W полая, указывая, что разрешение записи ожидается, но v его не имеет.

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

error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> test.rs:4:1
  |
3 | let num: &i32 = &v[2];
  |                  - immutable borrow occurs here
4 | v.push(4);
  | ^^^^^^^^^ mutable borrow occurs here
5 | println!("Third element is {}", *num);
  |                                 ---- immutable borrow later used here

Сообщение об ошибке объясняет, что v не может быть изменено, пока ссылка num используется. Это поверхностная причина — основная проблема в том, что num может быть инвалидировано push. Rust ловит это потенциальное нарушение безопасности памяти.

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

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

Механизм для этого — изменяемые ссылки (также называемые уникальными ссылками). Вот простой пример изменяемой ссылки с accompanying изменениями разрешений:

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

•

R

•

W

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

Изменяемая ссылка создаётся оператором &mut. Тип num записывается как &mut i32. По сравнению с неизменяемыми ссылками, вы можете увидеть две важные разницы в разрешениях:

1. Когда num была неизменяемой ссылкой, v всё ещё имел разрешение R. Теперь, когда num — изменяемая ссылка, v потерял все разрешения, пока num используется.
2. Когда num была неизменяемой ссылкой, место *num имело только разрешение R. Теперь, когда num — изменяемая ссылка, *num также получил разрешение W.

Первое наблюдение делает изменяемые ссылки безопасными. Изменяемые ссылки позволяют мутацию, но предотвращают алиасинг. Заимствованное место v временно становится непригодным для использования, поэтому эффективно не является алиасом.

Второе наблюдение делает изменяемые ссылки полезными. v[2] может быть изменён через *num. Например, *num += 1 изменяет v[2]. Обратите внимание, что *num имеет разрешение W, но num — нет. num ссылается на саму изменяемую ссылку, например num не может быть переназначен на другую изменяемую ссылку.

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

Примечание: когда изменения разрешений не релевантны примеру, мы будем их скрывать. Вы можете просмотреть скрытые шаги, нажав “»”, и вы можете просмотреть скрытые разрешения в рамках шага, нажав “● ● ●”.

В этой программе заимствование &*num снимает разрешение W с *num, но не разрешение R, поэтому println!(..) может читать и *num, и *num2.

Разрешения возвращаются в конце времени жизни ссылки

Мы сказали выше, что ссылка изменяет разрешения, пока она “используется”. Фраза “используется” описывает время жизни ссылки, или диапазон кода от её рождения (где ссылка создаётся) до её смерти (последний раз(ы), когда ссылка используется).

Например, в этой программе время жизни y начинается с let y = &x и заканчивается с let z = *y:

Разрешение W на x возвращается x после окончания времени жизни y, как мы видели ранее.

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

Переменная c имеет разное время жизни в каждой ветви if-выражения. В then-блоке c используется в выражении c.to_ascii_uppercase(). Поэтому *v не восстанавливает разрешение W до после этой строки.

Однако в else-блоке c не используется. *v немедленно восстанавливает разрешение W при входе в else-блок.

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

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

Чтобы поймать такие ошибки, Rust использует разрешения, которые мы уже обсуждали. Заимствование &s снимает разрешение O с s. Однако drop ожидает разрешение O, что приводит к несоответствию разрешений.

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

Этот фрагмент вводит новый вид разрешения, разрешение потока F. Разрешение F ожидается всякий раз, когда выражение использует входную ссылку (как &strings[0]) или возвращает выходную ссылку (как return s_ref).

В отличие от разрешений RWO, F не меняется на протяжении тела функции. Ссылка имеет разрешение F, если ей разрешено использоваться (то есть протекать) в конкретном выражении. Например, давайте изменим first на новую функцию first_or, которая включает параметр default:

Эта функция больше не компилируется, потому что выражения &strings[0] и default не имеют необходимого разрешения F для возврата. Но почему? Rust даёт следующую ошибку:

error[E0106]: missing lifetime specifier
 --> test.rs:1:57
  |
1 | fn first_or(strings: &Vec<String>, default: &String) -> &String {
  |                      ------------           -------     ^ 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 `strings` or `default`

Сообщение “missing lifetime specifier” немного загадочно, но справочное сообщение даёт некоторый полезный контекст. Если Rust просто посмотрит на сигнатуру функции, он не знает, является ли выход &String ссылкой на strings или default. Чтобы понять, почему это важно, давайте скажем, что мы использовали first_or так:

fn main() {
    let strings = vec![];
    let default = String::from("default");
    let s = first_or(&strings, &default);
    drop(default);
    println!("{}", s);
}

Эта программа небезопасна, если first_or позволяет default протекать в возвращаемое значение. Как и в предыдущем примере, drop может инвалидировать s. Rust позволит компилировать эту программу только если он уверен, что default не может протекать в возвращаемое значение.

Чтобы указать, может ли default быть возвращён, Rust предоставляет механизм, называемый параметрами времени жизни. Мы объясним эту особенность позже в Главе 10.3, “Проверка ссылок с помощью времени жизни”. Пока достаточно знать, что: (1) входные/выходные ссылки обрабатываются иначе, чем ссылки внутри тела функции, и (2) Rust использует другой механизм, разрешение F, для проверки безопасности этих ссылок.

Чтобы увидеть разрешение F в другом контексте, скажем, вы попытались вернуть ссылку на переменную в стеке, вот так:

Эта программа небезопасна, потому что ссылка &s будет инвалидирована при возврате return_a_string. И Rust отклонит эту программу с похожей ошибкой “missing lifetime specifier”. Теперь вы можете понять, что эта ошибка означает, что s_ref отсутствует соответствующее разрешение потока.

Резюме

Ссылки предоставляют возможность читать и записывать данные без потребления владения ими. Ссылки создаются заимствованиями (& и &mut) и используются с разыменованиями (*), часто неявно.

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

• Все переменные могут читать, владеть и (опционально) записывать свои данные.
• Создание ссылки передаст разрешения из заимствованного места ссылке.
• Разрешения возвращаются, как только время жизни ссылки заканчивается.
• Данные должны переживать все ссылки, которые на них указывают.

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

Исправление ошибок владения

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

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

Исправление небезопасной программы: возврат ссылки на стек

Первый кейс — возврат ссылки на стек, как мы обсуждали в разделе “Данные должны переживать все ссылки на них”. Вот функция, которую мы рассматривали:

fn return_a_string() -> &String {
    let s = String::from("Hello world");
    &s
}

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

В зависимости от ситуации есть четыре способа продлить время жизни строки. Один — передать владение строкой из функции, изменив &String на String:

#![allow(unused)]
fn main() {
fn return_a_string() -> String {
    let s = String::from("Hello world");
    s
}
}

Другой вариант — вернуть строковый литерал, который живёт вечно (обозначается 'static). Это решение подходит, если строка никогда не будет изменяться, и тогда выделение в куче не нужно:

#![allow(unused)]
fn main() {
fn return_a_string() -> &'static str {
    "Hello world"    
}
}

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

#![allow(unused)]
fn main() {
use std::rc::Rc;
fn return_a_string() -> Rc<String> {
    let s = Rc::new(String::from("Hello world"));
    Rc::clone(&s)
}
}

Мы обсудим подсчёт ссылок подробнее в главе 15.4 “Rc<T>, умный указатель с подсчётом ссылок”. Вкратце, Rc::clone клонирует только указатель на s, а не сами данные. Во время выполнения Rc проверяет, когда последний Rc, указывающий на данные, будет удалён, и затем освобождает данные.

Ещё один вариант — чтобы вызывающий код предоставил “слот” для строки с помощью изменяемой ссылки:

#![allow(unused)]
fn main() {
fn return_a_string(output: &mut String) {
    output.replace_range(.., "Hello world");
}
}

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

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

Исправление небезопасной программы: недостаточно прав

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

Эта программа отклоняется проверкой заимствований, потому что name — это неизменяемая ссылка, но name.push(..) требует права W. Эта программа небезопасна, потому что push может сделать недействительными другие ссылки на name за пределами stringify_name_with_title, например:

В этом примере ссылка first на name[0] создаётся до вызова stringify_name_with_title. Функция name.push(..) перераспределяет содержимое name, что делает first недействительной, вызывая чтение освобождённой памяти в println.

Так как исправить этот API? Одно простое решение — изменить тип name с &Vec<String> на &mut Vec<String>:

fn stringify_name_with_title(name: &mut Vec<String>) -> String {
    name.push(String::from("Esq."));
    let full = name.join(" ");
    full
}

Но это не хорошее решение! Функции не должны изменять свои входные данные, если вызывающий код не ожидает этого. Человек, вызывающий stringify_name_with_title, вероятно, не ожидает, что его вектор будет изменён этой функцией. Другая функция, например add_title_to_name, может ожидать изменения входных данных, но не наша.

Другой вариант — взять владение именем, изменив &Vec<String> на Vec<String>:

fn stringify_name_with_title(mut name: Vec<String>) -> String {
    name.push(String::from("Esq."));
    let full = name.join(" ");
    full
}

Но это тоже не хорошее решение! Очень редко функции в Rust берут владение над структурами данных в куче, такими как Vec и String. Эта версия stringify_name_with_title сделает входной name непригодным для использования, что очень неудобно для вызывающего кода, как мы обсуждали в начале раздела “Ссылки и заимствование”.

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

fn stringify_name_with_title(name: &Vec<String>) -> String {
    let mut name_clone = name.clone();
    name_clone.push(String::from("Esq."));
    let full = name_clone.join(" ");
    full
}

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

fn stringify_name_with_title(name: &Vec<String>) -> String {
    let mut full = name.join(" ");
    full.push_str(" Esq.");
    full
}

Это решение работает, потому что slice::join уже копирует данные из name в строку full.

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

Исправление небезопасной программы: псевдонимы и изменение структуры данных

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

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

Эта программа отклоняется проверкой заимствований, потому что let largest = .. удаляет права W для dst. Однако dst.push(..) требует права W. Снова спросим: почему эта программа небезопасна? Потому что dst.push(..) может освободить содержимое dst, делая ссылку largest недействительной.

Чтобы исправить программу, ключевое понимание — нужно сократить время жизни largest, чтобы оно не перекрывалось с dst.push(..). Один вариант — клонировать largest:

#![allow(unused)]
fn main() {
fn add_big_strings(dst: &mut Vec<String>, src: &[String]) {
    let largest: String = dst.iter().max_by_key(|s| s.len()).unwrap().clone();
    for s in src {
        if s.len() > largest.len() {
            dst.push(s.clone());
        }
    }
}
}

Однако это может вызвать потерю производительности из-за выделения и копирования данных строки.

Другой вариант — выполнить все сравнения длин сначала, а затем изменить dst afterwards:

#![allow(unused)]
fn main() {
fn add_big_strings(dst: &mut Vec<String>, src: &[String]) {
    let largest: &String = dst.iter().max_by_key(|s| s.len()).unwrap();
    let to_add: Vec<String> = 
        src.iter().filter(|s| s.len() > largest.len()).cloned().collect();
    dst.extend(to_add);
}
}

Однако это также вызывает потерю производительности из-за выделения вектора to_add.

Последний вариант — скопировать длину largest, так как нам на самом деле не нужно содержимое largest, только его длина. Это решение, пожалуй, самое идиоматичное и производительное:

#![allow(unused)]
fn main() {
fn add_big_strings(dst: &mut Vec<String>, src: &[String]) {
    let largest_len: usize = dst.iter().max_by_key(|s| s.len()).unwrap().len();
    for s in src {
        if s.len() > largest_len {
            dst.push(s.clone());
        }
    }
}
}

Все эти решения объединяет ключевая идея: сокращение времени жизни заимствований dst так, чтобы они не перекрывались с изменением dst.

Исправление небезопасной программы: копирование vs. перемещение из коллекции

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

Операция разыменования *n_ref ожидает только права R, которые есть у пути *n_ref. Но что произойдёт, если изменить тип элементов вектора с i32 на String? Тогда у нас больше не будет необходимых прав:

Первая программа скомпилируется, а вторая — нет. Rust выдаёт следующее сообщение об ошибке:

error[E0507]: cannot move out of `*s_ref` which is behind a shared reference
 --> test.rs:4:9
  |
4 | let s = *s_ref;
  |         ^^^^^^
  |         |
  |         move occurs because `*s_ref` has type `String`, which does not implement the `Copy` trait

Проблема в том, что вектор v владеет строкой “Hello world”. Когда мы разыменовываем s_ref, это пытается взять владение строкой из вектора. Но ссылки — это неуправляющие указатели; мы не можем взять владение через ссылку. Поэтому Rust жалуется, что мы “не можем переместить из […] общей ссылки”.

Но почему это небезопасно? Мы можем проиллюстрировать проблему, имитируя отклонённую программу:

Что происходит здесь — двойное освобождение. После выполнения let s = *s_ref и v, и s думают, что владеют “Hello world”. После удаления s строка “Hello world” освобождается. Затем удаляется v, и неопределённое поведение происходит при втором освобождении строки.

Примечание: после выполнения s = *s_ref нам даже не нужно использовать v или s, чтобы вызвать неопределённое поведение через двойное освобождение. Как только мы перемещаем строку из s_ref, неопределённое поведение произойдёт, как только элементы будут удалены.

Однако это неопределённое поведение не происходит, когда вектор содержит элементы i32. Разница в том, что копирование String копирует указатель на данные в куче. Копирование i32 этого не делает. В технических терминах Rust говорит, что тип i32 реализует типаж Copy, а String не реализует Copy (мы обсудим типажи в следующей главе).

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

• i32 не владеет данными в куче, поэтому его можно скопировать без перемещения.
• String владеет данными в куче, поэтому его нельзя скопировать без перемещения.
• &String не владеет данными в куче, поэтому его можно скопировать без перемещения.

Примечание: Одно исключение из этого правила — изменяемые ссылки. Например, &mut i32 — не копируемый тип. Так что если вы делаете что-то вроде:

let mut n = 0;
let a = &mut n;
let b = a;

Тогда a нельзя использовать после присвоения b. Это предотвращает одновременное использование двух изменяемых ссылок на одни и те же данные.

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

fn main() {
let v: Vec<String> = vec![String::from("Hello world")];
let s_ref: &String = &v[0];
println!("{s_ref}!");
}

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

fn main() {
let v: Vec<String> = vec![String::from("Hello world")];
let mut s: String = v[0].clone();
s.push('!');
println!("{s}");
}

Наконец, можно использовать метод, такой как Vec::remove, чтобы переместить строку из вектора:

fn main() {
let mut v: Vec<String> = vec![String::from("Hello world")];
let mut s: String = v.remove(0);
s.push('!');
println!("{s}");
assert!(v.len() == 0);
}

Исправление безопасной программы: изменение разных полей кортежа

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

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

Инструкция let first = &name.0 заимствует name.0. Это заимствование удаляет права WO у name.0. Оно также удаляет права WO у name. (Например, нельзя передать name в функцию, принимающую значение типа (String, String).) Но name.1 по-прежнему сохраняет право W, поэтому операция name.1.push_str(...) допустима.

Однако Rust может потерять точное понимание, какие места заимствованы. Например, представим, что мы рефакторим выражение &name.0 в функцию get_first. Обратите внимание, как после вызова get_first(&name) Rust теперь удаляет право W у name.1:

Теперь мы не можем сделать name.1.push_str(..)! Rust вернёт эту ошибку:

error[E0502]: cannot borrow `name.1` as mutable because it is also borrowed as immutable
  --> test.rs:11:5
   |
10 |     let first = get_first(&name);
   |                           ----- immutable borrow occurs here
11 |     name.1.push_str(", Esq.");
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here
12 |     println!("{first} {}", name.1);
   |                ----- immutable borrow later used here

Это странно, ведь программа была безопасна до редактирования. Сделанное изменение существенно не меняет поведение во время выполнения. Так почему важно, что мы поместили &name.0 в функцию?

Проблема в том, что Rust не смотрит на реализацию get_first при решении, что get_first(&name) должно заимствовать. Rust смотрит только на сигнатуру типа, которая просто говорит “некоторый String во входных данных заимствуется”. Rust консервативно решает, что тогда и name.0, и name.1 заимствуются, и устраняет права на запись и владение для обоих.

Помните, ключевая идея в том, что программа выше безопасна. В ней нет неопределённого поведения! Будущая версия Rust может быть достаточно умной, чтобы позволить ей скомпилироваться, но сегодня она отклоняется. Так как обойти проверку заимствований сегодня? Один вариант — встроить выражение &name.0, как в исходной программе. Другой вариант — отложить проверку заимствований на время выполнения с помощью [ячеек], что мы обсудим в будущих главах.

Исправление безопасной программы: изменение разных элементов массива

Подобная проблема возникает при заимствовании элементов массива. Например, посмотрим, какие места заимствуются, когда мы берём изменяемую ссылку на массив:

Проверка заимствований Rust не содержит отдельных мест для a[0], a[1] и так далее. Она использует одно место a[_], представляющее все индексы a. Rust делает это, потому что не всегда может определить значение индекса. Например, представьте более сложный сценарий:

let idx = a_complex_function();
let x = &mut a[idx];

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

Однако Rust отклоняет эту программу, потому что a отдала свои права на чтение x. Сообщение об ошибке компилятора говорит то же самое:

error[E0502]: cannot borrow `a[_]` as immutable because it is also borrowed as mutable
 --> test.rs:4:9
  |
3 | let x = &mut a[1];
  |         --------- mutable borrow occurs here
4 | let y = &a[2];
  |         ^^^^^ immutable borrow occurs here
5 | *x += *y;
  | -------- mutable borrow later used here

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

fn main() {
let mut a = [0, 1, 2, 3];
let (a_l, a_r) = a.split_at_mut(2);
let x = &mut a_l[1];
let y = &a_r[0];
*x += *y;
}

Вы можете спросить, но как реализован split_at_mut? В некоторых библиотеках Rust, особенно в основных типах, таких как Vec или slice, вы часто найдёте unsafe блоки. unsafe блоки позволяют использовать “сырые” указатели, которые не проверяются на безопасность проверкой заимствований. Например, мы могли бы использовать unsafe-блок для выполнения нашей задачи:

fn main() {
let mut a = [0, 1, 2, 3];
let x = &mut a[1] as *mut i32;
let y = &a[2] as *const i32;
unsafe { *x += *y; } // НЕ ДЕЛАЙТЕ ЭТОГО, если не знаете, что делаете!
}

Небезопасный код иногда необходим для обхода ограничений проверки заимствований. Как общая стратегия, скажем, проверка заимствований отклоняет программу, которую вы считаете фактически безопасной. Тогда вам стоит искать функции стандартной библиотеки (такие как split_at_mut), содержащие unsafe блоки, которые решают вашу проблему. Мы обсудим небезопасный код подробнее в Главе 20. Пока просто имейте в виду, что небезопасный код — это то, как Rust реализует определённые иначе невозможные шаблоны.

Резюме

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

1. Эта гарантия применяется к программам, написанным на “безопасном подмножестве” Rust. Если вы используете unsafe код или вызываете небезопасные компоненты (например, библиотеку на C), то должны проявить дополнительную осторожность, чтобы избежать неопределённого поведения. ↩

Тип среза

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

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

fn first_word(s: &String) -> ?

Функция first_word принимает параметр &String. Нам не нужно владение строкой, так что это нормально. Но что возвращать? У нас нет способа описать часть строки. Однако можно вернуть индекс конца слова, обозначенный пробелом. Попробуем так, как показано в Листинге 4-7.

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

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

Листинг 4-7: Функция first_word, возвращающая индекс байта в параметре String

Чтобы пройти по строке элемент за элементом и проверить, является ли значение пробелом, преобразуем String в массив байтов с помощью метода as_bytes:

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

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

    s.len()
}

fn main() {}

Затем создаём итератор по массиву байтов с помощью метода iter:

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

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

    s.len()
}

fn main() {}

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

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

Внутри цикла for мы ищем байт, представляющий пробел, используя синтаксис байтового литерала. Если находим пробел, возвращаем позицию. Иначе возвращаем длину строки с помощью s.len():

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

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

    s.len()
}

fn main() {}

Теперь у нас есть способ узнать индекс конца первого слова в строке, но есть проблема. Мы возвращаем usize сам по себе, но это число имеет смысл только в контексте &String. Другими словами, поскольку это отдельное значение от String, нет гарантии, что оно останется действительным в будущем. Рассмотрим программу в Листинге 4-8, которая использует функцию first_word из Листинга 4-7.

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

Листинг 4-8: Сохранение результата вызова функции first_word и последующее изменение содержимого String

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

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

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

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

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

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

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

В отличие от ссылки на весь String (как s2), hello — это ссылка на часть String, указанная дополнительным фрагментом [0..5]. Мы создаём срезы, используя диапазон в квадратных скобках, указывая [начальный_индекс..конечный_индекс], где начальный_индекс — это первая позиция в срезе, а конечный_индекс — на единицу больше последней позиции в срезе.

Срезы — особые виды ссылок, потому что они являются “толстыми” указателями, или указателями с метаданными. Здесь метаданные — это длина среза. Мы можем увидеть эти метаданные, изменив визуализацию, чтобы заглянуть внутрь структур данных Rust:

Обратите внимание, что переменные hello и world имеют оба поля ptr и len, которые вместе определяют подчёркнутые области строки в куче. Вы также можете увидеть здесь, как на самом деле выглядит String: строка — это вектор байтов (Vec<u8>), который содержит длину len и буфер buf с указателем ptr и ёмкостью cap.

Поскольку срезы являются ссылками, они также изменяют права на referenced данные. Например, обратите внимание, что при создании hello как среза s, s теряет права на запись и владение:

Синтаксис диапазонов

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

#![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 находится в разделе “Хранение текста, закодированного в UTF-8, со строками” Главы 8.

Переписывание first_word со строковыми срезами

Учитывая всю эту информацию, перепишем first_word для возврата среза. Тип, обозначающий “строковый срез”, записывается как &str:

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

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

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

    &s[..]
}

fn main() {}

Мы получаем индекс конца слова так же, как в Листинге 4-7, ища первое вхождение пробела. Когда находим пробел, возвращаем строковый срез, используя начало строки и индекс пробела в качестве начального и конечного индексов.

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

Возврат среза также сработал бы для функции second_word:

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

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

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

Вы видите, что вызов first_word теперь удаляет право на запись из s, что предотвращает вызов s.clear(). Вот ошибка компилятора:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                  ------ immutable borrow later used here

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

Вспомните из правил заимствования, что если у нас есть неизменяемая ссылка на что-то, мы не можем также взять изменяемую ссылку. Поскольку 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 {

Более опытный Rustacean написал бы сигнатуру, показанную в Листинге 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` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Листинг 4-9: Улучшение функции first_word использованием строкового среза для типа параметра s

Если у нас есть строковый срез, мы можем передать его напрямую. Если у нас есть String, мы можем передать срез String или ссылку на String. Эта гибкость использует неявное преобразование разыменования, особенность, которую мы рассмотрим в разделе “Неявные преобразования разыменования с функциями и методами” Главы 15.

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

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

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

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

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Другие срезы

Строковые срезы, как вы можете себе представить, специфичны для строк. Но есть и более общий тип среза. Рассмотрим этот массив:

#![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]. Он работает так же, как и строковые срезы, храня ссылку на первый элемент и длину. Вы будете использовать этот вид среза для всех sorts других коллекций. Мы подробно обсудим эти коллекции, когда будем говорить о векторах в Главе 8.

Краткое содержание

Срезы — это особый вид ссылки, который ссылается на поддиапазоны последовательности, такие как строка или вектор. Во время выполнения срез представляется как “толстый указатель”, содержащий указатель на начало диапазона и длину диапазона. Одно из преимуществ срезов над диапазонами на основе индексов заключается в том, что срез не может быть недействительным, пока он используется.

Краткое повторение: владение

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

Владение против сборки мусора

Чтобы понять контекст владения, стоит поговорить о сборке мусора (garbage collection). Большинство языков программирования используют сборщик мусора для управления памятью, например, Python, JavaScript, Java и Go. Сборщик мусора работает во время выполнения программы (по крайней мере, трассировочный сборщик). Он сканирует память, чтобы найти данные, которые больше не используются — то есть, запущенная программа больше не может получить доступ к этим данным из локальной переменной функции. Затем сборщик освобождает неиспользуемую память для последующего использования.

Ключевое преимущество сборщика мусора в том, что он предотвращает неопределённое поведение (например, использование освобождённой памяти), которое может происходить в C или C++. Сборка мусора также устраняет необходимость сложной системы типов для проверки неопределённого поведения, как в Rust. Однако у сборки мусора есть несколько недостатков. Один из очевидных недостатков — производительность, поскольку сборка мусора влечёт либо частые небольшие накладные расходы (для подсчёта ссылок, как в Python и Swift), либо редкие крупные накладные расходы (для трассировки, как во всех остальных языках с сборкой мусора).

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

class Document:     
    def __init__(self, words: List[str]):
        """Create a new document"""
        self.words = words

    def add_word(self, word: str):
        """Add a word to the document"""
        self.words.append(word)
        
    def get_words(self) -> List[str]:  
        """Get a list of all the words in the document"""
        return self.words

Вот один из способов использования этого класса Document, который создаёт документ d, копирует его в новый документ d2, а затем изменяет d2.

words = ["Hello"]
d = Document(words)

d2 = Document(d.get_words())
d2.add_word("world")

Рассмотрим два ключевых вопроса об этом примере:

1. Когда массив words будет освобождён? Эта программа создала три указателя на один и тот же массив. Переменные words, d и d2 все содержат указатель на массив words, выделенный в куче. Поэтому Python освободит массив words только тогда, когда все три переменные выйдут из области видимости. В более общем случае, часто бывает трудно предсказать, где данные будут собраны сборщиком мусора, просто прочитав исходный код.

2. Каково содержимое документа d? Поскольку d2 содержит указатель на тот же массив words, что и d, то d2.add_word("world") также изменяет документ d. Поэтому в этом примере слова в d — это ["Hello", "world"]. Это происходит потому, что d.get_words() возвращает изменяемую ссылку на массив words в d. Повсеместные неявные изменяемые ссылки могут легко привести к непредсказуемым ошибкам, когда структуры данных могут раскрывать свою внутреннюю реализацию¹. Здесь, вероятно, не предполагалось, что изменение d2 может изменить d.

Эта проблема не уникальна для Python — вы можете столкнуться с подобным поведением в C#, Java, JavaScript и так далее. Фактически, у большинства языков программирования есть понятие указателей. Вопрос лишь в том, как язык предоставляет указатели программисту. Сборка мусора затрудняет определение, какая переменная указывает на какие данные. Например, было неочевидно, что d.get_words() производит указатель на данные внутри d.

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

#![allow(unused)]
fn main() {
type Document = Vec<String>;

fn new_document(words: Vec<String>) -> Document {
    words
}

fn add_word(this: &mut Document, word: String) {
    this.push(word);
}

fn get_words(this: &Document) -> &[String] {
    this.as_slice()
}
}

Этот API Rust отличается от API Python в нескольких ключевых моментах:

• Функция new_document потребляет владение входным вектором words. Это означает, что Document владеет вектором слов. Вектор слов будет предсказуемо освобождён, когда его владеющий Document выйдет из области видимости.

• Функция add_word требует изменяемую ссылку &mut Document для возможности изменения документа. Она также потребляет владение входным параметром word, что означает, что никто больше не может изменять отдельные слова документа.

• Функция get_words возвращает явную неизменяемую ссылку на строки внутри документа. Единственный способ создать новый документ из этого вектора слов — глубоко скопировать его содержимое, вот так:

fn main() {
    let words = vec!["hello".to_string()];
    let d = new_document(words);

    // .to_vec() преобразует &[String] в Vec<String> путём клонирования каждой строки
    let words_copy = get_words(&d).to_vec();
    let mut d2 = new_document(words_copy);
    add_word(&mut d2, "world".to_string());

    // Изменение `d2` не влияет на `d`
    assert!(!get_words(&d).contains(&"world".into()));
}

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

Концепции владения

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

Владение во время выполнения

Начнём с повторения того, как Rust использует память во время выполнения:

• Rust размещает локальные переменные в кадрах стека, которые выделяются при вызове функции и освобождаются при завершении вызова.
• Локальные переменные могут содержать либо данные (например, числа, булевы значения, кортежи и т.д.), либо указатели.
• Указатели могут быть созданы либо через “ящики” (Box — указатели, владеющие данными в куче), либо через ссылки (невладеющие указатели).

Эта диаграмма иллюстрирует, как каждая концепция выглядит во время выполнения:

Изучите эту диаграмму и убедитесь, что понимаете каждую часть. Например, вы должны быть able ответить на вопросы:

• Почему a_box_stack_ref указывает на стек, в то время как a_box_heap_ref указывает на кучу?
• Почему значение 2 больше не находится в куче на L2?
• Почему a_num имеет значение 5 на L2?

Если вы хотите повторить “ящики” (Box), перечитайте Главу 4.1. Если вы хотите повторить ссылки, перечитайте Главу 4.2. Если вы хотите увидеть исследования случаев с “ящиками” и ссылками, перечитайте Главу 4.3.

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

Если вы хотите повторить срезы, перечитайте Главу 4.4.

Владение на этапе компиляции

Rust отслеживает разрешения R (чтение), W (запись) и O (владение) для каждой переменной. Rust требует, чтобы у переменной были соответствующие разрешения для выполнения заданной операции. В качестве базового примера, если переменная не объявлена как let mut, то у неё отсутствует разрешение W, и её нельзя изменять:

Разрешения переменной могут измениться, если она перемещена (moved) или заимствована (borrowed). Перемещение переменной с типом, не поддерживающим копирование (например, Box<T> или String), требует разрешений RO, и перемещение лишает переменную всех разрешений. Это правило предотвращает использование перемещённых переменных:

Если вы хотите повторить, как работают перемещения, перечитайте Главу 4.1.

Заимствование переменной (создание ссылки на неё) временно удаляет некоторые разрешения переменной. Неизменяемое заимствование создаёт неизменяемую ссылку и также запрещает изменение или перемещение заимствованных данных. Например, печать неизменяемой ссылки допустима:

Но изменение неизменяемой ссылки недопустимо:

И изменение неявно заимствованных данных недопустимо:

И перемещение данных из ссылки недопустимо:

Изменяемое заимствование создаёт изменяемую ссылку, которая запрещает чтение, запись или перемещение заимствованных данных. Например, изменение изменяемой ссылки допустимо:

Но доступ к неявно заимствованным данным недопустим:

Если вы хотите повторить разрешения и ссылки, перечитайте Главу 4.2.

Связь владения между этапом компиляции и выполнением

Разрешения Rust предназначены для предотвращения неопределённого поведения. Например, один вид неопределённого поведения — это использование после освобождения (use-after-free), когда освобождённая память читается или записывается. Неизменяемые заимствования удаляют разрешение W для предотвращения использования после освобождения, как в этом случае:

Другой вид неопределённого поведения — это двойное освобождение (double-free), когда память освобождается дважды. Разыменования ссылок на данные, не поддерживающие копирование, не имеют разрешения O для предотвращения двойных освобождений, как в этом случае:

Если вы хотите повторить неопределённое поведение, перечитайте Главу 4.1 и Главу 4.3.

Остальное о владении

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

И не забывайте пройти викторины, если хотите проверить своё понимание!

1. Фактически, исходное изобретение типов владения вообще не было связано с безопасностью памяти. Оно было направлено на предотвращение утечек изменяемых ссылок на внутренности структур данных в языках, похожих на Java. Если вам интересно узнать больше об истории типов владения, ознакомьтесь со статьёй “Ownership Types for Flexible Alias Protection” (Clarke et al. 1998). ↩

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

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

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

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

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

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

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

fn main() {}

Чтобы использовать структуру после её определения, мы создаём экземпляр этой структуры, указывая конкретные значения для каждого поля. Мы создаём экземпляр, записывая имя структуры, а затем добавляем фигурные скобки, содержащие пары ключ: значение, где ключи — это имена полей, а значения — данные, которые мы хотим хранить в этих полях. Нам не нужно указывать поля в том же порядке, в котором мы объявили их в структуре. Другими словами, определение структуры — это общий шаблон для типа, а экземпляры заполняют этот шаблон конкретными данными, создавая значения типа. Например, мы можем объявить конкретного пользователя, как показано на Листинге 5-2.

Чтобы получить конкретное значение из структуры, мы используем точечную нотацию. Например, чтобы получить адрес электронной почты этого пользователя, мы используем user1.email. Если экземпляр изменяемый, мы можем изменить значение, используя точечную нотацию и присваивание конкретному полю. Листинг 5-3 показывает, как изменить значение в поле email изменяемого экземпляра User.

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

Листинг 5-6: Создание нового экземпляра User с использованием всех, кроме одного, значений из user1

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

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

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

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

Обратите внимание, что синтаксис обновления структур использует =, как присваивание; это происходит потому, что он перемещает данные, как мы видели в разделе “Что такое владение?”. В этом примере после создания user2 user1 частично становится недействительным, потому что String в поле username user1 была перемещена в user2. Если бы мы дали user2 новые значения String как для email, так и для username, и, таким образом, использовали только значения active и sign_in_count из user1, то user1 оставался бы полностью действительным после создания user2. Типы active и sign_in_count — это типы, которые реализуют типаж Copy, поэтому поведение, которое мы обсудили в разделе “Копирование против перемещения из коллекции”, применилось бы.

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

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

Чтобы определить кортежную структуру, начните с ключевого слова struct и имени структуры, за которым следуют типы в кортеже. Например, здесь мы определяем и используем две кортежные структуры с именами Color и Point:

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

Структуры, подобные единичному типу, без каких-либо полей

Вы также можете определить структуры, которые не имеют никаких полей! Они называются структурами, подобными единичному типу, потому что они ведут себя аналогично (), единичному типу, который мы упоминали в разделе “Тип кортежа”. Структуры, подобные единичному типу, могут быть полезны, когда вам нужно реализовать типаж для некоторого типа, но у вас нет данных, которые вы хотите хранить в самом типе. Мы обсудим типажи в Главе 10. Вот пример объявления и создания экземпляра структуры, подобной единичному типу, с именем AlwaysEqual:

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

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

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

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

Заимствование полей структуры

Подобно нашему обсуждению в “Разные поля кортежа”, проверка заимствований Rust будет отслеживать разрешения владения как на уровне структуры, так и на уровне поля. Например, если мы заимствуем поле x структуры Point, то и p, и p.x временно теряют свои разрешения (но не p.y):

В результате, если мы попытаемся использовать p, пока p.x заимствован изменяемо, как здесь:

Тогда компилятор отклонит нашу программу со следующей ошибкой:

error[E0502]: cannot borrow `p` as immutable because it is also borrowed as mutable
  --> test.rs:10:17
   |
9  |     let x = &mut p.x;
   |             -------- mutable borrow occurs here
10 |     print_point(&p);
   |                 ^^ immutable borrow occurs here
11 |     *x += 1;
   |     ------- mutable borrow later used here

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

Пример программы с использованием структур

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

Создадим новый бинарный проект Cargo с именем rectangles. Оно будет принимать ширину и высоту прямоугольника в пикселях и вычислять его площадь. Листинг 5-8 показывает короткую программу, которая делает это в файле src/main.rs нашего проекта.

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

Теперь запустите эту программу с помощью cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

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

Проблема этого кода очевидна в сигнатуре функции area:

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

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

Рефакторинг с использованием кортежей

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

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

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

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

Рефакторинг со структурами: добавление большего смысла

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

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

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

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

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

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

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

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

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

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

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

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

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

Макрос println! может делать многие виды форматирования, и по умолчанию фигурные скобки говорят 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 is {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 is {rect1:?}");
}

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

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

Отлично! Это не самый красивый вывод, но он показывает значения всех полей этого экземпляра, что определённо поможет во время отладки. Когда у нас есть более крупные структуры, полезно иметь вывод, который немного легче читать; в таких случаях мы можем использовать {:#?} вместо {:?} в строке println!. В этом примере использование стиля {:#?} выведет следующее:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

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

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

Вот пример, где нас интересует значение, присваиваемое полю width, а также значение всей структуры в rect1:

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

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

Мы можем поместить dbg! вокруг выражения 30 * scale, и поскольку dbg! возвращает владение значением выражения, поле width получит то же значение, что и если бы у нас не было вызова dbg!. Мы не хотим, чтобы 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,
}

Мы видим, что первая часть вывода пришла из файла src/main.rs строки 10, где мы отлаживаем выражение 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 и Главе 18 соответственно), и их первый параметр всегда self, который представляет экземпляр структуры, для которого вызывается метод.

Определение методов

Давайте изменим функцию area, которая принимает экземпляр Rectangle в качестве параметра, и вместо этого сделаем метод area, определённый для структуры Rectangle, как показано в Листинге 5-13.

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

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

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

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

Мы выбрали &self здесь по той же причине, по которой использовали &Rectangle в версии функции: мы не хотим принимать владение, а просто хотим прочитать данные в структуре, не записывая в неё. Если бы мы хотели изменить экземпляр, для которого вызывается метод, в рамках того, что делает метод, мы бы использовали &mut self в качестве первого параметра. Наличие метода, который принимает владение экземпляром, используя только self в качестве первого параметра, встречается редко; эта техника обычно используется, когда метод преобразует self во что-то ещё, и вы хотите предотвратить использование исходного экземпляра вызывающей стороной после преобразования.

Основная причина использования методов вместо функций, помимо предоставления синтаксиса методов и необходимости повторять тип self в сигнатуре каждого метода, — это организация. Мы поместили всё, что мы можем делать с экземпляром типа, в один блок impl, а не заставляем будущих пользователей нашего кода искать возможности Rectangle в различных местах в предоставляемой нами библиотеке.

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

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

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

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

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

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

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

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

Давайте потренируемся в использовании методов, реализовав второй метод для структуры Rectangle. На этот раз мы хотим, чтобы экземпляр Rectangle принимал другой экземпляр Rectangle и возвращал true, если второй Rectangle может полностью поместиться внутри self (первого Rectangle); в противном случае он должен вернуть false. То есть, как только мы определим метод can_hold, мы хотим иметь возможность написать программу, показанную в Листинге 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Ожидаемый вывод будет выглядеть следующим образом, потому что обе размерности rect2 меньше размерностей rect1, но rect3 шире, чем rect1:

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

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

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

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

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

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

Ассоциированные функции, которые не являются методами, часто используются для конструкторов, которые будут возвращать новый экземпляр структуры. Их часто называют new, но new — это не специальное имя и не встроено в язык. Например, мы могли бы предоставить ассоциированную функцию с именем square, которая бы имела один параметр размерности и использовала его как для ширины, так и для высоты, тем самым упрощая создание квадратного Rectangle, вместо того чтобы указывать одно и то же значение дважды:

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

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

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

Ключевые слова Self в возвращаемом типе и в теле функции являются псевдонимами для типа, который появляется после ключевого слова impl, который в данном случае — Rectangle.

Чтобы вызвать эту ассоциированную функцию, мы используем синтаксис :: с именем структуры; let sq = Rectangle::square(3); — это пример. Эта функция пространства имён структуры: синтаксис :: используется как для ассоциированных функций, так и для пространств имён, создаваемых модулями. Мы обсудим модули в Главе 7.

Несколько блоков impl

Каждой структуре разрешено иметь несколько блоков impl. Например, Листинг 5-15 эквивалентен коду, показанному в Листинге 5-16, где каждый метод находится в своём блоке impl.

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

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

Вызовы методов — это синтаксический сахар для вызовов функций

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

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn set_width(&mut self, width: u32) {
        self.width = width;
    }
}

И предположим, что у нас есть прямоугольник r. Тогда вызовы методов r.area() и r.set_width(2) эквивалентны этому:

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

impl Rectangle {
    fn area(&self) -> u32 {
       self.width * self.height
     }

    fn set_width(&mut self, width: u32) {
        self.width = width;
    }
}

fn main() {
    let mut r = Rectangle { 
        width: 1,
        height: 2
    };
    let area1 = r.area();
    let area2 = Rectangle::area(&r);
    assert_eq!(area1, area2);

    r.set_width(2);
    Rectangle::set_width(&mut r, 2);
}

Вызов метода r.area() становится Rectangle::area(&r). Имя функции — это ассоциированная функция Rectangle::area. Аргумент функции — это параметр &self. Rust автоматически вставляет оператор заимствования &.

Примечание: если вы знакомы с C или C++, вы привыкли к двум разным синтаксисам для вызовов методов: r.area() и r->area(). У Rust нет эквивалента оператору стрелки ->. Rust автоматически ссылается и разыменовывает получатель метода при использовании оператора точки.

Вызов метода r.set_width(2) аналогично становится Rectangle::set_width(&mut r, 2). Этот метод ожидает &mut self, поэтому первый аргумент — изменяемая ссылка &mut r. Второй аргумент точно такой же, число 2.

Как мы описали в Главе 4.2 “Разыменование указателя даёт доступ к его данным”, Rust вставит столько ссылок и разыменований, сколько нужно, чтобы типы совпали для параметра self. Например, вот два эквивалентных вызова area для изменяемой ссылки на коробчатый прямоугольник:

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

impl Rectangle {
    fn area(&self) -> u32 {
       self.width * self.height
     }

    fn set_width(&mut self, width: u32) {
        self.width = width;
    }
}
fn main() {
    let r = &mut Box::new(Rectangle { 
        width: 1,
        height: 2
    });
    let area1 = r.area();
    let area2 = Rectangle::area(&**r);
    assert_eq!(area1, area2);
}

Rust добавит два разыменования (один для изменяемой ссылки, один для коробки), а затем одну неизменяемую ссылку, потому что area ожидает &Rectangle. Обратите внимание, что это также ситуация, когда изменяемая ссылка “понижается” до общей ссылки, как мы обсуждали в Главе 4.2. И наоборот, вам не будет разрешено вызвать set_width на значении типа &Rectangle или &Box<Rectangle>.

Методы и владение

Как мы обсуждали в Главе 4.2 “Ссылки и заимствование”, методы должны вызываться для структур, которые имеют необходимые права. В качестве работающего примера мы будем использовать эти три метода, которые принимают &self, &mut self и self соответственно.

impl Rectangle {    
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn set_width(&mut self, width: u32) {
        self.width = width;
    }

    fn max(self, other: Rectangle) -> Rectangle {
        Rectangle { 
            width: self.width.max(other.width),
            height: self.height.max(other.height),
        }
    }
}

Чтение и запись с &self и &mut self

Если мы создаём владеющий прямоугольник с let rect = Rectangle { ... }, то rect имеет права R и O. С этими правами допустимо вызвать методы area и max:

Однако, если мы попытаемся вызвать set_width, у нас не хватает права W:

Rust отклонит эту программу с соответствующим сообщением об ошибке:

error[E0596]: cannot borrow `rect` as mutable, as it is not declared as mutable
  --> test.rs:28:1
   |
24 | let rect = Rectangle {
   |     ---- help: consider changing this to be mutable: `mut rect`
...
28 | rect.set_width(0);
   | ^^^^^^^^^^^^^^^^^ cannot borrow as mutable

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

Перемещения с self

Вызов метода, который ожидает self, переместит входную структуру (если только структура не реализует Copy). Например, мы не можем использовать Rectangle после передачи его в max:

Как только мы вызываем rect.max(..), мы перемещаем rect и теряем все права на него. Попытка скомпилировать эту программу даст нам следующую ошибку:

error[E0382]: borrow of moved value: `rect`
  --> test.rs:33:16
   |
24 | let rect = Rectangle {
   |     ---- move occurs because `rect` has type `Rectangle`, which does not implement the `Copy` trait
...
32 | let max_rect = rect.max(other_rect);
   |                     --------------- `rect` moved due to this method call
33 | println!("{}", rect.area());
   |                ^^^^^^^^^^^ value borrowed here after move

Аналогичная ситуация возникает, если мы пытаемся вызвать метод self на ссылку. Например, предположим, что мы попытались сделать метод set_to_max, который присваивает self результату self.max(..):

Тогда мы можем видеть, что self не имеет прав O в операции self.max(..). Поэтому Rust отклоняет эту программу со следующим сообщением об ошибке:

error[E0507]: cannot move out of `*self` which is behind a mutable reference
  --> test.rs:23:17
   |
23 |         *self = self.max(other);
   |                 ^^^^^----------
   |                 |    |
   |                 |    `*self` moved due to this method call
   |                 move occurs because `*self` has type `Rectangle`, which does not implement the `Copy` trait
   |

Это тот же тип ошибки, который мы обсуждали в Главе 4.3 “Копирование против перемещения из коллекции”.

Хорошие перемещения и плохие перемещения

Вы можете спросить: почему имеет значение, перемещаем ли мы из *self? На самом деле, для случая Rectangle это безопасно перемещать из *self, хотя Rust не позволяет вам этого сделать. Например, если мы смоделируем программу, которая вызывает отклонённый set_to_max, вы можете видеть, что ничего небезопасного не происходит:

Причина, по которой безопасно перемещать из *self, заключается в том, что Rectangle не владеет данными в куче. На самом деле, мы можем заставить Rust скомпилировать set_to_max, просто добавив #[derive(Copy, Clone)] к определению Rectangle:

Обратите внимание, что в отличие от предыдущего случая, self.max(other) больше не требует права O на *self или other. Помните, что self.max(other) раскрывается в Rectangle::max(*self, other). Разыменование *self не требует владения над *self, если Rectangle копируем.

Вы можете спросить: почему Rust не автоматически выводит Copy для Rectangle? Rust не автоматически выводит Copy для стабильности при изменениях API. Представьте, что автор типа Rectangle решил добавить поле name: String. Тогда весь клиентский код, который полагается на то, что Rectangle является Copy, внезапно будет отклонён компилятором. Чтобы избежать этой проблемы, авторы API должны явно добавить #[derive(Copy)], чтобы указать, что они ожидают, что их структура всегда будет Copy.

Чтобы лучше понять проблему, давайте запустим симуляцию. Допустим, мы добавили name: String в Rectangle. Что произойдёт, если Rust разрешит компиляцию set_to_max?

В этой программе мы вызываем set_to_max с двумя прямоугольниками r1 и r2. self — это изменяемая ссылка на r1, а other — это перемещение r2. После вызова self.max(other) метод max потребляет владение обоими прямоугольниками. Когда max возвращается, Rust освобождает обе строки “r1” и “r2” в куче. Обратите внимание на проблему: в месте L2 *self должен быть читаемым и записываемым. Однако (*self).name (фактически r1.name) была освобождена.

Поэтому, когда мы делаем *self = max, мы сталкиваемся с неопределённым поведением. Когда мы перезаписываем *self, Rust неявно удалит данные, которые ранее были в *self. Чтобы сделать это поведение явным, мы добавили drop(*self). После вызова drop(*self) Rust пытается освободить (*self).name во второй раз. Это действие — двойное освобождение, что является неопределённым поведением.

Поэтому помните: когда вы видите ошибку вроде “cannot move out of *self”, это обычно потому, что вы пытаетесь вызвать метод self на ссылку, такую как &self или &mut self. Rust защищает вас от двойного освобождения.

Итоги

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

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

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

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

Здесь мы определили структуру IpAddr, которая имеет два поля: поле kind типа IpAddrKind (перечисление, которое мы определили ранее) и поле address типа String. У нас есть два экземпляра этой структуры. Первый — home, и у него значение IpAddrKind::V4 в качестве kind с связанными данными адреса 127.0.0.1. Второй экземпляр — loopback. У него другой вариант IpAddrKind в качестве значения kind, V6, и связанный с ним адрес ::1. Мы использовали структуру, чтобы сгруппировать значения kind и address, теперь вариант связан со значением.

Однако представление той же концепции с помощью только перечисления более лаконично: вместо перечисления внутри структуры мы можем поместить данные непосредственно в каждый вариант перечисления. Это новое определение перечисления IpAddr говорит, что оба варианта V4 и V6 будут иметь связанные значения String:

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

Есть ещё одно преимущество использования перечисления вместо структуры: каждый вариант может иметь разные типы и количество связанных данных. IP-адреса четвёртой версии всегда будут иметь четыре числовых компонента со значениями от 0 до 255. Если бы мы хотели хранить адреса V4 как четыре значения u8, но по-прежнему выражать адреса V6 как одно значение String, мы не смогли бы этого сделать со структурой. Перечисления легко справляются с этим случаем:

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

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

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

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

Давайте посмотрим на ещё один пример перечисления в листинге 6-2: в нём содержится большое разнообразие типов, встроенных в его варианты.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

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

• Quit: Не имеет связанных с ним данных вообще
• Move: Имеет именованные поля, как структура
• Write: Включает одну String
• ChangeColor: Включает три значения i32

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

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

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) {
            // method body would be defined here
        }
    }

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

Синтаксис <T> — это особенность Rust, о которой мы ещё не говорили. Это обобщённый параметр типа, и мы подробнее рассмотрим обобщения в главе 10. Пока всё, что вам нужно знать, это то, что <T> означает, что вариант Some перечисления Option может хранить один фрагмент данных любого типа, и что каждый конкретный тип, который используется вместо T, делает общий тип Option<T> другим типом. Вот несколько примеров использования значений Option для хранения числовых типов и типов символов:

Тип 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>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

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

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

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

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

Так как же вы получаете значение 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, где каждая ветвь просто возвращает значение. Если нужно выполнить несколько строк кода в ветви match, необходимо использовать фигурные скобки, а запятая после ветви тогда необязательна. Например, следующий код выводит «Lucky penny!» каждый раз, когда функция вызывается с Coin::Penny, но всё равно возвращает последнее значение блока, 1:

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

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Образцы, привязывающие к значениям

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

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

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn main() {}

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

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

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

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

Если бы мы вызвали value_in_cents(Coin::Quarter(UsState::Alaska)), coin был бы Coin::Quarter(UsState::Alaska). Когда мы сравниваем это значение с каждой ветвью match, ни одна не совпадёт, пока мы не дойдём до Coin::Quarter(state). В этот момент привязка для state будет значением UsState::Alaska. Затем мы можем использовать эту привязку в выражении println!, таким образом получая внутреннее значение штата из варианта Quarter перечисления Coin.

Сопоставление с Option<T>

В предыдущем разделе мы хотели извлечь внутреннее значение T из случая Some при использовании Option<T>; мы также можем обрабатывать Option<T> с помощью match, как мы делали с перечислением Coin! Вместо сравнения монет мы будем сравнивать варианты Option<T>, но способ работы выражения match остаётся тем же.

Допустим, мы хотим написать функцию, которая принимает Option<i32> и, если внутри есть значение, добавляет 1 к этому значению. Если внутри нет значения, функция должна вернуть значение None и не пытаться выполнять никаких операций.

Эту функцию очень легко написать благодаря match, и она будет выглядеть как в Листинге 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Рассмотрим первый вызов plus_one более подробно. Когда мы вызываем plus_one(five), переменная x в теле plus_one будет иметь значение Some(5). Затем мы сравниваем его с каждой ветвью 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);
}

Значение 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 привязывается к значению, contained в Some, поэтому i принимает значение 5. Затем выполняется код в ветви match, поэтому мы добавляем 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, который нужно обсудить: образцы ветвей должны покрывать все возможности. Рассмотрим эту версию нашей функции plus_one, в которой есть ошибка и которая не скомпилируется:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Мы не обработали случай None, поэтому этот код вызовет ошибку. К счастью, это ошибка, которую Rust умеет ловить. Если мы попытаемся скомпилировать этот код, получим следующую ошибку:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/4eb161250e340c8f48f66e2b929ef4a5bed7c181/library/core/src/option.rs:572:1
 ::: /rustc/4eb161250e340c8f48f66e2b929ef4a5bed7c181/library/core/src/option.rs:576:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

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

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

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

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

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

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

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

Наконец, изменим правила игры ещё раз так, чтобы ничего не происходило в ваш ход, если вы бросите что-либо кроме 3 или 7. Мы можем выразить это, используя единичное значение (пустой тип кортежа, упомянутый в разделе «Тип кортежа») в качестве кода, который идёт с ветвью _:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

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

Есть больше об образцах и сопоставлении, что мы рассмотрим в Главе 19.

Как соответствия взаимодействуют с владением

Если перечисление содержит некопируемые данные, такие как String, то следует быть осторожным с тем, перемещает или заимствует match эти данные. Например, эта программа с использованием Option<String> скомпилируется:

Но если мы заменим заполнитель в Some(_) на имя переменной, например Some(s), то программа НЕ скомпилируется:

opt — это обычное перечисление — его тип Option<String>, а не ссылка, такая как &Option<String>. Поэтому match по opt переместит неигнорируемые поля, такие как s. Обратите внимание, как opt теряет разрешения на чтение и владение раньше во второй программе по сравнению с первой. После выражения match данные внутри opt были перемещены, поэтому чтение opt в println недопустимо.

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

Rust «протолкнёт» ссылку из внешнего перечисления, &Option<String>, во внутреннее поле, &String. Поэтому s имеет тип &String, и opt можно использовать после match. Чтобы лучше понять механизм «проталкивания», см. раздел о режимах привязки в Справочнике Rust.

Краткий контроль потока выполнения с if let и let else

Синтаксис if let позволяет объединить if и let в более краткий способ обработки значений, которые соответствуют одному образцу, игнорируя остальные. Рассмотрим программу из Листинга 6-6, которая сопоставляет значение Option<u8> в переменной config_max, но хочет выполнить код только если значение является вариантом Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

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

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

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

Синтаксис if let принимает образец и выражение, разделённые знаком равенства. Он работает так же, как match, где выражение передаётся в 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,
    // --snip--
}

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

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

Или мы могли бы использовать выражение if let и else, вот так:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

Оставаться на «счастливом пути» с let...else

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

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

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

Затем мы могли бы использовать if let для сопоставления с типом монеты, вводя переменную state в теле условия, как в Листинге 6-7.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

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

Это решает задачу, но переносит работу в тело оператора if let, и если работа, которую нужно выполнить, более сложная, может быть трудно понять, как именно связаны верхние ветви. Мы также могли бы воспользоваться тем, что выражения производят значение, либо чтобы получить state из if let, либо чтобы вернуться досрочно, как в Листинге 6-8. (Вы могли бы сделать подобное и с match.)

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

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

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

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

В Листинге 6-9 вы можете увидеть, как выглядит Листинг 6-8 при использовании let...else вместо if let.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

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

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

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

Резюме

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

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

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

Инвентаризация владения #1

«Инвентаризация владения» — это серия вопросов, проверяющих ваше понимание владения в реальных сценариях. Эти сценарии вдохновлены распространёнными вопросами о Rust на StackOverflow. Вы можете использовать эти вопросы, чтобы проверить, насколько хорошо вы понимаете владение на данный момент.

Новая технология: веб-среда разработки

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

• Наведите курсор мыши на replace, чтобы увидеть его тип и описание.
• Наведите курсор мыши на s2, чтобы увидеть его выведенный тип.

/// Превращает строку в гораздо более захватывающую строку
fn make_exciting(s: &str) -> String {
  let s2 = s.replace(".", "!");
  let s3 = s2.replace("?", "‽");
  s3
}

Несколько важных оговорок об этой экспериментальной технологии:

СОВМЕСТИМОСТЬ С ПЛАТФОРМАМИ: веб-среда разработки не работает на сенсорных экранах. Она была протестирована только в Google Chrome 109 и Firefox 107. Она может не работать в более старых версиях Safari.

ИСПОЛЬЗОВАНИЕ ПАМЯТИ: веб-среда разработки использует сборку WebAssembly rust-analyzer, которая может занимать значительный объём памяти. Каждый экземпляр среды, по-видимому, занимает около ~300 МБ. (Примечание: мы также получили некоторые сообщения об использовании >10 ГБ памяти.)

ПРОКРУТКА: веб-среда разработки «съест» ваш курсор, если он пересекается с редактором при прокрутке. Если у вас возникают проблемы с прокруткой страницы, попробуйте переместить курсор на самую правую полосу прокрутки.

ВРЕМЯ ЗАГРУЗКИ: среда может занимать до 15 секунд для инициализации новой программы. Она будет отображать «Загрузка…», пока вы взаимодействуете с кодом в редакторе.

Вопросы

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

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

Все программы, которые мы писали до сих пор, находились в одном модуле в одном файле. По мере роста проекта следует организовать код, разделив его на несколько модулей, а затем и на несколько файлов. Пакет может содержать несколько бинарных крейтов и, опционально, один библиотечный крейт. По мере роста пакета вы можете выделить части в отдельные крейты, которые станут внешними зависимостями. В этой главе рассматриваются все эти техники. Для очень больших проектов, состоящих из набора взаимосвязанных пакетов, развивающихся вместе, Cargo предоставляет рабочие пространства (workspaces), которые мы рассмотрим в главе 14 в разделе “Cargo Workspaces”.

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

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

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

• Пакеты: Возможность Cargo, позволяющая собирать, тестировать и делиться крейтами
• Крейты: Дерево модулей, которое производит библиотеку или исполняемый файл
• Модули и use: Позволяют управлять организацией, областью видимости и приватностью путей
• Пути: Способ именования элемента, такого как структура, функция или модуль

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

Пакеты и крейты

Первые элементы системы модулей, которые мы рассмотрим, — это пакеты и крейты.

Крейт — это минимальный объём кода, который компилятор Rust рассматривает за один раз. Даже если вы запускаете rustc вместо cargo и передаёте один файл с исходным кодом (как мы делали в разделе «Написание и запуск программы на Rust» в главе 1), компилятор считает этот файл крейтом. Крейты могут содержать модули, и модули могут быть определены в других файлах, которые компилируются вместе с крейтом, как мы увидим в следующих разделах.

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

Библиотечные крейты не имеют функции main и не компилируются в исполняемый файл. Вместо этого они определяют функциональность, предназначенную для использования в нескольких проектах. Например, крейт rand, который мы использовали в главе 2, предоставляет функциональность для генерации случайных чисел. Чаще всего, когда разработчики Rust говорят «крейт», они имеют в виду библиотечный крейт и используют слово «крейт» как синоним общего понятия «библиотека» в программировании.

Корень крейта — это исходный файл, с которого начинает работу компилятор Rust и который составляет корневой модуль вашего крейта (мы подробно объясним модули в разделе «Определение модулей для управления областью видимости и доступом»)modules).

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

Шпаргалка по модулям

Прежде чем углубиться в детали модулей и путей, вот краткая справка о том, как работают модули, пути, ключевое слово use и ключевое слово pub в компиляторе, и как большинство разработчиков организуют свой код. Мы будем рассматривать примеры каждого из этих правил в этой главе, но это отличное место для справки о том, как работают модули.

• Начинайте с корня крейта: При компиляции крейта компилятор сначала ищет код для компиляции в корневом файле крейта (обычно src/lib.rs для библиотечного крейта или src/main.rs для бинарного крейта).
• Объявление модулей: В корневом файле крейта вы можете объявлять новые модуules; допустим, вы объявляете модуль “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 в модуле garden vegetables будет находиться по пути crate::garden::vegetables::Asparagus.
• Приватное vs публичное: Код внутри модуля по умолчанию приватный для его родительских модулей. Чтобы сделать модуль публичным, объявите его с помощью pub mod вместо mod. Чтобы сделать элементы внутри публичного модуля также публичными, используйте pub перед их объявлениями.
• Ключевое слово use: Внутри области видимости ключевое слово use создаёт сокращения для элементов, чтобы уменьшить повторение длинных путей. В любой области видимости, которая может ссылаться на crate::garden::vegetables::Asparagus, вы можете создать сокращение с помощью use crate::garden::vegetables::Asparagus; и с тех пор вам нужно будет писать только Asparagus для использования этого типа в области видимости.

Здесь мы создаём бинарный крейт с именем backyard, который иллюстрирует эти правила. Директория крейта, также названная backyard, содержит эти файлы и директории:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Корневой файл крейта в этом случае — src/main.rs, и он содержит:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

Строка pub mod garden; говорит компилятору включить код, который он находит в src/garden.rs, а это:

pub mod vegetables;

Здесь pub mod vegetables; означает, что код в src/garden/vegetables.rs также включается. Этот код:

#[derive(Debug)]
pub struct Asparagus {}

Теперь давайте подробно разберём эти правила и продемонстрируем их в действии!

Группировка связанного кода в модулях

Модули позволяют нам организовывать код внутри крейта для читаемости и простоты повторного использования. Модули также позволяют нам контролировать доступность элементов, потому что код внутри модуля по умолчанию приватный. Приватные элементы — это внутренние детали реализации, недоступные для использования извне. Мы можем выбрать, чтобы сделать модули и элементы внутри них публичными, что открывает их для внешнего кода, чтобы тот мог их использовать и зависеть от них.

В качестве примера давайте напишем библиотечный крейт, который предоставляет функциональность ресторана. Мы определим сигнатуры функций, но оставим их тела пустыми, чтобы сосредоточиться на организации кода, а не на реализации ресторана.

В индустрии общественного питания некоторые части ресторана называются передней частью зала (front of house), а другие — задней частью зала (back of house). Передняя часть зала — это место, где находятся клиенты; это включает в себя, где хостессы рассаживают клиентов, официанты принимают заказы и оплату, а бармены готовят напитки. Задняя часть зала — это место, где повара и кухонные работники работают на кухне, мойщики убирают, а менеджеры занимаются административной работой.

Чтобы структурировать наш крейт таким образом, мы можем организовать его функции во вложенные модули. Создайте новую библиотеку с именем restaurant, выполнив cargo new restaurant --lib. Затем введите код из Листинга 7-1 в src/lib.rs, чтобы определить некоторые модули и сигнатуры функций; этот код представляет раздел передней части зала.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Мы определяем модуль с помощью ключевого слова mod, за которым следует имя модуля (в этом случае front_of_house). Тело модуля затем помещается внутрь фигурных скобок. Внутри модулей мы можем размещать другие модули, как в этом случае с модулями hosting и serving. Модули также могут содержать определения других элементов, таких как структуры, перечисления, константы, типажи и, как в Листинге 7-1, функции.

Используя модули, мы можем группировать связанные определения вместе и обозначать, почему они связаны. Программисты, использующие этот код, могут ориентироваться в коде на основе групп, а не читать все определения, что облегчает поиск определений, актуальных для них. Программисты, добавляющие новую функциональность в этот код, будут знать, где разместить код, чтобы сохранить программу организованной.

Ранее мы упоминали, что src/main.rs и src/lib.rs называются корнями крейта. Причина их названия в том, что содержимое любого из этих двух файлов образует модуль с именем crate в корне структуры модулей крейта, известной как дерево модулей.

Листинг 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() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    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 для старта с корня крейта аналогично использованию / для старта с корня файловой системы в вашей оболочке.

Второй раз мы вызываем 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() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

К сожалению, код в Листинге 7-5 по-прежнему приводит к ошибкам компилятора, как показано в Листинге 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
3  |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
3  |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

Что произошло? Добавление ключевого слова pub перед mod hosting делает модуль публичным. С этим изменением, если мы можем получить доступ к front_of_house, мы можем получить доступ к hosting. Но содержимое hosting по-прежнему приватно; простое сделание модуля публичным не делает его содержимое публичным. Ключевое слово pub на модуле только позволяет коду в его модулях-предках ссылаться на него, но не даёт доступа к его внутреннему коду. Поскольку модули — это контейнеры, мы не можем сделать много, только сделав модуль публичным; нам нужно пойти дальше и выбрать, сделать ли один или несколько элементов внутри модуля публичными.

Ошибки в Листинге 7-6 говорят, что функция add_to_waitlist приватная. Правила конфиденциальности применяются к структурам, перечислениям, функциям и методам, а также к модулям.

Давайте также сделаем функцию add_to_waitlist публичной, добавив ключевое слово pub перед её определением, как в Листинге 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Теперь код скомпилируется! Чтобы понять, почему добавление ключевого слова pub позволяет нам использовать эти пути в eat_at_restaurant с точки зрения правил конфиденциальности, давайте посмотрим на абсолютный и относительный пути.

В абсолютном пути мы начинаем с crate — корня дерева модулей нашего крейта. Модуль front_of_house определён в корне крейта. Хотя front_of_house не является публичным, потому что функция eat_at_restaurant определена в том же модуле, что и front_of_house (то есть eat_at_restaurant и front_of_house являются sibling-ами), мы можем ссылаться на 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, чтобы упростить зависимость от вашего крейта. Эти соображения выходят за рамки этой книги; если вас интересует эта тема, см. Руководство по Rust API.

Начало относительных путей с super

Мы можем построить относительные пути, которые начинаются в родительском модуле, а не в текущем модуле или корне крейта, используя super в начале пути. Это аналогично началу пути файловой системы с синтаксиса .., который означает переход в родительский каталог. Использование super позволяет нам ссылаться на элемент, который, как мы знаем, находится в родительском модуле, что может облегчить перестановку дерева модулей, когда модуль тесно связан с родителем, но родитель может быть перемещён в другое место дерева модулей в будущем.

Рассмотрим код в Листинге 7-8, который моделирует ситуацию, когда повар исправляет неправильный заказ и лично выносит его клиенту. Функция fix_incorrect_order, определённая в модуле back_of_house, вызывает функцию deliver_order, определённую в родительском модуле, указывая путь к deliver_order, начиная с super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

Функция fix_incorrect_order находится в модуле back_of_house, поэтому мы можем использовать super, чтобы перейти к родительскому модулю back_of_house, которым в данном случае является crate — корень. Оттуда мы ищем deliver_order и находим его. Успех! Мы думаем, что модуль back_of_house и функция deliver_order, скорее всего, останутся в тех же отношениях друг к другу и будут перемещены вместе, если мы решим реорганизовать дерево модулей крейта. Поэтому мы использовали super, чтобы в будущем при перемещении этого кода в другой модуль нам пришлось обновлять меньше мест.

Сделание структур и перечислений публичными

Мы также можем использовать pub, чтобы обозначить структуры и перечисления как публичные, но есть несколько дополнительных деталей в использовании pub со структурами и перечислениями. Если мы используем pub перед определением структуры, мы делаем структуру публичной, но поля структуры по-прежнему будут приватными. Мы можем сделать каждое поле публичным или нет на индивидуальной основе. В Листинге 7-9 мы определили публичную структуру back_of_house::Breakfast с публичным полем toast, но приватным полем seasonal_fruit. Это моделирует ситуацию в ресторане, где клиент может выбрать тип хлеба, который идёт с едой, но повар решает, какой фрукт сопровождает еду, исходя из сезона и наличия. Доступные фрукты быстро меняются, поэтому клиенты не могут выбрать фрукт или даже увидеть, какой фрукт они получат.

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal.
    // meal.seasonal_fruit = String::from("blueberries");
}

Поскольку поле 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, каждый раз при её вызове нам также требовалось указывать front_of_house и hosting. К счастью, есть способ упростить этот процесс: мы можем один раз создать ярлык для пути с помощью ключевого слова use, а затем использовать это короткое имя везде в области видимости.

В Листинге 7-11 мы делаем модуль crate::front_of_house::hosting доступным в области видимости функции eat_at_restaurant, поэтому для вызова функции add_to_waitlist в eat_at_restaurant нам нужно указать только hosting::add_to_waitlist.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Добавление use и пути в область видимости похоже на создание символической ссылки в файловой системе. Добавив use crate::front_of_house::hosting в корень крейта, hosting становится допустимым именем в этой области видимости, так как будто бы модуль hosting был определён в корне крейта. Пути, сделанные доступными с помощью use, также проверяют правила приватности, как и любые другие пути.

Обратите внимание, что use создаёт ярлык только для конкретной области видимости, в которой находится это 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 {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    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 {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    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(), что также требовало, чтобы модуль front_of_house был помечен как pub. Теперь, когда этот pub use реэкспортировал модуль hosting из корневого модуля, внешний код может использовать путь restaurant::hosting::add_to_waitlist() вместо этого.

Реэкспорт полезен, когда внутренняя структура вашего кода отличается от того, как программисты, вызывающие ваш код, думают о предметной области. Например, в этой метафоре ресторана владельцы ресторана думают о «передней части дома» и «задней части дома». Но посетители ресторана, вероятно, не будут думать о частях ресторана в этих терминах. С помощью 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!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Члены сообщества 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;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Вместо этого мы можем использовать вложенные пути, чтобы сделать те же элементы доступными в одной строке. Мы делаем это, указывая общую часть пути, за которой следуют два двоеточия, а затем фигурные скобки вокруг списка частей путей, которые отличаются, как показано в Листинге 7-18.

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

В больших программах доступ ко многим элементам из одного и того же крейта или модуля с помощью вложенных путей может значительно сократить количество отдельных операторов 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.

Глобальный оператор

Если мы хотим сделать все публичные элементы, определённые в пути, доступными, мы можем указать этот путь, за которым следует глобальный оператор *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Этот оператор use делает все публичные элементы, определённые в std::collections, доступными в текущей области видимости. Будьте осторожны при использовании глобального оператора! Глобальный оператор может затруднить определение того, какие имена находятся в области видимости и где было определено используемое в вашей программе имя. Кроме того, если зависимость изменит свои определения, то то, что вы импортировали, также изменится, что может привести к ошибкам компиляции при обновлении зависимости, если зависимость добавит определение с тем же именем, что и ваше определение в той же области видимости, например.

Глобальный оператор часто используется при тестировании, чтобы сделать всё под тестом доступным в модуле tests; мы поговорим об этом в разделе «Как писать тесты» в Главе 11. Глобальный оператор также иногда используется как часть шаблона прелюдии: см. документацию стандартной библиотеки для получения дополнительной информации об этом шаблоне.

Разделение модулей на разные файлы

До сих пор все примеры в этой главе определяли несколько модулей в одном файле. Когда модули становятся большими, вы можете захотеть переместить их определения в отдельный файл, чтобы упростить навигацию по коду.

Например, начнём с кода из листинга 7-17, в котором были несколько модулей ресторана. Мы извлечём модули в файлы вместо того, чтобы определять все модули в файле корня крейта. В данном случае файлом корня крейта является src/lib.rs, но эта процедура также работает с бинарными крейтами, чей файл корня крейта — src/main.rs.

Сначала мы извлечём модуль front_of_house в собственный файл. Удалите код внутри фигурных скобок для модуля front_of_house, оставив только объявление mod front_of_house;, так что src/lib.rs содержит код, показанный в листинге 7-21. Обратите внимание, что это не скомпилируется, пока мы не создадим файл src/front_of_house.rs из листинга 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Далее поместите код, который был в фигурных скобках, в новый файл с именем src/front_of_house.rs, как показано в листинге 7-22. Компилятор знает, что нужно искать в этом файле, потому что он наткнулся на объявление модуля в корне крейта с именем front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Обратите внимание, что вам нужно загрузить файл с помощью объявления mod только один раз в вашем дереве модулей. Как только компилятор знает, что файл является частью проекта (и знает, где в дереве модулей находится код, благодаря тому, где вы поместили оператор mod), другие файлы в вашем проекте должны ссылаться на код загруженного файла, используя путь к месту, где он был объявлен, как описано в разделе «Пути для ссылки на элемент в дереве модулей». Другими словами, mod — это не операция «включения», которую вы могли видеть в других языках программирования.

Далее мы извлечём модуль hosting в собственный файл. Процесс немного отличается, потому что hosting является дочерним модулем front_of_house, а не корневого модуля. Мы поместим файл для hosting в новый каталог, который будет назван в честь его предков в дереве модулей, в данном случае src/front_of_house.

Чтобы начать перемещение hosting, изменим src/front_of_house.rs так, чтобы он содержал только объявление модуля hosting:

pub mod hosting;

Затем мы создаём каталог src/front_of_house и файл hosting.rs для содержания определений, сделанных в модуле hosting:

pub fn add_to_waitlist() {}

Если бы мы вместо этого поместили hosting.rs в каталог src, компилятор ожидал бы, что код hosting.rs находится в модуле hosting, объявленном в корне крейта, а не объявленном как дочерний модуль front_of_house. Правила компилятора о том, в каких файлах искать код для каких модулей, означают, что каталоги и файлы более точно соответствуют дереву модулей.

Мы переместили код каждого модуля в отдельный файл, и дерево модулей остаётся прежним. Вызовы функций в eat_at_restaurant будут работать без каких-либо изменений, даже если определения находятся в разных файлах. Эта техника позволяет перемещать модули в новые файлы по мере их роста.

Обратите внимание, что оператор pub use crate::front_of_house::hosting в src/lib.rs также не изменился, и use не влияет на то, какие файлы компилируются как часть крейта. Ключевое слово mod объявляет модули, и Rust ищет в файле с тем же именем, что и модуль, код, который попадает в этот модуль.

Краткий итог

Rust позволяет разделить пакет на несколько крейтов, а крейт — на модули, чтобы вы могли ссылаться на элементы, определённые в одном модуле, из другого модуля. Вы можете сделать это, указав абсолютные или относительные пути. Эти пути могут быть приведены в область видимости с помощью оператора use, чтобы вы могли использовать более короткий путь для многократного использования элемента в этой области видимости. Код модуля по умолчанию является приватным, но вы можете сделать определения публичными, добавив ключевое слово pub.

В следующей главе мы рассмотрим некоторые структуры данных коллекций в стандартной библиотеке, которые вы можете использовать в своём аккуратно организованном коде.

Распространённые коллекции

Стандартная библиотека Rust включает множество полезных структур данных, называемых коллекциями. Большинство других типов данных представляют одно конкретное значение, но коллекции могут содержать несколько значений. В отличие от встроенных типов массивов и кортежей, данные, на которые указывают эти коллекции, хранятся в куче. Это означает, что объём данных не обязательно должен быть известен на этапе компиляции и может увеличиваться или уменьшаться во время выполнения программы. Каждый вид коллекции обладает разными возможностями и характеристиками, а выбор подходящей коллекции для текущей задачи — это навык, который вы будете развивать со временем. В этой главе мы обсудим три коллекции, которые часто используются в программах на Rust:

• Вектор позволяет хранить переменное количество значений, расположенных последовательно.
• Строка — это коллекция символов. Мы уже упоминали тип String ранее, но в этой главе поговорим о нём подробно.
• Хэш-таблица позволяет связать значение с конкретным ключом. Это частная реализация более общей структуры данных, называемой отображением.

Чтобы узнать о других видах коллекций, предоставляемых стандартной библиотекой, см. документацию.

Мы обсудим, как создавать и изменять векторы, строки и хэш-таблицы, а также что делает каждую из них особенной.

Хранение списков значений с помощью векторов

Первый тип коллекции, который мы рассмотрим, — Vec<T>, также известный как вектор. Векторы позволяют хранить более одного значения в одной структуре данных, которая размещает все значения рядом в памяти. Векторы могут хранить только значения одного типа. Они полезны, когда у вас есть список элементов, например, строки текста в файле или цены товаров в корзине покупок.

Создание нового вектора

Чтобы создать новый пустой вектор, мы вызываем функцию Vec::new, как показано в Листинге 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Обратите внимание, что мы добавили здесь аннотацию типа. Поскольку мы не вставляем никакие значения в этот вектор, Rust не знает, какой тип элементов мы намереваемся хранить. Это важный момент. Векторы реализованы с использованием обобщений; мы рассмотрим, как использовать обобщения с вашими собственными типами, в Главе 10. Пока знайте, что тип Vec<T>, предоставляемый стандартной библиотекой, может хранить любой тип. Когда мы создаём вектор для хранения конкретного типа, мы можем указать тип в угловых скобках. В Листинге 8-1 мы сообщили Rust, что Vec<T> в v будет хранить элементы типа i32.

Чаще вы будете создавать Vec<T> с начальными значениями, и Rust выведет тип значения, которое вы хотите хранить, поэтому вам редко нужно делать такую аннотацию типа. Rust удобно предоставляет макрос vec!, который создаст новый вектор, содержащий переданные ему значения. Листинг 8-2 создаёт новый Vec<i32>, содержащий значения 1, 2 и 3. Тип целого числа — i32, потому что это тип целого числа по умолчанию, как мы обсуждали в разделе “Типы данных” Главы 3.

fn main() {
    let v = vec![1, 2, 3];
}

Поскольку мы предоставили начальные значения i32, Rust может вывести, что тип v — Vec<i32>, и аннотация типа не требуется. Далее мы посмотрим, как изменять вектор.

Изменение вектора

Чтобы создать вектор, а затем добавить в него элементы, мы можем использовать метод push, как показано в Листинге 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Как и с любой переменной, если мы хотим иметь возможность изменять её значение, нам нужно сделать её изменяемой с помощью ключевого слова mut, как обсуждалось в Главе 3. Числа, которые мы помещаем внутрь, все имеют тип i32, и Rust выводит это из данных, поэтому нам не нужна аннотация Vec<i32>.

Чтение элементов векторов

Есть два способа получить ссылку на значение, хранящееся в векторе: по индексу или с помощью метода get. В следующих примерах мы аннотировали типы значений, возвращаемых этими функциями, для большей ясности.

Листинг 8-4 показывает оба способа доступа к значению в векторе: с помощью синтаксиса индексации и метода get.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

Обратите внимание на несколько деталей здесь. Мы используем индекс 2, чтобы получить третий элемент, потому что векторы индексируются числами, начиная с нуля. Использование & и [] даёт нам ссылку на элемент по значению индекса. Когда мы используем метод get с индексом, переданным в качестве аргумента, мы получаем Option<&T>, который можно использовать с match.

Rust предоставляет эти два способа ссылаться на элемент, чтобы вы могли выбрать, как программа должна вести себя при попытке использовать индекс за пределами существующих элементов. Например, давайте посмотрим, что происходит, когда у нас есть вектор из пяти элементов, а затем мы пытаемся получить доступ к элементу с индексом 100 каждым способом, как показано в Листинге 8-5.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

При запуске этого кода первый метод [] приведёт к панике программы, потому что он ссылается на несуществующий элемент. Этот метод лучше всего использовать, когда вы хотите, чтобы программа завершилась с ошибкой при попытке доступа к элементу за концом вектора.

Когда методу get передаётся индекс вне вектора, он возвращает None без паники. Вы бы использовали этот метод, если доступ к элементу за пределами вектора может иногда происходить при нормальных обстоятельствах. Затем ваш код будет содержать логику для обработки либо Some(&element), либо None, как обсуждалось в Главе 6. Например, индекс может поступать от человека, вводящего число. Если он случайно вводит слишком большое число и программа получает значение None, вы можете сообщить пользователю, сколько элементов в текущем векторе, и дать ему ещё один шанс ввести допустимое значение. Это будет более дружелюбно к пользователю, чем падение программы из-за опечатки!

Когда программа имеет действительную ссылку, проверка заимствований обеспечивает соблюдение правил владения и заимствования (рассмотренных в Главе 4), чтобы гарантировать, что эта ссылка и любые другие ссылки на содержимое вектора остаются действительными. Вспомните правило, которое гласит, что вы не можете иметь изменяемые и неизменяемые ссылки в одной области видимости. Это правило применяется в Листинге 8-6, где мы держим неизменяемую ссылку на первый элемент вектора и пытаемся добавить элемент в конец. Эта программа не будет работать, если мы также попытаемся обратиться к этому элементу позже в функции.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

Компиляция этого кода приведёт к следующей ошибке:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                     ------- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` (bin "collections") due to 1 previous error

Код в Листинге 8-6 может выглядеть так, как будто он должен работать: почему ссылка на первый элемент должна беспокоиться об изменениях в конце вектора? Эта ошибка связана с тем, как работают векторы: поскольку векторы размещают значения рядом в памяти, добавление нового элемента в конец вектора может потребовать выделения новой памяти и копирования старых элементов в новое пространство, если недостаточно места, чтобы разместить все элементы рядом там, где вектор хранится в данный момент. В этом случае ссылка на первый элемент будет указывать на освобождённую память. Правила заимствования предотвращают попадание программ в такую ситуацию.

Примечание: Для получения дополнительной информации о деталях реализации типа Vec<T> см. “The Rustonomicon”.

Итерация по значениям в векторе

Чтобы последовательно получить доступ к каждому элементу вектора, мы будем проходить через все элементы, а не использовать индексы для доступа к ним по одному. Листинг 8-7 показывает, как использовать цикл for для получения неизменяемых ссылок на каждый элемент вектора значений i32 и их печати.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Чтобы прочитать число, на которое указывает n_ref, мы должны использовать оператор разыменования *, чтобы получить значение в n_ref, прежде чем мы сможем прибавить 1 к нему, как рассматривалось в “Разыменование указателя даёт доступ к его данным”.

Мы также можем итерировать по изменяемым ссылкам на каждый элемент в изменяемом векторе, чтобы изменить все элементы. Цикл for в Листинге 8-8 прибавит 50 к каждому элементу.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Чтобы изменить значение, на которое указывает изменяемая ссылка, мы снова используем оператор разыменования *, чтобы получить значение в n_ref, прежде чем сможем использовать оператор +=.

Безопасное использование итераторов

Мы обсудим подробнее, как работают итераторы, в Главе 13.2 “Обработка серии элементов с помощью итераторов”. Пока что одна важная деталь: итераторы содержат указатель на данные внутри вектора. Мы можем увидеть, как работают итераторы, раскрыв цикл for в соответствующие вызовы методов Vec::iter и Iterator::next:

Заметьте, что итератор iter — это указатель, который перемещается через каждый элемент вектора. Метод next продвигает итератор и возвращает необязательную ссылку на предыдущий элемент, либо Some (которую мы раскрываем), либо None в конце вектора.

Эта деталь важна для безопасного использования векторов. Например, предположим, мы хотим продублировать вектор на месте, так что [1, 2] станет [1, 2, 1, 2]. Наивная реализация может выглядеть так, с аннотациями разрешений, выведенных компилятором:

Заметьте, что v.iter() удаляет разрешение W из *v. Поэтому операция v.push(..) не имеет ожидаемого разрешения W. Компилятор Rust отклонит эту программу с соответствующим сообщением об ошибке:

error[E0502]: cannot borrow `*v` as mutable because it is also borrowed as immutable
 --> test.rs:3:9
  |
2 |     for n_ref in v.iter() {
  |                  --------
  |                  |
  |                  immutable borrow occurs here
  |                  immutable borrow later used here
3 |         v.push(*n_ref);
  |         ^^^^^^^^^^^^^^ mutable borrow occurs here

Как мы обсуждали в Главе 4, проблема безопасности, лежащая в основе этой ошибки, — это чтение освобождённой памяти. Как только происходит v.push(1), вектор перераспределит своё содержимое и сделает указатель итератора недействительным. Поэтому для безопасного использования итераторов Rust не позволяет добавлять или удалять элементы из вектора во время итерации.

Один способ итерировать по вектору без использования указателя — использовать диапазон, как мы использовали для срезов строк в Главе 4.4. Например, диапазон 0 .. v.len() — это итератор по всем индексам вектора v, как видно здесь:

Использование перечисления для хранения нескольких типов

Векторы могут хранить только значения одного типа. Это может быть неудобно; безусловно, есть случаи использования, когда нужно хранить список элементов разных типов. К счастью, варианты перечисления определены под одним типом перечисления, поэтому, когда нам нужен один тип для представления элементов разных типов, мы можем определить и использовать перечисление!

Например, предположим, мы хотим получить значения из строки в электронной таблице, в которой некоторые столбцы в строке содержат целые числа, некоторые числа с плавающей точкой, а некоторые строки. Мы можем определить перечисление, варианты которого будут хранить разные типы значений, и все варианты перечисления будут считаться одним типом: типом перечисления. Затем мы можем создать вектор, который будет хранить это перечисление, а значит, в конечном итоге, хранить разные типы. Мы продемонстрировали это в Листинге 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust должен знать, какие типы будут в векторе во время компиляции, чтобы он знал точно, сколько памяти в куче потребуется для хранения каждого элемента. Мы также должны явно указать, какие типы разрешены в этом векторе. Если бы Rust позволял вектору хранить любой тип, существовала бы вероятность, что один или несколько типов вызовут ошибки с операциями, выполняемыми над элементами вектора. Использование перечисления плюс выражение match означает, что Rust гарантирует на этапе компиляции, что каждый возможный случай будет обработан, как обсуждалось в Главе 6.

Если вы не знаете исчерпывающий набор типов, которые программа получит во время выполнения для хранения в векторе, техника с перечислением не сработает. Вместо этого вы можете использовать объект типажа, который мы рассмотрим в Главе 18.

Теперь, когда мы обсудили некоторые из наиболее распространённых способов использования векторов, обязательно ознакомьтесь с документацией API для всех многочисленных полезных методов, определённых в Vec<T> стандартной библиотекой. Например, в дополнение к push, метод pop удаляет и возвращает последний элемент.

Удаление вектора удаляет его элементы

Как и любой другой struct, вектор освобождается, когда он выходит из области видимости, как аннотировано в Листинге 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

Когда вектор удаляется, всё его содержимое также удаляется, то есть целые числа, которые он хранит, будут очищены. Проверка заимствований гарантирует, что любые ссылки на содержимое вектора используются только пока сам вектор действителен.

Перейдём к следующему типу коллекции: String!

Хранение текста в кодировке UTF-8 с помощью строк

Мы уже говорили о строках в главе 4, но теперь рассмотрим их подробнее. Новички в Rust часто застревают на строках по трём причинам одновременно: склонность Rust к выявлению возможных ошибок, более сложная структура данных строк, чем многие программисты думают, и UTF-8. Эти факторы в сочетании могут казаться трудными, если вы пришли из других языков программирования.

Мы обсуждаем строки в контексте коллекций, потому что строки реализованы как коллекция байтов с дополнительными методами для удобной работы, когда эти байты интерпретируются как текст. В этом разделе мы поговорим об операциях с String, которые есть у любого типа коллекции: создание, обновление и чтение. Мы также обсудим, чем String отличается от других коллекций, а именно как индексация в String усложняется из-за различий в том, как люди и компьютеры интерпретируют данные String.

Что такое строка?

Сначала определим, что мы подразумеваем под термином строка. В ядре языка Rust есть только один тип строки — строковый срез str, который обычно встречается в заимствованной форме &str. В главе 4 мы говорили о строковых срезах, которые являются ссылками на некоторые данные UTF-8 строки, хранящиеся в другом месте. Например, строковые литералы хранятся в бинарном файле программы и поэтому являются строковыми срезами.

Тип String, который предоставляется стандартной библиотекой Rust, а не встроен в ядро языка, — это изменяемая, владеющая строка с кодировкой UTF-8. Когда разработчики на Rust говорят о «строках», они могут иметь в виду как String, так и строковый срез &str, а не только один из этих типов. Хотя этот раздел в основном о String, оба типа активно используются в стандартной библиотеке Rust, и String, и строковые срезы кодируются в UTF-8.

Создание новой строки

С String доступны многие из тех же операций, что и с Vec<T>, потому что String фактически реализован как обёртка вокруг вектора байтов с некоторыми дополнительными гарантиями, ограничениями и возможностями. Пример функции, которая работает одинаково с Vec<T> и String, — это функция new для создания экземпляра, показанная в листинге 8-11.

fn main() {
    let mut s = String::new();
}

Эта строка создаёт новую пустую строку с именем s, в которую затем можно загрузить данные. Часто у нас есть начальные данные, с которых мы хотим начать строку. Для этого используем метод to_string, который доступен для любого типа, реализующего типаж Display, как и строковые литералы. Листинг 8-12 показывает два примера.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // The method also works on a literal directly:
    let s = "initial contents".to_string();
}

Этот код создаёт строку, содержащую initial contents.

Мы также можем использовать функцию String::from для создания String из строкового литерала. Код в листинге 8-13 эквивалентен коду в листинге 8-12, использующему to_string.

fn main() {
    let s = String::from("initial contents");
}

Поскольку строки используются для многих целей, мы можем использовать множество различных общих API для строк, что даёт нам много вариантов. Некоторые из них могут показаться избыточными, но у каждого есть своё место! В данном случае String::from и to_string делают одно и то же, поэтому выбор зависит от стиля и читаемости.

Помните, что строки кодируются в UTF-8, поэтому мы можем включать в них любые правильно закодированные данные, как показано в листинге 8-14.

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Все они являются допустимыми значениями String.

Обновление строки

String может увеличиваться в размере, и её содержимое может меняться, как и содержимое Vec<T>, если добавлять в неё больше данных. Кроме того, для конкатенации значений String удобно использовать оператор + или макрос format!.

Добавление к строке с помощью push_str и push

Мы можем увеличить String, используя метод push_str для добавления строкового среза, как показано в листинге 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

После этих двух строк s будет содержать foobar. Метод push_str принимает строковый срез, потому что мы не обязательно хотим принимать владение параметром. Например, в коде из листинга 8-16 мы хотим иметь возможность использовать s2 после добавления её содержимого к s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Если бы метод push_str принимал владение s2, мы не смогли бы вывести его значение в последней строке. Однако этот код работает так, как ожидается!

Метод push принимает один символ в качестве параметра и добавляет его к String. Листинг 8-17 добавляет букву l к String с помощью метода push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

В результате s будет содержать lol.

Конкатенация с помощью оператора + или макроса format!

Часто нужно объединить две существующие строки. Один из способов сделать это — использовать оператор +, как показано в листинге 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

Строка 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; выглядит так, как будто оно скопирует обе строки и создаст новую, это утверждение вместо этого делает следующее:

1. add принимает владение s1,
2. добавляет копию содержимого s2 к s1,
3. а затем возвращает обратно владение s1.

Если у s1 достаточно ёмкости для s2, то выделения памяти не происходит. Однако, если у s1 недостаточно ёмкости для s2, то s1 внутренне сделает большее выделение памяти, чтобы вместить обе строки.

Если нам нужно объединить несколько строк, поведение оператора + становится неудобным:

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 с помощью синтаксиса индексации в Rust, вы получите ошибку. Рассмотрим недопустимый код в листинге 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

Этот код приведёт к следующей ошибке:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = 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<str>` is not implemented for `{integer}`
          but 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. Однако следующая строка может вас удивить (обратите внимание, что эта строка начинается с заглавной кириллической буквы Ze, а не с цифры 3):

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Если бы вас спросили, какой длины эта строка, вы могли бы сказать 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 не компилирует этот код вообще и предотвращает недопонимание на ранних этапах разработки.

Байты, скалярные значения и графемные кластеры! Ого!

Ещё один момент о UTF-8 заключается в том, что на самом деле есть три релевантных способа рассматривать строки с точки зрения Rust: как байты, скалярные значения и графемные кластеры (самое близкое к тому, что мы называем буквами).

Если мы посмотрим на хинди слово «नमस्ते», написанное деванагари, оно хранится как вектор значений u8, который выглядит так:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Это 18 байтов, и именно так компьютеры в конечном итоге хранят эти данные. Если мы посмотрим на них как на значения Unicode-скаляра, которыми является тип char в Rust, эти байты будут выглядеть так:

['न', 'म', 'स', '्', 'त', 'े']

Здесь шесть значений 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, hash table, dictionary или associative array.

Хэш-мапы полезны, когда вы хотите искать данные не по индексу, как в векторах, а по ключу, который может быть любого типа. Например, в игре вы можете отслеживать очки каждой команды в хэш-мапе, где каждый ключ — это название команды, а значения — её очки. Зная название команды, вы можете получить её счёт.

В этом разделе мы рассмотрим базовый API хэш-мап, но в стандартной библиотеке, в функциях, определённых для HashMap<K, V>, скрыто много дополнительных возможностей. Как всегда, для более подробной информации проверьте документацию стандартной библиотеки.

Создание новой хэш-мапы

Один из способов создать пустую хэш-мапу — использовать new и добавлять элементы с помощью insert. В Листинге 8-20 мы отслеживаем очки двух команд с названиями Blue (Синие) и Yellow (Жёлтые). Команда Синие начинает с 10 очков, а Жёлтые — с 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Обратите внимание, что нам нужно сначала use импортировать HashMap из раздела коллекций стандартной библиотеки. Из наших трёх распространённых коллекций эта используется реже всего, поэтому она не включена в возможности, автоматически импортируемые в прелюд. У хэш-мап также меньше поддержки со стороны стандартной библиотеки; например, для их создания нет встроенного макроса.

Как и вектора, хэш-мапы хранят свои данные в куче. Эта HashMap имеет ключи типа String и значения типа i32. Как и вектора, хэш-мапы однородны: все ключи должны иметь одинаковый тип, и все значения должны иметь одинаковый тип.

Доступ к значениям в хэш-мапе

Мы можем получить значение из хэш-мапы, передав её ключ методу get, как показано в Листинге 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Здесь score будет иметь значение, связанное с командой Синие, и результат будет 10. Метод get возвращает Option<&V>; если в хэш-мапе нет значения для этого ключа, get вернёт None. Эта программа обрабатывает Option, вызывая copied, чтобы получить Option<i32> вместо Option<&i32>, а затем unwrap_or, чтобы установить score в ноль, если в scores нет записи для ключа.

Мы можем перебирать каждую пару ключ-значение в хэш-мапе аналогично тому, как мы это делаем с векторами, используя цикл for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Этот код выведет каждую пару в произвольном порядке:

Yellow: 50
Blue: 10

Хэш-мапы и владение

Для типов, реализующих типаж Copy, таких как i32, значения копируются в хэш-мапу. Для владеющих значений, таких как String, значения будут перемещены, и хэш-мапа станет владельцем этих значений, как показано в Листинге 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

Мы не можем использовать переменные field_name и field_value после того, как они были перемещены в хэш-мапу с помощью вызова insert.

Если мы вставляем в хэш-мапу ссылки на значения, значения не будут перемещены в хэш-мапу. Значения, на которые указывают ссылки, должны быть действительными как минимум столько же, сколько и хэш-мапа. Мы подробнее обсудим эти вопросы в разделе «Проверка ссылок с помощью времени жизни» в Главе 10.

Обновление хэш-мапы

Хотя количество пар ключ-значение может увеличиваться, каждый уникальный ключ может иметь только одно значение одновременно (но не наоборот: например, и команда Синие, и команда Жёлтые могут иметь значение 10 в хэш-мапе scores).

Когда вы хотите изменить данные в хэш-мапе, вы должны решить, как поступать в случае, если ключу уже присвоено значение. Вы можете заменить старое значение новым, полностью игнорируя старое. Вы можете сохранить старое значение и проигнорировать новое, добавляя новое значение только если ключ ещё не имеет значения. Или вы можете объединить старое и новое значения. Давайте посмотрим, как сделать каждое из этих действий!

Перезапись значения

Если мы вставляем ключ и значение в хэш-мапу, а затем вставляем тот же ключ с другим значением, значение, связанное с этим ключом, будет заменено. Хотя код в Листинге 8-23 дважды вызывает insert, хэш-мапа будет содержать только одну пару ключ-значение, потому что мы оба раза вставляем значение для ключа команды Синие.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

    println!("{scores:?}");
}

Этот код выведет {"Blue": 25}. Исходное значение 10 было перезаписано.

Добавление ключа и значения только если ключ отсутствует

Обычно проверяют, существует ли определённый ключ в хэш-мапе со значением, и затем предпринимают следующие действия: если ключ существует в хэш-мапе, существующее значение должно оставаться как есть; если ключ не существует, вставляют его и значение для него.

У хэш-мап есть специальный API для этого под названием entry, который принимает ключ, который вы хотите проверить, в качестве параметра. Возвращаемое значение метода entry — это перечисление Entry, представляющее значение, которое может или не существовать. Допустим, мы хотим проверить, имеет ли ключ для команды Жёлтые связанное значение. Если нет, мы хотим вставить значение 50, и то же самое для команды Синие. Используя API entry, код выглядит как в Листинге 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

    println!("{scores:?}");
}

Метод or_insert на Entry определён так, чтобы возвращать изменяемую ссылку на значение для соответствующего ключа Entry, если этот ключ существует, а если нет — вставляет параметр как новое значение для этого ключа и возвращает изменяемую ссылку на новое значение. Этот подход гораздо чище, чем писать логику самостоятельно, и, кроме того, лучше согласуется с проверкой заимствований.

Запуск кода из Листинга 8-24 выведет {"Yellow": 50, "Blue": 10}. Первый вызов entry вставит ключ для команды Жёлтые со значением 50, потому что у команды Жёлтые ещё нет значения. Второй вызов entry не изменит хэш-мапу, потому что у команды Синие уже есть значение 10.

Обновление значения на основе старого значения

Ещё один распространённый вариант использования хэш-мап — найти значение ключа, а затем обновить его на основе старого значения. Например, Листинг 8-25 показывает код, который подсчитывает, сколько раз каждое слово встречается в некотором тексте. Мы используем хэш-мапу, где слова являются ключами, и увеличиваем значение, чтобы отслеживать, сколько раз мы видели это слово. Если мы видим слово впервые, мы сначала вставим значение 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{map:?}");
}

Этот код выведет {"world": 2, "hello": 1, "wonderful": 1}. Вы можете увидеть те же пары ключ-значение, выведенные в другом порядке: вспомните из раздела «Доступ к значениям в хэш-мапе», что перебор хэш-мапы происходит в произвольном порядке.

Метод split_whitespace возвращает итератор по подсрезам, разделённым пробельными символами, значения в text. Метод or_insert возвращает изменяемую ссылку (&mut V) на значение для указанного ключа. Здесь мы сохраняем эту изменяемую ссылку в переменной count, поэтому чтобы присвоить этому значению, мы сначала должны разыменовать count с помощью звёздочки (*). Изменяемая ссылка выходит из области видимости в конце цикла for, поэтому все эти изменения безопасны и разрешены правилами заимствования.

Хэш-функции

По умолчанию HashMap использует хэш-функцию под названием SipHash, которая может обеспечить устойчивость к атакам типа «отказ в обслуживании» (DoS), связанным с хэш-таблицами¹. Это не самая быстрая хэш-функция, но компромисс в виде лучшей безопасности из-за падения производительности того стоит. Если вы профилируете свой код и обнаруживаете, что хэш-функция по умолчанию слишком медленна для ваших целей, вы можете переключиться на другую, указав другого хэшера. Хэшер — это тип, который реализует типаж BuildHasher. Мы поговорим о типажах и их реализации в Главе 10. Вам не обязательно реализовывать свой хэшер с нуля; на crates.io есть библиотеки, которыми делятся другие пользователи Rust, предоставляющие хэшеры, реализующие многие распространённые алгоритмы хэширования.

Краткий итог

Векторы, строки и хэш-мапы предоставят большой объём функциональности, необходимой в программах, когда вам нужно хранить, получать доступ и изменять данные. Вот несколько упражнений, которые вы теперь готовы решить:

1. Имея список целых чисел, используйте вектор и верните медиану (при сортировке — значение в средней позиции) и моду (значение, которое встречается чаще всего; здесь поможет хэш-мапа) списка.
2. Преобразуйте строки в «свинскую латынь». Первая согласная каждого слова перемещается в конец слова, и добавляется ay, так что first становится irst-fay. Слова, начинающиеся с гласной, получают в конце hay вместо этого (apple становится apple-hay). Учитывайте детали кодировки UTF-8!
3. Используя хэш-мапу и векторы, создайте текстовый интерфейс, позволяющий пользователю добавлять имена сотрудников в отдел компании; например, «Add Sally to Engineering» или «Add Amir to Sales». Затем позвольте пользователю получать список всех людей в отделе или всех людей в компании по отделам, отсортированных по алфавиту.

Документация API стандартной библиотеки описывает методы, которые есть у векторов, строк и хэш-мап и которые помогут в этих упражнениях!

Мы переходим к более сложным программам, в которых операции могут завершаться неудачей, поэтому это идеальное время обсудить обработку ошибок. Мы сделаем это следующим шагом!

1. https://en.wikipedia.org/wiki/SipHash ↩

Инвентаризация владения #2

«Инвентаризация владения» — это серия викторин, проверяющих понимание владения в реальных примерах. Эти примеры вдохновлены распространёнными вопросами о Rust на StackOverflow.

Обработка ошибок

Ошибки — неотъемлемая часть разработки программного обеспечения, поэтому в Rust существует ряд возможностей для обработки ситуаций, когда что-то идёт не так. Во многих случаях Rust требует, чтобы вы признали возможность ошибки и предприняли некоторые действия, прежде чем ваш код скомпилируется. Это требование делает вашу программу более надёжной, обеспечивая обнаружение ошибок и их правильную обработку до развёртывания кода в производственной среде!

Rust группирует ошибки на две основные категории: восстанавливаемые и невосстанавливаемые ошибки. Для восстанавливаемой ошибки, такой как ошибка «файл не найден», мы, скорее всего, просто хотим сообщить о проблеме пользователю и повторить операцию. Невосстанавливаемые ошибки всегда являются симптомами багов, таких как попытка доступа к элементу за пределами массива, и поэтому мы хотим немедленно остановить программу.

Большинство языков не различают эти два вида ошибок и обрабатывают их одинаково, используя такие механизмы, как исключения. В Rust нет исключений. Вместо этого существует тип Result<T, E> для восстанавливаемых ошибок и макрос panic!, который останавливает выполнение, когда программа сталкивается с невосстанавливаемой ошибкой. Эта глава сначала охватывает вызов panic!, а затем рассказывает о возврате значений Result<T, E>. Кроме того, мы рассмотрим соображения при принятии решения о попытке восстановления после ошибки или остановке выполнения.

Невосстанавливаемые ошибки с panic!

Иногда в вашем коде происходят плохие вещи, и вы ничего не можете с этим поделать. В таких случаях Rust предоставляет макрос panic!. На практике есть два способа вызвать панику: выполнить действие, которое приводит к панике (например, доступ к элементу массива за его пределами), или явно вызвать макрос panic!. В обоих случаях мы вызываем панику в нашей программе. По умолчанию такие паники выводят сообщение об ошибке, выполняют разворачивание стека (unwinding), очищают стек и завершают программу. С помощью переменной окружения вы также можете заставить Rust отображать трассировку стека при панике, чтобы упростить поиск источника проблемы.

[profile.release]
panic = 'abort'

Давайте попробуем вызвать panic! в простой программе:

fn main() {
    panic!("crash and burn");
}

При запуске программы вы увидите что-то вроде этого:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Вызов panic! вызывает сообщение об ошибке, содержащееся в последних двух строках. Первая строка показывает наше сообщение о панике и место в исходном коде, где произошла паника: src/main.rs:2:5 указывает, что это вторая строка, пятый символ нашего файла src/main.rs.

В этом случае указанная строка является частью нашего кода, и если мы перейдем к этой строке, мы увидим вызов макроса panic!. В других случаях вызов panic! может находиться в коде, который вызывает наш код, и имя файла и номер строки, указанные в сообщении об ошибке, будут относиться к чужому коду, где вызван макрос panic!, а не к строке нашего кода, которая в конечном итоге привела к этому вызову.

Мы можем использовать трассировку стека (backtrace) функций, из которых произошел вызов panic!, чтобы выяснить, какая часть нашего_code вызывает проблему. Чтобы понять, как использовать трассировку стека при panic!, давайте рассмотрим другой пример и посмотрим, как это выглядит, когда вызов panic! исходит из крейта из-за ошибки в нашем коде, а не из нашего прямого вызова макроса. В листинге 9-1 есть код, который пытается получить доступ к элементу вектора по индексу, выходящему за пределы допустимых индексов.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Здесь мы пытаемся получить доступ к 100-му элементу нашего вектора (который имеет индекс 99, так как индексация начинается с нуля), но вектор содержит только три элемента. В такой ситуации Rust вызовет панику. Использование [] предполагает возврат элемента, но если передать недопустимый индекс, не существует элемента, который Rust мог бы вернуть и который был бы корректным.

В C попытка чтения за пределами структуры данных приводит к неопределённому поведению (undefined behavior). Вы можете получить любые данные, находящиеся в памяти, которые соответствуют этому элементу в структуре, даже если память не принадлежит этой структуре. Это называется переполнением буфера при чтении (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/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:274:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/alloc/src/vec/mod.rs:3361:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Это очень много вывода! Точный вывод, который вы увидите, может отличаться в зависимости от вашей операционной системы и версии Rust. Чтобы получать трассировки стека с такой информацией, должны быть включены символы отладки (debug symbols). Символы отладки включены по умолчанию при использовании cargo build или cargo run без флага --release, как мы и сделали.

В выводе в листинге 9-2 строка 6 трассировки стека указывает на строку в нашем проекте, которая вызывает проблему: строку 4 файла src/main.rs. Если мы не хотим, чтобы наша программа паниковала, мы должны начать расследование в месте, на которое указывает первая строка, упоминающая файл, который мы написали. В листинге 9-1, где мы намеренно написали код, который вызовет панику, способ исправить панику — не запрашивать элемент за пределами диапазона индексов вектора. Когда ваш код паникует в будущем, вам нужно будет выяснить, какое действие выполняет код с какими значениями, что вызывает панику, и что код должен делать вместо этого.

Мы вернемся к panic! и к тому, когда мы должны и не должны использовать panic! для обработки условий ошибок, в разделе «panic! или не panic!» позже в этой главе. Далее мы посмотрим, как восстанавливаться после ошибки с помощью Result.

Восстанавливаемые ошибки с Result

Большинство ошибок не настолько серьёзны, чтобы требовать полной остановки программы. Иногда, когда функция завершается с ошибкой, причина легко интерпретируется и на неё можно отреагировать. Например, если вы пытаетесь открыть файл и эта операция завершается с ошибкой, потому что файл не существует, вы, возможно, захотите создать файл вместо завершения процесса.

Вспомните из главы 2 “Обработка потенциального сбоя с Result”, что перечисление Result определено с двумя вариантами, Ok и Err, следующим образом:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T и E — это параметры обобщённых типов: мы обсудим обобщения подробнее в главе 10. Сейчас вам нужно знать, что T представляет тип значения, которое будет возвращено в случае успеха внутри варианта Ok, а E представляет тип ошибки, который будет возвращён в случае сбоя внутри варианта Err. Поскольку Result имеет эти параметры обобщённых типов, мы можем использовать тип 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 должна иметь способ сообщить нам, succeeded ли она, и одновременно дать либо дескриптор файла, либо информацию об ошибке. Эта информация именно то, что передаёт перечисление 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!("Problem opening the file: {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:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Как обычно, этот вывод точно сообщает нам, что пошло не так.

Сопоставление с разными ошибками

Код в листинге 9-4 вызовет panic! независимо от причины сбоя File::open. Однако мы хотим предпринимать разные действия для разных причин сбоя. Если File::open завершился с ошибкой потому, что файл не существует, мы хотим создать файл и вернуть дескриптор нового файла. Если File::open завершился с ошибкой по любой другой причине — например, потому что у нас нет прав на открытие файла — мы всё ещё хотим, чтобы код вызвал panic! так же, как это было в листинге 9-4. Для этого мы добавляем вложенное выражение match, показанное в листинге 9-5.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            _ => {
                panic!("Problem opening the file: {error:?}");
            }
        },
    };
}

Тип значения, которое File::open возвращает внутри варианта Err, — это io::Error, который является структурой, предоставляемой стандартной библиотекой. У этой структуры есть метод kind, который мы можем вызвать, чтобы получить значение io::ErrorKind. Перечисление io::ErrorKind предоставляется стандартной библиотекой и имеет варианты, представляющие различные виды ошибок, которые могут возникнуть в результате операции io. Вариант, который мы хотим использовать, — это ErrorKind::NotFound, который указывает, что файл, который мы пытаемся открыть, ещё не существует. Поэтому мы сопоставляем greeting_file_result, но также имеем вложенное сопоставление по error.kind().

Условие, которое мы хотим проверить во вложенном match, — это является ли значение, возвращаемое error.kind(), вариантом NotFound перечисления ErrorKind. Если это так, мы пытаемся создать файл с помощью File::create. Однако, поскольку File::create тоже может завершиться с ошибкой, нам нужна вторая ветвь во вложенном выражении match. Когда файл не может быть создан, выводится другое сообщение об ошибке. Вторая ветвь внешнего match остаётся той же, поэтому программа аварийно завершается при любой ошибке, кроме ошибки отсутствующего файла.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

Ярлыки для паники при ошибке: 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" }

Аналогично, метод expect позволяет нам также выбрать сообщение об ошибке panic!. Использование expect вместо unwrap и предоставление хороших сообщений об ошибках может передать ваше намерение и облегчить отслеживание источника паники. Синтаксис expect выглядит так:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

Мы используем expect так же, как unwrap: чтобы вернуть дескриптор файла или вызвать макрос panic!. Сообщение об ошибке, которое использует expect в своём вызове panic!, будет параметром, который мы передаём в expect, а не стандартным сообщением panic!, которое использует unwrap. Вот как это выглядит:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

В коде production-quality большинство Rustaceans выбирают 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 — username, который эта функция прочитала из файла. Если эта функция столкнётся с какими-либо проблемами, вызывающий код получит значение Err, содержащее экземпляр io::Error, который содержит дополнительную информацию о том, какими были проблемы. Мы выбрали io::Error в качестве типа возврата этой функции, потому что это как раз тип значения ошибки, возвращаемого из обеих операций, которые мы вызываем в теле этой функции и которые могут завершиться с ошибкой: функции File::open и метода read_to_string.

Тело функции начинается с вызова функции File::open. Затем мы обрабатываем значение Result с помощью match, аналогично match в листинге 9-4. Если File::open завершается успешно, дескриптор файла в переменной шаблона file становится значением в изменяемой переменной username_file, и функция продолжает выполнение. В случае Err вместо вызова panic! мы используем ключевое слово return, чтобы досрочно выйти из функции полностью и передать значение ошибки из File::open, теперь в переменной шаблона e, обратно в вызывающий код как значение ошибки этой функции.

Итак, если у нас есть дескриптор файла в username_file, функция затем создаёт новую String в переменной username и вызывает метод 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, что 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.