Мова програмування Rust

Стів Клабнік, Керол Ніколс і Кріс Крайчо, за участі спільноти Rust

Ця версія тексту передбачає, що ви використовуєте Rust 1.90.0 (випущений 2025-09-18) або новіший із edition = "2024" у файлі Cargo.toml усіх проєктів, щоб налаштувати їх на використання ідіом Rust 2024 Edition. Дивіться розділ “Встановлення” у Розділі 1 для інструкцій зі встановлення або оновлення Rust, а також Додаток E для інформації про редакції.

Формат HTML доступний онлайн за адресою https://doc.rust-lang.org/stable/book/ і офлайн у встановленнях Rust, зроблених за допомогою rustup; виконайте rustup doc --book, щоб відкрити.

Також доступні кілька спільнотних перекладів.

Цей текст доступний у друкованому та електронному форматах від No Starch Press.

🚨 Хочете більш інтерактивний досвід навчання? Спробуйте іншу версію Книги про Rust, яка містить: вікторини, підсвічування, візуалізації та більше: https://rust-book.cs.brown.edu

Передмова

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

На цьому етапі легко вказати на чудові можливості, які пропонує Rust, щоб пояснити цей вибух інтересу та впровадження. Хто ж не хоче безпеки пам’яті (memory safety), і швидкої продуктивності, і дружнього компілятора, і чудового інструментарію, серед безлічі інших чудових можливостей? Мова Rust, яку ви бачите сьогодні, поєднує роки досліджень у системному програмуванні з практичною мудрістю живої й захопленої спільноти. Цю мову було спроєктовано цілеспрямовано й створено дбайливо, пропонуючи розробникам інструмент, який полегшує написання безпечного, швидкого й надійного коду.

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

Це видання The Rust Programming Language є всеосяжним оновленням, яке відображає еволюцію мови протягом років і надає цінну нову інформацію. Але це не просто посібник із синтаксису та бібліотек — це запрошення приєднатися до спільноти, яка цінує якість, продуктивність і продуманий дизайн. Незалежно від того, чи ви досвідчений розробник, який хоче вперше спробувати Rust, чи досвідчений растацеанець (Rustacean), який хоче вдосконалити свої навички, це видання пропонує щось для кожного.

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

Ласкаво просимо до спільноти Rust!

• Bec Rumbul, виконавча директорка Rust Foundation

Вступ

Примітка: Це видання книги збігається з The Rust Programming Language, доступним у друкованому та електронному форматі від No Starch Press.

Ласкаво просимо до Мови програмування Rust — вступної книги про Rust. Мова програмування Rust допомагає писати швидше та надійніше програмне забезпечення. Висока ергономіка та низькорівневий контроль часто суперечать одне одному в дизайні мов програмування; Rust кидає виклик цьому протиріччю. Балансуючи між потужними технічними можливостями та чудовим досвідом розробника, Rust дає вам можливість контролювати низькорівневі деталі (наприклад, використання пам’яті) без усіх труднощів, традиційно пов’язаних з таким контролем.

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

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

Команди розробників

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

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

• Cargo, вбудований менеджер залежностей та інструмент збірки, робить додавання, компіляцію та управління залежностями безболісним та узгодженим у всій екосистемі Rust.
• Rustfmt забезпечує узгоджений стиль кодування серед розробників.
• rust-analyzer забезпечує інтеграцію з IDE для автодоповнення коду та вбудованих повідомлень про помилки.

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

Студенти

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

Компанії

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

Розробники відкритого програмного забезпечення

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

Люди, яким важлива швидкість та стабільність

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

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

Для кого призначена ця книга

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

Як користуватися цією книгою

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

У цій книзі ви знайдете два типи розділів: концептуальні розділи та проєктні розділи. У концептуальних розділах ви дізнаєтеся про аспект Rust. У проєктних розділах ми будуємо невеликі програми разом, застосовуючи те, що ви дізналися до цього часу. Розділи 2, 12 та 21 є проєктними розділами; решта — концептуальні.

Розділ 1 пояснює, як встановити Rust, як написати програму “Привіт, Світ!” та як використовувати Cargo, менеджер пакетів та інструмент збірки Rust. Розділ 2 є практичним вступом до написання програми на Rust, де ви будуєте гру в вгадування числа. Тут ми охоплюємо концепції на високому рівні, а пізніші розділи надають додаткові деталі. Якщо ви хочете одразу забруднити руки, Розділ 2 — це місце для цього. Розділ 3 охоплює функції Rust, схожі на функції інших мов програмування, а в Розділі 4 ви дізнаєтеся про систему володіння (ownership) Rust. Якщо ви особливо прискіпливий учень, який воліє вивчити кожну деталь перед тим, як рухатися далі, ви можете пропустити Розділ 2 і перейти безпосередньо до Розділу 3, повернувшись до Розділу 2, коли захочете попрацювати над проєктом, застосовуючи деталі, які ви вивчили.

Розділ 5 обговорює структури (structs) та методи (methods), а Розділ 6 охоплює переліки (enums), вирази match та конструкцію потоку управління if let. Ви будете використовувати структури та переліки для створення власних типів у Rust.

У Розділі 7 ви дізнаєтеся про систему модулів (modules) Rust та про правила приватності для організації вашого коду та його публічного інтерфейсу прикладного програмування (API). Розділ 8 обговорює деякі загальні структури даних колекцій, які надає стандартна бібліотека, такі як вектори (vectors), рядки (strings) та хеш-таблиці (hash maps). Розділ 9 досліджує філософію та техніки обробки помилок (error handling) Rust.

Розділ 10 заглиблюється в узагальнені типи (generics), трейти (traits) та часи життя (lifetimes), які дають вам можливість визначати код, що застосовується до кількох типів. Розділ 11 повністю присвячений тестуванню, яке навіть з гарантіями безпеки Rust необхідне для забезпечення правильної логіки вашої програми. У Розділі 12 ми будуємо власну реалізацію підмножини функціональності з інструменту командного рядка grep, який шукає текст у файлах. Для цього ми використаємо багато концепцій, які обговорювали в попередніх розділах.

Розділ 13 досліджує замикання (closures) та ітератори (iterators): функції Rust, що надходять з функціональних мов програмування. У Розділі 14 ми детальніше розглянемо Cargo та поговоримо про найкращі практики обміну вашими бібліотеками з іншими. Розділ 15 обговорює розумні вказівники (smart pointers), які надає стандартна бібліотека, та трейти, що забезпечують їх функціональність.

У Розділі 16 ми розглянемо різні моделі конкурентного програмування та поговоримо про те, як Rust допомагає вам програмувати в кількох потоках (threads) конкурентність без страху (fearless concurrency). Розділ 17 розширює це, розглядаючи синтаксис async/await та легку модель конкурентності, яку він підтримує.

Розділ 18 розглядає, як ідіоми Rust порівнюються з принципами об’єктно-орієнтованого програмування, з якими ви можете бути знайомі. Розділ 19 є довідником по шаблонах та зіставленню зі зразком (pattern matching), які є потужними способами вираження ідей у програмах на Rust. Розділ 20 містить різноманітні цікаві розширені теми, включаючи небезпечний Rust, макроси та більше про часи життя, трейти, типи, функції та замикання.

У Розділі 21 ми завершимо проєкт, в якому реалізуємо низькорівневий багатопотоковий веб-сервер!

Нарешті, деякі додатки містять корисну інформацію про мову у форматі довідника. Додаток А охоплює ключові слова Rust, Додаток Б охоплює оператори та символи Rust, Додаток В охоплює похідні трейти, що надаються стандартною бібліотекою Rust, Додаток Г охоплює деякі корисні інструменти розробки, а Додаток Д пояснює видання Rust. У Додатку Е ви можете знайти переклади книги, а в Додатку Є — деталі про те, як створюється Rust та що таке нічний Rust.

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

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

Ferris	Значення
	Цей код не компілюється!
	Цей код панікує!
	Цей код не виробляє бажаної поведінки.

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

Вихідний код

Вихідні файли, з яких генерується ця книга, можна знайти на GitHub.

Початок роботи

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

• Встановлення Rust у Linux, macOS і Windows
• Написання програми, яка друкує Hello, world!
• Використання cargo, менеджера пакетів і системи збирання Rust

Встановлення

Встановлення (Installation)

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

Примітка: якщо з якоїсь причини ви не хочете використовувати rustup, дивіться сторінку Other Rust Installation Methods для інших варіантів.

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

Позначення командного рядка

У цьому розділі та впродовж усієї книги ми показуватимемо деякі команди, які використовуються в терміналі. Рядки, які ви маєте вводити в терміналі, усі починаються з $. Вам не потрібно вводити символ $; це запрошення командного рядка, яке показує початок кожної команди. Рядки, що не починаються з $, зазвичай показують вивід попередньої команди. Крім того, приклади, специфічні для PowerShell, використовуватимуть > замість $.

Встановлення rustup на Linux або macOS

Якщо ви використовуєте Linux або macOS, відкрийте термінал і введіть таку команду:

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

Команда завантажує скрипт і запускає встановлення інструмента rustup, який встановлює останню стабільну версію Rust. Вас можуть попросити ввести пароль. Якщо встановлення успішне, з’явиться такий рядок:

Rust is installed now. Great!

Вам також знадобиться лінкер (linker), тобто програма, яку Rust використовує, щоб об’єднати свої скомпільовані результати в один файл. Імовірно, у вас уже є такий. Якщо ви отримаєте помилки лінкера, вам слід встановити компілятор C, який зазвичай міститиме лінкер. Компілятор C також корисний, тому що деякі поширені пакети Rust залежать від коду C і потребуватимуть компілятора C.

На macOS ви можете отримати компілятор C, запустивши:

$ xcode-select --install

Користувачам Linux зазвичай слід встановити GCC або Clang відповідно до документації їхнього дистрибутива. Наприклад, якщо ви використовуєте Ubuntu, ви можете встановити пакет build-essential.

Встановлення rustup на Windows

На Windows перейдіть на https://www.rust-lang.org/tools/install і дотримуйтеся інструкцій для встановлення Rust. На певному етапі встановлення вам запропонують встановити Visual Studio. Це надає лінкер (linker) і рідні бібліотеки, потрібні для компіляції програм. Якщо вам потрібна додаткова допомога з цим кроком, дивіться https://rust-lang.github.io/rustup/installation/windows-msvc.html.

У решті цієї книги використовуються команди, які працюють і в cmd.exe, і в PowerShell. Якщо існують специфічні відмінності, ми пояснимо, що саме використовувати.

Усунення неполадок

Щоб перевірити, чи правильно встановлено Rust, відкрийте shell і введіть цей рядок:

$ rustc --version

Ви маєте побачити номер версії, hash коміту та дату коміту для останньої стабільної версії, яка була випущена, у такому форматі:

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

Якщо ви бачите цю інформацію, Rust успішно встановлено! Якщо ви не бачите цю інформацію, перевірте, чи є Rust у вашій системній змінній %PATH% таким чином.

У Windows CMD використовуйте:

> echo %PATH%

У PowerShell використовуйте:

> echo $env:Path

У Linux і macOS використовуйте:

$ echo $PATH

Якщо все це правильно, а Rust усе ще не працює, є кілька місць, де ви можете отримати допомогу. Дізнайтеся, як зв’язатися з іншими растацеанцями (Rustaceans), на сторінці спільноти.

Оновлення та видалення

Після того як Rust встановлено через rustup, оновити його до нової випущеної версії легко. У вашому shell виконайте такий скрипт оновлення:

$ rustup update

Щоб видалити Rust і rustup, виконайте такий скрипт видалення у вашому shell:

$ rustup self uninstall

Читання локальної документації

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

У будь-який момент, коли тип або функція надаються стандартною бібліотекою, і ви не впевнені, що вони роблять або як їх використовувати, скористайтеся документацією інтерфейсу прикладного програмування (API), щоб з’ясувати це!

Використання текстових редакторів та IDE

Ця книга не робить жодних припущень щодо того, які інструменти ви використовуєте для написання коду Rust. Підійде майже будь-який текстовий редактор! Однак багато текстових редакторів і інтегрованих середовищ розробки (IDE (скорочено від англ. integrated development environment)) мають вбудовану підтримку Rust. Ви завжди можете знайти доволі актуальний список багатьох редакторів та IDE на сторінці інструментів на вебсайті Rust.

Робота з цією книгою офлайн

У кількох прикладах ми будемо використовувати пакети Rust поза стандартною бібліотекою. Щоб пройти ці приклади, вам або потрібно мати підключення до інтернету, або заздалегідь завантажити ці залежності. Щоб завантажити залежності заздалегідь, ви можете виконати такі команди. (Ми детально пояснимо, що таке cargo і що робить кожна з цих команд, пізніше.)

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

Це закешує завантаження для цих пакетів, тож вам не потрібно буде завантажувати їх пізніше. Після того як ви виконаєте цю команду, вам не потрібно зберігати папку get-dependencies. Якщо ви виконали цю команду, ви можете використовувати прапорець --offline з усіма командами cargo в решті книги, щоб використовувати ці кешовані версії замість спроби звернення до мережі.

Привіт, світ!

Привіт, світ! (Hello, World!)

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

Примітка: Ця книга припускає базове знайомство з командним рядком. Rust не висуває жодних спеціальних вимог до вашого редагування, інструментів або місця, де знаходиться ваш код, тож якщо ви віддаєте перевагу використанню IDE замість командного рядка, сміливо користуйтеся вашою улюбленою IDE. Багато IDE тепер мають певний рівень підтримки Rust; дивіться документацію IDE для деталей. Команда Rust зосередилася на забезпеченні чудової підтримки IDE через rust-analyzer. Див. Додаток D для отримання додаткових відомостей.

Налаштування каталогу проєкту

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

Відкрийте термінал і введіть такі команди, щоб створити каталог projects і каталог для проєкту “Hello, world!” всередині каталогу projects.

Для Linux, macOS і PowerShell у Windows введіть таке:

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

Для Windows CMD введіть таке:

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

Основи програми на Rust

Далі створіть новий файл вихідного коду й назвіть його main.rs. Файли Rust завжди закінчуються розширенням .rs. Якщо у назві файла ви використовуєте більше одного слова, прийнято розділяти їх за допомогою підкреслення. Наприклад, використовуйте hello_world.rs, а не helloworld.rs.

Тепер відкрийте файл main.rs, який ви щойно створили, і введіть код із Лістинга (Listing) 1-1.

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

Збережіть файл і поверніться до вікна термінала в каталозі ~/projects/hello_world. У Linux або macOS введіть такі команди, щоб скомпілювати й запустити файл:

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

У Windows введіть команду .\main замість ./main:

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

Незалежно від вашої операційної системи, рядок Hello, world! має надрукуватися в терміналі. Якщо ви не бачите цього виводу, поверніться до частини “Troubleshooting” розділу Встановлення (Installation), щоб дізнатися способи отримати допомогу.

Якщо Hello, world! дійсно надрукувалося, вітаємо! Ви офіційно написали програму на Rust. Це робить вас програмістом Rust — ласкаво просимо!

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

Давайте детально розглянемо цю програму “Hello, world!”. Ось перша частина головоломки:

fn main() {

}

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

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

Примітка: Якщо ви хочете дотримуватися стандартного стилю в усіх проєктах Rust, ви можете використовувати інструмент автоматичного форматування під назвою rustfmt, щоб форматувати ваш код у певному стилі (про rustfmt докладніше в Додатку D). Команда Rust включила цей інструмент до стандартного дистрибутива Rust, так само як і rustc, тож він уже має бути встановлений на вашому комп’ютері!

Тіло функції main містить такий код:

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

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

По-перше, println! викликає макрос Rust. Якби він викликав функцію, це було б записано як println (без !). Макроси Rust — це спосіб писати код, який створює код для розширення синтаксису Rust, і ми обговоримо їх докладніше в Розділі 20. Наразі вам достатньо знати, що використання ! означає, що ви викликаєте макрос замість звичайної функції, і що макроси не завжди слідують тим самим правилам, що й функції.

По-друге, ви бачите рядок "Hello, world!". Ми передаємо цей рядок як аргумент println!, і рядок виводиться на екран.

По-третє, ми закінчуємо рядок крапкою з комою (;), яка вказує, що цей вираз завершено, і наступний готовий початися. Більшість рядків коду Rust закінчуються крапкою з комою.

Компіляція та виконання

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

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

$ rustc main.rs

Якщо у вас є досвід роботи з C або C++, ви помітите, що це подібно до gcc або clang. Після успішної компіляції Rust виводить двійковий виконуваний файл.

У Linux, macOS і PowerShell у Windows ви можете побачити виконуваний файл, ввівши команду ls у вашій оболонці:

$ ls
main  main.rs

У Linux і macOS ви побачите два файли. У PowerShell у Windows ви побачите ті самі три файли, які побачили б, використовуючи CMD. У CMD у Windows ви ввели б таке:

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

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

$ ./main # or .\main on Windows

Якщо ваш main.rs — це програма “Hello, world!”, цей рядок виводить Hello, world! у ваш термінал.

Якщо ви краще знайомі з динамічною мовою, такою як Ruby, Python або JavaScript, ви можете бути не звиклі до компіляції та запуску програми як окремих кроків. Rust — це мова попередньої компіляції (ahead-of-time compiled), що означає, що ви можете скомпілювати програму й передати виконуваний файл комусь іншому, і ця людина зможе запустити його навіть без встановленого Rust. Якщо ви дасте комусь файл .rb, .py або .js, їм потрібно буде мати встановлену реалізацію Ruby, Python або JavaScript (відповідно). Але в цих мовах вам потрібна лише одна команда, щоб скомпілювати й запустити вашу програму. У дизайні мов завжди є компроміс.

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

Привіт, Cargo!

Привіт, Cargo! (Hello, Cargo!)

Cargo — це система збирання та менеджер пакетів Rust. Більшість растацеанців (Rustaceans) використовують цей інструмент для керування своїми проєктами Rust, тому що Cargo бере на себе багато завдань, таких як збирання вашого коду, завантаження бібліотек, від яких залежить ваш код, і збирання цих бібліотек. (Ми називаємо бібліотеки, які потрібні вашому коду, залежностями.)

Найпростіші програми Rust, як та, яку ми написали досі, не мають жодних залежностей. Якби ми зібрали проєкт “Hello, world!” за допомогою Cargo, він використовував би лише ту частину Cargo, яка відповідає за збирання вашого коду. У міру того як ви пишете складніші програми Rust, ви додаватимете залежності, і якщо ви почнете проєкт за допомогою Cargo, додавати залежності буде значно простіше.

Оскільки переважна більшість проєктів Rust використовує Cargo, решта цієї книги припускає, що ви теж використовуєте Cargo. Cargo встановлюється разом із Rust, якщо ви користувалися офіційними інсталяторами, про які йшлося в розділі “Встановлення (Installation)”. Якщо ви встановили Rust іншим способом, перевірте, чи встановлено Cargo, ввівши в терміналі таку команду:

$ cargo --version

Якщо ви бачите номер версії, він у вас є! Якщо ви бачите помилку, наприклад command not found, перегляньте документацію для вашого способу встановлення, щоб визначити, як встановити Cargo окремо.

Створення проєкту за допомогою Cargo

Давайте створимо новий проєкт за допомогою Cargo і подивимося, чим він відрізняється від нашого початкового проєкту “Hello, world!”. Поверніться до вашого каталогу projects (або до того місця, де ви вирішили зберігати свій код). Потім, на будь-якій операційній системі, виконайте таке:

$ cargo new hello_cargo
$ cd hello_cargo

Перша команда створює новий каталог і проєкт під назвою hello_cargo. Ми назвали наш проєкт hello_cargo, і Cargo створює його файли в каталозі з тією самою назвою.

Перейдіть до каталогу hello_cargo і виведіть список файлів. Ви побачите, що Cargo згенерував для нас два файли й один каталог: файл Cargo.toml і каталог src з файлом main.rs всередині.

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

Примітка: Git — поширена система керування версіями. Ви можете змінити cargo new, щоб використовувати іншу систему керування версіями або взагалі не використовувати її, за допомогою прапорця --vcs. Запустіть cargo new --help, щоб побачити доступні варіанти.

Відкрийте Cargo.toml у текстовому редакторі на ваш вибір. Він має виглядати подібно до коду в Лістингу (Listing) 1-2.

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

[dependencies]

Цей файл має формат TOML (Tom’s Obvious, Minimal Language), який є форматом конфігурації Cargo.

Перший рядок, [package], є заголовком розділу, що вказує, що наступні оператори налаштовують пакет. У міру того як ми додаватимемо більше інформації до цього файлу, ми додаватимемо й інші розділи.

Наступні три рядки задають інформацію конфігурації, яка потрібна Cargo для компіляції вашої програми: назву, версію та редакцію (edition) Rust, яку слід використовувати. Про ключ edition ми поговоримо в Додатку E.

Останній рядок, [dependencies], — це початок розділу, у якому ви можете перелічити будь-які залежності вашого проєкту. У Rust пакети коду називають крейтами (crates). Для цього проєкту нам не знадобляться інші крейти, але вони знадобляться в першому проєкті в Розділі 2, тож тоді ми використаємо цей розділ dependencies.

Тепер відкрийте src/main.rs і погляньте:

Ім’я файлу: src/main.rs

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

Cargo згенерував для вас програму “Hello, world!”, так само як ту, яку ми написали в Лістингу (Listing) 1-1! Поки що відмінності між нашим проєктом і проєктом, згенерованим Cargo, полягають у тому, що Cargo розмістив код у каталозі src, а в нас є файл конфігурації Cargo.toml у верхньому каталозі.

Cargo очікує, що ваші вихідні файли будуть розміщені всередині каталогу src. Каталог проєкту верхнього рівня призначений лише для файлів README, інформації про ліцензію, конфігураційних файлів і всього іншого, що не пов’язано з вашим кодом. Використання Cargo допомагає вам упорядковувати ваші проєкти. Для всього є своє місце, і все перебуває на своєму місці.

Якщо ви почали проєкт, який не використовує Cargo, як ми зробили з проєктом “Hello, world!”, ви можете перетворити його на проєкт, який використовує Cargo. Перемістіть код проєкту в каталог src і створіть відповідний файл Cargo.toml. Один простий спосіб отримати цей файл Cargo.toml — запустити cargo init, який створить його для вас автоматично.

Збирання та запуск проєкту Cargo

Тепер давайте подивимося, що змінюється, коли ми збираємо та запускаємо програму “Hello, world!” за допомогою Cargo! У вашому каталозі hello_cargo зберіть проєкт, ввівши таку команду:

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

Ця команда створює виконуваний файл у target/debug/hello_cargo (або target\debug\hello_cargo.exe на Windows), а не у вашому поточному каталозі. Оскільки стандартне збирання — це debug-збирання, Cargo поміщає бінарний файл у каталог із назвою debug. Ви можете запустити виконуваний файл цією командою:

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

Якщо все піде добре, Hello, world! має вивестися в термінал. Перший запуск cargo build також змушує Cargo створити новий файл на верхньому рівні: Cargo.lock. Цей файл відстежує точні версії залежностей у вашому проєкті. У цього проєкту немає залежностей, тож файл трохи порожній. Вам ніколи не потрібно буде змінювати цей файл вручну; Cargo керує його вмістом за вас.

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

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

Використовувати cargo run зручніше, ніж пам’ятати про необхідність спочатку запускати cargo build, а потім вказувати повний шлях до бінарного файлу, тому більшість розробників використовують cargo run.

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

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

Cargo також надає команду під назвою cargo check. Ця команда швидко перевіряє ваш код, щоб переконатися, що він компілюється, але не створює виконуваний файл:

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

Чому вам може не хотітися виконуваного файлу? Часто cargo check набагато швидший за cargo build, тому що він пропускає крок створення виконуваного файлу. Якщо ви постійно перевіряєте свою роботу під час написання коду, використання cargo check пришвидшить процес повідомлення вам про те, чи ваш проєкт і далі компілюється! Тому багато растацеанців (Rustaceans) періодично запускають cargo check у міру написання своєї програми, щоб переконатися, що вона компілюється. Потім вони запускають cargo build, коли готові використовувати виконуваний файл.

Давайте підсумуємо, що ми вже дізналися про Cargo:

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

Додатковою перевагою використання Cargo є те, що команди однакові незалежно від того, в якій операційній системі ви працюєте. Тож на цьому етапі ми більше не наводитимемо окремих інструкцій для Linux і macOS проти Windows.

Збирання для випуску

Коли ваш проєкт нарешті готовий до випуску, ви можете використати cargo build --release, щоб скомпілювати його з оптимізаціями. Ця команда створить виконуваний файл у target/release замість target/debug. Оптимізації змушують ваш код Rust працювати швидше, але їх увімкнення збільшує час, потрібний для компіляції вашої програми. Саме тому існують два різні профілі: один для розробки, коли ви хочете швидко і часто перебудовувати, і інший для збирання фінальної програми, яку ви передасте користувачу, яку не буде потрібно перебудовувати багато разів і яка працюватиме максимально швидко. Якщо ви вимірюєте час виконання вашого коду, обов’язково запускайте cargo build --release і виконуйте вимірювання з виконуваним файлом у target/release.

Використання конвенцій Cargo

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

Хоча проєкт hello_cargo простий, він уже використовує багато реальних інструментів, які ви використовуватимете протягом решти своєї кар’єри в Rust. Насправді, щоб працювати з будь-якими наявними проєктами, ви можете використовувати такі команди, щоб отримати код за допомогою Git, перейти до каталогу цього проєкту та зібрати його:

$ git clone example.org/someproject
$ cd someproject
$ cargo build

Більше інформації про Cargo дивіться в його документації.

Підсумок

Ви вже чудово почали свою подорож Rust! У цьому розділі ви дізналися, як:

• Встановити найновішу стабільну версію Rust за допомогою rustup.
• Оновитися до новішої версії Rust.
• Відкрити локально встановлену документацію.
• Написати та запустити програму “Hello, world!” безпосередньо за допомогою rustc.
• Створити та запустити новий проєкт, використовуючи конвенції Cargo.

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

Програмування гри у вгадування (Programming a Guessing Game)

Давайте зануримося в Rust, разом виконавши практичний проєкт! Цей розділ знайомить вас із кількома поширеними концепціями Rust, показуючи, як використовувати їх у реальній програмі. Ви дізнаєтеся про let, match, методи (methods), асоційовані функції (associated functions), зовнішні крейти (external crates) та багато іншого! У наступних розділах ми розглянемо ці ідеї детальніше. У цьому розділі ви просто потренуєте основи.

Ми реалізуємо класичну програму для початківців: гру у вгадування. Ось як вона працює: програма згенерує випадкове ціле число від 1 до 100. Потім вона запропонує гравцеві ввести припущення. Після введення припущення програма повідомить, чи є припущення надто малим або надто великим. Якщо припущення є правильним, гра надрукує вітальне повідомлення та завершиться.

Налаштування нового проєкту (Setting Up a New Project)

Щоб налаштувати новий проєкт, перейдіть до каталогу projects, який ви створили в Розділі 1, і створіть новий проєкт за допомогою Cargo, ось так:

$ cargo new guessing_game
$ cd guessing_game

Перша команда, cargo new, бере назву проєкту (guessing_game) як перший аргумент. Друга команда змінює каталог на каталог нового проєкту.

Подивіться на згенерований файл Cargo.toml:

Filename: Cargo.toml

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

[dependencies]

Як ви бачили в Розділі 1, cargo new генерує для вас програму “Hello, world!”. Подивіться на файл src/main.rs:

Filename: src/main.rs

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

Тепер давайте скомпілюємо цю програму “Hello, world!” і запустимо її на тому ж кроці, використовуючи команду cargo run:

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

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

Знову відкрийте файл src/main.rs. Ви писатимете весь код у цьому файлі.

Обробка припущення (Processing a Guess)

Перша частина програми гри у вгадування попросить у користувача введення, обробить це введення та перевірить, що введення має очікувану форму. Для початку ми дозволимо гравцеві ввести припущення. Введіть код із Лістинга (Listing) 2-1 у src/main.rs.

use std::io;

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

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

    let mut guess = String::new();

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

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

Цей код містить багато інформації, тож розглянемо його рядок за рядком. Щоб отримати введення користувача, а потім надрукувати результат як виведення, нам потрібно внести бібліотеку введення/виведення io в область видимості. Бібліотека io походить зі стандартної бібліотеки, відомої як std:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

Як ви бачили в Розділі 1, функція main є точкою входу в програму:

use std::io;

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

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

    let mut guess = String::new();

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

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

