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

• У Debian/Ubuntu ви можете встановити Cargo, вихідний код Rust та Rust formatter за допомогою apt. Однак це може призвести до встановлення застарілої версії Rust і неочікуваної поведінки. Використовуйте таку команду:

  sudo apt install cargo rust-src rustfmt
  

Ключові моменти:

• У Rust стрімкий графік релізів: нова версія виходить кожні шість тижнів. Нові версії підтримують зворотну сумісність із старими версіями --- на додаток вони надають нові функціональні можливості.

• Існує три канали релізів: "stable", "beta" та "nightly".

• Нові функції тестуються на "nightly", "beta" це те, що стає "stable" кожні шість тижнів.

• Залежності також можна вирішити за допомогою альтернативних реєстрів, git, папок тощо.

• Rust також має [редакції]: поточна редакція це Rust 2021. Попередніми редакціями були Rust 2015 та Rust 2018.

  • Редакціям дозволено вносити зворотно-несумісні зміни до мови.

  • Щоб уникнути збоїв коду, редакцію для свого пакета можна явно вказати у файлі Cargo.toml.

  • Щоб уникнути поділу екосистеми, компілятор Rust може змішувати код, написаний для різних редакцій.

  • Варто нагадати, що використання компілятора безпосередньо, а не через cargo, є рідкісним явищем (більшість користувачів ніколи цього не роблять).

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

    • Структуру проекту/пакета
    • робочі області
    • Управління/кешування залежностями для розробки (dev) та часу виконання (runtime)
    • сценарії побудови
    • глобальна установка
    • Він також розширюється за допомогою плагінів підкоманд (таких як cargo clippy).

  • Докладніше читайте в офіційній Cargo Book

Більшість прикладів коду доступні для редагування, як показано вище. Кілька прикладів коду недоступні для редагування з різних причин:

• Вбудований у сторінку редактор коду не може запускати модульні тести. Скопіюйте код і відкрийте його в справжньому Playground, щоб продемонструвати модульні тести.

• Вбудовані в сторінку редактори коду втрачають свій стан у той момент, коли ви йдете зі сторінки! Саме з цієї причини учні повинні виконувати вправи, використовуючи локальну установку Rust або Rust Playground.

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

Будь ласка, нагадайте учням, що:

• Вони повинні задавати питання, коли вони їх мають, а не зберігати їх до кінця.
• Клас має на меті бути інтерактивним, тому дискусії дуже заохочуються!
  • Як інструктор, ви повинні намагатися підтримувати обговорення актуальними, тобто підтримувати обговорення, пов’язані з тим, як Rust щось робить на відміну від іншої мови. Буває важко знайти правильний баланс, але краще дозволити дискусії, оскільки вони залучають людей набагато більше, ніж одностороннє спілкування.
• Запитання, швидше за все, означатимуть, що ми обговорюємо речі, які випереджають слайди.
  • Це цілком нормально! Повторення є важливою частиною навчання. Пам’ятайте, що слайди є лише підтримкою, і ви можете пропускати їх, якщо забажаєте.

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

Якщо ви викладаєте цей курс у класі, це гарний момент, щоб ознайомитися з розкладом. Зверніть увагу, що в кінці кожного сегмента є вправа, після якої слідує перерва. Плануйте розглянути рішення вправи після перерви. Час, вказаний тут, є рекомендацією для того, щоб тримати курс за розкладом. Не соромтеся бути гнучкими і вносити корективи за потреби!

Rust вписується в ту ж саму область, що й C++:

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

Не витрачайте тут багато часу. Всі ці пункти будуть розглянуті більш детально пізніше.

Обов’язково запитайте клас, з якими мовами вони мають досвід. Залежно від відповіді ви можете виділити різні особливості Rust:

• Досвід роботи з C або C++: Rust усуває цілий клас помилок виконання за допомогою засобу перевірки запозичень. Ви отримуєте продуктивність, як у C і C++, але у вас немає проблем із небезпекою пам’яті. Крім того, ви отримуєте сучасну мову з такими конструкціями, як зіставлення шаблонів і вбудоване керування залежностями.

• Досвід роботи з Java, Go, Python, JavaScript...: Ви отримуєте таку саму безпеку пам’яті, що й у цих мовах, а також подібне відчуття мови високого рівня. Крім того, ви отримуєте швидку та передбачувану продуктивність як C і C++ (без збиральника сміття), а також доступ низького рівня до апаратного забезпечення (якщо воно вам знадобиться)

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

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

Ключові моменти:

• Rust дуже схожий на інші традиціїні мови як C/C++/Java. Це навмисно, і він не намагається винайти щось заново, якщо це не є абсолютно необхідним.

• Rust сучасний із повною підтримкою таких речей, як Unicode.

• Rust використовує макроси для ситуацій, коли потрібно мати змінну кількість аргументів (немає перевантаження функцій).

• Макроси є «гігієнічними» що означає, що вони випадково не захоплюють ідентифікатори з області, у якій вони використовуються. Макроси Rust насправді лише [частково гігієнічні](https://veykril.github.io/tlborm/decl-macros/minutiae/hygiene .html).

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

• Відкоментуйте x = 20, щоб продемонструвати, що змінні за замовчуванням є незмінними. Додайте ключове слово mut, щоб дозволити зміну.

• Тут i32 - це тип змінної. Він має бути відомий під час компіляції, але виведення типів (розглядається пізніше) дозволяє програмісту у багатьох випадках не вказувати його.

Є кілька синтаксисів, які не показано вище:

• Усі підкреслення у числах можна опускати, вони призначені лише для розбірливості. Отже, 1_000 можна записати як 1000 (або 10_00), а 123_i64 можна записати як 123i64.

Це перший раз, коли ми бачимо функцію, відмінну від main, але її значення повинно бути зрозумілим: вона отримує три цілих числа і повертає ціле число. Функції буде розглянуто більш детально пізніше.

Арифметика дуже схожа на інші мови, зі схожими пріоритетами.

Як бути з переповненням цілих чисел? У мовах C та C++ переповнення цілих чисел зі знаком фактично не визначено, і може робити невідомі речі під час виконання. У Rust воно визначене.

Замініть i32 на i16, щоб побачити цілочисельне переповнення, яке панікує (перевіряється) у налагоджувальній збірці і загортається у релізній збірці. Існують і інші варіанти, такі як переповнення, перенасичення і перенесення. Доступ до них здійснюється за допомогою синтаксису методу, наприклад, (a * b).saturating_add(b * c).saturating_add(c * a).

Насправді, компілятор виявить переповнення константних виразів, тому приклад вимагає окремої функції.

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

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

Якщо тип цілочисельного літерала не обмежено, Rust за замовчуванням використовує тип i32. Іноді у повідомленнях про помилки це позначається як {integer}. Подібно до цього, літерали з плаваючою комою за замовчуванням мають тип f64.

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

Оскільки if є виразом і повинен мати певний тип, обидва його блоки розгалужень повинні мати той самий тип. Покажіть, що станеться, якщо додати ; після "маленький" у другому прикладі.

Коли у виразі використовується if, вираз повинен мати ;, щоб відокремити його від наступного оператора. Видаліть ; перед println!, щоб побачити помилку компілятора.

• Під капотом циклів for використовується концепція, яка називається "ітератори", для обробки ітерацій над різними типами діапазонів/колекцій. Ітератори буде розглянуто більш детально пізніше.
• Зверніть увагу, що перший цикл for виконує ітерацію тільки до 4. Покажіть синтаксис 1..=5 для включеного діапазону.

• Зауважте, що loop — це єдина конструкція циклу, яка повертає нетривіальне значення. Це тому, що він гарантовано буде введений принаймні один раз (на відміну від циклів while та for).

• Ви можете показати, як змінюється значення блоку, змінивши останній рядок у блоці. Наприклад, додаванням/видаленням крапки з комою або використанням return.

• Покажіть, що область видимості змінної обмежена, додавши b у внутрішньому блоці в останньому прикладі, а потім спробувавши отримати доступ до неї за межами цього блоку.
• Затінення відрізняється від мутації тим, що після затінення обидві ділянки пам'яті змінної існують одночасно. Обидві змінні доступні під одним і тим же ім'ям, залежно від того, де ви їх використовуєте у коді.
• Змінна затінення може мати інший тип.
• Затінення спочатку виглядає незрозумілим, але є зручним для збереження значень після .unwrap().

• Параметри оголошення супроводжуються типом (у зворотному порядку порівняно з деякими мовами програмування), а потім типом повернення.
• Останній вираз у тілі функції (або будь-якого блоку) стає значенням, що повертається. Просто опустіть ; в кінці виразу. Ключове слово return можна використовувати для дострокового повернення, але форма "голого значення" є ідіоматичною у кінці функції (рефактор gcd щоб використовувати return).
• Деякі функції не мають значення, що повертається, і повертають 'тип агрегату', (). Компілятор визначить це, якщо тип повернення -> () пропущено.
• Перевантаження не підтримується - кожна функція має єдину реалізацію.
  • Завжди приймає фіксовану кількість параметрів. Аргументи за замовчуванням не підтримуються. Для підтримки варіаційних функцій можна використовувати макроси.
  • Завжди приймає єдиний набір типів параметрів. Ці типи можуть бути загальними, що буде розглянуто пізніше.

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

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

• Значення типу масиву [T; N] містить N (константа часу компіляції) елементів того самого типу T. Зверніть увагу, що довжина масиву є частиною його типу, що означає, що [u8; 3] і [u8; 4] вважаються двома різними типами. Зрізи, розмір яких визначається під час виконання, покриваються пізніше.

• Спробуйте доступ до елементу масиву, що знаходиться за межами масиву. Доступ до масиву перевіряється під час виконання. Зазвичай Rust може оптимізувати ці перевірки, і їх можна уникнути, використовуючи небезпечний Rust.

• Ми можемо використовувати літерали для присвоєння значень масивам.

• Макрос println! запитує реалізацію налагодження за допомогою параметра формату ?: {} - виведення за замовчуванням, {:?} - виведення налагодження. Такі типи, як цілі числа і рядки, реалізують виведення за замовчуванням, але масиви реалізують лише виведення для налагодження. Це означає, що тут ми повинні використовувати налагоджувальний вивід.

• Додавання #, наприклад {a:#?}, викликає формат "гарного друку", який може бути легшим для читання.

• Як і масиви, кортежі мають фіксовану довжину.

• Кортежі групують значення різних типів у складений тип.

• Доступ до полів кортежу можна отримати після крапки з індексом значення, наприклад. t.0, t.1.

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

Ця функціональність використовує трейт IntoIterator, але ми ще не розглядали його.

Макрос assert_ne! тут новий. Існують також макроси assert_eq! та assert!. Вони завжди перевіряються під час виконання, варіанти лише для налагодження, такі як debug_assert!, не компілюються у релізних збірках.

• Шаблони, що використовуються тут, є "неспростовними", тобто компілятор може статично перевірити, що значення праворуч від = має таку саму структуру, як і шаблон.
• Ім'я змінної - це неспростовний шаблон, який завжди відповідає будь-якому значенню, тому ми також можемо використовувати let для оголошення однієї змінної.
• Rust також підтримує використання шаблонів в умовних операторах, що дозволяє виконувати порівняння на рівність і деструкцію одночасно. Ця форма порівняння шаблонів буде розглянута більш детально пізніше.
• Відредагуйте приклади вище, щоб показати помилку компілятора, коли шаблон не збігається зі значенням, що порівнюється.

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

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

• Rust не створює посилання автоматично - завжди потрібно використовувати &.

• У деяких випадках Rust виконує автоматичне розіменування, зокрема під час виклику методів (спробуйте r.is_ascii()). Тут не потрібен оператор ->, як у C++.

• У цьому прикладі r є мутабельним, тому його можна перепризначити (r = &b). Зверніть увагу, що це повторно зв'язує r, так що він посилається на щось інше. Це відрізняється від C++, де присвоювання посилання змінює значення, на яке воно посилається.

• Спільне посилання не дозволяє змінювати значення, на яке воно посилається, навіть якщо це значення було змінним. Спробуйте *r = 'X'.

• Rust відстежує час життя всіх посилань, щоб переконатися, що вони живуть достатньо довго. У безпечному Rust'і не може бути "висячих" посилань. Функція x_axis поверне посилання на point, але point буде звільнено, коли функція повернеться, тому це не буде скомпільовано.

• Про запозичення ми поговоримо більше, коли дійдемо до володіння.

Ключові моменти:

• "Ексклюзивне" означає, що тільки це посилання може бути використане для доступу до значення. Жодні інші посилання (спільні або ексклюзивні) не можуть існувати одночасно, і до значення, на яке посилаються, не можна отримати доступ, поки існує ексклюзивне посилання. Спробуйте створити &point.0 або змінити point.0, поки існує x_coord.

• Обов’язково зверніть увагу на різницю між let mut x_coord: &i32 і let x_coord: &mut i32. Перший представляє спільне посилання, яке можна прив'язати до різних значень, тоді як другий представляє ексклюзивне посилання на значення, що змінюється.

• Ми створюємо зріз, запозичуючи a та вказуючи початковий і кінцевий індекси в дужках.

• Якщо зріз починається з індексу 0, синтаксис діапазону Rust дозволяє нам відкинути початковий індекс, тобто &a[0..a.len()] і &a[..a.len()] ідентичні.

• Теж саме стосується останнього індексу, тому &a[2..a.len()] і &a[2..] ідентичні.

• Щоб легко створити повний зріз масиву, ми можемо використовувати &a[..].

• s є посиланням на зріз i32. Зверніть увагу, що тип s (&[i32]) більше не згадує довжину масиву. Це дозволяє нам виконувати обчислення на зрізах різного розміру.

• Зрізи завжди запозичуються з іншого об'єкта. У цьому прикладі a має залишатися 'живим' (в області застосування) принаймні стільки ж, скільки і наш зріз.

• Питання про модифікацію a[3] може викликати цікаву дискусію, але відповідь полягає в тому, що з міркувань безпеки пам’яті ви не можете зробити це через a на цьому етапі виконання, але ви можете читати дані з обох a і s безпечно. Це спрацьовує до того, як ви створили зріз, і знову після println, коли зріз більше не використовується.

• &str представляє зріз рядка, який є незмінним посиланням на дані рядка в кодуванні UTF-8, що зберігаються в блоці пам’яті. Рядкові літерали ("Hello") зберігаються у бінарному файлі програми.

• Тип String в Rust — це оболонка навколо вектора байтів. Як і у випадку з Vec<T>, він знаходиться у володінні.

• Як і у багатьох інших типів, String::from() створює рядок із рядкового літералу; String::new() створює новий порожній рядок, до якого дані рядка можна додати за допомогою методів push() і push_str().

• Макрос format!() є зручним способом створення рядка, яким володіють, з динамічних значень. Він приймає таку саму специфікацію формату, як і println!().

• Ви можете запозичувати зрізки &str з String за допомогою & і, за бажанням, вибору діапазону. Якщо ви виберете діапазон байт, який не вирівняно за межами символів, вираз запанікує. Ітератор chars перебирає символи, і йому надається перевага перед спробами вирівняти межі символів.

• Для програмістів на C++: думайте про &str як про std::string_view з C++, але такий, що завжди вказує на дійсний рядок у пам'яті. Rust String є приблизним еквівалентом std::string з C++ (головна відмінність: він може містити лише байти у кодуванні UTF-8 і ніколи не використовує оптимізацію малих рядків)..

• Літерали байтових рядків дозволяють створювати значення &[u8] безпосередньо:

  fn main() {
      println!("{:?}", b"abc");
      println!("{:?}", &[97, 98, 99]);
  }

• Необроблені рядки дозволяють створювати значення &str з відключеним екрануванням: r"\n" == "\\n". Ви можете вставити подвійні лапки, використовуючи однакову кількість # з обох боків лапок:

  fn main() {
      println!(r#"<a href="link.html">link</a>"#);
      println!("<a href=\"link.html\">link</a>");
  }

Ключові моменти:

• Структури працюють як у C або C++.
  • Як і в C++, і на відміну від C, для визначення типу не потрібен typedef.
  • На відміну від C++, між структурами немає успадкування.
• Це може бути вдалий час, щоб повідомити людям, що існують різні типи структур.
  • Структури нульового розміру (наприклад, struct Foo;) можуть бути використані при реалізації трейту на якомусь типі, але не мають даних, які ви хочете зберігати у самому значенні.
  • На наступному слайді буде представлено структури кортежу, які використовуються, коли імена полів не важливі.
• Якщо у вас уже є змінні з правильними іменами, ви можете створити структуру за допомогою скорочення:
• Синтаксис ..avery дозволяє нам скопіювати більшість полів зі старої структури без необхідності явного введення всіх полів. Це завжди має бути останнім елементом.

• Newtypes — чудовий спосіб закодувати додаткову інформацію про значення в примітивному типі, наприклад:
  • Число вимірюється в деяких одиницях: у наведеному вище прикладі Newtons.
  • Значення пройшло певну перевірку під час створення, тому вам більше не потрібно перевіряти його знову при кожному використанні: PhoneNumber(String) або OddNumber(u32).
• Продемонструйте, як додати значення f64 до типу Newtons, отримавши доступ до єдиного поля в newtype.
  • Rust зазвичай не любить неявних речей, таких як автоматичне розгортання або, наприклад, використання логічних значень як цілих чисел.
  • Перевантаження операторів обговорюється в день 3 (дженерики).
• Цей приклад є тонким посиланням на невдачу Mars Climate Orbiter.

Ключові моменти:

• Переліки дозволяють збирати набір значень під одним типом.
• Напрямок - це тип з варіантами. Існує два значення Direction: Direction::Left та Direction::Right.
• PlayerMove - це тип з трьома варіантами. На додаток до корисного навантаження, Rust зберігатиме дискримінант, щоб під час виконання знати, який варіант є у значенні PlayerMove.
• Це може бути гарний час для порівняння структури та переліки:
  • В обох ви можете мати просту версію без полів (структура одиниць) або з різними типами полів (різні варіанти корисного навантаження).
  • Ви навіть можете реалізувати різні варіанти переліку окремими структурами, але тоді вони не будуть одного типу, як якщо б всі вони були визначені в переліку.
• Rust використовує мінімальний обсяг пам'яті для зберігання дискримінанта.

  • Якщо потрібно, він зберігає ціле число найменшого необхідного розміру

  • Якщо допустимі значення варіантів не покривають усіх бітових шаблонів, для кодування дискримінанта буде використано неприпустимі бітові шаблони ("нішева оптимізація"). Наприклад, Option<&u8> зберігає або вказівник на ціле число, або NULL для варіанта None.

  • За потреби можна керувати дискримінантом (наприклад, для сумісності з C):

    #[repr(u32)]
    enum Bar {
        A, // 0
        B = 10000,
        C, // 10001
    }
    
    fn main() {
        println!("A: {}", Bar::A as u32);
        println!("B: {}", Bar::B as u32);
        println!("C: {}", Bar::C as u32);
    }

    Без repr тип дискримінанта займає 2 байти, оскільки 10001 вміщує 2 байти.

Більше інформації для вивчення

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

• Оптимізація нульового вказівника: для деяких типів Rust гарантує, що size_of::<T>() дорівнює size_of::<Option <T>>().

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

  use std::mem::transmute;
  
  macro_rules! dbg_bits {
      ($e:expr, $bit_type:ty) => {
          println!("- {}: {:#x}", stringify!($e), transmute::<_, $bit_type>($e));
      };
  }
  
  fn main() {
      unsafe {
          println!("bool:");
          dbg_bits!(false, u8);
          dbg_bits!(true, u8);
  
          println!("Option<bool>:");
          dbg_bits!(None::<bool>, u8);
          dbg_bits!(Some(false), u8);
          dbg_bits!(Some(true), u8);
  
          println!("Option<Option<bool>>:");
          dbg_bits!(Some(Some(false)), u8);
          dbg_bits!(Some(Some(true)), u8);
          dbg_bits!(Some(None::<bool>), u8);
          dbg_bits!(None::<Option<bool>>, u8);
  
          println!("Option<&i32>:");
          dbg_bits!(None::<&i32>, usize);
          dbg_bits!(Some(&0i32), usize);
      }
  }

• static схожий на мутабельні глобальні змінні в C++.
• static забезпечує ідентичність об’єкта: адресу в пам’яті та стан відповідно до типів із внутрішньою змінністю, таких як Mutex<T>.

Більше інформації для вивчення

Оскільки static змінні доступні з будь-якого потоку, вони повинні бути Sync. Внутрішня змінність можлива через Mutex, atomic або подібні до них.

Локальні дані потоку можна створити за допомогою макросу std::thread_local.

• Зауважте, що const поводиться семантично подібно до constexpr C++.
• Не так часто виникає потреба у константі, що обчислюється під час виконання, але це корисно та безпечніше, ніж використовувати static.

Програмісти на C впізнають це як схоже на typedef.

Ключові моменти:

• Ви можете вказати, як деякі конкретні символи використовуються в шаблоні

  • | як or
  • .. може розширюватися настільки, наскільки це потрібно
  • 1..=5 представляє включний діапазон
  • _ - символ підстановки

• Запобіжники зіставлення як окрема функція синтаксису є важливою та необхідною, коли ми хочемо стисло висловити більш складні ідеї, ніж це дозволили б самі шаблони.

• Це не те саме, що окремий вираз if всередині гілкі зіставлення. Вираз if всередині блоку розгалуження (після =>) виникає після вибору гілкі зіставлення. Невиконання умови if всередині цього блоку не призведе до розгляду інших частин вихідного виразу match.

• Умова, визначена в запобіжнику, застосовується до кожного виразу в шаблоні з |.

• Змініть значення літералів у foo, відповідно до інших шаблонів.
• Додайте нове поле до Foo і внесіть потрібні зміни до шаблону.
• Різницю між захопленням і постійним виразом може бути важко помітити. Спробуйте змінити 2 у другій гілці на змінну, і побачте, що це непомітно не працює. Змініть ії на const і подивіться, що це знову запрацює.

• Вираз if/else повертає перелік, який пізніше розпаковується за допомогою match.
• Ви можете спробувати додати третій варіант до визначення переліку і відобразити помилки під час виконання коду. Вкажіть місця, де ваш код зараз є невичерпним, і як компілятор намагається дати вам підказки.
• Доступ до значень у варіантах переліку можливий лише після зіставлення з шаблоном.
• Продемонструйте, що відбувається, коли пошук є невичерпним. Зверніть увагу на перевагу, яку надає компілятор Rust, підтверджуючи що всі випадки оброблено.
• Збережіть результат divide_in_two у змінній result і match його у циклі. Це не буде скомпільовано, оскільки при порівнянні споживається msg. Щоб виправити це, порівняйте &result замість result. Це зробить msg посиланням, тому його не буде використано. Ця "ергономіка співставлення" з'явилася у Rust 2018. Якщо ви хочете підтримувати попередні версії Rust, замініть msg на ref msg у шаблоні.

if-let

• На відміну від match, if let не має охоплювати всі гілки. Це може зробити його більш лаконічним, ніж match.
• Загальним використанням є обробка значень Some під час роботи з Option.
• На відміну від match, if let не підтримує захисні вирази для збігу шаблонів.

let-else

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

Переписана версія така:

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

while-let

• Зверніть увагу, що цикл while let триватиме, доки значення відповідає шаблону.
• Ви можете переписати цикл while let як нескінченний цикл з оператором if, який переривається, коли для name.pop() немає значення для розгортання. Цикл while let забезпечує синтаксичний цукор для наведеного вище сценарію.

Ключові моменти:

• Може бути корисно представити методи, порівнюючи їх із функціями.
  • Методи викликаються для екземпляра типу (такі як структура або перелік), перший параметр представляє екземпляр як self.
  • Розробники можуть використовувати методи, щоб скористатися перевагами синтаксису отримувача методів і допомогти їм бути більш організованими. Використовуючи методи, ми можемо зберігати весь код реалізації в одному передбачуваному місці.
• Зверніть увагу на використання ключового слова self, отримувача методу.
  • Покажіть, що це скорочений термін для self: Self і, можливо, покажіть, як можна також використовувати назву структури.
  • Поясніть, що Self — це псевдонім типу для типу, до якого входить блок impl, і його можна використовувати деінде в блоці.
  • Зауважте, що self використовується, як і інші структури, і крапкова нотація може використовуватися для посилання на окремі поля.
  • Це може бути гарний час, щоб продемонструвати, чим &self відрізняється від self, спробувавши запустити finish двічі.
  • Окрім варіантів self, існують також спеціальні типи обгорток, які можуть бути типами отримувачів, наприклад Box<Self>.

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

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

• Щоб реалізувати Trait для Type, ви використовуєте impl Trait for Type { .. } блок.

• На відміну від інтерфейсів Go, просто мати відповідні методи недостатньо: тип Cat з методом talk() не буде автоматично задовольняти Pet, якщо він не знаходиться у блоці impl Pet.

• Трейти можуть надавати реалізації за замовчуванням для деяких методів. Реалізації за замовчуванням можуть покладатися на всі методи трейту. У цьому випадку надається greet, який покладається на talk.

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

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

• Багато стандартних бібліотечних трейтів мають асоційовані типи, включаючи арифметичні оператори та Iterator.

Виведення реалізовано за допомогою макросів, і багато крейтів надають корисні макроси виведення для додавання корисної функціональності. Наприклад, serde може виводити підтримку серіалізації для структури за допомогою #[derive(Serialize)].

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

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

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

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

use std::fmt::Display;

pub trait Logger {
    /// Запишіть повідомлення із заданим рівнем докладності.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

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

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

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

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

Рішення

use std::fmt::Display;

pub trait Logger {
    /// Запишіть повідомлення із заданим рівнем докладності.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

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

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

/// Записуйте повідомлення лише до заданого рівня докладності.
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StderrLogger,
}

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

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

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

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, ("собака", 1), ("кіт", 2)));
}

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

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

