Добро пожаловать в Comprehensive Rust 🦀

Это бесплатный курс по Rust, разработанный командой Android в Google. Курс охватывает весь спектр Rust: от базового синтаксиса до сложных тем, таких как обобщённые типы (generics) и обработка ошибок.

Актуальная версия курса доступна по адресу https://r007.github.io/EmbeddedRust-Rus/comprehensive-rust/. Если вы читаете курс в другом месте, пожалуйста, проверьте обновления там.

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

Курс также доступен в формате EPUB.

Цель курса — научить вас языку Rust. Мы предполагаем, что вы ничего не знаете о Rust, и надеемся:

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

Первые четыре дня курса мы называем «Основы Rust» (Rust Fundamentals).

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

• Android: рассчитанный на полдня курс по использованию Rust для разработки на платформе Android (AOSP). Сюда входит взаимодействие с C, C++ и Java.
• Chromium: рассчитанный на полдня курс по использованию Rust в браузерах на базе Chromium. Включает взаимодействие с C++ и подключение сторонних крейтов в Chromium.
• Bare-metal: занятие на целый день по использованию Rust для разработки bare-metal (встраиваемых систем). Рассматриваются как микроконтроллеры, так и прикладные процессоры.
• Конкурентность: занятие на целый день, посвящённое конкурентности в Rust. Мы рассмотрим как классическую конкурентность (вытесняющее планирование с помощью потоков и мьютексов), так и конкурентность на основе async/await (кооперативная многозадачность с помощью фьючерсов).

За рамками курса

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

• Чтобы научиться писать макросы, обратитесь к The Rust Book и Rust by Example.

Предположения

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

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

Проведение курса

Эта страница предназначена для преподавателя курса.

Вот краткая справочная информация о том, как мы проводили курс внутри компании Google.

Обычно занятия проходят с 9:00 до 16:00 с часовым перерывом на обед. Таким образом, на утреннее и на дневное занятие остается по 3 часа. В каждой части есть несколько перерывов и время, которое слушатели тратят на упражнения.

Перед проведением курса желательно:

1. Ознакомиться с материалами курса. Мы добавили заметки для преподавателя на некоторых страницах, чтобы выделить ключевые моменты (пожалуйста, помогайте нам, добавляя свои заметки для преподавателей!). Убедитесь в том, что открыли заметки для преподавателя во всплывающем окне (нажмите на ссылку с маленькой стрелкой рядом с «Заметки для преподавателя»). У вас откроется отдельное окно с заметками для преподавателя, в то время как основное окно вы можете демонстрировать классу.

2. Определите даты. Поскольку курс занимает четыре дня, мы рекомендуем распределить эти дни на две недели. Участники курса говорят, что им полезен перерыв посередине, так как он помогает переварить всю информацию, которую мы им даём.

3. Найдите помещение, достаточно просторное для очных участников. Мы рекомендуем группу из 15–25 человек. Это достаточно мало, чтобы людям было удобно задавать вопросы, и в то же время достаточно, чтобы один преподаватель успевал на них отвечать. Убедитесь, что в помещении есть столы для вас и для слушателей: всем нужно сидеть и работать с ноутбуками. Вам как преподавателю придется много писать код на занятии вживую, поэтому кафедра будет мало полезна.

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

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

На этом всё, удачи в прохождении курса! Мы надеемся, что вам будет так же весело, как и нам!

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

Структура курса

Эта страница предназначена для преподавателя курса.

Основы Rust

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

Расписание курса:

• День 1, утро (2 часа 10 минут, включая перерывы)

• День 1, после обеда (2 часа 45 минут, включая перерывы)

• День 2, утро (2 часа 50 минут, включая перерывы)

• День 2, после обеда (2 часа 50 минут, включая перерывы)

• День 3, утро (2 часа 20 минут, включая перерывы)

• День 3, после обеда (2 часа 30 минут, включая перерывы)

• День 4, утро (2 часа 50 минут, включая перерывы)

• День 4, после обеда (2 часа 20 минут, включая перерывы)

Глубокое погружение

В дополнение к четырёхдневному курсу по основам Rust мы рассмотрим ещё несколько специализированных тем:

Rust в Android

Углублённый курс Rust в Android занимает полдня и посвящён использованию Rust для разработки на платформе Android. Включает взаимодействие с C, C++ и Java.

Вам потребуется AOSP. Загрузите репозиторий курса на тот же компьютер, что и AOSP, и переместите каталог src/android/ в корневой каталог вашего AOSP. Это гарантирует, что система сборки Android увидит файлы Android.bp в src/android/.

Убедитесь, что adb sync работает с вашим эмулятором или реальным устройством, и предварительно соберите все примеры Android, используя src/android/build_all.sh. Прочтите скрипт, чтобы увидеть команды, которые он запускает, и убедитесь, что они работают, когда вы запускаете их вручную.

Rust в Chromium

Углублённый курс Rust в Chromium занимает полдня и посвящён использованию Rust как части браузера Chromium. Он включает использование Rust в системе сборки gn Chromium, подключение сторонних библиотек («крейтов») и взаимодействие с C++.

Нужно уметь собрать Chromium: для скорости рекомендуется отладочная сборка в компонентном режиме (component build), но подойдёт любая сборка. Убедитесь, что вы можете запустить собранный браузер Chromium.

Bare-Metal Rust

Углублённый курс Bare-Metal Rust занимает целый день и посвящён использованию Rust для разработки bare-metal (встраиваемых систем). Рассматриваются как микроконтроллеры, так и прикладные процессоры.

Что касается части микроконтроллеров, то вам нужно будет заранее приобрести плату разработки BBC micro:bit v2. Всем нужно будет установить несколько пакетов, как описано на странице приветствия.

Конкурентная многозадачность в Rust

Углублённый курс Конкурентность в Rust занимает целый день и охватывает как классическую конкурентность, так и async/await.

Вам понадобится настроенный новый крейт, а также загруженные зависимости, готовые к работе. Затем вы можете скопировать примеры в src/main.rs, чтобы поэкспериментировать с ними:

cargo init concurrency
cd concurrency
cargo add tokio --features full
cargo run

Расписание курса:

• Утро (3 часа 20 минут, включая перерывы)

• После обеда (3 часа 30 минут, включая перерывы)

Идиоматичный Rust

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

Перед началом этого курса вы должны освоить материал Основ Rust.

Расписание курса:

• Утро (14 часов 10 минут, включая перерывы)

Unsafe (в работе)

Углублённый курс Unsafe — двухдневное занятие о небезопасном языке Rust. Он охватывает основы гарантий безопасности Rust, мотивацию для unsafe, процесс ревью небезопасного кода, основы FFI и построение структур данных, которые анализатор заимствований обычно отклоняет.

not found - {{%course outline Unsafe}}

Формат

Курс задуман очень интерактивным, и мы рекомендуем позволять вопросам направлять изучение Rust!

Горячие клавиши

В mdBook есть несколько полезных сочетаний клавиш:

• Arrow-Left: переход на предыдущую страницу.
• Arrow-Right: переход на следующую страницу.
• Ctrl + Enter: выполнение примера кода, находящегося в фокусе.
• s: активация панели поиска.

Переводы

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

• Бразильский португальский от @rastringer, @hugojacob, @joaovicmendes и @henrif75.
• Китайский (упрощённый) от @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK и @nodmp.
• Китайский (традиционный) от @hueich, @victorhsieh, @mingyc, @kuanhungchen и @johnathan79717.
• Фарси от @DannyRavi, @javad-jafari, @Alix1383, @moaminsharifi , @hamidrezakp и @mehrad77.
• Японский от @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi и @kantasv.
• Корейский от @keispace, @jiyongp, @jooyunghan и @namhyung.
• Испанский от @deavid.
• Украинский от @git-user-cpp, @yaremam и @reta.

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

Незавершённые переводы

Существует большое количество переводов в работе. Ниже приведены ссылки на наиболее недавно обновлённые:

• Арабский от @younies
• Бенгальский от @raselmandol.
• Французский: @KookaS, @vcaen и @AdrienBaudemont.
• Немецкий от @Throvn и @ronaldfw.
• Итальянский от @henrythebuilder и @detro.

Полный список переводов с их текущим статусом доступен на момент последнего обновления или с синхронизацией с последней версией курса.

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

Использование Cargo

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

Установка

Пожалуйста, следуйте инструкциям на https://rustup.rs/.

Так вы получите систему сборки Cargo (cargo) и компилятор Rust (rustc). Также будет установлен rustup — утилита командной строки, с помощью которой можно устанавливать разные версии компилятора.

После установки Rust настройте редактор или IDE для работы с Rust. Большинство редакторов делают это через rust-analyzer, который обеспечивает автодополнение и переход к определению для VS Code, Emacs, Vim/Neovim и многих других. Существует также отдельная IDE — RustRover.

Экосистема Rust

Экосистема Rust состоит из ряда инструментов, основными из которых являются:

• rustc: компилятор Rust, который превращает файлы .rs в исполняемые файлы и другие промежуточные форматы.

• cargo: менеджер зависимостей и система сборки Rust. Cargo умеет загружать зависимости, обычно размещённые на https://crates.io, и передавать их rustc при сборке проекта. Cargo также включает встроенное средство запуска тестов, которое выполняет модульные тесты.

• rustup: установщик и средство обновления инструментария Rust. Этот инструмент используется для установки и обновления rustc и cargo при выходе новых версий Rust. Кроме того, rustup может загружать документацию стандартной библиотеки. Можно одновременно установить несколько версий Rust, и rustup позволит переключаться между ними по мере необходимости.

Примеры кода в этом курсе

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

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

Блоки кода в этом курсе полностью интерактивны:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    println!("Edit me!");
}

Можно использовать Ctrl + Enter, чтобы выполнить код, когда фокус находится в текстовом поле.

Запуск кода локально с помощью Cargo

Если вы хотите поэкспериментировать с кодом на своей системе, то вам нужно будет сначала установить Rust. Сделайте это, следуя инструкциям в The Rust Book. В вашей системе появятся инструменты rustc и cargo. На момент написания курса последний стабильный выпуск Rust имеет следующие версии:

% rustc --version
rustc 1.69.0 (84c898d65 2023-04-16)
% cargo --version
cargo 1.69.0 (6e9a83356 2023-04-12)

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

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

1. Нажмите кнопку «Copy to clipboard» на примере кода, который вы хотите скопировать.

2. Используйте cargo new exercise, чтобы создать новый каталог exercise/ для вашего кода:

   $ cargo new exercise
        Created binary (application) `exercise` package
   

3. Перейдите в каталог exercise/ и выполните cargo run для сборки и запуска исполняемого файла:

   $ cd exercise
   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.75s
        Running `target/debug/exercise`
   Hello, world!
   

4. Замените шаблонный код в src/main.rs своим. Например, используя пример с предыдущей страницы, сделайте src/main.rs похожим на

   // Copyright 2022 Google LLC
   // SPDX-License-Identifier: Apache-2.0
   
   fn main() {
       println!("Edit me!");
   }

5. Используйте cargo run для сборки и запуска обновленного исполняемого файла:

   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.24s
        Running `target/debug/exercise`
   Edit me!
   

6. Используйте cargo check для быстрой проверки проекта на наличие ошибок и cargo build для компиляции проекта без его запуска. Вы найдёте результат в каталоге target/debug/ для отладочной сборки. Используйте cargo build --release для создания оптимизированной финальной сборки в target/release/.

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

Добро пожаловать в День 1

Это первый день курса «Основы Rust». Сегодня мы рассмотрим широкий круг тем:

• Базовый синтаксис Rust: переменные, скалярные и составные типы, перечисления, структуры, ссылки, функции и методы.
• Типы и вывод типов.
• Управляющие конструкции: циклы, условные операторы и так далее.
• Пользовательские типы: структуры и перечисления.

Расписание

Вместе с 10-минутными перерывами занятие займёт около 2 часов 10 минут. Оно включает:

Привет, мир!

Этот сегмент займёт около 15 минут. Он включает:

Что такое Rust?

Rust — новый язык программирования, версия 1.0 которого вышла в 2015 году:

• Rust — это статически компилируемый язык, выступающий в той же роли, что и C++.
  • rustc использует LLVM в качестве бэкенда.
• Rust поддерживает множество платформ и архитектур:
  • x86, ARM, WebAssembly, …
  • Linux, Mac, Windows, …
• Rust используется для широкого спектра устройств:
  • прошивки и загрузчики,
  • смарт-экраны,
  • мобильные устройства,
  • настольные компьютеры,
  • серверы.

Сильные стороны

Некоторые уникальные преимущества Rust:

• Безопасность памяти на этапе компиляции — целые классы ошибок работы с памятью предотвращаются во время компиляции

  • Нет неинициализированных переменных.
  • Нет двойных освобождений.
  • Нет использования-после-освобождения (use-after-free).
  • Нет NULL указателей.
  • Нет забытых заблокированных мьютексов.
  • Нет гонок данных между потоками.
  • Нет инвалидации итераторов.

• Отсутствие неопределённого поведения во время выполнения — то, что делает каждая инструкция Rust, никогда не остаётся неопределённым

  • Проверка границ массива.
  • Переполнение целых чисел определено (паника или циклическое переполнение).

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

  • Перечисления и сопоставление с образцом.
  • Обобщения (generics).
  • Нет накладных расходов для FFI.
  • Абстракции с нулевой стоимостью (zero-cost abstractions).
  • Отличные ошибки компилятора.
  • Встроенный менеджер зависимостей.
  • Встроенная поддержка тестирования.
  • Великолепная поддержка протокола языкового сервера (LSP).

Песочница

Rust Playground — удобный способ запускать короткие программы на Rust; на нём основаны примеры и упражнения курса. Попробуйте запустить программу «hello-world», с которой он начинается. В нём есть несколько полезных функций:

• В меню «Tools» используйте опцию rustfmt, чтобы отформатировать код по «стандартным» правилам.

• В Rust есть два основных «профиля» сборки кода: Debug (дополнительные проверки во время выполнения, меньше оптимизаций) и Release (меньше проверок во время выполнения, много оптимизаций). Переключаться между ними можно через меню «Debug» вверху страницы.

• Если интересно, используйте «ASM» в меню «…», чтобы посмотреть сгенерированный ассемблерный код.

Типы и значения

Этот сегмент займёт около 40 минут. Он включает:

Привет, мир!

Давайте перейдём к самой простой из возможных программ на Rust, классической программе «Привет, мир!»

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    println!("Привет, 🌍!");
}

Что вы видите:

• Функции объявляются с помощью fn.
• Функция main является точкой входа в программу.
• Блоки разделяются фигурными скобками, как в C и C++.
• Инструкции завершаются ;.
• println — это макрос, на что указывает ! при вызове.
• Строки закодированы в UTF-8 и могут содержать любой символ Юникода.