Синтаксис fn оголошує нову функцію; дужки () вказують, що немає параметрів; а фігурна дужка { починає тіло функції.

Як ви також дізналися в Розділі 1, println! — це макрос, який друкує рядок на екран:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

Зберігання значень у змінних (Storing Values with Variables)

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

use std::io;

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

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

    let mut guess = String::new();

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

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

Тепер програма стає цікавішою! У цьому маленькому рядку відбувається багато чого. Ми використовуємо оператор let, щоб створити змінну. Ось ще один приклад:

let apples = 5;

Цей рядок створює нову змінну з іменем apples і зв’язує її зі значенням 5. У Rust змінні за замовчуванням є незмінними (immutable), тобто після того, як ми надаємо змінній значення, це значення не змінюватиметься. Ми детально обговоримо цю концепцію в розділі “Змінні та змінність (Variables and Mutability)” Розділу 3. Щоб зробити змінну змінною, ми додаємо mut перед іменем змінної:

let apples = 5; // immutable
let mut bananas = 5; // mutable

Примітка: Синтаксис // починає коментар, який триває до кінця рядка. Rust ігнорує все в коментарях. Ми детальніше обговоримо коментарі в Розділі 3.

Повертаючись до програми гри у вгадування, ви тепер знаєте, що let mut guess введе змінну guess, яка є змінною. Знак рівності (=) каже Rust, що ми хочемо щось прив’язати до змінної зараз. Праворуч від знака рівності знаходиться значення, до якого прив’язується guess, а саме результат виклику String::new, функції, яка повертає новий екземпляр String. String — це тип рядка, який надається стандартною бібліотекою та є текстом змінної довжини, закодованим у UTF-8.

Синтаксис :: у рядку ::new вказує, що new є асоційованою функцією типу String. Асоційована функція — це функція, яка реалізована для типу, у цьому випадку String. Ця функція new створює новий, порожній рядок. Ви знайдете функцію new у багатьох типах, тому що це поширена назва для функції, яка створює нове значення певного виду.

У повному вигляді рядок let mut guess = String::new(); створив змінну, яка наразі прив’язана до нового, порожнього екземпляра String. Ух!

Отримання введення від користувача (Receiving User Input)

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

use std::io;

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

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

    let mut guess = String::new();

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

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

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

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

Символ & вказує, що цей аргумент є посиланням, яке дає вам спосіб дозволити кільком частинам вашого коду отримувати доступ до одного фрагмента даних без потрібності копіювати ці дані в пам’ять багато разів. Посилання — це складна можливість, і однією з головних переваг Rust є те, наскільки безпечно та легко використовувати посилання. Вам не потрібно знати багато з цих деталей, щоб завершити цю програму. Наразі все, що вам потрібно знати, це те, що, як і змінні, посилання є незмінними за замовчуванням. Отже, вам потрібно писати &mut guess замість &guess, щоб зробити його змінним. (Розділ 4 пояснить посилання детальніше.)

Обробка можливої помилки за допомогою Result (Handling Potential Failure with the Result Type)

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

use std::io;

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

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

    let mut guess = String::new();

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

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

Ми могли б записати цей код так:

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

Однак один довгий рядок важко читати, тому краще його розбити. Часто доцільно вставити новий рядок та інші пробіли, щоб допомогти розбити довгі рядки, коли ви викликаєте метод із синтаксисом .method_name(). Тепер давайте обговоримо, що робить цей рядок.

Як уже згадувалося раніше, read_line кладе все, що користувач вводить, у рядок, який ми йому передаємо, але він також повертає значення Result. Result — це перелік (enum (скорочено від enumeration)), який часто називають переліком, і це тип, який може перебувати в одному з кількох можливих станів. Кожен можливий стан ми називаємо варіантом.

Розділ 6 детальніше розгляне enum. Призначення цих типів Result — кодувати інформацію про обробку помилок.

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

Значення типу Result, як і значення будь-якого типу, мають визначені для них методи. Екземпляр Result має expect method який ви можете викликати. Якщо цей екземпляр Result є значенням Err, expect призведе до аварійного завершення програми та покаже повідомлення, яке ви передали як аргумент до expect. Якщо метод read_line повертає Err, це, ймовірно, буде результатом помилки, що надходить від базової операційної системи. Якщо цей екземпляр Result є значенням Ok, expect візьме значення, яке містить Ok, і поверне вам лише це значення, щоб ви могли його використати. У цьому випадку це значення — кількість байтів у введенні користувача.

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

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

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

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

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

Виведення значень з місцезаповнювачами println!

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

use std::io;

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

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

    let mut guess = String::new();

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

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

Цей рядок друкує рядок, який тепер містить введення користувача. Пара {} з фігурних дужок — це місцезаповнювач: уявіть {} як маленькі клешні краба, які утримують значення на місці. Під час друку значення змінної, ім’я змінної може бути всередині фігурних дужок. Під час друку результату обчислення виразу, поставте порожні фігурні дужки у форматний рядок, а потім допишіть після форматного рядка список виразів, розділених комами, які потрібно надрукувати в кожному порожньому місцезаповнювачі у тому самому порядку. Друк змінної та результату виразу в одному виклику println! виглядав би так:

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

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

Цей код надрукував би x = 5 and y + 2 = 12.

Тестування першої частини (Testing the First Part)

Давайте протестуємо першу частину гри у вгадування. Запустіть її за допомогою cargo run:

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

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

Генерування секретного числа (Generating a Secret Number)

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

Розширення функціональності за допомогою крейта (Using a Crate to Get More Functionality)

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

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

Filename: Cargo.toml

[dependencies]
rand = "0.8.5"

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

Cargo вважає ці версії сумісними з публічними API версії 0.8.5, і цей запис гарантує, що ви отримаєте останній патч-реліз, який усе ще скомпілюється з кодом у цьому розділі. Будь-яка версія 0.9.0 або вища не гарантується як така, що має той самий API, який використовують наведені нижче приклади.

Тепер, не змінюючи жодного рядка коду, давайте зберемо проєкт, як показано в Лістингу (Listing) 2-2.

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

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

Коли ми додаємо зовнішню залежність, Cargo отримує останні версії всього, що цій залежності потрібно, із registry, яка є копією даних з Crates.io. Crates.io — це місце, де люди в екосистемі Rust публікують свої проєкти з відкритим кодом на Rust, щоб інші могли ними користуватися.

Після оновлення registry Cargo перевіряє розділ [dependencies] і завантажує будь-які перелічені крейти, які ще не завантажено. У цьому випадку, хоча ми перелічили лише rand як залежність, Cargo також підтягнув інші крейти, від яких rand залежить для роботи. Після завантаження крейтів Rust компілює їх, а потім компілює проєкт із доступними залежностями.

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

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

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

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

Забезпечення відтворюваних збірок (Ensuring Reproducible Builds with the Cargo.lock File)

У Cargo є механізм, який гарантує, що ви зможете перебудувати той самий артефакт щоразу, коли ви або хтось інший збирає ваш код: Cargo використовуватиме лише версії залежностей, які ви вказали, доки ви не вкажете інше. Наприклад, скажімо, що наступного тижня виходить версія 0.8.6 крейта rand, і ця версія містить важливе виправлення помилки, але також містить регресію, яка зламає ваш код. Щоб вирішити це, Rust створює файл Cargo.lock під час першого запуску cargo build, тож тепер у каталозі guessing_game ми маємо цей файл.

Коли ви вперше збираєте проєкт, Cargo визначає всі версії залежностей, що відповідають критеріям, а потім записує їх у файл Cargo.lock. Коли ви збираєте свій проєкт у майбутньому, Cargo побачить, що файл Cargo.lock існує, і використовуватиме вказані там версії замість того, щоб знову виконувати всю роботу з визначення версій. Це дає вам можливість автоматично мати відтворювану збірку. Іншими словами, ваш проєкт залишатиметься на 0.8.5, доки ви явно не оновите його, завдяки файлу Cargo.lock. Оскільки файл Cargo.lock важливий для відтворюваних збірок, його часто додають до системи керування вихідним кодом разом з рештою коду вашого проєкту.

Оновлення крейта, щоб отримати нову версію (Updating a Crate to Get a New Version)

Коли ви дійсно хочете оновити крейт, Cargo надає команду update, яка ігноруватиме файл Cargo.lock і визначатиме всі останні версії, що відповідають вашим специфікаціям у Cargo.toml. Потім Cargo запише ці версії у файл Cargo.lock. В іншому випадку, за замовчуванням, Cargo шукатиме лише версії більші за 0.8.5 і менші за 0.9.0. Якщо крейт rand випустив дві нові версії 0.8.6 і 0.999.0, ви побачили б таке, якби запустили cargo update:

$ cargo update
    Updating crates.io index
     Locking 1 package to latest Rust 1.85.0 compatible version
    Updating rand v0.8.5 -> v0.8.6 (available: v0.999.0)

Cargo ігнорує реліз 0.999.0. На цьому етапі ви також помітили б зміну у вашому файлі Cargo.lock, що вказує, що версія крейта rand, яку ви тепер використовуєте, — 0.8.6. Щоб використовувати версію rand 0.999.0 або будь-яку версію в серії 0.999.x, вам потрібно було б оновити файл Cargo.toml так, щоб він виглядав ось так (не робіть цього насправді, тому що наведені нижче приклади припускають, що ви використовуєте rand 0.8):

[dependencies]
rand = "0.999.0"

Наступного разу, коли ви запустите cargo build, Cargo оновить реєстр доступних крейтів і повторно оцінить ваші вимоги до rand відповідно до нової версії, яку ви вказали.

Є ще багато що сказати про Cargo та його екосистему, про що ми поговоримо в Розділі 14, але поки що це все, що вам потрібно знати. Cargo дуже полегшує повторне використання бібліотек, тож растацеанці (Rustaceans) можуть писати менші проєкти, які складаються з низки пакетів.

Генерування випадкового числа (Generating a Random Number)

Давайте почнемо використовувати rand, щоб згенерувати число для вгадування. Наступний крок — оновити src/main.rs, як показано в Лістингу (Listing) 2-3.

use std::io;

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

Спочатку ми додаємо рядок use rand::Rng;. Трейт Rng визначає методи, які реалізують генератори випадкових чисел, і цей трейт має бути в області видимості, щоб ми могли використовувати ці методи. Розділ 10 детально розгляне трейт.

Далі ми додаємо два рядки посередині. У першому рядку ми викликаємо функцію rand::thread_rng, яка дає нам конкретний генератор випадкових чисел, який ми використовуватимемо: той, що локальний для поточного потоку виконання і ініціалізується операційною системою. Потім ми викликаємо метод gen_range на генераторі випадкових чисел. Цей метод визначений трейтом Rng, який ми внесли в область видимості за допомогою оператора use rand::Rng;. Метод gen_range бере вираз діапазону як аргумент і генерує випадкове число в цьому діапазоні. Тип виразу діапазону, який ми використовуємо тут, має форму start..=end і є включним як для нижньої, так і для верхньої межі, тож нам потрібно вказати 1..=100, щоб запросити число від 1 до 100.

Примітка: Ви не просто знатимете, які трейтів використовувати і які методи та функції викликати з крейта, тож кожен крейт має документацію з інструкціями щодо використання. Ще однією зручністю Cargo є те, що запуск команди cargo doc --open збудує документацію, надану всіма вашими залежностями, локально і відкриє її у вашому браузері. Якщо вам, наприклад, цікава інша функціональність у крейті rand, запустіть cargo doc --open і клацніть rand у бічній панелі ліворуч.

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

Спробуйте запустити програму кілька разів:

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

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

Ви повинні отримати різні випадкові числа, і всі вони мають бути числами від 1 до 100. Чудова робота!

Порівняння припущення із секретним числом (Comparing the Guess to the Secret Number)

Тепер, коли у нас є введення користувача і випадкове число, ми можемо їх порівняти. Цей крок показано в Лістингу (Listing) 2-4. Зверніть увагу, що цей код ще не скомпілюється, як ми зараз пояснимо.

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

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

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

Спочатку ми додаємо ще один оператор use, вносячи в область видимості тип під назвою std::cmp::Ordering зі стандартної бібліотеки. Тип Ordering — це ще один перелік (enum) і має варіанти Less, Greater і Equal. Це три результати, які можливі, коли ви порівнюєте два значення.

Потім ми додаємо п’ять нових рядків унизу, які використовують тип Ordering. Метод cmp порівнює два значення і може бути викликаний на будь-чому, що можна порівняти. Він бере посилання на те, з чим ви хочете порівняти: тут він порівнює guess із secret_number. Потім він повертає варіант enum Ordering, який ми внесли в область видимості за допомогою оператора use. Ми використовуємо вираз match, щоб вирішити, що робити далі, залежно від того, який варіант Ordering був повернутий із виклику cmp зі значеннями в guess і secret_number.

Вираз match складається з гілок. Гілка складається із шаблону для зіставлення та коду, який слід виконати, якщо значення, передане до match, відповідає шаблону цієї гілки. Rust бере значення, передане до match, і послідовно перевіряє шаблон кожної гілки. Шаблони та конструкція match — це потужні можливості Rust: вони дають вам змогу виражати різноманітні ситуації, з якими може зіткнутися ваш код, і гарантують, що ви обробите їх усі. Ці можливості будуть детально розглянуті в Розділі 6 і Розділі 19 відповідно.

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

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

Однак код у Лістингу (Listing) 2-4 ще не скомпілюється. Давайте спробуємо:

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

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

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

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

Filename: src/main.rs

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

use rand::Rng;

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

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

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

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

    // --snip--

    let mut guess = String::new();

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

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

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

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

Цей рядок:

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

Ми створюємо змінну з іменем guess. Але зачекайте, хіба програма вже не має змінної з іменем guess? Має, але, на щастя, Rust дозволяє нам затінити попереднє значення guess новим. Затінення дозволяє нам повторно використовувати ім’я змінної guess замість того, щоб змушувати нас створювати дві унікальні змінні, такі як guess_str і guess, наприклад. Ми детальніше розглянемо затінення (shadowing) в Розділі 3, але наразі знайте, що цю можливість часто використовують, коли хочуть перетворити значення з одного типу в інший.

Ми прив’язуємо цю нову змінну до виразу guess.trim().parse(). guess у виразі посилається на початкову змінну guess, яка містила введення як рядок. Метод trim на екземплярі String видалить будь-які пробіли на початку і в кінці, що ми повинні зробити перед тим, як можемо перетворити рядок на u32, який може містити лише числові дані. Користувач має натиснути enter, щоб задовольнити read_line і ввести своє припущення, що додає символ нового рядка до рядка. Наприклад, якщо користувач вводить 5 і натискає enter, guess виглядає так: 5\n. \n означає “новий рядок”. (У Windows натискання enter призводить до символу повернення каретки і нового рядка, \r\n.) Метод trim усуває \n або \r\n, залишаючи лише 5.

Метод parse on strings перетворює рядок на інший тип. Тут ми використовуємо його, щоб перетворити рядок на число. Нам потрібно сказати Rust точний тип числа, який ми хочемо, використовуючи let guess: u32. Двокрапка (:) після guess каже Rust, що ми будемо анотувати тип змінної. Rust має кілька вбудованих числових типів; u32, який тут показано, — це беззнакове 32-бітне ціле число. Це хороший вибір за замовчуванням для невеликого додатного числа. Ви дізнаєтеся про інші числові типи в Розділі 3.

Крім того, анотація u32 у цьому прикладному програмному коді та порівняння з secret_number означає, що Rust також виведе, що secret_number має бути u32. Отже, тепер порівняння буде між двома значеннями одного типу!

Метод parse працюватиме лише з символами, які можна логічно перетворити на числа, тож він легко може спричиняти помилки. Якщо, наприклад, рядок містив A👍%, не було б способу перетворити це на число. Оскільки він може зазнати невдачі, метод parse повертає тип Result, так само як і метод read_line (обговорювався раніше в “Обробка можливої помилки за допомогою Result (Handling Potential Failure with the Result Type)”). Ми поводитимемося з цим Result так само, знову використавши метод expect. Якщо parse повертає варіант Err типу Result, тому що не зміг створити число з рядка, виклик expect аварійно завершить гру та надрукує повідомлення, яке ми йому дамо. Якщо parse може успішно перетворити рядок на число, він поверне варіант Ok типу Result, а expect поверне число, яке ми хочемо з значення Ok.

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

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

Чудово! Хоча перед припущенням були додані пробіли, програма все одно з’ясувала, що користувач вгадав 76. Запустіть програму кілька разів, щоб перевірити різну поведінку з різними типами введення: вгадайте число правильно, вгадайте число, яке надто велике, і вгадайте число, яке надто мале.

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

Дозволяємо кілька припущень за допомогою циклу (Allowing Multiple Guesses with Looping)

Ключове слово loop створює нескінченний цикл. Ми додамо цикл, щоб дати користувачам більше шансів відгадати число:

Filename: src/main.rs

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

use rand::Rng;

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

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

    // --snip--

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

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

        // --snip--


        let mut guess = String::new();

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

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

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

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

Як ви бачите, ми перемістили все від підказки введення припущення і далі в цикл. Обов’язково зробіть відступ у чотири додаткові пробіли для рядків усередині циклу і запустіть програму знову. Тепер програма буде знову і знову запитувати ще одне припущення, що насправді створює нову проблему. Схоже, користувач не може вийти!

Користувач завжди може перервати програму за допомогою комбінації клавіш ctrl-C. Але є ще один спосіб вирватися з цього ненажерливого монстра, як згадувалося в обговоренні parse у “Порівняння припущення із секретним числом”: якщо користувач вводить відповідь не числом, програма аварійно завершиться. Ми можемо скористатися цим, щоб дозволити користувачеві вийти, як показано тут:

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

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

Введення quit завершить гру, але, як ви помітите, так само завершить її і будь-яке інше невідповідне числу введення. Це, м’яко кажучи, неоптимально; ми хочемо, щоб гра також зупинялася, коли вгадано правильне число.

Вихід після правильного припущення (Quitting After a Correct Guess)

Давайте запрограмуємо гру завершуватися, коли користувач перемагає, додавши оператор break:

Filename: src/main.rs

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

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

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

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

        // --snip--

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

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

Обробка некоректного введення (Handling Invalid Input)

Щоб далі вдосконалити поведінку гри, замість аварійного завершення програми, коли користувач вводить нечислове значення, давайте зробимо так, щоб гра ігнорувала нечислове значення, щоб користувач міг продовжувати відгадувати. Ми можемо зробити це, змінивши рядок, де guess перетворюється зі String на u32, як показано в Лістингу (Listing) 2-5.

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

        // --snip--

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

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

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

        // --snip--

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

Ми переходимо від виклику expect до виразу match, щоб перейти від аварійного завершення при помилці до обробки помилки. Пам’ятайте, що parse повертає тип Result, а Result — це перелік (enum), який має варіанти Ok і Err. Тут ми використовуємо вираз match, як і з результатом Ordering методу cmp.

Якщо parse може успішно перетворити рядок на число, він поверне значення Ok, яке містить отримане число. Це значення Ok відповідатиме шаблону першої гілки, і вираз match просто поверне значення num, яке parse створив і поклав у значення Ok. Це число опиниться саме там, де ми хочемо, у новій змінній guess, яку ми створюємо.

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

Тепер усе в програмі має працювати як очікується. Давайте спробуємо:

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

Чудово! З одним маленьким фінальним налаштуванням ми завершимо гру у вгадування. Згадайте, що програма все ще друкує секретне число. Це добре працювало для тестування, але псує гру. Давайте видалимо println!, який виводить секретне число. Лістинг (Listing) 2-6 показує фінальний код.

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

use rand::Rng;

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

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

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

        let mut guess = String::new();

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

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

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

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

На цьому етапі ви успішно створили гру у вгадування. Вітаємо!

Підсумок (Summary)

Цей проєкт був практичним способом ознайомити вас із багатьма новими концепціями Rust: let, match, функції, використання зовнішніх крейтів, і багато чого ще. У наступних кількох розділах ви детальніше дізнаєтеся про ці концепції. Розділ 3 охоплює концепції, які є в більшості мов програмування, такі як змінні, типи даних і функції, та показує, як використовувати їх у Rust. Розділ 4 досліджує володіння (ownership), можливість, яка робить Rust відмінним від інших мов. Розділ 5 обговорює структури (structs) та синтаксис методів (methods), а Розділ 6 пояснює, як працюють переліки (enums).

Загальні концепції програмування (Common Programming Concepts)

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

Зокрема, ви дізнаєтеся про змінні (variables), базові типи (basic types), функції (functions), коментарі (comments) та потік управління (control flow). Ці основи будуть у кожній програмі Rust, і раннє їхнє вивчення дасть вам міцну основу, від якої можна відштовхуватися.

Ключові слова

Мова Rust має набір ключових слів, зарезервованих для використання лише мовою, так само, як і в інших мовах. Пам’ятайте, що ви не можете використовувати ці слова як назви змінних або функцій. Більшість ключових слів мають спеціальні значення, і ви використовуватимете їх для виконання різних завдань у ваших програмах Rust; деякі наразі не мають пов’язаної з ними функціональності, але зарезервовані для функціональності, яка може бути додана до Rust у майбутньому. Ви можете знайти список ключових слів у Додатку A.

Змінні та змінність (mutability)

Змінні та змінність (Variables and Mutability)

Як згадувалося в розділі «Зберігання значень зі змінними», за замовчуванням змінні є незмінними. Це — один із багатьох поштовхів, які Rust дає вам, щоб писати свій код так, щоб він використовував переваги безпеки та легкої конкурентності, які пропонує Rust. Однак у вас усе ще є можливість зробити ваші змінні змінними. Дослідимо, як і чому Rust заохочує вас надавати перевагу незмінності та чому інколи ви можете захотіти від цього відмовитися.

Коли змінна є незмінною, після того як значення прив’язано до імені, ви не можете змінити це значення. Щоб проілюструвати це, створіть новий проєкт під назвою variables у вашому каталозі projects, використавши cargo new variables.

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

Filename: src/main.rs

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

Збережіть і запустіть програму за допомогою cargo run. Ви маєте отримати повідомлення про помилку, пов’язану з незмінністю, як показано в цьому виводі:

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

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

Цей приклад показує, як компілятор допомагає вам знаходити помилки у ваших програмах. Помилки компілятора можуть дратувати, але насправді вони лише означають, що ваша програма ще не безпечно робить те, що ви хочете, щоб вона робила; вони не означають, що ви не є хорошим програмістом! Досвідчені растацеанці (Rustaceans) досі отримують помилки компілятора.

Ви отримали повідомлення про помилку cannot assign twice to immutable variable `x`, тому що спробували присвоїти друге значення незмінній змінній x.

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

Але змінність може бути дуже корисною і може зробити код зручнішим для написання. Хоча змінні за замовчуванням є незмінними, ви можете зробити їх змінними, додавши mut перед іменем змінної, як ви зробили в розділі 2. Додавання mut також передає намір майбутнім читачам коду, вказуючи, що інші частини коду змінюватимуть значення цієї змінної.

Наприклад, змінимо src/main.rs на таке:

Filename: src/main.rs

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

Коли ми запускаємо програму тепер, отримуємо таке:

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

Нам дозволено змінювати значення, прив’язане до x, з 5 на 6, коли використовується mut. Зрештою, вирішувати, використовувати змінність чи ні, — це залежить від вас і від того, що ви вважаєте найчіткішим у конкретній ситуації.

Оголошення констант (Declaring Constants)

Як і незмінні змінні, константи — це значення, які прив’язуються до імені і не можуть змінюватися, але між константами та змінними є кілька відмінностей.

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

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

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

Ось приклад оголошення константи:

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

Ім’я константи — THREE_HOURS_IN_SECONDS, а її значення встановлюється як результат множення 60 (кількості секунд у хвилині) на 60 (кількість хвилин у годині) на 3 (кількість годин, які ми хочемо порахувати в цій програмі). Умовність найменування констант у Rust полягає у використанні всіх великих літер із підкресленнями між словами. Компілятор здатний обчислювати обмежений набір операцій під час компіляції, що дає нам змогу записати це значення так, щоб його було легше зрозуміти й перевірити, замість того щоб встановлювати цю константу в значення 10,800. Дивіться розділ Rust Reference про обчислення констант для отримання додаткової інформації про те, які операції можна використовувати під час оголошення констант.

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

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

Затінення (Shadowing)

Як ви бачили в підручнику з гри у вгадування в розділі 2, ви можете оголосити нову змінну з тим самим іменем, що й попередня змінна. растацеанці (Rustaceans) кажуть, що перша змінна затінена другою, що означає, що друга змінна — це те, що компілятор бачитиме, коли ви використовуєте ім’я змінної. Фактично, друга змінна затінює першу, забираючи всі звернення до імені змінної собі, доки або вона сама не буде затінена, або не завершиться область видимості. Ми можемо затінити змінну, використавши те саме ім’я змінної та повторно використавши ключове слово let, як показано нижче:

Filename: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

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

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

Ця програма спочатку прив’язує x до значення 5. Потім вона створює нову змінну x, повторно записуючи let x =, беручи початкове значення та додаючи 1, так що значення x стає 6. Потім, у внутрішній області видимості, створеній фігурними дужками, третій оператор let також затінює x і створює нову змінну, множачи попереднє значення на 2, щоб надати x значення 12. Коли ця область видимості завершується, внутрішнє затінення закінчується, і x повертається до значення 6. Коли ми запускаємо цю програму, вона виведе таке:

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

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

Інша відмінність між mut і затіненням полягає в тому, що оскільки ми фактично створюємо нову змінну, коли знову використовуємо ключове слово let, ми можемо змінити тип значення, але повторно використати те саме ім’я. Наприклад, припустімо, що наша програма просить користувача показати, скільки пробілів він хоче між якимось текстом, вводячи символи пробілу, а потім ми хочемо зберегти це введення як число:

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

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

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

У повідомленні про помилку сказано, що нам не дозволено змінювати тип змінної:

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

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

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

Типи даних

Типи даних (Data Types)

Кожне значення в Rust має певний тип даних, який повідомляє Rust, який саме вид даних було вказано, щоб він знав, як працювати з цими даними. Ми розглянемо два підмножини типів даних: скалярні (scalar) та складені (compound).

Пам’ятайте, що Rust — це статично типізована мова, що означає, що вона має знати типи всіх змінних під час компіляції. Зазвичай компілятор може вивести, який тип ми хочемо використовувати, на основі значення та того, як ми його використовуємо. У випадках, коли можливі багато типів, наприклад, коли ми перетворювали String на числовий тип за допомогою parse у розділі “Порівняння припущення із секретним числом” у розділі 2, ми маємо додати анотацію типу, ось так:

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

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

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

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

Ви побачите різні анотації типів для інших типів даних.

Скалярні типи (Scalar Types)

Скалярний тип представляє одне значення. Rust має чотири основні скалярні типи: цілі числа, числа з рухомою комою, булеві (boolean) та символи. Ви можете впізнати їх з інших мов програмування. Давайте перейдемо до того, як вони працюють у Rust.

Цілі типи (Integer Types)

Ціле число — це число без дробової частини. Ми використовували один цілочисельний тип у розділі 2, тип u32. Це оголошення типу вказує, що значення, з яким воно пов’язане, має бути беззнаковим цілим числом (знакові цілочисельні типи починаються з i замість u), яке займає 32 біти пам’яті. Таблиця 3-1 показує вбудовані цілочисельні типи в Rust. Ми можемо використовувати будь-який із цих варіантів, щоб оголосити тип цілочисельного значення.

Таблиця 3-1: Цілочисельні типи в Rust

Кожен варіант може бути або знаковим, або беззнаковим і має явний розмір. Знаковий і беззнаковий стосуються того, чи можливо для числа бути від’ємним — іншими словами, чи потрібно числу мати знак із собою (знаковий), чи воно буде лише додатним і тому може бути представлене без знака (беззнаковий). Це як записувати числа на папері: коли знак має значення, число показується зі знаком плюс або мінус; однак коли можна безпечно припустити, що число додатне, воно показується без знака. Знакові числа зберігаються за допомогою представлення доповняльного коду (two’s complement).

Кожен знаковий варіант може зберігати числа від −(2^{n − 1}) до 2^{n − 1} − 1 включно, де n — це кількість бітів, яку використовує цей варіант. Отже, i8 може зберігати числа від −(2⁷) до 2⁷ − 1, що дорівнює від −128 до 127. Беззнакові варіанти можуть зберігати числа від 0 до 2ⁿ − 1, тому u8 може зберігати числа від 0 до 2⁸ − 1, що дорівнює від 0 до 255.

Крім того, типи isize і usize залежать від архітектури комп’ютера, на якому запущена ваша програма: 64 біти, якщо ви на 64-бітній архітектурі, і 32 біти, якщо ви на 32-бітній архітектурі.

Ви можете записувати цілочисельні літерали в будь-якій із форм, показаних у Таблиці 3-2. Зауважте, що числові літерали, які можуть належати до кількох числових типів, дозволяють суфікс типу, такий як 57u8, щоб позначити тип. Числові літерали також можуть використовувати _ як візуальний роздільник, щоб зробити число легшим для читання, наприклад 1_000, яке матиме те саме значення, що й 1000.

Таблиця 3-2: Цілочисельні літерали в Rust

Отже, як дізнатися, який цілочисельний тип використовувати? Якщо ви не впевнені, типові значення Rust зазвичай є хорошими точками для початку: цілочисельні типи за замовчуванням мають тип i32. Основна ситуація, у якій ви б використовували isize або usize, — це індексування деякої колекції.

Переповнення цілого числа

Припустімо, у вас є змінна типу u8, яка може містити значення від 0 до 255. Якщо ви спробуєте змінити змінну на значення поза цим діапазоном, наприклад 256, станеться переповнення цілого числа, що може призвести до однієї з двох поведінок. Коли ви компілюєте в режимі debug, Rust додає перевірки на переповнення цілого числа, які спричиняють паніку програми під час виконання, якщо це відбувається. Rust використовує термін панікування, коли програма завершується з помилкою; ми детальніше обговоримо паніку в розділі “Невідновлювані помилки з panic!” у розділі 9.

Коли ви компілюєте в режимі release з прапорцем --release, Rust не додає перевірки на переповнення цілого числа, які спричиняють паніку. Натомість, якщо відбувається переповнення, Rust виконує зациклення за доповняльним кодом (two’s complement wrap-around). Коротко кажучи, значення, більші за максимальне значення, яке може містити тип, “обертаються” до мінімального значення, яке може містити тип. У випадку u8 значення 256 стає 0, значення 257 стає 1, і так далі. Програма не панікуватиме, але змінна матиме значення, яке, ймовірно, не є тим, якого ви очікували. Покладатися на поведінку переповнення цілого числа як на зациклення (wrap-around) вважається помилкою.

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

• Обертати в усіх режимах за допомогою методів wrapping_*, таких як wrapping_add.
• Повернути значення None, якщо є переповнення, за допомогою методів checked_*.
• Повернути значення та булеве значення (boolean), що вказує, чи було переповнення, за допомогою методів overflowing_*.
• Насичуватися на мінімальному або максимальному значенні за допомогою методів saturating_*.

Типи з рухомою комою (Floating-Point Types)

Rust також має два примітивні типи для чисел з рухомою комою, які є числами з десятковими крапками. Типи з рухомою комою в Rust — це f32 і f64, які мають розмір 32 біти та 64 біти відповідно. Тип за замовчуванням — f64, тому що на сучасних CPU він приблизно такий самий швидкий, як f32, але здатний до більшої точності. Усі типи з рухомою комою є знаковими.

Ось приклад, який показує числа з рухомою комою в дії:

Ім’я файлу: src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

Числа з рухомою комою представлені відповідно до стандарту IEEE-754.

Числові операції (Numeric Operations)

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

Ім’я файлу: src/main.rs

fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

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

    // remainder
    let remainder = 43 % 5;
}

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

Булевий (boolean) тип (The Boolean Type)

Як і в більшості інших мов програмування, булевий (boolean) тип у Rust має два можливі значення: true і false. Булеві значення (boolean values) мають розмір один байт. Тип Boolean у Rust позначається за допомогою bool. Наприклад:

Ім’я файлу: src/main.rs

fn main() {
    let t = true;

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

Основний спосіб використання булевих значень (boolean values) — через умовні конструкції, такі як вираз if. Ми розглянемо, як працюють вирази if у Rust, у розділі “Керування потоком”.

Тип символу (The Character Type)

Тип char у Rust — це найпримітивніший алфавітний тип мови. Ось кілька прикладів оголошення значень char:

Ім’я файлу: src/main.rs

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

Зауважте, що ми вказуємо літерали char одинарними лапками, на відміну від рядкових літералів, які використовують подвійні лапки. Тип char у Rust має розмір 4 байти і представляє скалярне значення Unicode (Unicode scalar value), що означає, що він може представляти набагато більше, ніж лише ASCII. Літери з наголосами; китайські, японські та корейські символи; emoji; і пробіли нульової ширини — усе це є дійсними значеннями char у Rust. Скалярні значення Unicode (Unicode scalar values) знаходяться в діапазоні від U+0000 до U+D7FF і від U+E000 до U+10FFFF включно. Однак “символ” насправді не є концепцією в Unicode, тому ваша людська інтуїція щодо того, чим є “символ”, може не збігатися з тим, чим є char у Rust. Ми детально обговоримо цю тему в розділі “Зберігання тексту, закодованого в UTF-8, у рядках” у розділі 8.

Складені типи (Compound Types)

Складені типи можуть групувати кілька значень в один тип. Rust має два примітивні складені типи: кортежі та масиви.

Тип кортежу (The Tuple Type)

Кортеж — це загальний спосіб згрупувати разом певну кількість значень із різними типами в один складений тип. Кортежі мають фіксовану довжину: після оголошення вони не можуть збільшуватися або зменшуватися в розмірі.

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

Ім’я файлу: src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

Змінна tup прив’язується до всього кортежу, тому що кортеж вважається одним складеним елементом. Щоб отримати окремі значення з кортежу, ми можемо використати зіставлення зі зразком (pattern matching), щоб розпакувати значення кортежу, ось так:

Ім’я файлу: src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

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

Ця програма спочатку створює кортеж і прив’язує його до змінної tup. Потім вона використовує шаблон з let, щоб взяти tup і перетворити його на три окремі змінні, x, y і z. Це називається розпакуванням, тому що воно розбиває один кортеж на три частини. Нарешті, програма друкує значення y, яке дорівнює 6.4.

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

Ім’я файлу: src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

Ця програма створює кортеж x, а потім отримує доступ до кожного елемента кортежу, використовуючи відповідні індекси. Як і в більшості мов програмування, перший індекс у кортежі — 0.

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

Тип масиву (The Array Type)

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

Ми записуємо значення в масиві як список, розділений комами, всередині квадратних дужок:

Ім’я файлу: src/main.rs

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

Масиви корисні, коли ви хочете, щоб ваші дані були розміщені в стеку, так само як інші типи, які ми бачили дотепер, а не в купі (ми обговоримо стек і купу докладніше в Розділі 4) або коли ви хочете гарантувати, що у вас завжди є фіксована кількість елементів. Однак масив не настільки гнучкий, як тип вектора (vector). Вектор (vector) — це подібний тип колекції, наданий стандартною бібліотекою, якому дозволено збільшуватися або зменшуватися в розмірі, тому що його вміст живе в купі. Якщо ви не впевнені, чи використовувати масив або вектор (vector), швидше за все, вам слід використовувати вектор (vector). Розділ 8 докладніше обговорює вектори (vectors).

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

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

Ви записуєте тип масиву за допомогою квадратних дужок із типом кожного елемента, крапкою з комою, а потім кількістю елементів у масиві, ось так:

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

Тут i32 — це тип кожного елемента. Після крапки з комою число 5 вказує, що масив містить п’ять елементів.

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

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

Масив із назвою a міститиме 5 елементів, і всі вони спочатку будуть встановлені в значення 3. Це те саме, що написати let a = [3, 3, 3, 3, 3];, але більш стисло.

Доступ до елементів масиву (Accessing Array Elements)

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

Ім’я файлу: src/main.rs

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

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

У цьому прикладі змінна з назвою first отримає значення 1, тому що це значення з індексом [0] у масиві. Змінна з назвою second отримає значення 2 з індексу [1] у масиві.

Недійсний доступ до елемента масиву (Invalid Array Element Access)

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

Ім’я файлу: src/main.rs

use std::io;

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

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

    let mut index = String::new();

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

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

    let element = a[index];

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

Цей код успішно компілюється. Якщо ви запустите цей код за допомогою cargo run і введете 0, 1, 2, 3 або 4, програма виведе відповідне значення за цим індексом у масиві. Якщо натомість ви введете число за межами масиву, наприклад 10, ви побачите такий вивід:

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

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

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

Функції

Функції (Functions)

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

Код Rust використовує snake case як традиційний стиль для імен функцій і змінних, у якому всі літери є малими, а підкреслення розділяють слова. Ось програма, яка містить приклад визначення функції:

Filename: src/main.rs

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

    another_function();
}

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

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

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

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

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

Рядки виконуються в тому порядку, в якому вони з’являються у функції main. Спочатку друкується повідомлення “Hello, world!”, а потім викликається another_function і друкується її повідомлення.

Параметри (Parameters)

Ми можемо визначати функції так, щоб вони мали параметри (parameters), які є спеціальними змінними, що є частиною сигнатури функції. Коли функція має параметри, ви можете надати їй конкретні значення для цих параметрів. Технічно, конкретні значення називаються аргументами (arguments), але в повсякденному спілкуванні люди, як правило, використовують слова параметр і аргумент взаємозамінно як для змінних у визначенні функції, так і для конкретних значень, переданих під час виклику функції.

У цій версії another_function ми додаємо parameter:

Filename: src/main.rs

fn main() {
    another_function(5);
}

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

Спробуйте запустити цю програму; ви повинні отримати такий вивід:

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

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

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

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

Filename: src/main.rs

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

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

Цей приклад створює функцію з іменем print_labeled_measurement із двома параметрами. Перший параметр має ім’я value і є i32. Другий має ім’я unit_label і має тип char. Потім функція друкує текст, що містить і value, і unit_label.

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

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

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

Оператори та вирази (Statements and Expressions)

Тіла функцій складаються з послідовності операторів, які за бажанням завершуються виразом. Поки що функції, які ми розглядали, не містили кінцевого виразу, але ви бачили вираз як частину оператора. Оскільки Rust є мовою на основі виразів, це важлива відмінність, яку потрібно розуміти. В інших мовах немає таких самих відмінностей, тож давайте подивимося, що таке оператори та вирази (operators and expressions) і як їхні відмінності впливають на тіла функцій.

• Оператори (statements) — це інструкції, які виконують певну дію і не повертають значення.
• Вирази (expressions) обчислюються до результуючого значення.

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

Насправді ми вже використовували оператори та вирази (operators and expressions) . Створення змінної та присвоєння їй значення за допомогою ключового слова let — це оператор. У Лістинг (Listing) 3-1, let y = 6; — це оператор.

fn main() {
    let y = 6;
}

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

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

Filename: src/main.rs

fn main() {
    let x = (let y = 6);
}

