Ласкаво просимо в Comprehensive Rust 🦀

Це безкоштовний курс Rust, розроблений командою Android у Google. Курс охоплює весь спектр Rust, від базового синтаксиса до складних тем, таких як узагальнення (generics) и обробка помилок.

Останню версію курсу можна знайти за адресою https://google.github.io/comprehensive-rust/. Якщо ви читаєте десь в іншому місці, перевіряйте там на оновлення.

Курс доступний на інших мовах. Виберіть потрібну мову у верхньому правому куті сторінки або перегляньте сторінку Переклади, щоб ознайомитися зі списком усіх доступних перекладів.

Курс також доступний у форматі PDF.

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

• Дати вам повне уявлення про синтаксис та семантику мови Rust.
• Навчити працювати з існуючим кодом та писати нові програми на Rust.
• Показати розповсюджені ідіоми мови Rust.

Перші чотири дні курсу ми називаємо Rust Fundamentals.

Спираючись на це, вам пропонується зануритися в одну або кілька спеціалізованих тем:

• Android: розрахований на половину дня курс з використання Rust для розробки на платформі Android (AOSP). Сюди входить взаємодія з C, C++ та Java.
• Chromium: розрахований на половину дня курс курс із використання Rust у браузерах на основі Chromium. Сюди входить взаємодія з C++ та як включити крейти сторонніх розробників у Chromium.
• Голе залізо: одноденне заняття з використання Rust для низькорівневої (embedded) розробки, що охоплює як мікроконтролери, так і звичайні процесори.
• Concurrency: повний день занять з вивчення конкурентності у Rust. Ми розглянемо як класичну конкурентність (витіснююча багатозадачність з використанням потоків і м'ютексів), так і async/await конкурентність (кооперативна багатозадачність з використанням futures).

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

Rust це об'ємна мова, і ми не зможемо охопити її за кілька днів. Теми, що виходять за межі курсу:

• Написання макросів, будь ласка подивіться Розділ 19.5 у The Rust Book та Rust by Example.

Припущення

Передбачається, що ви вже можете програмувати. Rust це статично типізована мова, і іноді ми порівнюватимемо і зіставлятимемо її з C та C++, щоб краще пояснити чи підкреслити різницю у підходах до написання коду на Rust.

Якщо ви знаєте, як програмувати мовою з динамічною типізацією, наприклад Python або JavaScript, ви зможете також успішно пройти цей курс.

Проведення курсу

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

Ось коротка довідкова інформація про те, як ми проводили цей курс всередині Google.

Зазвичай ми проводимо заняття з 9:00 до 16:00, з 1-годинною перервою на обід посередині. Це залишає 3 години для ранкового заняття та 3 години для післяобіднього заняття. Обидві сесії містять кілька перерв і час для роботи студентів над вправами.

Перед проведенням курсу бажано:

1. Ознайомитись з матеріалами курсу. Ми додали нотатки для викладача на деяких сторінках, щоб виділити ключові моменти (будь ласка, допомагайте нам, додаючи свої нотатки для викладачів!). Під час презентації переконайтеся, що відкрили нотатки для викладача у спливаючому вікні (натисніть на посилання з маленькою стрілкою поруч з "Нотатки для викладача"). Таким чином ви матимете чистий екран, який можна представити класу.

2. Визначитись з датами. Оскільки курс вимагає щонайменше чотири дні, ми рекомендуємо вам запланувати ці дні протягом двох тижнів. Учасники курсу сказали, що вони вважають корисним наявність прогалин у курсі, оскільки це допомагає їм обробити всю інформацію, яку ми їм надаємо.

3. Знайти приміщення досить просторе для очної участі. Ми рекомендуємо, щоб у класі було 15-20 чоловік. Це досить небагато для того, щоб людям було комфортно ставити запитання --- також достатньо мало, щоб один інструктор мав час відповісти на запитання. Переконайтеся, що в кімнаті є парти для вас і для студентів: ви всі повинні мати можливість сидіти і працювати за своїми ноутбуками. Зокрема, ви будете виконувати багато програмування в реальному часі як інструктор, тому кафедра вам не дуже допоможе.

4. У день заняття приходьте в кімнату трохи раніше, щоби все підготувати. Ми рекомендуємо презентувати безпосередньо за допомогою mdbook serve, запущеного на вашому ноутбуці (дивиться installation instructions). Це забезпечує оптимальну продуктивність без затримок під час зміни сторінок. Використання ноутбука також дозволить вам виправляти друкарські помилки в міру їх виявлення вами або учасниками курсу.

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

На цьому все, удачі у проходженні курсу! Ми сподіваємося, що вам буде так само весело, як і нам!

Будь ласка, залишіть відгук, щоб ми могли продовжувати удосконалювати курс. Ми хотіли б почути, що було добре і що можна зробити краще. Ваші студенти також можуть надіслати нам свої відгуки!

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

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

Основи Rust

Перші чотири дні складають Основи Rust. Дні протікають швидко, і ми багато робимо!

Course schedule:

• Day 1 Morning (2 hours and 5 minutes, including breaks)

• Day 1 Afternoon (2 hours and 35 minutes, including breaks)

• Day 2 Morning (2 hours and 10 minutes, including breaks)

• Day 2 Afternoon (3 hours and 15 minutes, including breaks)

• Day 3 Morning (2 hours and 20 minutes, including breaks)

• Day 3 Afternoon (1 hour and 55 minutes, including breaks)

• Day 4 Morning (2 hours and 40 minutes, including breaks)

• Day 4 Afternoon (2 hours and 20 minutes, including breaks)

Глибоке занурення

На додаток до 4-денного курсу з основ Rust, ми розглянемо ще кілька спеціалізованих тем:

Rust в Android

Rust в Android --- це напівденний курс з використання Rust для розробки на Android платформі. Сюди входить взаємодія з C, C++ та Java.

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

Переконайтеся, що adb sync працює з вашим емулятором або реальним пристроєм, та попередньо зберіть усі приклади Android, використовуючи src/android/build_all.sh. Прочитайте скрипт, щоб побачити команди, які він запускає, і переконайтеся, що вони працюють, коли ви запускаєте їх вручну.

Rust в Chromium

Глибоке занурення Rust in Chromium — це південний курс із використання Rust як частини браузера Chromium. Він включає використання Rust у системі збирання gn Chromium, залучення сторонніх бібліотек ("крейтів") і взаємодію з C++.

Вам потрібно буде мати можливість зібрати Chromium --- налагодженна, компонентна побудова рекомендується для швидкості, але будь-яка збірка буде працювати. Переконайтеся, що ви можете запустити веб-переглядач Chromium, який ви побудували.

Rust на голому залізі

Rust на голому залізі: заняття на повний день з використання Rust для низькорівневої (embedded) розробки. Розглядаються як мікроконтролери, так і прикладні процесори.

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

Конкурентність в Rust

Конкурентність в Rust це цілий день занять з класичної, а також async/await конкурентності.

Вам знадобиться налаштований новий крейт, а також завантажені залежності готові до роботи. Потім ви сможете скопіювати приклади в src/main.rs, щоб поекспериментувати з ними:

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

Course schedule:

• Morning (3 hours and 20 minutes, including breaks)

• Afternoon (3 hours and 20 minutes, including breaks)

Формат

Курс задуманий дуже інтерактивним, і ми рекомендуємо, щоб питання сприяли вивченню Rust!

Гарячі клавіші

У mdBook є кілька корисних поєднань клавіш:

• Стрілка вліво: Перехід на попередню сторінку.
• Стрілка вправо: Перехід до наступної сторінки.
• Ctrl + Enter: Виконати приклад коду, який знаходиться у фокусі.
• s: Активувати панель пошуку.

Переклади

Курс був перекладений іншими мовами групою чудових волонтерів:

• Бразильска Португальська від @rastringer, @hugojacob, @joaovicmendes, та @henrif75.
• Chinese (Simplified) by @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK, and @nodmp.
• Китайська (традиційна) від @hueich, @victorhsieh, @mingyc, @kuanhungchen, and @johnathan79717.
• Японьска від @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi і @kantasv.
• Корейска від @keispace, @jiyongp, @jooyunghan та @namhyung.
• Іспанська від @deavid.
• Українська від @git-user-cpp, @yaremam і @reta.

Використовуйте кнопку вибору мови у верхньому правому куті для перемикання між мовами.

Незавершені переклади

Існує велика кількість незавершених перекладів. Ми посилаємося на останні оновлені переклади:

• Арабська від @younies.
• Бенгальська від @raselmandol.
• Фарсі від @Alix1383, @DannyRavi, @hamidrezakp, @javad-jafari і @moaminsharifi.
• Французька від @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.

Блоки коду в цьому курсі є повністю інтерактивними:

fn main() {
    println!("Відредагуте мене!");
}

Ви можете використовувати 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 схожим на

   fn main() {
       println!("Відредагуте мене!");
   }

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 Fundamentals. Сьогодні ми розглянемо багато питань:

• Базовий синтаксис Rust: змінні, скалярні та складені типи, переліки, структури, посилання, функції та методи.
• Типи та виведення типів.
• Конструкції потоку управління: цикли, умовні переходи і так далі.
• Типи, визначені користувачем: структури та переліки.
• Зіставлення шаблонів: деструктуризація переліків, структур і масивів.

Розклад

Including 10 minute breaks, this session should take about 2 hours and 5 minutes. It contains:

Hello World!

This segment should take about 15 minutes. It contains:

Що таке Rust?

Rust — це нова мова програмування, яка мала 1.0 випуск у 2015 році:

• Rust — це статично скомпільована мова, яка виконує таку саму роль, як C++
  • rustc використовує LLVM як бекенд.
• Rust підтримує багато платформ і архітектур:
  • x86, ARM, WebAssembly, ...
  • Linux, Mac, Windows, ...
• Rust використовується для широкого спектру пристроїв:
  • прошивки та завантажувачі,
  • розумні дисплеї,
  • мобільні телефони,
  • робочі станції,
  • сервери.

Переваги Rust

Деякі унікальні переваги Rust:

• Безпека пам'яті під час компіляції - цілі класи помилок пам'яті запобігаються на етапі компіляції

  • Немає неініціалізованих змінних.
  • Ніяких подвійних звільнень.
  • Немає використання після звільнення.
  • Немає вказівників NULL.
  • Немає забутих заблокованих м'ютексів.
  • Немає перегонів даних між потоками.
  • Немає недійсності ітератора.

• Ніякої невизначеної поведінки під час виконання - те, що робить оператор Rust, ніколи не залишається невизначеним

  • Доступ до масиву перевірено на межі.
  • Поведінка цілочисельного переповнення визначена (паніка або обертання).

• Можливості сучасної мови - така ж виразна та ергономічна, як і мови вищих рівнів

  • Переліки та зіставлення шаблонів.
  • Узагальнені типи.
  • FFI без накладних витрат.
  • Абстракції без витрат.
  • Чудово деталізовані помилки компілятора.
  • Вбудований менеджер залежностей.
  • Вбудована підтримка тестування.
  • Чудова підтримка протоколу мовного сервера (LSP).

Ігровий майданчик

Rust Playground надає простий спосіб виконання коротких Rust-програм і є основою для прикладів і вправ у цьому курсі. Спробуйте запустити програму "hello-world", з якої він починається. Вона має декілька зручних можливостей:

• У розділі "Інструменти" скористайтеся опцією rustfmt для форматування вашого коду у "стандартний" спосіб.

• Rust має два основних "профілі" для генерації коду: Налагодження (додаткові перевірки під час виконання, менше оптимізації) та Випуску (менше перевірок під час виконання, багато оптимізацій). Вони доступні у розділі "Налагодження" у верхній частині вікна.

• Якщо вам цікаво, скористайтеся командою "ASM" в "...", щоб переглянути згенерований асемблерний код.

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

This segment should take about 40 minutes. It contains:

Hello World!

Перейдемо до найпростішої програми Rust, класичної програми Hello World:

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

Що ви бачите:

• Функції вводяться за допомогою fn.
• Блоки розділені фігурними дужками, як у C і C++.
• Функція main є точкою входу в програму.
• Rust має гігієнічні макроси, println! є прикладом цього.
• Рядки в Rust мають кодування UTF-8 і можуть містити будь-які символи Unicode.

Змінні

Rust забезпечує безпеку типів за допомогою статичної типізації. Прив'язки змінних створюються за допомогою let:

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

Значення

Нижче наведено деякі основні вбудовані типи та синтаксис для літеральних значень кожного типу.

Типи мають наступну ширину:

• iN, uN і fN мають ширину N біт,
• isize і usize – це ширина вказівника,
• char має ширину 32 біти,
• bool має ширину 8 біт.

Арифметика

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

fn main() {
    println!("результат: {}", interproduct(120, 100, 248));
}

Виведення типів

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

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

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ПОМИЛКА: немає реалізації для `{float} == {integer}`
}

Вправа: Фібоначчі

Послідовність Фібоначчі починається з [0,1]. Для n>1 n-те число Фібоначчі обчислюється рекурсивно як сума n-1-го та n-2-го чисел Фібоначчі.

Напишіть функцію fib(n), яка обчислює n-те число Фібоначчі. Коли ця функція запанікує?

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

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

Рішення

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

Основи потоку керування

This segment should take about 40 minutes. It contains:

Вирази if

Ви використовуєте вирази if так само, як і вирази if в інших мовах:

fn main() {
    let x = 10;
    if x == 0 {
        println!("нуль!");
    } else if x < 100 {
        println!("великий");
    } else {
        println!("величезний");
    }
}

Крім того, ви можете використовувати if як вираз. Останній вираз кожного блоку стає значенням виразу if:

fn main() {
    let x = 10;
    let size = if x < 20 { "маленький" } else { "великий" };
    println!("розмір числа: {}", size);
}

Цикли

У Rust є три ключові слова циклу: while, loop і for:

while

Ключове слово while працює так само, як і в інших мовах, виконуючи тіло циклу доти, доки умова виконується.

fn main() {
    let mut x = 200;
    while x >= 10 {
        x = x / 2;
    }
    println!("Final x: {x}");
}