Переменные

Rust обеспечивает типобезопасность за счёт статической типизации. Привязки переменных создаются с помощью let:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x: i32 = 10;
    println!("x: {x}");
    // x = 20;
    // println!("x: {x}");
}

Литералы

Вот несколько основных встроенных типов и синтаксис литералов для каждого из них.

Типы имеют следующие размеры:

• iN, uN и fN – N бит,
• isize и usize – размерность указателя,
• char – 32 бита,
• bool – 8 бит.

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn interproduct(a: i32, b: i32, c: i32) -> i32 {
    return a * b + b * c + c * a;
}

fn main() {
    println!("result: {}", interproduct(120, 100, 248));
}

Выведение типов

Rust анализует использование переменной для определения её типа:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn takes_u32(x: u32) {
    println!("u32: {x}");
}

fn takes_i8(y: i8) {
    println!("i8: {y}");
}

fn main() {
    let x = 10;
    let y = 20;

    takes_u32(x);
    takes_i8(y);
    // takes_u32(y);
}

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ОШИБКА: no implementation for `{float} == {integer}`
}

Упражнение: Числа Фибоначчи

Последовательность Фибоначчи начинается с [0, 1]. Для n > 1 следующее число равно сумме двух предыдущих.

Напишите функцию fib(n), которая вычисляет n-е число Фибоначчи. При каких условиях эта функция вызовет панику?

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn fib(n: u32) -> u32 {
    if n < 2 {
        // Базовый случай.
        return todo!("Реализуйте это");
    } else {
        // Рекурсивный случай.
        return todo!("Реализуйте это");
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn fib(n: u32) -> u32 {
    if n < 2 {
        return n;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

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

Условие if n < 2 не требует скобок, это стандартный стиль Rust.

Паника

В упражнении спрашивается, при каких условиях эта функция вызовет панику. Последовательность Фибоначчи растёт очень быстро. Для u32 вычисляемые значения превысят 32-битный предел (4 294 967 295), когда n достигнет 48.

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

Управляющие конструкции

Этот сегмент займёт около 45 минут. Он включает:

Блоки и области видимости

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let z = 13;
    let x = {
        let y = 10;
        dbg!(y);
        z - y
    };
    dbg!(x);
    // dbg!(y);
}

Если последнее выражение заканчивается ;, то результатом блока (и его типом) будет ().

Область видимости переменной ограничена объемлющим блоком.

Выражение if

Выражение if работает так же, как и оператор if в других языках:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x = 10;
    if x == 0 {
        println!("zero!");
    } else if x < 100 {
        println!("biggish");
    } else {
        println!("huge");
    }
}

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x = 10;
    let size = if x < 20 { "small" } else { "large" };
    println!("number size: {}", size);
}

Выражения match

match можно использовать, чтобы проверить значение на соответствие одному или нескольким вариантам:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let val = 1;
    match val {
        1 => println!("one"),
        10 => println!("ten"),
        100 => println!("one hundred"),
        _ => {
            println!("something else");
        }
    }
}

Как и выражения if, match тоже может возвращать значение;

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let flag = true;
    let val = match flag {
        true => 1,
        false => 0,
    };
    println!("The value of {flag} is {val}");
}

Циклы

В Rust есть три ключевых слова для циклов: while, loop и for:

Выражение while

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut x = 200;
    while x >= 10 {
        x = x / 2;
    }
    dbg!(x);
}

for

Цикл for перебирает диапазоны значений или элементы коллекции:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    for x in 1..5 {
        dbg!(x);
    }

    for elem in [2, 4, 8, 16, 32] {
        dbg!(elem);
    }
}

loop

Оператор loop повторяется бесконечно, пока не встретится break.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        dbg!(i);
        if i > 100 {
            break;
        }
    }
}

break и continue

Если нужно сразу перейти к следующей итерации, используйте continue.

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        if i > 5 {
            break;
        }
        if i % 2 == 0 {
            continue;
        }
        dbg!(i);
    }
}

Метки

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let s = [[5, 6, 7], [8, 9, 10], [21, 15, 32]];
    let mut elements_searched = 0;
    let target_value = 10;
    'outer: for i in 0..=2 {
        for j in 0..=2 {
            elements_searched += 1;
            if s[i][j] == target_value {
                break 'outer;
            }
        }
    }
    dbg!(elements_searched);
}

Функции

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn gcd(a: u32, b: u32) -> u32 {
    if b > 0 { gcd(b, a % b) } else { a }
}

fn main() {
    dbg!(gcd(143, 52));
}

Макросы

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

• println!(format, ..) выводит строку в стандартный вывод, применяя форматирование, описанное в std::fmt.
• format!(format, ..) работает так же, как println!, но возвращает результат в виде строки.
• dbg!(expression) выводит значение выражения в лог и возвращает его.
• todo!() отмечает фрагмент кода как ещё не реализованный. При выполнении он вызовет панику.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn factorial(n: u32) -> u32 {
    let mut product = 1;
    for i in 1..=n {
        product *= dbg!(i);
    }
    product
}

fn fizzbuzz(n: u32) -> u32 {
    todo!()
}

fn main() {
    let n = 4;
    println!("{n}! = {}", factorial(n));
}

Упражнение: Последовательность Коллатца

Последовательность Коллатца определяется следующим образом для произвольного n₁, большего нуля:

• Если n_i равно 1, то последовательность завершается на n_i.
• Если n_i чётное, то n_i+1 = n_i / 2.
• Если n_i нечётное, то n_i+1 = 3 * n_i + 1.

Например, начиная с n₁ = 3:

• 3 нечётное, поэтому n₂ = 3 * 3 + 1 = 10;
• 10 чётное, поэтому n₃ = 10 / 2 = 5;
• 5 нечётное, поэтому n₄ = 3 * 5 + 1 = 16;
• 16 чётное, поэтому n₅ = 16 / 2 = 8;
• 8 чётное, поэтому n₆ = 8 / 2 = 4;
• 4 чётное, поэтому n₇ = 4 / 2 = 2;
• 2 чётное, поэтому n₈ = 1; и
• последовательность завершается.

Напишите функцию, которая вычисляет длину последовательности Коллатца для заданного начального n.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Определяет длину последовательности Коллатца, начинающейся с `n`.
fn collatz_length(mut n: i32) -> u32 {
  todo!("Реализуйте это")
}

fn main() {
    println!("Length: {}", collatz_length(11)); // должно быть 15
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Определяет длину последовательности Коллатца, начинающейся с `n`.
fn collatz_length(mut n: i32) -> u32 {
    let mut len = 1;
    while n > 1 {
        n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 };
        len += 1;
    }
    len
}

fn main() {
    println!("Length: {}", collatz_length(11)); // должно быть 15
}

Это решение демонстрирует несколько ключевых возможностей Rust:

• Аргументы mut: аргумент n объявлен как mut n. Это делает локальную переменную n изменяемой в области видимости функции. Это не влияет на значение у вызывающего кода, так как целые — типы Copy, которые передаются по значению.
• Выражения if: if в Rust — это выражение, то есть оно порождает значение. Мы присваиваем результат блока if/else напрямую n. Это короче, чем писать n = ... внутри каждой ветви.
• Неявный возврат: функция заканчивается на len (без точки с запятой), и это значение автоматически возвращается.

Добро пожаловать

Включая 10-минутные перерывы, это занятие займёт около 2 часов 45 минут. Оно включает:

Кортежи и массивы

Этот сегмент займёт около 35 минут. Он включает:

Массивы

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut a: [i8; 5] = [5, 4, 3, 2, 1];
    a[2] = 0;
    println!("a: {a:?}");
}

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut a: [i8; 5] = [5, 4, 3, 2, 1];
    a[6] = 0;
    println!("a: {a:?}");
}

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn get_index() -> usize {
    6
}

fn main() {
    let mut a: [i8; 5] = [5, 4, 3, 2, 1];
    a[get_index()] = 0;
    println!("a: {a:?}");
}

Кортежи

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let t: (i8, bool) = (7, true);
    dbg!(t.0);
    dbg!(t.1);
}

Обход массивов

Выражение for позволяет обходить элементы массива (но не кортежа).

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let primes = [2, 3, 5, 7, 11, 13, 17, 19];
    for prime in primes {
        for i in 2..prime {
            assert_ne!(prime % i, 0);
        }
    }
}

Деструктуризация

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn check_order(tuple: (i32, i32, i32)) -> bool {
    let (left, middle, right) = tuple;
    left < middle && middle < right
}

fn main() {
    let tuple = (1, 5, 3);
    println!(
        "{tuple:?}: {}",
        if check_order(tuple) { "ordered" } else { "unordered" }
    );
}

Упражнение: Вложенные массивы

Элементами массива также могут быть массивы:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];

Каков тип этой переменной?

Используя пример выше, напишите функцию transpose, которая транспонирует матрицу (превращает строки в столбцы):

Скопируйте код ниже в https://play.rust-lang.org/ и реализуйте функцию. Эта функция работает только с матрицами 3×3.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    todo!()
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- rustfmt сохранит перенос на следующую строку
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("Original:");
    for row in matrix {
        println!("{row:?}");
    }

    let transposed = transpose(matrix);

    println!("\nTransposed:");
    for row in transposed {
        println!("{row:?}");
    }
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    let mut result = [[0; 3]; 3];
    for i in 0..3 {
        for j in 0..3 {
            result[j][i] = matrix[i][j];
        }
    }
    result
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- rustfmt сохранит перенос на следующую строку
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("Original:");
    for row in matrix {
        println!("{row:?}");
    }

    let transposed = transpose(matrix);

    println!("\nTransposed:");
    for row in transposed {
        println!("{row:?}");
    }
}

• Типы массивов: тип [[i32; 3]; 3] обозначает массив размера 3, каждый элемент которого сам является массивом из 3 значений i32. Так обычно представляются многомерные массивы в Rust.
• Инициализация: мы инициализируем result нулями ([[0; 3]; 3]) перед заполнением. Rust требует, чтобы все переменные были инициализированы до использования; в безопасном Rust понятия «неинициализированной памяти» нет.
• Семантика копирования: массивы элементов типа Copy (например, i32) сами являются Copy. Когда мы передаём matrix в функцию, она копируется по значению. Переменная result — новый отдельный массив.
• Итерация: мы используем обычные циклы for с диапазонами (0..3), чтобы перебрать индексы. В Rust есть и мощные итераторы, которые мы рассмотрим позже, но для транспонирования матрицы индексация достаточно проста.

Ссылки

Этот сегмент займёт около 55 минут. Он включает:

Общие ссылки

Ссылка даёт доступ к другому значению, не забирая владение этим значением; её также называют «заимствованием». Неизменяемые ссылки доступны только для чтения, и данные, на которые они указывают, не могут меняться.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let a = 'A';
    let b = 'B';

    let mut r: &char = &a;
    dbg!(r);

    r = &b;
    dbg!(r);
}

Неизменяемая ссылка на тип T имеет тип &T. Значение-ссылка создаётся оператором &. Оператор * «разыменовывает» ссылку, возвращая её значение.

Эксклюзивные ссылки

Эксклюзивные ссылки, также известные как изменяемые ссылки, позволяют менять значение, на которое они указывают. Их тип — &mut T.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut point = (1, 2);
    let x_coord = &mut point.0;
    *x_coord = 20;
    println!("point: {point:?}");
}

Срезы

Срезы позволяют ссылаться на непрерывную последовательность элементов в коллекции:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];
    println!("s: {s:?}");
}

• Срезы заимствуют данные у коллекции.

Строки

Теперь давайте разберемся с двумя типами строк в Rust:

• &str — это срез из байтов в кодировке UTF-8, аналогичный &[u8].
• String — это владеющий буфер из байтов в кодировке UTF-8, похожий на Vec<T>.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let s1: &str = "World";
    println!("s1: {s1}");

    let mut s2: String = String::from("Привет ");
    println!("s2: {s2}");

    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[2..9];
    println!("s3: {s3}");
}

Допустимость ссылок

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x_ref = {
        let x = 10;
        &x
    };
    dbg!(x_ref);
}

Упражнение: Геометрия

Мы напишем несколько вспомогательных функций для трёхмерной геометрии, представляя точку как [f64;3]. Сигнатуры функций вы определите сами.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// Вычислите длину вектора, сложив квадраты его координат
// и взяв квадратный корень. Для вычисления корня используйте метод `sqrt()`,
// например `v.sqrt()`.


fn magnitude(...) -> f64 {
    todo!()
}

// Нормализуйте вектор: вычислите его длину и разделите все его координаты
// на эту длину.


fn normalize(...) {
    todo!()
}

// Проверьте свою работу с помощью следующей `main`.