Коли ви запустите цю програму, помилка, яку ви отримаєте, виглядатиме так:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^
  |
  = note: only supported directly in conditions of `if` and `while` expressions

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` (bin "functions") due to 1 previous error; 1 warning emitted

Оператор let y = 6 не повертає значення, тож немає нічого, до чого міг би прив’язатися x. Це відрізняється від того, що відбувається в інших мовах, таких як C і Ruby, де присвоєння повертає значення присвоєння. У цих мовах ви можете написати x = y = 6 і щоб і x, і y мали значення 6; у Rust це не так.

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

Filename: src/main.rs

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

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

Цей вираз (expression):

{
    let x = 3;
    x + 1
}

є блоком, який, у цьому випадку, обчислюється до 4. Це значення прив’язується до y як частина оператора let. Зверніть увагу на рядок x + 1 без крапки з комою в кінці, що відрізняється від більшості рядків, які ви бачили досі. Вирази (Expressions) не включають завершувальних крапок з комою. Якщо ви додасте крапку з комою в кінець виразу, ви перетворите його на оператор, і тоді він не повертатиме значення. Майте це на увазі, коли далі досліджуватимете значення, що повертаються функціями, та вирази.

Функції зі значеннями, що повертаються (Functions with Return Values)

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

Filename: src/main.rs

fn five() -> i32 {
    5
}

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

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

У функції five немає викликів функцій, макросів чи навіть let-операторів — лише число 5 саме по собі. Це цілком дійсна функція в Rust. Зверніть увагу, що тип повернення функції також вказано як -> i32. Спробуйте запустити цей код; вивід має виглядати так:

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

5 у five — це значення, що повертається функцією, саме тому тип повернення є i32. Давайте розглянемо це докладніше. Є дві важливі речі: по-перше, рядок let x = five(); показує, що ми використовуємо значення, що повертається функцією, для ініціалізації змінної. Оскільки функція five повертає 5, цей рядок є тим самим, що й такий:

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

По-друге, функція five не має параметрів і визначає тип значення, що повертається, але тіло функції — це самотнє 5 без крапки з комою, тому що це вираз, значення якого ми хочемо повернути.

Давайте подивимося на інший приклад:

Filename: src/main.rs

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

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

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

Запуск цього коду надрукує The value of x is: 6. Але що станеться, якщо ми поставимо крапку з комою в кінці рядка, що містить x + 1, перетворивши його з виразу на оператор?

Filename: src/main.rs

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

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

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

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

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

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

Основне повідомлення про помилку, mismatched types, розкриває ключову проблему цього коду. Визначення функції plus_one говорить, що вона повертатиме i32, але оператори не обчислюються до значення, що виражається (), одиничним типом (unit type). Отже, нічого не повертається, що суперечить визначенню функції й призводить до помилки. У цьому виводі Rust надає повідомлення, яке може допомогти виправити цю проблему: він пропонує прибрати крапку з комою, що виправило б помилку.

Коментарі

Коментарі (Comments)

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

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

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

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

#![allow(unused)]
fn main() {
// So we're doing something complicated here, long enough that we need
// multiple lines of comments to do it! Whew! Hopefully, this comment will
// explain what's going on.
}

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

Filename: src/main.rs

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

Але ви частіше бачитимете їх використаними в такому форматі, коли коментар розміщується на окремому рядку над кодом, який він анотує:

Filename: src/main.rs

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

Rust також має інший вид коментарів, документаційні коментарі (documentation comments), які ми обговоримо в розділі “Публікація крейта на Crates.io (Publishing a Crate to Crates.io)” Розділу 14.

Керування потоком виконання

Керування потоком (Control Flow)

Можливість виконувати певний код залежно від того, чи є умова true, і можливість виконувати певний код повторно, поки умова є true, — це основні будівельні блоки в більшості мов програмування. Найпоширеніші конструкції, що дають вам змогу керувати потоком виконання коду Rust, — це вирази if і цикли.

Вирази if (if Expressions)

Вираз if дає змогу вам розгалужувати код залежно від умов. Ви надаєте умову, а потім зазначаєте: «Якщо ця умова виконується, виконайте цей блок коду. Якщо умова не виконується, не виконуйте цей блок коду».

Створіть новий проєкт під назвою branches у вашому каталозі projects, щоб дослідити вираз if. У файлі src/main.rs введіть таке:

Filename: src/main.rs

fn main() {
    let number = 3;

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

Усі вирази if починаються з ключового слова if, за яким іде умова. У цьому випадку умова перевіряє, чи має змінна number значення менше за 5. Ми розміщуємо блок коду, який потрібно виконати, якщо умова є true, безпосередньо після умови всередині фігурних дужок. Блоки коду, пов’язані з умовами у виразах if, інколи називають гілками (arms), так само як гілки (arms) у виразах match, про які ми говорили в розділі “Порівняння припущення із секретним числом” у розділі 2.

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

Спробуйте запустити цей код; ви повинні побачити такий вивід:

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

Спробуймо змінити значення number на таке, що робить умову false, щоб побачити, що станеться:

fn main() {
    let number = 7;

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

Запустіть програму ще раз і подивіться на вивід:

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

Також варто зазначити, що умова в цьому коді має бути bool. Якщо умова не є bool, ми отримаємо помилку. Наприклад, спробуйте запустити такий код:

Filename: src/main.rs

fn main() {
    let number = 3;

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

Умова if цього разу обчислюється до значення 3, і Rust видає помилку:

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

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

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

Filename: src/main.rs

fn main() {
    let number = 3;

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

Запуск цього коду надрукує number was something other than zero.

Обробка кількох умов за допомогою else if (Handling Multiple Conditions with else if)

Ви можете використовувати кілька умов, комбінуючи if і else у виразі else if. Наприклад:

Filename: src/main.rs

fn main() {
    let number = 6;

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

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

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

Коли ця програма виконується, вона послідовно перевіряє кожен вираз if і виконує перший блок, для якого умова обчислюється до true. Зверніть увагу, що хоча 6 ділиться на 2, ми не бачимо виводу number is divisible by 2, як і не бачимо тексту number is not divisible by 4, 3, or 2 з блоку else. Це тому, що Rust виконує лише блок для першої умови true, і, щойно знаходить таку, навіть не перевіряє решту.

Надмірне використання виразів else if може захаращувати ваш код, тож якщо їх більше ніж один, можливо, вам варто відрефакторити свій код. Розділ 6 описує потужну конструкцію розгалуження Rust під назвою match для таких випадків.

Використання if в операторі let (Using if in a let Statement)

Оскільки if є виразом, ми можемо використовувати його в правій частині оператора let, щоб присвоїти результат змінній, як у Лістингу (Listing) 3-2.

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

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

Змінна number буде прив’язана до значення на основі результату виразу if. Запустіть цей код, щоб побачити, що станеться:

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

Пам’ятайте, що блоки коду обчислюються до останнього виразу в них, а числа самі по собі також є виразами. У цьому випадку значення всього виразу if залежить від того, який блок коду виконується. Це означає, що значення, які потенційно можуть бути результатами з кожної гілки виразу if, мають бути одного й того самого типу; у Лістингу (Listing) 3-2 результати як гілки if, так і гілки else були цілими числами i32. Якщо типи не збігаються, як у такому прикладі, ми отримаємо помилку:

Filename: src/main.rs

fn main() {
    let condition = true;

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

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

Коли ми намагаємося скомпілювати цей код, ми отримаємо помилку. Гілки if і else мають несумісні типи значень, і Rust точно вказує, де знайти проблему в програмі:

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

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

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

Повторення за допомогою циклів (Repetition with Loops)

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

У Rust є три види циклів: loop, while і for. Спробуймо кожен із них.

Повторення коду за допомогою loop (Repeating Code with loop)

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

Як приклад, змініть файл src/main.rs у вашому каталозі loops так, щоб він виглядав ось так:

Filename: src/main.rs

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

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

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

Символ ^C позначає місце, де ви натиснули ctrl-C.

Ви можете побачити, а можете й не побачити слово again!, надруковане після ^C, залежно від того, де код був у циклі, коли отримав сигнал переривання.

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

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

Повернення значень із циклів (Returning Values from Loops)

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

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

    println!("The result is {result}");
}

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

Ви також можете return ізсередини циклу. Тоді як break лише виходить із поточного циклу, return завжди виходить із поточної функції.

Уточнення за допомогою міток циклів (Loop Labels to Disambiguate Between Multiple Loops)

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

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

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

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

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

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

Спрощення умовних циклів за допомогою while (Conditional Loops with while)

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

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

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

Ця конструкція усуває багато вкладеності, яка була б необхідна, якби ви використовували loop, if, else і break, і вона зрозуміліша. Поки умова обчислюється до true, код виконується; інакше він виходить із циклу.

Циклічний прохід по колекції за допомогою for (Looping Through a Collection with for)

Ви можете обрати використання конструкції while для проходу по елементах колекції, такої як масив. Наприклад, цикл у Лістингу (Listing) 3-4 друкує кожен елемент у масиві a.

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

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

        index += 1;
    }
}

Тут код рахує вгору по елементах у масиві. Він починає з індексу 0, а потім повторює цикл, доки не досягне останнього індексу в масиві (тобто, коли index < 5 перестає бути true). Запуск цього коду надрукує кожен елемент у масиві:

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

Усі п’ять значень масиву з’являються в терміналі, як і очікувалося. Хоча index у якийсь момент досягне значення 5, цикл зупиняє виконання перед спробою отримати шосте значення з масиву.

Однак цей підхід схильний до помилок; ми могли б спричинити паніку програми, якщо значення індексу або умова перевірки є неправильними. Наприклад, якщо б ви змінили визначення масиву a, щоб він мав чотири елементи, але забули оновити умову до while index < 4, код спричинив би паніку. Він також повільний, тому що компілятор додає код виконання для перевірки умови, чи перебуває індекс у межах масиву, на кожній ітерації циклу.

Як більш стислу альтернативу, ви можете використати цикл for і виконувати певний код для кожного елемента в колекції. Цикл for виглядає як код у Лістингу (Listing) 3-5.

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

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

Коли ми запустимо цей код, ми побачимо такий самий вивід, як у Лістингу (Listing) 3-4. Що важливіше, тепер ми підвищили безпеку коду і усунули ризик помилок, які можуть виникнути через вихід за кінець масиву або через те, що ви не дійшли достатньо далеко і пропустили деякі елементи. Машинний код, згенерований з циклів for, також може бути ефективнішим, тому що індекс не потрібно порівнювати з довжиною масиву на кожній ітерації.

Використовуючи цикл for, вам не потрібно було б пам’ятати про зміну будь-якого іншого коду, якби ви змінили кількість значень у масиві, як це було б із методом, використаним у Лістингу (Listing) 3-4.

Безпека й стислість циклів for роблять їх найуживанішою конструкцією циклів у Rust. Навіть у ситуаціях, коли ви хочете виконати певний код певну кількість разів, як у прикладі з відліком назад, що використовував цикл while у Лістингу (Listing) 3-3, більшість растацеанців (Rustaceans) використали б цикл for. Спосіб зробити це — використати Range, наданий стандартною бібліотекою, який генерує всі числа послідовно, починаючи з одного числа і закінчуючи перед іншим числом.

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

Filename: src/main.rs

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

Цей код трохи кращий, чи не так?

Підсумок (Summary)

Ви дісталися сюди! Це був значний розділ: ви дізналися про змінні, скалярні та складені типи даних, функції, коментарі, вирази if і цикли! Щоб практикуватися з концепціями, розглянутими в цьому розділі, спробуйте створити програми, які робитимуть таке:

• Перетворювати температури між Фаренгейтом і Цельсієм.
• Генерувати n-те число Фібоначчі.
• Друкувати текст різдвяної колядки “The Twelve Days of Christmas”, використовуючи повторення в пісні.

Коли будете готові рухатися далі, ми поговоримо про концепцію в Rust, яка не поширена в інших мовах програмування: володіння (ownership).

Розуміння володіння (Understanding Ownership)

Володіння (Ownership) — це найунікальніша особливість Rust і має глибокі наслідки для решти мови. Вона дає змогу Rust гарантувати безпеку пам’яті без потреби у збирачі сміття, тож важливо зрозуміти, як працює володіння. У цьому розділі ми поговоримо про володіння, а також про кілька пов’язаних можливостей: запозичення (borrowing), зрізи (slices) і про те, як Rust розміщує дані в пам’яті.

Що таке власність?

Що таке володіння / власність (Ownership)

Володіння (Ownership) — це набір правил, які керують тим, як програма Rust керує пам’яттю. Усі програми мають керувати способом, у який вони використовують пам’ять комп’ютера під час виконання. Деякі мови мають збирання сміття, яке регулярно шукає пам’ять, що більше не використовується, поки програма працює; в інших мовах програміст має явно виділяти і звільняти пам’ять. Rust використовує третій підхід: пам’ять керується через систему володіння (ownership system) з набором правил, які перевіряє компілятор. Якщо будь-яке з правил порушено, програма не скомпілюється. Жодна з можливостей володіння (ownership) не сповільнить вашу програму під час виконання.

Оскільки володіння (ownership) — це нова концепція для багатьох програмістів, до неї справді потрібно трохи часу, щоб звикнути. Добра новина полягає в тому, що чим досвідченішими ви стаєте з Rust і правилами системи володіння (ownership system), тим легше вам буде природно розробляти код, який є безпечним і ефективним. Продовжуйте!

Коли ви зрозумієте володіння (ownership), у вас буде міцна основа для розуміння можливостей, які роблять Rust унікальним. У цьому розділі ви дізнаєтеся про володіння (ownership), працюючи з кількома прикладами, що зосереджені на дуже поширеній структурі даних: рядках.

Стек і купа (The Stack and the Heap)

Багато мов програмування не вимагають, щоб ви дуже часто думали про стек і купу. Але в системній мові програмування, як-от Rust, те, чи значення перебуває у стеку чи в купі, впливає на те, як поводиться мова і чому вам доводиться робити певні рішення. Частини володіння (ownership) буде описано у зв’язку зі стеком і купою пізніше в цьому розділі, тож ось коротке пояснення для підготовки.

І стек, і купа є частинами пам’яті, доступними для використання вашим кодом під час виконання, але вони структуровані по-різному. Стек зберігає значення в тому порядку, в якому він їх отримує, і видаляє значення у зворотному порядку. Це називається останній прийшов — перший пішов (LIFO). Подумайте про стопку тарілок: коли ви додаєте ще тарілки, ви кладете їх на верхівку стопки, а коли вам потрібна тарілка, ви берете одну згори. Додавати або видаляти тарілки із середини чи знизу працювало б не так добре! Додавання даних називається проштовхуванням у стек, а видалення даних називається виштовхуванням зі стеку. Усі дані, що зберігаються у стеку, мають мати відомий, фіксований розмір. Дані з невідомим розміром під час компіляції або розміром, який може змінюватися, мають зберігатися в купі замість цього.

Купа менш упорядкована: коли ви розміщуєте дані в купі, ви запитуєте певний обсяг простору. Алокатор пам’яті знаходить порожнє місце в купі, достатньо велике, позначає його як таке, що використовується, і повертає вказівник, який є адресою цього місця. Цей процес називається виділенням у купі і інколи скорочується просто до виділення (проштовхування значень у стек не вважається виділенням). Оскільки вказівник на купу має відомий, фіксований розмір, ви можете зберегти вказівник у стеку, але коли ви хочете отримати самі дані, ви маєте слідувати за вказівником. Подумайте про те, як вас садять у ресторані. Коли ви входите, ви повідомляєте кількість людей у вашій групі, а хост знаходить порожній стіл, який вмістить усіх, і проводить вас туди. Якщо хтось із вашої групи запізниться, він може запитати, де вас посадили, щоб знайти вас.

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

Доступ до даних у купі загалом повільніший, ніж доступ до даних у стеку, тому що вам потрібно слідувати за вказівником, щоб дістатися туди. Сучасні процесори працюють швидше, якщо вони менше стрибають пам’яттю. Продовжуючи аналогію, уявіть собі офіціанта в ресторані, який приймає замовлення від багатьох столів. Найефективніше отримати всі замовлення за одним столом, перш ніж переходити до наступного столу. Брати замовлення за столом A, потім замовлення за столом B, потім одне з A знову, а потім одне з B знову було б значно повільнішим процесом. Так само процесор зазвичай може краще виконувати свою роботу, якщо він працює з даними, які близько розташовані до інших даних (як це є у стеку), а не далі від них (як це може бути в купі).

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

очищення невикористаних даних у купі, щоб у вас не закінчився простір, — усе це проблеми, які вирішує володіння (ownership). Щойно ви зрозумієте володіння (ownership), вам не доведеться дуже часто думати про стек і купу. Але знання того, що головна мета володіння (ownership) — керувати даними в купі, може допомогти пояснити, чому вона працює саме так, як працює.

Правила володіння (Ownership Rules)

Спочатку давайте поглянемо на правила володіння (ownership rules). Тримайте ці правила в голові, коли ми розглядатимемо приклади, що їх ілюструють:

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

Область видимості змінної (Variable Scope)

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

Як перший приклад володіння (ownership) ми розглянемо область видимості деяких змінних. Область видимості — це діапазон у програмі, протягом якого елемент є дійсним. Візьміть таку змінну:

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

Змінна s посилається на рядковий літерал, де значення рядка жорстко закодоване (hardcoded) в тексті нашої програми. Змінна є дійсною від моменту, коли її оголошено, і до кінця поточної області видимості. У Лістингу (Listing) 4-1 показано програму з коментарями, які позначають, де змінна s була б дійсною.

fn main() {
    {                      // s is not valid here, since it's not yet declared
        let s = "hello";   // s is valid from this point forward

        // do stuff with s
    }                      // this scope is now over, and s is no longer valid
}

Іншими словами, тут є два важливі моменти в часі:

• Коли s входить у область видимості, вона є дійсною.
• Вона залишається дійсною, доки не вийде з області видимості.

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

Тип String (The String Type)

Щоб ілюструвати правила володіння (ownership), нам потрібен тип даних, який є складнішим, ніж ті, що ми розглядали в розділі “Типи даних” (Data Types) з Розділу 3. Попередньо розглянуті типи мають відомий розмір, можуть зберігатися у стеку й виштовхуватися зі стеку, коли їхня область видимості завершується, і можуть швидко та тривіально копіюватися, щоб створити новий, незалежний екземпляр, якщо іншій частині коду потрібно використати те саме значення в іншій області видимості. Але ми хочемо подивитися на дані, що зберігаються в купі, і дослідити, як Rust знає, коли очищати ці дані, а тип String — чудовий приклад.

Ми зосередимося на тих частинах String, які пов’язані з володінням (ownership). Ці аспекти також застосовуються до інших складних типів даних, незалежно від того, чи надаються вони стандартною бібліотекою, чи створені вами. Ми обговоримо аспекти String, не пов’язані з володінням (ownership), у Розділі 8.

Ми вже бачили рядкові літерали, де значення рядка жорстко закодоване у нашій програмі. Рядкові літерали зручні, але вони не підходять для кожної ситуації, в якій ми можемо захотіти використовувати текст. Одна з причин полягає в тому, що вони незмінні. Інша полягає в тому, що не кожне значення рядка можна знати, коли ми пишемо наш код: наприклад, що якби ми хотіли приймати введення користувача і зберігати його? Саме для таких ситуацій у Rust є тип String. Цей тип керує даними, виділеними в купі, і тому може зберігати обсяг тексту, який нам невідомий під час компіляції. Ви можете створити String з рядкового літерала за допомогою функції from, ось так:

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

Оператор подвійної двокрапки :: дозволяє нам помістити цю конкретну функцію from у простір імен типу String замість використання якогось імені на кшталт string_from. Ми обговоримо цей синтаксис детальніше в розділі “Methods” Розділу 5, а також коли говоритимемо про простори імен за допомогою модулів у “Paths for Referring to an Item in the Module Tree” у Розділі 7.

Цей тип рядка можна змінювати:

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

    s.push_str(", world!"); // push_str() appends a literal to a String

    println!("{s}"); // this will print `hello, world!`
}

Отже, у чому тут різниця? Чому String можна змінювати, а літерали — ні? Різниця полягає в тому, як ці два типи поводяться з пам’яттю.

Пам’ять і виділення (Memory and Allocation)

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

У випадку типу String, щоб підтримати змінюваний, зростаючий фрагмент тексту, нам потрібно виділити в купі обсяг пам’яті, невідомий під час компіляції, щоб утримувати вміст. Це означає:

• Потрібно запитати пам’ять у алокатора пам’яті під час виконання.
• Нам потрібен спосіб повернути цю пам’ять алокатору, коли ми закінчимо з нашим String.

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

Однак друга частина відрізняється. У мовах зі збирачем сміття (GC) збирач сміття відстежує і очищає пам’ять, яка більше не використовується, і нам не потрібно про це думати. У більшості мов без GC це наша відповідальність — визначити, коли пам’ять більше не використовується, і викликати код, щоб явно звільнити її, так само як ми робили для запиту на її виділення. Історично зробити це правильно було складною програмістською проблемою. Якщо ми забудемо, ми марнуватимемо пам’ять. Якщо зробимо це занадто рано, у нас буде недійсна змінна. Якщо зробимо це двічі, це теж помилка. Нам потрібно поєднати рівно один allocate з рівно одним free.

Rust обирає інший шлях: пам’ять автоматично повертається, коли змінна, що володіє нею, виходить за межі області видимості. Ось версія нашого прикладу з областю видимості з Лістингу (Listing) 4-1, але з String замість рядкового літерала:

fn main() {
    {
        let s = String::from("hello"); // s is valid from this point forward

        // do stuff with s
    }                                  // this scope is now over, and s is no
                                       // longer valid
}

Існує природний момент, коли ми можемо повернути пам’ять, потрібну нашому String, алокатору: коли s виходить за межі області видимості. Коли змінна виходить за межі області видимості, Rust викликає для нас спеціальну функцію. Ця функція називається drop, і саме в ній автор String може розмістити код для повернення пам’яті. Rust викликає drop автоматично при закривальній фігурній дужці.

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

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

Змінні та дані, що взаємодіють через переміщення (Variables and Data Interacting with Move)

Кілька змінних можуть взаємодіяти з тими самими даними по-різному в Rust. У Лістингу (Listing) 4-2 показано приклад з використанням цілого числа.

fn main() {
    let x = 5;
    let y = x;
}

Ми, ймовірно, можемо здогадатися, що тут відбувається: “Прив’язати значення 5 до x; потім зробити копію значення в x і прив’язати її до y.” Тепер у нас є дві змінні, x і y, і обидві дорівнюють 5. Саме це й відбувається, тому що цілі числа — це прості значення з відомим, фіксованим розміром, і обидва ці значення 5 проштовхуються у стек.

Тепер давайте подивимося на версію з String:

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

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

Подивіться на Figure 4-1, щоб побачити, що відбувається з String під капотом. String складається з трьох частин, показаних ліворуч: вказівника на пам’ять, що містить вміст рядка, довжини та ємності. Ця група даних зберігається у стеку. Праворуч — пам’ять у купі, яка містить вміст.

Рисунок (Figure) 4-1: Представлення в пам’яті String, що містить значення "hello", прив’язане до s1 (The representation in memory of a String holding the value "hello" bound to s1)

Довжина — це те, скільки пам’яті, у байтах, зараз використовує вміст String. Ємність — це загальний обсяг пам’яті, у байтах, який String отримав від алокатора. Різниця між довжиною та ємністю має значення, але не в цьому контексті, тож поки що її можна ігнорувати.

Коли ми присвоюємо s1 до s2, дані String копіюються, тобто ми копіюємо вказівник, довжину та ємність, що знаходяться у стеку. Ми не копіюємо дані в купі, на які вказує вказівник. Іншими словами, представлення даних у пам’яті виглядає як на Figure 4-2.

Рисунок (Figure) 4-2: Представлення в пам’яті змінної s2, що має копію вказівника, довжини та ємності s1 (The representation in memory of the variable s2 that has a copy of the pointer, length, and capacity of s1)

Представлення не виглядає як Figure 4-3, яке було б у пам’яті, якби Rust також копіював дані в купі. Якби Rust робив це, операція s2 = s1 могла б бути дуже дорогою з точки зору продуктивності під час виконання, якщо дані в купі були б великими.

Рисунок (Figure) 4-3: Інша можливість того, що могла б зробити s2 = s1, якби Rust також копіював дані в купі (Another possibility for what s2 = s1 might do if Rust copied the heap data as well)

Раніше ми сказали, що коли змінна виходить за межі області видимості, Rust автоматично викликає функцію drop і очищає пам’ять у купі для цієї змінної. Але Figure 4-2 показує, що обидва вказівники даних вказують на одне й те саме місце. Це проблема: коли s2 і s1 вийдуть за межі області видимості, вони обидва спробують звільнити ту саму пам’ять. Це відоме як помилка подвійного звільнення (double free) і є однією з помилок безпеки пам’яті, про які ми згадували раніше. Подвійне звільнення пам’яті (double free) може призвести до пошкодження пам’яті, що потенційно може призвести до вразливостей безпеки.

Щоб забезпечити безпеку пам’яті, після рядка let s2 = s1;, Rust вважає s1 більш не дійсною. Тому Rust не потрібно нічого звільняти, коли s1 виходить за межі області видимості. Подивіться, що відбувається, коли ви намагаєтеся використати s1 після створення s2; це не спрацює:

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

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

Ви отримаєте таку помилку, тому що Rust не дає вам використовувати недійсне посилання:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:16
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, world!");
  |                ^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

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

Якщо ви чули терміни shallow copy і deep copy, працюючи з іншими мовами, концепція копіювання вказівника, довжини та ємності без копіювання даних, імовірно, звучить як створення shallow copy. Але оскільки Rust також робить першу змінну недійсною, замість того щоб це називалося shallow copy, це відоме як переміщення. У цьому прикладі ми б сказали, що s1 було переміщено у s2. Отже, те, що насправді відбувається, показано на Figure 4-4.

Рисунок (Figure) 4-4: Представлення в пам’яті після того, як s1 було анульовано (The representation in memory after s1 has been invalidated)

Це вирішує нашу проблему! Оскільки дійсною лишається лише s2, коли вона вийде за межі області видимості, вона одна звільнить пам’ять, і на цьому все.

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

Область видимості та присвоєння (Variables and Data Interacting with Move)

Інверсія цього твердження також справедлива для взаємозв’язку між областю видимості, володінням та звільненням пам’яті через функцію drop. Коли ви присвоюєте зовсім нове значення існуючій змінній, Rust викличе drop і негайно звільнить пам’ять початкового значення. Розглянемо, наприклад, цей код:

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

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

Спочатку ми оголошуємо змінну s і прив’язуємо її до String зі значенням "hello". Потім ми негайно створюємо новий String зі значенням "ahoy" і присвоюємо його s. У цей момент жоден об’єкт взагалі не посилається на початкове значення в купі. Figure 4-5 ілюструє дані стеку та купи тепер:

Рисунок (Figure) 4-5: Представлення в пам’яті після того, як початкове значення було повністю замінено (The representation in memory after the initial value has been replaced in its entirety)

Отже, початковий рядок одразу виходить за межі області видимості. Rust запустить на ньому функцію drop, і його пам’ять буде звільнено негайно. Коли ми надрукуємо значення в кінці, це буде "ahoy, world!".

Змінні та дані, що взаємодіють через clone (Variables and Data Interacting with Clone)

Якщо ми дійсно хочемо глибоко скопіювати дані String у купі, а не лише дані зі стеку, ми можемо використати поширений метод під назвою clone. Синтаксис методів ми обговоримо в Розділі 5, але оскільки методи є поширеною можливістю в багатьох мовах програмування, ви, ймовірно, бачили їх раніше.

Ось приклад методу clone у дії:

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

    println!("s1 = {s1}, s2 = {s2}");
}

Це працює цілком добре і явно створює поведінку, показану на Рисунку (Figure) 4-3, де дані в купі дійсно копіюються.

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

Дані лише у стеку: Copy (Stack-Only Data: Copy)

Є ще одна складність, про яку ми ще не говорили. Цей код із цілими числами — частина якого була показана в Лістингу (Listing) 4-2 — працює і є дійсним:

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

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

Але цей код, здається, суперечить тому, що ми щойно дізналися: у нас немає виклику clone, але x усе ще дійсна і не була переміщена в y.

Причина в тому, що типи на кшталт цілих чисел, які мають відомий розмір під час компіляції, повністю зберігаються у стеку, тож копії фактичних значень створюються швидко. Це означає, що немає жодної причини перешкоджати тому, щоб x залишалася дійсною після створення змінної y. Іншими словами, тут немає різниці між глибоким і неглибоким копіюванням, тож виклик clone не дав би нічого іншого порівняно зі звичайним неглибоким копіюванням, і ми можемо його не вживати.

Rust має спеціальну анотацію під назвою трейту (trait) Copy, яку ми можемо застосовувати до типів, що зберігаються у стеку, як-от цілі числа (ми ще поговоримо більше про трейти (traits) у Розділі 10). Якщо тип реалізує трейт (trait) Copy, змінні, які його використовують, не переміщуються, а просто копіюються, залишаючись дійсними після присвоєння іншій змінній.

Rust не дозволить нам анотувати тип Copy, якщо тип або будь-яка з його частин реалізували трейт (trait) Drop. Якщо для типу має відбуватися щось спеціальне, коли значення виходить за межі області видимості, і ми додаємо до цього типу анотацію Copy, ми отримаємо помилку під час компіляції. Щоб дізнатися, як додати анотацію Copy до вашого типу, щоб реалізувати трейт, див. “Derivable Traits” в Додатку C.

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

• Усі цілі типи, як-от u32.
• Булевий тип, bool, зі значеннями true і false.
• Усі типи чисел із рухомою комою, як-от f64.
• Символьний тип, char.
• Кортежі, якщо вони містять лише типи, які також реалізують Copy. Наприклад, (i32, i32) реалізує Copy, але (i32, String) — ні.

Володіння / Власність (Ownership) і функції

Механіка передавання значення у функцію подібна до тієї, що й під час присвоєння значення змінній. Передавання змінної у функцію перемістить або скопіює її, так само як і присвоєння. У Лістингу (Listing) 4-3 є приклад із деякими позначками, що показують, де змінні входять у область видимості та виходять з неї.

fn main() {
    let s = String::from("hello");  // s comes into scope

    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope

    makes_copy(x);                  // Because i32 implements the Copy trait,
                                    // x does NOT move into the function,
                                    // so it's okay to use x afterward.

} // Here, x goes out of scope, then s. However, because s's value was moved,
  // nothing special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{some_string}");
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{some_integer}");
} // Here, some_integer goes out of scope. Nothing special happens.

Якби ми спробували використати s після виклику takes_ownership, Rust викинув би помилку під час компіляції. Ці статичні перевірки захищають нас від помилок. Спробуйте додати код до main, який використовує s і x, щоб побачити, де ви можете їх використовувати і де правила володіння (ownership) не дозволяють вам це робити.

Значення, що повертаються, і область видимості (Return Values and Scope)

Повернення значень також може передавати володіння (ownership). У Лістингу (Listing) 4-4 показано приклад функції, яка повертає деяке значення, з такими ж позначками, як і в Лістингу (Listing) 4-3.

fn main() {
    let s1 = gives_ownership();        // gives_ownership moves its return
                                       // value into s1

    let s2 = String::from("hello");    // s2 comes into scope

    let s3 = takes_and_gives_back(s2); // s2 is moved into
                                       // takes_and_gives_back, which also
                                       // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
  // happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {       // gives_ownership will move its
                                       // return value into the function
                                       // that calls it

    let some_string = String::from("yours"); // some_string comes into scope

    some_string                        // some_string is returned and
                                       // moves out to the calling
                                       // function
}

// This function takes a String and returns a String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string comes into
    // scope

    a_string  // a_string is returned and moves out to the calling function
}

Володіння (Ownership) змінної щоразу слідує одному й тому самому шаблону: присвоєння значення іншій змінній переміщує його. Коли змінна, яка містить дані в купі, виходить за межі області видимості, значення буде очищено за допомогою drop, якщо володіння (ownership) даними не було переміщене до іншої змінної.

Хоча це працює, брати володіння (ownership) і потім повертати володіння (ownership) у кожній функції трохи виснажливо. Що якби ми хотіли дозволити функції використати значення, але не брати володіння? Досить незручно, що все, що ми передаємо, також потрібно передати назад, якщо ми хочемо використати це знову, окрім будь-яких даних, що виникають у тілі функції, які ми також можемо захотіти повернути.

Rust справді дозволяє повертати кілька значень за допомогою кортежу, як показано в Лістингу (Listing) 4-5.

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

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

    println!("The length of '{s2}' is {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String

    (s, length)
}

Але це забагато церемонності й багато роботи для поняття, яке має бути звичним. На щастя для нас, у Rust є можливість використовувати значення без передавання володіння (ownership): посилання.

Посилання та запозичення

Посилання та запозичення (References and Borrowing)

Проблема з кодом кортежу в Лістингу (Listing) 4-5 полягає в тому, що ми маємо повернути String викличній функції, щоб ми все ще могли використовувати String після виклику calculate_length, тому що String було переміщено в calculate_length. Натомість ми можемо надати посилання на значення String. Посилання — це як вказівник у тому сенсі, що це адреса, за якою ми можемо прослідкувати, щоб отримати доступ до даних, що зберігаються за цією адресою; ці дані належать якійсь іншій змінній. На відміну від вказівника, посилання гарантовано вказує на дійсне значення певного типу протягом часу життя цього посилання.

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

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

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

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

Спочатку зверніть увагу, що весь код кортежу в оголошенні змінної та значення повернення функції зник. По-друге, зауважте, що ми передаємо &s1 у calculate_length і, у її визначенні, ми беремо &String, а не String. Ці амперсанди (ampersands) позначають посилання, і вони дозволяють вам посилатися на певне значення, не беручи його у володіння. Рисунок (Figure) 4-6 зображує цю концепцію.

Рисунок (Figure) 4-6: Діаграма &String s, що вказує на String s1 (A diagram of &String s pointing at String s1)

Примітка: Протилежністю посилання через використання & є розіменування (dereferencing), яке виконується за допомогою оператора розіменування, *. Ми побачимо деякі способи використання оператора розіменування в Розділі 8 і обговоримо деталі розіменування в Розділі 15.

Давайте придивимося до виклику функції тут:

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

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

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

Синтаксис &s1 дозволяє нам створити посилання, яке посилається на значення s1, але не володіє ним. Оскільки посилання не володіє ним, значення, на яке воно вказує, не буде вивільнено, коли посилання перестане використовуватися.

Так само сигнатура функції використовує &, щоб вказати, що тип параметра s є посиланням. Додамо кілька пояснювальних позначок:

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

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because s does not have ownership of what
  // it refers to, the String is not dropped.

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

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

Отже, що станеться, якщо ми спробуємо змінити щось, що ми запозичуємо? Спробуйте код у Лістингу (Listing) 4-6. Спойлер: це не працює!

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

    change(&s);
}

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

Ось помилка:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
8 |     some_string.push_str(", world");
  |     ^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn change(some_string: &mut String) {
  |                         +++

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

Так само, як змінні за замовчуванням є незмінними, такими є й посилання. Нам не дозволено змінювати те, на що ми маємо посилання.

Змінні посилання (Mutable References)

Ми можемо виправити код з Лістингу (Listing) 4-6, щоб дозволити нам змінювати запозичене значення, лише з кількома невеликими змінами, які замість цього використовують змінне посилання (mutable reference):

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

    change(&mut s);
}

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

Спочатку ми змінюємо s на mut. Потім ми створюємо змінне посилання за допомогою &mut s там, де ми викликаємо функцію change, і оновлюємо сигнатуру функції так, щоб вона приймала змінне посилання з some_string: &mut String. Це дуже чітко показує, що функція change змінюватиме значення, яке вона запозичує.

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

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

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{r1}, {r2}");
}

Ось помилка:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{r1}, {r2}");
  |                -- first borrow later used here

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

Ця помилка каже, що цей код є недійсним, тому що ми не можемо запозичити s як змінне більше ніж один раз одночасно. Перше змінне запозичення знаходиться в r1 і має тривати до моменту його використання в println!, але між створенням цього змінного посилання та його використанням ми спробували створити ще одне змінне посилання в r2, яке запозичує ті самі дані, що й r1.

Обмеження, яке не дозволяє кільком змінним посиланням на ті самі дані існувати одночасно, дає змогу виконувати змінювання, але в дуже контрольований спосіб. Це те, з чим новачки в Rust, растацеанці (Rustaceans), мають труднощі, тому що більшість мов дозволяють вам змінювати коли завгодно. Перевага наявності цього обмеження полягає в тому, що Rust може запобігати станам гонки даних (data race) під час компіляції. Стан гонки даних — це подібно до умови гонки і трапляється, коли відбуваються такі три поведінки:

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

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

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

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

    {
        let r1 = &mut s;
    } // r1 goes out of scope here, so we can make a new reference with no problems.

    let r2 = &mut s;
}

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

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

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    let r3 = &mut s; // BIG PROBLEM

    println!("{r1}, {r2}, and {r3}");
}

Ось помилка:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no problem
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no problem
6 |     let r3 = &mut s; // BIG PROBLEM
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{r1}, {r2}, and {r3}");
  |                -- immutable borrow later used here

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

Ох! Ми також не можемо мати змінне посилання, коли маємо незмінне на те саме значення.

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

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

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

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{r1} and {r2}");
    // Variables r1 and r2 will not be used after this point.

    let r3 = &mut s; // no problem
    println!("{r3}");
}

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

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

Висячі посилання (Dangling References)

У мовах із вказівниками легко помилково створити висячий вказівник (dangling pointer) — вказівник, який посилається на місце в пам’яті, яке, можливо, було передано комусь іншому — звільнивши частину пам’яті, зберігаючи при цьому вказівник на цю пам’ять. У Rust, навпаки, компілятор гарантує, що посилання ніколи не будуть висячими посиланнями: якщо ви маєте посилання на якісь дані, компілятор забезпечить, що дані не вийдуть за межі області видимості раніше, ніж посилання на ці дані.

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

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

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

    &s
}

Ось помилка:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn dangle() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

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

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

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

Давайте придивимося уважніше до того, що саме відбувається на кожному етапі нашого коду dangle:

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

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope and is dropped, so its memory goes away.
  // Danger!

Оскільки s створюється всередині dangle, коли код dangle завершується, s буде деалоковано. Але ми спробували повернути на нього посилання. Це означає, що це посилання вказувало б на недійсний String. Це погано! Rust не дозволить нам цього зробити.

Рішення тут — повертати String безпосередньо:

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

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

    s
}

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

Правила посилань (The Rules of References)

Підсумуймо те, що ми обговорили щодо посилань:

• У будь-який момент часу ви можете мати або одне змінне посилання, або будь-яку кількість незмінних посилань.
• Посилання завжди мають бути дійсними.

Далі ми розглянемо інший вид посилання: зрізи.

Тип зрізу (slice)

Тип зрізу (The Slice Type)

Зрізи (slices) дають змогу вам посилатися на неперервну послідовність елементів у колекції. Зріз — це вид посилання, тож він не має володіння.

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

Примітка: Для цілей запровадження зрізів у цьому розділі ми припускаємо лише ASCII; більш ґрунтовне обговорення обробки UTF-8 є в розділі “Збереження кодування UTF-8 для тексту за допомогою рядків” Розділу 8.

Давайте розглянемо, як ми написали б сигнатуру цієї функції без використання зрізів, щоб зрозуміти проблему, яку зрізи розв’яжуть:

fn first_word(s: &String) -> ?

Функція first_word має параметр типу &String. Нам не потрібна володіння, тож це підходить. (В ідіоматичному Rust функції не беруть володіння над своїми аргументами, якщо їм це не потрібно, і причини цього стануть очевиднішими, коли ми рухатимемось далі.) Але що ми маємо повернути? У нас справді немає способу говорити про частину рядка. Однак ми могли б повернути індекс кінця слова, позначеного пробілом. Спробуймо це, як показано в Лістингу (Listing) 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

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

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Далі ми створюємо ітератор (iterator) над масивом байтів за допомогою методу iter:

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Ми докладніше обговоримо ітератори в Розділі 13. Поки що знайте, що iter — це метод, який повертає кожен елемент у колекції, а enumerate загортає результат iter і натомість повертає кожен елемент як частину кортежу. Перший елемент кортежу, повернутого з enumerate, — це індекс, а другий елемент — це посилання на елемент. Це трохи зручніше, ніж обчислювати індекс самостійно.

Оскільки метод enumerate повертає кортеж, ми можемо використовувати шаблони для деструктурування цього кортежу. Ми докладніше говоритимемо про шаблони в Розділі 6. У циклі for we вказуємо шаблон, у якому i — це індекс у кортежі, а &item — це окремий байт у кортежі. Оскільки ми отримуємо посилання на елемент з .iter().enumerate(), ми використовуємо & у шаблоні.

Усередині циклу for ми шукаємо байт, який представляє пробіл, використовуючи синтаксис байтового літерала. Якщо ми знаходимо пробіл, ми повертаємо позицію. Інакше ми повертаємо довжину рядка, використовуючи s.len().

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Тепер ми маємо спосіб дізнатися індекс кінця першого слова в рядку, але є проблема. Ми повертаємо сам по собі usize, але це лише змістовне число в контексті &String. Іншими словами, оскільки це окреме значення від String, немає гарантії, що воно і надалі буде чинним. Розгляньте програму в Лістингу (Listing) 4-8, яка використовує функцію first_word із Лістингу (Listing) 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

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

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but s no longer has any content that we
    // could meaningfully use with the value 5, so word is now totally invalid!
}

Ця програма компілюється без жодних помилок і зробила б це також, якби ми використали word після виклику s.clear(). Оскільки word зовсім не пов’язаний зі станом s, word усе ще містить значення 5. Ми могли б використати це значення 5 із змінною s, щоб спробувати витягти перше слово, але це була б помилка, тому що вміст s змінився після того, як ми зберегли 5 у word.

Потрібність турбуватися про те, що індекс у word розсинхронізується з даними в s, — це клопітно й схильне до помилок! Керування цими індексами ще більш крихке, якщо ми напишемо функцію second_word. Її сигнатура мала б виглядати так:

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

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

На щастя, у Rust є розв’язання цієї проблеми: рядкові зрізи.

Рядкові зрізи

Рядковий зріз (string slice) — це посилання на неперервну послідовність елементів String, і він виглядає так:

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

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

Замість посилання на весь String, hello — це посилання на частину String, указаню додатковим фрагментом [0..5]. Ми створюємо зрізи, використовуючи діапазон у квадратних дужках, указуючи [starting_index..ending_index], де starting_index — це перша позиція в зрізі, а ending_index — це на одиницю більше за останню позицію в зрізі. Усередині структура даних зрізу зберігає початкову позицію і довжину зрізу, яка відповідає ending_index мінус starting_index. Отже, у випадку let world = &s[6..11];, world буде зрізом, який містить вказівник на байт з індексом 6 у s із значенням довжини 5.

Рисунок (Figure) 4-7 показує це на діаграмі.

Рисунок (Figure) 4-7: Рядковий зріз, що посилається на частину String (A string slice referring to part of a String)

За допомогою синтаксису діапазонів Rust .., якщо ви хочете почати з індексу 0, ви можете опустити значення перед двома крапками. Іншими словами, ці вирази рівні:

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

let slice = &s[0..2];
let slice = &s[..2];
}

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

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

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

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

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

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

Примітка: Індекси діапазону рядкового зрізу мають збігатися з допустимими межами символів UTF-8. Якщо ви спробуєте створити рядковий зріз посередині багатобайтного символу, ваша програма завершиться з помилкою.

Маючи всю цю інформацію, перепишімо first_word, щоб вона повертала зріз. Тип, який позначає «рядковий зріз», записується як &str:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

Ми отримуємо індекс кінця слова тим самим способом, що й у Лістингу (Listing) 4-7, — шукаючи перше входження пробілу. Коли ми знаходимо пробіл, ми повертаємо рядковий зріз, використовуючи початок рядка та індекс пробілу як початковий і кінцевий індекси.

Тепер, коли ми викликаємо first_word, ми отримуємо назад одне значення, яке пов’язане з базовими даними. Це значення складається з посилання на початкову точку зрізу та кількості елементів у зрізі.

Повернення зрізу також працювало б для функції second_word:

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

Тепер у нас є простий API, який набагато важче зламати, тому що компілятор забезпечить, щоб посилання на String залишалися чинними. Пам’ятаєте помилку в програмі з Лістингу (Listing) 4-8, коли ми отримали індекс до кінця першого слова, а потім очистили рядок, тож наш індекс став недійсним? Той код був логічно неправильним, але не показував негайних помилок. Проблеми з’явилися б пізніше, якби ми продовжували намагатися використовувати індекс першого слова з очищеним рядком. Зрізи роблять цю помилку неможливою і дають нам знати значно раніше, що в нашому коді є проблема. Використання версії first_word зі зрізом призведе до помилки під час компіляції:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

Ось помилка компілятора:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                   ---- immutable borrow later used here

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

Згадайте з правил запозичення, що якщо ми маємо незмінне посилання на щось, ми не можемо також узяти змінне посилання. Оскільки clear потрібно обрізати String, йому потрібно отримати змінне посилання. println! після виклику clear використовує посилання в word, тож незмінне посилання має все ще бути активним у цей момент. Rust не дозволяє змінному посиланню в clear і незмінному посиланню в word існувати одночасно, і компіляція завершується невдачею. Rust не лише зробив наш API простішим у використанні, але й усунув цілий клас помилок під час компіляції!

Рядкові літерали як зрізи (String Literals Are Slices)

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

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

Тип s тут — &str: це зріз, який вказує на цю конкретну точку бінарного файлу. Саме тому рядкові літерали є незмінними; &str — це незмінне посилання.

Рядкові зрізи як параметри (String Slices as Parameters)

Знання того, що ви можете брати зрізи літералів і значень String, приводить нас ще до одного поліпшення first_word, а саме до її сигнатури:

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

Більш досвідчений растацеанець (Rustacean) написав би сигнатуру, показану в Лістингу (Listing) 4-9, замість цього, тому що вона дає змогу використовувати ту саму функцію як зі значеннями &String, так і зі значеннями &str.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Якщо в нас є рядковий зріз, ми можемо передати його безпосередньо. Якщо в нас є String, ми можемо передати зріз String або посилання на String. Ця гнучкість використовує переваги приведення типів через розіменування (deref coercions) — можливості, яку ми розглянемо в розділі “Використання приведення типів через розіменування у функціях і методах (Using Deref Coercions with Functions and Methods)” Розділу 15.

Визначення функції, яка приймає рядковий зріз замість посилання на String, робить наш API більш загальним і корисним, не втрачаючи жодної функціональності:

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Інші зрізи (Other Slices)

Рядкові зрізи, як ви можете уявити, специфічні для рядків. Але є й більш загальний тип зрізу. Розгляньмо цей масив:

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

Так само як ми можемо хотіти посилатися на частину рядка, ми можемо хотіти посилатися на частину масиву. Ми зробили б це так:

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

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

Цей зріз має тип &[i32]. Він працює так само, як і рядкові зрізи, зберігаючи посилання на перший елемент і довжину. Ви використовуватимете цей тип зрізу для різноманітних інших колекцій. Ми докладно обговоримо ці колекції, коли говоритимемо про вектори в Розділі 8.

Підсумок (Summary)

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

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

Використання структур для структурування пов’язаних даних (Using Structs to Structure Related Data)

Структура (struct), або structure, — це користувацький тип даних, який дає змогу пакувати разом і називати кілька пов’язаних значень, що утворюють змістовну групу. Якщо ви знайомі з об’єктно-орієнтованою мовою, структура — це як атрибути даних об’єкта. У цьому розділі ми порівняємо й зіставимо кортежі зі структурами, щоб спиратися на те, що ви вже знаєте, і показати, коли структури є кращим способом групування даних.

Ми покажемо, як визначати й створювати екземпляри структур. Ми обговоримо, як визначати асоційовані функції (associated functions), особливо той вид асоційованих функцій, які називаються методами (methods), щоб задавати поведінку, пов’язану з типом структури. Структури та перелічення (enums) (розглянуті в Розділі 6) — це будівельні блоки для створення нових типів у домені вашої програми, щоб повною мірою скористатися перевіркою типів Rust під час компіляції.

Визначення та створення екземплярів структур

Визначення та створення екземплярів структур (Defining and Instantiating Structs)

Структури подібні до кортежів, про які йшлося в розділі “Тип кортежу”, тим, що обидва зберігають кілька пов’язаних значень. Як і кортежі, частини структури можуть мати різні типи. На відміну від кортежів, у структурі ви назвемо кожну частину даних, щоб було зрозуміло, що означають значення. Додавання цих назв означає, що структури є гнучкішими за кортежі: вам не потрібно покладатися на порядок даних, щоб визначати або отримувати доступ до значень екземпляра.

Щоб визначити структуру, ми вводимо ключове слово struct і називаємо всю структуру. Назва структури має описувати значущість частин даних, які групуються разом. Потім, усередині фігурних дужок, ми визначаємо назви та типи частин даних, які ми називаємо полями (fields). Наприклад, у Лістингу (Listing) 5-1 показано структуру, яка зберігає інформацію про обліковий запис користувача.

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

fn main() {}

Щоб використати структуру після того, як ми її визначили, ми створюємо екземпляр (instance) цієї структури, вказуючи конкретні значення для кожного з полів. Ми створюємо екземпляр, називаючи структуру, а потім додаючи фігурні дужки, що містять пари key: value, де ключі — це назви полів, а значення — це дані, які ми хочемо зберігати в цих полях. Нам не потрібно вказувати поля в тому самому порядку, в якому ми оголосили їх у структурі. Іншими словами, визначення структури — це як загальний шаблон для типу, а екземпляри заповнюють цей шаблон конкретними даними, щоб створити значення типу. Наприклад, ми можемо оголосити конкретного користувача, як показано в Лістингу (Listing) 5-2.

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

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

Щоб отримати певне значення зі структури, ми використовуємо точкову нотацію. Наприклад, щоб отримати доступ до електронної адреси цього користувача, ми використовуємо user1.email. Якщо екземпляр є змінним, ми можемо змінити значення, використовуючи точкову нотацію і присвоюючи значення в конкретне поле. Лістинг (Listing) 5-3 показує, як змінити значення в полі email змінного екземпляра User.

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

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

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

Лістинг (Listing) 5-4 показує функцію build_user, яка повертає екземпляр User із заданими електронною адресою та ім’ям користувача. Поле active отримує значення true, а sign_in_count — значення 1.

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

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Має сенс називати параметри функції так само, як і поля структури, але необхідність повторювати назви полів і змінних email та username дещо обтяжлива. Якби структура мала більше полів, повторення кожної назви стало б ще більш набридливим. На щастя, є зручне скорочення!

Використання скороченого синтаксису ініціалізації полів (Using the Field Init Shorthand)

Оскільки в Лістингу (Listing) 5-4 імена параметрів і імена полів структури є точно однаковими, ми можемо використати синтаксис скороченого синтаксису ініціалізації полів для переписування build_user так, щоб вона поводилася точно так само, але без повторення username і email, як показано в Лістингу (Listing) 5-5.

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

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Тут ми створюємо новий екземпляр структури User, яка має поле з назвою email. Ми хочемо встановити значення поля email у значення параметра email функції build_user. Оскільки поле email і параметр email мають однакову назву, нам потрібно лише написати email, а не email: email.

Створення екземплярів за допомогою синтаксису оновлення структури (Creating Instances from Other Instances with Struct Update Syntax)

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

Спочатку, у Лістингу (Listing) 5-6 ми покажемо, як створити новий екземпляр User у user2 звичайним способом, без синтаксису оновлення. Ми встановлюємо нове значення для email, але в іншому використовуємо ті самі значення з user1, які ми створили в Лістингу (Listing) 5-2.

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

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

Використовуючи синтаксис оновлення структури, ми можемо досягти того самого ефекту з меншим обсягом коду, як показано в Лістингу (Listing) 5-7. Синтаксис .. указує, що решта полів, які не встановлено явно, мають мати ті самі значення, що й поля в заданому екземплярі.

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

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

Код у Лістингу (Listing) 5-7 також створює екземпляр у user2, який має інше значення для email, але має ті самі значення для полів username, active і sign_in_count з user1. ..user1 має бути останнім, щоб указати, що будь-які решта полів мають отримати свої значення з відповідних полів у user1, але ми можемо обрати вказати значення для будь-якої кількості полів у будь-якому порядку, незалежно від порядку полів у визначенні структури.

Зверніть увагу, що синтаксис оновлення структури використовує = як присвоювання; це тому, що він переміщує дані, так само як ми бачили в розділі “Змінні та дані, що взаємодіють із переміщенням”. У цьому прикладі ми більше не можемо використовувати user1 після створення user2, тому що String у полі username з user1 було переміщено в user2. Якби ми надали user2 нові значення String для обох полів email і username, і таким чином використали б лише значення active і sign_in_count з user1, тоді user1 усе ще був би дійсним після створення user2. І active, і sign_in_count — це типи, які реалізують трейт Copy, тому поведінка, яку ми обговорювали в розділі “Дані лише у стеку: Copy”, буде застосовуватися. Ми також усе ще можемо використовувати user1.email у цьому прикладі, тому що його значення не було переміщено з user1.

Створення різних типів за допомогою кортежних структур (Using Tuple Structs without Named Fields to Create Different Types)

Rust також підтримує структури, які виглядають подібно до кортежів, що називаються кортежними структурами (tuple structs). Кортежні структури мають додаткове значення, яке надає назва структури, але не мають назв, пов’язаних із їхніми полями; натомість вони просто мають типи полів. Кортежні структури корисні, коли ви хочете надати всьому кортежу назву і зробити кортеж іншим типом від інших кортежів, а також коли називати кожне поле, як у звичайній структурі, було б багатослівно або надлишково.

Щоб визначити кортежну структуру, почніть із ключового слова struct і назви структури, після чого вкажіть типи в кортежі. Наприклад, тут ми визначаємо та використовуємо дві кортежні структури з назвами Color і Point:

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

Зверніть увагу, що значення black і origin мають різні типи, тому що це екземпляри різних кортежних структур. Кожна визначена вами структура є окремим типом, навіть якщо поля всередині структури можуть мати ті самі типи. Наприклад, функція, яка приймає параметр типу Color, не може приймати Point як аргумент, навіть якщо обидва типи складаються з трьох значень i32. В іншому випадку екземпляри кортежних структур подібні до кортежів тим, що ви можете розпакувати їх на окремі частини, і ви можете використовувати . із наступним індексом, щоб отримати доступ до окремого значення. На відміну від кортежів, кортежні структури вимагають, щоб ви назвали тип структури, коли розпаковуєте їх. Наприклад, ми б написали let Point(x, y, z) = origin;, щоб розпакувати значення в точці origin у змінні з назвами x, y і z.

Визначення одноподібних структур (Defining Unit-Like Structs without Any Fields)

Ви також можете визначати структури, які не мають жодних полів! Вони називаються одноподібними структурами (unit-like structs), тому що поводяться подібно до (), типу одиниці, про який ми згадували в розділі “Тип кортежу”. Одноподібні структури можуть бути корисними, коли вам потрібно реалізувати трейт для якогось типу, але ви не маєте жодних даних, які хочете зберігати в самому типі. Ми обговоримо трейти в Розділі 10. Ось приклад оголошення і створення екземпляра одноподібної структури з назвою AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Щоб визначити AlwaysEqual, ми використовуємо ключове слово struct, назву, яку хочемо, а потім крапку з комою. Не потрібно жодних фігурних дужок або круглих дужок! Потім ми можемо отримати екземпляр AlwaysEqual у змінній subject подібним способом: використовуючи назву, яку ми визначили, без будь-яких фігурних дужок або круглих дужок. Уявіть, що пізніше ми реалізуємо поведінку для цього типу так, що кожен екземпляр AlwaysEqual завжди дорівнює кожному екземпляру будь-якого іншого типу, можливо, щоб мати відомий результат для цілей тестування. Нам не потрібні були б жодні дані, щоб реалізувати таку поведінку! У Розділі 10 ви побачите, як визначати трейти і реалізовувати їх для будь-якого типу, включно з одноподібними структурами.

У визначенні структури User у Лістингу (Listing) 5-1 ми використовували тип String, що володіє даними, а не тип рядкового зрізу &str. Це свідомий вибір, тому що ми хочемо, щоб кожен екземпляр цієї структури володів усіма своїми даними і щоб ці дані були дійсними доти, доки дійсна вся структура.

Також можливо, щоб структури зберігали посилання на дані, які належать чомусь іншому, але для цього потрібно використати часи життя (lifetimes), особливість Rust, яку ми обговоримо в Розділі 10. Часи життя гарантують, що дані, на які посилається структура, є дійсними доти, доки дійсна структура. Припустімо, ви намагаєтеся зберегти посилання в структурі без указання часів життя, як у наведеному нижче в src/main.rs; це не спрацює:

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

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

Компілятор скаржитиметься, що йому потрібні специфікатори часу життя:

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

У Розділі 10 ми обговоримо, як виправити ці помилки, щоб ви могли зберігати посилання в структурах, але наразі ми виправлятимемо такі помилки, використовуючи типи, що володіють даними (owned types), як-от String, замість посилань, як-от &str.

Приклад програми з використанням структур

Приклад програми з використанням структур (An Example Program Using Structs)

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

Давайте створимо новий двійковий проєкт за допомогою Cargo під назвою rectangles, який братиме ширину та висоту прямокутника, задані в пікселях, і обчислюватиме площу прямокутника. У Лістингу (Listing) 5-8 показано коротку програму з одним способом зробити саме це в нашому проєкті src/main.rs.

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

Тепер запустіть цю програму за допомогою cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

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

Проблема цього коду очевидна в сигнатурі area:

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

Функція area має обчислювати площу одного прямокутника, але функція, яку ми написали, має два параметри, і ніде в нашій програмі не зрозуміло, що ці параметри пов’язані між собою. Було б читабельніше й зручніше для супроводу згрупувати ширину та висоту разом. Ми вже обговорювали один спосіб, як ми могли б це зробити, у розділі 3: за допомогою кортежів.

Переробка з кортежами (Refactoring with Tuples)

У Лістингу (Listing) 5-9 показано іншу версію нашої програми, яка використовує кортежі.

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

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

Плутанина між шириною та висотою не мала б значення для обчислення площі, але якщо ми хочемо намалювати прямокутник на екрані, це було б важливо! Нам довелося б пам’ятати, що width — це індекс кортежа 0, а height — це індекс кортежа 1. Комусь іншому було б ще важче це зрозуміти й тримати в пам’яті, якби він або вона захотіли використати наш код. Оскільки ми не передали зміст наших даних у нашому коді, тепер легше ввести помилки.

Переробка зі структурами (Refactoring with Structs: Adding More Meaning)

Ми використовуємо структури, щоб додати зміст шляхом маркування даних. Ми можемо перетворити кортеж, який використовуємо, на структуру з назвою для цілого, а також назвами для частин, як показано в Лістингу (Listing) 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

Тут ми визначили структуру й назвали її Rectangle. Усередині фігурних дужок ми визначили поля як width і height, обидва з типом u32. Потім у main ми створили конкретний екземпляр Rectangle, який має ширину 30 і висоту 50.

Наша функція area тепер визначена з одним параметром, який ми назвали rectangle, чий тип є незмінним запозиченням екземпляра структури Rectangle. Як ми обговорювали в розділі 4, ми хочемо запозичити структуру, а не брати її у володіння. Таким чином main зберігає володіння і може продовжувати використовувати rect1, через що ми використовуємо & у сигнатурі функції та там, де викликаємо функцію.

Функція area отримує доступ до полів width і height екземпляра Rectangle (зверніть увагу, що доступ до полів запозиченого екземпляра структури не переміщує значення полів, саме тому ви часто бачите запозичення структур). Наша сигнатура функції для area тепер точно каже те, що ми маємо на увазі: обчислити площу Rectangle, використовуючи його поля width і height. Це передає, що width і height пов’язані між собою, і дає описові назви значенням замість використання значень індексів кортежа 0 і 1. Це виграш для ясності.

Додавання корисної функціональності за допомогою виведених трейтів (Adding Useful Functionality with Derived Traits)

Було б корисно мати змогу надрукувати екземпляр Rectangle, коли ми налагоджуємо нашу програму, і побачити значення всіх його полів. У Лістингу (Listing) 5-11 спробовано використати макрос (macro) println!, як ми вже робили в попередніх розділах. Однак це не спрацює.

struct Rectangle {
    width: u32,
    height: u32,
}

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

    println!("rect1 is {rect1}");
}

Коли ми компілюємо цей код, отримуємо помилку з таким основним повідомленням:

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

Макрос println! може виконувати багато видів форматування, і за замовчуванням фігурні дужки вказують println! використовувати форматування, відоме як Display: вивід, призначений для безпосереднього споживання кінцевим користувачем. Примітивні типи, які ми бачили досі, реалізують Display за замовчуванням, тому що є лише один спосіб, яким ви хотіли б показати 1 або будь-який інший примітивний тип користувачеві. Але зі структурами спосіб, у який println! має форматувати вивід, менш очевидний, тому що є більше варіантів відображення: чи потрібні коми? Чи потрібно друкувати фігурні дужки? Чи мають бути показані всі поля? Через цю неоднозначність Rust не намагається вгадати, чого ми хочемо, і структури не мають наданої реалізації Display, яку можна використати з println! і заповнювачем {}.

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

   |                        |`Rectangle` cannot be formatted with the default formatter
   |                        required by this formatting parameter

Спробуймо це! Виклик макроса println! тепер виглядатиме так: println!("rect1 is {rect1:?}");. Розміщення специфікатора :? всередині фігурних дужок повідомляє println!, що ми хочемо використати формат виводу, який називається Debug. Трейт (trait) Debug дає нам змогу друкувати нашу структуру так, щоб це було корисно для розробників, аби ми могли бачити її значення під час налагодження нашого коду.

Скомпілюйте код із цією зміною. От халепа! Ми все ще отримуємо помилку:

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

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

   |                        required by this formatting parameter
   |

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

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

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

    println!("rect1 is {rect1:?}");
}

Тепер, коли ми запустимо програму, ми не отримаємо жодних помилок і побачимо такий вивід:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

Чудово! Це не найгарніший вивід, але він показує значення всіх полів цього екземпляра, що безумовно допомогло б під час налагодження. Коли ми маємо більші структури, корисно мати вивід, який трохи легше читати; у таких випадках ми можемо використовувати {:#?} замість {:?} у рядку println!. У цьому прикладі використання стилю {:#?} виведе таке:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

Інший спосіб надрукувати значення, використовуючи формат Debug, — застосувати макрос (macro) dbg!, який бере у володіння вираз (на відміну від println!, який бере посилання), друкує ім’я файлу та номер рядка, де виклик цього макроса dbg! відбувається у вашому коді, разом із результативним значенням цього виразу, і повертає володіння значення.

Примітка: виклик макроса dbg! друкує в консольний потік стандартної помилки (stderr), на відміну від println!, який друкує в консольний потік стандартного виводу (stdout). Ми докладніше говоритимемо про stderr і stdout у розділі “Redirecting Errors to Standard Error” розділу 12.

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

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

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

Ми можемо обгорнути dbg! навколо виразу 30 * scale і, оскільки dbg! повертає володіння значення виразу, поле width отримає те саме значення, ніби виклику dbg! там не було. Ми не хочемо, щоб dbg! брав у володіння rect1, тому в наступному виклику ми використовуємо посилання на rect1. Ось як виглядає вивід цього прикладу:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

Ми можемо побачити, що перша частина виводу походить із src/main.rs рядка 10, де ми налагоджуємо вираз 30 * scale, і його результативне значення дорівнює 60 (форматування Debug, реалізоване для цілих чисел, полягає в друкуванні лише їх значення). Виклик dbg! у рядку 14 src/main.rs виводить значення &rect1, яке є структурою Rectangle. Цей вивід використовує красиве форматування Debug типу Rectangle. Макрос dbg! може бути справді корисним, коли ви намагаєтеся з’ясувати, що робить ваш код!

Окрім трейту Debug, Rust надав нам низку трейтів для використання з атрибутом derive, які можуть додати корисну поведінку нашим власним типам. Ці трейти та їхня поведінка перелічені в Додатку C. Ми розглянемо, як реалізовувати ці трейти з власною поведінкою, а також як створювати власні трейти, у розділі 10. Також існує багато інших атрибутів, окрім derive; для отримання додаткової інформації дивіться розділ “Attributes” у Rust Reference.

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

Методи

Методи

Методи подібні до функцій: Ми оголошуємо їх за допомогою ключового слова fn і імені, вони можуть мати параметри та значення, що повертається, і вони містять код, який виконується, коли метод викликається звідкись іще. На відміну від функцій, методи визначаються в контексті структури (або перелічення (enum), або об’єкта трейту (trait object), що ми розглядаємо в Розділі 6 та Розділі 18 відповідно), і їхній перший параметр завжди self, який представляє екземпляр структури, для якого викликається метод.

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

Давайте змінимо функцію area, яка має екземпляр Rectangle як параметр, і натомість зробимо методом area, визначеним для структури Rectangle, як показано в Лістингу 5-13.

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

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

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

Щоб визначити функцію в контексті Rectangle, ми починаємо блок impl (реалізація) для Rectangle. Усе в межах цього блоку impl буде пов’язане з типом Rectangle. Потім ми переміщуємо функцію area всередину фігурних дужок impl і змінюємо перший (і в цьому випадку єдиний) параметр на self у сигнатурі та всюди в тілі. У main, де ми викликали функцію area і передавали rect1 як аргумент, ми можемо натомість використати синтаксис методів, щоб викликати метод area на нашому екземплярі Rectangle. Синтаксис методів іде після екземпляра: Ми додаємо крапку, за якою йде ім’я методу, круглі дужки та будь-які аргументи.

У сигнатурі для area ми використовуємо &self замість rectangle: &Rectangle. &self насправді є скороченням для self: &Self. Усередині блоку impl тип Self є псевдонімом для типу, для якого призначений блок impl. Методи повинні мати параметр на ім’я self типу Self як свій перший параметр, тому Rust дозволяє скоротити це, використовуючи лише ім’я self у першій позиції параметра. Зверніть увагу, що нам усе ще потрібно використовувати & перед скороченням self, щоб позначити, що цей метод запозичує екземпляр Self, так само як ми робили в rectangle: &Rectangle. Методи можуть брати володіння на self, запозичувати self незмінно, як ми зробили тут, або запозичувати self змінно, так само як і будь-який інший параметр.

Ми вибрали тут &self з тієї ж причини, з якої використовували &Rectangle у версії функції: Ми не хочемо брати володіння, і ми лише хочемо читати дані в структурі, а не записувати в них. Якби ми хотіли змінити екземпляр, на якому ми викликали метод, як частину того, що робить метод, ми б використали &mut self як перший параметр. Мати метод, який бере володіння на екземпляр, використовуючи лише self як перший параметр, трапляється рідко; цю техніку зазвичай використовують, коли метод перетворює self на щось інше, і ви хочете заборонити викликачу використовувати оригінальний екземпляр після перетворення.

Головна причина використовувати методи замість функцій, окрім надання синтаксису методів і відсутності потреби повторювати тип self у сигнатурі кожного методу, — це організація. Ми зібрали все, що можемо робити з екземпляром типу, в одному блоці impl, а не змушуємо майбутніх користувачів нашого коду шукати можливості Rectangle у різних місцях у бібліотеці, яку ми надаємо.

Зверніть увагу, що ми можемо дати методу те саме ім’я, що й одному з полів структури. Наприклад, ми можемо визначити метод для Rectangle, який також називається width:

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

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

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

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

Тут ми вирішуємо зробити так, щоб метод width повертав true, якщо значення в полі width екземпляра більше за 0, і false, якщо значення дорівнює 0: Ми можемо використовувати поле всередині методу з тим самим іменем для будь-якої мети. У main, коли ми додаємо круглі дужки після rect1.width, Rust знає, що ми маємо на увазі метод width. Коли ми не використовуємо круглі дужки, Rust знає, що ми маємо на увазі поле width.

Часто, але не завжди, коли ми даємо методу те саме ім’я, що й поле, ми хочемо, щоб він лише повертав значення поля і більше нічого не робив. Такі методи називаються гетерами, і Rust не реалізує їх автоматично для полів структури, як це роблять деякі інші мови. Гетери корисні, тому що ви можете зробити поле приватним, але метод — публічним і таким чином надати доступ лише для читання до цього поля як частини публічного API типу. Ми обговоримо, що таке публічне і приватне та як позначити поле або метод як публічний чи приватний у Розділі 7.

Де оператор ->?

У C і C++, для виклику методів використовуються два різні оператори: Ви використовуєте . якщо викликаєте метод безпосередньо на об’єкті, і -> якщо ви викликаєте метод на вказівнику на об’єкт і спочатку потрібно розіменувати вказівник. Іншими словами, якщо object — це вказівник, object->something() подібне до (*object).something().

У Rust немає еквівалента оператору ->; натомість у Rust є можливість, яка називається автоматичне посилання та розіменування. Виклик методів — одне з небагатьох місць у Rust із такою поведінкою.

Ось як це працює: Коли ви викликаєте метод за допомогою object.something(), Rust автоматично додає &, &mut або *, щоб object відповідав сигнатурі методу. Іншими словами, наведене нижче є однаковим:

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

Перше виглядає значно охайніше. Така автоматична поведінка посилання працює тому, що методи мають чіткий одержувач — тип self. Маючи одержувача та ім’я методу, Rust може безпомилково визначити, чи метод читає (&self), змінює (&mut self) або споживає (self). Той факт, що Rust робить запозичення неявним для одержувачів методів, — велика частина того, що робить володіння ергономічною на практиці.

Методи з більшою кількістю параметрів

Давайте попрактикуємося у використанні методів, реалізувавши другий метод для структури Rectangle. Цього разу ми хочемо, щоб екземпляр Rectangle приймав інший екземпляр Rectangle і повертав true, якщо другий Rectangle може повністю поміститися всередині self (першого Rectangle); інакше він повинен повертати false. Тобто, після того як ми визначимо метод can_hold, ми хочемо мати змогу написати програму, показану в Лістингу 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Очікуваний вивід виглядав би так, як наведено нижче, тому що обидва виміри rect2 менші за виміри rect1, але rect3 ширший за rect1:

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

Ми знаємо, що хочемо визначити метод, отже він буде в блоці impl Rectangle. Ім’я методу буде can_hold, і він прийматиме незмінне запозичення іншого Rectangle як параметр. Ми можемо зрозуміти, яким буде тип параметра, подивившись на код, що викликає метод: rect1.can_hold(&rect2) передає &rect2, яке є незмінним запозиченням rect2, екземпляра Rectangle. Це має сенс, тому що нам потрібно лише читати rect2 (а не записувати, що означало б, що нам знадобиться змінне запозичення), і ми хочемо, щоб main зберіг володіння над rect2, щоб ми могли використати його знову після виклику методу can_hold. Значення, що повертається can_hold, буде логічним, а реалізація перевірятиме, чи ширина і висота self більші за ширину і висоту іншого Rectangle відповідно. Давайте додамо новий метод can_hold до блоку impl із Лістингу 5-13, показаного в Лістингу 5-15.

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

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

Асоційовані функції

Усі функції, визначені в блоці impl, називаються асоційованими функціями тому що вони пов’язані з типом, названим після impl. Ми можемо визначати асоційовані функції, які не мають self як свій перший параметр (і отже не є методами), тому що їм не потрібен екземпляр типу, з яким працювати. Ми вже використали одну таку функцію: функцію String::from, яка визначена для типу String.

Асоційовані функції, які не є методами, часто використовуються як конструктори, що повертатимуть новий екземпляр структури. Їх часто називають new, але new — не спеціальне ім’я і не вбудоване в мову. Наприклад, ми могли б вирішити надати асоційовану функцію з назвою square, яка мала б один параметр розміру та використовувала б його і як ширину, і як висоту, таким чином полегшуючи створення квадратної Rectangle замість того, щоб указувати одне й те саме значення двічі:

Filename: src/main.rs

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

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

Ключові слова Self у типі, що повертається, та в тілі функції є псевдонімами для типу, який стоїть після ключового слова impl, яким у цьому випадку є Rectangle.

Щоб викликати цю асоційовану функцію, ми використовуємо синтаксис :: з назвою структури; let sq = Rectangle::square(3); — це приклад. Ця функція має простір імен структури: Синтаксис :: використовується як для асоційованих функцій, так і для просторів імен, створених модулями. Ми обговоримо модулі в Розділі 7.

Кілька блоків impl

Кожна структура може мати кілька блоків impl. Наприклад, Лістинг 5-15 еквівалентний коду, показаному в Лістингу 5-16, який має кожен метод у власному блоці impl.

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

це допустимий синтаксис. Ми побачимо випадок, у якому кілька блоків impl є корисними, у Розділі 10, де ми обговорюємо узагальнені типи та трейти.

Підсумок

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

Але структури — не єдиний спосіб створювати власні типи: Давайте звернемося до можливості перелічень (enums) у Rust, щоб додати ще один інструмент до вашого набору інструментів.

Перелічення та зіставлення зі зразком (Enums and Pattern Matching)

У цьому розділі ми розглянемо перелічення, також відомі як enum. Перелічення (Enums) дають змогу визначити тип, перелічуючи його можливі варіанти. Спочатку ми визначимо та використаємо перелічення (enum), щоб показати, як перелічення (enum) може кодувати значення разом із даними. Далі ми дослідимо особливо корисне перелічення (enum) під назвою Option, яке виражає, що значення може бути або чимось, або нічим. Потім ми розглянемо, як зіставлення зі зразком у виразі match робить простим запуск різного коду для різних значень перелічення (enum). Нарешті, ми охопимо, як конструкція if let є ще однією зручною та стислою ідіомою, доступною для обробки перелічень (enums) у вашому коді.

Визначення переліку

Визначення перелічення (Defining an Enum)

Там, де структури дають вам спосіб групувати пов’язані поля та дані, як-от Rectangle з його width і height, перелічення (enum) дають вам спосіб сказати, що значення є одним із можливого набору значень. Наприклад, ми можемо захотіти сказати, що Rectangle є одним із набору можливих фігур, до якого також входять Circle і Triangle. Щоб зробити це, Rust дозволяє нам кодувати ці можливості як перелічення (enum).

Давайте подивимося на ситуацію, яку ми могли б виразити в коді, і побачимо, чому перелічення (enum) корисніші та доречніші за структури в цьому випадку. Припустімо, нам потрібно працювати з IP-адресами. Наразі для IP-адрес використовуються два основні стандарти: версія чотири і версія шість. Оскільки це єдині можливості для IP-адреси, з якими зіткнеться наша програма, ми можемо перелічити всі можливі варіанти, звідси й походить назва перелічення (enum).

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

Ми можемо виразити цю концепцію в коді, визначивши перелічення IpAddrKind і перелічивши можливі види, якими може бути IP-адреса, V4 і V6. Це варіанти перелічення:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind тепер є власним типом даних, який ми можемо використовувати в іншому місці нашого коду.

Значення перелічень

Ми можемо створити екземпляри кожного з двох варіантів IpAddrKind ось так:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

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

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

І ми можемо викликати цю функцію з будь-яким із варіантів:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Використання перелічень має ще більше переваг. Якщо подумати ще раз про наш тип IP-адреси, зараз у нас немає способу зберегти фактичні дані IP-адреси; ми знаємо лише, який це вид. Враховуючи, що ви щойно дізналися про структури в Розділі 5, у вас може виникнути спокуса розв’язати цю проблему за допомогою структур, як показано у Лістингу 6-1.

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

Тут ми визначили структуру IpAddr, яка має два поля: поле kind, що має тип IpAddrKind (перелічення, яке ми визначили раніше), і поле address типу String. У нас є два екземпляри цієї структури. Перший — home, і він має значення IpAddrKind::V4 як своє kind із пов’язаними даними адреси 127.0.0.1. Другий екземпляр — loopback. Він має інший варіант IpAddrKind як значення свого kind, V6, і має пов’язану з ним адресу ::1. Ми використали структуру, щоб об’єднати значення kind і address разом, тож тепер варіант пов’язаний зі значенням.

Однак подати ту саму концепцію, використовуючи лише перелічення, лаконічніше: Замість перелічення всередині структури ми можемо помістити дані безпосередньо в кожен варіант перелічення. Це нове визначення перелічення IpAddr каже, що і варіант V4, і варіант V6 матимуть пов’язані значення String:

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

Ми приєднуємо дані до кожного варіанта перелічення безпосередньо, тож додаткова структура не потрібна. Тут також легше побачити ще одну деталь того, як працюють перелічення: Назва кожного визначеного нами варіанта перелічення також стає функцією, яка створює екземпляр перелічення. Тобто IpAddr::V4() — це виклик функції, який приймає аргумент String і повертає екземпляр типу IpAddr. Ми автоматично отримуємо визначення цієї функції-конструктора як результат визначення перелічення.

Є ще одна перевага використання перелічення замість структури: Кожен варіант може мати різні типи та обсяги пов’язаних даних. IP-адреси версії чотири завжди матимуть чотири числові компоненти, значення яких будуть між 0 і 255. Якби ми хотіли зберігати адреси V4 як чотири значення u8, але все ще подавати адреси V6 як одне значення String, ми не змогли б зробити це за допомогою структури. Перелічення легко справляються з цим випадком:

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

Ми показали кілька різних способів визначення структур даних для зберігання IP-адрес версії чотири та версії шість. Однак, як виявляється, бажання зберігати IP-адреси й кодувати, до якого виду вони належать, настільки поширене, що стандартна бібліотека має визначення, яке ми можемо використати! Давайте подивимося, як стандартна бібліотека визначає IpAddr. Вона має точнісінько той самий перелічення і ті самі варіанти, які ми визначили та використали, але вона вбудовує дані адреси всередину варіантів у формі двох різних структур, які визначені по-різному для кожного варіанта:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

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

Зверніть увагу, що хоча стандартна бібліотека містить визначення для IpAddr, ми все ще можемо створити та використовувати власне визначення без конфлікту, оскільки ми ще не ввели визначення стандартної бібліотеки до нашої області видимості. Ми ще поговоримо про введення типів в область видимості в Розділі 7.

Давайте подивимося на інший приклад перелічення у Лістингу 6-2: У ньому є широкий спектр типів, вбудованих у його варіанти.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

Це перелічення має чотири варіанти з різними типами:

• Quit: Не має жодних пов’язаних даних
• Move: Має іменовані поля, як і структура
• Write: Містить один String
• ChangeColor: Містить три значення i32

Визначення перелічення з такими варіантами, як у Лістингу 6-2, схоже на визначення різних видів структур, за винятком того, що перелічення не використовує ключове слово struct, і всі варіанти згруповані разом під типом Message. Такі структури могли б зберігати ті самі дані, що й попередні варіанти перелічення:

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

не змогли б так само легко визначити функцію, яка приймає будь-який із цих видів повідомлень, як ми могли б із визначеним у Лістингу 6-2 переліченням Message, яке є одним типом.

Є ще одна схожість між переліченнями та структурами: Так само як ми можемо визначати методи для структур за допомогою impl, ми також можемо визначати методи для перелічень. Ось метод під назвою call, який ми могли б визначити для нашого перелічення Message:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

Тіло методу використовувало б self, щоб отримати значення, для якого ми викликали метод. У цьому прикладі ми створили змінну m, яка має значення Message::Write(String::from("hello")), і саме це значення буде в self у тілі методу call, коли виконується m.call().

Давайте подивимося на ще одне перелічення в стандартній бібліотеці, яке є дуже поширеним і корисним: Option.

Перелічення Option

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

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

Проєктування мов програмування часто розглядають з погляду того, які можливості ви включаєте, але те, які можливості ви виключаєте, теж важливо. Rust не має можливості null, яка є в багатьох інших мовах. Null — це значення, яке означає, що там немає значення. У мовах із null змінні завжди можуть перебувати в одному з двох станів: null або не-null.

У своїй презентації 2009 року “Null References: The Billion Dollar Mistake” Тоні Гоар, винахідник null, сказав таке:

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

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

Однак концепція, яку null намагається виразити, усе ще є корисною: null — це значення, яке наразі є недійсним або відсутнім з певної причини.

Проблема не зовсім у концепції, а в конкретній реалізації. Тому Rust не має null, але має перелічення, яке може кодувати концепцію присутності або відсутності значення. Це перелічення — Option<T>, і воно [визначене стандартною бібліотекою] option ось так:

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

Перелічення Option<T> настільки корисне, що його навіть включено до prelude; вам не потрібно явно вводити його в область видимості. Його варіанти також включено до prelude: Ви можете використовувати Some і None безпосередньо без префікса Option::. Перелічення Option<T> і далі є звичайним переліченням, а Some(T) і None усе ще є варіантами типу Option<T>.

Синтаксис <T> — це можливість Rust, про яку ми ще не говорили. Це параметр узагальненого типу, і ми розглянемо узагальнені типи детальніше в Розділі 10. Наразі вам потрібно знати лише те, що <T> означає, що варіант Some перелічення Option може містити один фрагмент даних будь-якого типу, а кожен конкретний тип, який використовується замість T, робить загальний тип Option<T> іншим типом. Ось кілька прикладів використання значень Option для зберігання числових типів і типів char:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

Тип some_number — це Option<i32>. Тип some_char — це Option<char>, який є іншим типом. Rust може вивести ці типи, тому що ми вказали значення всередині варіанта Some. Для absent_number Rust вимагає від нас анотувати загальний тип Option: Компілятор не може вивести тип, який відповідний варіант Some буде містити, дивлячись лише на значення None. Тут ми повідомляємо Rust, що маємо на увазі absent_number типу Option<i32>.

Коли в нас є значення Some, ми знаємо, що значення присутнє, і це значення міститься всередині Some. Коли в нас є значення None, у певному сенсі це означає те саме, що й null: У нас немає дійсного значення. То чому ж Option<T> кращий за null?

Коротко кажучи, тому що Option<T> і T (де T може бути будь-яким типом) є різними типами, компілятор не дозволить нам використовувати значення Option<T> так, ніби воно точно є дійсним значенням. Наприклад, цей код не скомпілюється, тому що він намагається додати i8 до Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

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

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

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

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

Іншими словами, ви маєте перетворити Option<T> на T перед тим, як зможете виконувати з ним операції T. Загалом це допомагає виявити одну з найпоширеніших проблем із null: припущення, що щось не є null, тоді як насправді це так.

Усунення ризику помилкового припущення про значення не-null допомагає вам бути впевненішими у своєму коді. Щоб мати значення, яке потенційно може бути null, ви повинні явно погодитися на це, зробивши тип цього значення Option<T>. Потім, коли ви використовуєте це значення, ви зобов’язані явно обробити випадок, коли значення є null. У будь-якому місці, де значення має тип, який не є Option<T>, ви можете безпечно припустити, що значення не є null. Це було свідоме рішення в дизайні Rust, щоб обмежити повсюдність null та підвищити безпеку коду Rust.

То як же отримати значення T із варіанта Some, коли у вас є значення типу Option<T>, щоб ви могли використати це значення? Перелічення Option<T> має велике число методів, корисних у різних ситуаціях; ви можете ознайомитися з ними в його документації. Ознайомлення з методами Option<T> буде надзвичайно корисним на вашому шляху з Rust.

Загалом, щоб використовувати значення Option<T>, вам потрібен код, який оброблятиме кожен варіант. Вам потрібен певний код, який виконуватиметься лише тоді, коли у вас є значення Some(T), і цей код може використовувати внутрішнє T. Вам потрібен інший код, який виконуватиметься лише якщо у вас є значення None, і цей код не має доступного значення T. Вираз match — це конструкція керування потоком, яка робить саме це, коли використовується з переліченнями: Він виконуватиме різний код залежно від того, який варіант перелічення він має, і цей код може використовувати дані всередині значення, що зіставляється.

Конструкція керування потоком match

Конструкція керування потоком match (The match Control Flow Construct)

Rust має надзвичайно потужну конструкцію керування потоком, що називається match, яка дозволяє вам порівнювати значення з послідовністю шаблонів (patterns) і потім виконувати код на основі того, який шаблон збігається. Шаблони можуть складатися з літеральних значень, імен змінних, символів підстановки для будь-чого, і багато чого іншого; Розділ 19 охоплює всі різні види шаблонів і те, що вони роблять. Сила match походить від виразності шаблонів і того факту, що компілятор підтверджує, що всі можливі випадки оброблено.

Уявіть вираз match як схожий на машину для сортування монет: монети ковзають вниз по доріжці з отворами різного розміру вздовж неї, і кожна монета падає крізь перший отвір, який вона зустрічає і в який підходить. Так само значення проходять через кожен шаблон у match, і при першому шаблоні, у який значення “підходить”, значення падає у пов’язаний блок коду, який буде використано під час виконання.

Якщо вже про монети, давайте використаємо їх як приклад із match! Ми можемо написати функцію, яка бере невідому монету США і, подібно до машини для підрахунку, визначає, яка це монета, і повертає її вартість у центах, як показано в Лістингу 6-3.

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

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Розберімо match у функції value_in_cents. Спочатку ми записуємо ключове слово match, за яким іде вираз, яким у цьому випадку є значення coin. Це здається дуже схожим на умовний вираз, використаний з if, але є велика різниця: з if умова має обчислюватися до булевого значення, але тут це може бути будь-який тип. Тип coin у цьому прикладі — це перелічення Coin, яке ми визначили в першому рядку.

Далі йдуть гілки match. Гілка має дві частини: шаблон і деякий код. Перша гілка тут має шаблон, який є значенням Coin::Penny, а потім оператор =>, що відокремлює шаблон і код, який потрібно виконати. Код у цьому випадку — це просто значення 1. Кожна гілка відокремлюється від наступної комою.

Коли вираз match виконується, він порівнює отримане значення з шаблоном кожної гілки, по порядку. Якщо шаблон збігається зі значенням, код, пов’язаний із цим шаблоном, виконується. Якщо цей шаблон не збігається зі значенням, виконання продовжується до наступної гілки, так само як і в машині для сортування монет. Ми можемо мати стільки гілок, скільки нам потрібно: у Лістингу 6-3 наш match має чотири гілки.

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

Зазвичай ми не використовуємо фігурні дужки, якщо код у гілці match короткий, як у Лістингу 6-3, де кожна гілка просто повертає значення. Якщо ви хочете виконати кілька рядків коду в гілці match, ви повинні використовувати фігурні дужки, і тоді кома після гілки є необов’язковою. Наприклад, наступний код друкує “Lucky penny!” кожного разу, коли метод викликається з Coin::Penny, але він все одно повертає останнє значення блоку, 1:

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

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Шаблони, що прив’язуються до значень

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

Як приклад, давайте змінимо один із варіантів нашого перелічення, щоб він містив дані всередині. З 1999 по 2008 рік Сполучені Штати карбували монети quarter з різним дизайном для кожного з 50 штатів на одному боці. Жодні інші монети не мали дизайну штатів, тож лише quarter мають це додаткове значення. Ми можемо додати цю інформацію до нашого перелічення (enum), змінивши варіант Quarter, щоб він включав значення UsState, збережене всередині нього, що ми й зробили в Лістингу 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn main() {}

Уявімо, що друг намагається зібрати всі 50 state quarters. Поки ми сортуємо дріб’язок за типом монети, ми також називатимемо назву штату, пов’язаного з кожною quarter, щоб якщо це одна з тих, якої у нашого друга немає, він міг додати її до своєї колекції.

У виразі match для цього коду ми додаємо змінну під назвою state до шаблону, який відповідає значенням варіанта Coin::Quarter. Коли Coin::Quarter збігається, змінна state прив’яжеться до значення штату цієї quarter. Потім ми можемо використати state у коді для цієї гілки, ось так:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

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

Якби ми викликали value_in_cents(Coin::Quarter(UsState::Alaska)), coin було б Coin::Quarter(UsState::Alaska). Коли ми порівнюємо це значення з кожною із гілок match, жодна з них не збігається, доки ми не досягнемо Coin::Quarter(state). У цей момент прив’язка для state буде значенням UsState::Alaska. Потім ми можемо використати цю прив’язку у виразі println!, таким чином отримавши внутрішнє значення штату з варіанта Coin для Quarter.

Зіставлення match з Option<T>

У попередньому розділі ми хотіли отримати внутрішнє значення T із випадку Some при використанні Option<T>; ми також можемо обробляти Option<T> за допомогою match, як ми робили з переліченням Coin! Замість порівняння монет ми будемо порівнювати варіанти Option<T>, але спосіб роботи виразу match залишається тим самим.

Припустімо, ми хочемо написати функцію, яка бере Option<i32> і, якщо всередині є значення, додає 1 до цього значення. Якщо всередині немає значення, функція має повернути значення None і не намагатися виконувати жодних операцій.

Цю функцію дуже легко написати завдяки match, і вона виглядатиме як у Лістингу 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Розгляньмо перше виконання plus_one детальніше. Коли ми викликаємо plus_one(five), змінна x у тілі plus_one матиме значення Some(5). Потім ми порівнюємо це з кожною гілкою match:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Значення Some(5) не збігається з шаблоном None, тому ми продовжуємо до наступної гілки:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Чи збігається Some(5) із Some(i)? Так! У нас той самий варіант. i прив’язується до значення, що міститься в Some, тож i набуває значення 5. Потім виконується код у гілці match, тож ми додаємо 1 до значення i і створюємо нове значення Some із нашим підсумком 6 всередині.

Тепер розгляньмо другий виклик plus_one у Лістингу 6-5, де x є None. Ми входимо в match і порівнюємо з першою гілкою:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

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

Поєднання match і перелічень корисне в багатьох ситуаціях. Ви часто бачитимете цей шаблон у коді Rust: match проти перелічення, прив’язування змінної до даних всередині, а потім виконання коду на основі цього. Спочатку це трохи складно, але після того, як ви звикнете до цього, ви захочете мати це в усіх мовах. Це послідовно є улюбленим серед користувачів.

Зіставлення вичерпне

Є ще один аспект match, про який нам потрібно поговорити: шаблони в гілках мають охоплювати всі можливості. Розгляньте цю версію нашої функції plus_one, яка має помилку і не компілюється:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Ми не обробили випадок None, тож цей код спричинить помилку. На щастя, це помилка, яку Rust уміє виявляти. Якщо ми спробуємо скомпілювати цей код, ми отримаємо таку помилку:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

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

Rust знає, що ми не охопили кожен можливий випадок, і навіть знає, який шаблон ми забули! Зіставлення в Rust є вичерпним: ми повинні вичерпати кожну останню можливість, щоб код був дійсним. Особливо у випадку Option<T>, коли Rust не дає нам забути явно обробити випадок None, він захищає нас від припущення, що ми маємо значення, коли ми можемо мати null, таким чином роблячи неможливою помилку на мільярд доларів, про яку йшлося раніше.

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

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

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

Для перших двох гілок шаблонами є літеральні значення 3 і 7. Для останньої гілки, яка охоплює кожне інше можливе значення, шаблон є змінною, яку ми вирішили назвати other. Код, що виконується для гілки other, використовує цю змінну, передаючи її до функції move_player.

Цей код компілюється, хоча ми не перелічили всі можливі значення, які може мати u8, тому що останній шаблон збігатиметься з усіма значеннями, не переліченими явно. Цей універсальний шаблон (catch-all pattern) виконує вимогу, що match має бути вичерпним. Зверніть увагу, що ми маємо поставити гілку-заглушку останню, тому що шаблони оцінюються по порядку. Якби ми поставили гілку-заглушку раніше, інші гілки ніколи б не виконувалися, тож Rust попередить нас, якщо ми додамо гілки після гілки-заглушки!

У Rust також є шаблон, який ми можемо використовувати, коли хочемо мати заглушку, але не хочемо використовувати значення в шаблоні-заглушці: _ — це спеціальний шаблон, який збігається з будь-яким значенням і не прив’язується до цього значення. Це повідомляє Rust, що ми не збираємося використовувати значення, тож Rust не попереджатиме нас про невикористану змінну.

Давайте змінимо правила гри: тепер, якщо ви кидаєте будь-що, окрім 3 або 7, ви повинні кидати знову. Нам більше не потрібно використовувати значення-заглушку, тож ми можемо змінити наш код, щоб використовувати _ замість змінної під назвою other:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

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

Нарешті, ми ще раз змінимо правила гри так, щоб нічого іншого не відбувалося під час вашого ходу, якщо ви кидаєте будь-що, окрім 3 або 7. Ми можемо виразити це, використавши одиничне значення (unit value) (порожній тип кортежу, який ми згадували в розділі 3) як код, що йде з гілкою _:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

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

Більше про шаблони та зіставлення ми розглянемо в Розділі 19. А зараз ми перейдемо до синтаксису if let, який може бути корисним у ситуаціях, коли вираз match трохи багатослівний.

Лаконічне керування потоком за допомогою if let та let...else

Стислий керований потік виконання з if let і let...else (Concise Control Flow with if let and let...else)

Синтаксис if let дає змогу поєднати if і let у менш багатослівний спосіб для обробки значень, що відповідають одному шаблону, ігноруючи решту. Розгляньте програму у Лістингу 6-6, яка зіставляє значення Option<u8> у змінній config_max, але хоче виконати код лише якщо значення — це варіант Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

Якщо значення — Some, ми виводимо значення у варіанті Some, зв’язуючи значення зі змінною max у шаблоні. Ми не хочемо нічого робити зі значенням None. Щоб задовольнити вираз match, нам доводиться додати _ => () після обробки лише одного варіанта, що є набридливим шаблонним кодом, який потрібно додавати.

Натомість ми могли б записати це коротшим способом, використовуючи if let. Наступний код поводиться так само, як match у Лістингу 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

Синтаксис if let приймає шаблон і вираз, розділені знаком рівності. Він працює так само, як match, де вираз передається до match, а шаблон є його першою гілкою. У цьому випадку шаблон — Some(max), а max зв’язується зі значенням усередині Some. Потім ми можемо використовувати max у тілі блоку if let так само, як ми використовували max у відповідній гілці match. Код у блоці if let виконується лише якщо значення відповідає шаблону.

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

Іншими словами, ви можете думати про if let як про синтаксичний цукор для match, який запускає код, коли значення відповідає одному шаблону, а потім ігнорує всі інші значення.

Ми можемо включити else з if let. Блок коду, що йде з else, такий самий, як блок коду, що йшов би з випадком _ у виразі match, який еквівалентний if let і else. Згадайте визначення перелічення Coin у Лістингу 6-4, де варіант Quarter також містив значення UsState. Якби ми хотіли рахувати всі монети, що не є quarter, які ми бачимо, одночасно оголошуючи state quarter, ми могли б зробити це за допомогою виразу match, ось так:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

Або ми могли б використати вираз if let і else, ось так:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

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

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

Залишатися на “щасливому шляху” (happy path) з let...else

Поширений шаблон — виконати деяке обчислення, коли значення присутнє, і повернути значення за замовчуванням інакше. Продовжуючи наш приклад із монетами зі значенням UsState, якщо ми хотіли б сказати щось смішне залежно від того, наскільки стара state на quarter була, ми могли б додати метод до UsState, щоб перевірити вік state, ось так:

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

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

Потім ми могли б використати if let, щоб зіставити тип монети, створюючи змінну state у тілі умови, як у Лістингу 6-7.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

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

Це справляється із завданням, але воно перенесло роботу в тіло оператора if let, і якщо робота, яку потрібно виконати, є складнішою, може бути важко точно простежити, як пов’язані верхньорівневі гілки. Ми також могли б скористатися тим фактом, що вирази створюють значення, або щоб отримати state з if let, або щоб повернутися рано, як у Лістингу 6-8. (Ви могли б зробити щось подібне і з match.)

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

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

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

Щоб зробити цей поширений шаблон приємнішим для вираження, Rust має let...else. Синтаксис let...else приймає шаблон ліворуч і вираз праворуч, дуже подібно до if let, але він не має гілки if, лише гілку else. Якщо шаблон відповідає, він зв’яже значення зі шаблону у зовнішній області видимості. Якщо шаблон не відповідає, програма перейде до гілки else, яка має повернутися з функції.

У Лістингу 6-9 ви можете побачити, як виглядає Лістинг 6-8 при використанні let...else замість if let.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

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

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

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

Зверніть увагу, що таким чином у головному тілі функції він залишається на “щасливому шляху” (happy path), без суттєво відмінного керування потоком виконання для двох гілок, як це було з if let.

Якщо у вас є ситуація, в якій логіка вашої програми є занадто багатослівною, щоб виразити її за допомогою match, пам’ятайте, що if let і let...else також є у вашому інструментарії Rust.

Підсумок

Тепер ми розглянули, як використовувати перелічення для створення власних типів, які можуть бути одним із набору перелічених значень. Ми показали, як стандартна бібліотека Option<T> допомагає вам використовувати систему типів, щоб запобігати помилкам. Коли значення перелічення мають усередині дані, ви можете використовувати match або if let, щоб витягувати й використовувати ці значення, залежно від того, скільки випадків вам потрібно обробити.

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

Щоб надати вашим користувачам добре організований API, який є простим у використанні та відкриває рівно те, що потрібно вашим користувачам, тепер перейдемо до модулів Rust.

Керування зростаючими проєктами за допомогою пакетів, крейтів та модулів (Managing Growing Projects with Packages, Crates, and Modules)

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

Програми, які ми написали досі, були в одному модулі в одному файлі. Коли проект зростає, слід організовувати код, розділяючи його на кілька модулів, а потім на кілька файлів. Пакет може містити кілька двійкових крейтів і, необов’язково, один бібліотечний крейт. Коли пакет зростає, ви можете виділяти частини в окремі крейти, які стають зовнішніми залежностями. Цей розділ охоплює всі ці техніки. Для дуже великих проектів, що складаються з набору взаємопов’язаних пакетів, які розвиваються разом, Cargo надає робочі простори, які ми розглянемо в “Робочі простори Cargo” у розділі 14.

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

Пов’язане поняття — область видимості: вкладений контекст, у якому написано код, має набір імен, які визначені як “у межах області видимості”. Під час читання, написання та компіляції коду програмістам і компіляторам потрібно знати, чи певне ім’я в певному місці означає змінну, функцію, структуру, перелічення, модуль, константу або інший елемент, і що означає цей елемент. Ви можете створювати області видимості і змінювати, які імена перебувають у межах або поза межами області видимості. Ви не можете мати два елементи з однаковим іменем в одній області видимості; для розв’язання конфліктів імен доступні інструменти.

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

• Пакети (Packages): можливість Cargo, яка дає вам змогу будувати, тестувати і поширювати крейти
• Крейти (Crates): дерево модулів, яке створює бібліотеку або виконуваний файл
• Модулі (Modules) та use: дають вам змогу керувати організацією, областю видимості та приватністю шляхів
• Шляхи (Paths): спосіб іменування елемента, такого як структура, функція або модуль

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

Пакети та крейти

Пакети та крейти (Packages and Crates)

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

Крейт — це найменший обсяг коду, який компілятор Rust розглядає за раз. Навіть якщо ви запускаєте rustc замість cargo і передаєте один файл вихідного коду (як ми робили ще в “Основи програми Rust” у розділі 1), компілятор вважає цей файл крейтом. Крейт може містити модулі, а модулі можуть бути визначені в інших файлах, які компілюються разом із крейтом, як ми побачимо в наступних розділах.

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

Бібліотечні крейти не мають функції main і не компілюються у виконуваний файл. Натомість вони визначають функціональність, призначену для спільного використання з кількома проєктами. Наприклад, крейт rand, який ми використовували в розділі 2, надає функціональність, що генерує випадкові числа. Найчастіше, коли растацеанці (Rustaceans) кажуть “крейт”, вони мають на увазі бібліотечний крейт, і використовують “крейт” як взаємозамінне з загальним програмним поняттям “бібліотеки”.

Корінь крейту — це файл вихідного коду, з якого компілятор Rust починає роботу і який утворює кореневий модуль вашого крейту (ми детально пояснимо модулі в “Визначення модулів для керування областю видимості та приватністю”).

Пакет — це набір одного або кількох крейтів, що надає набір функціональності. Пакет містить файл Cargo.toml, який описує, як зібрати ці крейти. Cargo насправді є пакетом, який містить бінарний крейт для інструмента командного рядка, яким ви користувалися для збирання свого коду. Пакет Cargo також містить бібліотечний крейт, від якого залежить бінарний крейт. Інші проєкти можуть залежати від бібліотечного крейту Cargo, щоб використовувати ту саму логіку, яку використовує інструмент командного рядка Cargo.

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

Давайте розглянемо, що відбувається, коли ми створюємо пакет. Спочатку ми вводимо команду cargo new my-project:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

Після того як ми запускаємо cargo new my-project, ми використовуємо ls, щоб побачити, що створює Cargo. У каталозі my-project є файл Cargo.toml, який дає нам пакет. Також є каталог src, що містить main.rs. Відкрийте Cargo.toml у своєму текстовому редакторі та зауважте, що там немає згадки про src/main.rs. Cargo дотримується домовленості, що src/main.rs — це корінь крейту бінарного крейту з тією самою назвою, що й пакет. Аналогічно, Cargo знає, що якщо каталог пакета містить src/lib.rs, пакет містить бібліотечний крейт з тією самою назвою, що й пакет, а src/lib.rs — це його корінь крейту. Cargo передає файли кореня крейту до rustc, щоб зібрати бібліотеку або бінарний файл.

Тут у нас є пакет, який містить лише src/main.rs, тобто він містить лише бінарний крейт під назвою my-project. Якщо пакет містить src/main.rs і src/lib.rs, він має два крейти: бінарний і бібліотечний, обидва з тією самою назвою, що й пакет. Пакет може мати кілька бінарних крейтів, якщо розмістити файли в каталозі src/bin: кожен файл буде окремим бінарним крейтом.

Керуйте областю видимості та приватністю за допомогою модулів

Визначення модулів для керування областю видимості та приватністю (Defining Modules to Control Scope and Privacy)

У цьому розділі ми поговоримо про модулі та інші частини системи модулів, а саме шляхи (paths), які дають змогу називати елементи; ключове слово use, яке вводить шлях (path) в область видимості; і ключове слово pub, щоб робити елементи публічними. Ми також обговоримо ключове слово as, зовнішні пакети та glob-оператор.

Шпаргалка з модулів

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

• Починайте з кореня крейту: Під час компіляції крейта компілятор спочатку шукає в файлі кореня крейту (зазвичай src/lib.rs для бібліотечного крейта і src/main.rs для бінарного крейта) код для компіляції.
• Оголошення модулів: У файлі кореня крейта ви можете оголошувати нові модулі; скажімо, ви оголошуєте модуль “garden” за допомогою mod garden;. Компілятор шукатиме код модуля в таких місцях:
  • Вбудовано, всередині фігурних дужок, які замінюють крапку з комою після mod garden
  • У файлі src/garden.rs
  • У файлі src/garden/mod.rs
• Оголошення підмодулів: У будь-якому файлі, окрім кореня крейту, ви можете оголошувати підмодулі. Наприклад, ви можете оголосити mod vegetables; у src/garden.rs. Компілятор шукатиме код підмодуля всередині каталогу, названого на честь батьківського модуля, у таких місцях:
  • Вбудовано, безпосередньо після mod vegetables, у фігурних дужках замість крапки з комою
  • У файлі src/garden/vegetables.rs
  • У файлі src/garden/vegetables/mod.rs
• Шляхи (paths) до коду в модулях: Після того як модуль став частиною вашого крейта, ви можете посилатися на код у цьому модулі з будь-якого іншого місця в тому самому крейті, якщо правила приватності це дозволяють, використовуючи шлях (path) до коду. Наприклад, тип Asparagus у модулі garden vegetables буде знайдено за адресою crate::garden::vegetables::Asparagus.
• Приватне проти публічного: Код у межах модуля за замовчуванням є приватним для його батьківських модулів. Щоб зробити модуль публічним, оголосіть його з pub mod замість mod. Щоб зробити елементи всередині публічного модуля також публічними, використовуйте pub перед їхніми оголошеннями.
• Ключове слово use: В межах області видимості ключове слово use створює скорочення для елементів, щоб зменшити повторення довгих шляхів (paths). У будь-якій області видимості, яка може посилатися на crate::garden::vegetables::Asparagus, ви можете створити скорочення за допомогою use crate::garden::vegetables::Asparagus;, і відтоді вам потрібно буде лише писати Asparagus, щоб використовувати цей тип у цій області видимості.

Тут ми створюємо бінарний крейт з назвою backyard, який ілюструє ці правила. Каталог крейта, який також називається backyard, містить такі файли та каталоги:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Файл кореня крейта в цьому випадку — src/main.rs, і він містить:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

Рядок pub mod garden; каже компілятору включити код, який він знаходить у src/garden.rs, а саме:

pub mod vegetables;

Тут pub mod vegetables; означає, що код у src/garden/vegetables.rs також включається. Цей код такий:

#[derive(Debug)]
pub struct Asparagus {}

Тепер давайте перейдемо до деталей цих правил і продемонструємо їх у дії!

Групування пов’язаного коду в модулях

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

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

У ресторанній індустрії деякі частини ресторану називають front of house, а інші — back of house. Front of house — це місце, де перебувають клієнти; це охоплює те, де хости саджають клієнтів, офіціанти приймають замовлення та оплату, а бармени готують напої. Back of house — це місце, де шеф-кухарі та кухарі працюють на кухні, посудомийники прибирають, а менеджери виконують адміністративну роботу.

Щоб структурувати наш крейт у такий спосіб, ми можемо організувати його функції у вкладені модулі. Створіть новий бібліотечний крейт під назвою restaurant, виконавши cargo new restaurant --lib. Потім внесіть код з Лістингу 7-1 у src/lib.rs, щоб визначити деякі модулі та сигнатури функцій; цей код є розділом front of house.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Ми визначаємо модуль за допомогою ключового слова mod, після якого йде назва модуля (у цьому випадку front_of_house). Тіло модуля потім розміщується всередині фігурних дужок. Усередині модулів ми можемо розміщувати інші модулі, як у цьому випадку з модулями hosting і serving. Модулі також можуть містити оголошення інших елементів, таких як структури, перелічення, константи, трейти і, як у Лістингу 7-1, функції.

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

Раніше ми згадували, що src/main.rs і src/lib.rs називаються коренями крейту. Причина їхньої назви в тому, що вміст будь-якого з цих двох файлів утворює модуль із назвою crate у корені модульної структури крейта, відомої як дерево модулів.

Лістинг 7-2 показує дерево модулів для структури в Лістингу 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Це дерево показує, як деякі модулі вкладені в інші модулі; наприклад, hosting вкладений у front_of_house. Дерево також показує, що деякі модулі є сусідніми, тобто вони визначені в одному модулі; hosting і serving є сусідніми, визначеними всередині front_of_house. Якщо модуль A міститься всередині модуля B, ми кажемо, що модуль A є дочірнім модулю B, а модуль B є батьківським модулю A. Зверніть увагу, що все дерево модулів має корінь під неявним модулем із назвою crate.

Дерево модулів може нагадати вам дерево каталогів файлової системи на вашому комп’ютері; це дуже влучне порівняння! Так само як каталоги у файловій системі, ви використовуєте модулі для організації свого коду. І так само як файли в каталозі, нам потрібен спосіб знаходити наші модулі.

Шляхи для посилання на елемент у дереві модулів

Шляхи для посилання на елемент у дереві модулів (Paths for Referring to an Item in the Module Tree)

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

Шлях може мати дві форми:

• Абсолютний шлях — це повний шлях, що починається від кореня крейту; для коду із зовнішнього крейту абсолютний шлях починається з назви крейту, а для коду з поточного крейту він починається з літерала crate.
• Відносний шлях починається з поточного модуля і використовує self, super або ідентифікатор у поточному модулі.

І за абсолютним, і за відносним шляхом ідуть один або кілька ідентифікаторів, розділених подвійними двокрапками (::).

Повертаючись до Лістингу 7-1, скажімо, ми хочемо викликати функцію add_to_waitlist. Це те саме, що запитати: який шлях у функції add_to_waitlist? Лістинг 7-3 містить Лістинг 7-1 із вилученими деякими модулями та функціями.

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

Функція eat_at_restaurant є частиною нашого публічного API бібліотечного крейту, тому ми позначаємо її ключовим словом pub. У розділі “Відкриття шляхів за допомогою ключового слова pub” ми детальніше розглянемо pub.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Перший раз, коли ми викликаємо функцію add_to_waitlist у eat_at_restaurant, ми використовуємо абсолютний шлях. Функція add_to_waitlist визначена в тому самому крейті, що й eat_at_restaurant, а це означає, що ми можемо використати ключове слово crate, щоб почати абсолютний шлях. Потім ми включаємо кожен із наступних модулів, доки не дійдемо до add_to_waitlist. Ви можете уявити ту саму структуру у файловій системі: ми б вказали шлях /front_of_house/hosting/add_to_waitlist, щоб запустити програму add_to_waitlist; використання назви crate для початку від кореня крейту — це як використання / для початку від кореня файлової системи у вашій оболонці.

Другий раз, коли ми викликаємо add_to_waitlist у eat_at_restaurant, ми використовуємо відносний шлях. Шлях починається з front_of_house, назви модуля, визначеного на тому самому рівні дерева модулів, що й eat_at_restaurant. Тут файловим еквівалентом було б використання шляху front_of_house/hosting/add_to_waitlist. Починати з назви модуля означає, що шлях є відносним.

Вибір між відносним і абсолютним шляхом — це рішення, яке ви прийматимете залежно від вашого проєкту, і воно залежить від того, чи з більшою ймовірністю ви будете переміщувати код визначення елемента окремо від коду, що використовує елемент, чи разом із ним. Наприклад, якщо ми перемістимо модуль front_of_house і функцію eat_at_restaurant у модуль із назвою customer_experience, нам потрібно буде оновити абсолютний шлях до add_to_waitlist, але відносний шлях усе ще буде дійсним. Однак якщо ми перемістимо функцію eat_at_restaurant окремо в модуль із назвою dining, абсолютний шлях до виклику add_to_waitlist залишиться тим самим, але відносний шлях потрібно буде оновити. Загалом ми надаємо перевагу вказуванню абсолютних шляхів, тому що, ймовірно, ми захочемо переміщувати визначення коду та виклики елементів незалежно одне від одного.

Спробуймо скомпілювати Лістинг 7-3 і з’ясуємо, чому він ще не компілюється! Помилки, які ми отримаємо, показані в Лістингу 7-4.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
 2 |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

Повідомлення про помилки кажуть, що модуль hosting є приватним. Іншими словами, ми маємо правильні шляхи для модуля hosting і функції add_to_waitlist, але Rust не дозволить нам використовувати їх, тому що він не має доступу до приватних секцій. У Rust усі елементи (функції, методи, структури, перелічення, модулі та константи) за замовчуванням є приватними для батьківських модулів. Якщо ви хочете зробити елемент, наприклад функцію або структуру, приватним, ви поміщаєте його в модуль.

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

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

Відкриття шляхів за допомогою ключового слова pub

Повернімося до помилки в Лістингу 7-4, яка сказала нам, що модуль hosting є приватним. Ми хочемо, щоб функція eat_at_restaurant у батьківському модулі мала доступ до функції add_to_waitlist у дочірньому модулі, тому ми позначаємо модуль hosting ключовим словом pub, як показано в Лістингу 7-5.

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

На жаль, код у Лістингу 7-5 усе ще призводить до помилок компілятора, як показано в Лістингу 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

Що сталося? Додавання ключового слова pub перед mod hosting робить модуль публічним. З цією зміною, якщо ми можемо отримати доступ до front_of_house, ми можемо отримати доступ до hosting. Але вміст hosting усе ще приватний; зробити модуль публічним не означає зробити публічним його вміст. Ключове слово pub для модуля лише дозволяє коду в його модулях-предках посилатися на нього, але не отримувати доступ до його внутрішнього коду. Оскільки модулі є контейнерами, мало що можна зробити, лише зробивши модуль публічним; нам потрібно піти далі й обрати також зробити один або кілька елементів усередині модуля публічними.

Помилки в Лістингу 7-6 кажуть, що функція add_to_waitlist є приватною. Правила приватності застосовуються також до структур, перелічень, функцій і методів, а також до модулів.

Давайте також зробимо функцію add_to_waitlist публічною, додавши ключове слово pub перед її визначенням, як у Лістингу 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

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

В абсолютному шляху ми починаємо з crate, кореня дерева модулів нашого крейту. Модуль front_of_house визначений у корені крейту. Хоча front_of_house не є публічним, оскільки функція eat_at_restaurant визначена в тому самому модулі, що й front_of_house (тобто eat_at_restaurant і front_of_house є сусідніми), ми можемо посилатися на front_of_house із eat_at_restaurant. Далі йде модуль hosting, позначений pub. Ми можемо отримати доступ до батьківського модуля hosting, тож ми можемо отримати доступ до hosting. Нарешті, функція add_to_waitlist позначена pub, і ми можемо отримати доступ до її батьківського модуля, тож цей виклик функції працює!

У відносному шляху логіка така сама, як і в абсолютному шляху, за винятком першого кроку: замість початку від кореня крейту шлях починається з front_of_house. Модуль front_of_house визначений у тому самому модулі, що й eat_at_restaurant, тому відносний шлях, що починається з модуля, у якому визначено eat_at_restaurant, працює. Потім, оскільки hosting і add_to_waitlist позначені pub, решта шляху працює, і цей виклик функції є дійсним!

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

Найкращі практики для пакетів із бінарним і бібліотечним крейтом

Ми згадували, що пакет може містити як корінь бінарного крейту src/main.rs, так і корінь бібліотечного крейту src/lib.rs, і обидва крейти за замовчуванням матимуть назву пакета. Зазвичай пакети з таким шаблоном, що містять і бібліотечний, і бінарний крейт, матимуть лише стільки коду в бінарному крейді, щоб запустити виконуваний файл, який викликає код, визначений у бібліотечному крейді. Це дає змогу іншим проєктам отримати користь від максимальної функціональності, яку надає пакет, тому що код бібліотечного крейту можна спільно використовувати.

Дерево модулів слід визначати в src/lib.rs. Потім будь-які публічні елементи можна використовувати в бінарному крейді, починаючи шляхи з назви пакета. Бінарний крейт стає користувачем бібліотечного крейту так само, як повністю зовнішній крейт використовував би бібліотечний крейт: він може використовувати лише публічний API. Це допомагає вам проєктувати хороший API; ви не лише автор, а й клієнт!

У Розділі 12 ми продемонструємо цю організаційну практику на програмі командного рядка, яка міститиме і бінарний крейт, і бібліотечний крейт.

Початок відносних шляхів із super

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

Розгляньте код у Лістингу 7-8, який моделює ситуацію, коли кухар виправляє неправильне замовлення і особисто приносить його клієнту. Функція fix_incorrect_order, визначена в модулі back_of_house, викликає функцію deliver_order, визначену в батьківському модулі, вказуючи шлях до deliver_order, що починається з super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

Функція fix_incorrect_order знаходиться в модулі back_of_house, тому ми можемо використати super, щоб перейти до батьківського модуля back_of_house, яким у цьому випадку є crate, корінь. Звідти ми шукаємо deliver_order і знаходимо його. Успіх! Ми вважаємо, що модуль back_of_house і функція deliver_order імовірно залишаться в тому самому взаємозв’язку один з одним і будуть переміщені разом, якщо ми вирішимо реорганізувати дерево модулів крейту. Тому ми використали super, щоб у майбутньому нам потрібно було оновлювати менше місць у коді, якщо цей код буде переміщено в інший модуль.

Зроблення структур і перелічень публічними

Ми також можемо використовувати pub, щоб позначати структури й перелічення як публічні, але є кілька додаткових деталей використання pub зі структурами й переліченнями. Якщо ми використовуємо pub перед визначенням структури, ми робимо структуру публічною, але поля структури все ще будуть приватними. Ми можемо робити кожне поле публічним або ні в кожному окремому випадку. У Лістингу 7-9 ми визначили публічну структуру back_of_house::Breakfast із публічним полем toast і приватним полем seasonal_fruit. Це моделює випадок у ресторані, коли клієнт може вибрати тип хліба, що подається до страви, але кухар вирішує, який фрукт супроводжує страву, залежно від того, що є в сезоні та в наявності. Доступний фрукт швидко змінюється, тому клієнти не можуть вибрати фрукт або навіть побачити, який фрукт вони отримають.

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal.
    // meal.seasonal_fruit = String::from("blueberries");
}

Оскільки поле toast у структурі back_of_house::Breakfast є публічним, у eat_at_restaurant ми можемо записувати і читати поле toast, використовуючи крапкову нотацію. Зверніть увагу, що ми не можемо використовувати поле seasonal_fruit у eat_at_restaurant, тому що seasonal_fruit є приватним. Спробуйте розкоментувати рядок, що змінює значення поля seasonal_fruit, щоб побачити, яку помилку ви отримаєте!

Також зверніть увагу, що оскільки back_of_house::Breakfast має приватне поле, структура має надати публічну асоційовану функцію, яка створює екземпляр Breakfast (ми назвали її summer). Якби Breakfast не мала такої функції, ми не змогли б створити екземпляр Breakfast у eat_at_restaurant, тому що ми не могли б встановити значення приватного поля seasonal_fruit у eat_at_restaurant.

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

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

Оскільки ми зробили перелічення Appetizer публічним, ми можемо використовувати варіанти Soup і Salad у eat_at_restaurant.

Перелічення не дуже корисні, якщо їхні варіанти не є публічними; було б незручно щоразу позначати всі варіанти перелічення pub, тому типовим значенням для варіантів перелічення є публічність. Структури часто корисні без публічності їхніх полів, тому поля структур підпорядковуються загальному правилу: усе за замовчуванням приватне, якщо не позначено pub.

Є ще одна ситуація, пов’язана з pub, яку ми не розглядали, і це наша остання можливість системи модулів: ключове слово use. Спочатку ми окремо розглянемо use, а потім покажемо, як поєднати pub і use.

Введення шляхів в область видимості за допомогою ключового слова use

Додавання шляхів до області видимості за допомогою ключового слова use (Bringing Paths into Scope with the use Keyword)

Необхідність виписувати шляхи для виклику функцій може здаватися незручною і повторюваною. У Лістингу 7-7, незалежно від того, чи обрали ми абсолютний чи відносний шлях до функції add_to_waitlist, кожного разу, коли ми хотіли викликати add_to_waitlist, нам також доводилося вказувати front_of_house і hosting. На щастя, є спосіб спростити цей процес: ми можемо один раз створити скорочення до шляху за допомогою ключового слова use, а потім використовувати коротшу назву всюди ще в межах області видимості.

У Лістингу 7-11 ми додаємо модуль crate::front_of_house::hosting до області видимості функції eat_at_restaurant, так що нам потрібно вказувати лише hosting::add_to_waitlist, щоб викликати функцію add_to_waitlist у eat_at_restaurant.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Додавання use і шляху до області видимості подібне до створення символічного посилання у файловій системі. Додавши use crate::front_of_house::hosting у корені крейту, hosting тепер є дійсною назвою в цій області видимості, ніби модуль hosting було визначено в корені крейту. Шляхи, додані до області видимості за допомогою use, також перевіряють приватність, як і будь-які інші шляхи.

Зверніть увагу, що use створює скорочення лише для конкретної області видимості, в якій відбувається use. Лістинг 7-12 переміщує функцію eat_at_restaurant до нового дочірнього модуля на ім’я customer, який тоді є іншою областю видимості, ніж оператор use, тому тіло функції не скомпілюється.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

Повідомлення компілятора про помилку показує, що скорочення більше не застосовується всередині модуля customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of unresolved module or unlinked crate `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   |
   = help: if you wanted to use a crate named `hosting`, use `cargo add hosting` to add it to your `Cargo.toml`
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