for

Цикл for виконує ітерації над діапазонами значень або елементами колекції:

fn main() {
    for x in 1..5 {
        println!("x: {x}");
    }

    for elem in [1, 2, 3, 4, 5] {
        println!("elem: {elem}");
    }
}

loop

Оператор loop просто повторюється до нескінченності, поки не трапиться break.

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

break та continue

Якщо ви хочете негайно почати наступну ітерацію, використовуйте continue.

Якщо ви хочете достроково вийти з будь-якого типу циклу, використовуйте break. З loop це може бути необов'язковий вираз, який стане значенням виразу loop.

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

Мітки

І continue, і break можуть додатково приймати аргумент мітки, який використовується для виходу з вкладених циклів:

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;
            }
        }
    }
    print!("елементів переглянуто: {elements_searched}");
}

Блоки та області застосування

Блоки

Блок у Rust містить послідовність виразів, взятих у фігурні дужки {}. Кожен блок має значення і тип, які відповідають значенню і типу останнього виразу в блоці:

fn main() {
    let z = 13;
    let x = {
        let y = 10;
        println!("y: {y}");
        z - y
    };
    println!("x: {x}");
}

Якщо останній вираз закінчується символом ;, то результуюче значення і тип буде ().

Області видимості та затінення

Область видимості змінної обмежується блоком, що її охоплює.

Ви можете затіняти змінні, як із зовнішніх областей, так і змінні з тієї ж області:

fn main() {
    let a = 10;
    println!("до: {a}");
    {
        let a = "привіт";
        println!("внутрішня область видимості: {a}");

        let a = true;
        println!("затінений у внутрішній області видимості: {a}");
    }

    println!("після: {a}");
}

Функції

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

fn main() {
    println!("gcd: {}", gcd(143, 52));
}

Макроси

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

• println!(format, ..) виводить рядок у стандартний вивід, застосовуючи форматування, описане у std::fmt.
• format!(format, ..) працює так само, як println!, але повертає результат у вигляді рядка.
• dbg!(вираз) записує значення виразу і повертає його.
• todo!() позначає частину коду як таку, що ще не виконана. Якщо цей код буде виконано, він викличе паніку.
• unreachable!() позначає ділянку коду як недосяжну. Якщо цей код буде виконано, він викличе паніку.

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.

/// Визначте довжину послідовності колатів, яка починається з `n`.
fn collatz_length(mut n: i32) -> u32 {
  todo!("Реалізуйте це")
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Довжина: {}", collatz_length(11));
}

Рішення

/// Визначте довжину послідовності колатів, яка починається з `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
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Довжина: {}", collatz_length(11));
}

Ласкаво просимо назад

Including 10 minute breaks, this session should take about 2 hours and 35 minutes. It contains:

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

This segment should take about 35 minutes. It contains:

Масиви

fn main() {
    let mut a: [i8; 10] = [42; 10];
    a[5] = 0;
    println!("a: {a:?}");
}

Кортежі

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

Ітерація масиву

Оператор for підтримує ітерацію над масивами (але не кортежами).

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

Патерни та деструктуризація

При роботі з кортежами та іншими структурованими значеннями часто виникає потреба витягти внутрішні значення у локальні змінні. Це можна зробити вручну шляхом прямого доступу до внутрішніх значень:

fn print_tuple(tuple: (i32, i32)) {
    let left = tuple.0;
    let right = tuple.1;
    println!("left: {left}, right: {right}");
}

Однак, Rust також підтримує використання зіставлення шаблонів для розбиття більшого значення на складові частини:

fn print_tuple(tuple: (i32, i32)) {
    let (left, right) = tuple;
    println!("left: {left}, right: {right}");
}

Вправа: Вкладені масиви

Масиви можуть містити інші масиви:

#![allow(unused)]
fn main() {
let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
}

Який тип цієї змінної?

Використовуйте масив, подібний до наведеного вище, для написання функції transpose, яка транспонує матрицю (перетворює рядки у стовпці):

Скопіюйте наведений нижче код на https://play.rust-lang.org/ і реалізуйте функцію. Ця функція працює лише з матрицями 3x3.

// TODO: видаліть це, коли закінчите реалізацію.
#![allow(unused_variables, dead_code)]

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

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- коментар змушує rustfmt додати новий рядок
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("матриця: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("транспонована: {:#?}", transposed);
}

Рішення

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
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- коментар змушує rustfmt додати новий рядок
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("матриця: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("транспонована: {:#?}", transposed);
}

Посилання

This segment should take about 55 minutes. It contains:

Спільні посилання

Посилання забезпечує доступ до іншого значення без отримання права власності на нього, і також називається "запозиченням". Спільні посилання доступні лише для читання, і дані, на які вони посилаються, не можуть бути змінені.

fn main() {
    let a = 'A';
    let b = 'B';
    let mut r: &char = &a;
    println!("r: {}", *r);
    r = &b;
    println!("r: {}", *r);
}

Спільне посилання на тип T має тип &T. Значення посилання робиться за допомогою оператора &. Оператор * "розіменовує" посилання, повертаючи його значення.

Rust статично забороняє висячі посилання:

fn x_axis(x: &i32) -> &(i32, i32) {
    let point = (*x, 0);
    return &point;
}

Ексклюзивні посилання

Ексклюзивні посилання, також відомі як мутабельні посилання, дозволяють змінювати значення, на яке вони посилаються. Вони мають тип &mut T.

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

Зрізи

Зріз дає змогу поглянути на більшу колекцію:

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

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• Зрізи запозичують дані зі зрізаного типу.

Рядки

Тепер ми можемо зрозуміти два типи рядків у Rust:

• &str is a slice of UTF-8 encoded bytes, similar to &[u8].
• String is an owned buffer of UTF-8 encoded bytes, similar to Vec<T>.

fn main() {
    let s1: &str = "Світ";
    println!("s1: {s1}");

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

    let s3: &str = &s2[s2.len() - s1.len()..];
    println!("s3: {s3}");
}

Вправа: Геометрія

Ми створимо декілька утиліт для тривимірної геометрії, що представляють точку у вигляді [f64;3]. Ви самі визначаєте сигнатури функцій.

// Обчисліть величину вектора шляхом додавання квадратів його координат
// і вилучення квадратного кореня. Використовуйте метод `qrt()` для для обчислення квадратного
// кореня, наприклад `v.sqrt()`.


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

// Нормалізуйте вектор, обчисливши його величину і поділивши всі його
// координати на цю величину.


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

Використовуйте наступний `main` для тестування вашої роботи.

fn main() {
    println!("Величина одиничного вектора: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Величина {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Величина {v:?} після нормалізації: {}", magnitude(&v));
}

Рішення

/// Обчисліть величину заданого вектора.
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(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Величина {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Величина {v:?} після нормалізації: {}", magnitude(&v));
}

Типи, які визначаються користувачем

This segment should take about 50 minutes. It contains:

Іменовані структури

Подібно до C і C++, Rust підтримує користувальницькі структури:

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

fn describe(person: &Person) {
    println!("{} віком {} років", 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);

    let jackie = Person { name: String::from("Jackie"), ..avery };
    describe(&jackie);
}

Кортежні структури

Якщо імена полів неважливі, ви можете використати структуру кортежу:

struct Point(i32, i32);

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

Це часто використовується для обгорток з одним полем (так званих newtypes):

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

fn compute_thruster_force() -> PoundsOfForce {
    todo!("Запитайте вченого-ракетника з NASA")
}

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

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

Перелічувані типи

Ключове слово enum дозволяє створити тип, який має кілька різних варіантів:

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

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

fn main() {
    let m: PlayerMove = PlayerMove::Run(Direction::Left);
    println!("На цьому повороті: {:?}", m);
}

const

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

const DIGEST_SIZE: usize = 3;
const ZERO: Option<u8> = Some(42);

fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {
    let mut digest = [ZERO.unwrap_or(0); 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:?}");
}

Відповідно до Книги Rust RFC вони підставляються під час використання.

Лише функції з позначкою const можна викликати під час компіляції для створення значень const. Однак функції const можна викликати під час виконання.

static

Статичні змінні будуть жити протягом усього часу виконання програми, тому не будуть переміщатися:

static BANNER: &str = "Ласкаво просимо до RustOS 3.14";

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

Як зазначено в Книзі Rust RFC, вони не підставляються під час використання та мають реальну асоційовану ділянку пам'яті. Це корисно для небезпечного та вбудованого коду, і змінна живе протягом усього виконання програми. Якщо значення глобальної області видимості не потребує ідентичності об’єкта, перевага надається const.

Псевдоніми типу

Псевдонім типу створює ім'я для іншого типу. Ці два типи можна використовувати взаємозамінно.

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// Псевдоніми більш корисні для довгих, складних типів:
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

Вправа: події в ліфті

Ми створимо структуру даних для представлення події в системі керування ліфтом. Ви самі визначаєте типи та функції для створення різних подій. Використовуйте #[derive(Debug)], щоб дозволити форматування типів за допомогою {:?}.

У цій вправі потрібно лише створити і заповнити структури даних так, щоб main працював без помилок. Наступна частина курсу буде присвячена отриманню даних з цих структур.

#[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!(
        "Пасажир першого поверху натиснув кнопку вгору: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("Кабіна ліфта заїхала на перший поверх: {:?}", car_arrived(0));
    println!("Двері у кабіні ліфта відчинилися: {:?}", car_door_opened());
    println!(
        "Пасажир натиснув кнопку 3-го поверху: {:?}",
        car_floor_button_pressed(3)
    );
    println!("Двері у кабіні ліфта зачинилися: {:?}", car_door_closed());
    println!("Кабіна ліфта заїхала на 3-й поверх: {:?}", car_arrived(3));
}

Рішення

#[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!(
        "Пасажир першого поверху натиснув кнопку вгору: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("Кабіна ліфта заїхала на перший поверх: {:?}", car_arrived(0));
    println!("Двері у кабіні ліфта відчинилися: {:?}", car_door_opened());
    println!(
        "Пасажир натиснув кнопку 3-го поверху: {:?}",
        car_floor_button_pressed(3)
    );
    println!("Двері у кабіні ліфта зачинилися: {:?}", car_door_closed());
    println!("Кабіна ліфта заїхала на 3-й поверх: {:?}", car_arrived(3));
}

Ласкаво просимо до Дня 2

Тепер, коли ми побачили достатню кількість Rust, ми зосередимося на системі типів Rust:

• Зіставлення шаблонів: вилучення даних зі структур.
• Методи: зв'язування функцій з типами.
• Трэйти: поведінка, спільна для кількох типів
• Узагальнення: параметризація типів в інших типах.
• Типи та властивості стандартної бібліотеки: екскурсія по багатій стандартній бібліотеці Rust.

Розклад

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

Зіставлення зразків

This segment should take about 1 hour. It contains:

Співставлення значень

Ключове слово match дозволяє зіставити значення з одним або декількома шаблонами. Порівняння відбуваються зверху вниз, і виграє перший збіг.

Шаблони можуть бути простими значеннями, подібно до switch у C та C++:

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("Виходжу"),
        'a' | 's' | 'w' | 'd'     => println!("Пересування"),
        '0'..='9'                 => println!("Введення числа"),
        key if key.is_lowercase() => println!("Нижній регістр: {key}"),
        _                         => println!("Щось інше"),
    }
}

Шаблон _ - це шаблон підстановки, який відповідає будь-якому значенню. Вирази повинні бути вичерпними, тобто охоплювати всі можливі варіанти, тому _ часто використовується як остаточний всеохоплюючий випадок.

Match можна використовувати як вираз. Як і у випадку з if, кожна гілка зіставлення повинно мати однаковий тип. Тип - це останній вираз у блоці, якщо такий є. У наведеному вище прикладі тип ().

Змінна у шаблоні (у цьому прикладі - key) створить прив'язку, яку можна використовувати у гілці зіставлення.

Запобіжник зіставлення призводить до гілці зіставлення, тільки якщо умова істинна.

Структури

Як і кортежі, структури також можуть бути деструктуровані шляхом зіставлення:

struct Foo {
    x: (u32, u32),
    y: u32,
}

#[rustfmt::skip]
fn main() {
    let foo = Foo { x: (1, 2), y: 3 };
    match foo {
        Foo { x: (1, b), y } => println!("x.0 = 1, b = {b}, y = {y}"),
        Foo { y: 2, x: i }   => println!("y = 2, x = {i:?}"),
        Foo { y, .. }        => println!("y = {y}, інші поля були проігноровані"),
    }
}

Перелічувані типи

Як і кортежі, переліки також можуть бути деструктуровані шляхом зіставлення:

Шаблони також можна використовувати для прив’язки змінних до частин ваших значень. Таким чином ви перевіряєте структуру ваших типів. Давайте розпочнемо з простого типу enum:

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!("не можна поділити {n} на дві рівні частини"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} поділена навпіл, це {half}"),
        Result::Err(msg) => println!("вибачте, сталася помилка: {msg}"),
    }
}

Тут ми використали гілки для деструктурування значення Result. У першій гілці half прив'язано до значення всередині варіанту Ok. У другій гілці msg прив'язано до повідомлення про помилку.

Потік контролю Let

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

• вирази if let
• вирази let else
• вирази while let

вирази if let

Вираз if let дозволяє виконувати інший код залежно від того, чи відповідає значення шаблону :

use std::time::Duration;

fn sleep_for(secs: f32) {
    if let Ok(dur) = Duration::try_from_secs_f32(secs) {
        std::thread::sleep(dur);
        println!("проспав {:?}", dur);
    }
}

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

вирази let else

Для загального випадку зіставлення шаблону і повернення з функції використовуйте let else. Випадок "else" повинен відрізнятися (return, break або паніка - що завгодно, але не випадання з кінця блоку).

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    if let Some(s) = maybe_string {
        if let Some(first_byte_char) = s.chars().next() {
            if let Some(digit) = first_byte_char.to_digit(16) {
                Ok(digit)
            } else {
                return Err(String::from("не шістнадцяткова цифра"));
            }
        } else {
            return Err(String::from("отримав порожній рядок"));
        }
    } else {
        return Err(String::from("отримав None"));
    }
}