fn main() {
    println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude of {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Вычисляет длину заданного вектора.
fn magnitude(vector: &[f64; 3]) -> f64 {
    let mut mag_squared = 0.0;
    for coord in vector {
        mag_squared += coord * coord;
    }
    mag_squared.sqrt()
}

/// Меняет длину вектора на 1.0, не меняя его направления.
fn normalize(vector: &mut [f64; 3]) {
    let mag = magnitude(vector);
    for item in vector {
        *item /= mag;
    }
}

fn main() {
    println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude of {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
}

Определяемые пользователем типы

Этот сегмент займёт около 1 часа. Он включает:

Именованные структуры

Как и C и C++, Rust поддерживает пользовательские структуры:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Person {
    name: String,
    age: u8,
}

fn describe(person: &Person) {
    println!("{} is {} years old", person.name, person.age);
}

fn main() {
    let mut peter = Person {
        name: String::from("Peter"),
        age: 27,
    };
    describe(&peter);

    peter.age = 28;
    describe(&peter);

    let name = String::from("Avery");
    let age = 39;
    let avery = Person { name, age };
    describe(&avery);
}

Кортежи

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Point(i32, i32);

fn main() {
    let p = Point(17, 23);
    println!("({}, {})", p.0, p.1);
}

Так часто делают обёртки над одним полем (их называют newtype):

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct PoundsOfForce(f64);
struct Newtons(f64);

fn compute_thruster_force() -> PoundsOfForce {
    todo!("Ask a rocket scientist at NASA")
}

fn set_thruster_force(force: Newtons) {
    // ...
}

fn main() {
    let force = compute_thruster_force();
    set_thruster_force(force);
}

Перечисления

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
enum Direction {
    Left,
    Right,
}

#[derive(Debug)]
enum PlayerMove {
    Pass,                        // Простой вариант
    Run(Direction),              // Вариант-кортеж
    Teleport { x: u32, y: u32 }, // Вариант-структура
}

fn main() {
    let dir = Direction::Left;
    let player_move: PlayerMove = PlayerMove::Run(dir);
    println!("On this turn: {player_move:?}");
}

Псевдонимы типов

Псевдоним типа создаёт имя для другого типа. Оба типа можно использовать взаимозаменяемо.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// Псевдонимы полезнее для длинных, сложных типов:
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

const

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

const DIGEST_SIZE: usize = 3;
const FILL_VALUE: u8 = calculate_fill_value();

const fn calculate_fill_value() -> u8 {
    if DIGEST_SIZE < 10 { 42 } else { 13 }
}

fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {
    let mut digest = [FILL_VALUE; DIGEST_SIZE];
    for (idx, &b) in text.as_bytes().iter().enumerate() {
        digest[idx % DIGEST_SIZE] = digest[idx % DIGEST_SIZE].wrapping_add(b);
    }
    digest
}

fn main() {
    let digest = compute_digest("Hello");
    println!("digest: {digest:?}");
}

Во время компиляции можно вызывать только функции, помеченные const, чтобы получить значения const. Однако функции const можно вызывать и во время выполнения.

static

Статические переменные существуют на протяжении всего выполнения программы и поэтому не перемещаются:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

static BANNER: &str = "Добро пожаловать в RustOS 3.14";

fn main() {
    println!("{BANNER}");
}

Как отмечено в Rust RFC Book, при использовании они не подставляются, а имеют реальное связанное место в памяти. Это полезно для небезопасного и встраиваемого кода, а переменная живёт всё время выполнения программы. Если глобально определённому значению не нужна идентичность объекта, обычно предпочтительнее const.

Упражнение: Управление лифтом

Мы создадим структуру данных, которая представляет событие в системе управления лифтом. Вы сами определите типы и функции для создания различных событий. Используйте #[derive(Debug)], чтобы типы можно было выводить через {:?}.

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#![allow(dead_code)]

#[derive(Debug)]
/// Событие в системе лифта, на которое должен реагировать контроллер.
enum Event {
    // TODO: добавьте необходимые варианты
}

/// Направление движения.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// Кабина прибыла на указанный этаж.
fn car_arrived(floor: i32) -> Event {
    todo!()
}

/// Двери кабины открылись.
fn car_door_opened() -> Event {
    todo!()
}

/// Двери кабины закрылись.
fn car_door_closed() -> Event {
    todo!()
}

/// Была нажата кнопка направления в холле лифта на указанном этаже.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    todo!()
}

/// Была нажата кнопка этажа в кабине лифта.
fn car_floor_button_pressed(floor: i32) -> Event {
    todo!()
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("The car has arrived on the ground floor: {:?}", car_arrived(0));
    println!("The car door opened: {:?}", car_door_opened());
    println!(
        "A passenger has pressed the 3rd floor button: {:?}",
        car_floor_button_pressed(3)
    );
    println!("The car door closed: {:?}", car_door_closed());
    println!("The car has arrived on the 3rd floor: {:?}", car_arrived(3));
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#![allow(dead_code)]

#[derive(Debug)]
/// Событие в системе лифта, на которое должен реагировать контроллер.
enum Event {
    /// Была нажата кнопка.
    ButtonPressed(Button),

    /// Кабина прибыла на указанный этаж.
    CarArrived(Floor),

    /// Двери кабины открылись.
    CarDoorOpened,

    /// Двери кабины закрылись.
    CarDoorClosed,
}

/// Этаж представлен целым числом.
type Floor = i32;

/// Направление движения.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// Кнопка, доступная пользователю.
#[derive(Debug)]
enum Button {
    /// Кнопка в холле лифта на указанном этаже.
    LobbyCall(Direction, Floor),

    /// Кнопка этажа внутри кабины.
    CarFloor(Floor),
}

/// Кабина прибыла на указанный этаж.
fn car_arrived(floor: i32) -> Event {
    Event::CarArrived(floor)
}

/// Двери кабины открылись.
fn car_door_opened() -> Event {
    Event::CarDoorOpened
}

/// Двери кабины закрылись.
fn car_door_closed() -> Event {
    Event::CarDoorClosed
}

/// Была нажата кнопка направления в холле лифта на указанном этаже.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    Event::ButtonPressed(Button::LobbyCall(dir, floor))
}

/// Была нажата кнопка этажа в кабине лифта.
fn car_floor_button_pressed(floor: i32) -> Event {
    Event::ButtonPressed(Button::CarFloor(floor))
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("The car has arrived on the ground floor: {:?}", car_arrived(0));
    println!("The car door opened: {:?}", car_door_opened());
    println!(
        "A passenger has pressed the 3rd floor button: {:?}",
        car_floor_button_pressed(3)
    );
    println!("The car door closed: {:?}", car_door_closed());
    println!("The car has arrived on the 3rd floor: {:?}", car_arrived(3));
}

• Перечисления с данными: варианты перечислений Rust могут содержать данные. CarArrived(Floor) хранит целое число, а ButtonPressed(Button) хранит вложенное перечисление Button. Так Event может представлять богатый набор состояний безопасным для типов способом.
• Псевдонимы типов: type Floor = i32 задаёт семантическое имя для i32. Это повышает читаемость, но для компилятора Floor по-прежнему остаётся просто i32.
• #[derive(Debug)]: этот атрибут автоматически генерирует код, который форматирует перечисления при выводе через {:?}. Без него пришлось бы вручную реализовать трейт fmt::Debug.
• Вложенные перечисления: перечисление Button вложено в Event::ButtonPressed. Такая иерархическая структура распространена в Rust для моделирования сложных предметных областей.

Добро пожаловать во второй день

Мы рассмотрели основы Rust:

• Базовые типы: целые, булевы значения, символы, кортежи и массивы.
• Управление потоком: выражения if, циклы и выражения match.
• Функции: как определять и вызывать функции.
• Пользовательские типы: моделирование данных через struct и enum.
• Ссылки: базовое заимствование через & и &mut.

Теперь вы можете построить любой тип в Rust и реализовать базовую логику!

Расписание

Включая 10-минутные перерывы, это занятие займёт около 2 часов 50 минут. Оно включает:

Шаблоны и сопоставление

Этот сегмент займёт около 50 минут. Он включает:

Неопровержимые шаблоны

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn takes_tuple(tuple: (char, i32, bool)) {
    let a = tuple.0;
    let b = tuple.1;
    let c = tuple.2;

    // Это делает то же самое, что и выше.
    let (a, b, c) = tuple;

    // Пропустить первый элемент, связать только второй и третий.
    let (_, b, c) = tuple;

    // Пропустить всё, кроме последнего элемента.
    let (.., c) = tuple;
}

fn main() {
    takes_tuple(('a', 777, true));
}

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

Ключевое слово match позволяет сопоставить значение с одним или несколькими шаблонами. Шаблоны могут быть простыми значениями, как switch в C и C++, но также могут выражать более сложные условия:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("Quitting"),
        'a' | 's' | 'w' | 'd'     => println!("Moving around"),
        '0'..='9'                 => println!("Number input"),
        key if key.is_lowercase() => println!("Lowercase: {key}"),
        _                         => println!("Something else"),
    }
}

Переменная в шаблоне (здесь key) создаёт привязку, которую можно использовать внутри ветки match. Подробнее об этом мы узнаем на следующем слайде.

Охранник совпадения (match guard) делает так, что ветка срабатывает, только если условие истинно. Если условие ложно, match продолжит проверять последующие варианты.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[rustfmt::skip]
fn main() {
    let input = 'a';
    match input {
        key if key.is_uppercase() => println!("Uppercase"),
        key => if input == 'q' { println!("Quitting") },
        _   => println!("Bug: this is never printed"),
    }
}

Структуры

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

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Move {
    delta: (i32, i32),
    repeat: u32,
}

#[rustfmt::skip]
fn main() {
    let m = Move { delta: (10, 0), repeat: 5 };

    match m {
        Move { delta: (0, 0), .. }        => println!("Standing still"),
        Move { delta: (x, 0), repeat }    => println!("{repeat} step x: {x}"),
        Move { delta: (0, y), repeat: 1 } => println!("Single step y: {y}"),
        _                                 => println!("Other move"),
    }
}

Перечисления

Как и кортежи, перечисления тоже можно деструктурировать через сопоставление:

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

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

enum Result {
    Ok(i32),
    Err(String),
}

fn divide_in_two(n: i32) -> Result {
    if n % 2 == 0 {
        Result::Ok(n / 2)
    } else {
        Result::Err(format!("cannot divide {n} into two equal parts"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} divided in two is {half}"),
        Result::Err(msg) => println!("sorry, an error happened: {msg}"),
    }
}

Здесь мы использовали ветки, чтобы деструктурировать значение Result. В первой ветке half связывается со значением внутри варианта Ok. Во второй ветке msg связывается с сообщением об ошибке.

Let в потоке управления

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

• Выражение if let
• Выражение while let
• Выражение let else

Выражения if let

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::time::Duration;

fn sleep_for(secs: f32) {
    let result = Duration::try_from_secs_f32(secs);

    if let Ok(duration) = result {
        std::thread::sleep(duration);
        println!("slept for {duration:?}");
    }
}

fn main() {
    sleep_for(-10.0);
    sleep_for(0.8);
}

Операторы while let

Аналогично if let существует while let, который многократно проверяет значение на соответствие шаблону:

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut name = String::from("Comprehensive Rust 🦀");
    while let Some(c) = name.pop() {
        dbg!(c);
    }
    // (Есть более эффективные способы развернуть строку!)
}

Здесь String::pop возвращает Some(c), пока строка не опустеет, после чего вернёт None. Цикл while let позволяет последовательно перебрать все элементы.

Операторы let else

В распространённом случае, когда нужно сопоставить шаблон и вернуться из функции, используйте let else. Ветка else должна «расходиться» (return, break или паника, но не выход за конец блока).

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let s = if let Some(s) = maybe_string {
        s
    } else {
        return Err(String::from("got None"));
    };

    let first_byte_char = if let Some(first) = s.chars().next() {
        first
    } else {
        return Err(String::from("got empty string"));
    };

    let digit = if let Some(digit) = first_byte_char.to_digit(16) {
        digit
    } else {
        return Err(String::from("not a hex digit"));
    };

    Ok(digit)
}

fn main() {
    println!("result: {:?}", hex_or_die_trying(Some(String::from("foo"))));
}

#![allow(unused)]
fn main() {
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("got None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("got empty string"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("not a hex digit"));
    };

    Ok(digit)
}
}

Упражнение: Вычисление выражения

Напишем простой рекурсивный вычислитель арифметических выражений.

Пример небольшого арифметического выражения — 10 + 20, которое вычисляется в 30. Выражение можно представить как дерево:

Более крупное и сложное выражение — (10 * 9) + ((3 - 4) * 5), которое вычисляется в 85. Мы представим его гораздо большим деревом:

В коде мы представим дерево двумя типами:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Операция, которую нужно выполнить над двумя подвыражениями.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Выражение в виде дерева.
#[derive(Debug)]
enum Expression {
    /// Операция над двумя подвыражениями.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Литеральное значение
    Value(i64),
}

Тип Box здесь — умный указатель, который будет подробно рассмотрен позже в курсе. Выражение можно «упаковать» в Box через Box::new, как показано в тестах. Чтобы вычислить упакованное выражение, используйте оператор разыменования (*), чтобы «распаковать» его: eval(*boxed_expr).

Создайте новый проект Cargo типа library с помощью

cargo new --lib evaluator

Скопируйте и вставьте код ниже в файл src/lib.rs.

Затем начните реализовывать eval. Используйте cargo test, чтобы убедиться, что итоговая библиотека проходит тесты. Может быть полезно использовать todo!() и добиваться прохождения тестов по одному. Тест можно временно пропустить с помощью #[ignore]:

#[test]
#[ignore]
fn test_value() { .. }

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Операция, которую нужно выполнить над двумя подвыражениями.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Выражение в виде дерева.
#[derive(Debug)]
enum Expression {
    /// Операция над двумя подвыражениями.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Литеральное значение
    Value(i64),
}

fn eval(e: Expression) -> i64 {
    todo!()
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), 19);
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        30
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        85
    );
}

#[test]
fn test_zeros() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Mul,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
}

#[test]
fn test_div() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(2)),
        }),
        5
    )
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Операция, которую нужно выполнить над двумя подвыражениями.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Выражение в виде дерева.
#[derive(Debug)]
enum Expression {
    /// Операция над двумя подвыражениями.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Литеральное значение
    Value(i64),
}

fn eval(e: Expression) -> i64 {
    match e {
        Expression::Op { op, left, right } => {
            let left = eval(*left);
            let right = eval(*right);
            match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => left / right,
            }
        }
        Expression::Value(v) => v,
    }
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), 19);
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        30
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        85
    );
}

#[test]
fn test_zeros() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Mul,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        0
    );
}

#[test]
fn test_div() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(2)),
        }),
        5
    )
}

Методы и трейты

Этот сегмент займёт около 45 минут. Он включает:

Методы

Rust позволяет связывать функции с вашими новыми типами. Это делается через блок impl:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
struct CarRace {
    name: String,
    laps: Vec<i32>,
}

impl CarRace {
    // Без получателя, статический метод
    fn new(name: &str) -> Self {
        Self { name: String::from(name), laps: Vec::new() }
    }

    // Эксклюзивный заимствованный доступ на чтение и запись к self
    fn add_lap(&mut self, lap: i32) {
        self.laps.push(lap);
    }

    // Разделяемый заимствованный доступ только на чтение к self
    fn print_laps(&self) {
        println!("Recorded {} laps for {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Lap {idx}: {lap} sec");
        }
    }

    // Эксклюзивное владение self (рассмотрим позже)
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("Race {} is finished, total lap time: {}", self.name, total);
    }
}

fn main() {
    let mut race = CarRace::new("Monaco Grand Prix");
    race.add_lap(70);
    race.add_lap(68);
    race.print_laps();
    race.add_lap(71);
    race.print_laps();
    race.finish();
    // race.add_lap(42);
}

Аргументы self задают «получатель» (receiver) — объект, над которым работает метод. Для методов есть несколько распространённых видов получателей:

• &self: заимствует объект у вызывающего кода через разделяемую неизменяемую ссылку. Объект можно использовать снова после этого.
• &mut self: заимствует объект у вызывающего кода через уникальную изменяемую ссылку. Объект можно использовать снова после этого.
• self: забирает владение объектом и перемещает его из вызывающего кода. Метод становится владельцем объекта. Объект будет освобождён (удалён из памяти) при возврате из метода, если только его владение явно не передано дальше. Полное владение автоматически не означает изменяемость.
• mut self: то же, что и выше, но метод может изменять объект.
• Без получателя: это становится статическим методом структуры. Обычно так создают конструкторы, которые по соглашению называются new.

Трейты