Зверніть увагу, що також є попередження про те, що use більше не використовується у своїй області видимості! Щоб виправити цю проблему, перемістіть use також усередину модуля customer, або зверніться до скорочення в батьківському модулі за допомогою super::hosting всередині дочірнього модуля customer.

Створення ідіоматичних шляхів use

У Лістингу 7-11 ви могли замислитися, чому ми вказали use crate::front_of_house::hosting, а потім викликали hosting::add_to_waitlist у eat_at_restaurant, замість того щоб вказати шлях use аж до функції add_to_waitlist, щоб досягти того самого результату, як у Лістингу 7-13.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

Хоча і Лістинг 7-11, і Лістинг 7-13 виконують одне й те саме завдання, Лістинг 7-11 є ідіоматичним способом додати функцію до області видимості за допомогою use. Додавання до області видимості батьківського модуля функції за допомогою use означає, що під час виклику функції нам доводиться вказувати батьківський модуль. Вказування батьківського модуля під час виклику функції робить зрозумілим, що функція не визначена локально, і водночас мінімізує повторення повного шляху. Код у Лістингу 7-13 не дає зрозуміти, де визначено add_to_waitlist.

З іншого боку, коли за допомогою use додаються структури, перелічення та інші елементи, ідіоматично вказувати повний шлях. Лістинг 7-14 показує ідіоматичний спосіб додати структуру HashMap зі стандартної бібліотеки до області видимості бінарного крейту.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

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