fn main() {
    println!("результат: {:?}", hex_or_die_trying(Some(String::from("foo"))));
}

Подібно до if let, існує варіант while let, який багаторазово перевіряє значення на відповідність шаблону:

fn main() {
    let mut name = String::from("Comprehensive Rust 🦀");
    while let Some(c) = name.pop() {
        println!("character: {c}");
    }
    // (There are more efficient ways to reverse a string!)
}

Тут String::pop повертає Some(c) поки рядок не стане порожнім, після чого поверне None. Використання while let дозволяє нам продовжувати ітерацію по всіх елементах.

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("отримав None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("отримав порожній рядок"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("не шістнадцяткова цифра"));
    };

    return Ok(digit);
}
}

Вправа: обчислення виразу

Давайте напишемо простий рекурсивний обчислювач арифметичних виразів.

Тип Box тут є розумним вказівником і буде детально розглянутий пізніше у курсі. Вираз може бути "упаковано" за допомогою Box::new, як показано у тестах. Щоб обчислити вираз, використайте оператор розіменування (*), щоб "розпакувати" його: eval(*boxed_expr).

Деякі вирази не можуть бути обчислені і повертають помилку. Стандартний тип Result<Value, String> - це перелік, який представляє або успішне значення (Ok(Value)), або помилку (Err(String)). Ми розглянемо цей тип більш детально пізніше.

Скопіюйте та вставте код у середовище Rust і почніть реалізацію eval. Кінцевий продукт повинен пройти тести. Може бути корисно використати todo!() і змусити тести проходити один за одним. Ви також можете тимчасово оминути тест за допомогою #[ignore]:

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

Якщо ви закінчили раніше, спробуйте написати тест, який призводить до ділення на нуль або цілочисельного переповнення. Як ви могли б впоратися з цим за допомогою Result замість того, щоб панікувати?

#![allow(unused)]
fn main() {
/// Операція для виконання над двома під-виразами.
#[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) -> Result<i64, String> {
    todo!()
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(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)),
        }),
        Ok(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),
        }),
        Ok(85)
    );
}

#[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(String::from("ділення на нуль"))
    );
}
}

Рішення

/// Операція для виконання над двома під-виразами.
#[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) -> Result<i64, String> {
    match e {
        Expression::Op { op, left, right } => {
            let left = match eval(*left) {
                Ok(v) => v,
                Err(e) => return Err(e),
            };
            let right = match eval(*right) {
                Ok(v) => v,
                Err(e) => return Err(e),
            };
            Ok(match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => {
                    if right == 0 {
                        return Err(String::from("ділення на нуль"));
                    } else {
                        left / right
                    }
                }
            })
        }
        Expression::Value(v) => Ok(v),
    }
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(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)),
        }),
        Ok(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),
        }),
        Ok(85)
    );
}

#[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(String::from("ділення на нуль"))
    );
}

fn main() {
    let expr = Expression::Op {
        op: Operation::Sub,
        left: Box::new(Expression::Value(20)),
        right: Box::new(Expression::Value(10)),
    };
    println!("expr: {:?}", expr);
    println!("результат: {:?}", eval(expr));
}

Методи та Трейти

This segment should take about 50 minutes. It contains:

Методи

Rust дозволяє пов’язувати функції з новими типами. Ви робите це за допомогою блоку impl:

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

impl Race {
    // Немає отримувача, статичний метод
    fn new(name: &str) -> Self {
        Self { name: String::from(name), laps: Vec::new() }
    }

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

    // Спільний та запозичений доступ тільки на читання до себе
    fn print_laps(&self) {
        println!("Записано {} кіл для {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Коло {idx}: {lap} sec");
        }
    }

    // Виключне володіння собою
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("Гонка {} завершена, загальний час проходження кола: {}", self.name, total);
    }
}

fn main() {
    let mut race = Race::new("Гран-прі Монако");
    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 визначають "отримувача" - об'єкт, на який діє метод. Існує декілька типових отримувачів для методу:

• &self: запозичує об’єкт у викликувача за допомогою спільного та незмінного посилання. Після цього об’єкт можна використовувати знову.
• &mut self: запозичує об’єкт у викликувача, використовуючи унікальне та мутабельне посилання. Після цього об’єкт можна використовувати знову.
• self: приймає право власності на об'єкт і переміщує його від викликувача. Метод стає власником об'єкта. Об’єкт буде видалено (звільнено), коли метод завершиться, якщо володіння їм не передано явно. Повне володіння не означає автоматичної мутабельності.
• mut self: те саме, що й вище, але метод може змінювати об’єкт.
• Немає отримувача: це стає статичним методом у структурі. Зазвичай використовується для створення конструкторів, які за домовленістю називаються new.

Трейти

Rust дозволяє абстрагування над типами за допомогою трейтів. Вони схожі на інтерфейси:

trait Pet {
    /// Повертає речення від цього вихованця.
    fn talk(&self) -> String;

    /// Виводить на термінал рядок привітання цього вихованця.
    fn greet(&self);
}

Реалізація трейтів

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

    fn greet(&self) {
        println!("Який же ти милий! Як тебе звати? {}", self.talk());
    }
}

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

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Гав, мене звуть {}!", self.name)
    }
}

fn main() {
    let fido = Dog { name: String::from("Фідо"), age: 5 };
    fido.greet();
}

Супертрейти

Трейт може вимагати, щоб типи, які його реалізують, також реалізовували інші трейти, так звані супертрейти. У цьому випадку, будь-який тип, що реалізує Pet, повинен реалізувати Animal.

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("Рекс"));
    println!("{} має {} ніг", puppy.name(), puppy.leg_count());
}

Асоційовані типи

Асоціативні типи - це типи-заповнювачі, які надаються реалізацією трейту.

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

Виведення

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

#[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!("{:?} vs. {:?}", p1, p2);
}

Вправа: Трейт логгера

Давайте розробимо просту утиліту для ведення логів, використовуючи трейт Logger з методом log. Код, який може реєструвати свій прогрес, може отримати &impl Logger. Під час тестування це може призвести до запису повідомлень до тестового лог-файлу, тоді як у виробничій збірці повідомлення надсилатимуться до сервера логів.

Однак, наведений нижче StderrLogger реєструє всі повідомлення, незалежно від їхньої докладності. Ваше завдання - написати тип VerbosityFilter, який ігноруватиме повідомлення з максимальною докладностю.

Це поширений патерн: структура, що обгортає реалізацію трейту і реалізує той самий трейт, додаючи поведінку в процесі. Які ще типи обгорток можуть бути корисними у утиліті для ведення логів?

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

// TODO: Визначте та реалізуйте `VerbosityFilter`.

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

Рішення

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

Ласкаво просимо назад

Including 10 minute breaks, this session should take about 3 hours and 15 minutes. It contains:

Узагальнені типи

This segment should take about 45 minutes. It contains:

Узагальнені функції

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

/// Виберіть `even` або `odd` в залежності від значення `n`.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("вибраний номер: {:?}", pick(97, 222, 333));
    println!("вибрав рядок: {:?}", pick(28, "собака", "кіт"));
}

Узагальнені типи даних

Ви можете використовувати узагальнення для абстрагування від конкретного типу поля:

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    fn set_x(&mut self, x: T) {
        self.x = x;
    }
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} та {float:?}");
    println!("координати: {:?}", integer.coords());
}

Узагальнені трейти

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

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

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("Перетворено з цілого числа: {from}"))
    }
}

impl From<bool> for Foo {
    fn from(from: bool) -> Foo {
        Foo(format!("Перетворено з булевого значення: {from}"))
    }
}

fn main() {
    let from_int = Foo::from(123);
    let from_bool = Foo::from(true);
    println!("{from_int:?}, {from_bool:?}");
}

Обмеження трейту

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

Ви можете зробити це за допомогою T: Trait:

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

// struct NotClonable;

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

impl Trait

Подібно до меж трейтів, синтаксис impl Trait можна використовувати в аргументах функції та значеннях, що повертаються:

// Синтаксичний цукор для:
//   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);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("debuggable: {debuggable:?}");
}

dyn Trait

На додаток до використання трейтів для статичного пересилання за допомогою узагальнень, Rust також підтримує їх використання для динамічного пересилання зі стиранням типу за допомогою об'єктів трейтів:

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!("Гав, мене звуть {}!", self.name)
    }
}

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

// Використовує узагальнення та статичну диспетчеризацію.
fn generic(pet: &impl Pet) {
    println!("Привіт, ви хто? {}", pet.talk());
}

// Використовує стирання типів та динамічну диспетчеризацію.
fn dynamic(pet: &dyn Pet) {
    println!("Привіт, ви хто? {}", pet.talk());
}

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

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

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

Вправа: узагальнена min

У цій короткій вправі ви реалізуєте узагальнену функцію min, яка визначає мінімальне з двох значень, використовуючи трейт Ord.

use std::cmp::Ordering;

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

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("привіт", "до побачення"), "до побачення");
    assert_eq!(min("кажан", "броненосець"), "броненосець");
}

Рішення

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

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("привіт", "до побачення"), "до побачення");
    assert_eq!(min("кажан", "броненосець"), "броненосець");
}

Типи стандартної бібліотеки

This segment should take about 1 hour. It contains:

Стандартна бібліотека

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

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

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

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

Rust постачається з обширною документацією. Наприклад:

• Всі подробиці про цикли.
• Примітивні типи на зразок u8
• Типи стандартної бібліотеки, такі як Option або BinaryHeap.

Фактично, ви можете документувати свій власний код:

/// Визначити, чи ділиться перший аргумент на другий.
///
/// Якщо другий аргумент дорівнює нулю, результат буде false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

Контент розглядається як Markdown. Усі опубліковані крейти бібліотеки Rust автоматично документуються на docs.rs за допомогою rustdoc. Це ідіоматично документувати всі публічні елементи в API за допомогою цього шаблону.

Щоб задокументувати елемент із середини елемента (наприклад, всередині модуля), використовуйте //! або /*! .. */, які називаються "внутрішні коментарі до документу":

//! Цей модуль містить функціональність, пов'язану з подільністю цілих чисел.

Option

Ми вже бачили деяке використання Option<T>. Це зберігає або значення типу T, або нічого. Наприклад, String::find повертає Option<usize>.

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("пошук повернув {position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("пошук повернув {position:?}");
    assert_eq!(position.expect("Символ не знайдено"), 0);
}

Result

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

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!("Дорогий щоденник: {contents} ({bytes} байтів)");
            } else {
                println!("Не вдалося прочитати вміст файлу");
            }
        }
        Err(err) => {
            println!("Щоденник не вдалося відкрити: {err}");
        }
    }
}

String

String — це розширюваний рядок у кодуванні UTF-8:

fn main() {
    let mut s1 = String::new();
    s1.push_str("Привіт");
    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>, що означає, що ви можете викликати усі методи str у String.

Vec

Vec — стандартний буфер із змінним розміром, виділений у купі:

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-атак:

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!(
            "Ми знаємо про {} книги, але не 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} сторінок"),
            None => println!("{book} невідома."),
        }
    }

    // Використовуйте метод .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;
    }

    println!("{page_counts:#?}");
}

Вправа: Лічильник

У цій вправі ви візьмете дуже просту структуру даних і зробите її узагальненою. Вона використовує std::collections::HashMap для відстеження того, які значення було переглянуто і скільки разів кожне з них з'являлося.

Початкова версія Counter жорстко налаштована на роботу лише зі значеннями u32. Зробіть структуру та її методи узагальненими щодо типу значення, яке відстежується, таким чином Counter зможе відстежувати будь-який тип значення.

Якщо ви закінчите раніше, спробуйте використати метод entry, щоб вдвічі зменшити кількість переглядів хешу, необхідних для реалізації методу count.

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!("побачив {} значень рівних {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("яблуко");
    strctr.count("апельсин");
    strctr.count("яблуко");
    println!("отримав {} яблук", strctr.times_seen("яблуко"));
}

Рішення

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!("побачив {} значень рівних {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("яблуко");
    strctr.count("апельсин");
    strctr.count("яблуко");
    println!("отримав {} яблук", strctr.times_seen("яблуко"));
}

Трейти стандартної бібліотеки

This segment should take about 1 hour and 10 minutes. It contains:

Порівняння

Ці трейти підтримують порівняння між значеннями. Усі трейти можуть бути визначені для типів, що містять поля, які реалізують ці трейти

PartialEq та Eq

PartialEq- це відношення часткової еквівалентності, з обов'язковим методомeqта наданим методомne. Оператори ==та!=` викликають ці методи.

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. Він використовується для реалізації операторів <, <=, >= та >.

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.

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

Оператори

Перевантаження операторів реалізовано за допомогою трейтів у std::ops:

#[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](https://doc.rust-lang.org/std /convert/trait.Into.html), щоб полегшити перетворення типів. На відміну від as, ці трейти відповідають безпомилковим перетворенням без втрат.

fn main() {
    let s = String::from("привіт");
    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](https://doc.rust-lang.org/ std/convert/trait.From.html) реалізовано:

fn main() {
    let s: String = "привіт".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, де вони визначені.

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

Результати функції as завжди визначені у Rust і є стабільними на всіх платформах. Це може не збігатися з вашою інтуїцією щодо зміни знаку або приведення до меншого типу - зверніться до документації та коментарів для уточнення.

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

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

Read та Write

Використовуючи Read і BufRead, ви можете абстрагуватися над джерелами u8:

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!("рядків у зрізі: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("рядків у файлі: {}", count_lines(file));
    Ok(())
}

Подібним чином, Write дозволяє вам абстрагуватися над u8 прийомниками:

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, "Привіт")?;
    log(&mut buffer, "Світ")?;
    println!("Записано: {:?}", buffer);
    Ok(())
}

Трейт Default

Трейт Default створює значення за замовчуванням для типу.

#[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();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Y встановлено!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

Закриття

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

fn apply_and_log(func: impl FnOnce(i32) -> i32, func_name: &str, input: i32) {
    println!("Викликаємо {func_name}({input}): {}", func(input))
}