Rust позволяет абстрагироваться от типов с помощью трейтов. Они похожи на интерфейсы:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

trait Pet {
    /// Возвращает фразу, которую произносит этот питомец.
    fn talk(&self) -> String;

    /// Выводит в терминал строку-приветствие от этого питомца.
    fn greet(&self);
}

Реализация трейтов

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

trait Pet {
    fn talk(&self) -> String;

    fn greet(&self) {
        println!("Oh you're a cutie! What's your name? {}", self.talk());
    }
}

struct Dog {
    name: String,
    age: i8,
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

fn main() {
    let fido = Dog { name: String::from("Fido"), age: 5 };
    dbg!(fido.talk());
    fido.greet();
}

Супертрейты

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

trait Animal {
    fn leg_count(&self) -> u32;
}

trait Pet: Animal {
    fn name(&self) -> String;
}

struct Dog(String);

impl Animal for Dog {
    fn leg_count(&self) -> u32 {
        4
    }
}

impl Pet for Dog {
    fn name(&self) -> String {
        self.0.clone()
    }
}

fn main() {
    let puppy = Dog(String::from("Rex"));
    println!("{} has {} legs", puppy.name(), puppy.leg_count());
}

Ассоциированные типы

Ассоциированные типы — это типы-заполнители, которые предоставляет реализация трейта.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
struct Meters(i32);
#[derive(Debug)]
struct MetersSquared(i32);

trait Multiply {
    type Output;
    fn multiply(&self, other: &Self) -> Self::Output;
}

impl Multiply for Meters {
    type Output = MetersSquared;
    fn multiply(&self, other: &Self) -> Self::Output {
        MetersSquared(self.0 * other.0)
    }
}

fn main() {
    println!("{:?}", Meters(10).multiply(&Meters(20)));
}

Наследование

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug, Clone, Default)]
struct Player {
    name: String,
    strength: u8,
    hit_points: u8,
}

fn main() {
    let p1 = Player::default(); // Трейт Default добавляет конструктор `default`.
    let mut p2 = p1.clone(); // Трейт Clone добавляет метод `clone`.
    p2.name = String::from("EldurScrollz");
    // Трейт Debug добавляет поддержку вывода через `{:?}`.
    println!("{p1:?} vs. {p2:?}");
}

Упражнение: трейт Logger

Давайте спроектируем простую утилиту логирования с трейтом Logger, у которого есть метод log. Код, который может записывать ход своей работы, затем может принимать &impl Logger. В тестах это может записывать сообщения в файл журнала тестов, а в рабочей (production) сборке — отправлять сообщения на сервер логов.

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

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

trait Logger {
    /// Записывает сообщение с заданным уровнем подробности.
    fn log(&self, verbosity: u8, message: &str);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: &str) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

/// Записывает только сообщения до заданного уровня подробности.
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StderrLogger,
}

// TODO: Реализуйте трейт `Logger` для `VerbosityFilter`.

fn main() {
    let logger = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

trait Logger {
    /// Записывает сообщение с заданным уровнем подробности.
    fn log(&self, verbosity: u8, message: &str);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: &str) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

/// Записывает только сообщения до заданного уровня подробности.
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StderrLogger,
}

impl Logger for VerbosityFilter {
    fn log(&self, verbosity: u8, message: &str) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let logger = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

Обобщения

Этот сегмент займёт около 50 минут. Он включает:

Обобщённые функции

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn pick<T>(cond: bool, left: T, right: T) -> T {
    if cond { left } else { right }
}

fn main() {
    println!("picked a number: {:?}", pick(true, 222, 333));
    println!("picked a string: {:?}", pick(false, 'L', 'R'));
}

Ограничение трейта

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

Это можно сделать с помощью T: Trait:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

struct NotCloneable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

Обобщённые типы данных

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub trait Logger {
    /// Записывает сообщение с заданным уровнем подробности.
    fn log(&self, verbosity: u8, message: &str);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: &str) {
        eprintln!("[stderr] verbosity={verbosity}: {message}");
    }
}

struct StdoutLogger;

impl Logger for StdoutLogger {
    fn log(&self, verbosity: u8, message: &str) {
        println!("[stdout] verbosity={verbosity}: {message}");
    }
}

/// Записывает только сообщения до заданного уровня подробности.
struct VerbosityFilter<L> {
    max_verbosity: u8,
    inner: L,
}

impl<L: Logger> Logger for VerbosityFilter<L> {
    fn log(&self, verbosity: u8, message: &str) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let err = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    err.log(5, "FYI");
    err.log(2, "Uhoh");

    let out = VerbosityFilter { max_verbosity: 3, inner: StdoutLogger };
    out.log(5, "FYI");
    out.log(2, "Uhoh");
}

Обобщённые трейты

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

#![allow(unused)]
fn main() {
// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub trait From<T>: Sized {
    fn from(value: T) -> Self;
}
}

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
struct Foo(String);

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("Converted from integer: {from}"))
    }
}

impl From<bool> for Foo {
    fn from(from: bool) -> Foo {
        Foo(format!("Converted from bool: {from}"))
    }
}

fn main() {
    let from_int = Foo::from(123);
    let from_bool = Foo::from(true);
    dbg!(from_int);
    dbg!(from_bool);
}

Синтаксис impl

Как и ограничения трейтов, синтаксис impl Trait можно использовать в аргументах функций и в возвращаемых значениях:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

// Синтаксический сахар для:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    dbg!(many);
    let many_more = add_42_millions(10_000_000);
    dbg!(many_more);
    let debuggable = pair_of(27);
    dbg!(debuggable);
}

dyn Trait

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

// Использует обобщения и статическую диспетчеризацию.
fn generic(pet: &impl Pet) {
    println!("Hello, who are you? {}", pet.talk());
}

// Использует стирание типов и динамическую диспетчеризацию.
fn dynamic(pet: &dyn Pet) {
    println!("Hello, who are you? {}", pet.talk());
}

fn main() {
    let cat = Cat { lives: 9 };
    let dog = Dog { name: String::from("Fido"), age: 5 };

    generic(&cat);
    generic(&dog);

    dynamic(&cat);
    dynamic(&dog);
}

Упражнение: Обобщение min

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cmp::Ordering;

// TODO: реализуйте функцию `min`, которая используется в тестах.

#[test]
fn integers() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);
}

#[test]
fn chars() {
    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');
}

#[test]
fn strings() {
    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cmp::Ordering;

fn min<T: Ord>(l: T, r: T) -> T {
    match l.cmp(&r) {
        Ordering::Less | Ordering::Equal => l,
        Ordering::Greater => r,
    }
}

#[test]
fn integers() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);
}

#[test]
fn chars() {
    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');
}

#[test]
fn strings() {
    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

Добро пожаловать

Включая 10-минутные перерывы, это занятие займёт около 2 часов 50 минут. Оно включает:

Замыкания

Этот сегмент займёт около 30 минут. Он включает:

Синтаксис замыканий

Замыкания создаются с помощью вертикальных черт: |..| ...

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    // Тип аргумента и возвращаемый тип могут быть выведены в облегчённом синтаксисе:
    let double_it = |n| n * 2;
    dbg!(double_it(50));

    // Или можно явно указать типы и заключить тело в фигурные скобки:
    let add_1f32 = |x: f32| -> f32 { x + 1.0 };
    dbg!(add_1f32(50.));
}

Захват переменных

Замыкание может захватывать переменные из окружения, в котором оно определено.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let max_value = 5;
    let clamp = |v| {
        if v > max_value { max_value } else { v }
    };

    dbg!(clamp(1));
    dbg!(clamp(3));
    dbg!(clamp(5));
    dbg!(clamp(7));
    dbg!(clamp(10));
}

Трейты замыканий

Замыкания, или лямбда-выражения, имеют типы, которые нельзя назвать. Однако они реализуют специальные трейты Fn, FnMut и FnOnce:

Специальные типы fn(..) -> T обозначают указатели на функции: либо адрес функции, либо замыкание, которое ничего не захватывает.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn apply_and_log(
    func: impl FnOnce(&'static str) -> String,
    func_name: &'static str,
    input: &'static str,
) {
    println!("Calling {func_name}({input}): {}", func(input))
}

fn main() {
    let suffix = "-itis";
    let add_suffix = |x| format!("{x}{suffix}");
    apply_and_log(&add_suffix, "add_suffix", "senior");
    apply_and_log(&add_suffix, "add_suffix", "appendix");

    let mut v = Vec::new();
    let mut accumulate = |x| {
        v.push(x);
        v.join("/")
    };
    apply_and_log(&mut accumulate, "accumulate", "red");
    apply_and_log(&mut accumulate, "accumulate", "green");
    apply_and_log(&mut accumulate, "accumulate", "blue");

    let take_and_reverse = |prefix| {
        let mut acc = String::from(prefix);
        acc.push_str(&v.into_iter().rev().collect::<Vec<_>>().join("/"));
        acc
    };
    apply_and_log(take_and_reverse, "take_and_reverse", "reversed: ");
}

Упражнение: фильтр логов

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub trait Logger {
    /// Записывает сообщение с заданным уровнем подробности.
    fn log(&self, verbosity: u8, message: &str);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: &str) {
        eprintln!("[stderr] verbosity={verbosity}: {message}");
    }
}

struct StdoutLogger;

impl Logger for StdoutLogger {
    fn log(&self, verbosity: u8, message: &str) {
        println!("[stdout] verbosity={verbosity}: {message}");
    }
}

// TODO: определите и реализуйте `Filter`.

fn main() {
    let prefix = "yikes";
    let max_verbosity = 3;

    // Логгер, который пишет в stderr и фильтрует по содержимому сообщений.
    let logger = Filter::new(StderrLogger, |_verbosity, msg| msg.contains(prefix));
    logger.log(5, "FYI");
    logger.log(1, "yikes, something went wrong");
    logger.log(2, "uhoh");

    // Логгер, который пишет в stdout и фильтрует по уровню подробности.
    let logger =
        Filter::new(StdoutLogger, |verbosity, _msg| verbosity <= max_verbosity);
    logger.log(5, "FYI");
    logger.log(1, "yikes, something went wrong");
    logger.log(2, "uhoh");
}

Решение

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub trait Logger {
    /// Записывает сообщение с заданным уровнем подробности.
    fn log(&self, verbosity: u8, message: &str);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: &str) {
        eprintln!("[stderr] verbosity={verbosity}: {message}");
    }
}

struct StdoutLogger;

impl Logger for StdoutLogger {
    fn log(&self, verbosity: u8, message: &str) {
        println!("[stdout] verbosity={verbosity}: {message}");
    }
}

/// Записывает только сообщения, которые соответствуют предикату фильтрации.
struct Filter<L, P> {
    inner: L,
    predicate: P,
}

impl<L, P> Filter<L, P>
where
    P: Fn(u8, &str) -> bool,
{
    fn new(inner: L, predicate: P) -> Self {
        Self { inner, predicate }
    }
}

impl<L, P> Logger for Filter<L, P>
where
    L: Logger,
    P: Fn(u8, &str) -> bool,
{
    fn log(&self, verbosity: u8, message: &str) {
        if (self.predicate)(verbosity, message) {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let prefix = "yikes";
    let max_verbosity = 3;

    // Логгер, который пишет в stderr и фильтрует по содержимому сообщений.
    let logger = Filter::new(StderrLogger, |_verbosity, msg| msg.contains(prefix));
    logger.log(5, "FYI");
    logger.log(1, "yikes, something went wrong");
    logger.log(2, "uhoh");

    // Логгер, который пишет в stdout и фильтрует по уровню подробности.
    let logger =
        Filter::new(StdoutLogger, |verbosity, _msg| verbosity <= max_verbosity);
    logger.log(5, "FYI");
    logger.log(1, "yikes, something went wrong");
    logger.log(2, "uhoh");
}

• Хранение замыканий: чтобы сохранить замыкание в структуре, мы используем обобщённый параметр типа (здесь P). Это потому, что каждое замыкание в Rust имеет уникальный анонимный тип, который генерирует компилятор.
• Ограничение Fn: ограничение P: Fn(u8, &str) -> bool сообщает компилятору, что P можно вызвать как функцию с указанными аргументами и возвращаемым типом. Мы используем Fn (а не FnMut или FnOnce), потому что log принимает &self, поэтому предикат можно использовать только неизменяемо.
• Вызов полей: мы вызываем замыкание через (self.predicate)(...). Скобки вокруг self.predicate необходимы, чтобы отличить вызов метода с именем predicate от вызова самого поля.

Стандартная библиотека: Типы

Этот сегмент займёт около 1 часа. Он включает:

Стандартная библиотека

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

На самом деле в стандартной библиотеке Rust есть несколько уровней: core, alloc и std.

• core включает самые базовые типы и функции, которые не зависят от libc, аллокатора и даже наличия операционной системы.
• alloc включает типы, которым нужен глобальный аллокатор кучи, например Vec, Box и Arc.
• Встраиваемые приложения на Rust обычно используют только core, а иногда и alloc.

Документация

В Rust есть обширная документация. Например:

• Все подробности о циклах.
• Примитивные типы, например u8.
• Типы стандартной библиотеки, например Option или BinaryHeap.

Чтобы просмотреть документацию, используйте rustup doc --std или https://std.rs.

На самом деле вы можете документировать и собственный код:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Определяет, делится ли первый аргумент на второй.
///
/// Если второй аргумент равен нулю, результат --- false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

Содержимое интерпретируется как Markdown. Все опубликованные крейты библиотек Rust автоматически документируются на docs.rs с помощью инструмента rustdoc. Документировать таким образом все общедоступные элементы API — идиоматичный подход.

Чтобы задокументировать элемент изнутри него (например, внутри модуля), используйте //! или /*! .. */, так называемые «внутренние doc-комментарии»:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

//! Этот модуль содержит функции, связанные с делимостью целых чисел.

Option

Мы уже видели некоторое использование Option<T>. Он хранит либо значение типа T, либо ничего. Например, String::find возвращает Option<usize>.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    dbg!(position);
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    dbg!(position);
    assert_eq!(position.expect("Character not found"), 0);
}

Result

Result похож на Option, но указывает на успех или неудачу операции, каждое из которых представлено разным вариантом перечисления. Он обобщённый: Result<T, E>, где T используется в варианте Ok, а E появляется в варианте Err.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Dear diary: {contents} ({bytes} bytes)");
            } else {
                println!("Could not read file content");
            }
        }
        Err(err) => {
            println!("The diary could not be opened: {err}");
        }
    }
}

String

String — это растущая строка в кодировке UTF-8:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut s1 = String::new();
    s1.push_str("Hello");
    println!("s1: len = {}, capacity = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: len = {}, capacity = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇨🇭");
    println!("s3: len = {}, number of chars = {}", s3.len(), s3.chars().count());
}