Виняток із цього ідіому — якщо ми додаємо до області видимості за допомогою операторів use два елементи з однаковою назвою, тому що Rust не дозволяє цього. Лістинг 7-15 показує, як додати до області видимості два типи Result, що мають однакову назву, але різні батьківські модулі, і як на них посилатися.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

Як бачите, використання батьківських модулів розрізняє два типи Result. Якби натомість ми вказали use std::fmt::Result і use std::io::Result, у нас було б два типи Result в одній і тій самій області видимості, і Rust не знав би, який саме з них ми маємо на увазі, коли використовуємо Result.

Надання нових назв за допомогою ключового слова as

Існує ще одне рішення проблеми додавання двох типів з однаковою назвою до однієї й тієї самої області видимості за допомогою use: після шляху ми можемо вказати as і нову локальну назву, або псевдонім, для типу. Лістинг 7-16 показує інший спосіб написати код із Лістингу 7-15, перейменувавши один із двох типів Result за допомогою as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

У другому операторі use ми вибрали нову назву IoResult для типу std::io::Result, яка не конфліктуватиме з Result зі std::fmt, який ми також додали до області видимості. Лістингу 7-15 і Лістингу 7-16 вважаються ідіоматичними, тож вибір за вами!

Повторне виведення назв за допомогою pub use

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