fn main() {
    let n = 3;
    let add_3 = |x| x + n;
    apply_and_log(&add_3, "add_3", 10);
    apply_and_log(&add_3, "add_3", 20);

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    apply_and_log(&mut accumulate, "accumulate", 4);
    apply_and_log(&mut accumulate, "accumulate", 5);

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    apply_and_log(multiply_sum, "multiply_sum", 3);
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("Привіт".to_string());
    hi(" Грег");
}

Вправа: ROT13

У цьому прикладі ви будете реалізовувати класичний "ROT13" шифр. Скопіюйте цей код на ігровий майданчик і додайте біти, яких бракує. Перевертайте лише символи ASCII, щоб результат залишався дійсним UTF-8.

use std::io::Read;

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

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

fn main() {
    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();
    println!("{}", result);
}

#[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_ref(), 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 символів?

Рішення

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

fn main() {
    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();
    println!("{}", result);
}

#[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_ref(), 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());
            }
        }
    }
}

Ласкаво просимо до дня 3

Сьогодні ми розглянемо:

• Керування пам'яттю, час існування та перевірка запозичень: як Rust гарантує безпеку пам'яті.
• Розумні вказівники: стандартні бібліотечні типи вказівників.

Розклад

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

Управління пам'яттю

This segment should take about 1 hour. It contains:

Огляд пам'яті програми

Програми виділяють пам'ять двома способами:

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

  • Значення мають фіксовані розміри, відомі під час компіляції.
  • Надзвичайно швидко: просто перемістіть вказівник стека.
  • Легко керувати: слідує за викликами функцій.
  • Чудова локальність пам'яті.

• Купа: Зберігання значень поза викликами функцій.

  • Значення мають динамічні розміри, визначені під час виконання.
  • Трохи повільніше, ніж стек: потрібн певний облік.
  • Немає гарантії локальності пам'яті.

Приклад

Створення String поміщає метадані фіксованого розміру в стек, а дані динамічного розміру, фактичний рядок, у купу:

fn main() {
    let s1 = String::from("Привіт");
}

fn main() {
    let mut s1 = String::from("Привіт");
    s1.push(' ');
    s1.push_str("світ");
    // НЕ РОБІТЬ ЦЬОГО ВДОМА! Тільки в навчальних цілях.
    // 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 пропонує нову суміш:

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

Це робиться за допомогою чіткої концепції володіння.

Володіння

Усі прив’язки змінних мають область, де вони дійсні, і використання змінної поза її областю є помилкою:

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

Ми говоримо, що змінна володіє значенням. Кожне значення у Rust завжди має лише одного власника.

В кінці області видимості змінна знищується і дані звільняються. Тут може бути запущено деструктор, щоб звільнити ресурси.

Семантика переміщення

Присвоєння переміщує володіння між змінними:

fn main() {
    let s1: String = String::from("Привіт!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

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

Перед переміщенням до s2:

Після переміщення до s2:

Коли ви передаєте значення функції, це значення присвоюється параметру функції. Це переміщує володіння:

fn say_hello(name: String) {
    println!("Привіт {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Дублювання даних в s1.

Clone

Іноді вам необхідно зробити копію значення. Для цього призначений крейт Clone.

fn say_hello(name: String) {
    println!("Привіт {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name.clone());
    say_hello(name);
}

Типи які копіюються

Хоча семантика переміщення використовується за замовчуванням, певні типи копіюються за замовчуванням:

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

Ці типи реалізують трейт Copy.

Ви можете вибрати власні типи для використання семантики копіювання:

#[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, можуть вказувати код, який запускатиметься, коли вони виходять за межі області видимості:

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Відкидаємо {}", 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!("Виходимо з блоку B");
        }
        println!("Виходимо з блоку A");
    }
    drop(a);
    println!("Виходимо з main");
}

Вправа: Тип будівельника

У цьому прикладі ми реалізуємо складний тип даних, який володіє всіма своїми даними. Ми використаємо патерн "конструктор" для підтримки побудови нового значення по частинах за допомогою зручних функцій.

Заповніть пропущені частини.

#[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 as_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();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Рішення

#[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 as_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![],
            dependencies: vec![],
            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();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Розумні вказівники

This segment should take about 55 minutes. It contains:

Box<T>

Box — це вказівник на дані в купі:

fn main() {
    let five = Box::new(5);
    println!("five: {}", *five);
}

Box<T> реалізує Deref<Target = T>, що означає, що ви можете викликати методи з T безпосередньо на Box<T>.

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

#[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:?}");
}

use std::mem::size_of_val;

struct Item(String);

fn main() {
    let just_box: Box<Item> = Box::new(Item("Just box".into()));
    let optional_box: Option<Box<Item>> =
        Some(Box::new(Item("Optional box".into())));
    let none: Option<Box<Item>> = None;

    assert_eq!(size_of_val(&just_box), size_of_val(&optional_box));
    assert_eq!(size_of_val(&just_box), size_of_val(&none));

    println!("Розмір just_box: {}", size_of_val(&just_box));
    println!("Розмір optional_box: {}", size_of_val(&optional_box));
    println!("Розмір none: {}", size_of_val(&none));
}

Rc

Rc — це спільний вказівник із підрахунком посилань. Використовуйте це, коли вам потрібно звернутися до тих самих даних з кількох місць:

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• Дивіться Arc та Mutex, якщо ви працюєте у багатопотоковому контексті.
• Ви можете понизити спільний вказівник на Weak вказівник, щоб створити цикли, які буде відкинуті.

Принадлежні об'єкти трейтів

Раніше ми бачили, як об'єкти трейтів можна використовувати з посиланнями, наприклад, &dyn Pet. Однак, ми також можемо використовувати об'єкти трейтів з розумними вказівниками, такими як Box, щоб створити власний об'єкт трейту: Box<dyn Pet>.

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!("Гав, мене звуть {}!", self.name)
    }
}

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

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Фідо"), age: 5 }),
    ];
    for pet in pets {
        println!("Привіт, ви хто? {}", pet.talk());
    }
}

Розташування пам’яті після виділення pets:

Вправа: Бінарне дерево

Бінарне дерево - це структура даних деревовидного типу, де кожен вузол має двох нащадків (лівого і правого). Ми створимо дерево, у якому кожна вершина зберігає значення. Для заданого вузла N всі вузли лівого піддерева N містять менші значення, а всі вузли правого піддерева N будуть містити більші значення.

Реалізуйте наступні типи так, щоб задані тести пройшли.

Додаткове завдання: реалізувати ітератор над бінарним деревом, який повертає значення відповідно до порядку.

/// Вузол у бінарному дереві.
#[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`, `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);
    }

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

Рішення

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

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

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

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

Ласкаво просимо назад

Including 10 minute breaks, this session should take about 1 hour and 55 minutes. It contains:

Запозичення

This segment should take about 55 minutes. It contains:

Запозичення значення

Як ми бачили раніше, замість того, щоб передавати право власності при виклику функції, ви можете дозволити функції позичити значення:

#[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 позичає дві точки та повертає нову точку.
• Викликач зберігає право власності на вхідні дані.

Перевірка запозичення

Перевірка запозичень у Rust'і накладає обмеження на способи, якими ви можете запозичувати значення. Для певного значення, у будь-який час:

• Ви можете мати одне або декілька спільних посилань на значення, або
• Ви можете мати лише одне ексклюзивне посилання на значення.

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

Помилки запозичення

Як конкретний приклад того, як ці правила запозичення запобігають помилкам пам'яті, розглянемо випадок модифікації колекції, коли на її елементи є посилання:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let elem = &vec[2];
    vec.push(6);
    println!("{elem}");
}

Аналогічно, розглянемо випадок оголошення ітератора недійсним:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    for elem in &vec {
        vec.push(elem * 2);
    }
}

Внутрішня мутабельність

У деяких ситуаціях необхідно модифікувати дані за спільним (доступним лише для читання) посиланням. Наприклад, структура даних зі спільним доступом може мати внутрішній кеш, і ви хочете оновити цей кеш методами, доступними лише для читання.

Паттерн "внутрішня мутабельність" дозволяє ексклюзивний (мутабельний) доступ за спільним посиланням. Стандартна бібліотека надає декілька способів зробити це, забезпечуючи при цьому безпеку, як правило, шляхом виконання перевірки під час виконання.

Cell

Cell обгортає значення і дозволяє отримати або встановити значення, використовуючи лише спільне посилання на Cell. Однак, вона не дозволяє жодних посилань на внутрішнє значення. Оскільки посилань немає, правила запозичення не можуть бути порушені.

use std::cell::Cell;

fn main() {
    // Зауважте, що `cell` НЕ оголошено як мутабельну.
    let cell = Cell::new(5);

    cell.set(123);
    println!("{}", cell.get());
}

RefCell

RefCell дозволяє отримувати доступ до обгорнутого значення та змінювати його, надаючи альтернативні типи Ref та RefMut, які імітують &T/&mut T, не будучи насправді Rust посиланнями.

Ці типи виконують динамічні перевірки за допомогою лічильника в RefCell, щоб запобігти існуванню RefMut поряд з іншим Ref/RefMut.

Завдяки реалізації Deref (і DerefMut для RefMut), ці типи дозволяють викликати методи за внутрішнім значенням, не дозволяючи посиланням втекти.

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

Вправа: Статистика здоров’я

Ви працюєте над впровадженням системи моніторингу здоров’я. У рамках цього вам потрібно відстежувати статистику здоров’я користувачів.

Ви почнете із заглушки функції у блоці impl, а також з визначення структури User. Ваша мета — рреалізувати заглушений метод в структурі User, визначений у блоці impl.

Скопіюйте код нижче в https://play.rust-lang.org/ та заповніть відсутній метод:

// TODO: видаліть це, коли закінчите реалізацію.
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!(" Оновити статистику користувача на основі вимірювань під час візиту до лікаря")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("Мене звуть {}, а мій вік - {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

Рішення

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("Мене звуть {}, а мій вік - {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

Тривалість життя

This segment should take about 50 minutes. It contains:

Анотації тривалісті життя

Посилання має тривалість життя, яка не повинна "пережити" значення, на яке воно посилається. Це перевіряється чекером запозичень.

Тривалість життя може бути неявною - це те, що ми бачили досі. Часи життя також можуть бути явними: &'a Point'', &'document str''. Тривалість життя починається з ', а 'a є типовим іменем за замовчуванням. Читати &'a Point як "запозичений Point, який є дійсним принаймні протягом тривалості життя a".

Тривалість життя завжди визначається компілятором: ви не можете призначити час життя самостійно. Явні анотації часу життя створюють обмеження там, де існує неоднозначність; компілятор перевіряє, чи існує правильний розв'язок.

Часи життя ускладнюються, якщо врахувати передачу значень у функції та повернення значень з них.

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // Яка тривалість життя p3?
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

Тривалість життя у викликах функцій

Тривалість життя аргументів функції та значень, що повертаються, має бути повністю вказана, але Rust дозволяє у більшості випадків не вказувати тривалість життя за допомогою кількох простих правил. Це не виведення - це просто синтаксичне скорочення.

• Кожному аргументу, який не має анотації тривалості життя, присвоюється одна.
• Якщо існує лише одна тривалість життя аргументу, то вона надається всім неанотованим значенням, що повертаються.
• Якщо існує декілька тривалостей життя аргументів, але перша з них призначена для self, ця тривалість надається усім неанотованим значенням повернення.

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    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.map(|(p, _)| p)
}

fn main() {
    println!(
        "{:?}",
        nearest(
            &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1),],
            &Point(0, 2)
        )
    );
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

Тривалість життя в структурах даних

Якщо тип даних зберігає запозичені дані, він повинен мати анотацію із зазначенням тривалості життя:

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("Bye {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

Вправа: Розбір 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) і тип передачі, який визначає спосіб визначення корисного навантаження з потоку байт.

Цілі числа, включаючи тег, подаються у кодуванні змінної довжини, яке називається VARINT. На щастя, нижче визначено parse_varint для вас. Наведений код також визначає виклики для обробки полів Person і PhoneNumber, а також для розбору повідомлення на серію викликів цих зворотних викликів.

Вам залишається реалізувати функцію parse_field та трейт ProtoMessage для Person та PhoneNumber.

/// wire type як він приходить по дроту.
enum WireType {
    /// Varint WireType вказує на те, що значення є одним VARINT.
    Varint,
    /// I64 WireType вказує на те, що значення має точно 8 байт у little-endian
    /// порядку та містить 64-бітне ціле зі знаком або тип з плаваючою комою подвійної точності.
//I64,  -- не потрібно для цієї вправи
    /// Len WireType вказує на те, що значення є довжиною, представленою у вигляді 
    /// VARINT за яким слідує рівно стільки байт.
    Len,
    // Тип WireType I32 вказує на те, що значення - це рівно 4 байти в
    // little-endian порядку, що містять 32-бітне ціле число зі знаком або тип з плаваючою комою.
    //I32,  -- не потрібно для цієї вправи
}

#[derive(Debug)]
/// Значення поля, введене на основі wire type.
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!("Неправильний wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Очікуваний рядок має бути полем `Len`");
        };
        std::str::from_utf8(data).expect("Неправильний рядок")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Очікувані байти мають бути полем `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Очікувалося, що `u64` буде полем `Varint`");
        };
        *value
    }
}

/// Розбір VARINT з поверненням розібраного значення та решти байтів.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Недостатньо байт для 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!("Забагато байт для 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!("На основі wire type побудуйте Field, використовуючи стільки байт, скільки потрібно.")
    };
    todo!("Повернути поле та всі невикористані байти.")
}

/// Розбір повідомлення за заданими даними, викликаючи `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 Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Реалізувати ProtoMessage для Person та PhoneNumber.

fn main() {
    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,
    ]);
    println!("{:#?}", person);
}

Рішення