String реализует Deref<Target = str>, что означает, что на String можно вызывать все методы str.

Vec

Vec — стандартный расширяемый буфер в куче:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: len = {}, capacity = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: len = {}, capacity = {}", v2.len(), v2.capacity());

    // Канонический макрос для инициализации вектора элементами.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Оставить только чётные элементы.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Удалить подряд идущие дубликаты.
    v3.dedup();
    println!("{v3:?}");
}

Vec реализует Deref<Target = [T]>, что означает, что на Vec можно вызывать методы срезов.

HashMap

Стандартная хеш-таблица с защитой от атак HashDoS:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Adventures of Huckleberry Finn", 207);
    page_counts.insert("Grimms' Fairy Tales", 751);
    page_counts.insert("Pride and Prejudice", 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "We know about {} books, but not Les Misérables.",
            page_counts.len()
        );
    }

    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} pages"),
            None => println!("{book} is unknown."),
        }
    }

    // Используйте метод .entry(), чтобы вставить значение, если ничего не найдено.
    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        let page_count: &mut i32 = page_counts.entry(book).or_insert(0);
        *page_count += 1;
    }

    dbg!(page_counts);
}

Упражнение: Счётчик

В этом упражнении вы возьмёте очень простую структуру данных и сделаете её обобщённой. Она использует std::collections::HashMap, чтобы отслеживать, какие значения встречались и сколько раз каждое из них появлялось.

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

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::collections::HashMap;

/// Counter считает, сколько раз встретилось каждое значение типа T.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Создаёт новый Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Учитывает появление заданного значения.
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// Возвращает, сколько раз встретилось заданное значение.
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::collections::HashMap;
use std::hash::Hash;

/// Counter считает, сколько раз встретилось каждое значение типа T.
struct Counter<T> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Создаёт новый Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Учитывает появление заданного значения.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Возвращает, сколько раз встретилось заданное значение.
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

Стандартная библиотека: Трейты

Этот сегмент займёт около 1 часа. Он включает:

Сравнения

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

PartialEq и Eq

PartialEq — частичное отношение эквивалентности с обязательным методом eq и предоставляемым методом ne. Операторы == и != вызывают эти методы.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq — полное отношение эквивалентности (рефлексивное, симметричное и транзитивное), и оно подразумевает PartialEq. Функции, которые требуют полной эквивалентности, используют Eq как ограничение трейта.

PartialOrd и Ord

PartialOrd задаёт частичный порядок с методом partial_cmp. Он используется для реализации операторов <, <=, >= и >.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord — полный порядок, где cmp возвращает Ordering.

Перегрузка операторов

Перегрузка операторов реализуется через трейты в std::ops:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{p1:?} + {p2:?} = {:?}", p1 + p2);
}

From и Into

Типы реализуют From и Into, чтобы упростить преобразования типов. В отличие от as, эти трейты соответствуют преобразованиям без потерь, которые не могут завершиться ошибкой.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let s = String::from("hello");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

Into реализуется автоматически, когда реализован From:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let s: String = "hello".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

Преобразование типов

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let value: i64 = 1000;
    println!("as u16: {}", value as u16);
    println!("as i16: {}", value as i16);
    println!("as u8: {}", value as u8);
}

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

Приведение через as — довольно острый инструмент, которым легко ошибиться, и он может стать источником тонких ошибок, когда при дальнейшей разработке меняются используемые типы или диапазоны значений. Приведения лучше использовать только тогда, когда намерение — безусловно отбросить старшие биты (например, выбрать младшие 32 бита u64 через as u32, независимо от того, что было в старших битах).

Для приведений, которые не могут завершиться ошибкой (например, u32 в u64), предпочтительнее использовать From или Into, а не as, чтобы подтвердить, что приведение действительно безошибочно. Для приведений, которые могут не сработать, доступны TryFrom и TryInto, если нужно по-разному обрабатывать значения, которые помещаются, и те, которые не помещаются.

Read и Write

Используя Read и BufRead, можно абстрагироваться от источников u8:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("lines in slice: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("lines in file: {}", count_lines(file));
    Ok(())
}

Аналогично Write позволяет абстрагироваться от приёмников u8:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "Hello")?;
    log(&mut buffer, "World")?;
    println!("Logged: {buffer:?}");
    Ok(())
}

Трейт Default

Default задаёт значение по умолчанию для типа.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    dbg!(default_struct);

    let almost_default_struct =
        Derived { y: "Y is set!".into(), ..Derived::default() };
    dbg!(almost_default_struct);

    let nothing: Option<Derived> = None;
    dbg!(nothing.unwrap_or_default());
}

Упражнение: Шифр ROT13

В этом упражнении вы реализуете классический шифр «ROT13». Скопируйте код в playground и реализуйте недостающие части. Поворачивайте только буквы ASCII, чтобы результат оставался корректным UTF-8.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// Реализуйте трейт `Read` для `RotDecoder`.

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_slice(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

Что произойдёт, если соединить два экземпляра RotDecoder подряд, каждый из которых поворачивает на 13 символов?

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_slice(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

Добро пожаловать в третий день

Теперь мы рассмотрели все основные возможности языка:

• Основы: базовые типы, управление потоком, функции и структуры данных.
• Сопоставление с образцом: эффективная деструктуризация данных.
• Полиморфизм: методы, трейты и обобщения.
• Стандартная библиотека: использование основных типов, таких как Option, Result, Vec и String.
• Замыкания: анонимные функции, которые могут захватывать окружение.

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

Расписание

Включая 10-минутные перерывы, это занятие займёт около 2 часов 20 минут. Оно включает:

Управление памятью

Этот сегмент займёт около 1 часа. Он включает:

Куча и стек

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

• Стек: непрерывная область памяти для локальных переменных.

  • Значения имеют фиксированный размер, известный во время компиляции.
  • Чрезвычайно быстро: достаточно сдвинуть указатель стека.
  • Легко управлять: следует за вызовами функций.
  • Отличная локальность памяти.

• Куча: хранилище значений вне вызовов функций.

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

Пример

Создание String размещает метаданные фиксированного размера на стеке, а данные переменного размера, то есть саму строку, — в куче:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut s1 = String::from("Hello");
    s1.push(' ');
    s1.push_str("world");
    // НЕ ДЕЛАЙТЕ ТАК ДОМА! Только в учебных целях.
    // String не даёт никаких гарантий о своей раскладке, поэтому это может привести к
    // неопределённому поведению.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacity = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

Подходы к управлению памятью

Традиционно языки делятся на две широкие категории:

• Полный контроль через ручное управление памятью: C, C++, Pascal, …
  • Программист решает, когда выделять или освобождать память в куче.
  • Программист должен определить, всё ещё ли указатель указывает на допустимую память.
  • Исследования показывают, что программисты допускают ошибки.
• Полная безопасность через автоматическое управление памятью во время выполнения: Java, Python, Go, Haskell, …
  • Система времени выполнения гарантирует, что память не освобождается, пока на неё можно ссылаться.
  • Обычно реализуется подсчётом ссылок или сборкой мусора.

Rust предлагает новую комбинацию:

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

Это достигается с помощью явной концепции владения.

Владение

У каждой привязки переменной есть область видимости, в которой она действительна, и использовать переменную вне её области видимости — ошибка:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        dbg!(p.0);
    }
    dbg!(p.1);
}

Говорят, что переменная владеет значением. Каждое значение в Rust всегда имеет ровно одного владельца.

В конце области видимости переменная освобождается (dropped), и данные освобождаются. Здесь может выполниться деструктор, чтобы освободить ресурсы.

Перемещение

Присваивание передаёт владение между переменными:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let s1 = String::from("Hello!");
    let s2 = s1;
    dbg!(s2);
    // dbg!(s1);
}

• Присваивание s1 в s2 передаёт владение.
• Когда s1 выходит из области видимости, ничего не происходит: она ничем не владеет.
• Когда s2 выходит из области видимости, данные строки освобождаются.

До перемещения в s2:

После перемещения в s2:

Когда вы передаёте значение в функцию, оно присваивается параметру функции. Это передаёт владение:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn say_hello(name: String) {
    println!("{name}, привет!")
}

fn main() {
    let name = String::from("Алиса");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Дублируем данные из s1.

Clone

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn say_hello(name: String) {
    println!("{name}, привет!")
}

fn main() {
    let name = String::from("Алиса");
    say_hello(name.clone());
    say_hello(name);
}

Копируемые типы

Хотя семантика перемещения используется по умолчанию, некоторые типы копируются по умолчанию:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x = 42;
    let y = x;
    dbg!(x); // would not be accessible if not Copy
    dbg!(y);
}

Эти типы реализуют трейт Copy.

Свои типы можно явно пометить для использования семантики копирования:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• После присваивания и p1, и p2 владеют собственными данными.
• Также можно использовать p1.clone(), чтобы явно скопировать данные.

Трейт Drop

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Dropping {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "b" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Exiting innermost block");
        }
        println!("Exiting next block");
    }
    drop(a);
    println!("Exiting main");
}

Упражнение: Тип-построитель

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

Заполните недостающие части.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Представление программного пакета.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Возвращает представление этого пакета как зависимости, для использования при
    /// сборке других пакетов.
    fn to_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// Строитель для Package. Используйте `build()`, чтобы создать сам `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// Задаёт версию пакета.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Задаёт авторов пакета.
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// Добавляет дополнительную зависимость.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Задаёт язык. Если не задан, язык по умолчанию --- None.
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    dbg!(&base64);
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    dbg!(&log);
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.to_dependency())
        .dependency(log.to_dependency())
        .build();
    dbg!(serde);
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Представление программного пакета.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Возвращает представление этого пакета как зависимости, для использования при
    /// сборке других пакетов.
    fn to_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// Строитель для Package. Используйте `build()`, чтобы создать сам `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: Vec::new(),
            dependencies: Vec::new(),
            language: None,
        })
    }

    /// Задаёт версию пакета.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Задаёт авторов пакета.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Добавляет дополнительную зависимость.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Задаёт язык. Если не задан, язык по умолчанию --- None.
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    dbg!(&base64);
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    dbg!(&log);
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.to_dependency())
        .dependency(log.to_dependency())
        .build();
    dbg!(serde);
}

Умные указатели

Этот сегмент займёт около 55 минут. Он включает:

Box<T>

Box — владеющий указатель на данные в куче:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let five = Box::new(5);
    println!("five: {}", *five);
}

Box<T> реализует Deref<Target = T>, что означает, что можно вызывать методы T напрямую на Box<T>.

Рекурсивные типы данных и типы данных с динамическим размером нельзя хранить напрямую без косвенности через указатель. Box обеспечивает эту косвенность:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
enum List<T> {
    /// Непустой список: первый элемент и остальная часть списка.
    Element(T, Box<List<T>>),
    /// Пустой список.
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

Rc

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    dbg!(a);
    dbg!(b);
}

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

• См. Arc и Mutex, если вы работаете в многопоточном контексте.
• Разделяемый указатель можно понизить до Weak указателя, чтобы создавать циклы, которые в итоге будут освобождены.

Владеющие объекты трейтов

Ранее мы видели, как объекты трейтов можно использовать со ссылками, например &dyn Pet. Однако объекты трейтов можно использовать и с умными указателями, такими как Box, чтобы создать владеющий объект трейта: Box<dyn Pet>.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Fido"), age: 5 }),
    ];
    for pet in pets {
        println!("Hello, who are you? {}", pet.talk());
    }
}

Раскладка памяти после выделения pets:

Упражнение: Двоичное дерево

Двоичное дерево — древовидная структура данных, в которой каждый узел имеет двух потомков (левого и правого). Мы создадим дерево, в котором каждый узел хранит значение. Для заданного узла N все узлы в левом поддереве N содержат меньшие значения, а все узлы в правом поддереве N — большие. Заданное значение должно храниться в дереве только один раз, то есть дубликатов узлов быть не должно.

Реализуйте следующие типы так, чтобы заданные тесты проходили.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Узел двоичного дерева.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Поддерево, которое может быть пустым.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Контейнер, хранящий набор значений в двоичном дереве.
///
/// Если одно и то же значение добавляется несколько раз, оно хранится только один раз.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

// Реализуйте `new` для `Node`.
// Реализуйте `new`, `insert`, `len` и `has` для `Subtree`.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // не уникальный элемент
        assert_eq!(tree.len(), 2);
        tree.insert(3);
        assert_eq!(tree.len(), 3);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cmp::Ordering;

/// Узел двоичного дерева.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Поддерево, которое может быть пустым.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Контейнер, хранящий набор значений в двоичном дереве.
///
/// Если одно и то же значение добавляется несколько раз, оно хранится только один раз.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // не уникальный элемент
        assert_eq!(tree.len(), 2);
        tree.insert(3);
        assert_eq!(tree.len(), 3);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Добро пожаловать

Включая 10-минутные перерывы, это занятие займёт около 2 часов 30 минут. Оно включает:

Заимствование

Этот сегмент займёт около 1 часа 15 минут. Он включает:

Заимствование значения

Как мы видели раньше, вместо передачи владения при вызове функции можно позволить функции заимствовать значение:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• Функция add заимствует две точки и возвращает новую точку.
• Вызывающий код сохраняет владение входными данными.

Анализатор заимствований

Анализатор заимствований (borrow checker) Rust накладывает ограничения на способы заимствования значений. Мы уже видели, что ссылка не может пережить значение, которое она заимствует:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let x_ref = {
        let x = 10;
        &x
    };
    dbg!(x_ref);
}

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

• Можно иметь одну или несколько разделяемых ссылок на значение, или
• Можно иметь ровно одну эксклюзивную ссылку на значение.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut a = 10;
    let b = &a;

    {
        let c = &mut a;
        *c = 20;
    }

    dbg!(a);
    dbg!(b);
}

Ошибки заимствования

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let elem = &vec[2];
    vec.push(6);
    dbg!(elem);
}

Аналогично рассмотрим инвалидацию итератора:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    for elem in &vec {
        vec.push(elem * 2);
    }
}

Внутренняя изменяемость

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

Паттерн «внутренняя изменяемость» (interior mutability) позволяет эксклюзивный (изменяемый) доступ за разделяемой ссылкой. Стандартная библиотека предоставляет несколько способов это сделать, при этом сохраняя безопасность, обычно с помощью проверки во время выполнения.

Cell

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cell::Cell;

fn main() {
    // Обратите внимание, что `cell` НЕ объявлена как изменяемая.
    let cell = Cell::new(5);

    cell.set(123);
    dbg!(cell.get());
}

RefCell

RefCell позволяет обращаться к оборачиваемому значению и изменять его, предоставляя альтернативные типы Ref и RefMut, которые имитируют &T/&mut T, но при этом не являются ссылками Rust.