Лістинг 7-17 показує код із Лістингу 7-11, у якому use у кореневому модулі змінено на pub use.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

До цієї зміни зовнішній код мав би викликати функцію add_to_waitlist, використовуючи шлях restaurant::front_of_house::hosting::add_to_waitlist(), що також вимагало б, щоб модуль front_of_house було позначено як pub. Тепер, коли цей pub use повторно вивів модуль hosting з кореневого модуля, зовнішній код може натомість використовувати шлях restaurant::hosting::add_to_waitlist().

Повторне виведення корисне, коли внутрішня структура вашого коду відрізняється від того, як програмісти, що викликають ваш код, сприймали б цю предметну область. Наприклад, у цій метафорі з рестораном люди, які керують ресторанами, думають про “front of house” і “back of house”. Але відвідувачі ресторану, ймовірно, не думатимуть про частини ресторану в таких термінах. За допомогою pub use ми можемо писати наш код з однією структурою, але експонувати іншу структуру. Це робить нашу бібліотеку добре організованою як для програмістів, що працюють над бібліотекою, так і для програмістів, що викликають бібліотеку. Ми розглянемо ще один приклад pub use і те, як це впливає на документацію вашого крейту в “Експортування зручного публічного API” у розділі 14.

Використання зовнішніх пакетів

У розділі 2 ми створили проєкт гри в вгадування, який використовував зовнішній пакет під назвою rand, щоб отримувати випадкові числа. Щоб використати rand у нашому проєкті, ми додали цей рядок до Cargo.toml:

rand = "0.8.5"

Додавання rand як залежності в Cargo.toml каже Cargo завантажити пакет rand і будь-які залежності з crates.io та зробити rand доступним для нашого проєкту.

Потім, щоб додати визначення rand до області видимості нашого пакета, ми додали рядок use, що починається з назви крейту, rand, і перелічили елементи, які хотіли додати до області видимості. Згадайте, що в “Generating a Random Number” у розділі 2 ми додали трейт Rng до області видимості і викликали функцію rand::thread_rng:

use std::io;

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

Члени спільноти Rust зробили багато пакетів доступними на crates.io, і додавання будь-якого з них до вашого пакета передбачає ті самі кроки: перелічити їх у файлі Cargo.toml вашого пакета і використовувати use, щоб додати елементи з їхніх крейтів до області видимості.

Зверніть увагу, що стандартна бібліотека std також є крейтом, який є зовнішнім щодо нашого пакета. Оскільки стандартна бібліотека постачається разом із мовою Rust, нам не потрібно змінювати Cargo.toml, щоб включити std. Але нам потрібно посилатися на неї за допомогою use, щоб додати елементи звідти до області видимості нашого пакета. Наприклад, для HashMap ми б використали цей рядок:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Це абсолютний шлях, що починається з std, назви крейту стандартної бібліотеки.

Використання вкладених шляхів для впорядкування списків use

Якщо ми використовуємо кілька елементів, визначених в одному й тому самому крейді або модулі, перелік кожного елемента в окремому рядку може зайняти багато вертикального місця у наших файлах. Наприклад, ці два оператори use, які були в нас у грі в вгадування у Лістингу 2-4, додають елементи зі std до області видимості:

use rand::Rng;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

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

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

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

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

    let mut guess = String::new();

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

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

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

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

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

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

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

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

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

    let mut guess = String::new();

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

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

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

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

У більших програмах додавання багатьох елементів до області видимості з того самого крейту або модуля за допомогою вкладених шляхів може значно зменшити кількість окремих операторів use, які потрібні!

Ми можемо використовувати вкладений шлях на будь-якому рівні в шляху, що корисно, коли поєднуються два оператори use, які мають спільний підшлях. Наприклад, Лістинг 7-19 показує два оператори use: один, що додає std::io до області видимості, і один, що додає std::io::Write до області видимості.

use std::io;
use std::io::Write;

Спільною частиною цих двох шляхів є std::io, і це повний перший шлях. Щоб об’єднати ці два шляхи в один оператор use, ми можемо використати self у вкладеному шляху, як показано у Лістингу 7-20.

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

Цей рядок додає std::io і std::io::Write до області видимості.

Імпортування елементів за допомогою оператора glob

Якщо ми хочемо додати до області видимості всі публічні елементи, визначені в шляху, ми можемо вказати цей шлях, за яким іде оператор glob *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Цей оператор use додає всі публічні елементи, визначені в std::collections, до поточної області видимості. Будьте обережні, коли використовуєте оператор glob! Glob може ускладнити визначення того, які назви є в області видимості і де було визначено назву, використану у вашій програмі. Крім того, якщо залежність змінює свої визначення, імпортоване вами теж змінюється, що може призвести до помилок компілятора під час оновлення залежності, якщо залежність додасть визначення з такою самою назвою, як і визначення вашого коду в тій самій області видимості, наприклад.

Оператор glob часто використовується під час тестування, щоб додати все, що тестується, до модуля tests; ми поговоримо про це в “Як писати тести” у розділі 11. Оператор glob також іноді використовується як частина шаблону prelude: див. документацію стандартної бібліотеки для отримання додаткової інформації про цей шаблон.

Розділення модулів на різні файли

Розділення модулів у різні файли (Separating Modules into Different Files)

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

Наприклад, давайте почнемо з коду в Лістингу 7-17, який мав кілька модулів ресторану. Ми витягнемо модулі у файли замість того, щоб усі модулі були визначені у файлі кореня крейту. У цьому випадку файл кореня крейту — це src/lib.rs, але ця процедура також працює з бінарними крейтами, чий файл кореня крейту — src/main.rs.

Спочатку ми витягнемо модуль front_of_house у його власний файл. Видаліть код усередині фігурних дужок для модуля front_of_house, залишивши лише оголошення mod front_of_house;, так щоб src/lib.rs містив код, показаний у Лістингу 7-21. Зверніть увагу, що це не скомпілюється, доки ми не створимо файл src/front_of_house.rs у Лістингу 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Далі помістіть код, що був у фігурних дужках, у новий файл із назвою src/front_of_house.rs, як показано у Лістингу 7-22. Компілятор знає, що потрібно дивитися у цей файл, тому що він натрапив на оголошення модуля в корені крейту з назвою front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Зверніть увагу, що вам потрібно завантажити файл за допомогою оголошення mod лише один раз у вашому дереві модулів. Після того як компілятор знає, що файл є частиною проєкту (і знає, де в дереві модулів розташований код через те, де ви розмістили оператор mod), інші файли у вашому проєкті повинні посилатися на код завантаженого файлу, використовуючи шлях до того місця, де він був оголошений, як описано в розділі “Шляхи для посилання на елемент у дереві модулів”. Іншими словами, mod — це не операція “include”, яку ви могли бачити в інших мовах програмування.

Далі ми витягнемо модуль hosting у його власний файл. Процес трохи відрізняється, тому що hosting — це дочірній модуль front_of_house, а не кореневого модуля. Ми розмістимо файл для hosting у новому каталозі, який буде названо за його предками в дереві модулів, у цьому випадку src/front_of_house.

Щоб почати переміщення hosting, ми змінюємо src/front_of_house.rs, щоб він містив лише оголошення модуля hosting:

pub mod hosting;

Потім ми створюємо каталог src/front_of_house і файл hosting.rs, щоб містився код, визначений у модулі hosting:

pub fn add_to_waitlist() {}

Якби ми натомість помістили hosting.rs у каталог src, компілятор би очікував, що код hosting.rs буде в модулі hosting, оголошеному в корені крейту, а не оголошеному як дочірній елемент модуля front_of_house. Правила компілятора щодо того, які файли перевіряти для коду яких модулів, означають, що каталоги й файли тісніше відповідають дереву модулів.

Альтернативні шляхи до файлів

Поки що ми охопили найбільш ідіоматичні шляхи до файлів, які використовує компілятор Rust, але Rust також підтримує старіший стиль шляху до файлу. Для модуля з назвою front_of_house, оголошеного в корені крейту, компілятор шукатиме код модуля в:

• src/front_of_house.rs (те, що ми охопили)
• src/front_of_house/mod.rs (старіший стиль, шлях, що все ще підтримується)

Для модуля з назвою hosting, який є підмодулем front_of_house, компілятор шукатиме код модуля в:

• src/front_of_house/hosting.rs (те, що ми охопили)
• src/front_of_house/hosting/mod.rs (старіший стиль, шлях, що все ще підтримується)

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

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

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

Зверніть увагу, що оператор pub use crate::front_of_house::hosting у src/lib.rs також не змінився, і use також не впливає на те, які файли компілюються як частина крейту. Ключове слово mod оголошує модулі, а Rust шукає у файлі з тим самим іменем, що й модуль, код, який потрапляє в цей модуль.

Підсумок

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

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

Загальні колекції (Common Collections)

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

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

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

Ми обговоримо, як створювати та оновлювати вектори, рядки та хеш-мапи, а також що робить кожну з них особливою.

Зберігання списків значень за допомогою векторів

Зберігання списків значень за допомогою векторів

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

Створення нового вектора

Щоб створити новий, порожній вектор, ми викликаємо функцію Vec::new, як показано в Лістингу 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Зверніть увагу, що ми додали тут анотацію типу. Оскільки ми не вставляємо жодних значень у цей вектор, Rust не знає, який саме тип елементів ми маємо намір зберігати. Це важливий момент. Вектори реалізовано за допомогою узагальнених типів; ми розглянемо, як використовувати узагальнені типи у ваших власних типах, у Розділі 10. Поки що знайте, що тип Vec<T>, наданий стандартною бібліотекою, може містити будь-який тип. Коли ми створюємо вектор для зберігання певного типу, ми можемо вказати тип у кутових дужках. У Лістингу 8-1 ми повідомили Rust, що Vec<T> у v буде містити елементи типу i32.

Частіше ви створюватимете Vec<T> з початковими значеннями, і Rust виведе тип значення, яке ви хочете зберігати, тож вам рідко потрібно робити цю анотацію типу. Rust зручно надає макрос vec!, який створить новий вектор, що містить значення, які ви йому дасте. Лістинг 8-2 створює новий Vec<i32>, що містить значення 1, 2 і 3. Цілий тип є i32, тому що це типовий цілий тип, як ми обговорювали в розділі “Типи даних” Розділу 3.

fn main() {
    let v = vec![1, 2, 3];
}

Оскільки ми надали початкові значення i32, Rust може вивести, що тип v є Vec<i32>, і анотація типу не потрібна. Далі ми розглянемо, як змінювати вектор.

Оновлення вектора

Щоб створити вектор, а потім додати до нього елементи, ми можемо використати метод push, як показано в Лістингу 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Як і для будь-якої змінної, якщо ми хочемо мати змогу змінювати її значення, нам потрібно зробити її змінною за допомогою ключового слова mut, як обговорювалося в Розділі 3. Числа , які ми розміщуємо всередині, усі мають тип i32, і Rust виводить це з даних, тож нам не потрібна анотація Vec<i32>.

Читання елементів векторів

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

Лістинг 8-4 показує обидва методи доступу до значення у векторі, із синтаксисом індексування та методом get.

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

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

Зверніть увагу на кілька деталей тут. Ми використовуємо значення індексу 2, щоб отримати третій елемент , тому що вектори індексуються за номером, починаючи з нуля. Використання & і [] дає нам посилання на елемент за значенням індексу. Коли ми використовуємо метод get з переданим як аргумент індексом, ми отримуємо Option<&T>, який можемо використовувати з match.

Rust надає ці два способи посилання на елемент, щоб ви могли вибирати, як програма поводитиметься, коли ви спробуєте використати значення індексу за межами існуючих елементів. Як приклад, давайте подивимося, що станеться, коли ми маємо вектор із п’яти елементів і потім намагаємося отримати доступ до елемента за індексом 100 обома техніками, як показано в Лістингу 8-5.

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

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

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

Коли методу get передається індекс, що лежить поза межами вектора, він повертає None без паніки. Ви б використовували цей метод, якщо доступ до елемента поза межами вектора може інколи траплятися за нормальних обставин. Тоді ваш код матиме логіку для обробки або Some(&element), або None, як обговорювалося в Розділі 6. Наприклад, індекс може надходити від людини, яка вводить число. Якщо вона випадково введе занадто велике число, і програма отримає значення None, ви могли б повідомити користувачу, скільки елементів є в поточному векторі, і дати йому ще одну спробу ввести коректне значення. Це було б дружніше до користувача, ніж аварійне завершення програми через друкарську помилку!

Коли програма має дійсне посилання, перевірник запозичень забезпечує правила володіння та запозичення (розглянуті в Розділі 4), щоб гарантувати, що це посилання та будь-які інші посилання на вміст вектора залишаються дійсними. Пригадайте правило, яке стверджує, що ви не можете мати змінні та незмінні посилання в одній і тій самій області видимості. Це правило застосовується в Лістингу 8-6, де ми тримаємо незмінне посилання на перший елемент у векторі й намагаємося додати елемент до кінця. Ця програма не працюватиме, якщо ми також спробуємо послатися на цей елемент пізніше у функції.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

Компіляція цього коду призведе до такої помилки:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                      ----- immutable borrow later used here

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

Код у Лістингу 8-6 може виглядати так, ніби він мав би працювати: чому посилання на перший елемент має зважати на зміни в кінці вектора? Ця помилка зумовлена тим, як працюють вектори: оскільки вектори розміщують значення поруч одне з одним у пам’яті, додавання нового елемента в кінець вектора може вимагати виділення нової пам’яті та копіювання старих елементів у новий простір, якщо немає достатньо місця, щоб розмістити всі елементи поруч один з одним там, де вектор зараз зберігається. У такому разі посилання на перший елемент буде вказувати на звільнену пам’ять. Правила запозичення запобігають тому, щоб програми опинялися в такій ситуації.

Примітка: Щоб дізнатися більше про деталі реалізації типу Vec<T>, дивіться “The Rustonomicon”.

Ітерування по значеннях у векторі

Щоб послідовно отримати доступ до кожного елемента у векторі, ми ітерували б по всіх елементах замість використання індексів для доступу до них по одному. Лістинг 8-7 показує, як використати цикл for, щоб отримати незмінні посилання на кожен елемент у векторі значень i32 і вивести їх.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Ми також можемо ітерувати по змінних посиланнях на кожен елемент у змінному векторі, щоби вносити зміни до всіх елементів. Цикл for у Лістингу 8-8 додасть 50 до кожного елемента.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Щоб змінити значення, на яке вказує змінне посилання, ми маємо використати оператор розіменування *, щоб дістатися до значення в i, перш ніж ми зможемо використати оператор +=. Ми ще поговоримо більше про оператор розіменування в розділі “Перехід за посиланням до значення” Розділу 15.

Ітерація по вектору, чи то незмінно, чи то змінно, є безпечною завдяки правилам перевірника запозичень. Якщо б ми спробували вставити або видалити елементи в тілах циклу for у Лістингу 8-7 та у Лістингу 8-8, ми б отримали помилку компілятора, подібну до тієї, яку отримали з кодом у Лістингу 8-6. Посилання на вектор, яке тримає цикл for, запобігає одночасному зміненню всього вектора.

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

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

Наприклад, скажімо, ми хочемо отримати значення з рядка в електронній таблиці, в якому деякі стовпці в рядку містять цілі числа, деякі числа з плаваючою комою, а деякі рядки. Ми можемо визначити перелічення, чиї варіанти зберігатимуть різні типи значень, і всі варіанти перелічення вважатимуться одним і тим самим типом: типом перелічення. Потім ми можемо створити вектор для зберігання цього перелічення і, таким чином, зрештою, зберігати різні типи. Ми продемонстрували це у Лістингу 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust потрібно знати, які типи будуть у векторі під час компіляції, щоб він знав точно, скільки пам’яті на купі буде потрібно для зберігання кожного елемента. Ми також маємо явно вказати, які типи дозволені в цьому векторі. Якби Rust дозволив вектору містити будь-який тип, існувала б імовірність, що один або більше типів спричинять помилки з операціями, виконаними над елементами вектора. Використання перелічення разом із виразом match означає, що Rust забезпечить під час компіляції, щоб було оброблено кожен можливий випадок, як обговорювалося в Розділі 6.

Якщо ви не знаєте повного набору типів, які програма отримає під час виконання, щоб зберегти їх у векторі, техніка з переліченням не працюватиме. Натомість ви можете використати об’єкт трейту, який ми розглянемо в Розділі 18.

Тепер, коли ми обговорили деякі з найпоширеніших способів використання векторів, обов’язково перегляньте документацію API для всіх численних корисних методів, визначених для Vec<T> стандартною бібліотекою. Наприклад, окрім push, метод pop видаляє й повертає останній елемент.

Звільнення вектора звільняє його елементи

Як і будь-яка інша struct, вектор звільняється, коли виходить з області видимості, як позначено у Лістингу 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

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

Перейдемо до наступного типу колекції: String!

Зберігання тексту в кодуванні UTF-8 за допомогою рядків

Зберігання UTF-8-кодованого тексту за допомогою String

Ми говорили про рядки в Розділі 4, але зараз розглянемо їх детальніше. Нові растацеанці (Rustaceans) часто застрягають на рядках з поєднання трьох причин: схильність Rust виявляти можливі помилки, рядки є складнішою структурою даних, ніж багато програмістів вважають, і UTF-8. Ці чинники поєднуються так, що це може здаватися складним, коли ви переходите з інших мов програмування.

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

Визначення рядків (Strings)

Спочатку ми визначимо, що мається на увазі під терміном string. Rust має лише один тип рядка в основній мові, а саме слайс рядка str, який зазвичай бачать у його запозиченій формі, &str. У розділі 4 ми говорили про слайси рядків, які є посиланнями на деякі UTF-8-кодовані дані рядка, що зберігаються в іншому місці. Рядкові літерали, наприклад, зберігаються в бінарному файлі програми і, отже, є слайсами рядка.

Тип String, який надається стандартною бібліотекою Rust, а не вбудований в основну мову, — це зростаючий, змінний, власний UTF-8-кодований тип рядка. Коли растацеанці (Rustaceans) кажуть про “strings” у Rust, вони можуть мати на увазі або тип String, або слайс рядка &str, а не лише один із цих типів. Хоча цей розділ здебільшого про String, обидва типи широко використовуються в стандартній бібліотеці Rust, і і String, і слайси рядка є UTF-8-кодованими.

Створення нового String

Багато з тих самих операцій, доступних з Vec<T>, також доступні з String, тому що String насправді реалізований як обгортка навколо вектора байтів із деякими додатковими гарантіями, обмеженнями та можливостями. Прикладом функції, яка працює так само з Vec<T> і String, є функція new для створення екземпляра, показана в Лістингу 8-11.

fn main() {
    let mut s = String::new();
}

Цей рядок створює новий порожній рядок під назвою s, у який ми потім можемо завантажити дані. Часто в нас буде деякі початкові дані, з яких ми хочемо почати рядок. Для цього ми використовуємо метод to_string, який доступний для будь-якого типу, що реалізує трейт Display, як це роблять рядкові літерали. Лістинг 8-12 показує два приклади.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // The method also works on a literal directly:
    let s = "initial contents".to_string();
}

Цей код створює рядок, що містить initial contents.

Ми також можемо використати функцію String::from, щоб створити String із рядкового літерала. Код у Лістингу 8-13 еквівалентний коду в Лістингу 8-12, який використовує to_string.

fn main() {
    let s = String::from("initial contents");
}

Оскільки рядки використовуються для дуже багатьох речей, ми можемо використовувати багато різних узагальнених API для рядків, що надає нам багато варіантів. Деякі з них можуть здаватися надлишковими, але кожен має своє місце! У цьому випадку String::from і to_string роблять одне й те саме, тож який із них ви оберете — це питання стилю та читабельності.

Пам’ятайте, що рядки є UTF-8-кодованими, тож ми можемо включати в них будь-які правильно закодовані дані, як показано у Лістингу 8-14.

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Усі ці значення є дійсними String.

Оновлення String

String може збільшуватися в розмірі, і його вміст може змінюватися, так само як вміст Vec<T>, якщо ви додаєте в нього більше даних. Крім того, ви можете зручно використовувати оператор + або макрос format!, щоб конкатенувати значення String.

Додавання за допомогою push_str або push

Ми можемо збільшувати String, використовуючи метод push_str для додавання слайса рядка, як показано у Лістингу 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

Після цих двох рядків s міститиме foobar. Метод push_str приймає слайс рядка, тому що ми не обов’язково хочемо брати володіння над параметром. Наприклад, у коді у Лістингу 8-16 ми хочемо мати змогу використовувати s2 після додавання його вмісту до s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Якби метод push_str брав володіння над s2, ми не змогли б надрукувати його значення в останньому рядку. Однак цей код працює так, як ми й очікували!

Метод push приймає один символ як параметр і додає його до String. Лістинг 8-17 додає літеру l до String за допомогою методу push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

У результаті s міститиме lol.

Конкатенація за допомогою + або format!

Часто вам потрібно буде об’єднати два наявні рядки. Один зі способів зробити це — використати оператор +, як показано у Лістингу 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

Рядок s3 міститиме Hello, world!. Причина, чому s1 більше не є дійсним після додавання, і причина, чому ми використали посилання на s2, пов’язані з сигнатурою методу, який викликається, коли ми використовуємо оператор +. Оператор + використовує метод add, сигнатура якого виглядає приблизно так:

fn add(self, s: &str) -> String {

У стандартній бібліотеці ви побачите, що add визначено з використанням узагальнених типів і асоційованих типів. Тут ми підставили конкретні типи, що і відбувається, коли ми викликаємо цей метод зі значеннями String. Ми обговоримо узагальнені типи в Розділі 10. Ця сигнатура дає нам підказки, потрібні для того, щоб зрозуміти складні моменти оператора +.

По-перше, s2 має &, що означає, що ми додаємо посилання на другий рядок до першого рядка. Це пов’язано з параметром s у функції add: ми можемо додати лише слайс рядка до String; ми не можемо додати два значення String разом. Але зачекайте — тип &s2 є &String, а не &str, як зазначено в другому параметрі add. Тож чому Лістингу 8-18 компілюється?

Причина, через яку ми можемо використати &s2 у виклику add, полягає в тому, що компілятор може перетворити аргумент &String на &str. Коли ми викликаємо метод add, Rust використовує приведення при розіменуванні (deref coercion), яке тут перетворює &s2 на &s2[..]. Ми обговоримо приведення при розіменуванні детальніше в Розділі 15. Оскільки add не бере володіння над параметром s, s2 усе ще буде дійсним String після цієї операції.

По-друге, ми можемо побачити в сигнатурі, що add бере володіння над self, тому що self не має &. Це означає, що s1 у Лістингу 8-18 буде переміщено в виклик add і більше не буде дійсним після цього. Отже, хоча let s3 = s1 + &s2; виглядає так, ніби воно скопіює обидва рядки та створить новий, цей оператор насправді бере володіння над s1, додає копію вмісту s2, а потім повертає володіння над результатом. Іншими словами, виглядає так, ніби він робить багато копій, але це не так; реалізація ефективніша за копіювання.

Якщо нам потрібно конкатенувати кілька рядків, поведінка оператора + стає громіздкою:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

На цьому етапі s буде tic-tac-toe. З усіма символами + і " важко зрозуміти, що відбувається. Для об’єднання рядків більш складними способами ми натомість можемо використати макрос format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Цей код також встановлює s у tic-tac-toe. Макрос format! працює як println!, але замість того, щоб друкувати вивід на екран, він повертає String із вмістом. Версія коду з використанням format! набагато легше читається, а код, згенерований макросом format!, використовує посилання, тож цей виклик не бере володіння над жодним зі своїх параметрів.

Індексування в рядках

У багатьох інших мовах програмування доступ до окремих символів у рядку шляхом посилання на них за індексом є дійсною і поширеною операцією. Однак якщо ви спробуєте отримати доступ до частин String за допомогою синтаксису індексування в Rust, ви отримаєте помилку. Розгляньте недійсний код у Лістингу 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

Цей код призведе до такої помилки:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = help: the trait `SliceIndex<str>` is not implemented for `{integer}`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the following other types implement trait `SliceIndex<T>`:
            `usize` implements `SliceIndex<ByteStr>`
            `usize` implements `SliceIndex<[T]>`
  = note: required for `String` to implement `Index<{integer}>`

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

Помилка розповідає історію: рядки Rust не підтримують індексування. Але чому? Щоб відповісти на це запитання, нам потрібно обговорити, як Rust зберігає рядки в пам’яті.

Внутрішнє представлення

String — це обгортка над Vec<u8>. Розгляньмо деякі наші правильно закодовані приклади UTF-8-рядків із Лістингу 8-14. Спочатку ось цей:

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

У цьому випадку len буде 4, що означає, що вектор, який зберігає рядок "Hola", має довжину 4 байти. Кожна з цих літер займає 1 байт у кодуванні UTF-8. Наступний рядок, однак, може вас здивувати (зверніть увагу, що цей рядок починається з великої кириличної літери (Ze) Зе, а не з цифри 3):

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Якби вас запитали, якою є довжина рядка, ви могли б сказати 12. Насправді відповідь Rust — 24: це кількість байтів, потрібних, щоб закодувати “Здравствуйте” у UTF-8, тому що кожне скалярне значення Unicode в цьому рядку займає 2 байти пам’яті. Отже, індекс у байтах рядка не завжди відповідатиме дійсному скалярному значенню Unicode. Щоб продемонструвати це, розгляньте цей недійсний код Rust:

let hello = "Здравствуйте";
let answer = &hello[0];

Ви вже знаєте, що answer не буде З, першою літерою. У UTF-8 перший байт З — це 208, а другий — 151, тож може здаватися, що answer насправді має бути 208, але 208 не є дійсним символом сам по собі. Повернення 208 імовірно не було б тим, чого користувач хотів би, якби попросив першу літеру цього рядка; однак це єдині дані, які Rust має в байтовому індексі 0. Користувачі загалом не хочуть, щоб поверталося байтове значення, навіть якщо рядок містить лише латинські літери: якби &"hi"[0] був дійсним кодом, що повертає байтове значення, він повернув би 104, а не h.

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

Байти, скалярні значення та графемні кластери

Ще один момент про UTF-8 полягає в тому, що насправді є три відповідні способи дивитися на рядки з точки зору Rust: як на байти, скалярні значення та графемні кластери (найближче до того, що ми називали б літерами).

Якщо ми подивимося на хіндійське слово “नमस्ते”, написане письмом деванагарі, воно зберігається як вектор значень u8, який виглядає так:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

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

['न', 'म', 'स', '्', 'त', 'े']

Тут є шість значень char, але четверте і шосте — не літери: це діакритичні знаки, які самі по собі не мають сенсу. Нарешті, якщо ми подивимося на них як на графемні кластери, ми отримаємо те, що людина назвала б чотирма літерами, з яких складається хіндійське слово:

["न", "म", "स्", "ते"]

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

Остання причина, чому Rust не дозволяє нам індексувати в String, щоб отримати символ, полягає в тому, що операції індексування очікуються такими, що завжди займають константний час (O(1)). Але з String неможливо гарантувати таку продуктивність, тому що Rust довелося б пройтися по вмісту від початку до індексу, щоб визначити, скільки було дійсних символів.

Зрізи рядків (String Slicing)

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

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

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Тут s буде &str, що містить перші 4 байти рядка. Раніше ми згадували, що кожен із цих символів мав 2 байти, а це означає, що s буде Зд.

Якби ми спробували зробити слайс лише частини байтів символу за допомогою чогось на кшталт &hello[0..1], Rust би згенерував паніку під час виконання так само, як це було б при доступі до недійсного індексу у векторі:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`

thread 'main' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

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

Ітерування по рядках

Найкращий спосіб працювати з частинами рядків — чітко визначити, чи ви хочете символи, чи байти. Для окремих скалярних значень Unicode використовуйте метод chars. Виклик chars для “Зд” розділяє та повертає два значення типу char, і ви можете ітерувати по результату, щоб отримати доступ до кожного елемента:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Цей код надрукує таке:

З
д

Альтернативно, метод bytes повертає кожен сирий байт, що може бути доречним для вашої предметної області:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Цей код надрукує 4 байти, з яких складається цей рядок:

208
151
208
180

Але не забудьте, що дійсні скалярні значення Unicode можуть складатися більш ніж з 1 байта.

Отримання графемних кластерів із рядків, як у письмі деванагарі, є складним, тому ця функціональність не надається стандартною бібліотекою. Крейтів доступно на crates.io, якщо це потрібна вам функціональність.

Обробка складнощів рядків

Підсумовуючи, рядки складні. Різні мови програмування роблять різний вибір щодо того, як показувати цю складність програмісту. Rust обрав зробити правильну обробку даних String поведінкою за замовчуванням для всіх програм Rust, що означає, що програмістам доводиться заздалегідь більше думати про обробку UTF-8-даних. Цей компроміс виявляє більше складності рядків, ніж це видно в інших мовах програмування, але він позбавляє вас необхідності пізніше у вашому життєвому циклі розробки обробляти помилки, пов’язані з не-ASCII-символами.

Добра новина полягає в тому, що стандартна бібліотека пропонує багато функціональності, побудованої на типах String і &str, щоб правильно допомагати обробляти такі складні ситуації. Обов’язково перегляньте документацію для корисних методів, таких як contains для пошуку в рядку та replace для заміни частин рядка іншим рядком.

Давайте перейдемо до чогось трохи менш складного: хеш-мапи!

Зберігання ключів із пов'язаними значеннями в hash map

Зберігання ключів із пов’язаними значеннями в хеш-мапах (Storing Keys with Associated Values in Hash Maps)

Останньою з наших загальних колекцій є хеш-мапа. Тип HashMap<K, V> зберігає відображення ключів типу K у значення типу V, використовуючи функцію хешування, яка визначає, як вона розміщує ці ключі та значення в пам’яті. Багато мов програмування підтримують цей вид структури даних, але вони часто використовують іншу назву, наприклад hash, map, object, hash table, dictionary або associative array, щоб назвати лише деякі.

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

У цьому розділі ми розглянемо базовий API хеш-мап, але багато інших переваг приховано у функціях, визначених для HashMap<K, V> стандартною бібліотекою. Як завжди, дивіться документацію стандартної бібліотеки для отримання додаткової інформації.

Створення нової хеш-мапи

Один зі способів створити порожню хеш-мапу — це використати new і додавати елементи за допомогою insert. У Лістингу 8-20 ми відстежуємо рахунки двох команд, чиї назви — Blue та Yellow. Команда Blue починає з 10 очок, а команда Yellow починає з 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Зверніть увагу, що спочатку нам потрібно use HashMap із розділу колекцій стандартної бібліотеки. Із наших трьох загальних колекцій ця використовується найрідше, тому вона не входить до можливостей, які автоматично підключаються в область видимості в prelude. Хеш-мапи також мають меншу підтримку з боку стандартної бібліотеки; наприклад, для їх створення немає вбудованого макроса.

Так само, як і вектори, хеш-мапи зберігають свої дані в купі. Ця HashMap має ключі типу String і значення типу i32. Як і вектори, хеш-мапи є однорідними: усі ключі мають мати той самий тип, і всі значення мають мати той самий тип.

Доступ до значень у хеш-мапі

Ми можемо отримати значення з хеш-мапи, передавши її ключ у метод get, як показано у Лістингу 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Тут score матиме значення, пов’язане з командою Blue, і результат буде 10. Метод get повертає Option<&V>; якщо для цього ключа в хеш-мапі немає значення, get поверне None. Ця програма обробляє Option, викликаючи copied, щоб отримати Option<i32> замість Option<&i32>, а потім unwrap_or, щоб встановити score у нуль, якщо scores не має запису для цього ключа.

Ми можемо ітеруватися по кожній парі ключ-значення в хеш-мапі подібним способом, як це робимо з векторами, використовуючи цикл for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Цей код надрукує кожну пару в довільному порядку:

Yellow: 50
Blue: 10

Керування володінням в хеш-мапах

Для типів, що реалізують трейт Copy, як-от i32, значення копіюються в хеш-мапу. Для значень, що належать комусь, як-от String, значення будуть переміщені, і хеш-мапа буде володільцем цих значень, як показано у Лістингу 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

Ми не можемо використовувати змінні field_name і field_value після того, як їх було переміщено в хеш-мапу під час виклику insert.

Якщо ми вставляємо посилання на значення в хеш-мапу, значення не будуть переміщені в хеш-мапу. Значення, на які вказують посилання, мають бути дійсними протягом принаймні такого самого часу, як і хеш-мапа. Ми ще поговоримо про ці питання в “Validating References with Lifetimes” у Розділі 10.

Оновлення хеш-мапи

Хоча кількість пар ключів і значень може збільшуватися, кожен унікальний ключ може мати лише одне значення, пов’язане з ним, у певний момент часу (але не навпаки: наприклад, і команда Blue, і команда Yellow могли б мати значення 10, збережене в хеш-мапі scores).

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

Перезапис значення

Якщо ми вставляємо ключ і значення в хеш-мапу, а потім вставляємо той самий ключ з іншим значенням, значення, пов’язане з цим ключем, буде замінено. Хоча код у Лістингу 8-23 двічі викликає insert, хеш-мапа міститиме лише одну пару ключ-значення, тому що ми вставляємо значення для ключа команди Blue обидва рази.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

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

Цей код надрукує {"Blue": 25}. Початкове значення 10 було перезаписано.

Додавання ключа і значення лише якщо ключ відсутній

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

Хеш-мапи мають для цього спеціальний API під назвою entry, який приймає ключ, який ви хочете перевірити, як параметр. Значення, що повертається методом entry, — це перелічення під назвою Entry, який представляє значення, яке може існувати або не існувати. Припустімо, ми хочемо перевірити, чи має ключ для команди Yellow пов’язане з ним значення. Якщо ні, ми хочемо вставити значення 50, і те саме для команди Blue. Використовуючи API entry, код виглядає як у Лістингу 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

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

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

Запуск коду у Лістингу 8-24 надрукує {"Yellow": 50, "Blue": 10}. Перший виклик entry вставить ключ для команди Yellow зі значенням 50, тому що команда Yellow уже не має значення. Другий виклик entry не змінить хеш-мапу, тому що команда Blue уже має значення 10.

Оновлення значення на основі старого значення

Інший поширений випадок використання хеш-мап — це пошук значення ключа, а потім оновлення його на основі старого значення. Наприклад, у Лістингу 8-25 показано код, який підраховує, скільки разів кожне слово з’являється в певному тексті, використовуючи хеш-мапу, де ключі — це слова, а значення — це кількість входжень для цього слова. Якщо це перший раз, коли ми бачимо слово, ми спочатку вставимо значення 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

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

Цей код надрукує {"world": 2, "hello": 1, "wonderful": 1}. Ви можете побачити ті самі пари ключ-значення, надруковані в іншому порядку: пригадайте з “Доступ до значень у хеш-мапі”, що ітерація по хеш-мапі відбувається в довільному порядку.

Метод split_whitespace повертає ітератор по підзрізах, розділених пробільними символами, значення в text. Метод or_insert повертає змінне посилання (&mut V) на значення для вказаного ключа. Тут ми зберігаємо це змінне посилання в змінній count, тож щоб присвоїти це значення, ми спочатку маємо розіменувати count за допомогою зірочки (*). Змінне посилання виходить з області видимості наприкінці циклу for, тому всі ці зміни є безпечними й дозволеними правилами запозичення.

Функції хешування

За замовчуванням HashMap використовує функцію хешування під назвою SipHash, яка може забезпечити захист від атак відмови в обслуговуванні (DoS), пов’язаних із хеш-таблицями¹. Це не найшвидший доступний алгоритм хешування, але компроміс заради кращої безпеки, який супроводжується падінням продуктивності, того вартий. Якщо ви профілюєте свій код і виявите, що типова функція хешування занадто повільна для ваших потреб, ви можете переключитися на іншу функцію, вказавши інший хешер. Хешер — це тип, який реалізує трейт BuildHasher. Ми поговоримо про трейти та про те, як їх реалізовувати, у Розділі 10. Вам не обов’язково реалізовувати власний хешер з нуля; crates.io має бібліотеки, якими діляться інші користувачі Rust і які надають хешери, що реалізують багато поширених алгоритмів хешування.

Підсумок

Вектори, рядки та хеш-мапи надають велику кількість функціональності, необхідної в програмах, коли вам потрібно зберігати, отримувати доступ і змінювати дані. Ось кілька вправ, які тепер ви маєте змогу розв’язати:

1. Маючи список цілих чисел, використайте вектор і поверніть медіану (після сортування значення в серединній позиції) і моду (значення, яке трапляється найчастіше; тут буде корисною хеш-мапа) списку.
2. Перетворіть рядки на Pig Latin. Першу приголосну кожного слова переміщено в кінець слова, і додається ay, тож first стає irst-fay. Слова, що починаються з голосної, натомість отримують додане в кінці hay (apple стає apple-hay). Пам’ятайте про деталі кодування UTF-8!
3. Використовуючи хеш-мапу та вектори, створіть текстовий інтерфейс, щоб дозволити користувачу додавати імена працівників до відділу в компанії; наприклад, “Add Sally to Engineering” або “Add Amir to Sales.” Потім дозвольте користувачу отримати список усіх людей у відділі або всіх людей у компанії за відділами, відсортований за абеткою.

Документація API стандартної бібліотеки описує методи, які мають вектори, рядки та хеш-мапи, і які будуть корисні для цих вправ!

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

1. https://en.wikipedia.org/wiki/SipHash ↩

Обробка помилок (Error Handling)

Помилки — це факт життя в програмному забезпеченні, тому Rust має низку можливостей для обробки ситуацій, у яких щось іде не так. У багатьох випадках Rust вимагає від вас визнати можливість помилки та вжити певних дій, перш ніж ваш код буде скомпільовано. Ця вимога робить вашу програму надійнішою, гарантуючи, що ви виявите помилки й обробите їх належним чином до того, як розгорнете ваш код у промислове середовище (production)!

Rust поділяє помилки на дві основні категорії: відновлювані та невідновлювані помилки. Для відновлюваної помилки, такої як помилка file not found, ми найімовірніше просто хочемо повідомити про проблему користувачу та повторити операцію. Невідновлювані помилки завжди є симптомами багів, таких як спроба отримати доступ до розташування за межами кінця масиву, і тому ми хочемо негайно зупинити програму.

Більшість мов не розрізняють ці два види помилок і обробляють обидва однаково, використовуючи механізми на кшталт виключень (exceptions). У Rust немає виключень (exceptions). Натомість він має тип Result<T, E> для відновлюваних помилок і макрос panic!, який зупиняє виконання, коли програма стикається з невідновлюваною помилкою. У цьому розділі спочатку розглядається виклик panic!, а потім говориться про повернення значень Result<T, E>. Додатково ми дослідимо міркування під час визначення, чи намагатися відновитися після помилки, чи зупинити виконання.

Невідновлювані помилки з panic!

Невідновлювані помилки з panic!

Іноді у вашому коді трапляються погані речі, і ви нічого не можете з цим зробити. У цих випадках у Rust є макрос panic!. У практиці є два способи спричинити паніку: вчинити дію, яка спричиняє паніку нашого коду (наприклад, звернення до масиву за його межами) або явно викликати макрос panic!. В обох випадках ми спричиняємо паніку в нашій програмі. За замовчуванням ці паніки друкуватимуть повідомлення про збій, розгортатимуться, очищатимуть стек і завершуватимуть роботу. Через змінну середовища ви також можете змусити Rust показувати зворотне трасування (backtrace) стека викликів, коли трапляється паніка, щоб легше було відстежити джерело паніки.

Розгортання стека або аварійне завершення у відповідь на паніку

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

Пам’ять, яку програма використовувала, тоді потрібно буде очистити операційній системі. Якщо у вашому проєкті вам потрібно зробити отриманий двійковий файл якомога меншим, ви можете перемкнутися з розгортання на аварійне завершення під час паніки, додавши panic = 'abort' до відповідних розділів [profile] у вашому файлі Cargo.toml. Наприклад, якщо ви хочете аварійно завершуватися під час паніки в фінальному (release) режимі, додайте це:

[profile.release]
panic = 'abort'

Спробуймо викликати panic! у простій програмі:

fn main() {
    panic!("crash and burn");
}

Коли ви запустите програму, ви побачите щось подібне до цього:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Виклик panic! спричиняє повідомлення про помилку, що міститься в останніх двох рядках. Перший рядок показує наше повідомлення про паніку і місце у нашому вихідному коді, де сталася паніка: src/main.rs:2:5 означає, що це другий рядок, п’ятий символ нашого файлу src/main.rs.

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

Ми можемо використати зворотне трасування (backtrace) функцій, з яких було викликано panic!, щоб з’ясувати ту частину нашого коду, яка спричиняє проблему. Щоб зрозуміти, як використовувати зворотне трасування (backtrace) panic!, давайте подивимося на ще один приклад і побачимо, як це виглядає, коли виклик panic! надходить з бібліотеки через помилку в нашому коді, а не від прямого виклику макроса нашим кодом. Лістинг 9-1 містить код, який намагається звернутися до індексу в векторі за межами діапазону допустимих індексів.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Тут ми намагаємося отримати доступ до 100-го елемента нашого вектора (який знаходиться за індексом 99, оскільки індексація починається з нуля), але вектор має лише три елементи. У цій ситуації Rust панікуватиме. Використання [] має повертати елемент, але якщо ви передаєте недійсний індекс, тут немає елемента, який Rust міг би повернути і який був би правильним.

У C спроба прочитати за кінцем структури даних є невизначеною поведінкою (undefined behavior). Ви можете отримати те, що знаходиться в розташуванні в пам’яті, яке відповідало б цьому елементу в структурі даних, навіть якщо ця пам’ять не належить цій структурі. Це називається читанням за межами буфера (buffer overread) і може призвести до вразливостей безпеки, якщо зловмисник може маніпулювати індексом так, щоб прочитати дані, до яких йому не слід мати доступу, і які зберігаються після структури даних.

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

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`

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

Ця помилка вказує на рядок 4 нашого main.rs, де ми намагаємося отримати доступ до індексу 99 вектора в v.

Рядок note: повідомляє нам, що ми можемо встановити змінну середовища RUST_BACKTRACE, щоб отримати зворотне трасування (backtrace) того, що саме сталося і спричинило помилку. Зворотне трасування (backtrace) — це список усіх функцій, які було викликано, щоб дійти до цього моменту. Зворотне трасування в Rust працює так само, як і в інших мовах: ключ до читання зворотного трасування — почати зверху й читати, доки ви не побачите файли, які написали ви. Це місце, де виникла проблема. Рядки вище цього місця — це код, який викликав ваш код; рядки нижче — це код, який викликав ваш код. Ці рядки до і після можуть включати код core Rust, код стандартної бібліотеки або крейти, які ви використовуєте. Спробуймо отримати зворотне трасування, встановивши змінну середовища RUST_BACKTRACE у будь-яке значення, крім 0. Лістинг 9-2 показує вивід, подібний до того, який ви побачите.

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:274:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/alloc/src/vec/mod.rs:3361:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Це багато виводу! Точний вивід, який ви бачите, може відрізнятися залежно від вашої операційної системи та версії Rust. Щоб отримувати зворотне трасування (backtrace) з цією інформацією, мають бути увімкнені символи налагодження. Символи налагодження вмикаються за замовчуванням під час використання cargo build або cargo run без прапорця --release, як ми робимо тут.

У виводі у Лістингу 9-2 рядок 6 зворотного трасування вказує на рядок у нашому проєкті, який спричиняє проблему: рядок 4 у src/main.rs. Якщо ми не хочемо, щоб наша програма панікувала, ми маємо почати наше розслідування з місця, на яке вказує перший рядок, що згадує файл, який ми написали. У Лістингу 9-1, де ми навмисно написали код, який панікуватиме, способом виправити паніку є не запитувати елемент за межами діапазону індексів вектора. Коли ваш код у майбутньому панікуватиме, вам потрібно буде з’ясувати, яку дію код виконує і з якими значеннями, щоб спричинити паніку, і що код має робити замість цього.

Ми повернемося до panic! і до того, коли ми повинні і коли не повинні використовувати panic! для обробки умов помилок, у розділі “Панікувати чи не панікувати” пізніше в цьому розділі. Далі ми подивимося, як відновитися після помилки за допомогою Result.

Відновлювані помилки з Result

Відновлювані помилки з Result

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

Пригадайте з “Обробка можливої невдачі за допомогою Result” у Розділі 2, що перелічення Result визначено як такий, що має два варіанти, Ok і Err, ось так:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T і E — це узагальнені (generic) параметри типу: ми докладніше обговоримо узагальнені типи в Розділі 10. Що вам потрібно знати зараз, так це те, що T представляє тип значення, яке буде повернено в разі успіху у варіанті Ok, а E представляє тип помилки, яка буде повернена в разі невдачі у варіанті Err. Оскільки Result має ці узагальнені параметри типу, ми можемо використовувати тип Result і функції, визначені для нього, в багатьох різних ситуаціях, де значення успіху і значення помилки, які ми хочемо повернути, можуть відрізнятися.

Давайте назвемо функцію, яка повертає значення Result, такою, що може завершитися невдачею. У Лістингу 9-3 ми намагаємося відкрити файл.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

Тип повернення File::open — Result<T, E>. Узагальнений параметр T був заповнений реалізацією File::open типом значення успіху, std::fs::File, який є файловим дескриптором. Тип E, що використовується у значенні помилки, — std::io::Error. Цей тип повернення означає, що виклик File::open може завершитися успіхом і повернути файловий дескриптор, з якого ми можемо читати або в який можемо записувати. Виклик функції також може завершитися невдачею: наприклад, файл може не існувати, або ми можемо не мати дозволу на доступ до файлу. Функція File::open потребує способу повідомити нам, чи вона завершилася успіхом, чи невдачею, і водночас дати нам або файловий дескриптор, або інформацію про помилку. Саме цю інформацію і передає перелічення Result.

У випадку, коли File::open завершується успіхом, значення в змінній greeting_file_result буде екземпляром Ok, що містить файловий дескриптор. У випадку, коли вона завершується невдачею, значення в greeting_file_result буде екземпляром Err, що містить більше інформації про тип помилки, яка виникла.

Нам потрібно додати до коду в Лістингу 9-3, щоб виконувати різні дії залежно від значення, яке повертає File::open. Лістинг 9-4 показує один зі способів обробити Result за допомогою базового інструмента — виразу match, про який ми говорили в Розділі 6.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {error:?}"),
    };
}