/// wire type як він приходить по дроту.
enum WireType {
    /// Varint WireType вказує на те, що значення є одним VARINT.
    Varint,
    /// I64 WireType вказує на те, що значення має точно 8 байт у little-endian
    /// порядку та містить 64-бітне ціле зі знаком або тип з плаваючою комою подвійної точності.
//I64,  -- не потрібно для цієї вправи
    /// Len WireType вказує на те, що значення є довжиною, представленою у вигляді 
    /// VARINT за яким слідує рівно стільки байт.
    Len,
    // Тип WireType I32 вказує на те, що значення - це рівно 4 байти в
    // little-endian порядку, що містять 32-бітне ціле число зі знаком або тип з плаваючою комою.
    //I32,  -- не потрібно для цієї вправи
}

#[derive(Debug)]
/// Значення поля, введене на основі wire type.
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!("Неправильний wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Очікуваний рядок має бути полем `Len`");
        };
        std::str::from_utf8(data).expect("Неправильний рядок")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Очікувані байти мають бути полем `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Очікувалося, що `u64` буде полем `Varint`");
        };
        *value
    }
}

/// Розбір VARINT з поверненням розібраного значення та решти байтів.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Недостатньо байт для 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!("Забагато байт для 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: usize = len.try_into().expect("len не є допустимим `usize`");
            if remainder.len() < len {
                panic!("Несподіваний EOF");
            }
            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(),
            _ => {} // пропустити все інше
        }
    }
}

fn main() {
    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,
    ]);
    println!("{:#?}", person);
}

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

    #[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: "красиве ім'я", 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: "Еван", 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_: "дім" },],
            }
        );
    }
}

Ласкаво просимо до Дня 4

Сьогодні ми розглянемо теми, що стосуються створення великомасштабного програмного забезпечення на Rust:

• Ітератори: глибоке занурення в трейт Iterator.
• Модулі та видимість.
• Тестування
• Обробка помилок: паніка, Result і оператор спроби ?.
• Небезпечний Rust: рятувальний отвір, коли ви не можете виразити себе в безпечному Rust.

Розклад

Including 10 minute breaks, this session should take about 2 hours and 40 minutes. It contains:

Ітератори

This segment should take about 45 minutes. It contains:

Ітератор

Трейт Iterator підтримує ітерацію над значеннями у колекції. Він вимагає наявності методу next і надає багато методів. Багато стандартних бібліотечних типів реалізують Iterator, і ви також можете реалізувати його самостійно:

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

Трейт Iterator описує, як виконувати ітерацію після того, як ви створили ітератор. Пов'язаний з нею трейт IntoIterator визначає, як створити ітератор для типу. Він автоматично використовується циклом for.

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!("точка = {x}, {y}");
    }
}

FromIterator

FromIterator дозволяє створювати колекцію з Iterator.

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

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

Вправа: ланцюжок методів ітератора

У цій вправі вам потрібно буде знайти і використати деякі з методів, наданих у трейті Iterator, для реалізації складних обчислень.

Скопіюйте наступний код до https://play.rust-lang.org/ і запустіть тести. Для побудови значення, що повертається, використовуйте вираз ітератору та collect результат.

#![allow(unused)]
fn main() {
/// Обчислює різницю між елементами `values`, зміщеними на  `offset`,
/// обгортаючи навколо від кінця `values` до початку.
///
/// Елемент `n` результату має вигляд `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    unimplemented!()
}

#[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_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

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

Рішення

/// Обчислює різницю між елементами `values`, зміщеними на  `offset`,
/// обгортаючи навколо від кінця `values` до початку.
///
/// Елемент `n` результату має вигляд `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    let a = (&values).into_iter();
    let b = (&values).into_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_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

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

fn main() {}

Модулі

This segment should take about 40 minutes. It contains:

Модулі

Ми бачили, як блоки impl дозволяють нам співвідносити функції з типом.

Аналогічно, mod надає нам можливості співвідносити типи та функції:

mod foo {
    pub fn do_something() {
        println!("У модулі foo");
    }
}

mod bar {
    pub fn do_something() {
        println!("У модулі bar");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

Ієрархія файлової системи

Пропущення вмісту модуля призведе до того, що Rust шукатиме його в іншому файлі:

mod garden;

Це повідомляє Rust, що вміст модуля garden знаходиться в src/garden.rs. Так само модуль garden::vegetables можна знайти на src/garden/vegetables.rs.

Корінь crate знаходиться в:

• src/lib.rs (для крейта бібліотеки)
• src/main.rs (для крейта виконуваного файлу)

Модулі, визначені у файлах, також можна документувати за допомогою "внутрішніх коментарів документа". Вони документують елемент, який їх містить – у цьому випадку це модуль.

//! Цей модуль реалізує сад, включаючи високоефективну реалізацію
//! пророщування.

// Ре-експорт типів з цього модуля.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Посіяти задані пакети насіння.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Збір врожаю в саду, який вже готовий.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

Видимість

Модулі є межею конфіденційності:

• Елементи модуля є приватними за замовчуванням (приховує деталі реалізації).
• Батьківські та споріднені елементи завжди видно.
• Іншими словами, якщо елемент видимий у модулі foo, він видимий у всіх нащадках foo.

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

use, super, self

Модуль може залучати символи з іншого модуля до області видимості за допомогою use. Зазвичай ви бачите щось подібне у верхній частині кожного модуля:

use std::collections::HashSet;
use std::process::abort;

Шляхи

Шляхи вирішуються таким чином:

1. Як відносний шлях:

   • foo або self::foo посилається на foo в поточному модулі,
   • super::foo посилається на foo у батьківському модулі.

2. Як абсолютний шлях:

   • crate::foo посилається на foo в корені поточного крейту,
   • bar::foo посилається на foo в крейті bar.

Вправа: Модулі для бібліотеки графічного інтерфейсу користувача

У цій вправі ви реорганізуєте невелику реалізацію бібліотеки графічного інтерфейсу. У цій бібліотеці визначено трейт Widget та декілька реалізацій цього трейту, а також функцію main.

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

Установка Cargo

Ігрове середовище Rust підтримує лише один файл, тому вам потрібно створити проект Cargo у вашій локальній файловій системі:

cargo init gui-modules
cd gui-modules
cargo run

Відредагуйте отриманий файл src/main.rs, додавши оператори mod, та додайте додаткові файли до каталогу src.

Джерело

Ось одномодульна реалізація бібліотеки графічного інтерфейсу:

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 на return 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("Це невелика текстова демонстрація графічного інтерфейсу.")));
    window.add_widget(Box::new(Button::new("Клацни на мене!")));
    window.draw();
}

Рішення

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
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}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

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

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

// ---- 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
        // Add 4 paddings for borders
        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();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("Це невелика текстова демонстрація графічного інтерфейсу.")));
    window.add_widget(Box::new(widgets::Button::new("Клацни на мене!")));
    window.draw();
}

Тестування

This segment should take about 45 minutes. It contains:

Модульні тести

Rust і Cargo постачаються з простим фреймворком для модульного тестування:

• Модульні тести підтримуються у всьому коді.

• Тести інтеграції підтримуються через каталог tests/.

Тести позначаються #[test]. Модульні тести часто розміщують у вкладеному модулі tests, використовуючи #[cfg(test)] для їх умовної компіляції лише під час збирання тестів.

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("Привіт"), "Привіт");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Привіт, світ!"), "Привіт");
    }
}

• Це дозволяє тестувати приватних помічників.
• Атрибут #[cfg(test)] активний лише тоді, коли ви запускаєте cargo test.

Інші типи тестів

Інтеграційні тести

Якщо ви хочете перевірити свою бібліотеку як клієнт, скористайтеся інтеграційним тестом.

Створіть файл .rs у tests/:

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

Ці тести мають доступ лише до публічного API вашого ящика.

Тести документації

Rust має вбудовану підтримку для тестування документації:

#![allow(unused)]
fn main() {
/// Скорочує рядок до заданої довжини.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Привіт, світ", 5), "Привіт");
/// assert_eq!(shorten_string("Привіт, світ", 20), "Привіт, світ");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• Блоки коду в коментарях /// автоматично сприймаються як код Rust.
• Код буде скомпільовано та виконано як частину cargo test.
• Додавання # до коду приховає його з документації, але все одно скомпілює/запустить.
• Перевірте наведений вище код на Rust Playground.

Лінти компілятора та Clippy

Компілятор Rust видає фантастичні повідомлення про помилки, а також корисні вбудовані лінти. Clippy надає ще більше лінтів, організованих у групи, які можна вмикати для кожного проекту.

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X, напевно, поміститься в u16, так? {}", x as u16);
}

Вправа: Алгоритм Луна

Алгоритм Луна

Алгоритм Луна використовується для перевірки номерів кредитних карток. Алгоритм приймає рядок як вхідні дані та виконує наступне, щоб перевірити номер кредитної картки:

• Ігноруємо всі пробіли. Відхиляємо числа із менш ніж двома цифрами.

• Рухаючись справа наліво, подвоює кожну другу цифру: для числа 1234 ми подвоюємо 3 і 1. Для числа 98765 ми подвоюємо 6 і 8.

• Після подвоєння цифри підсумовує цифри, якщо результат більший за 9. Таким чином, подвоєння 7 перетворюється на 14, яке стає 1 + 4 = 5.

• Підсумовує всі неподвоєні та подвоєні цифри.

• Номер кредитної картки дійсний, якщо сума закінчується на 0.

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

Скопіюйте наведений нижче код на https://play.rust-lang.org/ і напишіть додаткові тести для виявлення помилок у наданій реалізації, виправивши всі знайдені помилки.

#![allow(unused)]
fn main() {
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"));
    }
}
}

Рішення

// Це версія з помилками, яка з'являється у проблемі.
#[cfg(never)]
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
}

// Це рішення, яке проходить усі наведені нижче тести.
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
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "Чи є {cc_number} дійсним номером кредитної картки? {}",
        if luhn(cc_number) { "так" } else { "ні" }
    );
}

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

Ласкаво просимо назад

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

Обробка помилок

This segment should take about 1 hour and 5 minutes. It contains:

Паніки

Rust обробляє фатальні помилки з "panic".

Rust викличе паніку, якщо під час виконання станеться фатальна помилка:

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• Паніки – це невиправні та несподівані помилки.
  • Паніки є ознакою помилок у програмі.
  • Збої у виконанні, такі як невдалі перевірки меж, можуть викликати паніку
  • Твердження (наприклад, assert!) панікують у разі невдачі
  • Для спеціальних панік можна використовувати макрос panic!.
• Паніка "розмотує" стек, відкидаючи значення так, як якщо б функції повернулися.
• Використовуйте API, що не викликають паніки (такі як Vec::get), якщо збій неприйнятний.

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "Ніяких проблем!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("о, ні!");
    });
    println!("{result:?}");
}

Result

Основним механізмом обробки помилок у Rust є перелік Result, який ми коротко розглядали під час обговорення стандартних бібліотечних типів.

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!("Дорогий щоденник: {contents} ({bytes} байтів)");
            } else {
                println!("Не вдалося прочитати вміст файлу");
            }
        }
        Err(err) => {
            println!("Щоденник не вдалося відкрити: {err}");
        }
    }
}

Оператор спроб

Помилки виконання, такі як відмова у з'єднанні або не знайдено файл, обробляються за допомогою типу Result, але зіставлення цього типу для кожного виклику може бути громіздким. Оператор спроби ? використовується для повернення помилок користувачеві. Він дозволяє перетворити звичайний оператор

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

у набагато простіше

some_expression?

Ми можемо використовувати це, щоб спростити наш код обробки помилок:

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

Перетворення спроб

Ефективне розширення ? є трохи складнішим, ніж було зазначено раніше:

expression?

працює так само, як

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

Виклик From::from тут означає, що ми намагаємося перетворити тип помилки на тип, який повертає функція. Це дозволяє легко інкапсулювати помилки у помилки вищого рівня.

Приклад

use std::error::Error;
use std::fmt::{self, Display, Formatter};
use std::fs::File;
use std::io::{self, Read};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl Display for ReadUsernameError {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "I/O помилка: {e}"),
            Self::EmptyUsername(path) => write!(f, "Не знайдено імені користувача в {path}"),
        }
    }
}

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);
    File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //std::fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("ім'я користувача або помилка: {username:?}");
}

Динамічні типи помилок

Іноді ми хочемо дозволити повертати будь-який тип помилки без написання власного переліку, що охоплює всі різні можливості. Трейт std::error::Error дозволяє легко створити об'єкт трейту, який може містити будь-яку помилку.

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}"),
        Err(err) => println!("Помилка: {err}"),
    }
}

thiserror

Крейт thiserror містить макроси, які допомагають уникнути повторювань при визначенні типів помилок. Він містить похідні макроси, які допомагають реалізувати From<T>, Display та трейтError.

use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Error)]
enum ReadUsernameError {
    #[error("I/O помилка: {e}")]
    IoError(#[from] io::Error),
    #[error("Не знайдено імені користувача в {0}")]
    EmptyUsername(String),
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    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}"),
        Err(err) => println!("Помилка: {err:?}"),
    }
}

anyhow

Крейт anyhow надає багатий тип помилок з підтримкою передачі додаткової контекстної інформації, яка може бути використана для семантичного відстеження дій програми, що призвели до виникнення помилки.

Це можна поєднати зі зручними макросами з thiserror, щоб уникнути написання реалізацій трейтів явно для користувацьких типів помилок.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Не знайдено імені користувача в {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!("Не вдалося відкрити {path}"))?
        .read_to_string(&mut username)
        .context("Не вдалося прочитати")?;
    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}"),
        Err(err) => println!("Помилка: {err:?}"),
    }
}

Вправа: Переписування с Result

Нижче реалізовано дуже простий синтаксичний аналізатор для мови виразів. Однак, він обробляє помилки панічно. Перепишіть його так, щоб він використовував ідіоматичну обробку помилок і поширював помилки на повернення з main. Сміливо використовуйте thiserror і anyhow.

Підказка: почніть з виправлення обробки помилок у функції parse. Після того, як вона буде працювати коректно, оновіть Tokenizer для реалізації Iterator<Item=Result<Token, TokenizerError>> і обробіть це у парсері.

use std::iter::Peekable;
use std::str::Chars;