Эти типы выполняют динамические проверки с помощью счётчика в RefCell, чтобы не допустить существования RefMut одновременно с другим Ref/RefMut.

Реализуя Deref (а для RefMut — DerefMut), эти типы позволяют вызывать методы внутреннего значения, не допуская утечки ссылок наружу.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::cell::RefCell;

fn main() {
    // Обратите внимание, что `cell` НЕ объявлена как изменяемая.
    let cell = RefCell::new(5);

    {
        let mut cell_ref = cell.borrow_mut();
        *cell_ref = 123;

        // Это вызывает ошибку во время выполнения.
        // let other = cell.borrow();
        // println!("{}", other);
    }

    println!("{cell:?}");
}

Упражнение: инвентарь волшебника

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

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

• У заклинаний ограниченное число использований. Когда у заклинания не остаётся использований, его нужно удалить из инвентаря волшебника.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Spell {
    name: String,
    cost: u32,
    uses: u32,
}

struct Wizard {
    spells: Vec<Spell>,
    mana: u32,
}

impl Wizard {
    fn new(mana: u32) -> Self {
        Wizard { spells: vec![], mana }
    }

    // TODO: Реализуйте `add_spell`, чтобы он забирал владение заклинанием и добавлял его в
    // инвентарь волшебника.
    fn add_spell(..., spell: ...) {
        todo!()
    }

    // TODO: Реализуйте `cast_spell`, чтобы он заимствовал заклинание из инвентаря и
    // применял его. Мана волшебника должна уменьшиться на стоимость заклинания, а
    // число использований заклинания --- на 1.
    //
    // Если у волшебника недостаточно маны, заклинание не срабатывает.
    // Если у заклинания не осталось использований, оно удаляется из инвентаря.
    fn cast_spell(..., name: ...) {
        todo!()
    }
}

fn main() {
    let mut merlin = Wizard::new(100);
    let fireball = Spell { name: String::from("Fireball"), cost: 10, uses: 2 };
    let ice_blast = Spell { name: String::from("Ice Blast"), cost: 15, uses: 1 };

    merlin.add_spell(fireball);
    merlin.add_spell(ice_blast);

    merlin.cast_spell("Fireball"); // Успешно применено
    merlin.cast_spell("Ice Blast"); // Успешно применено, затем удалено
    merlin.cast_spell("Ice Blast"); // Не срабатывает (не найдено)
    merlin.cast_spell("Fireball"); // Успешно применено, затем удалено
    merlin.cast_spell("Fireball"); // Не срабатывает (не найдено)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add_spell() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 3 };
        wizard.add_spell(spell);
        assert_eq!(wizard.spells.len(), 1);
    }

    #[test]
    fn test_cast_spell() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 3 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 5);
        assert_eq!(wizard.spells.len(), 1);
        assert_eq!(wizard.spells[0].uses, 2);
    }

    #[test]
    fn test_cast_spell_insufficient_mana() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 15, uses: 3 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 10);
        assert_eq!(wizard.spells.len(), 1);
        assert_eq!(wizard.spells[0].uses, 3);
    }

    #[test]
    fn test_cast_spell_not_found() {
        let mut wizard = Wizard::new(10);
        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 10);
    }

    #[test]
    fn test_cast_spell_removal() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 1 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 5);
        assert_eq!(wizard.spells.len(), 0);
    }
}

Решение: инвентарь волшебника

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Spell {
    name: String,
    cost: u32,
    uses: u32,
}

struct Wizard {
    spells: Vec<Spell>,
    mana: u32,
}

impl Wizard {
    fn new(mana: u32) -> Self {
        Wizard { spells: vec![], mana }
    }

    fn add_spell(&mut self, spell: Spell) {
        self.spells.push(spell);
    }

    fn cast_spell(&mut self, name: &str) {
        let mut spell_idx = None;
        for idx in 0..self.spells.len() {
            if self.spells[idx].name == name {
                spell_idx = Some(idx);
                break;
            }
        }

        let Some(idx) = spell_idx else {
            println!("Spell {} not found!", name);
            return;
        };

        let spell = &mut self.spells[idx];
        if self.mana >= spell.cost {
            self.mana -= spell.cost;
            spell.uses -= 1;
            println!(
                "Casting {}! Mana left: {}. Uses left: {}",
                spell.name, self.mana, spell.uses
            );
            if spell.uses == 0 {
                self.spells.remove(idx);
            }
        } else {
            println!("Not enough mana to cast {}!", spell.name);
        }
    }
}

fn main() {
    let mut merlin = Wizard::new(100);
    let fireball = Spell { name: String::from("Fireball"), cost: 10, uses: 2 };
    let ice_blast = Spell { name: String::from("Ice Blast"), cost: 15, uses: 1 };

    merlin.add_spell(fireball);
    merlin.add_spell(ice_blast);

    merlin.cast_spell("Fireball"); // Успешно применено
    merlin.cast_spell("Ice Blast"); // Успешно применено, затем удалено
    merlin.cast_spell("Ice Blast"); // Не срабатывает (не найдено)
    merlin.cast_spell("Fireball"); // Успешно применено, затем удалено
    merlin.cast_spell("Fireball"); // Не срабатывает (не найдено)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add_spell() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 3 };
        wizard.add_spell(spell);
        assert_eq!(wizard.spells.len(), 1);
    }

    #[test]
    fn test_cast_spell() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 3 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 5);
        assert_eq!(wizard.spells.len(), 1);
        assert_eq!(wizard.spells[0].uses, 2);
    }

    #[test]
    fn test_cast_spell_insufficient_mana() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 15, uses: 3 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 10);
        assert_eq!(wizard.spells.len(), 1);
        assert_eq!(wizard.spells[0].uses, 3);
    }

    #[test]
    fn test_cast_spell_not_found() {
        let mut wizard = Wizard::new(10);
        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 10);
    }

    #[test]
    fn test_cast_spell_removal() {
        let mut wizard = Wizard::new(10);
        let spell = Spell { name: String::from("Fireball"), cost: 5, uses: 1 };
        wizard.add_spell(spell);

        wizard.cast_spell("Fireball");
        assert_eq!(wizard.mana, 5);
        assert_eq!(wizard.spells.len(), 0);
    }
}

Время жизни ссылок

Этот сегмент займёт около 1 часа 5 минут. Он включает:

Заимствование в функциях

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn borrows(x: &i32) {
    dbg!(x);
}

fn main() {
    let mut val = 123;

    // Заимствуем `val` на время вызова функции.
    borrows(&val);

    // Заимствование закончилось, и можно изменять значение.
    val += 5;
}

Возврат заимствований

Но функция также может возвращать ссылку! Это означает, что заимствование передаётся обратно из функции:

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn identity(x: &i32) -> &i32 {
    x
}

fn main() {
    let mut x = 123;

    let out = identity(&x);

    // x = 5; // 🛠️❌ `x` всё ещё заимствован!

    dbg!(out);
}

Несколько заимствований

Но что, если в функцию передаются несколько заимствований, а возвращается одно из них?

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn multiple(a: &i32, b: &i32) -> &i32 {
    todo!("Return either `a` or `b`")
}

fn main() {
    let mut a = 5;
    let mut b = 10;

    let r = multiple(&a, &b);

    // Какой из них всё ещё заимствован?
    // Можно ли разрешить какое-либо из изменений?
    a += 7;
    b += 7;

    dbg!(r);
}

Заимствование обоих

В этом случае у нас есть функция, которая может вернуть либо a, либо b. Здесь мы используем аннотации времён жизни, чтобы сообщить компилятору, что оба заимствования могут попасть в возвращаемое значение.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn pick<'a>(c: bool, a: &'a i32, b: &'a i32) -> &'a i32 {
    if c { a } else { b }
}

fn main() {
    let mut a = 5;
    let mut b = 10;

    let r = pick(true, &a, &b);

    // Какой из них всё ещё заимствован?
    // Можно ли разрешить какое-либо из изменений?
    // a += 7;
    // b += 7;

    dbg!(r);
}

Заимствование одного

В этом примере find_nearest принимает несколько заимствований, но возвращает только одно из них. Аннотации времён жизни явно связывают возвращаемое заимствование с соответствующим заимствованием аргумента.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
struct Point(i32, i32);

/// Ищет в `points` точку, ближайшую к `query`.
/// Предполагается, что в `points` есть хотя бы одна точка.
fn find_nearest<'a>(points: &'a [Point], query: &Point) -> &'a Point {
    fn cab_distance(p1: &Point, p2: &Point) -> i32 {
        (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
    }

    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }

    nearest.expect("at least one point expected").0
    // query // Что будет, если сделать вот так?
}

fn main() {
    let points = &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1)];
    let query = Point(0, 2);
    let nearest = find_nearest(points, &query);

    // `query` в этот момент не заимствуется.
    drop(query);

    dbg!(nearest);
}

Неявное выведение времени жизни

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

• Каждому аргументу, у которого нет аннотации времени жизни, присваивается отдельное время жизни.
• Если есть только одно время жизни аргумента, оно присваивается всем неаннотированным заимствованиям в возвращаемом типе.
• Если аргументов с временами жизни несколько, но первый из них — self, то его время жизни присваивается всем неаннотированным заимствованиям в возвращаемом типе.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn only_args(a: &i32, b: &i32) {
    todo!();
}

fn identity(a: &i32) -> &i32 {
    a
}

struct Foo(i32);
impl Foo {
    fn get(&self, other: &i32) -> &i32 {
        &self.0
    }
}

Времена жизни в структурах данных

Если тип данных хранит заимствованные данные, его нужно аннотировать временем жизни:

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
enum HighlightColor {
    Pink,
    Yellow,
}

#[derive(Debug)]
struct Highlight<'document> {
    slice: &'document str,
    color: HighlightColor,
}

fn main() {
    let doc = String::from("The quick brown fox jumps over the lazy dog.");
    let noun = Highlight { slice: &doc[16..19], color: HighlightColor::Yellow };
    let verb = Highlight { slice: &doc[20..25], color: HighlightColor::Pink };
    // drop(doc);
    dbg!(noun);
    dbg!(verb);
}

Упражнение: Разбор Protobuf

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

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

Мы будем использовать следующий proto:

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

Сообщения

Сообщение proto кодируется как последовательность полей, одно за другим. Каждое поле реализовано как «тег», за которым следует значение. Тег содержит номер поля (например, 2 для поля id сообщения Person) и тип передачи (wire type), определяющий, как по потоку байтов находить полезную нагрузку. Они объединяются в одно целое число, которое декодируется в unpack_tag ниже.

Varint

Целые числа, включая тег, представлены с помощью кодирования переменной длины, которое называется VARINT. К счастью, parse_varint уже определена ниже.

Типы передачи (Wire Types)

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

Тип передачи Varint содержит одно varint и используется для кодирования значений proto типа int32, например Person.id.

Тип передачи Len содержит длину, выраженную как varint, за которой следует полезная нагрузка из стольких байтов. Он используется для кодирования значений proto типа string, например Person.name. Также он используется для значений proto, содержащих вложенные сообщения, например Person.phones, где полезная нагрузка содержит кодирование вложенного сообщения.

Упражнение

Приведённый код также определяет обратные вызовы для обработки полей Person и PhoneNumber, а также для разбора сообщения на последовательность вызовов этих обратных вызовов.

От вас остаётся реализовать функцию parse_field и трейт ProtoMessage для Person и PhoneNumber.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Тип передачи в том виде, в котором он появляется в потоке.
enum WireType {
    /// Тип передачи Varint указывает, что значение --- одно VARINT.
    Varint,
    // Тип передачи I64 указывает, что значение --- ровно 8 байт в порядке
    // little-endian, содержащие 64-битное знаковое целое или значение типа double.
    //I64,  -- не нужно для этого упражнения
    /// Тип передачи Len указывает, что значение --- длина, представленная как
    /// VARINT, за которой следует ровно столько байтов.
    Len,
    // Тип передачи I32 указывает, что значение --- ровно 4 байта в порядке
    // little-endian, содержащие 32-битное знаковое целое или значение типа float.
    //I32,  -- не нужно для этого упражнения
}

#[derive(Debug)]
/// Значение поля, типизированное на основе типа передачи.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- не нужно для этого упражнения
    Len(&'a [u8]),
    //I32(i32),  -- не нужно для этого упражнения
}

#[derive(Debug)]
/// Поле, содержащее номер поля и его значение.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- не нужно для этого упражнения
            2 => WireType::Len,
            //5 => WireType::I32,  -- не нужно для этого упражнения
            _ => panic!("Invalid wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Expected string to be a `Len` field");
        };
        std::str::from_utf8(data).expect("Invalid string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Expected bytes to be a `Len` field");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Expected `u64` to be a `Varint` field");
        };
        *value
    }
}

/// Разбирает VARINT, возвращая разобранное значение и оставшиеся байты.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Not enough bytes for varint");
        };
        if b & 0x80 == 0 {
            // Это последний байт VARINT, поэтому преобразуем его в
            // u64 и вернём.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Более 7 байтов недопустимо.
    panic!("Too many bytes for varint");
}

/// Преобразует тег в номер поля и WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}


/// Разбирает поле, возвращая оставшиеся байты
fn parse_field(data: &[u8]) -> (Field<'_>, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("Based on the wire type, build a Field, consuming as many bytes as necessary.")
    };
    todo!("Return the field, and any un-consumed bytes.")
}

/// Разбирает сообщение в заданных данных, вызывая `T::add_field` для каждого поля в
/// сообщении.
///
/// Весь входной набор данных потребляется.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Реализуйте ProtoMessage для Person и PhoneNumber.

#[test]
fn test_id() {
    let person_id: Person = parse_message(&[0x10, 0x2a]);
    assert_eq!(person_id, Person { name: "", id: 42, phone: vec![] });
}

#[test]
fn test_name() {
    let person_name: Person = parse_message(&[
        0x0a, 0x0e, 0x62, 0x65, 0x61, 0x75, 0x74, 0x69, 0x66, 0x75, 0x6c, 0x20,
        0x6e, 0x61, 0x6d, 0x65,
    ]);
    assert_eq!(person_name, Person { name: "beautiful name", id: 0, phone: vec![] });
}

#[test]
fn test_just_person() {
    let person_name_id: Person =
        parse_message(&[0x0a, 0x04, 0x45, 0x76, 0x61, 0x6e, 0x10, 0x16]);
    assert_eq!(person_name_id, Person { name: "Evan", id: 22, phone: vec![] });
}

#[test]
fn test_phone() {
    let phone: Person = parse_message(&[
        0x0a, 0x00, 0x10, 0x00, 0x1a, 0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x33,
        0x34, 0x2d, 0x37, 0x37, 0x37, 0x2d, 0x39, 0x30, 0x39, 0x30, 0x12, 0x04,
        0x68, 0x6f, 0x6d, 0x65,
    ]);
    assert_eq!(
        phone,
        Person {
            name: "",
            id: 0,
            phone: vec![PhoneNumber { number: "+1234-777-9090", type_: "home" },],
        }
    );
}