Зверніть увагу, що, як і перелічення Option, перелічення Result і його варіанти були внесені в область видимості завдяки prelude, тож нам не потрібно вказувати Result:: перед варіантами Ok і Err у гілках match.

Коли результат — Ok, цей код поверне внутрішнє значення file з варіанта Ok, і тоді ми присвоїмо це значення файлового дескриптора змінній greeting_file. Після match ми можемо використовувати файловий дескриптор для читання або запису.

Інша гілка match обробляє випадок, коли ми отримуємо значення Err від File::open. У цьому прикладі ми вирішили викликати макрос panic!. Якщо в нашому поточному каталозі немає файлу з назвою hello.txt і ми запустимо цей код, ми побачимо такий вивід від макроса panic!:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`

thread 'main' panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Як зазвичай, цей вивід точно повідомляє нам, що саме пішло не так.

Зіставлення з різними помилками

Код у Лістингу 9-4 викличе panic! незалежно від того, чому File::open завершився невдачею. Однак ми хочемо виконувати різні дії для різних причин невдачі. Якщо File::open завершився невдачею тому, що файл не існує, ми хочемо створити файл і повернути дескриптор нового файлу. Якщо File::open завершився невдачею з будь-якої іншої причини — наприклад, тому що ми не мали дозволу на відкриття файлу — ми все одно хочемо, щоб код викликав panic! так само, як це було у Лістингу 9-4. Для цього ми додаємо внутрішній вираз match, як показано у Лістингу 9-5.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            _ => {
                panic!("Problem opening the file: {error:?}");
            }
        },
    };
}

Тип значення, яке File::open повертає всередині варіанта Err, — io::Error, який є структурою, наданою стандартною бібліотекою. Ця структура має метод kind, який ми можемо викликати, щоб отримати значення io::ErrorKind. Перелічення io::ErrorKind надається стандартною бібліотекою і має варіанти, що представляють різні види помилок, які можуть виникнути під час операції io. Варіант, який ми хочемо використати, — ErrorKind::NotFound, що вказує, що файл, який ми намагаємося відкрити, ще не існує. Отже, ми виконуємо зіставлення на greeting_file_result, але також маємо внутрішнє зіставлення на error.kind().

Умова, яку ми хочемо перевірити у внутрішньому match, полягає в тому, чи є значення, повернуте error.kind(), варіантом NotFound перелічення ErrorKind. Якщо так, ми намагаємося створити файл за допомогою File::create. Однак, оскільки File::create також може завершитися невдачею, нам потрібна друга гілка у внутрішньому виразі match. Коли файл не вдається створити, виводиться інше повідомлення про помилку. Друга гілка зовнішнього match залишається тією ж, тож програма завершується панікою для будь-якої помилки, окрім помилки відсутнього файлу.

Альтернативи використанню match з Result<T, E>

Це багато match! Вираз match дуже корисний, але також дуже примітивний. У Розділі 13 ви дізнаєтеся про замикання, які використовуються з багатьма методами, визначеними на Result<T, E>. Ці методи можуть бути лаконічнішими, ніж використання match, під час обробки значень Result<T, E> у вашому коді.

Наприклад, ось ще один спосіб записати ту саму логіку, що показана в Лістингу 9-5, цього разу використовуючи замикання і метод unwrap_or_else:

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

Хоча цей код має таку саму поведінку, як у Лістингу 9-5, він не містить жодних виразів match і є чистішим для читання. Поверніться до цього прикладу після того, як прочитаєте Розділ 13, і пошукайте метод unwrap_or_else у документації стандартної бібліотеки. Є ще багато таких методів, які можуть прибрати величезні вкладені вирази match, коли ви працюєте з помилками.

Скорочені способи викликати паніку при помилці

Використання match працює достатньо добре, але це може бути дещо багатослівним і не завжди добре передає намір. Тип Result<T, E> має багато допоміжних методів, визначених для нього, щоб виконувати різні, більш специфічні завдання. Метод unwrap — це метод-швидкий спосіб, реалізований точно так само, як вираз match, який ми написали у Лістингу 9-4. Якщо значення Result є варіантом Ok, unwrap поверне значення всередині Ok. Якщо Result є варіантом Err, unwrap викличе для нас макрос panic!. Ось приклад unwrap у дії:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Якщо ми запустимо цей код без файлу hello.txt, ми побачимо повідомлення про помилку від виклику panic!, який робить метод unwrap:

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Аналогічно, метод expect також дає нам змогу обрати повідомлення про помилку для panic!. Використання expect замість unwrap і надання добрих повідомлень про помилки може передати ваш намір і полегшити пошук джерела паніки. Синтаксис expect виглядає так:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

Ми використовуємо expect так само, як unwrap: щоб повернути файловий дескриптор або викликати макрос panic!. Повідомлення про помилку, яке expect використовує у своєму виклику panic!, буде параметром, який ми передаємо до expect, а не стандартним повідомленням panic!, яке використовує unwrap. Ось як це виглядає:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

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

Поширення помилок

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

Наприклад, Лістинг 9-6 показує функцію, яка читає ім’я користувача з файлу. Якщо файл не існує або його неможливо прочитати, ця функція поверне ці помилки коду, що викликав функцію.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}
}

Цю функцію можна написати значно коротше, але ми почнемо з того, що зробимо багато чого вручну, щоб дослідити обробку помилок; наприкінці ми покажемо коротший спосіб. Спершу погляньмо на тип повернення функції: Result<String, io::Error>. Це означає, що функція повертає значення типу Result<T, E>, де узагальнений параметр T було заповнено конкретним типом String, а узагальнений тип E було заповнено конкретним типом io::Error.

Якщо ця функція завершується успіхом без будь-яких проблем, код, що викликає цю функцію, отримає значення Ok, яке містить String — username, яке ця функція прочитала з файлу. Якщо ця функція стикається з будь-якими проблемами, код, що викликає, отримає значення Err, яке містить екземпляр io::Error, що містить більше інформації про те, якими були проблеми. Ми обрали io::Error як тип повернення цієї функції, тому що саме такий тип має значення помилки, яке повертається обома операціями, які ми викликаємо в тілі цієї функції і які можуть завершитися невдачею: функцією File::open і методом read_to_string.

Тіло функції починається з виклику функції File::open. Потім ми обробляємо значення Result за допомогою match, подібного до match у Лістингу 9-4. Якщо File::open завершується успіхом, файловий дескриптор у шаблонній змінній file стає значенням у змінній username_file, і функція продовжується. У випадку Err, замість виклику panic!, ми використовуємо ключове слово return, щоб достроково вийти з функції повністю і передати значення помилки з File::open, тепер у шаблонній змінній e, назад коду, що викликає, як значення помилки цієї функції.

Отже, якщо ми маємо файловий дескриптор у username_file, функція потім створює новий String у змінній username і викликає метод read_to_string на файловому дескрипторі в username_file, щоб прочитати вміст файлу в username. Метод read_to_string також повертає Result, тому що він може завершитися невдачею, навіть якщо File::open завершився успіхом. Отже, нам потрібен ще один match, щоб обробити цей Result: якщо read_to_string завершується успіхом, тоді наша функція завершується успіхом, і ми повертаємо ім’я користувача з файлу, яке тепер у username, загорнуте в Ok. Якщо read_to_string завершується невдачею, ми повертаємо значення помилки так само, як ми повертали значення помилки в match, який обробляв повернене значення File::open. Однак нам не потрібно явно писати return, тому що це останній вираз у функції.

Код, що викликає цей код, потім оброблятиме отримання або значення Ok, яке містить ім’я користувача, або значення Err, яке містить io::Error. Саме коду, що викликає, вирішувати, що робити з цими значеннями. Якщо код, що викликає, отримує значення Err, він може викликати panic! і аварійно завершити програму, використати стандартне ім’я користувача або, наприклад, шукати ім’я користувача десь, крім файлу. У нас недостатньо інформації про те, що саме намагається зробити код, що викликає, тому ми поширюємо всю інформацію про успіх або помилку вгору, щоб він обробив її належним чином.

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

Скорочений спосіб поширення помилок: оператор ?

Лістинг 9-7 показує реалізацію read_username_from_file, яка має ту саму функціональність, що й у Лістингу 9-6, але ця реалізація використовує оператор ?.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

?, поставлений після значення Result, визначено так, щоб працювати майже так само, як вирази match, які ми визначили для обробки значень Result у Лістингу 9-6. Якщо значення Result — Ok, значення всередині Ok буде повернено з цього виразу, і програма продовжить виконання. Якщо значення — Err, Err буде повернено з усієї функції так, ніби ми використали ключове слово return, щоб значення помилки було поширено до коду, що викликає.

Існує різниця між тим, що робить вираз match з Лістингу 9-6, і тим, що робить оператор ?: значення помилки, до яких застосовано оператор ?, проходять через функцію from, визначену в трейті From у стандартній бібліотеці, яка використовується для перетворення значень з одного типу в інший. Коли оператор ? викликає функцію from, отриманий тип помилки перетворюється на тип помилки, визначений у типі повернення поточної функції. Це корисно, коли функція повертає один тип помилки, щоб представити всі способи, якими функція може завершитися невдачею, навіть якщо окремі частини можуть завершитися невдачею з багатьох різних причин.

Наприклад, ми могли б змінити функцію read_username_from_file у Лістингу 9-7, щоб вона повертала власний тип помилки з назвою OurError, який ми визначаємо. Якщо ми також визначимо impl From<io::Error> for OurError, щоб створювати екземпляр OurError з io::Error, тоді виклики оператора ? у тілі read_username_from_file викликатимуть from і перетворюватимуть типи помилок без потреби додавати ще якийсь код до функції.

У контексті Лістингу 9-7, ? у кінці виклику File::open поверне значення всередині Ok у змінну username_file. Якщо виникне помилка, оператор ? достроково поверне її з усієї функції і передасть будь-яке значення Err коду, що викликає. Те саме стосується ? у кінці виклику read_to_string.

Оператор ? усуває багато шаблонного коду і робить реалізацію цієї функції простішою. Ми навіть могли б ще скоротити цей код, безпосередньо ланцюжуючи виклики методів після ?, як показано у Лістингу 9-8.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

Ми перенесли створення нового String у username на початок функції; ця частина не змінилася. Замість створення змінної username_file ми безпосередньо приєднали виклик read_to_string до результату File::open("hello.txt")?. У нас усе ще є ? у кінці виклику read_to_string, і ми все ще повертаємо значення Ok, що містить username, коли і File::open, і read_to_string завершуються успіхом, а не повертають помилки. Функціональність знову та сама, що й у Лістингу 9-6 і у Лістингу 9-7; це просто інший, більш зручний спосіб записати це.

Лістинг 9-9 показує спосіб зробити це ще коротшим, використовуючи fs::read_to_string.

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

Читання файлу в рядок — це досить поширена операція, тож стандартна бібліотека надає зручну функцію fs::read_to_string, яка відкриває файл, створює новий String, читає вміст файлу, поміщає вміст у цей String і повертає його. Звісно, використання fs::read_to_string не дає нам можливості пояснити всю обробку помилок, тож спочатку ми зробили це довшим способом.

Де можна використовувати оператор ?

Оператор ? можна використовувати лише у функціях, тип повернення яких сумісний зі значенням, на якому використовується ?. Це тому, що оператор ? визначено так, щоб виконувати дострокове повернення значення з функції, так само, як і вираз match, який ми визначили у Лістингу 9-6. У Лістингу 9-6 match використовував значення Result, а гілка дострокового повернення повертала значення Err(e). Тип повернення функції має бути Result, щоб він був сумісний з цим return.

У Лістингу 9-10 подивімося на помилку, яку ми отримаємо, якщо використаємо оператор ? у функції main з типом повернення, несумісним із типом значення, на якому ми використовуємо ?.

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Цей код відкриває файл, що може завершитися невдачею. Оператор ? іде після значення Result, поверненого File::open, але ця функція main має тип повернення (), а не Result. Коли ми компілюємо цей код, ми отримуємо таке повідомлення про помилку:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
help: consider adding return type
  |
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 |     let greeting_file = File::open("hello.txt")?;
5 +     Ok(())
  |

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

Ця помилка вказує, що нам дозволено використовувати оператор ? лише у функції, яка повертає Result, Option або інший тип, що реалізує FromResidual.

Щоб виправити помилку, у вас є два варіанти. Один варіант — змінити тип повернення вашої функції так, щоб він був сумісний зі значенням, на якому ви використовуєте оператор ?, якщо вас нічого не обмежує. Інший варіант — це використати match або один із методів Result<T, E>, щоб обробити Result<T, E> у будь-який відповідний спосіб.

У повідомленні про помилку також згадувалося, що ? можна використовувати і зі значеннями Option<T>. Як і у випадку використання ? з Result, ви можете використовувати ? на Option лише у функції, яка повертає Option. Поведінка оператора ?, коли його застосовують до Option<T>, подібна до його поведінки, коли його застосовують до Result<T, E>: якщо значення — None, Noneбуде повернено достроково з функції в цій точці. Якщо значення —Some, значення всередині Some` є результатним значенням виразу, і функція продовжується. Лістинг 9-11 містить приклад функції, яка знаходить останній символ першого рядка в заданому тексті.

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

Ця функція повертає Option<char>, тому що там може бути символ, але також може і не бути. Цей код бере аргумент-зріз рядка text і викликає на ньому метод lines, який повертає ітератор по рядках у рядку. Оскільки ця функція хоче розглянути перший рядок, вона викликає next на ітераторі, щоб отримати перше значення з ітератора. Якщо text — порожній рядок, цей виклик next поверне None, і в такому разі ми використовуємо ?, щоб зупинитися і повернути None з last_char_of_first_line. Якщо text не є порожнім рядком, next поверне значення Some, що містить зріз рядка першого рядка в text.

? витягує зріз рядка, і ми можемо викликати chars на цьому зрізі рядка, щоб отримати ітератор його символів. Нас цікавить останній символ у цьому першому рядку, тож ми викликаємо last, щоб повернути останній елемент з ітератора. Це Option, тому що можливо, що перший рядок є порожнім рядком; наприклад, якщо text починається з порожнього рядка, але має символи в інших рядках, як у "\nhi". Однак якщо в першому рядку є останній символ, він буде повернений у варіанті Some. Оператор ? посередині дає нам лаконічний спосіб виразити цю логіку, дозволяючи реалізувати функцію в один рядок. Якби ми не могли використовувати оператор ? на Option, нам би довелося реалізовувати цю логіку за допомогою більшої кількості викликів методів або виразу match.

Зверніть увагу, що ви можете використовувати оператор ? на Result у функції, яка повертає Result, і ви можете використовувати оператор ? на Option у функції, яка повертає Option, але ви не можете їх змішувати. Оператор ? не перетворює автоматично Result на Option або навпаки; у таких випадках ви можете використовувати методи на кшталт ok на Result або ok_or на Option, щоб виконати перетворення явно.

Поки що всі функції main, які ми використовували, повертають (). Функція main є особливою, тому що вона є точкою входу і точкою виходу виконуваної програми, і існують обмеження щодо того, яким може бути її тип повернення, щоб програма поводилася так, як очікується.

На щастя, main також може повертати Result<(), E>. Лістинг 9-12 містить код із Лістингу 9-10, але ми змінили тип повернення main на Result<(), Box<dyn Error>> і додали значення повернення Ok(()) у кінець. Тепер цей код скомпілюється.

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

Тип Box<dyn Error> — це об’єкт трейту, про який ми поговоримо в “Використання трейт-об’єктів для абстрагування над спільною поведінкою” у Розділі 18. Поки що ви можете читати Box<dyn Error> як “будь-який тип помилки”. Використання ? на значенні Result у функції main з типом помилки Box<dyn Error> дозволено, тому що це дає змогу будь-якому значенню Err бути поверненим достроково. Хоча тіло цієї функції main завжди повертатиме лише помилки типу std::io::Error, якщо вказати Box<dyn Error>, цей сигнатурний тип залишатиметься правильним навіть якщо до тіла main буде додано більше коду, який повертає інші помилки.

Коли функція main повертає Result<(), E>, виконуваний файл завершить роботу зі значенням 0, якщо main поверне Ok(()), і завершить роботу з ненульовим значенням, якщо main поверне значення Err. Виконувані файли, написані в C, повертають цілі числа під час завершення: програми, що завершуються успішно, повертають ціле число 0, а програми, що завершуються з помилкою, повертають деяке ціле число, відмінне від 0. Rust також повертає цілі числа з виконуваних файлів, щоб бути сумісним із цією конвенцією.

Функція main може повертати будь-які типи, які реалізують трейт std::process::Termination, що містить функцію report, яка повертає ExitCode. Зверніться до документації стандартної бібліотеки для отримання додаткової інформації про реалізацію трейту Termination для власних типів.

Тепер, коли ми обговорили деталі виклику panic! або повернення Result, давайте повернемося до теми того, як вирішити, що саме доречно використовувати в яких випадках.

panic! чи не panic!

До panic! чи не до panic!

Отже, як вирішити, коли слід викликати panic!, а коли слід повертати Result? Коли код панікує, відновитися немає жодного способу. Ви могли б викликати panic! для будь-якої ситуації з помилкою, незалежно від того, чи є можливий спосіб відновитися, але тоді ви ухвалюєте рішення, що ситуація є невідновлюваною, замість викликаючого коду. Коли ви вирішуєте повертати значення Result, ви даєте викликаючому коду варіанти. Викликаючий код міг би обрати спробу відновитися способом, який відповідає його ситуації, або міг би вирішити, що значення Err у цьому випадку є невідновлюваним, тож він може викликати panic! і перетворити вашу відновлювану помилку на невідновлювану. Отже, повернення Result — це гарний вибір за замовчуванням, коли ви визначаєте функцію, яка може зазнати невдачі.

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

Приклади, код прототипу та тести

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

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

Якщо виклик методу зазнає невдачі в тесті, ви хотіли б, щоб уся перевірка зазнала невдачі, навіть якщо цей метод не є функціональністю, яку тестують. Оскільки panic! — це спосіб позначити тест як невдалий, виклик unwrap або expect є саме тим, що має статися.

Коли ви маєте більше інформації, ніж компілятор

Також було б доречно викликати expect, коли у вас є якась інша логіка, що гарантує, що Result матиме значення Ok, але ця логіка не є чимось, що розуміє компілятор. У вас усе ще буде значення Result, з яким вам потрібно обійтися: будь-яка операція, яку ви викликаєте, усе ще загалом має можливість зазнати невдачі, навіть якщо у вашій конкретній ситуації це логічно неможливо. Якщо ви можете переконатися шляхом ручної перевірки коду, що у вас ніколи не буде варіанта Err, цілком прийнятно викликати expect і документувати причину, чому ви вважаєте, що у вас ніколи не буде варіанта Err, у тексті аргументу. Ось приклад:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

Ми створюємо екземпляр IpAddr шляхом розбору жорстко заданого рядка. Ми бачимо, що 127.0.0.1 — це дійсна IP-адреса, тож тут прийнятно використати expect. Однак наявність жорстко заданого, дійсного рядка не змінює тип повернення методу parse: ми все ще отримуємо значення Result, і компілятор усе ще змушуватиме нас обробляти Result, ніби варіант Err є можливим, тому що компілятор недостатньо розумний, щоб побачити, що цей рядок завжди є дійсною IP-адресою. Якби рядок IP-адреси надходив від користувача, а не був жорстко заданий у програмі і тому дійсно мав би можливість збою, ми б однозначно хотіли обробляти Result більш надійним способом. Згадування припущення, що ця IP-адреса є жорстко заданою, спонукатиме нас змінити expect на кращий код обробки помилок, якщо в майбутньому нам потрібно буде отримувати IP-адресу з іншого джерела.

Рекомендації щодо обробки помилок

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

• Поганий стан — це щось несподіване, на відміну від чогось, що, ймовірно, час від часу траплятиметься, як-от коли користувач вводить дані в неправильному форматі.
• Ваш код після цього моменту має покладатися на те, що не перебуває в цьому поганому стані, а не перевіряти наявність проблеми на кожному кроці.
• Немає хорошого способу закодувати цю інформацію в типах, які ви використовуєте. Ми розглянемо приклад того, що саме мається на увазі, у «Кодування станів і поведінки як типів» у Розділі 18.

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

Однак, коли збій є очікуваним, доречніше повертати Result, а не робити виклик panic!. Приклади включають аналізатор (parser), якому передають пошкоджені дані, або HTTP-запит, який повертає статус, що вказує на те, що ви досягли обмеження частоти. У цих випадках повернення Result вказує, що збій — це очікувана можливість, яку викликаючий код має вирішити, як обробити.

Коли ваш код виконує операцію, яка може наразити користувача на ризик, якщо її викликати з недійсними значеннями, ваш код повинен спочатку перевірити, що значення дійсні, і панікувати, якщо значення недійсні. Це переважно з міркувань безпеки: спроба виконати операцію над недійсними даними може відкрити ваш код для вразливостей. Це головна причина, чому стандартна бібліотека викличе panic!, якщо ви спробуєте доступ до пам’яті за межами обмежень: спроба отримати доступ до пам’яті, яка не належить поточній структурі даних, є поширеною проблемою безпеки. Функції часто мають контракти: їхня поведінка гарантується лише тоді, коли вхідні дані відповідають певним вимогам. Панікувати, коли контракт порушено, має сенс, тому що порушення контракту завжди вказує на помилку з боку викликача, і це не той тип помилки, який ви хочете, щоб викликаючий код мав явно обробляти. Насправді, немає розумного способу для викликаючого коду відновитися; викликаючі програмісти мають виправити код. Контракти для функції, особливо коли порушення спричинятиме паніку, слід пояснювати в документації API для цієї функції.

Однак наявність багатьох перевірок помилок у всіх ваших функціях була б багатослівною й дратівливою. На щастя, ви можете використовувати систему типів Rust (а отже, і перевірку типів, яку виконує компілятор), щоб виконати багато перевірок за вас. Якщо ваша функція має певний тип як параметр, ви можете продовжувати логіку вашого коду, знаючи, що компілятор уже переконався, що у вас є дійсне значення. Наприклад, якщо у вас є тип, а не Option, ваша програма очікує мати щось, а не нічого. Тоді вашому коду не потрібно обробляти два випадки для варіантів Some і None: у нього буде лише один випадок для напевно наявного значення. Код, який намагається передати нічого вашій функції, навіть не скомпілюється, тож вашій функції не потрібно перевіряти цей випадок під час виконання. Інший приклад — використання типу цілого числа без знака, наприклад u32, який гарантує, що параметр ніколи не буде від’ємним.

Створення власних типів для перевірки

Давайте розвинемо ідею використання системи типів Rust для забезпечення того, що ми маємо дійсне значення, на один крок далі й подивимося на створення власного типу для перевірки. Згадайте гру в вгадування з Розділі 2, у якій наш код просив користувача вгадати число від 1 до 100. Ми ніколи не перевіряли, чи була здогадка користувача в межах цих чисел, перед тим як порівнювати її з нашим таємним числом; ми лише перевіряли, що здогадка була додатною. У цьому випадку наслідки були не дуже серйозними: наш вивід «Занадто велике» або «Занадто мале» все одно був би правильним. Але було б корисним удосконаленням спрямовувати користувача до дійсних здогадок і мати різну поведінку, коли користувач вгадує число поза діапазоном, порівняно з тим, коли користувач вводить, наприклад, літери.

Один зі способів зробити це — розбирати здогадку як i32 замість лише u32, щоб дозволити потенційно від’ємні числа, а потім додати перевірку того, що число перебуває в діапазоні, ось так:

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

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

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

    loop {
        // --snip--

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

        let mut guess = String::new();

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

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

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

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

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

Однак це не ідеальне рішення: якби було абсолютно критично, щоб програма працювала лише зі значеннями від 1 до 100, і вона мала багато функцій із цією вимогою, наявність такої перевірки в кожній функції була б виснажливою (і могла б вплинути на продуктивність).

Замість цього ми можемо створити новий тип у спеціальному модулі й помістити перевірки у функцію для створення екземпляра типу, а не повторювати перевірки всюди. Таким чином, функціям безпечно використовувати новий тип у своїх сигнатурах і впевнено використовувати значення, які вони отримують. У Лістингу 9-13 показано один зі способів визначити тип Guess, який створюватиме екземпляр Guess лише якщо функція new отримує значення між 1 і 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Зверніть увагу, що цей код у src/guessing_game.rs залежить від додавання оголошення модуля mod guessing_game; у src/lib.rs, яке ми тут не показували. Усередині файла цього нового модуля ми визначаємо структуру з назвою Guess, яка має поле з назвою value, що містить i32. Тут буде зберігатися число.

Потім ми реалізуємо пов’язану функцію (associated function) з назвою new для Guess, яка створює екземпляри значень Guess. Функцію new визначено так, що вона має один параметр з назвою value типу i32 і повертає Guess. Код у тілі функції new перевіряє value, щоб переконатися, що воно між 1 і 100. Якщо value не проходить цю перевірку, ми робимо виклик panic!, який повідомить програміста, що пише викликаючий код, про помилку, яку йому потрібно виправити, тому що створення Guess зі значенням value поза цим діапазоном порушило б контракт, на який покладається Guess::new. Умови, за яких Guess::new може панікувати, слід обговорити в її публічній документації API; ми розглянемо домовленості щодо документації, які вказують на можливість panic! у документації API, яку ви створюєте, у Розділі 14. Якщо value проходить перевірку, ми створюємо новий Guess, у якого поле value встановлено в параметр value, і повертаємо Guess.

Далі ми реалізуємо метод з назвою value, який запозичує self, не має жодних інших параметрів і повертає i32. Такий метод іноді називають гетер (getter), тому що його мета — отримати деякі дані з його полів і повернути їх. Цей публічний метод необхідний, тому що поле value структури Guess є приватним. Важливо, щоб поле value було приватним, щоб код, який використовує структуру Guess, не міг встановлювати value безпосередньо: код поза модулем guessing_game повинен використовувати функцію Guess::new, щоб створити екземпляр Guess, тим самим гарантуючи, що немає способу для Guess мати value, яке не було перевірене умовами у функції Guess::new.

Функція, яка має параметр або повертає лише числа між 1 і 100, тоді могла б оголосити в своїй сигнатурі, що вона приймає або повертає Guess, а не i32, і не потребувала б жодних додаткових перевірок у своєму тілі.

Підсумок

Можливості обробки помилок Rust розроблено, щоб допомогти вам писати надійніший код. Макрос panic! сигналізує, що ваша програма перебуває в стані, з яким вона не може впоратися, і дає вам змогу наказати процесу стані, з яким вона не може впоратися, і дає вам змогу наказати процесу зупинитися замість спроби продовжувати з недійсними або неправильними значеннями. Лістинг 9-13 використовує систему типів Rust, щоб вказати, що операції можуть зазнати невдачі способом, від якого ваш код міг би відновитися. Ви можете використовувати Result, щоб повідомити коду, який викликає ваш код, що йому також потрібно обробляти можливий успіх або збій. Використання panic! і Result у відповідних ситуаціях зробить ваш код надійнішим перед неминучими проблемами.

Тепер, коли ви побачили корисні способи, якими стандартна бібліотека використовує узагальнені типи з переліченнями Option і Result, ми поговоримо про те, як працюють узагальнені (generic) типи і як ви можете використовувати їх у своєму коді.

Узагальнені типи, трейти та часи життя

Кожна мова програмування має інструменти для ефективної обробки дублювання понять. У Rust одним із таких інструментів є узагальнення (generics): абстрактні замінники для конкретних типів або інших властивостей. Ми можемо виразити поведінку узагальнень (generics) або те, як вони пов’язані з іншими узагальненнями (generics), не знаючи, що буде на їхньому місці під час компіляції та виконання коду.

Функції можуть приймати параметри деякого узагальненого типу, замість конкретного типу на кшталт i32 або String, так само як вони приймають параметри з невідомими значеннями, щоб запускати той самий код на кількох конкретних значеннях. Насправді ми вже використовували узагальнення (generics) у Розділі 6 з Option<T>, у Розділі 8 з Vec<T> і HashMap<K, V>, а також у Розділі 9 з Result<T, E>. У цьому розділі ви дізнаєтеся, як визначати власні типи, функції та методи з узагальненнями (generics)!

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

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

Нарешті, ми обговоримо часи життя: різновид узагальнень (generics), який надає компілятору інформацію про те, як посилання пов’язані одне з одним. Часи життя дозволяють нам дати компілятору достатньо інформації про запозичені значення, щоб він міг гарантувати, що посилання будуть дійсними в більшій кількості ситуацій, ніж це було б без нашої допомоги.

Усунення дублювання шляхом виділення функції

Узагальнення (generics) дозволяють нам замінювати конкретні типи заповнювачем, який представляє кілька типів, щоб усунути дублювання коду. Перш ніж занурюватися в синтаксис узагальнень (generics), спочатку подивімося, як усунути дублювання способом, що не передбачає узагальнені типи, шляхом виділення функції, яка замінює конкретні значення заповнювачем, що представляє кілька значень. Потім ми застосуємо ту саму техніку, щоб виділити узагальнену функцію! Розглядаючи, як розпізнати дубльований код, який можна виділити у функцію, ви почнете розпізнавати дубльований код, який може використовувати узагальнення (generics).

Ми почнемо з короткої програми в Лістингу 10-1, яка знаходить найбільше число в списку.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
    assert_eq!(*largest, 100);
}

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

Тепер перед нами поставлено завдання знайти найбільше число у двох різних списках чисел. Щоб зробити це, ми можемо вирішити дублювати код у Лістингу 10-1 і використовувати ту саму логіку у двох різних місцях програми, як показано в Лістингу 10-2.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
}

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

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

У Лістингу 10-3 ми виділяємо код, який знаходить найбільше число, у функцію з назвою largest. Потім ми викликаємо цю функцію, щоб знайти найбільше число у двох списках з Лістингу 10-2. Ми також могли б використати цю функцію для будь-якого іншого списку значень i32, який у нас може з’явитися в майбутньому.

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 6000);
}

Функція largest має параметр під назвою list, який представляє будь-який конкретний зріз (slice) значень i32, який ми можемо передати у функцію. У результаті, коли ми викликаємо функцію, код виконується на конкретних значеннях, які ми передаємо в неї.

Підсумовуючи, ось кроки, які ми виконали, щоб змінити код з Лістингу 10-2 на Лістинг 10-3:

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

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

Наприклад, припустімо, що в нас є дві функції: одна, яка знаходить найбільший елемент у зрізі значень i32, і одна, яка знаходить найбільший елемент у зрізі значень char. Як би ми усунули це дублювання? Давайте з’ясуємо!

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

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

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

У визначеннях функцій

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

Продовжуючи нашу функцію largest, у Лістингу 10-4 показано дві функції, які обидві знаходять найбільше значення в зрізі. Потім ми об’єднаємо їх в одну функцію, що використовує узагальнення (generics).

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
    assert_eq!(*result, 'y');
}

Функція largest_i32 — це та, яку ми виділили в Лістингу 10-3 і яка знаходить найбільший i32 у зрізі. Функція largest_char знаходить найбільший char в зрізі. Тіла функцій мають однаковий код, тож усуньмо дублювання, увівши узагальнений параметр типу в одну функцію.

Щоб параметризувати типи в новій одній функції, нам потрібно назвати параметр типу так само, як ми робимо для параметрів значень функції. Ви можете використовувати будь-який ідентифікатор як назву параметра типу. Але ми використаємо T, тому що за домовленістю назви параметрів типу в Rust короткі, часто лише одна літера, а конвенція найменування типів у Rust — UpperCamelCase. Скорочення від type, T — це типовий вибір більшості програмістів Rust.

Коли ми використовуємо параметр у тілі функції, ми маємо оголосити ім’я параметра в сигнатурі, щоб компілятор знав, що означає це ім’я. Так само, коли ми використовуємо ім’я параметра типу в сигнатурі функції, ми маємо оголосити ім’я параметра типу до того, як використаємо його. Щоб визначити узагальнену функцію largest, ми розміщуємо оголошення імен типів всередині кутових дужок, <>, між назвою функції та списком параметрів, ось так:

fn largest<T>(list: &[T]) -> &T {

Ми читаємо це визначення як «Функція largest є узагальненою за деяким типом T». Ця функція має один параметр на ім’я list, який є зрізом значень типу T. Функція largest повертатиме посилання на значення того самого типу T.

Лістинг 10-5 показує об’єднане визначення функції largest, що використовує узагальнений тип даних у своїй сигнатурі. У списку також показано, як можна викликати функцію зі зрізом значень i32 або значень char. Зверніть увагу, що цей код ще не скомпілюється.

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

Якщо ми скомпілюємо цей код просто зараз, отримаємо таку помилку:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T` with trait `PartialOrd`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

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

Текст підказки згадує std::cmp::PartialOrd, який є трейтом (trait), і ми поговоримо про трейти (traits) в наступному розділі. Поки що знайте, що ця помилка стверджує: тіло largest не працюватиме для всіх можливих типів, якими може бути T. Оскільки ми хочемо порівнювати значення типу T у тілі, ми можемо використовувати лише ті типи, значення яких можна впорядкувати. Щоб увімкнути порівняння, стандартна бібліотека має трейт std::cmp::PartialOrd, який ви можете реалізувати для типів (див. Додаток C для більшої інформації про цей трейт). Щоб виправити Лістинг 10-5, ми можемо скористатися пропозицією з тексту підказки та обмежити типи, допустимі для T, лише тими, що реалізують PartialOrd. Після цього список скомпілюється, тому що стандартна бібліотека реалізує PartialOrd і для i32, і для char.

У визначеннях структур

Ми також можемо визначати структури так, щоб вони використовували узагальнений параметр типу в одному або кількох полях, використовуючи синтаксис <>. Listing 10-6 визначає структуру Point<T>, щоб зберігати значення координат x і y будь-якого типу.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

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

Зверніть увагу: оскільки ми використали лише один узагальнений тип для визначення Point<T>, це визначення каже, що структура Point<T> є узагальненою за деяким типом T, а поля x і y є обидва саме цим самим типом, яким би цей тип не був. Якщо ми створимо екземпляр Point<T>, який має значення різних типів, як у Лістингу 10-7, наш код не скомпілюється.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

У цьому прикладі, коли ми присвоюємо цілочисельне значення 5 до x, ми даємо компілятору знати, що узагальнений тип T буде цілочисельним для цього екземпляра Point<T>. Потім, коли ми вказуємо 4.0 для y, яке ми визначили як таке, що має той самий тип, що й x, ми отримаємо помилку невідповідності типів, подібну до цієї:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

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

Щоб визначити структуру Point, де x і y обидва є generics, але можуть мати різні типи, ми можемо використовувати кілька узагальнених параметрів типу. Наприклад, у Лістингу 10-8 ми змінюємо визначення Point, щоб воно було узагальненим за типами T і U, де x має тип T, а y має тип U.

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

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

У визначеннях переліків

Як і у випадку зі структурами, ми можемо визначати переліки, щоб зберігати узагальнені типи даних у їхніх варіантах. Ще раз погляньмо на перелік Option<T>, який надає стандартна бібліотека і який ми використовували в Розділі 6:

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

Тепер це визначення має для вас більше сенсу. Як бачите, перелік Option<T> є узагальненим за типом T і має два варіанти: Some, який зберігає одне значення типу T, і варіант None, який не зберігає жодного значення. Використовуючи перелік Option<T>, ми можемо виразити абстрактне поняття необов’язкового значення, і оскільки Option<T> є узагальненим, ми можемо використовувати цю абстракцію незалежно від того, який тип має необов’язкове значення.

Переліки також можуть використовувати кілька узагальнених типів. Визначення переліку Result, яке ми використовували в Розділі 9, — один із прикладів:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Перелік Result є узагальненим за двома типами, T і E, і має два варіанти: Ok, який зберігає значення типу T, і Err, який зберігає значення типу E. Це визначення робить зручним використання переліку Result будь-де, де ми маємо операцію, що може або завершитися успіхом (повернути значення певного типу T), або завершитися помилкою (повернути помилку певного типу E). Власне, саме це ми використали, щоб відкрити файл у Лістингу 9-3, де T було підставлено типом std::fs::File, коли файл було відкрито успішно, а E було підставлено типом std::io::Error, коли виникали проблеми з відкриттям файлу.

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

У визначеннях методів

Ми можемо реалізовувати методи для структур і переліків (як ми робили в Розділі 5) і використовувати узагальнені типи в їхніх визначеннях також. Лістинг 10-9 показує структуру Point<T>, яку ми визначили в Лістингу 10-6, з методом на ім’я x, реалізованим для неї.

struct Point<T> {
    x: T,
    y: T,
}

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

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Тут ми визначили метод на ім’я x для Point<T>, який повертає посилання на дані в полі x.

Зверніть увагу, що ми маємо оголосити T одразу після impl, щоб ми могли використовувати T для вказівки, що ми реалізуємо методи для типу Point<T>. Оголошуючи T як узагальнений тип після impl, Rust може визначити, що тип у кутових дужках у Point є узагальненим типом, а не конкретним типом. Ми могли б вибрати іншу назву для цього узагальненого параметра, ніж та, що оголошена у визначенні структури, але використання тієї самої назви є загальноприйнятим. Якщо ви пишете метод усередині impl, який оголошує узагальнений тип, цей метод буде визначено для будь-якого екземпляра типу, незалежно від того, який конкретний тип зрештою підставляється замість узагальненого типу.

Ми також можемо вказувати обмеження для узагальнених типів під час визначення методів для типу. Наприклад, ми могли б реалізувати методи лише для екземплярів Point<f32>, а не для екземплярів Point<T> з будь-яким узагальненим типом. У Лістингу 10-10 ми використовуємо конкретний тип f32, тобто не оголошуємо жодних типів після impl.

struct Point<T> {
    x: T,
    y: T,
}

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

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Цей код означає, що тип Point<f32> матиме метод distance_from_origin; інші екземпляри Point<T>, де T не має типу f32, не матимуть визначеного цього методу. Метод вимірює, як далеко наша точка знаходиться від точки з координатами (0.0, 0.0), і використовує математичні операції, які доступні лише для типів із плаваючою комою.

Узагальнені параметри типу у визначенні структури не завжди збігаються з тими, які ви використовуєте в сигнатурах методів цієї самої структури. Лістинг 10-11 використовує узагальнені типи X1 і Y1 для структури Point та X2 і Y2 для сигнатури методу mixup, щоб зробити приклад зрозумілішим. Метод створює новий екземпляр Point зі значенням x з Point self (типу X1) та значенням y з переданого Point (типу Y2).

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

У main ми визначили Point, який має i32 для x (зі значенням 5) та f64 для y (зі значенням 10.4). Змінна p2 — це структура Point, яка має рядковий зріз для x (зі значенням "Hello") і char для y (зі значенням c). Виклик mixup для p1 з аргументом p2 дає нам p3, який матиме i32 для x, тому що x походив із p1. Змінна p3 матиме char для y, тому що y походив із p2. Виклик макросу println! надрукує p3.x = 5, p3.y = c.

Мета цього прикладу — продемонструвати ситуацію, у якій деякі узагальнені параметри оголошуються з impl, а деякі — з визначенням методу. Тут узагальнені параметри X1 і Y1 оголошені після impl, тому що вони належать до визначення структури. Узагальнені параметри X2 і Y2 оголошені після fn mixup, тому що вони стосуються лише методу.

Продуктивність коду, що використовує generics

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

Rust досягає цього, виконуючи мономорфізацію коду, що використовує узагальнення (generics), під час компіляції. Мономорфізація (monomorphization) — це процес перетворення узагальненого коду на специфічний код шляхом підставляння конкретних типів, які використовуються під час компіляції. У цьому процесі компілятор робить протилежне крокам, які ми використовували для створення узагальненої функції в Listing 10-5: компілятор дивиться на всі місця, де викликається узагальнений код, і генерує код для конкретних типів, з якими викликається узагальнений код.

Подивімося, як це працює, використовуючи узагальнений перелік стандартної бібліотеки Option<T>:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Коли Rust компілює цей код, він виконує мономорфізацію. Під час цього процесу компілятор читає значення, які було використано в екземплярах Option<T>, і визначає два види Option<T>: один — i32, а інший — f64. Таким чином, він розгортає узагальнене визначення Option<T> у два визначення, спеціалізовані для i32 і f64, замінюючи узагальнене визначення конкретними.

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

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

Узагальнений Option<T> замінюється конкретними визначеннями, створеними компілятором. Оскільки Rust компілює узагальнений код у код, що вказує тип у кожному екземплярі, ми не сплачуємо витрат під час виконання за використання узагальнень (generics). Коли код виконується, він працює так само, як працював би, якби ми вручну дублювали кожне визначення. Процес мономорфізації робить узагальнення (generics) у Rust надзвичайно ефективними під час виконання.

Визначення спільної поведінки за допомогою трейтів

Визначення спільної поведінки за допомогою трейтів

Трейт визначає функціональність, яку має певний тип і яку він може ділити з іншими типами. Ми можемо використовувати трейти для визначення спільної поведінки абстрактним способом. Ми можемо використовувати обмеження трейтів (trait bounds), щоб вказати, що узагальнений тип може бути будь-яким типом, який має певну поведінку.

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

Визначення трейту

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

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

Ми хочемо створити бібліотечний крейт для медіа-агрегатора під назвою aggregator, який може відображати короткі підсумки даних, що можуть бути збережені в екземплярі NewsArticle або SocialPost. Щоб зробити це, нам потрібен підсумок від кожного типу, і ми запитуватимемо цей підсумок, викликаючи метод summarize на екземплярі. У Лістингу 10-12 показано визначення публічного трейту Summary, який виражає цю поведінку.

pub trait Summary {
    fn summarize(&self) -> String;
}

Тут ми оголошуємо трейт, використовуючи ключове слово trait, а потім ім’я трейту, яке в цьому випадку є Summary. Ми також оголошуємо трейт як pub, щоб крейти, які залежать від цього крейту, теж могли використовувати цей трейт, як ми побачимо в кількох прикладах. Усередині фігурних дужок ми оголошуємо сигнатури методів, які описують поведінку типів, що реалізують цей трейт, і в цьому випадку це fn summarize(&self) -> String.

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

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

Реалізація трейту для типу

Тепер, коли ми визначили потрібні сигнатури методів трейту Summary, ми можемо реалізувати його для типів у нашому медіа-агрегаторі. У Лістингу 10-13 показано реалізацію трейту Summary для структури NewsArticle, яка використовує заголовок, автора та місце, щоб створити значення, що повертається summarize. Для структури SocialPost ми визначаємо summarize як ім’я користувача, за яким іде весь текст допису, припускаючи, що вміст допису вже обмежено 280 символами.

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Реалізація трейту для типу подібна до реалізації звичайних методів. Різниця полягає в тому, що після impl ми ставимо ім’я трейту, який хочемо реалізувати, потім використовуємо ключове слово for, а тоді вказуємо ім’я типу, для якого хочемо реалізувати трейт. Усередині блоку impl ми розміщуємо сигнатури методів, які визначені у трейті. Замість додавання крапки з комою після кожної сигнатури ми використовуємо фігурні дужки та заповнюємо тіло методу конкретною поведінкою, яку ми хочемо, щоб методи трейту мали для цього конкретного типу.

Тепер, коли бібліотека реалізувала трейт Summary для NewsArticle і SocialPost, користувачі крейту можуть викликати методи трейту на екземплярах NewsArticle і SocialPost так само, як ми викликаємо звичайні методи. Єдина різниця полягає в тому, що користувач має імпортувати трейт в область видимості так само, як і типи. Ось приклад того, як бінарний крейт може використовувати наш бібліотечний крейт aggregator:

use aggregator::{SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

Цей код виводить 1 new post: horse_ebooks: of course, as you probably already know, people.

Інші крейти, які залежать від крейту aggregator, також можуть імпортувати трейт Summary в область видимості, щоб реалізувати Summary для власних типів. Одне обмеження, на яке слід звернути увагу, полягає в тому, що ми можемо реалізувати трейт для типу лише тоді, коли або трейт, або тип, або обидва є локальними для нашого крейту. Наприклад, ми можемо реалізувати трейти стандартної бібліотеки, такі як Display, для власного типу на кшталт SocialPost як частину функціональності нашого крейту aggregator, тому що тип SocialPost є локальним для нашого крейту aggregator. Ми також можемо реалізувати Summary для Vec<T> у нашому крейті aggregator, тому що трейт Summary є локальним для нашого крейту aggregator.

Але ми не можемо реалізовувати зовнішні трейти для зовнішніх типів. Наприклад, ми не можемо реалізувати трейт Display для Vec<T> у нашому крейті aggregator, тому що і Display, і Vec<T> визначені в стандартній бібліотеці й не є локальними для нашого крейту aggregator. Це обмеження є частиною властивості, яка називається узгодженість (coherence), і точніше правила сироти (orphan rule), так названого тому, що батьківський тип відсутній. Це правило гарантує, що чужий код не може зламати ваш код і навпаки. Без цього правила два крейти могли б реалізувати той самий трейт для того самого типу, і Rust не знав би, яку реалізацію використовувати.

Використання реалізацій за замовчуванням

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

У Лістингу 10-14 ми вказуємо рядок за замовчуванням для методу summarize трейту Summary замість того, щоб лише визначати сигнатуру методу, як ми робили в Лістингу 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Щоб використати реалізацію за замовчуванням для підсумовування екземплярів NewsArticle, ми вказуємо порожній блок impl із impl Summary for NewsArticle {}.

Хоча ми більше не визначаємо метод summarize безпосередньо для NewsArticle, ми надали реалізацію за замовчуванням і вказали, що NewsArticle реалізує трейт Summary. У результаті ми все ще можемо викликати метод summarize на екземплярі NewsArticle, ось так:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

Цей код виводить New article available! (Read more...).

Створення реалізації за замовчуванням не вимагає від нас змінювати щось у реалізації Summary для SocialPost у Лістингу 10-13. Причина полягає в тому, що синтаксис для перевизначення реалізації за замовчуванням такий самий, як і синтаксис для реалізації методу трейту, який не має реалізації за замовчуванням.

Реалізації за замовчуванням можуть викликати інші методи в тому самому трейді, навіть якщо ті інші методи не мають реалізації за замовчуванням. Таким чином трейт може надавати багато корисної функціональності й вимагати від тих, хто реалізує його, вказати лише її невелику частину. Наприклад, ми могли б визначити трейт Summary так, щоб він мав метод summarize_author, реалізація якого є обов’язковою, а потім визначити метод summarize, який має реалізацію за замовчуванням, що викликає метод summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Щоб використовувати цю версію Summary, нам потрібно лише визначити summarize_author, коли ми реалізуємо трейт для типу:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Після того як ми визначимо summarize_author, ми можемо викликати summarize для екземплярів структури SocialPost, і реалізація summarize за замовчуванням викличе визначення summarize_author, яке ми надали. Оскільки ми реалізували summarize_author, трейт Summary надав нам поведінку методу summarize без необхідності писати ще якийсь код. Ось як це виглядає:

use aggregator::{self, SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

Цей код виводить 1 new post: (Read more from @horse_ebooks...).

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

Використання трейтів як параметрів

Тепер, коли ви знаєте, як визначати й реалізовувати трейти, ми можемо дослідити, як використовувати трейти для визначення функцій, які приймають багато різних типів. Ми використаємо трейт Summary, який ми реалізували для типів NewsArticle і SocialPost у Лістингу 10-13, щоб визначити функцію notify, яка викликає метод summarize для свого параметра item, який має певний тип, що реалізує трейт Summary. Щоб зробити це, ми використовуємо синтаксис impl Trait, ось так:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

Замість конкретного типу для параметра item ми вказуємо ключове слово impl і ім’я трейту. Цей параметр приймає будь-який тип, який реалізує вказаний трейт. У тілі notify ми можемо викликати будь-які методи на item, які походять із трейту Summary, наприклад summarize. Ми можемо викликати notify і передати будь-який екземпляр NewsArticle або SocialPost. Код, що викликає цю функцію з будь-яким іншим типом, таким як String або i32, не скомпілюється, тому що ці типи не реалізують Summary.

Синтаксис обмеження трейтів

Синтаксис impl Trait працює для простих випадків, але насправді це синтаксичний цукор (syntactic sugar) для довшої форми, відомої як обмеження трейту (trait bound); вона виглядає ось так:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

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

Синтаксис impl Trait зручний і робить код коротшим у простих випадках, тоді як повніший синтаксис обмеження трейту може виражати більшу складність в інших випадках. Наприклад, ми можемо мати два параметри, які реалізують Summary. Зробити це за допомогою синтаксису impl Trait виглядає так:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

Використання impl Trait є доречним, якщо ми хочемо, щоб ця функція дозволяла item1 і item2 мати різні типи (за умови, що обидва типи реалізують Summary). Однак якщо ми хочемо змусити обидва параметри мати той самий тип, ми маємо використовувати обмеження трейту, ось так:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

Узагальнений тип T, вказаний як тип параметрів item1 і item2, обмежує функцію так, що конкретний тип значення, переданого як аргумент для item1 і item2, має бути однаковим.

Кілька обмежень трейтів із синтаксисом +

Ми також можемо вказати більше ніж одне обмеження трейту. Припустімо, ми хочемо, щоб notify використовувала форматування для відображення, а також summarize для item: ми вказуємо у визначенні notify, що item має реалізовувати і Display, і Summary. Ми можемо зробити це, використовуючи синтаксис +:

pub fn notify(item: &(impl Summary + Display)) {

Синтаксис + також є чинним для обмежень трейтів у узагальнених типів:

pub fn notify<T: Summary + Display>(item: &T) {

Після вказання двох обмежень трейтів тіло notify може викликати summarize і використовувати {} для форматування item.

Чіткіші обмеження трейтів із реченням where

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

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

ми можемо використовувати фразу where, ось так:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

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

Повернення типів, які реалізують трейти

Ми також можемо використовувати синтаксис impl Trait у позиції повернення, щоб повернути значення деякого типу, який реалізує трейт, як показано тут:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    }
}

Використовуючи impl Summary для типу, що повертається, ми вказуємо, що функція returns_summarizable повертає деякий тип, який реалізує трейт Summary, не називаючи конкретний тип. У цьому випадку returns_summarizable повертає SocialPost, але код, що викликає цю функцію, не має потреби знати це.

Можливість вказати тип, що повертається, лише через трейт, який він реалізує, є особливо корисною в контексті замикань і ітераторів, які ми розглядаємо в Розділі 13. Замикання й ітератори створюють типи, які знає лише компілятор, або типи, які дуже довго вказувати. Синтаксис impl Trait дає змогу стисло вказати, що функція повертає деякий тип, який реалізує трейт Iterator, без потреби записувати дуже довгий тип.

Однак ви можете використовувати impl Trait лише якщо повертаєте один тип. Наприклад, цей код, який повертає або NewsArticle, або SocialPost із типом, що повертається, вказаним як impl Summary, не працюватиме:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        SocialPost {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            repost: false,
        }
    }
}

Повернення або NewsArticle, або SocialPost не дозволено через обмеження щодо того, як синтаксис impl Trait реалізовано в компіляторі. Ми розглянемо, як написати функцію з такою поведінкою в підрозділі “Використання об’єктів трейтів для абстрагування над спільною поведінкою” Розділу 18.

Використання обмежень трейтів для умовної реалізації методів

Використовуючи обмеження трейту з блоком impl, що використовує узагальнені параметри типу, ми можемо умовно реалізовувати методи для типів, які реалізують вказані трейти. Наприклад, тип Pair<T> у Лістингу 10-15 завжди реалізує функцію new, щоб повертати новий екземпляр Pair<T> (згадайте з Розділу “Синтаксис методів” Розділу 5, що Self — це псевдонім типу для типу блоку impl, яким у цьому випадку є Pair<T>). Але в наступному блоці impl Pair<T> реалізує метод cmp_display лише якщо його внутрішній тип T реалізує трейт PartialOrd, який дає змогу порівняння, і трейт Display, який дає змогу друкування.

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

Ми також можемо умовно реалізувати трейт для будь-якого типу, який реалізує інший трейт. Реалізації трейту для будь-якого типу, який задовольняє обмеження трейтів, називаються загальними реалізаціями (blanket implementations) і широко використовуються в стандартній бібліотеці Rust. Наприклад, стандартна бібліотека реалізує трейт ToString для будь-якого типу, який реалізує трейт Display. Блок impl у стандартній бібліотеці виглядає подібно до цього коду:

impl<T: Display> ToString for T {
    // --snip--
}

Оскільки стандартна бібліотека має цю загальну реалізацію, ми можемо викликати метод to_string, визначений трейтом ToString, для будь-якого типу, який реалізує трейт Display. Наприклад, ми можемо перетворити цілі числа на відповідні значення String ось так, тому що цілі числа реалізують Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Загальні реалізації з’являються в документації для трейту в розділі “Implementors”.

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

Перевірка посилань за допомогою часів життя

Перевірка посилань за допомогою часів життя (Lifetimes)

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

Одна деталь, яку ми не обговорювали в розділі “References and Borrowing” у Розділі 4, полягає в тому, що кожне посилання в Rust має час життя, який є областю видимості, у межах якої це посилання є дійсним. Найчастіше часи життя є неявними та виведеними, так само як більшу частину часу виводяться типи. Нам потрібно анотувати типи лише тоді, коли можливі кілька типів. Подібним чином, ми мусимо анотувати часи життя, коли часи життя посилань можуть бути пов’язані кількома різними способами. Rust вимагає, щоб ми анотували ці зв’язки за допомогою узагальнених параметрів часу життя, щоб гарантувати, що фактичні посилання, які використовуються під час виконання, будуть точно дійсними.

Анотування часів життя — це навіть не концепція, яка є в більшості інших мов програмування, тому це буде здаватися незвичним. Хоча в цьому розділі ми не розглядатимемо часи життя в повному обсязі, ми обговоримо поширені способи, у яких ви можете зустріти синтаксис часів життя, щоб ви могли звикнути до цієї концепції.

Висячі посилання

Головна мета часів життя — запобігати висячим посиланням, які, якби їм було дозволено існувати, спричиняли б посилання програми на дані, відмінні від тих даних, на які вона має посилатися. Розгляньте програму в Лістингу 10-16, яка має зовнішню область видимості та внутрішню область видимості.

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

Примітка: Приклади в Лістингах 10-16, 10-17 та 10-23 оголошують змінні без надання їм початкового значення, тому ім’я змінної існує в зовнішній області видимості. На перший погляд, це може здатися таким, що суперечить тому, що в Rust немає нульових значень (null). Однак, якщо ми спробуємо використати змінну до того, як надамо їй значення, ми отримаємо помилку компіляції, що показує, що Rust дійсно не дозволяє нульові значення.

Зовнішня область видимості оголошує змінну з ім’ям r без початкового значення, а внутрішня область видимості оголошує змінну з ім’ям x із початковим значенням 5. Усередині внутрішньої області видимості ми намагаємося встановити значення r як посилання на x. Потім внутрішня область видимості закінчується, і ми намагаємося надрукувати значення в r. Цей код не скомпілюється, тому що значення, на яке r посилається, вийшло з області видимості до того, як ми спробували його використати. Ось повідомлення про помилку:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
5 |         let x = 5;
  |             - binding `x` declared here
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {r}");
  |                   - borrow later used here

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

Повідомлення про помилку каже, що змінна x “does not live long enough.” Причина в тому, що x буде поза областю видимості, коли внутрішня область видимості закінчиться на рядку 7. Але r все ще є дійсним для зовнішньої області видимості; оскільки її область видимості більша, ми кажемо, що вона “lives longer.” Якби Rust дозволив цьому коду працювати, r посилався б на пам’ять, яка була деалокована, коли x вийшла з області видимості, і все, що ми намагалися б зробити з r, не працювало б правильно. Отже, як Rust визначає, що цей код є недійсним? Він використовує перевірник запозичень.

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

Компілятор Rust має borrow checker, який порівнює області видимості, щоб визначити, чи всі запозичення є дійсними. Лістинг 10-17 показує той самий код, що й Лістинг 10-16, але з анотаціями, які показують часи життя змінних.

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {r}");   //          |
}                         // ---------+

Тут ми анотували час життя r як 'a, а час життя x як 'b. Як ви бачите, внутрішній блок 'b є набагато меншим, ніж зовнішній блок часу життя 'a. Під час компіляції Rust порівнює розмір цих двох часів життя і бачить, що r має час життя 'a, але що він посилається на пам’ять із часом життя 'b. Програма відхиляється, тому що 'b коротший за 'a: об’єкт, на який вказує посилання, живе не так довго, як саме посилання.

Лістинг 10-18 виправляє код так, що він не має висячого посилання, і він компілюється без жодних помилок.

fn main() {
    let x = 5;            // ----------+-- 'b
                          //           |
    let r = &x;           // --+-- 'a  |
                          //   |       |
    println!("r: {r}");   //   |       |
                          // --+       |
}                         // ----------+

Тут x має час життя 'b, який у цьому випадку більший за 'a. Це означає, що r може посилатися на x, тому що Rust знає, що посилання в r завжди буде дійсним, поки x є дійсним.

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

Узагальнені часи життя у функціях

Ми напишемо функцію, яка повертає довше з двох рядкових зрізів. Ця функція прийматиме два рядкові зрізи й повертатиме один рядковий зріз. Після того як ми реалізуємо функцію longest, код у Лістингу 10-19 має надрукувати The longest string is abcd.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

Зверніть увагу, що ми хочемо, щоб функція приймала рядкові зрізи, які є посиланнями, а не рядки, тому що ми не хочемо, щоб функція longest отримувала власність над своїми параметрами. Зверніться до розділу “String Slices as Parameters” в Розділі 4 для детальнішого обговорення того, чому параметри, які ми використовуємо в Лістингу 10-19, є саме тими, які нам потрібні.

Якщо ми спробуємо реалізувати функцію longest, як показано в Лістингу 10-20, це не скомпілюється.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() { x } else { y }
}

Натомість ми отримаємо таку помилку, яка говорить про часи життя:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0106]: missing lifetime specifier
 --> src/main.rs:9:33
  |
9 | fn longest(x: &str, y: &str) -> &str {
  |               ----     ----     ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`
help: consider introducing a named lifetime parameter
  |
9 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
  |           ++++     ++          ++          ++

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

Допоміжний текст показує, що тип, що повертається, потребує на собі узагальненого параметра часу життя, тому що Rust не може сказати, чи посилання, що повертається, посилається на x, чи на y. Насправді, ми також цього не знаємо, тому що блок if у тілі цієї функції повертає посилання на x, а блок else повертає посилання на y!

Коли ми визначаємо цю функцію, ми не знаємо конкретних значень, які будуть передані в цю функцію, тому ми не знаємо, чи виконається випадок if, чи випадок else. Ми також не знаємо конкретних часів життя посилань, які будуть передані, тому ми не можемо подивитися на області видимості так, як це робили в Listings 10-17 і 10-18, щоб визначити, чи посилання, яке ми повертаємо, завжди буде дійсним. Перевірник запозичень теж не може це визначити, тому що він не знає, як часи життя x і y пов’язані з часом життя значення, що повертається. Щоб виправити цю помилку, ми додамо узагальнені параметри часу життя, які визначають зв’язок між посиланнями, щоб перевірник запозичень міг виконати свій аналіз.

Синтаксис анотацій часу життя

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

Анотації часу життя мають дещо незвичайний синтаксис: імена параметрів часу життя мають починатися з апострофа (') і зазвичай складаються з малих літер та є дуже короткими, як і узагальнені типи. Більшість людей використовують ім’я 'a для першої анотації часу життя. Ми розміщуємо анотації параметра часу життя після & посилання, використовуючи пробіл, щоб відокремити анотацію від типу посилання.

Ось кілька прикладів — посилання на i32 без параметра часу життя, посилання на i32, яке має параметр часу життя з ім’ям 'a, і змінне посилання на i32, яке також має час життя 'a:

&i32        // a reference
&'a i32     // a reference with an explicit lifetime
&'a mut i32 // a mutable reference with an explicit lifetime

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

У сигнатурах функцій

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

Ми хочемо, щоб сигнатура виражала таке обмеження: посилання, що повертається, буде дійсним, поки дійсні обидва параметри. Це і є зв’язок між часами життя параметрів і значенням, що повертається. Ми назвемо час життя 'a, а потім додамо його до кожного посилання, як показано в Лістингу 10-21.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

Цей код має скомпілюватися і дати результат, який ми хочемо, коли ми використаємо його з функцією main у Listing 10-19.

Тепер сигнатура функції каже Rust, що для деякого часу життя 'a функція приймає два параметри, обидва з яких є рядковими зрізами, що живуть щонайменше так довго, як час життя 'a. Сигнатура функції також каже Rust, що рядковий зріз, який повертається з функції, буде жити щонайменше так довго, як час життя 'a. На практиці це означає, що час життя посилання, яке повертається функцією longest, є таким самим, як менший із часів життя значень, на які посилаються аргументи функції. Саме такі зв’язки ми хочемо, щоб Rust використовував під час аналізу цього коду.

Пам’ятайте, коли ми вказуємо параметри часу життя в цій сигнатурі функції, ми не змінюємо час життя жодних переданих або повернених значень. Натомість ми вказуємо, що перевірник запозичень має відхиляти будь-які значення, які не дотримуються цих обмежень. Зверніть увагу, що функції longest не потрібно точно знати, як довго житимуть x і y, лише те, що для 'a може бути підставлена деяка область видимості, яка задовольнить цю сигнатуру.

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

Коли ми передаємо конкретні посилання до longest, конкретний час життя, який підставляється замість 'a, є частиною області видимості x, що перетинається з областю видимості y. Іншими словами, узагальнений час життя 'a отримає конкретний час життя, який дорівнює меншому з часів життя x і y. Оскільки ми анотували посилання, що повертається, тим самим параметром часу життя 'a, посилання, що повертається, також буде дійсним протягом меншого з часів життя x і y.

Давайте подивимося, як анотації часу життя обмежують функцію longest, коли ми передаємо посилання з різними конкретними часами життя. Лістинг 10-22 — це простий приклад.

fn main() {
    let string1 = String::from("long string is long");

    {
        let string2 = String::from("xyz");
        let result = longest(string1.as_str(), string2.as_str());
        println!("The longest string is {result}");
    }
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

У цьому прикладі string1 є дійсним до кінця зовнішньої області видимості, string2 є дійсним до кінця внутрішньої області видимості, а result посилається на щось, що є дійсним до кінця внутрішньої області видимості. Запустіть цей код, і ви побачите, що перевірник запозичень схвалює його; він скомпілюється і надрукує The longest string is long string is long.

Далі давайте спробуємо приклад, який показує, що час життя посилання в result має бути меншим часом життя з двох аргументів. Ми перемістимо оголошення змінної result за межі внутрішньої області видимості, але залишимо присвоєння значення змінній result у межах області з string2. Потім ми перенесемо println!, який використовує result, за межі внутрішньої області видимості, після того як внутрішня область видимості закінчиться. Код у Лістингу 10-23 не скомпілюється.