/// Арифметичний оператор.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Токен у мові виразів.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Вираз у мові виразів.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Посилання на змінну.
    Var(String),
    /// Буквальне число.
    Number(u32),
    /// Бінарна операція.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(self.collect_number(c)),
            'a'..='z' => Some(self.collect_identifier(c)),
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("Неочікуваний символ {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("Неочікуваний кінець вводу");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Неправильне 32-бітне ціле число'");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Неочікуваний токен {tok:?}"),
        };
        // Заглянути наперед, щоб розібрати бінарну операцію, якщо вона присутня.
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("Неочікуваний токен {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

Рішення

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// Арифметичний оператор.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Токен у мові виразів.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Вираз у мові виразів.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Посилання на змінну.
    Var(String),
    /// Буквальне число.
    Number(u32),
    /// Бінарна операція.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Неочікуваний символ '{0}' у вхідних даних")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(Ok(self.collect_number(c))),
            'a'..='z' | '_' => Some(Ok(self.collect_identifier(c))),
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("Помилка токенізатора: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Неочікуваний кінець вводу")]
    UnexpectedEOF,
    #[error("Неочікуваний токен {0:?}")]
    UnexpectedToken(Token),
    #[error("Неправильне число")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // Заглянути наперед, щоб розібрати бінарну операцію, якщо вона присутня.
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

Небезпечний Rust

This segment should take about 1 hour and 5 minutes. It contains:

Небезпечний Rust

Мова Rust складається з двох частин:

• Safe Rust: безпека пам’яті, невизначена поведінка неможлива.
• Небезпечний Rust: може викликати невизначену поведінку, якщо порушуються попередні умови.

У цьому курсі ми розглянули переважно безпечний Rust, але важливо знати, що таке небезпечний Rust.

Небезпечний код зазвичай невеликий та ізольований, і його правильність слід ретельно задокументувати. Зазвичай він загорнутий у безпечний рівень абстракції.

Небезпечний Rust дає вам доступ до п’яти нових можливостей:

• Розіменування необроблених вказівників.
• Доступ або зміна мутабельних статичних змінних.
• Доступ до полів union.
• Викликати unsafe функції, включаючи extern функції.
• Реалізація unsafe трейтів.

Далі ми коротко розглянемо небезпечні можливості. Щоб отримати повну інформацію, перегляньте розділ 19.1 у книзі Rust та [Rustonomicon](https://doc .rust-lang.org/nomicon/).

Розіменування "сирих" вказівників

Створення вказівників є безпечним, але для їх розіменування потрібно unsafe:

fn main() {
    let mut s = String::from("обережно!");

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // БЕЗПЕКА: r1 та r2 були отримані з посилань і тому
    // гарантовано є ненульовими та правильно вирівняними, об'єкти, що лежать в основі
    // посилань, з яких вони були отримані, є дійсними на протязі
    // всього небезпечного блоку, і до них немає доступу ні через
    // посилання, ні одночасно через будь-які інші покажчики.
    unsafe {
        println!("r1 є: {}", *r1);
        *r1 = String::from("ууухооох");
        println!("r2 є: {}", *r2);
    }

    // НЕБЕЗПЕЧНО. НЕ РОБІТЬ ЦЬОГО.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 is: {}", *r3);
    */
}

Несталі статичні змінні

Читати незмінну статичну змінну безпечно:

static HELLO_WORLD: &str = "Привіт, світ!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

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

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // БЕЗПЕКА: Немає інших потоків, які могли б отримати доступ до `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // БЕЗПЕКА: Немає інших потоків, які могли б отримати доступ до `COUNTER`.
    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

Об'єднання

Об’єднання подібні до переліків, але вам потрібно самостійно відстежувати активне поле:

#[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, якщо вони мають додаткові передумови, які ви повинні підтримувати, щоб уникнути невизначеної поведінки:

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // БЕЗПЕКА: Індекси розташовані в правильному порядку в межах 
    // фрагмента рядка та лежать на межах послідовності UTF-8.
    unsafe {
        println!("смайлик: {}", emojis.get_unchecked(0..4));
        println!("смайлик: {}", emojis.get_unchecked(4..7));
        println!("смайлик: {}", emojis.get_unchecked(7..11));
    }

    println!("кількість символів: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    // БЕЗПЕКА: `abs` не працює з покажчиками і не має жодних вимог до
    // безпеки.
    unsafe {
        println!("Абсолютне значення -3 згідно з C: {}", abs(-3));
    }

    // Недотримання вимог кодування UTF-8 порушує безпеку пам’яті!
    // println!("смайлик: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("кількість символів: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

Написання небезпечних функцій

Ви можете позначити власні функції як unsafe, якщо вони вимагають певних умов, щоб уникнути невизначеної поведінки.

/// Міняє місцями значення, на які вказують задані покажчики.
///
/// # Безпека
///
/// Покажчики повинні бути дійсними і правильно вирівняними.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // БЕЗПЕКА: ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Реалізація небезпечних трейтів

Як і у випадку з функціями, ви можете позначити трейт unsafe, якщо реалізація повинна гарантувати певні умови, щоб уникнути невизначеної поведінки.

Наприклад, крейт zerocopy має небезпечний трейт, який виглядає приблизно так:

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Безпека
/// Тип повинен мати визначене представлення і не мати заповнень.
pub unsafe trait AsBytes {
    fn as_bytes(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(
                self as *const Self as *const u8,
                size_of_val(self),
            )
        }
    }
}

// БЕЗПЕКА: `u32` має визначене представлення і не має заповнення.
unsafe impl AsBytes for u32 {}

Безпечна обгортка інтерфейсу зовнішньої функції (FFI)

Rust має чудову підтримку виклику функцій через інтерфейс зовнішніх функцій (FFI). Ми скористаємося цим, щоб створити безпечну оболонку для функцій libc, які ви використовуєте у C для читання імен файлів у директорії.

Ви захочете переглянути сторінки посібника:

• opendir(3)
• readdir(3)
• closedir(3)

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

Ви будете конвертувати між усіма цими типами:

• &str до CString: вам потрібно виділити місце для кінцевого символу \0,
• CString до *const i8: вам потрібен покажчик для виклику функцій C,
• *const i8 до &CStr: вам потрібно щось, що може знайти кінцевий символ \0,
• &CStr до &[u8]: зріз байт є універсальним інтерфейсом для "деяких невідомих даних",
• &[u8] до &OsStr: &OsStr є кроком до OsString, використовуйте OsStrExt, щоб створити його,
• &OsStr до OsString: вам потрібно клонувати дані в &OsStr, щоб мати можливість повернути їх і знову викликати readdir.

У Nomicon також є дуже корисний розділ про FFI.

Скопіюйте код нижче на https://play.rust-lang.org/ і заповніть відсутні функції та методи:

// TODO: видаліть це, коли закінчите реалізацію.
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    //Прозорий тип. Дивіться https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Розміщення відповідно до man-сторінки Linux для readdir(3), де ino_t та
    // off_t розгорнуто відповідно до визначень у
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Розміщення відповідно до man-сторінки macOS для dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Дивіться https://github.com/rust-lang/libc/issues/414 та розділ про
        // _DARWIN_FEATURE_64_BIT_INODE у man-сторінці macOS про stat(2).
        //
        // "Платформи, які існували до виходу цих оновлень" відносяться
        // до macOS (на відміну від iOS / wearOS / тощо) на Intel і PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Викликати opendir і повернути значення Ok, якщо це спрацювало,
        // інакше повернути Err з повідомленням.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Продовжуємо викликати readdir до тих пір, поки не отримаємо назад вказівник NULL.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Викликати closedir за необхідністю.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("файли: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

Рішення

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    //Прозорий тип. Дивіться https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Розміщення відповідно до man-сторінки Linux для readdir(3), де ino_t та
    // off_t розгорнуто відповідно до визначень у
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Розміщення відповідно до man-сторінки macOS для dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Дивіться https://github.com/rust-lang/libc/issues/414 та розділ про
        // _DARWIN_FEATURE_64_BIT_INODE у man-сторінці macOS про stat(2).
        //
        // "Платформи, які існували до виходу цих оновлень" відносяться
        // до macOS (на відміну від iOS / wearOS / тощо) на Intel і PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Викликати opendir і повернути значення Ok, якщо це спрацювало,
        // інакше повернути Err з повідомленням.
        let path =
            CString::new(path).map_err(|err| format!("Неправильний путь: {err}"))?;
        // БЕЗПЕКА: path.as_ptr() не може бути NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("Не вдалося відкрити {:?}", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Продовжуємо викликати readdir, доки не отримаємо назад вказівник NULL.
        // БЕЗПЕКА: self.dir ніколи не є NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // Ми досягли кінця директорії.
            return None;
        }
        // БЕЗПЕКА: dirent не є NULL і dirent.d_name є NULL
        // завершено.
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Викликати closedir за необхідністю.
        if !self.dir.is_null() {
            // БЕЗПЕКА: self.dir не є NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("Не вдалося закрити {:?}", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("файли: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("no-such-directory");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Не UTF-8 символ у путі")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "The Foo Diaries\n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Crab\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Не UTF-8 символ у путі")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

Ласкаво просимо до Rust в Android

Rust підтримується для системного програмного забезпечення на Android. Це означає, що ви можете писати нові сервіси, бібліотеки, драйвери або навіть прошивки на Rust (або покращувати існуючий код за потреби).

Сьогодні ми спробуємо викликати Rust з одного з ваших проектів. Тож спробуйте знайти маленький куточок вашої кодової бази, куди ми можемо перенести кілька рядків коду в Rust. Чим менше залежностей і "екзотичних" типів, тим краще. Щось, що аналізує деякі необроблені байти, було б ідеальним.

Установка

Для тестування нашого коду ми будемо використовувати Cuttlefish Android Virtual Device. Переконайтеся, що у вас є доступ до нього або створіть новий:

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

Докладнішу інформацію можна знайти в Android Developer Codelab.

Правила побудови

Система збірки Android (Soong) підтримує Rust за допомогою кількох модулів:

Далі ми розглянемо rust_binary і rust_library.

Бінарні файли Rust

Почнемо з простої програми. У корені AOSP-каси створіть наступні файли:

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Демонстрація Rust.

/// Виводить привітання у стандартний вивід.
fn main() {
    println!("Привіт від Rust!");
}

Тепер ви можете створювати, завантажувати та запускати бінарний файл:

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust" /data/local/tmp
adb shell /data/local/tmp/hello_rust

Hello from Rust!

Бібліотеки Rust

Ви використовуєте rust_library, щоб створити нову бібліотеку Rust для Android.

Тут ми оголошуємо залежність від двох бібліотек:

• libgreeting, який ми визначаємо нижче,
• libtextwrap, який є крейтом, який уже поставляється в external/rust/crates/.

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // Це потрібно, щоб уникнути помилки динамічного лінкування.
}

rust_library {
    name: "libgreetings",
    crate_name: "привіт",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Демонстрація Rust.

use greetings::greeting;
use textwrap::fill;

/// Виводить привітання у стандартний вивід.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! Бібліотека привітання.

/// Привітати `name`.
pub fn greeting(name: &str) -> String {
    format!("Привіт, {name}, дуже приємно познайомитися з вами!")
}

Ви створюєте, завантажуєте та запускаєте бінарний файл, як і раніше:

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep" /data/local/tmp
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL

Android Interface Definition Language (AIDL) підтримується в Rust:

• Код Rust може викликати існуючі сервери AIDL,
• Ви можете створювати нові сервери AIDL у Rust.

Посібник із сервісу Birthday

Щоб проілюструвати, як використовувати Rust з Binder, ми розглянемо процес створення інтерфейсу Binder. Потім ми реалізуємо описаний сервіс і напишемо клієнтський код, який взаємодіє з цим сервісом.

Інтерфейси AIDL

Ви оголошуєте API свого сервісу за допомогою інтерфейсу AIDL:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

package com.example.birthdayservice;

/** Інтерфейс сервісу Birthday. */
interface IBirthdayService {
    /** Генерує привітання з днем народження. */
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp:

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust не увімкнено за замовчуванням
            enabled: true,
        },
    },
}

Згенерований API сервісу

Binder генерує трейт, що відповідає визначенню інтерфейсу. Трейт для зв'язку з сервісом.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Інтерфейс сервісу Birthday. */
interface IBirthdayService {
    /** Генерує привітання з днем народження. */
    String wishHappyBirthday(String name, int years);
}

Згенерований трейт:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Ваш сервіс повинен реалізувати цей трейт, а ваш клієнт використовуватиме цей трейт для спілкування зі сервісом.

Реалізація сервісу

Тепер ми можемо реалізувати сервіс AIDL:

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// Реалізація  `IBirthdayService`.
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("З днем народження {name}, вітаємо з {years} роками!"))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

Сервер AIDL

Нарешті, ми можемо створити сервер, який надаватиме сервіс:

birthday_service/src/server.rs:

//! Сервіс привітання з днем народження.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Точка входу для сервісу дня народження.
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("Не вдалося зареєструвати сервіс");
    binder::ProcessState::join_thread_pool()
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // Щоб уникнути помилки динамічного лінкування.
}

Розгортка

Тепер ми можемо створювати, надсилати та запускати службу:

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server" /data/local/tmp
adb root
adb shell /data/local/tmp/birthday_server

В іншому терміналі перевірте, чи працює сервіс:

adb shell service check birthdayservice

Service birthdayservice: found

Ви також можете викликати сервіс за допомогою service call:

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

Клієнт AIDL

Нарешті ми можемо створити клієнт Rust для нашого нового сервісу.

birthday_service/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Виклик сервісу привітання з днем народження.
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "Не вдалося підключитися до BirthdayService")?;

    // Викликаемо сервіс.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // Щоб уникнути помилки динамічного лінкування.
}

Зауважте, що клієнт не залежить від libbirthdayservice.

Створіть, завантажте та запустіть клієнт на своєму пристрої:

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

Зміна API

Давайте розширимо API, додавши більше функціональних можливостей: ми хочемо дозволити клієнтам вказувати список рядків для листівки з днем ​​народження:

package com.example.birthdayservice;