// Соберите всё это в один разбор.
#[test]
fn test_full_person() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    assert_eq!(
        person,
        Person {
            name: "maxwell",
            id: 42,
            phone: vec![
                PhoneNumber { number: "+1202-555-1212", type_: "home" },
                PhoneNumber { number: "+1800-867-5308", type_: "mobile" },
            ]
        }
    );
}

Решение

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Тип передачи в том виде, в котором он появляется в потоке.
enum WireType {
    /// Тип передачи Varint указывает, что значение --- одно VARINT.
    Varint,
    // Тип передачи I64 указывает, что значение --- ровно 8 байт в порядке
    // little-endian, содержащие 64-битное знаковое целое или значение типа double.
    //I64,  -- не нужно для этого упражнения
    /// Тип передачи Len указывает, что значение --- длина, представленная как
    /// VARINT, за которой следует ровно столько байтов.
    Len,
    // Тип передачи I32 указывает, что значение --- ровно 4 байта в порядке
    // little-endian, содержащие 32-битное знаковое целое или значение типа float.
    //I32,  -- не нужно для этого упражнения
}

#[derive(Debug)]
/// Значение поля, типизированное на основе типа передачи.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- не нужно для этого упражнения
    Len(&'a [u8]),
    //I32(i32),  -- не нужно для этого упражнения
}

#[derive(Debug)]
/// Поле, содержащее номер поля и его значение.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- не нужно для этого упражнения
            2 => WireType::Len,
            //5 => WireType::I32,  -- не нужно для этого упражнения
            _ => panic!("Invalid wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Expected string to be a `Len` field");
        };
        std::str::from_utf8(data).expect("Invalid string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Expected bytes to be a `Len` field");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Expected `u64` to be a `Varint` field");
        };
        *value
    }
}

/// Разбирает VARINT, возвращая разобранное значение и оставшиеся байты.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Not enough bytes for varint");
        };
        if b & 0x80 == 0 {
            // Это последний байт VARINT, поэтому преобразуем его в
            // u64 и вернём.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Более 7 байтов недопустимо.
    panic!("Too many bytes for varint");
}

/// Преобразует тег в номер поля и WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}

/// Разбирает поле, возвращая оставшиеся байты
fn parse_field(data: &[u8]) -> (Field<'_>, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder);
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder);
            let len = len as usize; // приведение для простоты
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
    };
    (Field { field_num, value: fieldvalue }, remainder)
}

/// Разбирает сообщение в заданных данных, вызывая `T::add_field` для каждого поля в
/// сообщении.
///
/// Весь входной набор данных потребляется.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.name = field.value.as_str(),
            2 => self.id = field.value.as_u64(),
            3 => self.phone.push(parse_message(field.value.as_bytes())),
            _ => {} // пропускаем всё остальное
        }
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.number = field.value.as_str(),
            2 => self.type_ = field.value.as_str(),
            _ => {} // пропускаем всё остальное
        }
    }
}

#[test]
fn test_id() {
    let person_id: Person = parse_message(&[0x10, 0x2a]);
    assert_eq!(person_id, Person { name: "", id: 42, phone: vec![] });
}

#[test]
fn test_name() {
    let person_name: Person = parse_message(&[
        0x0a, 0x0e, 0x62, 0x65, 0x61, 0x75, 0x74, 0x69, 0x66, 0x75, 0x6c, 0x20,
        0x6e, 0x61, 0x6d, 0x65,
    ]);
    assert_eq!(person_name, Person { name: "beautiful name", id: 0, phone: vec![] });
}

#[test]
fn test_just_person() {
    let person_name_id: Person =
        parse_message(&[0x0a, 0x04, 0x45, 0x76, 0x61, 0x6e, 0x10, 0x16]);
    assert_eq!(person_name_id, Person { name: "Evan", id: 22, phone: vec![] });
}

#[test]
fn test_phone() {
    let phone: Person = parse_message(&[
        0x0a, 0x00, 0x10, 0x00, 0x1a, 0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x33,
        0x34, 0x2d, 0x37, 0x37, 0x37, 0x2d, 0x39, 0x30, 0x39, 0x30, 0x12, 0x04,
        0x68, 0x6f, 0x6d, 0x65,
    ]);
    assert_eq!(
        phone,
        Person {
            name: "",
            id: 0,
            phone: vec![PhoneNumber { number: "+1234-777-9090", type_: "home" },],
        }
    );
}

// Соберите всё это в один разбор.
#[test]
fn test_full_person() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    assert_eq!(
        person,
        Person {
            name: "maxwell",
            id: 42,
            phone: vec![
                PhoneNumber { number: "+1202-555-1212", type_: "home" },
                PhoneNumber { number: "+1800-867-5308", type_: "mobile" },
            ]
        }
    );
}

Добро пожаловать в День 4

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

• Основы и абстракции: трейты, обобщения и стандартная библиотека.
• Владение: семантика перемещения и трейт Drop.
• Управление памятью: правила заимствования (& и &mut) и времена жизни.
• Умные указатели: Box, Rc и RefCell для сложных структур данных.

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

Расписание

Включая 10-минутные перерывы, это занятие займёт около 2 часов 50 минут. Оно включает:

Итераторы

Этот сегмент займёт около 55 минут. Он включает:

Повторение: for

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    // Принимает диапазон.
    for x in 1..5 {
        dbg!(x);
    }

    // Также принимает массив.
    for elem in [2, 4, 8, 16, 32] {
        dbg!(elem);
    }
}

Зачем нужны итераторы

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

• Некоторое состояние, отслеживающее текущую позицию в процессе итерации, например индекс.
• Условие, определяющее, когда итерация завершена.
• Логику обновления состояния итерации на каждом шаге цикла.
• Логику получения каждого элемента с использованием этого состояния итерации.

В цикле for в стиле C вы объявляете эти вещи напрямую:

for (int i = 0; i < array_len; i += 1) {
    int elem = array[i];
}

В Rust мы объединяем это состояние и логику в объект, известный как «итератор».

for (int *ptr = array; ptr < array + len; ptr += 1) {
    int elem = *ptr;
}

Трейт Iterator

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct SliceIter<'s> {
    slice: &'s [i32],
    i: usize,
}

impl<'s> Iterator for SliceIter<'s> {
    type Item = &'s i32;

    fn next(&mut self) -> Option<Self::Item> {
        if self.i == self.slice.len() {
            None
        } else {
            let next = &self.slice[self.i];
            self.i += 1;
            Some(next)
        }
    }
}

fn main() {
    let slice = &[2, 4, 6, 8];
    let iter = SliceIter { slice, i: 0 };
    for elem in iter {
        dbg!(elem);
    }
}

Вспомогательные методы Iterator

Помимо метода next, который определяет поведение итератора, трейт Iterator предоставляет более 70 вспомогательных методов, с помощью которых можно строить настраиваемые итераторы.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let result: i32 = (1..=10) // Создаём диапазон от 1 до 10
        .filter(|x| x % 2 == 0) // Оставляем только чётные числа
        .map(|x| x * x) // Возводим каждое число в квадрат
        .sum(); // Суммируем все квадраты

    println!("The sum of squares of even numbers from 1 to 10 is: {}", result);
}

enumerate

Вспомогательный метод enumerate даёт нам способ получить индекс каждого элемента для любого итератора.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let array = ['a', 'b', 'c', 'd', 'e'];

    // По умолчанию перебор массива возвращает только его элементы.
    for letter in array {
        println!("The element is {letter:?}, but what's its index?");
    }

    // `enumerate` возвращает и элемент, и его индекс.
    for (i, letter) in array.iter().enumerate() {
        println!("{letter:?} has index {i}");
    }
}

collect

Метод collect позволяет построить коллекцию из Iterator.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

Трейт IntoIterator

Трейт Iterator говорит, как итерироваться, когда итератор уже создан. Связанный трейт IntoIterator определяет, как создать итератор для типа. Он используется автоматически циклом for.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };

    for (x, y) in grid {
        println!("point = {x}, {y}");
    }

    // dbg!(&grid.x_coords); // ❌ Сетка была потреблена циклом.
}

IntoIterator для ссылок

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl<'a> IntoIterator for &'a Grid {
    type Item = (&'a u32, &'a u32);
    type IntoIter = GridRefIter<'a>;
    fn into_iter(self) -> GridRefIter<'a> {
        GridRefIter { grid: self, i: 0, j: 0 }
    }
}

struct GridRefIter<'a> {
    grid: &'a Grid,
    i: usize,
    j: usize,
}

impl<'a> Iterator for GridRefIter<'a> {
    type Item = (&'a u32, &'a u32);

    fn next(&mut self) -> Option<Self::Item> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((&self.grid.x_coords[self.i], &self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };

    // Цикл может заимствовать сетку, не забирая владение.
    for (x, y) in &grid {
        println!("point = {x}, {y}");
    }

    // Сетка остаётся доступной после цикла.
    dbg!(&grid.x_coords);
}

Упражнение: Цепочка вычислений

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

Скопируйте следующий код на https://play.rust-lang.org/ и добейтесь прохождения тестов. Используйте выражение-итератор и collect, чтобы построить возвращаемое значение.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Вычисляет разности между элементами `values`, смещёнными на `offset`,
/// переходя от конца `values` к началу.
///
/// Элемент `n` результата равен `values[(n+offset)%len] - values[n]`.
fn offset_differences(offset: usize, values: Vec<i32>) -> Vec<i32> {
    todo!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Вычисляет разности между элементами `values`, смещёнными на `offset`,
/// переходя от конца `values` к началу.
///
/// Элемент `n` результата равен `values[(n+offset)%len] - values[n]`.
fn offset_differences(offset: usize, values: Vec<i32>) -> Vec<i32> {
    let a = values.iter();
    let b = values.iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

Модули

Этот сегмент займёт около 45 минут. Он включает:

Модули

Мы видели, как блоки impl позволяют задавать пространство имён функций для типа.

Аналогично mod позволяет задавать пространство имён типам и функциям:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

mod foo {
    pub fn do_something() {
        println!("In the foo module");
    }
}

mod bar {
    pub fn do_something() {
        println!("In the bar module");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

Дерево модулей

Если не писать содержимое модуля, Rust будет искать его в другом файле:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

mod garden;

Это сообщает Rust, что содержимое модуля garden находится в файле garden.rs в том же каталоге, что и файл, объявивший модуль. Если модуль garden аналогично объявляет подмодуль vegetables, его содержимое будет находиться в garden/vegetables.rs.

Корень крейта находится в:

• src/lib.rs (для библиотечного крейта)
• src/main.rs (для бинарного крейта)

Это отправная точка, с которой компилятор определяет дополнительные модули.

Модули, определённые в файлах, тоже можно документировать с помощью «внутренних doc-комментариев». Они документируют элемент, который их содержит, в данном случае — модуль.

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

//! Этот модуль реализует сад, включая высокопроизводительную
//! реализацию прорастания семян.

// Объявляем подмодули.
mod plant;
mod seeds;

// Реэкспортируем типы из этого модуля.
pub use plant::Plant;
pub use seeds::SeedPacket;

pub struct Garden {
    plants: Vec<Plant>,
}

/// Сеет заданные пакеты семян.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Собирает готовые к сбору овощи и фрукты в саду.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

Область видимости

Модули задают границу приватности:

• Элементы модуля по умолчанию приватные (это скрывает детали реализации).
• Родительские и соседние элементы всегда видимы.
• Иными словами, если элемент виден в модуле foo, он виден во всех потомках foo.

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

Видимость и инкапсуляция

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

use outer::Foo;

mod outer {
    pub struct Foo {
        pub val: i32,
        is_big: bool,
    }

    impl Foo {
        pub fn new(val: i32) -> Self {
            Self { val, is_big: val > 100 }
        }
    }

    pub mod inner {
        use super::Foo;

        pub fn print_foo(foo: &Foo) {
            println!("Is {} big? {}", foo.val, foo.is_big);
        }
    }
}

fn main() {
    let foo = Foo::new(42);
    println!("foo.val = {}", foo.val);
    // let foo = Foo { val: 42, is_big: true };

    outer::inner::print_foo(&foo);
    // println!("Is {} big? {}", foo.val, foo.is_big);
}

Использование use, super и self

Модуль может внести символы из другого модуля в область видимости с помощью use. Обычно в начале каждого модуля вы увидите что-то подобное:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::collections::HashSet;
use std::process::abort;

Пути

Пути разрешаются следующим образом:

1. Как относительный путь:

   • foo или self::foo ссылаются на foo в текущем модуле,
   • super::foo ссылается на foo в родительском модуле.

2. Как абсолютный путь:

   • crate::foo ссылается на foo в корне текущего крейта,
   • bar::foo ссылается на foo в крейте bar.

Упражнение: Реорганизация графической библиотеки

В этом упражнении вы реорганизуете небольшую реализацию библиотеки для GUI. Эта библиотека определяет трейт Widget, несколько его реализаций и функцию main.

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

Настройка Cargo

Playground Rust поддерживает только один файл, поэтому вам понадобится создать проект Cargo на локальной файловой системе:

cargo init gui-modules
cd gui-modules
cargo run

Отредактируйте полученный src/main.rs, добавив операторы mod, и создайте дополнительные файлы в каталоге src.

Исходный код

Вот реализация библиотеки GUI в одном модуле:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub trait Widget {
    /// Естественная ширина `self`.
    fn width(&self) -> usize;

    /// Отрисовать виджет в буфер.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Отрисовать виджет в стандартный вывод.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // Добавить 4 отступа для рамок
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: Измените draw_into, чтобы он возвращал Result<(), std::fmt::Error>. Затем используйте
        // оператор ? здесь вместо .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // добавим немного отступов
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(Button::new("Click me!")));
    window.draw();
}

Решение

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// ---- src/widgets.rs ----
pub use button::Button;
pub use label::Label;
pub use window::Window;

mod button;
mod label;
mod window;

pub trait Widget {
    /// Естественная ширина `self`.
    fn width(&self) -> usize;

    /// Отрисовать виджет в буфер.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Отрисовать виджет в стандартный вывод.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // добавим немного отступов
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: Window-width
        // Добавить 4 отступа для рамок
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: после изучения обработки ошибок вы можете изменить
        // draw_into так, чтобы он возвращал Result<(), std::fmt::Error>. Затем используйте
        // оператор ? здесь вместо .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// ---- src/main.rs ----
mod widgets;

use widgets::{Button, Label, Widget, Window};

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(Button::new("Click me!")));
    window.draw();
}

Тестирование

Этот сегмент займёт около 45 минут. Он включает:

Модульные тесты

Rust и Cargo поставляются с простым фреймворком модульных тестов. Тесты помечаются #[test]. Модульные тесты часто помещают во вложенный модуль tests и используют #[cfg(test)], чтобы компилировать их только при сборке тестов.

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty() {
        assert_eq!(first_word(""), "");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("Hello"), "Hello");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word(Привет, мир!), "Hello");
    }
}