#[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 або impl 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, але вказує на успіх або невдачу операції, кожен з яких має свій тип. Він подібний до Res, визначеного у вправі з виразами, але є узагальненим: 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), щоб полегшити перетворення типів:

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_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {
    println!("Виклик функції на {input}");
    func(input)
}

fn main() {
    let add_3 = |x| x + 3;
    println!("add_3: {}", apply_with_log(add_3, 10));
    println!("add_3: {}", apply_with_log(add_3, 20));

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

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    println!("multiply_sum: {}", apply_with_log(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, ...
  • Система виконання гарантує, що пам'ять не звільняється доти, доки до неї не можна буде звертатися.
  • Зазвичай реалізується за допомогою підрахунку посилань, збору сміття або RAII.

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

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

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

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

RefCell

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

Cell

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

use std::cell::Cell;

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

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

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

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

Ви почнете із заглушки функції у блоці 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);

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

Рішення

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

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

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

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,  -- не потрібно для цієї вправи
    /// 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 + 'a {
    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_string(&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
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("Очікувалося, що `i32` буде полем `I32`");
        };
        *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 PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

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

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,  -- не потрібно для цієї вправи
    /// 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 + 'a {
    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_string(&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
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("Очікувалося, що `i32` буде полем `I32`");
        };
        *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)
        }
        WireType::I32 => {
            if remainder.len() < 4 {
                panic!("Несподіваний EOF");
            }
            let (value, remainder) = remainder.split_at(4);
            // Помилка розгортання, оскільки `value` точно має довжину 4 байти.
            let value = i32::from_le_bytes(value.try_into().unwrap());
            (FieldValue::I32(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(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

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_string(),
            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_string(),
            2 => self.type_ = field.value.as_string(),
            _ => {} // пропустити все інше
        }
    }
}

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

Ласкаво просимо до Дня 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 15 minutes. It contains:

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

This segment should take about 1 hour. 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, "IO помилка: {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 та anyhow

Крейти thiserror та anyhow широко використовуються для спрощення обробки помилок.

• thiserror часто використовується у бібліотеках для створення користувацьких типів помилок, які реалізують From<T>.
• anyhow часто використовується програмами для полегшення обробки помилок у функціях, зокрема для додавання контекстної інформації до ваших помилок.

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:

/** Інтерфейс сервісу 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");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

Надсилання файлів

Файли можна надсилати між клієнтами/серверами 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 дуже легко залежати один від одного. Так вони і роблять!

Для інженера Chromium це має плюси та мінуси:

• Всі крейти використовують спільну систему збірки, тому ми можемо автоматизувати їхнє включення до Chromium ...
• ... але, як правило, крейти мають транзитивні залежності, тому вам, ймовірно, доведеться залучити декілька бібліотек.

Ми обговоримо:

• Як розмістити крейт у дереві вхідного коду Chromium
• Як зробити так, щоб gn будував правила для нього
• Як провести аудит його вхідного коду на предмет достатньої безпеки.

Налаштування файлу Cargo.toml для додавання крейтів

Chromium має єдиний набір централізовано керованих прямих залежностей крейтів. Вони управляються через єдиний Cargo.toml:

[dependencies]
bitflags = "1"
cfg-if = "1"
cxx = "1"
# lots more...

Як і для будь-якого іншого Cargo.toml, ви можете вказати більш детальну інформацію про залежності --- найчастіше, вам потрібно вказати features, які ви хочете увімкнути в крейті.

При додаванні крейту до Chromium вам часто потрібно надати додаткову інформацію у додатковому файлі gnrt_config.tml, з яким ми познайомимося далі.

Налаштування gnrt_config.toml

Поряд з Cargo.toml знаходиться gnrt_config.toml. Він містить специфічні для Chromium розширення для роботи з крейтами.

Якщо ви додаєте новий крейт, ви повинні вказати принаймні group. Це одна з них:

#   'safe': The library satisfies the rule-of-2 and can be used in any process.
#   'sandbox': The library does not satisfy the rule-of-2 and must be used in
#              a sandboxed process such as the renderer or a utility process.
#   'test': The library is only used in tests.

Наприклад,

[crate.my-new-crate]
group = 'test' # only used in test code

Залежно від компонування вхідного коду крейту, вам також може знадобитися використовувати цей файл, щоб вказати, де можна знайти його файл(и) LICENSE.

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

Завантаження крейтів

Інструмент під назвою gnrt знає, як завантажувати крейти і як генерувати правила BUILD.gn.

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