/** Інтерфейс сервісу Birthday. */
interface IBirthdayService {
    /** Генерує привітання з днем народження. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

У результаті буде оновлено визначення трейту для IBirthdayService:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Оновлення клієнта та сервісу

Оновіть клієнтський та серверний код, щоб врахувати новий API.

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "З днем народження {name}, вітаємо з {years} роками!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_service/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("А також: багато іншого"),
    ],
)?;

Робота з типами AIDL

Типи AIDL транслюються у відповідний ідіоматичний тип Rust:

• Примітивні типи здебільшого відображаються на ідіоматичні типи Rust.
• Підтримуються такі типи колекцій, як зрізи, Vec та рядкові типи.
• Посилання на об'єкти AIDL та дескриптори файлів можуть передаватися між клієнтами та сервісами.
• Повністю підтримуються дескриптори файлів та посилкові дані.

Примітивні типи

Примітивні типи відображаються (здебільшого) ідіоматично:

Типи Масивів

Типи масивів (T[], byte[] та List<T>) буде переведено до відповідного типу масиву Rust залежно від того, як вони використовуються у сигнатурі функції:

Надсилання об'єктів

AIDL-об'єкти можна надсилати або як конкретний тип AIDL, або як інтерфейс IBinder зі стертим типом:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** Те саме, але з використанням об'єкта-зв'язки. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** Те саме, але з використанням `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust структурна структура, що реалізує інтерфейс `IBirthdayInfoProvider`.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Не вдалося підключитися до BirthdayService");

    // Створюємо об'єкт-зв'язувач для інтерфейсу `IBirthdayInfoProvider`.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Надсилаємо об'єкт-зв'язку до сервісу.
    service.wishWithProvider(&provider)?;

    // Виконуємо ту саму операцію, але передаємо провайдера як `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

Посилкові данні

Binder для Rust підтримує пряме надсилання посилкових данних:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** Те саме, але з посилковими даними. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Не вдалося підключитися до BirthdayService");

    let info = BirthdayInfo { name: "Alice".into(), years: 123 };
    service.wishWithInfo(&info)?;
}

Надсилання файлів

Файли можна надсилати між клієнтами/серверами Binder, використовуючи тип ParcelFileDescriptor:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** Те саме, але завантажує інформацію з файлу. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Не вдалося підключитися до BirthdayService");

    // Відкриваємо файл і записуємо до нього інформацію про день народження.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Створюємо `ParcelFileDescriptor` з файлу та надсилаємо його.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Перетворюємо дескриптор файлу в `File`. `ParcelFileDescriptor` обертає 
        // `OwnedFd`, який може бути клонований і потім використаний для створення об'єкту
        // `File`.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Неправильний дескриптор файлу");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("З днем народження {name}, вітаємо з {years} роками!"))
    }
}

Тестування в Android

Спираючись на Тестування, ми розглянемо, як працюють юніт-тести в AOSP. Використовуйте модуль rust_test для ваших модульних тестів:

testing/Android.bp:

rust_library {
    name: "libleftpad",
    crate_name: "leftpad",
    srcs: ["src/lib.rs"],
}

rust_test {
    name: "libleftpad_test",
    crate_name: "leftpad_test",
    srcs: ["src/lib.rs"],
    host_supported: true,
    test_suites: ["general-tests"],
}

testing/src/lib.rs:

#![allow(unused)]
fn main() {
//! Бібліотека лівих відступів.

/// Додати `s` зліва до `width`.
pub fn leftpad(s: &str, width: usize) -> String {
    format!("{s:>width$}")
}

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

    #[test]
    fn short_string() {
        assert_eq!(leftpad("foo", 5), "  foo");
    }

    #[test]
    fn long_string() {
        assert_eq!(leftpad("foobar", 6), "foobar");
    }
}
}

Тепер ви можете запустити тест за допомогою

atest --host libleftpad_test

Результат має такий вигляд:

INFO: Elapsed time: 2.666s, Critical Path: 2.40s
INFO: 3 processes: 2 internal, 1 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//comprehensive-rust-android/testing:libleftpad_test_host            PASSED in 2.3s
    PASSED  libleftpad_test.tests::long_string (0.0s)
    PASSED  libleftpad_test.tests::short_string (0.0s)
Test cases: finished with 2 passing and 0 failing out of 2 test cases

Зверніть увагу, що ви згадуєте лише корінь крейта бібліотеки. Тести знаходяться рекурсивно у вкладених модулях.

GoogleTest

Крейт GoogleTest дозволяє створювати гнучкі тестові твердження за допомогою зрівнювачів.

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq(&"foo"), lt(&"xyz"), starts_with("b")));
}

Якщо ми змінимо останній елемент на "!", тест завершиться невдачею зі структурованим повідомленням про помилку, яке точно вказує на помилку:

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

Mocking

Для імітації широко використовується бібліотека Mockall. Вам потрібно рефакторити свій код, щоб використовувати трейти, які потім можна швидко імітувати:

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

Журналювання

Ви повинні використовувати крейт log для автоматичної реєстрації в logcat (на пристрої) або stdout (на хості):

hello_rust_logs/Android.bp:

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs:

//! Демонстрація журналу Rust.

use log::{debug, error, info};

/// Реєструє привітання.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("Запуск програми.");
    info!("Справи йдуть добре.");
    error!("Щось пішло не так!");
}

Створіть, завантажте і запустіть бінарний файл на своєму пристрої:

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs" /data/local/tmp
adb shell /data/local/tmp/hello_rust_logs

Журнали відображаються в adb logcat:

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

Інтероперабельність

Rust чудово підтримує взаємодію з іншими мовами. Це означає, що ви можете:

• Викликати функції Rust з інших мов.
• Функції виклику, написані іншими мовами з Rust.

Коли ви викликаєте функції з іншої мови, ми говоримо, що ви використовуєте foreign function interface, також відомий як FFI.

Взаємодія з C

Rust має повну підтримку зв’язування об’єктних файлів за допомогою угоди про виклики C. Так само ви можете експортувати функції Rust і викликати їх із C.

Ви можете зробити це вручну, якщо хочете:

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    // SAFETY: `abs` doesn't have any safety requirements.
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

Ми вже бачили це у вправі Safe FFI Wrapper.

Це передбачає повне знання цільової платформи. Не рекомендується для використання.

Далі ми розглянемо кращі варіанти.

Використання Bindgen

Інструмент bindgen може автоматично генерувати прив’язки з файлу заголовка C.

Спочатку створіть невелику бібліотеку C:

interoperability/bindgen/libbirthday.h:

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

interoperability/bindgen/libbirthday.c:

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("| З днем народженняy %s!\n", card->name);
  printf("| Вітаємо з %i роками!\n", card->years);
  printf("+--------------\n");
}

Додайте це до свого файлу Android.bp:

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

Створіть файл заголовка оболонки для бібліотеки (у цьому прикладі це не обов’язково):

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

Тепер ви можете автоматично генерувати прив’язки:

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "прив'язки",
    static_libs: ["libbirthday"],
}

Нарешті, ми можемо використовувати прив’язки в нашій програмі Rust:

interoperability/bindgen/Android.bp:

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Демонстрація Bindgen.

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("Peter").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // БЕЗПЕКА: Вказівник, який ми передаємо, є дійсним, оскільки він прийшов з
    // Rust посилання, а `name`, яке воно містить, посилається на `name`
    // вище, яке також залишається дійсним. `print_card` не зберігає жодного з вказівників, щоб використати
    // їх пізніше після повернення.
    unsafe {
        print_card(&card as *const card);
    }
}

Створіть, завантажте і запустіть бінарний файл на своєму пристрої:

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card" /data/local/tmp
adb shell /data/local/tmp/print_birthday_card

Нарешті, ми можемо запустити автоматично згенеровані тести, щоб переконатися, що прив’язки працюють:

interoperability/bindgen/Android.bp:

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "none", // Згенерований файл, пропустити лінтування
    lints: "none",
}

atest libbirthday_bindgen_test

Виклик Rust

Експортувати функції та типи Rust на C легко:

interoperability/rust/libanalyze/analyze.rs

//! Демонстрація Rust FFI.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Проаналізувати числа.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) є найменшим!");
    } else {
        println!("y ({y}) ймовірно більше, ніж x ({x})");
    }
}

interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

extern "C" {
void analyze_numbers(int x, int y);
}

#endif

interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

Тепер ми можемо викликати це з бінарного файлу C:

interoperability/rust/analyze/main.c

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

Створіть, завантажте і запустіть бінарний файл на своєму пристрої:

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers" /data/local/tmp
adb shell /data/local/tmp/analyze_numbers

З С++

Крейт CXX дає змогу безпечно взаємодіяти між Rust і C++.

Загальний підхід виглядає так:

Модуль Bridge

CXX покладається на опис сигнатур функцій, які будуть передаватися з однієї мови до іншої. Ви надаєте цей опис за допомогою блоків extern у модулі Rust, анотованому макросом з атрибутом #[cxx::bridge].

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Спільні структури з полями, видимими для обох мов.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Типи та сигнатури Rust, що доступні у C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // Типи та сигнатури C++, доступні у Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Декларації мосту на мові Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Непрозорий тип
        fn foo(&self); // Метод на `MyType`
        fn bar() -> Box<MyType>; // Вільна функція
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

Згенерований C++

#[cxx::bridge]
mod ffi {
    // Типи та сигнатури Rust, що доступні у C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

В результаті маємо (приблизно) наступний код на C++:

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

Декларації мосту на мові C++

#[cxx::bridge]
mod ffi {
    // Типи та сигнатури C++, доступні у Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

В результаті отримуємо (приблизно) такий Rust:

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

Спільні типи

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Спільні переліки

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Згенерований Rust

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

Згенерований C++:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

Обробка помилок в Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 вимагає глибини > 0"));
    }

    Ok("Успіх!".into())
}

Обробка помилок в C++

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Помилка: {}", err);
        process::exit(1);
    }
}

Додаткові типи

Збірка в Android

Створіть cc_library_static, щоб зібрати бібліотеку C++, включаючи згенерований CXX заголовок і вихідний файл.

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

Збірка в Android

Створіть два правила генерування: Одне для створення заголовка CXX, а інше для створення вихідного файлу CXX. Потім їх буде використано як вхідні дані для cc_library_static.

// Згенерує C++ заголовок, що містить C++ прив'язки до
// експортованих функцій Rust у lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Згенерує C++ код, до якого звертається Rust.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

Збірка в Android

Створіть rust_binary, який залежить від libcxx і вашої cc_library_static.

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

Взаємодія з Java

Java може завантажувати спільні об’єкти через Java Native Interface (JNI). Крейт jni дозволяє створити сумісну бібліотеку.

Спочатку ми створюємо функцію Rust для експорту в Java:

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI демонстрація.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// Реалізація методу HelloWorld::hello.
#[no_mangle]
pub extern "system" fn Java_HelloWorld_hello(
    env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(name).unwrap().into();
    let greeting = format!("Привіт, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_inner()
}
}

interoperability/java/Android.bp:

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

Потім ми можемо викликати цю функцію з Java:

interoperability/java/HelloWorld.java:

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("Alice");
        System.out.println(output);
    }
}

interoperability/java/Android.bp:

java_binary {
    name: "helloworld_jni",
    srcs: ["HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

Нарешті, ви можете створити, синхронізувати та запустити бінарний файл:

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

Вправи

Це групова вправа: ми розглянемо один із проектів, з яким ви працюєте, і спробуємо інтегрувати в нього трохи Rust. Деякі пропозиції:

• Викличте свій сервіс AIDL з клієнтом, написаним на Rust.

• Перемістіть функцію зі свого проекту в Rust і викличте її.

Ласкаво просимо до Rust в Chromium

Rust підтримується для бібліотек сторонніх розробників у Chromium, а також стороннім кодом для з'єднання між Rust та існуючим кодом Chromium C++.

Сьогодні ми будемо викликати Rust, щоб зробити дещо безглузде з рядками. Якщо у вас є ділянка коду, де ви показуєте користувачеві рядок у кодуванні UTF8, сміливо використовуйте цей рецепт у вашій частині коду, замість тієї частини, про яку ми говоримо.

Установка

Переконайтеся, що ви можете зібрати та запустити Chromium. Підійде будь-яка платформа і набір флажків збірки, якщо ваш код відносно свіжий (позиція коміту 1223636 і далі, що відповідає листопаду 2023 року):

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(Рекомендується використовувати налагоджувальну збірку компонента для скорочення часу ітерацій. Це збірка за замовчуванням!)

Дивіться Як зібрати Chromium, якщо ви ще не зробили цього. Зауважте: підготовка до збірки Chromium потребує часу.

Також рекомендується, щоб у вас був встановлений код Visual Studio.

Про вправи

Ця частина курсу складається з серії вправ, які будуються одна на одній. Ми будемо виконувати їх протягом усього курсу, а не лише наприкінці. Якщо ви не встигнете виконати певну частину, не хвилюйтеся: ви зможете надолужити згаяне на наступному занятті.

Порівняння екосистем Chromium і Cargo

Спільнота Rust зазвичай використовує cargo та бібліотеки з crates.io. Chromium збирається за допомогою gn і ninja та курованого набору залежностей.

Коли ви пишете код на Rust, у вас є вибір:

• Використовувати gn і ninja за допомогою шаблонів з //build/rust/*.gni (наприклад, rust_static_library, з яким ми познайомимося пізніше). Для цього використовується перевірений інструментарій та крейти Chromium.
• Використовувати cargo, але обмежитися перевіреним інструментарієм та крейтами Chromium
• Використовувати cargo, довіряючи інструментарію та/або крейтам, завантаженим з Інтернету.

Відтепер ми зосередимося на gn та ninja, тому що саме так код Rust можна вбудувати в браузер Chromium. У той же час, Cargo є важливою частиною екосистеми Rust, і ви повинні мати його у своєму арсеналі інструментів.

Міні вправа

Розділіться на невеликі групи та:

• Проведіть мозковий штурм сценаріїв, де cargo може дати перевагу, і оцініть профіль ризику цих сценаріїв.
• Обговоріть, яким інструментам, бібліотекам і групам людей варто довіряти при використанні gn і ninja, офлайнового cargo тощо.

Політика Chromium щодо Rust

Chromium поки що не дозволяє сторонній Rust, за винятком рідкісних випадків, схвалених Chromium Area Tech Leads.

Політика Chromium щодо сторонніх бібліотек описана тут - Rust дозволяється для сторонніх бібліотек за різних обставин, зокрема, якщо вони є найкращим варіантом для продуктивності або безпеки.

Дуже мало бібліотек Rust безпосередньо надають C/C++ API, а це означає, що майже всі такі бібліотеки потребують невеликої кількості стороннього коду для склеювання.

Код склейки Rust від сторонніх розробників для конкретного стороннього скрипта зазвичай слід зберігати у third_party/rust/<crate>/<version>/wrapper.

Через це сьогоднішній курс буде значною мірою сфокусований на:

• Залучення сторонніх бібліотек Rust ("крейтів")
• Написання коду для використання цих крейтів з Chromium C++.

Якщо ця політика з часом зміниться, курс буде розвиватися, щоб не відставати від неї.

Правила побудови

Код Rust зазвичай збирається за допомогою cargo. Chromium збирає за допомогою gn та ninja для ефективності --- його статичні правила дозволяють максимальний паралелізм. Rust не є винятком.

Додавання коду Rust до Chromium

У деякому існуючому файлі Chromium BUILD.gn оголосіть rust_static_library:

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

Ви також можете додати deps на інших цілях Rust. Пізніше ми будемо використовувати це для залежності від стороннього коду.

Включаючи unsafe код Rust

Небезпечний Rust-код заборонено у rust_static_library за замовчуванням --- він не буде скомпільований. Якщо вам потрібен небезпечний Rust-код, додайте allow_unsafe = true до цілі gn. (Пізніше у курсі ми побачимо обставини, за яких це необхідно).

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

Залежнісь Chromium C++ від коду Rust

Просто додайте наведену вище ціль до deps деякої цілі Chromium C++.

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# or source_set, static_library etc.
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

Типи в Rust коді усуваються, що робить хорошу IDE ще більш корисною, ніж для C++. Код Visual Studio добре працює для Rust у Chromium. Щоб скористатися ним,

• Переконайтеся, що ваш VSCode має розширення rust-analyzer, а не більш ранні форми підтримки Rust
• gn gen out/Debug --export-rust-project (або еквівалент для вашого вихідного каталогу)
• ln -s out/Debug/rust-project.json rust-project.json

Вправа правил побудови

У вашій збірці Chromium додайте нову ціль Rust до файлу //ui/base/BUILD.gn, що містить:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("Привіт від Rust!")
}
}

Важливо: зауважте, що no_mangle тут розглядається компілятором Rust як тип небезпеки, тому вам потрібно буде дозволити небезпечний код у вашій цілі gn.

Додайте цю нову ціль Rust як залежність від //ui/base:base. Оголосіть цю функцію у верхній частині файлу ui/base/resource/resource_bundle.cc (пізніше ми побачимо, як це можна автоматизувати за допомогою інструментів генерації прив'язок):

extern "C" void hello_from_rust();

Викличте цю функцію звідкись з ui/base/resource/resource_bundle.cc - радимо зверху ResourceBundle::MaybeMangleLocalizedString. Зберіть і запустіть Chromium, і переконайтеся, що "Hello from Rust!" виводиться багато разів.

Якщо ви використовуєте VSCode, налаштуйте Rust для роботи у VSCode. Це стане у нагоді у наступних вправах. Якщо вам це вдалося, ви зможете скористатися командою "Go to definition" правою кнопкою миші на println!.

Де знайти допомогу

• Опції, доступні для rust_static_libraryшаблону gn
• Інформація про #[no_mangle]
• Інформація про extern "C"
• Інформація про перемикач --export-rust-project gn
• Як встановити rust-analyzer у VSCode

Тестування

Учасники спільноти Rust зазвичай пишуть модульні тести у модулі, розміщеному у тому самому вхідному файлі, що й код, який тестується. Це було розглянуто раніше у курсі і має такий вигляд:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

У Chromium ми розміщуємо модульні тести в окремому вхідному файлі і продовжуємо дотримуватися цієї практики для Rust --- це робить тести стабільно доступними для виявлення і допомагає уникнути повторної збірки .rs-файлів (у конфігурації test).

Це призводить до наступних варіантів тестування Rust-коду в Chromium:

• Нативні тести Rust (тобто #[test]). Не рекомендується використовувати поза //third_party/rust.
• Тести gtest, написані на C++, які виконують Rust за допомогою викликів FFI. Достатньо, коли код Rust є лише тонким прошарком FFI, а наявні модульні тести забезпечують достатнє покриття для функції.
• Тести gtest, написані на Rust, що використовують крейт який тестується через його публічний API (з використанням pub mod for_testing { ... }, якщо потрібно). Це тема наступних кількох слайдів.

Бібліотека rust_gtest_interop

Бібліотека rust_gtest_interop надає можливість для:

• Використовувати функцію Rust як тестовий приклад gtest (використовуючи атрибут #[gtest(...)])
• Використовувати expect_eq! та подібні макроси (подібні до assert_eq!, але не панікувати і не завершувати тест, коли твердження не спрацьовує).

Приклад:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Правила GN для тестів Rust

Найпростіший спосіб створити тести Rust gtest - це додати їх до існуючого тестового бінарного файлу, який вже містить тести, написані на C++. Наприклад:

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

Створення тестів Rust в окремій static_library також працює, але вимагає ручного оголошення залежності від допоміжних бібліотек:

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

Макрос chromium::import!

Після додавання :my_rust_lib до GN deps нам все ще потрібно навчитися імпортувати та використовувати my_rust_lib з my_rust_lib_unittest.rs. Ми не надали явного crate_name для my_rust_lib, тому його ім'я буде обчислено на основі повного шляху та імені. На щастя, ми можемо уникнути роботи з такою громіздкою назвою за допомогою макросу chromium::import! з автоматично імпортованого крейту chromium:

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

Під ковдрою макрос розширюється до чогось схожого на це:

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

Додаткову інформацію можна знайти у коментарі документації макросу chromium::import.

Тестова вправа

Час для наступної вправи!

У вашій збірці Chromium:

• Додайте тестову функцію поруч з hello_from_rust. Деякі пропозиції: додавання двох цілих чисел, отриманих як аргументи, обчислення n-го числа Фібоначчі, підсумовування цілих чисел у зрізі тощо.
• Додайте окремий файл ..._unittest.rs з тестом для нової функції.
• Додайте нові тести до BUILD.gn.
• Побудуйте тести, запустіть їх і перевірте, чи працює новий тест.

Взаємодія з C++

Спільнота Rust пропонує кілька варіантів взаємодії C++/Rust, при цьому постійно розробляються нові інструменти. Наразі у Chromium використовується інструмент під назвою CXX.

Ви описуєте всю вашу мовну границю мовою визначення інтерфейсів (яка дуже схожа на Rust), а потім інструменти CXX генерують оголошення для функцій і типів як на Rust, так і на C++.

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

Приклади прив'язок

CXX вимагає, щоб вся межа C++/Rust була оголошена в модулях cxx::bridge у вхідному коді .rs.

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// Визначення типів та функцій Rust можна знайти тут

Обмеження CXX

Безумовно, найбільш корисною сторінкою при використанні CXX є довідник типів.

CXX принципово підходить для випадків, коли:

• Ваш інтерфейс Rust-C++ достатньо простий, щоб ви могли оголосити все це.
• Ви використовуєте лише типи, які вже підтримуються CXX, наприклад, std::unique_ptr, std::string, &[u8] тощо.

Це має багато обмежень --- наприклад, відсутність підтримки типу Option у Rust.

Ці обмеження обмежують нас у використанні Rust у Chromium лише для добре ізольованих "листових вузлів", а не для довільної взаємодії Rust-C++. Розглядаючи варіанти використання Rust у Chromium, гарною відправною точкою є складання проекту прив'язки CXX для мовної межі, щоб побачити, чи виглядає він достатньо простим.

Обробка помилок в CXX

У CXX підтримка Result<T,E> покладається на винятки C++, тому ми не можемо використовувати її у Chromium. Альтернативи:

• Частина T у Result<T, E> може бути:

  • Повернута через вихідні параметри (наприклад, через &mut T). Для цього потрібно, щоб T можна було передати через межу FFI - наприклад, T має бути:
    • Примітивний тип (наприклад, u32 або usize)
    • Тип, що підтримується cxx (наприклад, UniquePtr<T>), який має відповідне значення за замовчуванням для використання у випадку невдачі (на відміну від Box<T>).
  • Збережена на стороні Rust та доступна за посиланням. Це може знадобитися, коли T є типом Rust, який не може бути переданий через межу FFI і не може бути збережений у UniquePtr<T>.

• Частина E у Result<T, E> може бути:

  • Повернута як булеве значення (наприклад, true означає успіх, а false - невдачу)
  • Збереження деталей помилок теоретично можливе, але поки що на практиці воно не було потрібне.

Обробка помилок CXX: Приклад з QR

Генератор QR-кодів - це приклад, де булеве значення використовується для передачі інформації про успіх чи невдачу, і де успішний результат може бути переданий через межу FFI:

#[cxx::bridge(namespace = "qr_code_generator")]
mod ffi {
    extern "Rust" {
        fn generate_qr_code_using_rust(
            data: &[u8],
            min_version: i16,
            out_pixels: Pin<&mut CxxVector<u8>>,
            out_qr_size: &mut usize,
        ) -> bool;
    }
}

Обробка помилок CXX: Приклад PNG

Прототип декодера PNG ілюструє, що можна зробити, коли успішний результат не може бути переданий через межу FFI:

#[cxx::bridge(namespace = "gfx::rust_bindings")]
mod ffi {
    extern "Rust" {
        /// Повертає дружній до FFI еквівалент `Result<PngReader<'a>,
        /// ()>`.
        fn new_png_reader<'a>(input: &'a [u8]) -> Box<ResultOfPngReader<'a>>;

        /// Зв'язування C++ для типу `crate::png::ResultOfPngReader`.
        type ResultOfPngReader<'a>;
        fn is_err(self: &ResultOfPngReader) -> bool;
        fn unwrap_as_mut<'a, 'b>(
            self: &'b mut ResultOfPngReader<'a>,
        ) -> &'b mut PngReader<'a>;

        /// Зв'язування C++ для типу `crate::png::PngReader`.
        type PngReader<'a>;
        fn height(self: &PngReader) -> u32;
        fn width(self: &PngReader) -> u32;
        fn read_rgba8(self: &mut PngReader, output: &mut [u8]) -> bool;
    }
}

Використання cxx у Chromium

У Chromium ми визначаємо незалежний #[cxx::bridge] mod для кожного листового вузла, де ми хочемо використовувати Rust. Зазвичай у вас буде по одному модулю для кожної rust_static_library. Просто додайте

cxx_bindings = [ "my_rust_file.rs" ]
   # список файлів, що містять #[cxx::bridge], не всі вхідні файли
allow_unsafe = true

до вашої існуючої цілі rust_static_ibrary разом з crate_root та sources.

C++ заголовки будуть згенеровані в доцільному місці, тому ви можете просто

#include "ui/base/my_rust_file.rs.h"

У //base ви знайдете деякі утиліти для перетворення типів Chromium C++ у типи CXX Rust --- наприклад SpanToRustSlice.

Вправа: Інтероперабельність з C++

Частина перша

• У створений раніше файл Rust додайте #[cxx::bridge], який визначає єдину функцію для виклику з C++ під назвою hello_from_rust, яка не отримує параметрів і не повертає жодного значення.
• Змініть вашу попередню функцію hello_from_rust, видаливши extern "C" і #[no_mangle]. Тепер це просто стандартна функція Rust.
• Змініть вашу ціль gn, щоб створити ці прив'язки.
• У вашому C++ коді видаліть форвардне оголошення hello_from_rust. Замість цього додайте згенерований заголовний файл.
• Будуємо і запускаємо!

Частина друга

Це гарна ідея - трохи погратися з CXX. Це допоможе вам зрозуміти, наскільки гнучким є Rust у Chromium.

Декілька речей, які варто спробувати:

• Зворотний виклик у C++ з Rust. Вам знадобиться:
  • Додатковий заголовний файл, який ви можете include! до вашого cxx::bridge. Вам потрібно буде оголосити вашу функцію C++ у цьому новому заголовному файлі.
  • unsafe блок для виклику такої функції, або вкажіть ключове слово unsafe у вашому #[cxx::bridge] як описано тут.
  • Вам також може знадобитися #include "third_party/rust/cxx/v1/crate/include/cxx.h"
• Передати рядок C++ з C++ у Rust.
• Передати в Rust посилання на об'єкт C++.
• Навмисно зробити так, щоб сигнатури функцій Rust не співпадали з #[cxx::bridge], і звикати до помилок, які ви побачите.
• Навмисно зробити так, щоб сигнатури функцій C++ не співпадали з #[cxx::bridge], і звикати до помилок, які ви побачите.
• Передати std::unique_ptr деякого типу з C++ у Rust, щоб Rust міг володіти деяким об'єктом C++.
• Створити об'єкт Rust і передати його в C++ так, щоб C++ володів ним. (Підказка: вам потрібен Box).
• Оголосити деякі методи на типі C++. Викликати їх з Rust.
• Оголосити декілька методів на типі Rust. Викликати їх з C++.

Частина третя

Тепер, коли ви розумієте сильні та слабкі сторони взаємодії CXX, подумайте про пару варіантів використання Rust у Chromium, де інтерфейс був би достатньо простим. Накидайте ескіз того, як ви могли б визначити цей інтерфейс.

Де знайти допомогу

• Довідник cxx зв'язувань
• rust_static_library шаблон gn

Додавання крейтів третіх сторін

Бібліотеки Rust називаються "крейтами" і знаходяться на crates.io. Для крейтів Rust дуже легко залежати один від одного. Так вони і роблять!