• Это позволяет модульно тестировать приватные вспомогательные функции.
• Атрибут #[cfg(test)] активен только при запуске cargo test.

Интеграционные и прочие тесты

Интеграционные тесты

Если вы хотите протестировать библиотеку как клиент, используйте интеграционный тест.

Создайте файл .rs в каталоге tests/:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

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

Тесты документации

В Rust есть встроенная поддержка тестов документации:

#![allow(unused)]
fn main() {
// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Укорачивает строку до заданной длины.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• Блоки кода в комментариях /// автоматически воспринимаются как код Rust.
• Код будет скомпилирован и выполнен в рамках cargo test.
• Добавление # в код скроет его в документации, но код всё равно будет скомпилирован и выполнен.
• Проверьте приведённый выше код на Rust Playground.

Ошибки компиляции и Clippy

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let mut x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X probably fits in a u16, right? {}", x as u16);
}

Упражнение: Алгоритм Лу́на

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

• Игнорируйте все пробелы. Отвергайте числа, в которых меньше двух цифр. Отвергайте буквы и другие нецифровые символы.

• Двигаясь справа налево, удвойте каждую вторую цифру: для числа 1234 удваиваем 3 и 1. Для числа 98765 удваиваем 6 и 8.

• После удвоения цифры, если результат больше 9, сложите его цифры. Так удвоение 7 даёт 14, а затем 1 + 4 = 5.

• Сложите все неудвоенные и удвоенные цифры.

• Номер карты действителен, если сумма заканчивается на 0.

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

Скопируйте текст программы ниже в https://play.rust-lang.org/ и напишите дополнительные тесты, раскрывающие недочёты реализации. Исправьте все обнаруженные проблемы.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            // Новое: принимаем пробелы.
            continue;
        } else {
            // Новое: отвергаем все остальные символы.
            return false;
        }
    }

    // Новое: проверяем, что у нас есть хотя бы две цифры
    digits >= 2 && sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0"));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn(""));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

Добро пожаловать

Включая 10-минутные перерывы, это занятие займёт около 2 часов 20 минут. Оно включает:

Обработка ошибок

Этот сегмент займёт около 55 минут. Он включает:

Паники

В случае фатальной ошибки времени выполнения Rust вызывает «панику»:

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let v = vec![10, 20, 30];
    dbg!(v[100]);
}

• Паника предназначена для неисправимых и неожиданных ошибок.
  • Паника — симптом ошибки в программе.
  • Ошибки времени выполнения, например неудачная проверка границ, могут вызвать панику.
  • Утверждения (например, assert!) вызывают панику при неудаче.
  • Панику для конкретных случаев можно вызвать с помощью макроса panic!.
• Паника «раскручивает» стек (unwind), освобождая значения так же, как если бы функции вернули управление.
• Если аварийное завершение недопустимо, используйте API, которые не паникуют (например, Vec::get).

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "No problem here!");
    dbg!(result);

    let result = panic::catch_unwind(|| {
        panic!("oh no!");
    });
    dbg!(result);
}

Result

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

// Copyright 2022 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::fs::File;
use std::io::Read;

fn main() {
    let open_result: Result<File, std::io::Error> = File::open("diary.txt");
    match open_result {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Dear diary: {contents} ({bytes} bytes)");
            } else {
                println!("Could not read file content");
            }
        }
        Err(err) => {
            println!("The diary could not be opened: {err}");
        }
    }
}

Проброс ошибок

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

в гораздо более простую:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

some_expression?

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::Read;
use std::{fs, io};

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

Преобразования через Try

Фактическое раскрытие ? немного сложнее, чем показано ранее:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

expression?

работает так же, как

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

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

Пример

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::error::Error;
use std::io::Read;
use std::{fmt, fs, io};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername,
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername);
    }
    Ok(username)
}

fn main() {
    //std::fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

Совместимость типов ошибок

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

• Реализуйте трейт Error из стандартной библиотеки.
• Получите Debug через derive и реализуйте Display (это требуется для Error).
• Реализуйте преобразования From для базовых типов ошибок, чтобы поддержать автоматическое преобразование типов ошибок с помощью ?.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::error::Error;
use std::io::Read;
use std::{fmt, fs, io};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername,
}

impl Error for ReadUsernameError {}

impl fmt::Display for ReadUsernameError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "I/O error: {e}"),
            Self::EmptyUsername => write!(f, "Username file was empty"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

thiserror

Крейт thiserror предоставляет макросы, которые помогают избежать шаблонного кода при определении типов ошибок. Он предоставляет макросы derive, которые помогают реализовать From<T>, Display и трейт Error.

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::io::Read;
use std::{fs, io};
use thiserror::Error;

#[derive(Debug, Error)]
enum ReadUsernameError {
    #[error("I/O error: {0}")]
    IoError(#[from] io::Error),

    #[error("Found no username in {0}")]
    EmptyUsername(String),
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        Err(err) => println!("Error: {err}"),
    }
}

Динамические типы ошибок

Иногда нужно разрешить возвращать ошибку любого типа, не написав собственное перечисление, которое покрывает все возможности. Трейт std::error::Error упрощает создание объекта трейта, который может содержать любую ошибку.

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("Count: {count}"),
        Err(err) => println!("Error: {err}"),
    }
}

anyhow

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

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

// Copyright 2024 Google LLC
// SPDX-License-Identifier: Apache-2.0

use anyhow::{Context, Result, bail};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Found no username in {0}")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("Failed to open {path}"))?
        .read_to_string(&mut username)
        .context("Failed to read")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        Err(err) => println!("Error: {err}"),
    }
}

Упражнение: Замена на Result

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Операция, которую нужно выполнить над двумя подвыражениями.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Выражение в виде дерева.
#[derive(Debug)]
enum Expression {
    /// Операция над двумя подвыражениями.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Литеральное значение
    Value(i64),
}

#[derive(PartialEq, Eq, Debug)]
struct DivideByZeroError;

// Исходная реализация вычислителя выражений. Обновите её, чтобы
// возвращать `Result` и создавать ошибку при делении на 0.
fn eval(e: Expression) -> i64 {
    match e {
        Expression::Op { op, left, right } => {
            let left = eval(*left);
            let right = eval(*right);
            match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => if right != 0 {
                    left / right
                } else {
                    panic!("Cannot divide by zero!");
                },
            }
        }
        Expression::Value(v) => v,
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_error() {
        assert_eq!(
            eval(Expression::Op {
                op: Operation::Div,
                left: Box::new(Expression::Value(99)),
                right: Box::new(Expression::Value(0)),
            }),
            Err(DivideByZeroError)
        );
    }

    #[test]
    fn test_ok() {
        let expr = Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(20)),
            right: Box::new(Expression::Value(10)),
        };
        assert_eq!(eval(expr), Ok(10));
    }
}

Решение

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Операция, которую нужно выполнить над двумя подвыражениями.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Выражение в виде дерева.
#[derive(Debug)]
enum Expression {
    /// Операция над двумя подвыражениями.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Литеральное значение
    Value(i64),
}

#[derive(PartialEq, Eq, Debug)]
struct DivideByZeroError;

fn eval(e: Expression) -> Result<i64, DivideByZeroError> {
    match e {
        Expression::Op { op, left, right } => {
            let left = eval(*left)?;
            let right = eval(*right)?;
            Ok(match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => {
                    if right == 0 {
                        return Err(DivideByZeroError);
                    } else {
                        left / right
                    }
                }
            })
        }
        Expression::Value(v) => Ok(v),
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_error() {
        assert_eq!(
            eval(Expression::Op {
                op: Operation::Div,
                left: Box::new(Expression::Value(99)),
                right: Box::new(Expression::Value(0)),
            }),
            Err(DivideByZeroError)
        );
    }

    #[test]
    fn test_ok() {
        let expr = Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(20)),
            right: Box::new(Expression::Value(10)),
        };
        assert_eq!(eval(expr), Ok(10));
    }
}

• Тип возвращаемого значения Result: сигнатура функции меняется, чтобы возвращать Result<i64, DivideByZeroError>. Такая явная сигнатура типа заставляет вызывающий код обрабатывать возможность ошибки.
• Оператор ?: мы используем ? в рекурсивных вызовах: eval(*left)?. Это аккуратно передаёт ошибки дальше. Если eval возвращает Err, функция немедленно возвращает этот Err. Если возвращается Ok(v), v присваивается left (или right).
• Оборачивание в Ok: успешные результаты должны быть обёрнуты в Ok(...).
• Обработка деления на ноль: мы явно проверяем right == 0 и возвращаем Err(DivideByZeroError). Это заменяет панику из исходного кода.

Небезопасный код в Rust

Этот сегмент займёт около 1 часа 15 минут. Он включает:

Небезопасный код в Rust

В языке Rust есть две части:

• Безопасный Rust: безопасен для памяти, неопределённое поведение невозможно.
• Небезопасный Rust: может вызвать неопределённое поведение, если нарушены предусловия.

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

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

Небезопасный Rust даёт доступ к пяти новым возможностям:

• Разыменование сырых указателей.
• Доступ к изменяемым статическим переменным и их изменение.
• Доступ к полям union.
• Вызов unsafe функций, включая функции extern.
• Реализация unsafe трейтов.

Далее кратко рассмотрим возможности небезопасного Rust. Полные подробности см. в главе 19.1 The Rust Book и в Rustonomicon.

Разыменование сырых указателей

Создание указателей безопасно, но их разыменование требует unsafe:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

fn main() {
    let mut x = 10;

    let p1: *mut i32 = &raw mut x;
    let p2 = p1 as *const i32;

    // SAFETY: p1 и p2 созданы взятием сырых указателей на локальную переменную, поэтому
    // гарантированно не равны null, выровнены и указывают на один объект,
    // выделенный (на стеке).
    //
    // Объект, на который указывают сырые указатели, живёт всё время выполнения функции, поэтому
    // он не освобождается, пока существуют сырые указатели. Через ссылки к нему
    // не обращаются, пока существуют сырые указатели, и из других потоков одновременно к нему тоже не обращаются.
    unsafe {
        dbg!(*p1);
        *p1 = 6;
        // Изменение может корректно наблюдаться через сырой указатель, как в C.
        dbg!(*p2);
    }

    // НЕКОРРЕКТНО. НЕ ДЕЛАЙТЕ ТАК.
    /*
    let r: &i32 = unsafe { &*p1 };
    dbg!(r);
    x = 50;
    dbg!(r); // Объект, лежащий в основе ссылки, был изменён. Это UB.
    */
}

Изменяемые статические переменные

Безопасно читать неизменяемую статическую переменную:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

static HELLO_WORLD: &str = "Hello, world!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

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

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

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // SAFETY: Нет других потоков, которые могли бы обращаться к `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // SAFETY: Нет других потоков, которые могли бы обращаться к `COUNTER`.
    unsafe {
        dbg!(COUNTER);
    }
}

Объединения

Объединения похожи на перечисления, но активное поле нужно отслеживать самостоятельно:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // Неопределённое поведение!
}

Небезопасные функции

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

Небезопасные функции могут происходить из двух мест:

• Функции Rust, объявленные как unsafe.
• Небезопасные внешние функции в блоках extern "C".

Небезопасные функции Rust

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Меняет местами значения, на которые указывают заданные указатели.
///
/// # Safety
///
/// Указатели должны быть допустимыми, правильно выровненными и не должны иначе
/// использоваться на протяжении вызова функции.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    // SAFETY: Вызывающий код обещал, что указатели допустимы, правильно выровнены
    // и не имеют другого доступа.
    unsafe {
        let temp = *a;
        *a = *b;
        *b = temp;
    }
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // SAFETY: Указатели должны быть допустимыми, выровненными и уникальными, потому что они
    // получены из ссылок.
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Небезопасные внешние функции

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

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::ffi::c_char;

unsafe extern "C" {
    // `abs` не работает с указателями и не имеет требований безопасности.
    safe fn abs(input: i32) -> i32;

    /// # Safety
    ///
    /// `s` должен быть указателем на строку C, оканчивающуюся NUL, которая допустима и
    /// не изменяется на протяжении этого вызова функции.
    unsafe fn strlen(s: *const c_char) -> usize;
}

fn main() {
    println!("Absolute value of -3 according to C: {}", abs(-3));

    // SAFETY: Мы передаём указатель на строковый литерал C, который допустим на
    // протяжении всей работы программы.
    unsafe {
        println!("String length: {}", strlen(c"String".as_ptr()));
    }
}

Вызов небезопасных функций

Несоблюдение требований безопасности нарушает безопасность памяти!

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

#[derive(Debug)]
#[repr(C)]
struct KeyPair {
    pk: [u16; 4], // 8 байт
    sk: [u16; 4], // 8 байт
}

const PK_BYTE_LEN: usize = 8;

fn log_public_key(pk_ptr: *const u16) {
    let pk: &[u16] = unsafe { std::slice::from_raw_parts(pk_ptr, PK_BYTE_LEN) };
    println!("{pk:?}");
}

fn main() {
    let key_pair = KeyPair { pk: [1, 2, 3, 4], sk: [0, 0, 42, 0] };
    log_public_key(key_pair.pk.as_ptr());
}

Всегда добавляйте комментарий о безопасности (// SAFETY:) к каждому блоку unsafe. Он должен объяснять, почему код действительно безопасен. В этом примере комментарий о безопасности отсутствует, и код некорректен.

Реализация небезопасных трейтов

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

Например, в крейте zerocopy есть небезопасный трейт, который выглядит примерно так:

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0

use std::{mem, slice};

/// ...
/// # Safety
/// Тип должен иметь определённое представление и не содержать выравнивающих байтов (padding).
pub unsafe trait IntoBytes {
    fn as_bytes(&self) -> &[u8] {
        let len = mem::size_of_val(self);
        let slf: *const Self = self;
        unsafe { slice::from_raw_parts(slf.cast::<u8>(), len) }
    }
}

// SAFETY: `u32` имеет определённое представление и не содержит выравнивающих байтов (padding).
unsafe impl IntoBytes for u32 {}

Безопасная обёртка FFI

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

Вам понадобится обратиться к man-страницам:

• opendir(3)
• readdir(3)
• closedir(3)

Также стоит посмотреть модуль std::ffi. Там вы найдёте несколько строковых типов, которые нужны для упражнения: