Język programowania Rust

autorzy: Steve Klabnik, Carol Nichols i Chris Krycho, Maciej Ostrowski (przekład pl gemini-2.5-pro sty 26 r.), przy kontrybucjach Społeczności Rusta

Ta wersja tekstu zakłada, że używasz Rusta w wersji 1.90.0 (wydanie 2025-09-18) lub nowszej z edition = "2024" w pliku Cargo.toml wszystkich projektów, aby skonfigurować je do używania idiomów wydania Rust 2024. Zobacz sekcję „Instalacja” w Rozdziale 1, aby uzyskać instrukcje dotyczące instalacji lub aktualizacji Rusta, oraz Dodatek E, aby uzyskać informacje o wydaniach.

Format HTML jest dostępny online pod adresem https://doc.rust-lang.org/stable/book/ oraz offline z instalacjami Rusta wykonanymi za pomocą rustup; uruchom rustup doc --book, aby otworzyć.

Dostępne są również liczne [tłumaczenia] społeczności.

Ten tekst jest dostępny w formacie papierowym i ebooku od No Starch Press.

🚨 Chcesz bardziej interaktywnego doświadczenia edukacyjnego? Wypróbuj inną wersję Książki o Ruście, zawierającą: quizy, wyróżnienia, wizualizacje i wiele więcej: https://rust-book.cs.brown.edu

Przedmowa

Język programowania Rust przeszedł długą drogę w ciągu kilku krótkich lat, od jego stworzenia i inkubacji przez małą i rodzącą się społeczność entuzjastów, aż po stanie się jednym z najbardziej lubianych i poszukiwanych języków programowania na świecie. Z perspektywy czasu było nieuniknione, że moc i obietnica Rusta przyciągną uwagę i zakorzenią się w programowaniu systemowym. To, co nie było nieuniknione, to globalny wzrost zainteresowania i innowacji, który przeniknął przez społeczności open source i katalizował szeroko zakrojoną adopcję w różnych branżach.

W tym momencie łatwo jest wskazać wspaniałe cechy, które Rust ma do zaoferowania, aby wyjaśnić ten wybuch zainteresowania i adopcji. Kto nie chce bezpieczeństwa pamięci i szybkiej wydajności, i przyjaznego kompilatora, i wspaniałych narzędzi, pośród wielu innych wspaniałych funkcji? Język Rust, który widzisz dzisiaj, łączy lata badań w programowaniu systemowym z praktyczną mądrością tętniącej życiem i pełnej pasji społeczności. Ten język został zaprojektowany z myślą o celu i starannie wykonany, oferując deweloperom narzędzie, które ułatwia pisanie bezpiecznego, szybkiego i niezawodnego kodu.

Ale to, co czyni Rusta naprawdę wyjątkowym, to jego korzenie w umożliwianiu tobie, użytkownikowi, osiągania twoich celów. Jest to język, który chce, abyś odniósł sukces, a zasada wzmacniania pozycji przeplata się przez rdzeń społeczności, która buduje, utrzymuje i promuje ten język. Od poprzedniego wydania tego definitywnego tekstu, Rust rozwinął się w prawdziwie globalny i zaufany język. Projekt Rust jest teraz solidnie wspierany przez Fundację Rust, która również inwestuje w kluczowe inicjatywy, aby zapewnić, że Rust jest bezpieczny, stabilny i zrównoważony.

Niniejsze wydanie książki Język programowania Rust jest kompleksową aktualizacją, odzwierciedlającą ewolucję języka na przestrzeni lat i dostarczającą cennych nowych informacji. Ale to nie tylko przewodnik po składni i bibliotekach — to zaproszenie do przyłączenia się do społeczności, która ceni jakość, wydajność i przemyślany projekt. Niezależnie od tego, czy jesteś doświadczonym deweloperem, który po raz pierwszy chce poznać Rusta, czy doświadczonym Rustaceanem, który chce udoskonalić swoje umiejętności, to wydanie oferuje coś dla każdego.

Podróż z Rustem to podróż współpracy, nauki i iteracji. Rozwój języka i jego ekosystemu jest bezpośrednim odzwierciedleniem tętniącej życiem, różnorodnej społeczności, która za nim stoi. Kontrybucje tysięcy deweloperów, od projektantów podstawowych języków po okazjonalnych kontrybutorów, sprawiają, że Rust jest tak wyjątkowym i potężnym narzędziem. Biorąc tę książkę do ręki, nie tylko uczysz się nowego języka programowania — dołączasz do ruchu, który ma na celu ulepszanie oprogramowania, czynienie go bezpieczniejszym i przyjemniejszym w obsłudze.

Witaj w społeczności Rusta!

• Bec Rumbul, dyrektor wykonawcza Fundacji Rust

Wprowadzenie

Uwaga: To wydanie książki jest takie samo jak Język programowania Rust dostępny w formie drukowanej i ebooka od No Starch Press.

Witaj w Języku programowania Rust, książce wprowadzającej do Rusta. Język programowania Rust pomaga pisać szybsze, bardziej niezawodne oprogramowanie. Wysoka ergonomia i niska kontrola są często sprzeczne w projektowaniu języków programowania; Rust kwestionuje ten konflikt. Poprzez równoważenie potężnych możliwości technicznych i wspaniałego doświadczenia deweloperskiego, Rust daje możliwość kontrolowania niskopoziomowych szczegółów (takich jak użycie pamięci) bez wszystkich kłopotów tradycyjnie związanych z taką kontrolą.

Dla kogo jest Rust

Rust jest idealny dla wielu osób z różnych powodów. Przyjrzyjmy się kilku najważniejszym grupom.

Zespoły deweloperskie

Rust okazuje się być produktywnym narzędziem do współpracy między dużymi zespołami deweloperów o różnym poziomie znajomości programowania systemowego. Niskopoziomowy kod jest podatny na różne subtelne błędy, które w większości innych języków można wykryć jedynie poprzez obszerne testy i staranną weryfikację kodu przez doświadczonych deweloperów. W Ruście kompilator pełni rolę strażnika, odmawiając kompilacji kodu z tymi nieuchwytnymi błędami, w tym błędami współbieżności. Pracując obok kompilatora, zespół może poświęcić swój czas na skupienie się na logice programu, zamiast ścigać błędy.

Rust wprowadza również nowoczesne narzędzia dla deweloperów do świata programowania systemowego:

• Cargo, dołączony menedżer zależności i narzędzie do budowania, sprawia, że dodawanie, kompilowanie i zarządzanie zależnościami jest bezbolesne i spójne w całym ekosystemie Rusta.
• Narzędzie formatujące rustfmt zapewnia spójny styl kodowania wśród deweloperów.
• Rust Language Server zasila integrację ze zintegrowanymi środowiskami deweloperskimi (IDE) dla uzupełniania kodu i wbudowanych komunikatów o błędach.

Dzięki tym i innym narzędziom w ekosystemie Rusta, deweloperzy mogą być produktywni podczas pisania kodu na poziomie systemowym.

Studenci

Rust jest dla studentów i tych, którzy są zainteresowani nauką koncepcji systemowych. Używając Rusta, wiele osób uczyło się tematów takich jak rozwój systemów operacyjnych. Społeczność jest bardzo otwarta i chętnie odpowiada na pytania studentów. Poprzez wysiłki takie jak ta książka, zespoły Rusta chcą uczynić koncepcje systemowe bardziej dostępnymi dla większej liczby osób, szczególnie dla tych, którzy dopiero zaczynają programować.

Firmy

Setki firm, dużych i małych, używają Rusta w produkcji do różnych zadań, w tym narzędzi wiersza poleceń, usług sieciowych, narzędzi DevOps, urządzeń wbudowanych, analizy i transkodowania audio i wideo, kryptowalut, bioinformatyki, wyszukiwarek, aplikacji Internetu Rzeczy, uczenia maszynowego, a nawet głównych części przeglądarki internetowej Firefox.

Deweloperzy open source

Rust jest dla ludzi, którzy chcą budować język programowania Rust, społeczność, narzędzia deweloperskie i biblioteki. Chcielibyśmy, abyś wniósł swój wkład w rozwój języka Rust.

Ludzie ceniący szybkość i stabilność

Rust jest dla ludzi, którzy pragną szybkości i stabilności w języku. Przez szybkość rozumiemy zarówno to, jak szybko może działać kod Rusta, jak i szybkość, z jaką Rust pozwala pisać programy. Kontrole kompilatora Rusta zapewniają stabilność poprzez dodawanie funkcji i refaktoryzację. Jest to przeciwieństwo kruchego starego kodu w językach bez tych kontroli, którego deweloperzy często obawiają się modyfikować. Dążąc do abstrakcji zerokosztowych — funkcji wyższego poziomu, które kompilują się do kodu niższego poziomu tak szybko, jak kod napisany ręcznie — Rust stara się, aby bezpieczny kod był również szybkim kodem.

Język Rust ma nadzieję wspierać również wielu innych użytkowników; ci wspomniani tutaj to tylko niektórzy z największych interesariuszy. Ogólnie rzecz biorąc, największą ambicją Rusta jest wyeliminowanie kompromisów, które programiści akceptowali przez dziesięciolecia, zapewniając bezpieczeństwo i produktywność, szybkość i ergonomię. Spróbuj Rusta i zobacz, czy jego wybory sprawdzą się dla Ciebie.

Dla kogo jest ta książka

Ta książka zakłada, że pisałeś już kod w innym języku programowania, ale nie czyni żadnych założeń co do tego, w jakim. Staraliśmy się, aby materiał był szeroko dostępny dla osób z różnych środowisk programistycznych. Nie spędzamy wielu czasu na mówieniu o tym, czym jest programowanie ani jak o nim myśleć. Jeśli jesteś zupełnie początkujący w programowaniu, lepiej będzie, jeśli przeczytasz książkę, która specjalnie wprowadza w programowanie.

Jak korzystać z tej książki

Ogólnie rzecz biorąc, ta książka zakłada, że czytasz ją sekwencyjnie od początku do końca. Późniejsze rozdziały bazują na koncepcjach z wcześniejszych rozdziałów, a wcześniejsze rozdziały mogą nie zagłębiać się w szczegóły konkretnego tematu, ale powrócą do niego w późniejszym rozdziale.

W tej książce znajdziesz dwa rodzaje rozdziałów: rozdziały koncepcyjne i rozdziały projektowe. W rozdziałach koncepcyjnych dowiesz się o pewnym aspekcie Rusta. W rozdziałach projektowych będziemy wspólnie budować małe programy, stosując to, czego nauczyłeś się do tej pory. Rozdział 2, Rozdział 12 i Rozdział 21 to rozdziały projektowe; pozostałe to rozdziały koncepcyjne.

Rozdział 1 wyjaśnia, jak zainstalować Rusta, jak napisać program „Witaj, świecie!” i jak używać Cargo, menedżera pakietów i narzędzia do budowania Rusta. Rozdział 2 to praktyczne wprowadzenie do pisania programu w Ruście, polegające na budowaniu gry w zgadywanie liczb. Tutaj omawiamy koncepcje na wysokim poziomie, a późniejsze rozdziały dostarczą dodatkowych szczegółów. Jeśli chcesz od razu zabrać się do pracy, Rozdział 2 jest do tego idealnym miejscem. Jeśli jesteś szczególnie skrupulatnym uczniem, który woli poznać każdy szczegół przed przejściem do następnego, możesz pominąć Rozdział 2 i przejść bezpośrednio do Rozdziału 3, który obejmuje funkcje Rusta podobne do tych z innych języków programowania; następnie możesz wrócić do Rozdziału 2, kiedy będziesz chciał popracować nad projektem, stosując poznane szczegóły.

W Rozdziale 4 dowiesz się o systemie własności Rusta. Rozdział 5 omawia struktury i metody. Rozdział 6 obejmuje typy wyliczeniowe, wyrażenia match oraz konstrukcje przepływu sterowania if let i let...else. Użyjesz struktur i typów wyliczeniowych do tworzenia własnych typów.

W Rozdziale 7 dowiesz się o systemie modułów Rusta i zasadach prywatności dotyczących organizacji kodu i jego publicznego interfejsu programistycznego (API). Rozdział 8 omawia niektóre popularne struktury danych kolekcji dostępne w standardowej bibliotece: wektory, ciągi znaków i mapy haszujące. Rozdział 9 bada filozofię i techniki obsługi błędów Rusta.

Rozdział 10 zagłębia się w generyki, cechy i czasy życia, które dają ci możliwość definiowania kodu, który stosuje się do wielu typów. Rozdział 11 polega na testowaniu, które nawet przy gwarancjach bezpieczeństwa Rusta jest konieczne, aby upewnić się, że logika programu jest poprawna. W Rozdziale 12 zbudujemy naszą własną implementację podzbioru funkcjonalności narzędzia wiersza poleceń grep, które wyszukuje tekst w plikach. W tym celu użyjemy wielu koncepcji, które omówiliśmy w poprzednich rozdziałach.

Rozdział 13 bada domknięcia i iteratory: cechy Rusta pochodzące z funkcyjnych języków programowania. W Rozdziale 14 dokładniej zbadamy Cargo i porozmawiamy o najlepszych praktykach udostępniania bibliotek innym. Rozdział 15 omawia inteligentne wskaźniki dostępne w standardowej bibliotece oraz cechy, które umożliwiają ich funkcjonalność.

W Rozdziale 16 omówimy różne modele programowania współbieżnego i porozmawiamy o tym, jak Rust pomaga programować w wielu wątkach bez obaw. W Rozdziale 17 rozbudujemy to, badając składnię async i await Rusta, wraz z zadaniami, futures i streams, oraz lekki model współbieżności, który umożliwiają.

Rozdział 18 przygląda się, jak idiomy Rusta porównują się z zasadami programowania obiektowego, które możesz znać. Rozdział 19 to odniesienie do wzorców i dopasowywania wzorców, które są potężnymi sposobami wyrażania idei w programach Rusta. Rozdział 20 zawiera zbiór zaawansowanych tematów interesujących, w tym niebezpieczny Rust, makra i więcej o czasach życia, cechach, typach, funkcjach i domknięciach.

W Rozdziale 21 ukończymy projekt, w którym zaimplementujemy niskopoziomowy, wielowątkowy serwer WWW!

Na koniec, kilka dodatków zawiera użyteczne informacje o języku w formacie bardziej przypominającym referencje. Dodatek A obejmuje słowa kluczowe Rusta, Dodatek B obejmuje operatory i symbole Rusta, Dodatek C obejmuje cechy możliwe do wyprowadzenia dostarczane przez standardową bibliotekę, Dodatek D obejmuje niektóre użyteczne narzędzia programistyczne, a Dodatek E wyjaśnia wydania Rusta. W Dodatku F znajdziesz tłumaczenia książki, a w Dodatku G omówimy, jak powstaje Rust i czym jest Nightly Rust.

Nie ma złego sposobu na czytanie tej książki: Jeśli chcesz przeskoczyć do przodu, zrób to! Może będziesz musiał wrócić do wcześniejszych rozdziałów, jeśli spotkasz się z jakimkolwiek zamieszaniem. Ale rób to, co działa dla ciebie.

Ważną częścią procesu nauki Rusta jest nauka czytania komunikatów o błędach wyświetlanych przez kompilator: Będą one prowadzić Cię do działającego kodu. W związku z tym, przedstawimy wiele przykładów, które się nie kompilują, wraz z komunikatem o błędzie, który kompilator wyświetli w każdej sytuacji. Pamiętaj, że jeśli wpiszesz i uruchomisz przypadkowy przykład, może się on nie skompilować! Upewnij się, że przeczytałeś otaczający tekst, aby sprawdzić, czy przykład, który próbujesz uruchomić, ma celowo wyświetlić błąd. W większości sytuacji poprowadzimy Cię do poprawnej wersji kodu, który się nie kompiluje. Ferris również pomoże Ci rozróżnić kod, który nie ma działać:

Ferris	Znaczenie
	Ten kod się nie kompiluje!
	Ten kod panikuje!
	Ten kod nie daje pożądanego zachowania.

W większości sytuacji poprowadzimy Cię do poprawnej wersji kodu, który się nie kompiluje.

Kod źródłowy

Pliki źródłowe, z których generowana jest ta książka, można znaleźć na GitHubie.

Pierwsze kroki

Rozpocznij swoją podróż z Rustem! Wiele jest do nauczenia, ale każda podróż zaczyna się gdzieś. W tym rozdziale omówimy:

• Instalację Rusta na Linuksie, macOS i Windows
• Pisanie programu, który wypisuje Witaj, świecie!
• Używanie cargo, menedżera pakietów i systemu budowania Rusta

Instalacja

Instalacja

Pierwszym krokiem jest zainstalowanie Rusta. Pobierzemy Rusta za pośrednictwem rustup, narzędzia wiersza poleceń do zarządzania wersjami Rusta i powiązanymi narzędziami. Do pobrania będziesz potrzebować połączenia z internetem.

Uwaga: Jeśli z jakiegoś powodu wolisz nie używać rustup, zapoznaj się z stroną Inne metody instalacji Rusta w celu uzyskania dodatkowych opcji.

Poniższe kroki instalują najnowszą stabilną wersję kompilatora Rusta. Gwarancje stabilności Rusta zapewniają, że wszystkie przykłady w książce, które się kompilują, będą nadal kompilować się z nowszymi wersjami Rusta. Wynik może nieznacznie różnić się między wersjami, ponieważ Rust często poprawia komunikaty o błędach i ostrzeżenia. Innymi słowy, każda nowsza, stabilna wersja Rusta zainstalowana za pomocą tych kroków powinna działać zgodnie z oczekiwaniami z treścią tej książki.

Notacja wiersza poleceń

W tym rozdziale i w całej książce będziemy pokazywać niektóre polecenia używane w terminalu. Wiersze, które powinieneś wpisać w terminalu, zaczynają się od $. Nie musisz wpisywać znaku $; jest to znak zachęty wiersza poleceń, który wskazuje początek każdego polecenia. Wiersze, które nie zaczynają się od $, zazwyczaj pokazują wynik poprzedniego polecenia. Dodatkowo, przykłady specyficzne dla PowerShell będą używać > zamiast $.

Instalacja rustup na Linuksie lub macOS

Jeśli używasz Linuksa lub macOS, otwórz terminal i wprowadź następujące polecenie:

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

Polecenie pobiera skrypt i rozpoczyna instalację narzędzia rustup, które instaluje najnowszą stabilną wersję Rusta. Może zostać wyświetlony monit o hasło. Jeśli instalacja zakończy się pomyślnie, pojawi się następujący wiersz:

Rust jest już zainstalowany. Świetnie!

Będziesz także potrzebował linkera, czyli programu, którego Rust używa do łączenia skompilowanych wyników w jeden plik. Prawdopodobnie już go masz. Jeśli otrzymasz błędy linkera, powinieneś zainstalować kompilator C, który zazwyczaj zawiera linker. Kompilator C jest również przydatny, ponieważ niektóre popularne pakiety Rusta zależą od kodu C i będą wymagały kompilatora C.

Na macOS możesz uzyskać kompilator C, uruchamiając:

$ xcode-select --install

Użytkownicy Linuksa powinni zazwyczaj instalować GCC lub Clang, zgodnie z dokumentacją swojej dystrybucji. Na przykład, jeśli używasz Ubuntu, możesz zainstalować pakiet build-essential.

Instalacja rustup na Windows

Na Windows, przejdź na https://www.rust-lang.org/tools/install i postępuj zgodnie z instrukcjami instalacji Rusta. W pewnym momencie instalacji zostaniesz poproszony o zainstalowanie Visual Studio. Zapewnia to linker i natywne biblioteki potrzebne do kompilowania programów. Jeśli potrzebujesz więcej pomocy w tym kroku, zobacz https://rust-lang.github.io/rustup/installation/windows-msvc.html.

Reszta tej książki używa poleceń, które działają zarówno w cmd.exe, jak i PowerShell. Jeśli wystąpią specyficzne różnice, wyjaśnimy, którego użyć.

Rozwiązywanie problemów

Aby sprawdzić, czy Rust jest poprawnie zainstalowany, otwórz powłokę i wrowadź ten wiersz:

$ rustc --version

Ppowinien pojawić się numer wersji, skrót commita i data commita dla najnowszej stabilnej wersji, która została wydana, w następującym formacie:

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

Jeśli widzisz te informacje, pomyślnie zainstalowałeś Rusta! Jeśli ich nie widzisz, sprawdź, czy Rust znajduje się w zmiennej systemowej %PATH% w następujący sposób.

W systemie Windows CMD użyj:

> echo %PATH%

W PowerShellu użyj:

> echo $env:Path

Na Linuksie i macOS użyj:

$ echo $PATH

Jeśli wszystko jest w porządku, a Rust nadal nie działa, istnieje wiele miejsc, w których możesz uzyskać pomoc. Dowiedz się, jak skontaktować się z innymi Rustaceanami (tak się nazywamy) na stronie społeczności.

Aktualizacja i deinstalacja

Po zainstalowaniu Rusta za pomocą rustup, aktualizacja do nowo wydanej wersji jest łatwa. Z poziomu powłoki uruchom następujący skrypt aktualizacji:

$ rustup update

Aby odinstalować Rusta i rustup, uruchom następujący skrypt odinstalowujący z poziomu powłoki:

$ rustup self uninstall

Czytanie lokalnej dokumentacji

Instalacja Rusta zawiera również lokalną kopię dokumentacji, dzięki czemu możesz czytać ją offline. Uruchom rustup doc, aby otworzyć lokalną dokumentację w przeglądarce.

Zawsze, gdy typ lub funkcja jest dostarczana przez bibliotekę standardową, a nie masz pewności, co robi lub jak jej używać, skorzystaj z dokumentacji interfejsu programowania aplikacji (API), aby się dowiedzieć!

Używanie edytorów tekstu i środowisk IDE

Ta książka nie czyni żadnych założeń co do narzędzi, których używasz do pisania kodu Rusta. Niemal każdy edytor tekstu spełni swoje zadanie! Jednakże wiele edytorów tekstu i zintegrowanych środowisk programistycznych (IDE) posiada wbudowane wsparcie dla Rusta. Zawsze możesz znaleźć dość aktualną listę wielu edytorów i środowisk IDE na stronie z narzędziami na stronie internetowej Rusta.

Praca offline z tą książką

W kilku przykładach będziemy używać pakietów Rusta poza biblioteką standardową. Aby przećwiczyć te przykłady, będziesz potrzebować połączenia z internetem lub wcześniejszego pobrania tych zależności. Aby pobrać zależności wcześniej, możesz uruchomić następujące polecenia. (Wyjaśnimy, czym jest cargo i co robi każde z tych poleceń szczegółowo później.)

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

Spowoduje to buforowanie pobrań tych pakietów, dzięki czemu nie będziesz musiał ich później pobierać. Po uruchomieniu tego polecenia nie musisz zatrzymywać folderu get-dependencies. Jeśli uruchomiłeś to polecenie, możesz użyć flagi --offline ze wszystkimi poleceniami cargo w pozostałej części książki, aby użyć tych buforowanych wersji zamiast próbować używać sieci.

Witaj, świecie!

Witaj, świecie!

Skoro zainstalowałeś Rusta, czas napisać swój pierwszy program w tym języku. Tradycyjnie, ucząc się nowego języka, pisze się mały program, który wyświetla tekst Witaj, świecie! na ekranie, więc zrobimy to samo i tutaj!

Uwaga: Ta książka zakłada podstawową znajomość wiersza poleceń. Rust nie stawia żadnych specyficznych wymagań dotyczących edycji, narzędzi ani miejsca przechowywania kodu, więc jeśli wolisz używać IDE zamiast wiersza poleceń, śmiało korzystaj ze swojego ulubionego IDE. Wiele środowisk IDE ma obecnie pewne wsparcie dla Rusta; sprawdź dokumentację IDE, aby uzyskać szczegółowe informacje. Zespół Rusta skupia się na zapewnieniu doskonałego wsparcia IDE za pośrednictwem rust-analyzer. Więcej szczegółów znajdziesz w Dodatku D.

Konfiguracja katalogu projektu

Zaczniesz od utworzenia katalogu do przechowywania kodu Rusta. Dla Rusta nie ma znaczenia, gdzie znajduje się Twój kod, ale dla ćwiczeń i projektów w tej książce sugerujemy utworzenie katalogu projects w katalogu domowym i przechowywanie tam wszystkich swoich projektów.

Otwórz terminal i wprowadź następujące polecenia, aby utworzyć katalog projects i katalog dla projektu „Witaj, świecie!” w katalogu projects.

Na Linuksie, macOS i w PowerShell na Windows, wprowadź:

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

W systemie Windows CMD wprowadź:

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

Podstawy programu w Ruście

Następnie utwórz nowy plik źródłowy i nazwij go main.rs. Pliki Rusta zawsze kończą się rozszerzeniem .rs. Jeśli używasz więcej niż jednego słowa w nazwie pliku, konwencją jest używanie podkreślenia do ich rozdzielania. Na przykład użyj hello_world.rs zamiast helloworld.rs.

Teraz otwórz nowo utworzony plik main.rs i wprowadź kod z Listingu 1-1.

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

Zapisz plik i wróć do okna terminala w katalogu ~/projects/hello_world. Na Linuksie lub macOS wprowadź następujące polecenia, aby skompilować i uruchomić plik:

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

Na Windows wprowadź polecenie .\main zamiast ./main:

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

Niezależnie od systemu operacyjnego, w terminalu powinno pojawić się Witaj, świecie!. Jeśli nie widzisz tego wyjścia, wróć do części „Rozwiązywanie problemów” w sekcji Instalacja, aby uzyskać pomoc.

Jeśli Witaj, świecie! zostało wypisane, gratulacje! Oficjalnie napisałeś program w Ruście. To czyni Cię programistą Rusta – witaj!

Anatomia programu w Ruście

Przejrzyjmy szczegółowo ten program „Witaj, świecie!”. Oto pierwszy element układanki:

fn main() {

}

Te wiersze definiują funkcję o nazwie main. Funkcja main jest specjalna: Zawsze jest pierwszym kodem, który jest uruchamiany w każdym wykonywalnym programie w Ruście. Tutaj pierwszy wiersz deklaruje funkcję o nazwie main, która nie ma parametrów i nic nie zwraca. Gdyby były parametry, znalazłyby się w nawiasach ().

Ciało funkcji jest ujęte w {}. Rust wymaga nawiasów klamrowych wokół wszystkich ciał funkcji. Dobrym stylem jest umieszczanie otwierającego nawiasu klamrowego w tym samym wierszu co deklaracja funkcji, dodając jeden odstęp pomiędzy nimi.

Uwaga: Jeśli chcesz trzymać się standardowego stylu w projektach Rusta, możesz użyć automatycznego narzędzia formatującego o nazwie rustfmt do formatowania kodu w określonym stylu (więcej o rustfmt w Dodatku D). Zespół Rusta dołączył to narzędzie do standardowej dystrybucji Rusta, podobnie jak rustc, więc powinno być już zainstalowane na Twoim komputerze!

Ciało funkcji main zawiera następujący kod:

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

Ten wiersz wykonuje całą pracę w tym małym programie: wyświetla tekst na ekranie. Należy zwrócić uwagę na trzy ważne szczegóły.

Po pierwsze, println! wywołuje makro Rusta. Gdyby wywoływało funkcję, byłoby wpisane jako println (bez !). Makra Rusta to sposób na pisanie kodu, który generuje kod w celu rozszerzenia składni Rusta, a omówimy je bardziej szczegółowo w Rozdziale 20. Na razie wystarczy wiedzieć, że użycie ! oznacza wywołanie makra zamiast normalnej funkcji, a makra nie zawsze przestrzegają tych samych zasad co funkcje.

Po drugie, widzisz ciąg znaków "Hello, world!". Przekazujemy ten ciąg jako argument do println!, a ciąg jest wyświetlany na ekranie.

Po trzecie, kończymy wiersz średnikiem (;), co oznacza, że to wyrażenie zostało zakończone, a następne jest gotowe do rozpoczęcia. Większość wierszy kodu Rusta kończy się średnikiem.

Kompilacja i wykonanie

Właśnie uruchomiłeś nowo utworzony program, więc przyjrzyjmy się każdemu krokowi w tym procesie.

Przed uruchomieniem programu w Ruście musisz go skompilować za pomocą kompilatora Rusta, wpisując polecenie rustc i podając nazwę pliku źródłowego, w ten sposób:

$ rustc main.rs

Jeśli masz doświadczenie z C lub C++, zauważysz, że jest to podobne do gcc lub clang. Po pomyślnej kompilacji Rust wypisuje plik wykonywalny.

Na Linuksie, macOS i w PowerShell na Windows, możesz zobaczyć plik wykonywalny, wpisując polecenie ls w swojej powłoce:

$ ls
main  main.rs

Na Linuksie i macOS zobaczysz dwa pliki. W PowerShell na Windows zobaczysz te same trzy pliki, które zobaczyłbyś używając CMD. W CMD na Windows wypisałbyś następujące polecenie:

> dir /B %= opcja /B wyświetla tylko nazwy plików =%
main.exe
main.pdb
main.rs

Pokazuje to plik kodu źródłowego z rozszerzeniem .rs, plik wykonywalny (main.exe na Windows, ale main na wszystkich innych platformach) oraz, w przypadku używania Windows, plik zawierający informacje debugowania z rozszerzeniem .pdb. Stąd uruchamiasz plik main lub main.exe, w ten sposób:

$ ./main # lub .\main na Windows

Jeśli twój main.rs to program „Witaj, świecie!”, ten wiersz wypisze Witaj, świecie! w twoim terminalu.

Jeśli jesteś bardziej zaznajomiony z językami dynamicznymi, takimi jak Ruby, Python lub JavaScript, możesz nie być przyzwyczajony do kompilowania i uruchamiania programu jako oddzielnych kroków. Rust jest językiem kompilowanym z wyprzedzeniem, co oznacza, że możesz skompilować program i przekazać plik wykonywalny komuś innemu, a ta osoba może go uruchomić nawet bez zainstalowanego Rusta. Jeśli przekażesz komuś plik .rb, .py lub .js, ta osoba musi mieć zainstalowaną (odpowiednio) implementację Ruby, Pythona lub JavaScriptu. Ale w tych językach potrzebujesz tylko jednego polecenia, aby skompilować i uruchomić program. Wszystko jest kompromisem w projektowaniu języka.

Samo kompilowanie za pomocą rustc jest wystarczające dla prostych programów, ale w miarę rozrostu projektu będziesz chciał zarządzać wszystkimi opcjami i ułatwić udostępnianie kodu. Następnie przedstawimy narzędzie Cargo, które pomoże Ci pisać rzeczywiste programy w Ruście.

Witaj, Cargo!

Witaj, Cargo!

Cargo to system budowania i menedżer pakietów Rusta. Większość Rustaceanów używa tego narzędzia do zarządzania swoimi projektami w Ruście, ponieważ Cargo obsługuje wiele zadań za Ciebie, takich jak budowanie kodu, pobieranie bibliotek, od których zależy Twój kod, i budowanie tych bibliotek. (Biblioteki, których potrzebuje Twój kod, nazywamy zależnościami.)

Najprostsze programy w Ruście, takie jak ten, który do tej pory napisaliśmy, nie mają żadnych zależności. Gdybyśmy zbudowali projekt „Witaj, świecie!” za pomocą Cargo, używałby on tylko części Cargo, która obsługuje budowanie kodu. W miarę pisania bardziej złożonych programów w Ruście, będziesz dodawać zależności, a jeśli rozpoczniesz projekt za pomocą Cargo, dodawanie zależności będzie znacznie łatwiejsze.

Ponieważ zdecydowana większość projektów w Ruście używa Cargo, reszta tej książki zakłada, że Ty również używasz Cargo. Cargo jest instalowane wraz z Rustem, jeśli użyłeś oficjalnych instalatorów omówionych w sekcji „Instalacja”. Jeśli zainstalowałeś Rusta innymi sposobami, sprawdź, czy Cargo jest zainstalowane, wpisując w terminalu:

$ cargo --version

Jeśli widzisz numer wersji, masz go! Jeśli widzisz błąd, taki jak command not found, poszukaj w dokumentacji swojej metody instalacji, aby ustalić, jak zainstalować Cargo oddzielnie.

Tworzenie projektu za pomocą Cargo

Utwórzmy nowy projekt za pomocą Cargo i przyjrzyjmy się, jak różni się od naszego oryginalnego projektu „Witaj, świecie!”. Wróć do katalogu projects (lub gdziekolwiek zdecydowałeś się przechowywać swój kod). Następnie, na każdym systemie operacyjnym, uruchom:

$ cargo new hello_cargo
$ cd hello_cargo

Pierwsze polecenie tworzy nowy katalog i projekt o nazwie hello_cargo. Nazwaliśmy nasz projekt hello_cargo, a Cargo tworzy swoje pliki w katalogu o tej samej nazwie.

Przejdź do katalogu hello_cargo i wypisz pliki. Zobaczysz, że Cargo wygenerowało dla nas dwa pliki i jeden katalog: plik Cargo.toml i katalog src z plikiem main.rs w środku.

Zainicjowało również nowe repozytorium Git wraz z plikiem .gitignore. Pliki Git nie zostaną wygenerowane, jeśli uruchomisz cargo new w istniejącym repozytorium Git; możesz nadpisać to zachowanie, używając cargo new --vcs=git.

Uwaga: Git to popularny system kontroli wersji. Możesz zmienić cargo new, aby używać innego systemu kontroli wersji lub żadnego, używając flagi --vcs. Uruchom cargo new --help, aby zobaczyć dostępne opcje.

Otwórz Cargo.toml w swoim ulubionym edytorze tekstu. Powinien wyglądać podobnie do kodu z Listingu 1-2.

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

[dependencies]

Ten plik jest w formacie TOML (Tom’s Obvious, Minimal Language), który jest formatem konfiguracyjnym Cargo.

Pierwszy wiersz, [package], to nagłówek sekcji wskazujący, że następne instrukcje konfigurują pakiet. W miarę dodawania kolejnych informacji do tego pliku, będziemy dodawać inne sekcje.

Trzy następne wiersze ustawiają informacje konfiguracyjne, których Cargo potrzebuje do skompilowania programu: nazwę, wersję i wydanie Rusta do użycia. Omówimy klucz edition w Dodatku E.

Ostatni wiersz, [dependencies], to początek sekcji, w której możesz wymienić wszystkie zależności swojego projektu. W Ruście pakiety kodu są nazywane skrzynkami. Nie będziemy potrzebować żadnych innych skrzynek do tego projektu, ale będziemy potrzebować ich w pierwszym projekcie w Rozdziale 2, więc skorzystamy z tej sekcji zależności wtedy.

Teraz otwórz src/main.rs i przyjrzyj się:

Nazwa pliku: src/main.rs

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

Cargo wygenerowało dla Ciebie program „Witaj, świecie!”, dokładnie taki jak ten, który napisaliśmy w Listingu 1-1! Do tej pory różnice między naszym projektem a projektem wygenerowanym przez Cargo polegały na tym, że Cargo umieściło kod w katalogu src, a my mamy plik konfiguracyjny Cargo.toml w najwyższym katalogu.

Cargo oczekuje, że Twoje pliki źródłowe będą znajdować się w katalogu src. Katalog projektu najwyższego poziomu jest przeznaczony tylko na pliki README, informacje licencyjne, pliki konfiguracyjne i wszystko inne, co nie jest związane z Twoim kodem. Korzystanie z Cargo pomaga w organizacji projektów. Wszystko ma swoje miejsce i wszystko jest na swoim miejscu.

Jeśli rozpocząłeś projekt, który nie używa Cargo, tak jak to zrobiliśmy z projektem „Witaj, świecie!”, możesz przekonwertować go na projekt, który używa Cargo. Przenieś kod projektu do katalogu src i utwórz odpowiedni plik Cargo.toml. Łatwym sposobem na uzyskanie pliku Cargo.toml jest uruchomienie cargo init, które utworzy go dla Ciebie automatycznie.

Budowanie i uruchamianie projektu Cargo

Teraz przyjrzyjmy się, co się zmieni, gdy zbudujemy i uruchomimy program „Witaj, świecie!” za pomocą Cargo! Z katalogu hello_cargo zbuduj swój projekt, wypisując następujące polecenie:

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

To polecenie tworzy plik wykonywalny w target/debug/hello_cargo (lub target\debug\hello_cargo.exe na Windows), a nie w bieżącym katalogu. Ponieważ domyślna kompilacja jest kompilacją debugową, Cargo umieszcza plik binarny w katalogu o nazwie debug. Możesz uruchomić plik wykonywalny za pomocą tego polecenia:

$ ./target/debug/hello_cargo # lub .\target\debug\hello_cargo.exe na Windows
Hello, world!

Jeśli wszystko pójdzie dobrze, w terminalu powinno zostać wyświetlone Witaj, świecie!. Uruchomienie cargo build po raz pierwszy powoduje również, że Cargo tworzy nowy plik na najwyższym poziomie: Cargo.lock. Ten plik śledzi dokładne wersje zależności w Twoim projekcie. Ten projekt nie ma zależności, więc plik jest nieco skąpy. Nigdy nie będziesz musiał ręcznie zmieniać tego pliku; Cargo zarządza jego zawartością za Ciebie.

Właśnie zbudowaliśmy projekt za pomocą cargo build i uruchomiliśmy go za pomocą ./target/debug/hello_cargo, ale możemy również użyć cargo run, aby skompilować kod, a następnie uruchomić wynikowy plik wykonywalny za jednym poleceniem:

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

Używanie cargo run jest wygodniejsze niż konieczność pamiętania o uruchamianiu cargo build, a następnie używaniu pełnej ścieżki do pliku binearnego, więc większość deweloperów używa cargo run.

Zauważ, że tym razem nie widzieliśmy wyjścia wskazującego, że Cargo kompiluje hello_cargo. Cargo ustaliło, że pliki nie uległy zmianie, więc nie przebudowywało, a jedynie uruchomiło plik binarny. Gdybyś zmodyfikował swój kod źródłowy, Cargo przebudowałoby projekt przed jego uruchomieniem, a Ty zobaczyłbyś takie wyjście:

$ 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 udostępnia również polecenie cargo check. To polecenie szybko sprawdza Twój kod, aby upewnić się, że kompiluje się, ale nie tworzy pliku wykonywalnego:

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

Dlaczego nie chciałbyś pliku wykonywalnego? Często cargo check jest zauważalnie szybsze niż cargo build, ponieważ pomija krok tworzenia pliku wykonywalnego. Jeśli stale sprawdzasz swoją pracę podczas pisania kodu, użycie cargo check przyspieszy proces informowania Cię, czy Twój projekt nadal się kompiluje! W związku z tym wielu Rustaceanów uruchamia cargo check periodycznie podczas pisania programu, aby upewnić się, że się kompiluje. Następnie uruchamiają cargo build, gdy są gotowi do użycia pliku wykonywalnego.

Podsumujmy, czego do tej pory nauczyliśmy się o Cargo:

• Możemy utworzyć projekt za pomocą cargo new.
• Możemy zbudować projekt za pomocą cargo build.
• Możemy zbudować i uruchomić projekt w jednym kroku za pomocą cargo run.
• Możemy zbudować projekt bez tworzenia pliku binarnego, aby sprawdzić błędy, za pomocą cargo check.
• Zamiast zapisywać wynik kompilacji w tym samym katalogu co nasz kod, Cargo przechowuje go w katalogu target/debug.

Dodatkową zaletą używania Cargo jest to, że polecenia są takie same, niezależnie od systemu operacyjnego, na którym pracujesz. Tak więc, w tym momencie nie będziemy już podawać konkretnych instrukcji dla Linuksa i macOS w stosunku do Windows.

Budowanie do wersji produkcyjnej

Kiedy Twój projekt jest wreszcie gotowy do wydania, możesz użyć cargo build --release, aby skompilować go z optymalizacjami. To polecenie utworzy plik wykonywalny w target/release zamiast target/debug. Optymalizacje sprawiają, że kod Rusta działa szybciej, ale ich włączenie wydłuża czas kompilacji programu. Dlatego istnieją dwa różne profile: jeden do rozwoju, gdy chcesz szybko i często przebudowywać, a drugi do budowania ostatecznego programu, który przekażesz użytkownikowi, który nie będzie wielokrotnie przebudowywany i który będzie działał tak szybko, jak to możliwe. Jeśli mierzysz czas uruchamiania kodu, upewnij się, że uruchamiasz cargo build --release i mierzysz wydajność z plikiem wykonywalnym w target/release.

Wykorzystanie konwencji Cargo

W przypadku prostych projektów Cargo nie zapewnia dużej wartości w porównaniu z samym używaniem rustc, ale udowodni swoją wartość, gdy Twoje programy staną się bardziej złożone. Gdy programy rozrosną się do wielu plików lub będą wymagały zależności, znacznie łatwiej jest pozwolić Cargo koordynować budowanie.

Mimo że projekt hello_cargo jest prosty, wykorzystuje teraz wiele rzeczywistych narzędzi, których będziesz używać w pozostałej części swojej kariery z Rustem. W rzeczywistości, aby pracować nad istniejącymi projektami, możesz użyć następujących poleceń, aby pobrać kod za pomocą Git, przejść do katalogu tego projektu i zbudować:

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

Więcej informacji na temat Cargo znajdziesz w jego dokumentacji.

Podsumowanie

Już świetnie zacząłeś swoją podróż z Rustem! W tym rozdziale nauczyłeś się:

• Jak zainstalować najnowszą stabilną wersję Rusta za pomocą rustup.
• Jak zaktualizować Rusta do nowszej wersji.
• Jak otworzyć lokalnie zainstalowaną dokumentację.
• Jak napisać i uruchomić program „Witaj, świecie!” bezpośrednio za pomocą rustc.
• Jak utworzyć i uruchomić nowy projekt, korzystając z konwencji Cargo.

To świetny moment, aby zbudować bardziej rozbudowany program, aby przyzwyczaić się do czytania i pisania kodu w Ruście. Tak więc, w Rozdziale 2 zbudujemy program do zgadywania liczb. Jeśli wolisz zacząć od nauki, jak działają powszechne koncepcje programistyczne w Ruście, zobacz Rozdział 3, a następnie wróć do Rozdziału 2.

Programowanie gry w zgadywanie

Zanurzmy się w Rust, realizując wspólnie praktyczny projekt! Ten rozdział wprowadza cię w kilka popularnych koncepcji Rusta, pokazując, jak używać ich w prawdziwym programie. Dowiesz się o let, match, metodach, funkcjach skojarzonych, zewnętrznych “crate’ach” i wielu innych! W kolejnych rozdziałach będziemy badać te idee bardziej szczegółowo. W tym rozdziale będziesz ćwiczyć tylko podstawy.

Zaimplementujemy klasyczny problem programistyczny dla początkujących: grę w zgadywanie. Działa to tak: program wygeneruje losową liczbę całkowitą od 1 do 100. Następnie poprosi gracza o podanie strzału. Po wprowadzeniu strzału, program wskaże, czy strzał jest za niski, czy za wysoki. Jeśli strzał jest prawidłowy, gra wyświetli komunikat gratulacyjny i zakończy się.

Konfiguracja nowego projektu

Aby skonfigurować nowy projekt, przejdź do katalogu projects, który utworzyłeś w Rozdziale 1, i utwórz nowy projekt za pomocą Cargo, w następujący sposób:

$ cargo new guessing_game
$ cd guessing_game

Pierwsze polecenie, cargo new, przyjmuje nazwę projektu (guessing_game) jako pierwszy argument. Drugie polecenie zmienia katalog na katalog nowego projektu.

Spójrz na wygenerowany plik Cargo.toml:

Nazwa pliku: Cargo.toml

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

[dependencies]

Jak widziałeś w Rozdziale 1, cargo new generuje program “Hello, world!” dla Ciebie. Sprawdź plik src/main.rs:

Nazwa pliku: src/main.rs

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

Teraz skompilujmy ten program “Hello, world!” i uruchommy go w tym samym kroku, używając polecenia 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!

Polecenie run przydaje się, gdy trzeba szybko iterować nad projektem, tak jak będziemy to robić w tej grze, szybko testując każdą iterację, zanim przejdziemy do następnej.

Otwórz ponownie plik src/main.rs. Cały kod będziesz pisać w tym pliku.

Przetwarzanie strzału

Pierwsza część programu do zgadywania liczb poprosi o dane wejściowe od użytkownika, przetworzy je i sprawdzi, czy dane są w oczekiwanej formie. Na początek pozwolimy graczowi wprowadzić strzał. Wprowadź kod z Listingu 2-1 do 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}");
}

Ten kod zawiera wiele informacji, więc przeanalizujmy go linia po linii. Aby pobrać dane od użytkownika, a następnie wyświetlić wynik, musimy wprowadzić bibliotekę wejścia/wyjścia io do zakresu. Biblioteka io pochodzi ze standardowej biblioteki, znanej jako 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}");
}

Domyślnie Rust ma zestaw elementów zdefiniowanych w standardowej bibliotece, które są wprowadzane do zakresu każdego programu. Ten zestaw nazywa się preludium, a wszystko w nim możesz zobaczyć w dokumentacji biblioteki standardowej.

Jeśli typ, którego chcesz użyć, nie znajduje się w preludium, musisz explicitnie wprowadzić ten typ do zakresu za pomocą instrukcji use. Użycie biblioteki std::io zapewnia wiele przydatnych funkcji, w tym możliwość przyjmowania danych wejściowych od użytkownika.

Jak widziałeś w Rozdziale 1, funkcja main jest punktem wejścia do programu:

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

Składnia fn deklaruje nową funkcję; nawiasy () wskazują, że nie ma parametrów; a nawias klamrowy { rozpoczyna ciało funkcji.

Jak również dowiedziałeś się w Rozdziale 1, println! to makro, które wyświetla ciąg znaków na ekranie:

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

Ten kod wyświetla komunikat informujący, czym jest gra, i prosi użytkownika o wprowadzenie danych.

Przechowywanie wartości w zmiennych

Następnie utworzymy zmienną do przechowywania danych wprowadzonych przez użytkownika, w ten sposób:

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

Teraz program staje się ciekawszy! W tej krótkiej linii dzieje się dużo. Używamy instrukcji let do utworzenia zmiennej. Oto inny przykład:

let apples = 5;

Ta linia tworzy nową zmienną o nazwie apples i wiąże ją z wartością 5. W Rust zmienne są domyślnie niezmienne, co oznacza, że gdy raz nadamy zmiennej wartość, wartość ta nie ulegnie zmianie. Omówimy tę koncepcję szczegółowo w sekcji „Zmienne i mutowalność”

nazwą zmiennej:

let apples = 5; // niezmienna
let mut bananas = 5; // mutowalna

Wracając do programu gry w zgadywanie, wiesz już, że let mut guess wprowadzi mutowalną zmienną o nazwie guess. Znak równości (=) mówi Rustowi, że chcemy teraz powiązać coś ze zmienną. Po prawej stronie znaku równości znajduje się wartość, z którą guess jest powiązane, czyli wynik wywołania String::new, funkcji, która zwraca nową instancję typu String. String to typ ciągu znaków dostarczony przez standardową bibliotekę, który jest rozszerzalnym, kodowanym UTF-8 fragmentem tekstu.

Składnia :: w linii ::new wskazuje, że new jest funkcją skojarzoną z typem String. Funkcja skojarzona to funkcja zaimplementowana dla danego typu, w tym przypadku String. Ta funkcja new tworzy nowy, pusty ciąg znaków. Funkcję new znajdziesz na wielu typach, ponieważ jest to powszechna nazwa dla funkcji, która tworzy nową wartość jakiegoś rodzaju.

Podsumowując, linia let mut guess = String::new(); utworzyła mutowalną zmienną, która jest obecnie powiązana z nową, pustą instancją String. Uff!

Odbieranie danych od użytkownika

Przypomnijmy, że na początku programu dołączyliśmy funkcjonalność wejścia/ wyjścia ze standardowej biblioteki za pomocą use std::io;. Teraz wywołamy funkcję stdin z modułu io, co pozwoli nam obsługiwać dane wejściowe od użytkownika:

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

Gdybyśmy nie zaimportowali modułu io za pomocą use std::io; na początku programu, nadal moglibyśmy użyć funkcji, pisząc wywołanie funkcji jako std::io::stdin. Funkcja stdin zwraca instancję std::io::Stdin, która jest typem reprezentującym uchwyt do standardowego wejścia dla Twojego terminala.

Następnie, linia .read_line(&mut guess) wywołuje metodę read_line na uchwycie standardowego wejścia w celu pobrania danych od użytkownika. Przekazujemy również &mut guess jako argument do read_line, aby powiedzieć jej, w którym ciągu znaków ma przechowywać dane wejściowe od użytkownika. Pełnym zadaniem read_line jest pobranie wszystkiego, co użytkownik wpisze do standardowego wejścia, i dodanie tego do ciągu znaków (bez nadpisywania jego zawartości), dlatego przekazujemy ten ciąg znaków jako argument. Argument ciągu znaków musi być mutowalny, aby metoda mogła zmieniać zawartość ciągu znaków.

Znak & wskazuje, że ten argument jest referencją, co pozwala wielu częściom Twojego kodu uzyskać dostęp do jednego fragmentu danych bez konieczności wielokrotnego kopiowania tych danych do pamięci. Referencje są złożoną funkcją, a jedną z głównych zalet Rusta jest to, jak bezpieczne i łatwe jest używanie referencji. Nie musisz znać wielu z tych szczegółów, aby zakończyć ten program. Na razie wystarczy wiedzieć, że podobnie jak zmienne, referencje są domyślnie niezmienne. Dlatego musisz napisać &mut guess zamiast &guess, aby uczynić ją mutowalną. (Rozdział 4 wyjaśni referencje bardziej dokładnie).

Obsługa potencjalnych błędów za pomocą Result

Nadal pracujemy nad tą linią kodu. Teraz omawiamy trzecią linię tekstu, ale zwróć uwagę, że jest to nadal część jednej logicznej linii kodu. Następna część to ta metoda:

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

Ten kod mogliśmy napisać jako:

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

Jednak jedna długa linia jest trudna do odczytania, więc najlepiej jest ją podzielić. Często rozsądne jest wprowadzenie nowej linii i innych białych znaków, aby ułatwić czytanie długich linii, gdy wywołujesz metodę za pomocą składni .method_name(). Teraz omówmy, co ta linia robi.

Jak wspomniano wcześniej, read_line umieszcza wszystko, co użytkownik wprowadzi, w przekazanym jej ciągu znaków, ale zwraca również wartość Result. Result to wyliczenie enums, często nazywane enum, które jest typem mogącym przyjmować jeden z wielu możliwych stanów. Każdy możliwy stan nazywamy wariantem.

Rozdział 6 omówi szczegółowo enums. Celem tych typów Result jest kodowanie informacji o obsłudze błędów.

Wariantami Result są Ok i Err. Wariant Ok wskazuje, że operacja zakończyła się sukcesem i zawiera pomyślnie wygenerowaną wartość. Wariant Err oznacza, że operacja zakończyła się niepowodzeniem i zawiera informacje o tym, jak lub dlaczego operacja się nie powiodła.

Wartości typu Result, podobnie jak wartości każdego typu, mają zdefiniowane na nich metody. Instancja Result ma metodę expect, którą możesz wywołać. Jeśli ta instancja Result jest wartością Err, expect spowoduje awarię programu i wyświetli komunikat, który przekazałeś jako argument do expect. Jeśli metoda read_line zwróci Err, będzie to prawdopodobnie wynikiem błędu pochodzącego z bazowego systemu operacyjnego. Jeśli ta instancja Result jest wartością Ok, expect pobierze wartość zwracaną, którą przechowuje Ok, i zwróci ci tylko tę wartość, abyś mógł jej użyć. W tym przypadku ta wartość to liczba bajtów w danych wejściowych użytkownika.

Jeśli nie wywołasz expect, program skompiluje się, ale otrzymasz ostrzeżenie:

$ 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 ostrzega, że nie użyłeś wartości Result zwróconej z read_line, wskazując, że program nie obsłużył możliwego błędu.

Właściwym sposobem na stłumienie ostrzeżenia jest faktyczne napisanie kodu do obsługi błędów, ale w naszym przypadku chcemy po prostu, aby ten program uległ awarii, gdy wystąpi problem, więc możemy użyć expect. Dowiesz się o recoverowaniu z błędów w Rozdziale 9.

Wyświetlanie wartości za pomocą znaczników println!

Poza końcowym nawiasem klamrowym, pozostała tylko jedna linia do omówienia w dotychczasowym kodzie:

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

Ta linia wyświetla ciąg znaków, który teraz zawiera dane wejściowe użytkownika. Zestaw nawiasów klamrowych {} to znacznik miejsca: Wyobraź sobie {} jako małe szczypce kraba, które trzymają wartość na miejscu. Podczas wyświetlania wartości zmiennej nazwa zmiennej może znajdować się w środku nawiasów klamrowych. Podczas wyświetlania wyniku oceny wyrażenia, umieść puste nawiasy klamrowe w ciągu formatującym, a następnie po ciągu formatującym umieść listę wyrażeń oddzielonych przecinkami, które mają być wyświetlone w każdym pustym znaczniku miejsca w tej samej kolejności. Wyświetlanie zmiennej i wyniku wyrażenia w jednym wywołaniu println! wyglądałoby tak:

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

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

Ten kod wydrukowałby x = 5 and y + 2 = 12.

Testowanie pierwszej części

Przetestujmy pierwszą część gry w zgadywanie. Uruchom ją za pomocą 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

W tym momencie pierwsza część gry jest gotowa: pobieramy dane z klawiatury, a następnie je wyświetlamy.

Generowanie tajnej liczby

Następnie musimy wygenerować tajną liczbę, którą użytkownik będzie próbował zgadnąć. Tajna liczba powinna być inna za każdym razem, aby gra była zabawna do wielokrotnego grania. Użyjemy losowej liczby od 1 do 100, aby gra nie była zbyt trudna. Rust nie zawiera jeszcze funkcji do generowania liczb losowych w standardowej bibliotece. Jednak zespół Rusta udostępnia pakiet rand crate z tą funkcjonalnością.

Zwiększanie funkcjonalności za pomocą pakietu

Pamiętaj, że crate to zbiór plików źródłowych Rusta. Projekt, który budujemy, jest binary crate, czyli plikiem wykonywalnym. Crate rand to library crate, który zawiera kod przeznaczony do użycia w innych programach i nie może być wykonywany samodzielnie.

Koordynacja zewnętrznych crate'ów przez Cargo to miejsce, w którym Cargo naprawdę błyszczy. Zanim będziemy mogli napisać kod, który używa rand, musimy zmodyfikować plik Cargo.toml, aby dodać rand jako zależność. Otwórz ten plik teraz i dodaj następującą linię na dole, pod nagłówkiem sekcji [dependencies], który Cargo dla Ciebie utworzył. Upewnij się, że określasz rand dokładnie tak, jak tutaj, z tym numerem wersji, w przeciwnym razie przykłady kodu w tym samouczku mogą nie działać:

Nazwa pliku: Cargo.toml

[dependencies]
rand = "0.8.5"

W pliku Cargo.toml wszystko, co następuje po nagłówku, jest częścią tej sekcji, która trwa, dopóki nie rozpocznie się inna sekcja. W [dependencies] informujesz Cargo, od których zewnętrznych pakietów zależy Twój projekt i których wersji tych pakietów potrzebujesz. W tym przypadku określamy pakiet rand ze specyfikatorem wersji semantycznej 0.8.5. Cargo rozumie Semantic Versioning (czasami nazywane SemVer), który jest standardem zapisu numerów wersji. Specyfikator 0.8.5 jest w rzeczywistości skrótem od ^0.8.5, co oznacza dowolną wersję co najmniej 0.8.5, ale padającą poniżej 0.9.0.

Cargo uważa, że te wersje mają publiczne API kompatybilne z wersją 0.8.5, a ta specyfikacja gwarantuje, że otrzymasz najnowszą wersję poprawki, która nadal będzie kompilować się z kodem w tym rozdziale. Żadna wersja 0.9.0 lub większa nie gwarantuje tego samego API, co w poniższych przykładach.

Teraz, bez zmiany kodu, zbudujmy projekt, jak pokazano w Listingu 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

Możesz zobaczyć różne numery wersji (ale wszystkie będą kompatybilne z kodem, dzięki SemVer!) i różne linie (w zależności od systemu operacyjnego), a linie mogą być w innej kolejności.

Gdy dołączamy zewnętrzną zależność, Cargo pobiera najnowsze wersje wszystkiego, czego ta zależność potrzebuje, z rejestru, który jest kopią danych z Crates.io. Crates.io to miejsce, w którym ludzie w ekosystemie Rusta publikują swoje projekty Rust open source, aby inni mogli z nich korzystać.

Po zaktualizowaniu rejestru Cargo sprawdza sekcję [dependencies] i pobiera wszystkie wymienione pakiety, które nie zostały jeszcze pobrane. W tym przypadku, choć wymieniliśmy tylko rand jako zależność, Cargo pobrał również inne pakiety, od których zależy rand, aby działał. Po pobraniu pakietów Rust kompiluje je, a następnie kompiluje projekt z dostępnymi zależnościami.

Jeśli natychmiast ponownie uruchomisz cargo build bez wprowadzania żadnych zmian, nie otrzymasz żadnych danych wyjściowych poza linią Finished. Cargo wie, że już pobrał i skompilował zależności, a Ty nie zmieniłeś nic w pliku Cargo.toml. Cargo wie również, że nie zmieniłeś nic w swoim kodzie, więc nie kompiluje go ponownie. Nie mając nic do zrobienia, po prostu kończy działanie.

Jeśli otworzysz plik src/main.rs, dokonasz trywialnej zmiany, a następnie zapiszesz go i ponownie zbudujesz, zobaczysz tylko dwie linie danych wyjściowych:

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

Te linie pokazują, że Cargo aktualizuje kompilację tylko o Twoją drobną zmianę w pliku src/main.rs. Twoje zależności nie uległy zmianie, więc Cargo wie, że może ponownie wykorzystać to, co już pobrał i skompilował dla nich.

Zapewnianie powtarzalnych kompilacji za pomocą pliku Cargo.lock

Cargo posiada mechanizm, który zapewnia, że możesz odbudować ten sam artefakt za każdym razem, gdy Ty lub ktokolwiek inny buduje Twój kod: Cargo będzie używać tylko tych wersji zależności, które określiłeś, chyba że wskażesz inaczej. Na przykład, powiedzmy, że w przyszłym tygodniu zostanie wydana wersja 0.8.6 pakietu rand, a ta wersja zawiera ważną poprawkę błędu, ale zawiera również regresję, która zepsuje Twój kod. Aby temu zaradzić, Rust tworzy plik Cargo.lock za pierwszym razem, gdy uruchamiasz cargo build, więc teraz mamy go w katalogu guessing_game.

Kiedy budujesz projekt po raz pierwszy, Cargo ustala wszystkie wersje zależności, które spełniają kryteria, a następnie zapisuje je do pliku Cargo.lock. Kiedy budujesz swój projekt w przyszłości, Cargo zobaczy, że plik Cargo.lock istnieje i użyje tam określonych wersji, zamiast ponownie wykonywać całej pracy związanej z ustalaniem wersji. Pozwala to na automatyczne powtarzalne budowanie. Innymi słowy, Twój projekt pozostanie w wersji 0.8.5, dopóki wyraźnie go nie zaktualizujesz, dzięki plikowi Cargo.lock. Ponieważ plik Cargo.lock jest ważny dla powtarzalnych kompilacji, często jest dodawany do kontroli wersji wraz z resztą kodu w Twoim projekcie.

Aktualizacja “crate’a”, aby uzyskać nową wersję

Kiedy chcesz zaktualizować pakiet, Cargo udostępnia polecenie update, które zignoruje plik Cargo.lock i ustali wszystkie najnowsze wersje, które pasują do twoich specyfikacji w Cargo.toml. Cargo następnie zapisze te wersje do pliku Cargo.lock. W przeciwnym razie, domyślnie, Cargo będzie szukać tylko wersji większych niż 0.8.5 i mniejszych niż 0.9.0. Jeśli pakiet rand wydał dwie nowe wersje 0.8.6 i 0.999.0, zobaczyłbyś następujące, gdybyś uruchomił 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 ignoruje wydanie 0.999.0. W tym momencie zauważyłbyś również zmianę w pliku Cargo.lock, wskazującą, że wersja pakietu rand, której teraz używasz, to 0.8.6. Aby użyć wersji rand 0.999.0 lub dowolnej wersji z serii 0.999.x, musiałbyś zamiast tego zaktualizować plik Cargo.toml, aby wyglądał tak (nie wprowadzaj tej zmiany, ponieważ poniższe przykłady zakładają, że używasz rand 0.8):

[dependencies]
rand = "0.999.0"

Następnym razem, gdy uruchomisz cargo build, Cargo zaktualizuje rejestr dostępnych pakietów i ponownie oceni Twoje wymagania dotyczące rand zgodnie z nową wersją, którą określiłeś.

Wiele jest do powiedzenia na temat Cargo i jego ekosystemu, które omówimy w Rozdziale 14, ale na razie to wszystko, co musisz wiedzieć. Cargo bardzo ułatwia ponowne używanie bibliotek, więc Rustowcy mogą pisać mniejsze projekty, które są montowane z wielu pakietów.

Generowanie liczby losowej

Zacznijmy używać rand do generowania liczby do zgadnięcia. Następnym krokiem jest aktualizacja src/main.rs, jak pokazano w Listingu 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}");
}

Najpierw dodajemy linię use rand::Rng;. Cecha Rng definiuje metody, które implementują generatory liczb losowych, i ta cecha musi być w zakresie, abyśmy mogli używać tych metod. Rozdział 10 szczegółowo omówi cechy.

Następnie dodajemy dwie linie w środku. W pierwszej linii wywołujemy funkcję rand::thread_rng, która daje nam konkretny generator liczb losowych, którego będziemy używać: taki, który jest lokalny dla bieżącego wątku wykonawczego i jest inicjowany przez system operacyjny. Następnie wywołujemy metodę gen_range na generatorze liczb losowych. Ta metoda jest zdefiniowana przez cechę Rng, którą wprowadziliśmy do zakresu za pomocą instrukcji use rand::Rng;. Metoda gen_range przyjmuje wyrażenie zakresu jako argument i generuje liczbę losową w tym zakresie. Rodzaj wyrażenia zakresu, którego tu używamy, ma postać start..=end i jest inkluzywny na dolnej i górnej granicy, więc musimy określić 1..=100, aby zażądać liczby od 1 do 100.

Druga nowa linia wyświetla tajną liczbę. Jest to przydatne podczas opracowywania programu, aby móc go przetestować, ale usuniemy ją z ostatecznej wersji. Nie ma sensu grać, jeśli program wyświetla odpowiedź zaraz po uruchomieniu!

Spróbuj uruchomić program kilka razy:

$ 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

Powinieneś otrzymać różne liczby losowe, i wszystkie powinny być liczbami pomiędzy 1 a 100. Świetna robota!

Porównywanie strzału z tajną liczbą

Teraz, gdy mamy dane wejściowe od użytkownika i liczbę losową, możemy je porównać. Ten krok jest pokazany w Listingu 2-4. Zauważ, że ten kod na razie się nie skompiluje, co wyjaśnimy.

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!"),
    }
}

Najpierw dodajemy kolejną instrukcję use, wprowadzając typ o nazwie std::cmp::Ordering do zakresu ze standardowej biblioteki. Typ Ordering to kolejne wyliczenie (enum) i ma warianty Less, Greater i Equal. Są to trzy możliwe wyniki porównania dwóch wartości.

Następnie dodajemy pięć nowych linii na dole, które używają typu Ordering. Metoda cmp porównuje dwie wartości i może być wywołana na wszystkim, co można porównać. Przyjmuje referencję do tego, z czym chcesz porównać: tutaj porównuje guess z secret_number. Następnie zwraca wariant wyliczenia Ordering, które wprowadziliśmy do zakresu za pomocą instrukcji use. Używamy wyrażenia match, aby zdecydować, co zrobić dalej, w oparciu o to, który wariant Ordering został zwrócony z wywołania cmp z wartościami w guess i secret_number.

Wyrażenie match składa się z ramion. Ramię składa się z wzorca, z którym ma być dopasowywana wartość, oraz kodu, który powinien zostać uruchomiony, jeśli wartość podana do match pasuje do wzorca tego ramienia. Rust pobiera wartość podaną do match i kolejno przegląda wzorce każdego ramienia. Patrzy na wzorzec pierwszego ramienia, Ordering::Less, i widzi, że wartość Ordering::Greater nie pasuje do Ordering::Less, więc ignoruje kod w tym ramieniu i przechodzi do następnego ramienia. Wzorzec następnego ramienia to Ordering::Greater, który pasuje do Ordering::Greater! Powiązany kod w tym ramieniu zostanie wykonany i wyświetli na ekranie Too big!. Wyrażenie match kończy się po pierwszym udanym dopasowaniu, więc w tym scenariuszu nie będzie patrzeć na ostatnie ramię.

Jednak kod w Listingu 2-4 jeszcze się nie skompiluje. Spróbujmy:

$ 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

Rdzeń błędu stwierdza, że występują niezgodne typy. Rust ma silny, statyczny system typów. Jednak ma również inferencję typów. Kiedy napisaliśmy let mut guess = String::new(), Rust był w stanie wywnioskować, że guess powinno być String i nie kazał nam pisać tego typu. secret_number natomiast jest typem liczbowym. Kilka typów liczbowych Rusta może mieć wartość pomiędzy 1 a 100: i32, liczba 32-bitowa; u32, niepodpisana liczba 32-bitowa; i64, liczba 64-bitowa; oraz inne. O ile nie określono inaczej, Rust domyślnie używa i32, który jest typem secret_number, chyba że dodasz informacje o typie w innym miejscu, co spowodowałoby, że Rust wywnioskowałby inny typ liczbowy. Powodem błędu jest to, że Rust nie może porównywać ciągu znaków i typu liczbowego.

Ostatecznie chcemy przekonwertować String, którą program odczytuje jako dane wejściowe, na typ liczbowy, abyśmy mogli porównać ją numerycznie z tajną liczbą. Robimy to, dodając tę linię do ciała funkcji main:

Nazwa pliku: 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!"),
    }
}

Linia to:

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

Tworzymy zmienną o nazwie guess. Ale chwila, czy program nie ma już zmiennej o nazwie guess? Tak, ale Rust pozwala nam w korzystny sposób zacienić poprzednią wartość guess nową. Zacienianie pozwala nam ponownie użyć nazwy zmiennej guess, zamiast zmuszać nas do tworzenia dwóch unikalnych zmiennych, takich jak guess_str i guess, na przykład. Omówimy to szczegółowo w Rozdziale 3, ale na razie wiedz, że ta funkcja jest często używana, gdy chcesz przekonwertować wartość z jednego typu na inny.

Wiązamy tę nową zmienną z wyrażeniem guess.trim().parse(). guess w wyrażeniu odnosi się do oryginalnej zmiennej guess, która zawierała dane wejściowe jako ciąg znaków. Metoda trim na instancji String usunie wszelkie białe znaki na początku i na końcu, co musimy zrobić, zanim przekonwertujemy ciąg znaków na u32, który może zawierać tylko dane liczbowe. Użytkownik musi nacisnąć enter, aby zadowolić read_line i wprowadzić swój strzał, co dodaje znak nowej linii do ciągu znaków. Na przykład, jeśli użytkownik wpisze 5 i naciśnie enter, guess będzie wyglądało tak: 5\n. \n oznacza “nową linię”. (W systemie Windows naciśnięcie enter powoduje powrót karetki i nową linię, \r\n.) Metoda trim usuwa \n lub \r\n, pozostawiając tylko 5.

Metoda parse na ciągach znaków konwertuje ciąg znaków na inny typ. Tutaj używamy jej do konwersji z ciągu znaków na liczbę. Musimy powiedzieć Rustowi dokładny typ liczbowy, którego chcemy, używając let guess: u32. Dwukropek (:) po guess mówi Rustowi, że będziemy anotować typ zmiennej. Rust ma kilka wbudowanych typów liczbowych; u32 widziane tutaj to niepodpisana, 32-bitowa liczba całkowita. Jest to dobry domyślny wybór dla małej liczby dodatniej. O innych typach liczbowych dowiesz się w Rozdziale 3.

Dodatkowo, adnotacja u32 w tym przykładzie programu i porównanie z secret_number oznacza, że Rust wywnioskuje, iż secret_number również powinno być u32. Tak więc, teraz porównanie będzie dotyczyło dwóch wartości tego samego typu!

Metoda parse będzie działać tylko na znakach, które można logicznie przekształcić na liczby i dlatego może łatwo powodować błędy. Gdyby, na przykład, ciąg znaków zawierał A👍%, nie byłoby sposobu na przekształcenie tego na liczbę. Ponieważ może to zakończyć się niepowodzeniem, metoda parse zwraca typ Result, podobnie jak metoda read_line (omówiona wcześniej w sekcji „Obsługa potencjalnych błędów za pomocą Result”). Będziemy traktować ten Result w ten sam sposób, ponownie używając metody expect. Jeśli parse zwróci wariant Err Result, ponieważ nie udało się utworzyć liczby z ciągu znaków, wywołanie expect spowoduje awarię gry i wyświetli komunikat, który mu podamy. Jeśli parse z powodzeniem przekonwertuje ciąg znaków na liczbę, zwróci wariant Ok Result, a expect zwróci liczbę, której chcemy z wartości Ok.

Uruchommy teraz program:

$ 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!

Świetnie! Mimo że przed zgadywaną liczbą dodano spacje, program nadal rozpoznał, że użytkownik zgadł 76. Uruchom program kilka razy, aby sprawdzić różne zachowania z różnymi rodzajami danych wejściowych: zgadnij liczbę poprawnie, zgadnij liczbę, która jest za wysoka, i zgadnij liczbę, która jest za niska.

Mamy już większość gry działającą, ale użytkownik może wykonać tylko jeden strzał. Zmieńmy to, dodając pętlę!

Zezwalanie na wielokrotne zgadywanie za pomocą pętli

Słowo kluczowe loop tworzy nieskończoną pętlę. Dodamy pętlę, aby dać użytkownikom więcej szans na odgadnięcie liczby:

Nazwa pliku: 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!"),
        }
    }
}

Jak widać, przenieśliśmy wszystko od monitu o wprowadzenie zgadywanej liczby dalej do pętli. Upewnij się, że wciśniesz każdą linię wewnątrz pętli o kolejne cztery spacje i ponownie uruchom program. Program będzie teraz prosił o kolejny strzał w nieskończoność, co wprowadza nowy problem. Wygląda na to, że użytkownik nie może wyjść!

Użytkownik zawsze mógł przerwać program za pomocą skrótu klawiaturowego ctrl-C. Ale jest inny sposób na ucieczkę przed tym nienasyconym potworem, jak wspomniano w dyskusji o parse w sekcji „Porównywanie strzału z tajną liczbą”: jeśli użytkownik wprowadzi dane nieliczbowe, program ulegnie awarii. Możemy to wykorzystać, aby pozwolić użytkownikowi wyjść, jak pokazano tutaj:

$ 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

Wpisanie quit spowoduje wyjście z gry, ale jak zauważysz, tak samo zadziała wprowadzenie dowolnych innych danych nieliczbowych. Jest to, delikatnie mówiąc, nieoptymalne; chcemy, aby gra zatrzymywała się również po odgadnięciu prawidłowej liczby.

Zakończenie po prawidłowym strzale

Zaprogramujmy grę tak, aby kończyła się, gdy użytkownik wygra, dodając instrukcję break:

Nazwa pliku: 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;
            }
        }
    }
}

Dodanie linii break po You win! powoduje, że program wychodzi z pętli, gdy użytkownik poprawnie odgadnie tajną liczbę. Wyjście z pętli oznacza również wyjście z programu, ponieważ pętla jest ostatnią częścią main.

Obsługa nieprawidłowych danych wejściowych

Aby jeszcze bardziej dopracować zachowanie gry, zamiast zawieszać program, gdy użytkownik wprowadzi dane nieliczbowe, niech gra ignoruje takie dane, umożliwiając użytkownikowi dalsze zgadywanie. Możemy to zrobić, zmieniając linię, w której guess jest konwertowane z String na u32, jak pokazano w Listingu 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;
            }
        }
    }
}

Zmieniamy wywołanie expect na wyrażenie match, aby zamiast zawieszenia w przypadku błędu, obsłużyć błąd. Pamiętaj, że parse zwraca typ Result, a Result jest wyliczeniem, które ma warianty Ok i Err. Używamy tutaj wyrażenia match, tak jak to robiliśmy z wynikiem Ordering metody cmp.

Jeśli parse jest w stanie pomyślnie przekształcić ciąg znaków w liczbę, zwróci wartość Ok, która będzie zawierać wynikową liczbę. Ta wartość Ok będzie pasować do wzorca pierwszego ramienia, a wyrażenie match po prostu zwróci wartość num, którą parse wyprodukowało i umieściło w wartości Ok. Ta liczba trafi dokładnie tam, gdzie chcemy, do nowej zmiennej guess, którą tworzymy.

Jeśli parse nie jest w stanie przekształcić ciągu znaków w liczbę, zwróci wartość Err, która zawiera więcej informacji o błędzie. Wartość Err nie pasuje do wzorca Ok(num) w pierwszym ramieniu match, ale pasuje do wzorca Err(_) w drugim ramieniu. Podkreślnik _ to wartość „chwyć-wszystko”; w tym przykładzie mówimy, że chcemy dopasować wszystkie wartości Err, niezależnie od tego, jakie informacje zawierają. Zatem program wykona kod drugiego ramienia, continue, co nakazuje programowi przejść do następnej iteracji loop i poprosić o kolejny strzał. Tak więc, efektywnie, program ignoruje wszystkie błędy, jakie parse może napotkać!

Teraz wszystko w programie powinno działać zgodnie z oczekiwaniami. Spróbujmy:

$ 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!

Cudownie! Z drobną, ostatnią poprawką, zakończymy grę w zgadywanie. Przypomnij sobie, że program nadal wyświetla tajną liczbę. To dobrze działało podczas testowania, ale psuje grę. Usuńmy println!, które wyświetla tajną liczbę. Listing 2-6 pokazuje ostateczny kod.

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

W tym momencie pomyślnie zbudowałeś grę w zgadywanie. Gratulacje!

Podsumowanie

Ten projekt był praktycznym sposobem na wprowadzenie cię w wiele nowych koncepcji Rusta: let, match, funkcje, użycie zewnętrznych pakietów i wiele innych. W kolejnych rozdziałach dowiesz się o tych koncepcjach bardziej szczegółowo. Rozdział 3 obejmuje koncepcje, które posiadają większość języków programowania, takie jak zmienne, typy danych i funkcje, i pokazuje, jak ich używać w Ruście. Rozdział 4 bada własność, cechę, która odróżnia Rusta od innych języków. Rozdział 5 omawia struktury i składnię metod, a Rozdział 6 wyjaśnia, jak działają wyliczenia (enums).

Podstawowe koncepcje programowania

Ten rozdział obejmuje koncepcje, które pojawiają się w prawie każdym języku programowania i sposób, w jaki działają w Ruście. Wiele języków programowania ma ze sobą wiele wspólnego w swoim rdzeniu. Żadna z koncepcji przedstawionych w tym rozdziale nie jest unikalna dla Rusta, ale omówimy je w kontekście Rusta i wyjaśnimy konwencje dotyczące ich używania.

Konkretnie, dowiesz się o zmiennych, podstawowych typach, funkcjach, komentarzach i przepływie sterowania. Te podstawy znajdą się w każdym programie Rusta, a wczesne ich poznanie da Ci solidny rdzeń, od którego możesz zacząć.

Słowa kluczowe

Język Rust ma zestaw słów kluczowych, które są zarezerwowane wyłącznie dla języka, podobnie jak w innych językach. Pamiętaj, że nie możesz używać tych słów jako nazw zmiennych ani funkcji. Większość słów kluczowych ma specjalne znaczenia, a będziesz ich używać do wykonywania różnych zadań w swoich programach w Ruście; kilka nie ma obecnie żadnej związanej z nimi funkcjonalności, ale zostały zarezerwowane dla funkcjonalności, która może zostać dodana do Rusta w przyszłości. Listę słów kluczowych znajdziesz w Dodatku A.

Zmienne i mutowalność

Zmienne i mutowalność

Jak wspomniano w sekcji „Przechowywanie wartości w zmiennych”, zmienne są domyślnie niezmienne. Jest to jedna z wielu wskazówek, które Rust daje Ci, abyś pisał swój kod w sposób, który wykorzystuje bezpieczeństwo i łatwą współbieżność, jakie oferuje Rust. Jednak nadal masz możliwość uczynienia swoich zmiennych mutowalnymi. Przyjrzyjmy się, jak i dlaczego Rust zachęca do preferowania niezmienności i dlaczego czasami możesz chcieć zrezygnować z tej opcji.

Kiedy zmienna jest niezmienna, po powiązaniu wartości z nazwą nie można zmienić tej wartości. Aby to zilustrować, wygeneruj nowy projekt o nazwie variables w swoim katalogu projects za pomocą cargo new variables.

Następnie, w nowym katalogu variables, otwórz src/main.rs i zastąp jego kod następującym kodem, który jeszcze się nie skompiluje:

Nazwa pliku: src/main.rs

fn main() {
    let x = 5;
    println!("Wartość x to: {x}");
    x = 6;
    println!("Wartość x to: {x}");
}

Zapisz i uruchom program za pomocą cargo run. Powinieneś otrzymać komunikat o błędzie dotyczący błędu niezmienności, jak pokazano w tym wyjściu:

$ 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

Ten przykład pokazuje, jak kompilator pomaga znaleźć błędy w Twoich programach. Błędy kompilatora mogą być frustrujące, ale tak naprawdę oznaczają tylko, że Twój program nie działa jeszcze bezpiecznie tak, jak chcesz; nie oznaczają, że nie jesteś dobrym programistą! Doświadczeni Rustaceanie nadal otrzymują błędy kompilatora.

Otrzymałeś komunikat o błędzie cannot assign twice to immutable variable `x` (nie można przypisać dwa razy do niezmiennej zmiennej x), ponieważ próbowałeś przypisać drugą wartość do niezmiennej zmiennej x.

Ważne jest, abyśmy otrzymywali błędy kompilacji, gdy próbujemy zmienić wartość, która została oznaczona jako niezmienna, ponieważ ta właśnie sytuacja może prowadzić do błędów. Jeśli jedna część naszego kodu działa w oparciu o założenie, że wartość nigdy się nie zmieni, a inna część naszego kodu zmienia tę wartość, możliwe jest, że pierwsza część kodu nie wykona tego, do czego została zaprojektowana. Przyczynę tego rodzaju błędu może być trudno wyśledzić po fakcie, zwłaszcza gdy druga część kodu zmienia wartość tylko czasami. Kompilator Rusta gwarantuje, że gdy zadeklarujesz, że wartość się nie zmieni, to naprawdę się nie zmieni, więc nie musisz sam tego śledzić. Twój kod jest dzięki temu łatwiejszy do przemyślenia.

Ale mutowalność może być bardzo przydatna i może sprawić, że kod będzie wygodniejszy w pisaniu. Chociaż zmienne są domyślnie niezmienne, możesz uczynić je mutowalnymi, dodając mut przed nazwą zmiennej, tak jak to zrobiłeś w Rozdziale 2. Dodanie mut również przekazuje intencję przyszłym czytelnikom kodu, wskazując, że inne części kodu będą zmieniać wartość tej zmiennej.

Na przykład, zmieńmy src/main.rs na następujący kod:

Nazwa pliku: src/main.rs

fn main() {
    let mut x = 5;
    println!("Wartość x to: {x}");
    x = 6;
    println!("Wartość x to: {x}");
}

Kiedy uruchomimy program teraz, otrzymamy:

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

Możemy zmienić wartość przypisaną do x z 5 na 6, gdy użyto mut. Ostatecznie, decyzja o użyciu mutowalności zależy od Ciebie i od tego, co uważasz za najbardziej przejrzyste w danej sytuacji.

Deklarowanie stałych

Podobnie jak niezmienne zmienne, stałe to wartości, które są powiązane z nazwą i nie mogą być zmieniane, ale istnieją pewne różnice między stałymi a zmiennymi.

Po pierwsze, nie wolno używać mut ze stałymi. Stałe są nie tylko domyślnie niezmienne — są zawsze niezmienne. Stałe deklaruje się za pomocą słowa kluczowego const zamiast słowa kluczowego let, a typ wartości musi być annotowany. Typy i adnotacje typów omówimy w następnej sekcji, „Typy danych”, więc na razie nie martw się szczegółami. Wystarczy wiedzieć, że zawsze musisz podawać typ.

Stałe mogą być deklarowane w dowolnym zasięgu, w tym w zasięgu globalnym, co czyni je użytecznymi dla wartości, o których wiele części kodu musi wiedzieć.

Ostatnia różnica polega na tym, że stałe mogą być ustawiane tylko na wyrażenie stałe, a nie na wynik wartości, która mogłaby być obliczona tylko w czasie uruchamiania.

Oto przykład deklaracji stałej:

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

Nazwa stałej to THREE_HOURS_IN_SECONDS, a jej wartość jest ustawiona na wynik pomnożenia 60 (liczby sekund w minucie) przez 60 (liczby minut w godzinie) przez 3 (liczby godzin, które chcemy policzyć w tym programie). Konwencją nazewniczą Rusta dla stałych jest używanie samych dużych liter z podkreśleniami między słowami. Kompilator jest w stanie ocenić ograniczony zestaw operacji w czasie kompilacji, co pozwala nam zapisać tę wartość w sposób łatwiejszy do zrozumienia i weryfikacji, zamiast ustawiać tę stałą na wartość 10 800. Więcej informacji na temat operacji, które można stosować przy deklarowaniu stałych, znajdziesz w sekcji Rust Reference dotyczącej ewaluacji stałych.

Stałe są ważne przez cały czas działania programu, w zasięgu, w którym zostały zadeklarowane. Ta właściwość sprawia, że stałe są przydatne dla wartości w domenie aplikacji, o których wiele części programu może potrzebować wiedzieć, takich jak maksymalna liczba punktów, jaką każdy gracz może zdobyć, lub prędkość światła.

Nazywanie zakodowanych wartości używanych w całym programie jako stałych jest przydatne w przekazywaniu znaczenia tej wartości przyszłym utrzymującym kod. Pomaga również mieć tylko jedno miejsce w kodzie, które trzeba by zmienić, gdyby zakodowana wartość wymagała aktualizacji w przyszłości.

Przesłanianie

Jak widziałeś w samouczku gry w zgadywanie w Rozdziale 2, możesz zadeklarować nową zmienną o tej samej nazwie co poprzednia zmienna. Rustaceanie mówią, że pierwsza zmienna jest przesłonięta przez drugą, co oznacza, że druga zmienna jest tym, co kompilator będzie widział, gdy użyjesz nazwy zmiennej. W efekcie druga zmienna przysłania pierwszą, przejmując wszelkie użycia nazwy zmiennej na siebie, dopóki sama nie zostanie przesłonięta lub zasięg się nie zakończy. Możemy przesłonić zmienną, używając tej samej nazwy zmiennej i powtarzając użycie słowa kluczowego let w następujący sposób:

Nazwa pliku: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("Wartość x w wewnętrznym zasięgu to: {x}");
    }

    println!("Wartość x to: {x}");
}

Ten program najpierw wiąże x z wartością 5. Następnie tworzy nową zmienną x, powtarzając let x =, biorąc oryginalną wartość i dodając 1 tak, aby wartość x wynosiła 6. Następnie, wewnątrz wewnętrznego zasięgu utworzonego za pomocą nawiasów klamrowych, trzecia instrukcja let również przesłania x i tworzy nową zmienną, mnożąc poprzednią wartość przez 2, aby nadać x wartość 12. Gdy ten zasięg się kończy, wewnętrzne przesłanianie zakończy się, a x powróci do 6. Kiedy uruchomimy ten program, wyświetli się następujący wynik:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
Wartość x w wewnętrznym zasięgu to: 12
Wartość x to: 6

Przesłanianie różni się od oznaczania zmiennej jako mut, ponieważ otrzymamy błąd kompilacji, jeśli przypadkowo spróbujemy przypisać nową wartość do tej zmiennej bez użycia słowa kluczowego let. Używając let, możemy wykonać kilka transformacji na wartości, ale po tych transformacjach zmienna pozostanie niezmienna.

Inna różnica między mut a przesłanianiem polega na tym, że ponieważ efektywnie tworzymy nową zmienną, gdy ponownie używamy słowa kluczowego let, możemy zmienić typ wartości, ale ponownie użyć tej samej nazwy. Na przykład, powiedzmy, że nasz program prosi użytkownika o podanie liczby spacji, jakie chce między tekstem, wprowadzając spacje, a następnie chcemy przechowywać te dane wejściowe jako liczbę:

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

Pierwsza zmienna spaces jest typu string, a druga zmienna spaces jest typu liczbowego. Przesłanianie pozwala nam uniknąć wymyślania różnych nazw, takich jak spaces_str i spaces_num; zamiast tego możemy ponownie użyć prostszej nazwy spaces. Jednakże, jeśli spróbujemy użyć mut w tym przypadku, jak pokazano tutaj, otrzymamy błąd kompilacji:

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

Błąd mówi, że nie wolno nam mutować typu zmiennej:

$ 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

Teraz, gdy zbadaliśmy, jak działają zmienne, przyjrzyjmy się innym typom danych, które mogą mieć.

Typy danych

Typy danych

Każda wartość w Ruście ma określony typ danych, który informuje Rusta, jaki rodzaj danych jest określany, aby wiedział, jak z nimi pracować. Przyjrzymy się dwóm podzbiorom typów danych: skalarnym i złożonym.

Pamiętaj, że Rust jest językiem statycznie typowanym, co oznacza, że musi znać typy wszystkich zmiennych w czasie kompilacji. Kompilator zazwyczaj może wywnioskować, jakiego typu chcemy użyć, na podstawie wartości i sposobu jej użycia. W przypadkach, gdy możliwych jest wiele typów, np. gdy konwertowaliśmy String na typ numeryczny za pomocą parse w sekcji „Porównywanie strzału z tajną liczbą” w Rozdziale 2, musimy dodać adnotację typu, taką jak ta:

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

Jeśli nie dodamy adnotacji typu : u32 pokazanej w poprzednim kodzie, Rust wyświetli następujący błąd, co oznacza, że kompilator potrzebuje od nas więcej informacji, aby wiedzieć, jakiego typu chcemy użyć:

$ 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

Zobaczysz różne adnotacje typów dla innych typów danych.

Typy skalarne

Typ skalarny reprezentuje pojedynczą wartość. Rust ma cztery główne typy skalarne: liczby całkowite, liczby zmiennoprzecinkowe, wartości boolowskie i znaki. Możesz je rozpoznać z innych języków programowania. Przejdźmy do tego, jak działają w Rust.

Typy całkowite

Liczba całkowita to liczba bez części ułamkowej. Użyliśmy jednego typu całkowitego w Rozdziale 2, typu u32. Ta deklaracja typu wskazuje, że wartość, z którą jest skojarzona, powinna być niepodpisaną liczbą całkowitą (typy całkowite ze znakiem zaczynają się od i zamiast u), która zajmuje 32 bity pamięci. Tabela 3-1 pokazuje wbudowane typy całkowite w Rust. Możemy użyć dowolnego z tych wariantów do zadeklarowania typu wartości całkowitej.

Tabela 3-1: Typy całkowite w Rust

Każdy wariant może być ze znakiem lub bez znaku i ma wyraźny rozmiar. Ze znakiem i bez znaku odnoszą się do tego, czy liczba może być ujemna – inaczej mówiąc, czy liczba musi mieć znak (ze znakiem), czy zawsze będzie dodatnia i dlatego może być reprezentowana bez znaku (bez znaku). To jak pisanie liczb na papierze: gdy znak ma znaczenie, liczba jest pokazywana ze znakiem plus lub minus; jednak, gdy można bezpiecznie założyć, że liczba jest dodatnia, jest pokazywana bez znaku. Liczby ze znakiem są przechowywane za pomocą reprezentacji dopełnienia do dwóch.

Każdy wariant ze znakiem może przechowywać liczby od −(2^{n − 1}) do 2^{n − 1} − 1 włącznie, gdzie n to liczba bitów, które używa ten wariant. Tak więc i8 może przechowywać liczby od −(2⁷) do 2⁷ − 1, co równa się −128 do 127. Warianty bez znaku mogą przechowywać liczby od 0 do 2ⁿ − 1, więc u8 może przechowywać liczby od 0 do 2⁸ − 1, co równa się 0 do 255.

Dodatkowo, typy isize i usize zależą od architektury komputera, na którym działa Twój program: 64 bity, jeśli jesteś na architekturze 64-bitowej, i 32 bity, jeśli jesteś na architekturze 32-bitowej.

Literały całkowite można zapisywać w dowolnej z form pokazanych w tabeli 3-2. Zauważ, że literały liczbowe, które mogą być wieloma typami numerycznymi, dopuszczają sufiks typu, taki jak 57u8, do określenia typu. Literały liczbowe mogą również używać _ jako wizualnego separatora, aby ułatwić odczytanie liczby, np. 1_000, która będzie miała taką samą wartość, jakbyś określił 1000.

Tabela 3-2: Literały całkowite w Rust

Więc skąd wiesz, jakiego typu liczby całkowitej użyć? Jeśli nie jesteś pewien, domyślne ustawienia Rusta są zazwyczaj dobrym punktem wyjścia: typy całkowite domyślnie przyjmują i32. Główna sytuacja, w której użyłbyś isize lub usize, to indeksowanie jakiegoś rodzaju kolekcji.

Typy zmiennoprzecinkowe

Rust ma również dwa prymitywne typy dla liczb zmiennoprzecinkowych, które są liczbami z punktami dziesiętnymi. Typy zmiennoprzecinkowe Rusta to f32 i f64, które mają odpowiednio 32 i 64 bity. Domyślnym typem jest f64, ponieważ na nowoczesnych procesorach ma on w przybliżeniu taką samą prędkość jak f32, ale jest w stanie zapewnić większą precyzję. Wszystkie typy zmiennoprzecinkowe są ze znakiem.

Oto przykład, który pokazuje liczby zmiennoprzecinkowe w akcji:

Nazwa pliku: src/main.rs

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

    let y: f32 = 3.0; // f32
}

Liczby zmiennoprzecinkowe są reprezentowane zgodnie ze standardem IEEE-754.

Operacje numeryczne

Rust obsługuje podstawowe operacje matematyczne, których można oczekiwać dla wszystkich typów liczbowych: dodawanie, odejmowanie, mnożenie, dzielenie i reszta z dzielenia. Dzielenie całkowite obcina w kierunku zera do najbliższej liczby całkowitej. Poniższy kod pokazuje, jak użyć każdej operacji numerycznej w instrukcji let:

Nazwa pliku: src/main.rs

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

    // odejmowanie
    let difference = 95.5 - 4.3;

    // mnożenie
    let product = 4 * 30;

    // dzielenie
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Wynosi -1

    // reszta z dzielenia
    let remainder = 43 % 5;
}

Każde wyrażenie w tych instrukcjach używa operatora matematycznego i ocenia się do pojedynczej wartości, która następnie jest wiązana ze zmienną. Dodatek B zawiera listę wszystkich operatorów, dostarczanych przez Rusta.

Typ boolowski

Podobnie jak w większości innych języków programowania, typ boolowski w Rust ma dwie możliwe wartości: true i false. Wartości boolowskie mają rozmiar jednego bajta. Typ boolowski w Rust jest określany za pomocą bool. Na przykład:

Nazwa pliku: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // z jawną adnotacją typu
}

Głównym sposobem używania wartości boolowskich jest poprzez warunki, takie jak wyrażenie if. Omówimy, jak działają wyrażenia if w Rust w sekcji „Sterowanie przepływem”.

Typ znakowy

Typ char w Rust jest najbardziej prymitywnym typem alfabetycznym języka. Oto kilka przykładów deklarowania wartości char:

Nazwa pliku: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // z jawną adnotacją typu
    let heart_eyed_cat = '😻';
}

Zwróć uwagę, że literały char określamy pojedynczymi cudzysłowami, w przeciwieństwie do literałów stringowych, które używają podwójnych cudzysłowów. Typ char w Rust ma rozmiar 4 bajtów i reprezentuje skalarną wartość Unicode, co oznacza, że może reprezentować znacznie więcej niż tylko ASCII. Litery akcentowane; znaki chińskie, japońskie i koreańskie; emotikony; oraz spacje o zerowej szerokości są w Ruście prawidłowymi wartościami char. Skalarne wartości Unicode mieszczą się w zakresie od U+0000 do U+D7FF oraz od U+E000 do U+10FFFF włącznie. Jednak „znak” nie jest tak naprawdę koncepcją w Unicode, więc Twoja ludzka intuicja co do tego, czym jest „znak”, może nie pasować do tego, czym jest char w Rust. Omówimy ten temat szczegółowo w sekcji „Przechowywanie tekstu kodowanego UTF-8 za pomocą ciągów znaków” w Rozdziale 8.

Typy złożone

Typy złożone mogą grupować wiele wartości w jeden typ. Rust ma dwa prymitywne typy złożone: krotki i tablice.

Typ krotki

Krotka to ogólny sposób grupowania wielu wartości o różnych typach w jeden typ złożony. Krotki mają stałą długość: po zadeklarowaniu nie mogą rosnąć ani kurczyć się.

Tworzymy krotkę, pisząc listę wartości oddzielonych przecinkami w nawiasach. Każda pozycja w krotce ma typ, a typy różnych wartości w krotce nie muszą być takie same. W tym przykładzie dodaliśmy opcjonalne adnotacje typów:

Nazwa pliku: src/main.rs

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

Zmienna tup wiąże się z całą krotką, ponieważ krotka jest traktowana jako pojedynczy element złożony. Aby uzyskać poszczególne wartości z krotki, możemy użyć dopasowania wzorców do dekonstrukcji wartości krotki, w ten sposób:

Nazwa pliku: src/main.rs

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

    let (x, y, z) = tup;

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

Ten program najpierw tworzy krotkę i wiąże ją ze zmienną tup. Następnie używa wzorca z let, aby wziąć tup i zamienić ją w trzy oddzielne zmienne: x, y i z. Nazywa się to dekonstrukcją, ponieważ rozbija pojedynczą krotkę na trzy części. Na koniec program wypisuje wartość y, która wynosi 6.4.

Możemy również uzyskać dostęp do elementu krotki bezpośrednio, używając kropki (.) następującej po indeksie wartości, do której chcemy uzyskać dostęp. Na przykład:

Nazwa pliku: 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;
}

Ten program tworzy krotkę x, a następnie uzyskuje dostęp do każdego elementu krotki za pomocą ich odpowiednich indeksów. Podobnie jak w większości języków programowania, pierwszy indeks w krotce to 0.

Krotka bez żadnych wartości ma specjalną nazwę, jednostka. Ta wartość i jej odpowiedni typ są zapisywane jako () i reprezentują pustą wartość lub pusty typ zwracany. Wyrażenia niejawnie zwracają wartość jednostkową, jeśli nie zwracają żadnej innej wartości.

Typ tablicowy

Innym sposobem posiadania kolekcji wielu wartości jest tablica. W przeciwieństwie do krotki, każdy element tablicy musi mieć ten sam typ. W przeciwieństwie do tablic w niektórych innych językach, tablice w Rust mają stałą długość.

Wartości w tablicy zapisujemy jako listę oddzieloną przecinkami w nawiasach kwadratowych:

Nazwa pliku: src/main.rs

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

Tablice są przydatne, gdy chcesz, aby dane były alokowane na stosie, tak jak inne typy, które widzieliśmy do tej pory, a nie na stercie (omówimy stos i sterę dokładniej w Rozdziale 4) lub gdy chcesz zapewnić, że zawsze będziesz mieć stałą liczbę elementów. Tablica nie jest jednak tak elastyczna jak typ wektora. Wektor to podobny typ kolekcji dostarczany przez standardową bibliotekę, który może rosnąć lub kurczyć się w rozmiarze, ponieważ jego zawartość znajduje się na stercie. Jeśli nie masz pewności, czy użyć tablicy, czy wektora, prawdopodobnie powinieneś użyć wektora. Rozdział 8 omawia wektory bardziej szczegółowo.

Jednak tablice są bardziej przydatne, gdy wiesz, że liczba elementów nie będzie musiała się zmieniać. Na przykład, jeśli używałbyś nazw miesięcy w programie, prawdopodobnie użyłbyś tablicy, a nie wektora, ponieważ wiesz, że zawsze będzie zawierać 12 elementów:

#![allow(unused)]
fn main() {
let months = ["Styczeń", "Luty", "Marzec", "Kwiecień", "Maj", "Czerwiec", "Lipiec",
              "Sierpień", "Wrzesień", "Październik", "Listopad", "Grudzień"];
}

Typ tablicy zapisujesz, używając nawiasów kwadratowych z typem każdego elementu, średnika, a następnie liczby elementów w tablicy, w ten sposób:

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

Tutaj i32 jest typem każdego elementu. Po średniku liczba 5 wskazuje, że tablica zawiera pięć elementów.

Możesz również zainicjalizować tablicę tak, aby zawierała tę samą wartość dla każdego elementu, określając wartość początkową, po której następuje średnik, a następnie długość tablicy w nawiasach kwadratowych, jak pokazano tutaj:

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

Tablica o nazwie a będzie zawierała 5 elementów, z których wszystkie początkowo zostaną ustawione na wartość 3. Jest to to samo, co napisanie let a = [3, 3, 3, 3, 3];, ale w bardziej zwięzły sposób.

Dostęp do elementów tablicy

Tablica to pojedynczy blok pamięci o znanej, stałej wielkości, który może być alokowany na stosie. Możesz uzyskać dostęp do elementów tablicy za pomocą indeksowania, w ten sposób:

Nazwa pliku: src/main.rs

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

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

W tym przykładzie zmienna o nazwie first otrzyma wartość 1, ponieważ jest to wartość pod indeksem [0] w tablicy. Zmienna o nazwie second otrzyma wartość 2 z indeksu [1] w tablicy.

Nieprawidłowy dostęp do elementów tablicy

Zobaczmy, co się stanie, jeśli spróbujesz uzyskać dostęp do elementu tablicy, który wykracza poza jej koniec. Powiedzmy, że uruchamiasz ten kod, podobny do gry w zgadywanie z Rozdziału 2, aby uzyskać indeks tablicy od użytkownika:

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

Ten kod kompiluje się pomyślnie. Jeśli uruchomisz ten kod za pomocą cargo run i wprowadzisz 0, 1, 2, 3 lub 4, program wyświetli odpowiednią wartość pod tym indeksem w tablicy. Jeśli zamiast tego wprowadzisz liczbę wykraczającą poza koniec tablicy, taką jak 10, zobaczysz dane wyjściowe podobne do tego:

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

Program spowodował błąd wykonawczy w momencie użycia nieprawidłowej wartości w operacji indeksowania. Program zakończył działanie z komunikatem o błędzie i nie wykonał końcowej instrukcji println!. Kiedy próbujesz uzyskać dostęp do elementu za pomocą indeksowania, Rust sprawdzi, czy podany indeks jest mniejszy niż długość tablicy. Jeśli indeks jest większy lub równy długości, Rust spanikuje. To sprawdzenie musi nastąpić w czasie wykonania, szczególnie w tym przypadku, ponieważ kompilator nie jest w stanie wiedzieć, jaką wartość użytkownik wprowadzi, gdy uruchomi kod później.

Jest to przykład działania zasad bezpieczeństwa pamięci Rusta. W wielu niskopoziomowych językach ten rodzaj sprawdzenia nie jest wykonywany, a gdy podasz nieprawidłowy indeks, można uzyskać dostęp do nieprawidłowej pamięci. Rust chroni Cię przed tego rodzaju błędami, natychmiast kończąc działanie, zamiast pozwalać na dostęp do pamięci i kontynuować. Rozdział 9 omawia więcej o obsłudze błędów w Rust i o tym, jak pisać czytelny, bezpieczny kod, który ani nie panikuje, ani nie pozwala na dostęp do nieprawidłowej pamięci.

Funkcje

Funkcje

Funkcje są powszechne w kodzie Rusta. Widziałeś już jedną z najważniejszych funkcji w języku: funkcję main, która jest punktem wejścia wielu programów. Widziałeś również słowo kluczowe fn, które pozwala deklarować nowe funkcje.

Kod Rusta używa snake case jako konwencjonalnego stylu dla nazw funkcji i zmiennych, w którym wszystkie litery są małe, a podkreślenia oddzielają słowa. Oto program, który zawiera przykładową definicję funkcji:

Nazwa pliku: src/main.rs

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

    another_function();
}

fn another_function() {
    println!("Inna funkcja.");
}

Definiujemy funkcję w Ruście, wpisując fn po której następuje nazwa funkcji i zestaw nawiasów. Nawiasy klamrowe informują kompilator, gdzie zaczyna się i kończy ciało funkcji.

Możemy wywołać dowolną zdefiniowaną przez nas funkcję, wpisując jej nazwę, a następnie zestaw nawiasów. Ponieważ another_function jest zdefiniowana w programie, może być wywołana z wewnątrz funkcji main. Zauważ, że zdefiniowaliśmy another_function po funkcji main w kodzie źródłowym; mogliśmy ją również zdefiniować wcześniej. Rust nie dba o to, gdzie definiujesz swoje funkcje, a jedynie o to, czy są zdefiniowane w zasięgu, który może być widoczny dla wywołującego.

Utwórzmy nowy projekt binarny o nazwie functions, aby dokładniej zbadać funkcje. Umieść przykład another_function w src/main.rs i uruchom go. Ppowinien pojawić się następujący wynik:

$ 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!
Inna funkcja.

Wiersze wykonują się w kolejności, w jakiej pojawiają się w funkcji main. Najpierw wypisuje się komunikat „Witaj, świecie!”, a następnie wywoływana jest another_function i wypisuje się jej komunikat.

Parametry

Możemy definiować funkcje tak, aby miały parametry, które są specjalnymi zmiennymi będącymi częścią sygnatury funkcji. Gdy funkcja ma parametry, można podać jej konkretne wartości dla tych parametrów. Technicznie, konkretne wartości nazywane są argumentami, ale w potocznej rozmowie ludzie mają skłonność do używania słów parametr i argument zamiennie dla zmiennych w definicji funkcji lub konkretnych wartości przekazywanych podczas wywoływania funkcji.

W tej wersji another_function dodajemy parametr:

Nazwa pliku: src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("Wartość x to: {x}");
}

Spróbuj uruchomić ten program; powinieneś uzyskać następujący wynik:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
Wartość x to: 5

Deklaracja another_function ma jeden parametr o nazwie x. Typ x jest określony jako i32. Kiedy przekazujemy 5 do another_function, makro println! umieszcza 5 tam, gdzie w ciągu formatującym znajdowały się nawiasy klemrowe zawierające x.

W sygnaturach funkcji musisz zadeklarować typ każdego parametru. Jest to świadoma decyzja w projekcie Rusta: Wymaganie adnotacji typów w definicjach funkcji oznacza, że kompilator prawie nigdy nie potrzebuje, abyś używał ich w innym miejscu w kodzie, aby zrozumieć, jaki typ masz na myśli. Kompilator jest również w stanie dostarczyć bardziej pomocne komunikaty o błędach, jeśli wie, jakich typów oczekuje funkcja.

Podczas definiowania wielu parametrów, oddziel deklaracje parametrów przecinkami, w ten sposób:

Nazwa pliku: src/main.rs

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

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("Pomiar to: {value}{unit_label}");
}

Ten przykład tworzy funkcję o nazwie print_labeled_measurement z dwoma parametrami. Pierwszy parametr ma nazwę value i jest typu i32. Drugi ma nazwę unit_label i jest typu char. Funkcja następnie wypisuje tekst zawierający zarówno value, jak i unit_label.

Spróbuj uruchomić ten kod. Zastąp program znajdujący się obecnie w pliku src/main.rs projektu functions poprzednim przykładem i uruchom go za pomocą 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`
Pomiar to: 5h

Ponieważ wywołaliśmy funkcję z 5 jako wartością dla value i 'h' jako wartością dla unit_label, wyjście programu zawiera te wartości.

Instrukcje i wyrażenia

Ciała funkcji składają się z serii instrukcji, opcjonalnie zakończonych wyrażeniem. Do tej pory omówione przez nas funkcje nie zawierały końcowego wyrażenia, ale widziałeś wyrażenie jako część instrukcji. Ponieważ Rust jest językiem opartym na wyrażeniach, jest to ważne rozróżnienie do zrozumienia. Inne języki nie mają tych samych rozróżnień, więc przyjrzyjmy się, czym są instrukcje i wyrażenia oraz jak ich różnice wpływają na ciała funkcji.

• Instrukcje to polecenia, które wykonują jakąś akcję i nie zwracają wartości.
• Wyrażenia obliczają się do wartości wynikowej.

Przyjrzyjmy się kilku przykładom.

W rzeczywistości już używaliśmy instrukcji i wyrażeń. Tworzenie zmiennej i przypisywanie jej wartości za pomocą słowa kluczowego let jest instrukcją. W Listingu 3-1, let y = 6; to instrukcja.

fn main() {
    let y = 6;
}

Definicje funkcji to również instrukcje; cały poprzedni przykład sam w sobie jest instrukcją. (Jak wkrótce zobaczymy, wywoływanie funkcji nie jest instrukcją.)

Instrukcje nie zwracają wartości. Dlatego nie możesz przypisać instrukcji let do innej zmiennej, tak jak próbuje to zrobić poniższy kod; otrzymasz błąd:

Nazwa pliku: src/main.rs

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

Po uruchomieniu tego programu otrzymasz następujący błąd:

$ 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

Instrukcja let y = 6 nie zwraca wartości, więc nie ma nic, do czego x mogłoby się związać. Różni się to od tego, co dzieje się w innych językach, takich jak C i Ruby, gdzie przypisanie zwraca wartość przypisania. W tych językach można napisać x = y = 6 i sprawić, że zarówno x, jak i y będą miały wartość 6; tak nie jest w Ruście.

Wyrażenia obliczają się do wartości i stanowią większość pozostałego kodu, który będziesz pisać w Ruście. Rozważ operację matematyczną, taką jak 5 + 6, która jest wyrażeniem, które oblicza się do wartości 11. Wyrażenia mogą być częścią instrukcji: W Listingu 3-1, 6 w instrukcji let y = 6; jest wyrażeniem, które oblicza się do wartości 6. Wywoływanie funkcji jest wyrażeniem. Wywoływanie makra jest wyrażeniem. Nowy blok zasięgu utworzony za pomocą nawiasów klamrowych jest wyrażeniem, na przykład:

Nazwa pliku: src/main.rs

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

    println!("Wartość y to: {y}");
}

To wyrażenie:

{
    let x = 3;
    x + 1
}

jest blokiem, który w tym przypadku oblicza się do 4. Ta wartość zostaje związana z y jako część instrukcji let. Zauważ wiersz x + 1 bez średnika na końcu, co różni się od większości dotychczas widzianych wierszy. Wyrażenia nie zawierają końcowych średników. Jeśli dodasz średnik na końcu wyrażenia, zmienisz je w instrukcję, a wtedy nie zwróci ono wartości. Miej to na uwadze, gdy będziesz dalej poznawać wartości zwracane przez funkcje i wyrażenia.

Funkcje zwracające wartości

Funkcje mogą zwracać wartości do wywołującego je kodu. Nie nazywamy wartości zwracanych, ale musimy zadeklarować ich typ po strzałce (->). W Ruście, wartość zwracana przez funkcję jest synonimem wartości ostatniego wyrażenia w bloku ciała funkcji. Możesz zwrócić wartość wcześniej z funkcji, używając słowa kluczowego return i określając wartość, ale większość funkcji zwraca ostatnie wyrażenie niejawnie. Oto przykład funkcji, która zwraca wartość:

Nazwa pliku: src/main.rs

fn five() -> i32 {
    5
}

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

    println!("Wartość x to: {x}");
}

Nie ma wywołań funkcji, makr, ani nawet instrukcji let w funkcji five — tylko sama liczba 5. To jest całkowicie poprawna funkcja w Ruście. Zauważ, że typ zwracany funkcji jest również określony jako -> i32. Spróbuj uruchomić ten kod; wyjście powinno wyglądać tak:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
Wartość x to: 5

5 w five jest wartością zwracaną przez funkcję, dlatego typ zwracany to i32. Zbadajmy to bardziej szczegółowo. Są tu dwa ważne aspekty: Po pierwsze, wiersz let x = five(); pokazuje, że używamy wartości zwracanej przez funkcję do inicjalizacji zmiennej. Ponieważ funkcja five zwraca 5, ten wiersz jest równoważny z następującym:

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

Po drugie, funkcja five nie ma parametrów i definiuje typ wartości zwracanej, ale ciało funkcji to samotne 5 bez średnika, ponieważ jest to wyrażenie, którego wartość chcemy zwrócić.

Przyjrzyjmy się innemu przykładowi:

Nazwa pliku: src/main.rs

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

    println!("Wartość x to: {x}");
}

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

Uruchomienie tego kodu wypisze Wartość x to: 6. Ale co się stanie, jeśli umieścimy średnik na końcu wiersza zawierającego x + 1, zmieniając go z wyrażenia w instrukcję?

Nazwa pliku: src/main.rs

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

    println!("Wartość x to: {x}");
}

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

Skompilowanie tego kodu spowoduje błąd, jak następuje:

$ 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

Główny komunikat o błędzie, mismatched types (niezgodne typy), ujawnia sedno problemu z tym kodem. Definicja funkcji plus_one mówi, że zwróci i32, ale instrukcje nie obliczają się do wartości, co jest wyrażone przez (), typ jednostkowy. Dlatego nic nie jest zwracane, co jest sprzeczne z definicją funkcji i skutkuje błędem. W tym wyjściu Rust dostarcza komunikat, który być może pomoże rozwiązać ten problem: sugeruje usunięcie średnika, co naprawiłoby błąd.

Komentarze

Komentarze

Wszyscy programiści dążą do tego, aby ich kod był łatwy do zrozumienia, ale czasami wymagane jest dodatkowe wyjaśnienie. W takich przypadkach programiści pozostawiają komentarze w swoim kodzie źródłowym, które kompilator zignoruje, ale które osoby czytające kod źródłowy mogą uznać za przydatne.

Oto prosty komentarz:

#![allow(unused)]
fn main() {
// witaj, świecie
}

W Ruście idiomatyczny styl komentarzy rozpoczyna komentarz dwoma ukośnikami, a komentarz trwa do końca linii. W przypadku komentarzy, które rozciągają się poza jedną linię, należy umieścić // na każdej linii, w ten sposób:

#![allow(unused)]
fn main() {
// Więc robimy tutaj coś skomplikowanego, na tyle długiego, że potrzebujemy
// wielu linii komentarzy, żeby to zrobić! Uff! Mamy nadzieję, że ten komentarz
// wyjaśni, co się dzieje.
}

Komentarze mogą być również umieszczane na końcu wierszy zawierających kod:

Nazwa pliku: src/main.rs

fn main() {
    let lucky_number = 7; // Czuję się dzisiaj szczęściarzem
}

Ale częściej zobaczysz je używane w tym formacie, z komentarzem w osobnej linii powyżej kodu, który opisuje:

Nazwa pliku: src/main.rs

fn main() {
    // Czuję się dzisiaj szczęściarzem
    let lucky_number = 7;
}

Rust ma również inny rodzaj komentarzy, komentarze dokumentacyjne, które omówimy w sekcji „Publikowanie skrzynki na Crates.io” w Rozdziale 14.

Przepływ sterowania

Przepływ sterowania

Możliwość uruchomienia części kodu w zależności od tego, czy warunek jest true, oraz możliwość wielokrotnego uruchamiania części kodu, dopóki warunek jest true, to podstawowe bloki konstrukcyjne w większości języków programowania. Najczęstsze konstrukcje, które pozwalają kontrolować przepływ wykonania kodu Rusta, to wyrażenia if i pętle.

Wyrażenia if

Wyrażenie if pozwala rozgałęziać kod w zależności od warunków. Podajesz warunek, a następnie stwierdzasz: „Jeśli ten warunek jest spełniony, uruchom ten blok kodu. Jeśli warunek nie jest spełniony, nie uruchamiaj tego bloku kodu.”

Utwórz nowy projekt o nazwie branches w katalogu projects, aby zbadać wyrażenie if. W pliku src/main.rs wprowadź następujący kod:

Nazwa pliku: src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("warunek był prawdziwy");
    } else {
        println!("warunek był fałszywy");
    }
}

Wszystkie wyrażenia if zaczynają się od słowa kluczowego if, po którym następuje warunek. W tym przypadku warunek sprawdza, czy zmienna number ma wartość mniejszą niż 5. Blok kodu do wykonania, jeśli warunek jest true, umieszczamy bezpośrednio po warunku w nawiasach klamrowych. Bloki kodu powiązane z warunkami w wyrażeniach if są czasami nazywane ramionami, podobnie jak ramiona w wyrażeniach match, które omówiliśmy w sekcji „Porównywanie zgadywanej liczby z tajną liczbą” w Rozdziale 2.

Opcjonalnie możemy również dołączyć wyrażenie else, co tutaj zrobiliśmy, aby podać programowi alternatywny blok kodu do wykonania, jeśli warunek oceni się na false. Jeśli nie podasz wyrażenia else, a warunek jest false, program po prostu pominie blok if i przejdzie do następnej części kodu.

Spróbuj uruchomić ten kod; powinieneś zobaczyć następujący wynik:

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

Spróbujmy zmienić wartość number na taką, która sprawi, że warunek będzie false, aby zobaczyć, co się stanie:

fn main() {
    let number = 7;

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

Uruchom program ponownie i spójrz na wynik:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
warunek był fałszywy

Warto również zauważyć, że warunek w tym kodzie musi być typu bool. Jeśli warunek nie jest typu bool, otrzymamy błąd. Na przykład, spróbuj uruchomić następujący kod:

Nazwa pliku: src/main.rs

fn main() {
    let number = 3;

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

Warunek if tym razem oblicza się do wartości 3, a Rust zwraca błąd:

$ 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

Błąd wskazuje, że Rust oczekiwał bool, ale otrzymał liczbę całkowitą. W przeciwieństwie do języków takich jak Ruby i JavaScript, Rust nie będzie automatycznie próbował konwertować typów niebędących bool na bool. Musisz być jawny i zawsze dostarczać if z wartością bool jako warunkiem. Jeśli chcemy, aby blok kodu if był uruchamiany tylko wtedy, gdy liczba nie jest równa 0, na przykład, możemy zmienić wyrażenie if na następujące:

Nazwa pliku: src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number było czymś innym niż zero");
    }
}

Uruchomienie tego kodu wypisze number było czymś innym niż zero.

Obsługa wielu warunków za pomocą else if

Możesz użyć wielu warunków, łącząc if i else w wyrażeniu else if. Na przykład:

Nazwa pliku: src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("liczba jest podzielna przez 4");
    } else if number % 3 == 0 {
        println!("liczba jest podzielna przez 3");
    } else if number % 2 == 0 {
        println!("liczba jest podzielna przez 2");
    } else {
        println!("liczba nie jest podzielna przez 4, 3 ani 2");
    }
}

Ten program może podążyć czterema możliwymi ścieżkami. Po jego uruchomieniu powinieneś zobaczyć następujący wynik:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
liczba jest podzielna przez 3

Kiedy ten program się wykonuje, sprawdza kolejno każde wyrażenie if i wykonuje pierwszy blok, dla którego warunek ocenia się na true. Zauważ, że mimo że 6 jest podzielne przez 2, nie widzimy wyjścia liczba jest podzielna przez 2, ani tekstu liczba nie jest podzielna przez 4, 3 ani 2 z bloku else. Dzieje się tak, ponieważ Rust wykonuje blok tylko dla pierwszego warunku true, a gdy tylko znajdzie taki, nie sprawdza już reszty.

Zbyt wiele wyrażeń else if może zaśmiecać kod, więc jeśli masz ich więcej niż jeden, możesz chcieć refaktoryzować swój kod. Rozdział 6 opisuje potężną konstrukcję rozgałęziającą Rusta o nazwie match dla takich przypadków.

Używanie if w instrukcji let

Ponieważ if jest wyrażeniem, możemy go użyć po prawej stronie instrukcji let, aby przypisać wynik do zmiennej, jak w Listingu 3-2.

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

    println!("Wartość liczby to: {number}");
}

Zmienna number zostanie związana z wartością na podstawie wyniku wyrażenia if. Uruchom ten kod, aby zobaczyć, co się stanie:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
Wartość liczby to: 5

Pamiętaj, że bloki kodu oceniają się do ostatniego w nich wyrażenia, a same liczby są również wyrażeniami. W tym przypadku wartość całego wyrażenia if zależy od tego, który blok kodu zostanie wykonany. Oznacza to, że wartości, które potencjalnie mogą być wynikami z każdego ramienia if, muszą być tego samego typu; w Listingu 3-2 wyniki zarówno ramienia if, jak i ramienia else były liczbami całkowitymi i32. Jeśli typy nie pasują do siebie, jak w następującym przykładzie, otrzymamy błąd:

Nazwa pliku: src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "sześć" };

    println!("Wartość liczby to: {number}");
}

Kiedy spróbujemy skompilować ten kod, otrzymamy błąd. Ramiona if i else mają niezgodne typy wartości, a Rust dokładnie wskazuje, gdzie znaleźć problem w programie:

$ 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

Wyrażenie w bloku if oblicza się do liczby całkowitej, a wyrażenie w bloku else oblicza się do ciągu znaków. To nie zadziała, ponieważ zmienne muszą mieć pojedynczy typ, a Rust musi wiedzieć jednoznacznie w czasie kompilacji, jakiego typu jest zmienna number. Znajomość typu number pozwala kompilatorowi sprawdzić, czy typ jest prawidłowy wszędzie tam, gdzie używamy number. Rust nie byłby w stanie tego zrobić, gdyby typ number był określany tylko w czasie działania; kompilator byłby bardziej złożony i dawałby mniej gwarancji co do kodu, gdyby musiał śledzić wiele hipotetycznych typów dla dowolnej zmiennej.

Powtarzanie z pętlami

Często przydatne jest wielokrotne wykonanie bloku kodu. Do tego zadania Rust udostępnia kilka pętli, które będą wykonywać kod wewnątrz ciała pętli do końca, a następnie natychmiast wrócą na początek. Aby poeksperymentować z pętlami, utwórzmy nowy projekt o nazwie loops.

Rust ma trzy rodzaje pętli: loop, while i for. Spróbujmy każdej z nich.

Powtarzanie kodu za pomocą loop

Słowo kluczowe loop mówi Rustowi, aby wykonywał blok kodu w kółko, albo w nieskończoność, albo dopóki jawnie nie powiesz mu, aby się zatrzymał.

Jako przykład, zmień plik src/main.rs w katalogu loops tak, aby wyglądał tak:

Nazwa pliku: src/main.rs

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

Kiedy uruchomimy ten program, będziemy widzieć znowu! wypisywane w kółko nieprzerwanie, dopóki nie zatrzymamy programu ręcznie. Większość terminali obsługuje skrót klawiaturowy ctrl-C do przerwania programu, który utknął w nieustannej pętli. Spróbuj:

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

Symbol ^C reprezentuje miejsce, w którym naciśnąłeś ctrl-C.

Możesz, ale nie musisz, zobaczyć słowo znowu! wypisane po ^C, w zależności od tego, w którym miejscu pętli znajdował się kod, gdy otrzymał sygnał przerwania.

Na szczęście Rust udostępnia również sposób na wyjście z pętli za pomocą kodu. Możesz umieścić słowo kluczowe break w pętli, aby powiedzieć programowi, kiedy ma zakończyć wykonywanie pętli. Przypomnij sobie, że zrobiliśmy to w grze w zgadywanie w sekcji „Zakończenie po poprawnym odgadnięciu” w Rozdziale 2, aby zakończyć program, gdy użytkownik wygrał grę, zgadując poprawną liczbę.

Używaliśmy również continue w grze w zgadywanie, co w pętli mówi programowi, aby pominął pozostały kod w tej iteracji pętli i przeszedł do następnej iteracji.

Zwracanie wartości z pętli

Jednym z zastosowań pętli loop jest ponowne wykonanie operacji, o której wiesz, że może się nie powieść, na przykład sprawdzenie, czy wątek zakończył swoje zadanie. Może być również konieczne przekazanie wyniku tej operacji poza pętlę do reszty kodu. Aby to zrobić, możesz dodać wartość, którą chcesz zwrócić, po wyrażeniu break, którego używasz do zatrzymania pętli; ta wartość zostanie zwrócona z pętli, abyś mógł jej użyć, jak pokazano tutaj:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

    println!("Wynik to {result}");
}

Przed pętlą deklarujemy zmienną counter i inicjalizujemy ją na 0. Następnie deklarujemy zmienną result, aby przechowywała wartość zwróconą z pętli. W każdej iteracji pętli dodajemy 1 do zmiennej counter, a następnie sprawdzamy, czy counter jest równe 10. Gdy tak jest, używamy słowa kluczowego break z wartością counter * 2. Po pętli używamy średnika, aby zakończyć instrukcję, która przypisuje wartość do result. Na koniec wypisujemy wartość w result, która w tym przypadku wynosi 20.

Możesz również return z wnętrza pętli. Podczas gdy break tylko wychodzi z bieżącej pętli, return zawsze wychodzi z bieżącej funkcji.

Rozróżnianie wielu pętli za pomocą etykiet pętli

Jeśli masz pętle zagnieżdżone w innych pętlach, break i continue dotyczą aktualnie najbardziej wewnętrznej pętli. Możesz opcjonalnie określić etykietę pętli dla pętli, którą następnie możesz użyć z break lub continue, aby określić, że te słowa kluczowe dotyczą oznaczonej pętli, a nie najbardziej wewnętrznej. Etykiety pętli muszą zaczynać się od pojedynczego cudzysłowu. Oto przykład z dwoma zagnieżdżonymi pętlami:

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

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

        count += 1;
    }
    println!("Końcowy licznik = {count}");
}

Zewnętrzna pętla ma etykietę 'counting_up i będzie liczyć od 0 do 2. Wewnętrzna pętla bez etykiety liczy od 10 do 9. Pierwszy break, który nie określa etykiety, zakończy tylko wewnętrzną pętlę. Instrukcja break 'counting_up; zakończy zewnętrzną pętlę. Ten kod wypisuje:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
licznik = 0
pozostało = 10
pozostało = 9
licznik = 1
pozostało = 10
pozostało = 9
licznik = 2
pozostało = 10
Końcowy licznik = 2

Upraszczanie pętli warunkowych za pomocą while

Program często musi oceniać warunek wewnątrz pętli. Dopóki warunek jest true, pętla działa. Gdy warunek przestaje być true, program wywołuje break, zatrzymując pętlę. Możliwe jest zaimplementowanie takiego zachowania za pomocą połączenia loop, if, else i break; możesz spróbować tego teraz w programie, jeśli chcesz. Jednak ten wzorzec jest tak powszechny, że Rust ma wbudowaną konstrukcję językową dla niego, zwaną pętlą while. W Listingu 3-3 używamy while, aby zapętlić program trzy razy, odliczając za każdym razem, a następnie, po pętli, wypisać wiadomość i zakończyć działanie.

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

    println!("START!!!");
}

Ta konstrukcja eliminuje wiele zagnieżdżeń, które byłyby konieczne, gdybyś używał loop, if, else i break, i jest bardziej przejrzysta. Dopóki warunek ocenia się na true, kod działa; w przeciwnym razie wychodzi z pętli.

Przeglądanie kolekcji za pomocą for

Możesz użyć konstrukcji while do iteracji po elementach kolekcji, takiej jak tablica. Na przykład, pętla w Listingu 3-4 wypisuje każdy element w tablicy a.

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

    while index < 5 {
        println!("wartość to: {}", a[index]);

        index += 1;
    }
}

Tutaj kod liczy elementy w tablicy. Zaczyna od indeksu 0, a następnie zapętla się, aż osiągnie ostatni indeks w tablicy (czyli, gdy index < 5 przestaje być true). Uruchomienie tego kodu wypisze każdy element w tablicy:

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

Wszystkie pięć wartości tablicy pojawia się w terminalu, zgodnie z oczekiwaniami. Mimo że index osiągnie wartość 5 w pewnym momencie, pętla przestaje się wykonywać przed próbą pobrania szóstej wartości z tablicy.

Jednak to podejście jest podatne na błędy; moglibyśmy spowodować panikę programu, jeśli wartość indeksu lub warunek testowy są niepoprawne. Na przykład, jeśli zmieniłeś definicję tablicy a na cztery elementy, ale zapomniałeś zaktualizować warunek na while index < 4, kod uległby panice. Jest to również wolne, ponieważ kompilator dodaje kod wykonawczy do wykonywania kontroli warunkowej, czy indeks znajduje się w granicach tablicy w każdej iteracji pętli.

Jako bardziej zwięzłą alternatywę, możesz użyć pętli for i wykonać kod dla każdego elementu w kolekcji. Pętla for wygląda jak kod w Listingu 3-5.

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

    for element in a {
        println!("wartość to: {element}");
    }
}

Kiedy uruchomimy ten kod, zobaczymy ten sam wynik co w Listingu 3-4. Co ważniejsze, zwiększyliśmy teraz bezpieczeństwo kodu i wyeliminowaliśmy możliwość błędów, które mogłyby wyniknąć z wyjścia poza koniec tablicy lub niewystarczającego przeszukania i pominięcia niektórych elementów. Kod maszynowy generowany z pętli for może być również bardziej wydajny, ponieważ indeks nie musi być porównywany z długością tablicy w każdej iteracji.

Używając pętli for, nie musiałbyś pamiętać o zmienianiu żadnego innego kodu, gdybyś zmienił liczbę wartości w tablicy, tak jak to miało miejsce w metodzie użytej w Listingu 3-4.

Bezpieczeństwo i zwięzłość pętli for sprawiają, że są one najczęściej używaną konstrukcją pętli w Ruście. Nawet w sytuacjach, gdy chcesz uruchomić jakiś kod określoną liczbę razy, jak w przykładzie odliczania, który używał pętli while w Listingu 3-3, większość Rustaceanów użyłaby pętli for. Sposób na to polegałby na użyciu Range, dostarczanego przez bibliotekę standardową, który generuje wszystkie liczby w sekwencji, zaczynając od jednej liczby i kończąc przed inną liczbą.

Oto jak wyglądałoby odliczanie za pomocą pętli for i innej metody, o której jeszcze nie mówiliśmy, rev, do odwracania zakresu:

Nazwa pliku: src/main.rs

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

Ten kod jest trochę ładniejszy, prawda?

Podsumowanie

Udało się! Dotarłeś do końca obszernego rozdziału: nauczyłeś się o zmiennych, skalarnych i złożonych typach danych, funkcjach, komentarzach, wyrażeniach if i pętlach! Aby poćwiczyć koncepcje omówione w tym rozdziale, spróbuj zbudować programy, aby wykonać następujące zadania:

• Konwertowanie temperatur między stopniami Fahrenheita i Celsjusza.
• Generowanie n-tej liczby Fibonacciego.
• Wypisywanie tekstu kolędy „The Twelve Days of Christmas”, wykorzystując powtórzenia w piosence.

Kiedy będziesz gotowy, przejdziemy do koncepcji w Ruście, która nie występuje powszechnie w innych językach programowania: własności.

Zrozumienie własności

Własność to najbardziej unikalna cecha Rusta i ma głębokie implikacje dla pozostałej części języka. Umożliwia Rustowi gwarantowanie bezpieczeństwa pamięci bez potrzeby zbierania śmieci, dlatego ważne jest zrozumienie, jak działa własność. W tym rozdziale omówimy własność, a także kilka powiązanych funkcji: pożyczanie, wycinki i sposób, w jaki Rust rozmieszcza dane w pamięci.

Czym jest Własność?

Czym jest Własność?

Własność to zbiór zasad, które określają, w jaki sposób program w Rust zarządza pamięcią.Wszystkie programy muszą zarządzać sposobem, w jaki wykorzystują pamięć komputera podczas działania.Niektóre języki mają zbieranie śmieci, które regularnie szuka nieużywanej już pamięcipamięci podczas działania programu; w innych językach programista musi jawnieprzydzielić i zwolnić pamięć. Rust używa trzeciego podejścia: Pamięć jest zarządzanaprzez system własności z zestawem zasad, które kompilator sprawdza. Jeśliktórakolwiek z zasad zostanie naruszona, program się nie skompiluje. Żadna z funkcjiwłasności nie spowolni programu podczas jego działania.

Ponieważ własność jest nową koncepcją dla wielu programistów, przyzwyczajenie się do niej zajmuje trochę czasu.Dobrą wiadomością jest to, że im bardziej doświadczony będziesz w Rusti zasadach systemu własności, tym łatwiej będzie ci naturalnierozwinąć kod, który jest bezpieczny i wydajny. Trzymaj tak dalej!

Kiedy zrozumiesz własność, będziesz mieć solidne podstawy do zrozumieniafunkcji, które sprawiają, że Rust jest unikalny. W tym rozdziale poznasz własność,pracując nad przykładami, które koncentrują się na bardzo popularnej strukturze danych:ciągach znaków.

Stos i sterta

Wiele języków programowania nie wymaga od ciebie zbyt częstego myślenia o stosie i stercie.Ale w języku programowania systemowego, takim jak Rust, to, czy wartość znajduje się na stosie, czy na stercie,wpływa na zachowanie języka i na to, dlaczego musisz podejmować pewne decyzje.Części własności zostaną opisane w odniesieniu do stosu i stertyw dalszej części tego rozdziału, więc oto krótkie wyjaśnienie w przygotowaniu.

Zarówno stos, jak i sterta są częściami pamięci dostępnymi dla twojego kodu do użyciaw czasie wykonywania, ale są one strukturalizowane w różny sposób. Stos przechowuje wartościw kolejności, w jakiej je otrzymuje, i usuwa wartości w odwrotnej kolejności.Jest to określane jako ostatnie weszło, pierwsze wyszło (LIFO). Pomyśl o stosietalerzy: Kiedy dodajesz więcej talerzy, kładziesz je na wierzchu stosu, a kiedypotrzebujesz talerza, bierzesz jeden z góry. Dodawanie lub usuwanie talerzy ze środka lub z dołu nie działałoby tak dobrze!Dodawanie danych nazywa się wkładaniem na stos, a usuwanie danych nazywa się zdejmowaniem ze stosu.Wszystkie dane przechowywane na stosie muszą mieć znaną, stałą wielkość.Dane o nieznanym rozmiarze w czasie kompilacji lub rozmiarze, który może się zmienić, muszą być przechowywanena stercie.

Sterta jest mniej zorganizowana: Kiedy umieszczasz dane na stercie, żądaszwielkości miejsca. Alokator pamięci znajduje wolne miejsce na stercie,które jest wystarczająco duże, oznacza je jako zajęte i zwraca wskaźnik,który jest adresem tej lokalizacji. Ten proces nazywa się _alokacją na stercie_i jest czasami skracany do samego alokowania (wkładanie wartości na stos nie jest uważane za alokację).Ponieważ wskaźnik do sterty ma znaną, stałą wielkość, możesz przechowywać wskaźnik na stosie,ale kiedy chcesz uzyskać rzeczywiste dane, musisz podążać za wskaźnikiem.Pomyśl o tym, jakbyś siedział w restauracji. Kiedy wchodzisz, podajesz liczbęosób w twojej grupie, a host znajduje pusty stół, który pasuje do wszystkich,i prowadzi cię tam. Jeśli ktoś z twojej grupy spóźni się, może zapytać,gdzie zostałeś usadzony, aby cię znaleźć.

Wkładanie na stos jest szybsze niż alokowanie na stercie, ponieważ alokator nigdy nie musi szukaćmiejsca do przechowywania nowych danych; ta lokalizacja zawsze znajduje się na szczycie stosu.W porównaniu, alokacja miejsca na stercie wymaga więcej pracy, ponieważ alokator musinajpierw znaleźć wystarczająco dużo miejsca, aby pomieścić dane, a następnie wykonać księgowość,aby przygotować się do następnej alokacji.

Dostęp do danych na stercie jest zazwyczaj wolniejszy niż dostęp do danych na stosie,ponieważ musisz podążać za wskaźnikiem, aby tam dotrzeć. Współczesne procesorysą szybsze, jeśli mniej skaczą po pamięci. Kontynuując analogię,rozważ kelnera w restauracji przyjmującego zamówienia od wielu stolików.Najbardziej efektywne jest zebranie wszystkich zamówień przy jednym stole, zanim przejdzie się do następnego.Przyjmowanie zamówienia ze stołu A, następnie zamówienia ze stołu B,następnie ponownie z A, a następnie ponownie z B, byłoby znacznie wolniejszym procesem.W ten sam sposób procesor zazwyczaj lepiej wykonuje swoją pracę, jeślidziała na danych, które są blisko innych danych (jak na stosie),a nie dalej (jak może być na stercie).

Kiedy twój kod wywołuje funkcję, wartości przekazane do funkcji(w tym, potencjalnie, wskaźniki do danych na stercie) i zmienne lokalne funkcji sąwkładane na stos. Kiedy funkcja się kończy, te wartości są usuwane ze stosu.

Śledzenie, które części kodu używają jakich danych na stercie,minimalizowanie ilości zduplikowanych danych na stercie i czyszczenie nieużywanychdanych na stercie, aby nie zabrakło miejsca, to problemyczne kwestie,które adresuje system własności. Kiedy zrozumiesz własność,nie będziesz musiał często myśleć o stosie i stercie.Ale wiedząc, że głównym celem własności jest zarządzanie danymi na stercie,może to pomóc wyjaśnić, dlaczego działa to tak, jak działa.

Zasady Własności

Najpierw przyjrzyjmy się zasadom własności. Pamiętaj o nich,gdy będziemy przechodzić przez przykłady, które je ilustrują:

• Każda wartość w Rust ma właściciela.
• W danym momencie może być tylko jeden właściciel.
• Gdy właściciel wyjdzie poza zasięg, wartość zostanie usunięta (dropped).

Zasięg zmiennych

Teraz, gdy podstawowa składnia Rust jest już za nami, nie będziemy zawierać całego kodu fn main() { w przykładach, więc jeśli śledzisz, upewnij się, że umieściłeś poniższe przykłady ręcznie w funkcji main. W rezultacie nasze przykłady będą nieco bardziej zwięzłe, pozwalając nam skupić się na rzeczywistych szczegółach, a nie na kodzie szablonowym.

Jako pierwszy przykład własności, przyjrzymy się zasięgowi niektórych zmiennych. Zasięg to zakres w programie, w którym element jest ważny. Weźmy następującą zmienną:

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

Zmienna s odnosi się do literału ciągu znaków, gdzie wartość ciągu jest zakodowana bezpośrednio w tekście naszego programu. Zmienna jest ważna od momentu jej zadeklarowania do końca bieżącego zasięgu. Listing 4-1 przedstawia program z komentarzami oznaczającymi, gdzie zmienna s byłaby ważna.

fn main() {
    {                      // s jest tutaj nieważne, ponieważ nie zostało jeszcze zadeklarowane
        let s = "hello";   // s jest ważne od tego momentu

        // rób coś z s
    }                      // ten zasięg się skończył, a s jest już nieważne
}

Innymi słowy, są tutaj dwa ważne momenty w czasie:

• Kiedy s wchodzi w zasięg, jest ważne.
• Pozostaje ważne, dopóki nie wyjdzie z zasięgu.

Na tym etapie, związek między zasięgami a ważnością zmiennych jest podobny jak w innych językach programowania. Teraz będziemy budować na tym zrozumieniu, wprowadzając typ String.

Typ String

Aby zilustrować zasady własności, potrzebujemy typu danych, który jest bardziej złożony niż te, które omówiliśmy w sekcji „Typy danych” w Rozdziale 3. Wcześniej omówione typy mają znany rozmiar, mogą być przechowywane na stosie i zdejmowane ze stosu po zakończeniu ich zasięgu, oraz mogą być szybko i trywialnie kopiowane, aby utworzyć nową, niezależną instancję, jeśli inna część kodu musi użyć tej samej wartości w innym zasięgu. Chcemy jednak przyjrzeć się danym przechowywanym na stercie i zbadać, w jaki sposób Rust wie, kiedy te dane posprzątać, a typ String jest doskonałym przykładem.

Skoncentrujemy się na częściach String, które odnoszą się do własności. Te aspekty dotyczą również innych złożonych typów danych, niezależnie od tego, czy są dostarczane przez bibliotekę standardową, czy stworzone przez ciebie. Aspekty String niezwiązane z własnością omówimy w Rozdziale 8.

Widzieliśmy już literały ciągów znaków, gdzie wartość ciągu jest zakodowana na stałe w naszym programie. Literały ciągów znaków są wygodne, ale nie nadają się do każdej sytuacji, w której możemy chcieć użyć tekstu. Jednym z powodów jest to, że są one niezmienne. Inną przyczyną jest to, że nie każda wartość ciągu może być znana, gdy piszemy nasz kod: na przykład, co jeśli chcemy pobrać dane od użytkownika i je zapisać? Właśnie dla takich sytuacji Rust ma typ String. Ten typ zarządza danymi alokowanymi na stercie i jako taki jest w stanie przechowywać ilość tekstu, która jest nam nieznana w czasie kompilacji. Możesz utworzyć String z literału ciągu znaków za pomocą funkcji from, w ten sposób:

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

Operator podwójnego dwukropka :: pozwala nam na umieszczenie funkcji from w przestrzeni nazw typu String, zamiast używać nazwy takiej jak string_from. Więcej o tej składni omówimy w sekcji „Metody” w Rozdziale 5, oraz gdy będziemy mówić o przestrzeniach nazw z modułami w sekcji „Ścieżki do odwoływania się do elementu w drzewie modułów” w Rozdziale 7.

Tego rodzaju ciąg może być mutowalny:

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

    s.push_str(", world!"); // push_str() dodaje literał do String

    println!("{s}"); // to wyświetli `hello, world!`
}

Więc, jaka jest tutaj różnica? Dlaczego String może być mutowalny, a literały nie? Różnica tkwi w sposobie, w jaki te dwa typy obsługują pamięć.

Pamięć i Alokacja

W przypadku literału ciągu znaków, znamy jego zawartość w czasie kompilacji, więc tekst jest zakodowany bezpośrednio w finalnym pliku wykonywalnym. Dlatego literały ciągów znaków są szybkie i wydajne. Ale te właściwości wynikają tylko z niezmienności literału ciągu znaków. Niestety, nie możemy umieścić bloku pamięci w pliku binarnym dla każdego fragmentu tekstu, którego rozmiar jest nieznany w czasie kompilacji i którego rozmiar może zmieniać się podczas działania programu.

Z typem String, aby obsługiwać zmienny, rozszerzalny fragment tekstu, musimy zaalokować na stercie ilość pamięci, nieznaną w czasie kompilacji, aby pomieścić zawartość. Oznacza to:

• Pamięć musi być żądana od alokatora pamięci w czasie wykonywania.
• Potrzebujemy sposobu na zwrócenie tej pamięci alokatorowi, gdy skończymy z naszym String.

Ta pierwsza część jest wykonywana przez nas: Kiedy wywołujemy String::from, jego implementacja żąda potrzebnej pamięci. Jest to dość powszechne w językach programowania.

Jednak druga część jest inna. W językach z garbage collector (GC), GC śledzi i usuwa pamięć, która nie jest już używana, i nie musimy o tym myśleć. W większości języków bez GC, to nasza odpowiedzialność, aby zidentyfikować, kiedy pamięć nie jest już używana i wywołać kod, aby jawnie ją zwolnić, tak jak robiliśmy to, aby ją zażądać. Robienie tego poprawnie było historycznie trudnym problemem programistycznym. Jeśli zapomnimy, zmarnujemy pamięć. Jeśli zrobimy to zbyt wcześnie, będziemy mieć nieprawidłową zmienną. Jeśli zrobimy to dwukrotnie, to też jest błąd. Musimy sparować dokładnie jedną allocate z dokładnie jedną free.

Rust obiera inną ścieżkę: Pamięć jest automatycznie zwracana, gdy zmienna, która ją posiada, wyjdzie poza zasięg. Oto wersja naszego przykładu zasięgu z Listingu 4-1, używająca String zamiast literału ciągu znaków:

fn main() {
    {
        let s = String::from("hello"); // s jest ważne od tego momentu

        // rób coś z s
    }                                  // ten zasięg się skończył, a s jest już
                                       // nieważne
}

Istnieje naturalny moment, w którym możemy zwrócić pamięć potrzebną naszej String alokatorowi: kiedy s wyjdzie poza zasięg. Kiedy zmienna wychodzi poza zasięg, Rust wywołuje dla nas specjalną funkcję. Funkcja ta nazywa się drop i to w niej autor String może umieścić kod do zwracania pamięci. Rust automatycznie wywołuje drop przy zamykającym nawiasie klamrowym.

Uwaga: W C++ ten wzorzec dealokowania zasobów na końcu życia elementu jest czasami nazywany Resource Acquisition Is Initialization (RAII). Funkcja drop w Rust będzie ci znana, jeśli używałeś wzorców RAII.

Ten wzorzec ma głęboki wpływ na sposób pisania kodu w Rust. Może wydawać się prosty teraz, ale zachowanie kodu może być nieoczekiwane w bardziej skomplikowanych sytuacjach, gdy chcemy, aby wiele zmiennych używało danych, które zaalokowaliśmy na stercie. Przyjrzyjmy się teraz kilku z tych sytuacji.

Zmienne i Dane w Interakcji przez Przeniesienie (Move)

W Rust wiele zmiennych może wchodzić w interakcję z tymi samymi danymi na różne sposoby. Listing 4-2 przedstawia przykład użycia liczby całkowitej.

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

Prawdopodobnie możemy zgadnąć, co to robi: „Przypisz wartość 5 do x; następnie, utwórz kopię wartości z x i przypisz ją do y.” Mamy teraz dwie zmienne, x i y, i obie są równe 5. Tak właśnie się dzieje, ponieważ liczby całkowite są prostymi wartościami o znanym, stałym rozmiarze, a te dwie wartości 5 są umieszczane na stosie.

Teraz przyjrzyjmy się wersji String:

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

Wygląda to bardzo podobnie, więc moglibyśmy założyć, że działałoby tak samo: to znaczy, że druga linia utworzyłaby kopię wartości z s1 i przypisała ją do s2. Ale tak się nie dzieje.

Przyjrzyj się Rysunkowi 4-1, aby zobaczyć, co dzieje się z String pod maską. String składa się z trzech części, pokazanych po lewej stronie: wskaźnika do pamięci, która przechowuje zawartość ciągu, długości i pojemności. Ta grupa danych jest przechowywana na stosie. Po prawej stronie znajduje się pamięć na stercie, która przechowuje zawartość.

Rysunek 4-1: Reprezentacja w pamięci String zawierającego wartość "hello" przypisaną do s1

Długość to ilość pamięci, w bajtach, którą aktualnie wykorzystuje zawartość String. Pojemność to całkowita ilość pamięci, w bajtach, którą String otrzymał od alokatora. Różnica między długością a pojemnością ma znaczenie, ale nie w tym kontekście, więc na razie można ją zignorować.

Kiedy przypisujemy s1 do s2, dane String są kopiowane, co oznacza, że kopiujemy wskaźnik, długość i pojemność, które znajdują się na stosie. Nie kopiujemy danych na stercie, do których odwołuje się wskaźnik. Innymi słowy, reprezentacja danych w pamięci wygląda jak na Rysunku 4-2.

Rysunek 4-2: Reprezentacja w pamięci zmiennej s2, która zawiera kopię wskaźnika, długości i pojemności s1

Reprezentacja nie wygląda jak na Rysunku 4-3, który przedstawiałby pamięć, gdyby Rust zamiast tego skopiował również dane na stercie. Gdyby Rust tak zrobił, operacja s2 = s1 mogłaby być bardzo kosztowna pod względem wydajności, gdyby dane na stercie były duże.

Rysunek 4-3: Inna możliwość tego, co s2 = s1 mógłby zrobić, gdyby Rust skopiował również dane ze sterty

Wcześniej powiedzieliśmy, że gdy zmienna wychodzi poza zasięg, Rust automatycznie wywołuje funkcję drop i zwalnia pamięć sterty dla tej zmiennej. Ale Rysunek 4-2 pokazuje, że oba wskaźniki danych wskazują na tę samą lokalizację. To jest problem: kiedy s2 i s1 wyjdą poza zasięg, oba będą próbowały zwolnić tę samą pamięć. Jest to znane jako błąd podwójnego zwolnienia (double free) i jest jednym z błędów bezpieczeństwa pamięci, o których wspomnieliśmy wcześniej. Dwukrotne zwolnienie pamięci może prowadzić do uszkodzenia pamięci, co potencjalnie może prowadzić do luk w zabezpieczeniach.

Aby zapewnić bezpieczeństwo pamięci, po linii let s2 = s1;, Rust uważa s1 za już nieprawidłowe. Dlatego Rust nie musi zwalniać niczego, gdy s1 wychodzi poza zasięg. Sprawdź, co się stanie, gdy spróbujesz użyć s1 po utworzeniu s2; to nie zadziała:

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

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

Otrzymasz błąd podobny do tego, ponieważ Rust uniemożliwia użycie unieważnionej referencji:

$ 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

Jeśli słyszałeś o pojęciach płytka kopia i głęboka kopia pracując z innymi językami, koncepcja kopiowania wskaźnika, długości i pojemności bez kopiowania danych prawdopodobnie brzmi jak tworzenie płytkiej kopii. Ale ponieważ Rust również unieważnia pierwszą zmienną, zamiast nazywać to płytką kopią, nazywa się to przeniesieniem. W tym przykładzie powiedzielibyśmy, że s1 zostało przeniesione do s2. Zatem to, co faktycznie się dzieje, pokazano na Rysunku 4-4.

Rysunek 4-4: Reprezentacja w pamięci po unieważnieniu s1

To rozwiązuje nasz problem! Gdy tylko s2 jest ważne, gdy wyjdzie ono poza zasięg, samo zwolni pamięć, i gotowe.

Dodatkowo, istnieje wynikająca z tego decyzja projektowa: Rust nigdy nie stworzy automatycznie „głębokich” kopii twoich danych. Dlatego wszelkie automatyczne kopiowanie można uznać za tanie pod względem wydajności czasu wykonania.

Zasięg i przypisanie

Odwrotność tego jest również prawdziwa dla związku między zasięgiem, własnością i zwalnianiem pamięci za pomocą funkcji drop. Kiedy przypisujesz całkowicie nową wartość do istniejącej zmiennej, Rust natychmiast wywoła drop i zwolni pamięć oryginalnej wartości. Rozważmy na przykład ten kod:

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

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

Początkowo deklarujemy zmienną s i wiążemy ją z String o wartości "hello". Następnie, natychmiast tworzymy nowy String o wartości "ahoy" i przypisujemy go do s. W tym momencie nic nie odnosi się do oryginalnej wartości na stercie. Rysunek 4-5 ilustruje teraz dane stosu i sterty:

Rysunek 4-5: Reprezentacja w pamięci po całkowitym zastąpieniu wartości początkowej

Oryginalny ciąg znaków natychmiast wychodzi więc poza zasięg. Rust uruchomi na nim funkcję drop i jego pamięć zostanie natychmiast zwolniona. Kiedy na końcu wydrukujemy wartość, będzie ona wynosić „ahoy, world!”.

Zmienne i Dane w Interakcji przez Klonowanie (Clone)

Jeśli chcemy głęboko skopiować dane String ze sterty, a nie tylko dane ze stosu, możemy użyć wspólnej metody clone. Składnię metod omówimy w Rozdziale 5, ale ponieważ metody są wspólną cechą wielu języków programowania, prawdopodobnie widziałeś je już wcześniej.

Oto przykład metody clone w działaniu:

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

    println!("s1 = {s1}, s2 = {s2}");
}

To działa bez problemów i wyraźnie tworzy zachowanie pokazane na Rysunku 4-3, gdzie dane na stercie są kopiowane.

Kiedy widzisz wywołanie clone, wiesz, że wykonywany jest jakiś dowolny kod i że ten kod może być kosztowny. To wizualny wskaźnik, że dzieje się coś innego.

Dane tylko na stosie: Kopia

Jest jeszcze jedna kwestia, o której jeszcze nie mówiliśmy. Ten kod używający liczb całkowitych — część z nich pokazana w Listingu 4-2 — działa i jest prawidłowy:

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

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

Ale ten kod wydaje się zaprzeczać temu, czego się właśnie nauczyliśmy: Nie mamy wywołania clone, ale x jest nadal ważne i nie zostało przeniesione do y.

Powodem jest to, że typy takie jak liczby całkowite, które mają znany rozmiar w czasie kompilacji, są przechowywane w całości na stosie, więc kopie rzeczywistych wartości są szybkie do wykonania. Oznacza to, że nie ma powodu, dla którego chcielibyśmy uniemożliwić x bycie ważnym po utworzeniu zmiennej y. Innymi słowy, nie ma tutaj różnicy między kopiowaniem głębokim a płytkim, więc wywołanie clone nie zrobiłoby nic innego niż zwykłe kopiowanie płytkie, i możemy to pominąć.

Rust posiada specjalną adnotację zwaną cechą Copy, którą możemy umieszczać na typach przechowywanych na stosie, tak jak to jest w przypadku liczb całkowitych (więcej o cechach omówimy w Rozdziale 10). Jeśli typ implementuje cechę Copy, zmienne, które jej używają, nie są przenoszone, lecz są trywialnie kopiowane, co sprawia, że pozostają ważne po przypisaniu do innej zmiennej.

Rust nie pozwoli nam zaadnotować typu jako Copy, jeśli typ, lub którakolwiek z jego części, zaimplementował cechę Drop. Jeśli typ potrzebuje, aby coś specjalnego się stało, gdy wartość wyjdzie poza zasięg, a my dodamy adnotację Copy do tego typu, otrzymamy błąd kompilacji. Aby dowiedzieć się, jak dodać adnotację Copy do swojego typu w celu zaimplementowania cechy, zobacz „Cechy pochodne” w Dodatku C.

Więc, jakie typy implementują cechę Copy? Aby być pewnym, możesz sprawdzić dokumentację dla danego typu, ale ogólnie rzecz biorąc, każda grupa prostych wartości skalarnych może implementować Copy, a nic, co wymaga alokacji lub jest jakąś formą zasobu, nie może implementować Copy. Oto niektóre typy, które implementują Copy:

• Wszystkie typy całkowite, takie jak u32.
• Typ boolowski, bool, z wartościami true i false.
• Wszystkie typy zmiennoprzecinkowe, takie jak f64.
• Typ znakowy, char.
• Krotki, jeśli zawierają tylko typy, które również implementują Copy. Na przykład (i32, i32) implementuje Copy, ale (i32, String) nie.

Własność i Funkcje

Mechanizmy przekazywania wartości do funkcji są podobne do tych, które występują przy przypisywaniu wartości do zmiennej. Przekazanie zmiennej do funkcji spowoduje przeniesienie lub skopiowanie, tak jak przypisanie. Listing 4-3 zawiera przykład z adnotacjami pokazującymi, gdzie zmienne wchodzą w zasięg i wychodzą z niego.

fn main() {
    let s = String::from("hello");  // s wchodzi w zasięg

    takes_ownership(s);             // wartość s przenosi się do funkcji...
                                    // ... i dlatego jest tutaj nieważna

    let x = 5;                      // x wchodzi w zasięg

    makes_copy(x);                  // Ponieważ i32 implementuje cechę Copy,
                                    // x NIE przenosi się do funkcji,
                                    // więc można używać x później.

} // Tutaj x wychodzi z zasięgu, potem s. Jednakże, ponieważ wartość s została przeniesiona,
  // nic specjalnego się nie dzieje.

fn takes_ownership(some_string: String) { // some_string wchodzi w zasięg
    println!("{some_string}");
} // Tutaj some_string wychodzi z zasięgu i wywoływane jest `drop`. Pamięć bazowa
  // jest zwalniana.

fn makes_copy(some_integer: i32) { // some_integer wchodzi w zasięg
    println!("{some_integer}");
} // Tutaj some_integer wychodzi z zasięgu. Nic specjalnego się nie dzieje.

Jeśli spróbowalibyśmy użyć s po wywołaniu takes_ownership, Rust wyrzuciłby błąd kompilacji. Te statyczne sprawdzenia chronią nas przed błędami. Spróbuj dodać kod do main, który używa s i x, aby zobaczyć, gdzie można ich używać, a gdzie zasady własności uniemożliwiają to.

Wartości zwracane i zasięg

Zwracanie wartości może również przenosić własność. Listing 4-4 przedstawia przykład funkcji, która zwraca pewną wartość, z podobnymi adnotacjami jak te z Listingu 4-3.

fn main() {
    let s1 = gives_ownership();        // gives_ownership przenosi swoją wartość
                                       // zwracaną do s1

    let s2 = String::from("hello");    // s2 wchodzi w zasięg

    let s3 = takes_and_gives_back(s2); // s2 jest przenoszone do
                                       // takes_and_gives_back, które również
                                       // przenosi swoją wartość zwracaną do s3
} // Tutaj s3 wychodzi z zasięgu i jest usuwane. s2 zostało przeniesione, więc nic
  // się nie dzieje. s1 wychodzi z zasięgu i jest usuwane.

fn gives_ownership() -> String {       // gives_ownership przeniesie swoją
                                       // wartość zwracaną do funkcji,
                                       // która ją wywoła

    let some_string = String::from("yours"); // some_string wchodzi w zasięg

    some_string                        // some_string jest zwracane i
                                       // przenosi się do funkcji
                                       // wywołującej
}

// Ta funkcja przyjmuje String i zwraca String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string wchodzi w
    // zasięg

    a_string  // a_string jest zwracane i przenosi się do funkcji wywołującej
}

Własność zmiennej zawsze podlega temu samemu wzorcowi: przypisanie wartości do innej zmiennej powoduje jej przeniesienie. Gdy zmienna zawierająca dane na stercie wyjdzie poza zasięg, wartość zostanie posprzątana przez drop, chyba że własność danych została przeniesiona do innej zmiennej.

Chociaż to działa, przejmowanie własności, a następnie zwracanie własności przy każdej funkcji jest trochę męczące. Co, jeśli chcemy pozwolić funkcji użyć wartości, ale nie przejmować własności? Jest to dość denerwujące, że wszystko, co przekazujemy, musi być również zwrócone, jeśli chcemy użyć tego ponownie, oprócz wszelkich danych wynikających z treści funkcji, które również możemy chcieć zwrócić.

Rust pozwala nam zwracać wiele wartości za pomocą krotki, jak pokazano w Listingu 4-5.

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

    let (s2, len) = calculate_length(s1);

    println!("Długość '{s2}' wynosi {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() zwraca długość String

    (s, length)
}

Ale to zbyt wiele ceremonii i dużo pracy dla koncepcji, która powinna być powszechna. Na szczęście Rust ma funkcję do używania wartości bez przenoszenia własności: referencje.

Referencje i Pożyczanie

Referencje i Pożyczanie

Problem z kodem krotki w Listingu 4-5 polega na tym, że musimy zwrócić String do funkcji wywołującej, abyśmy mogli nadal używać String po wywołaniu calculate_length, ponieważ String zostało przeniesione do calculate_length. Zamiast tego możemy dostarczyć referencję do wartości String. Referencja jest jak wskaźnik w tym sensie, że jest to adres, za którym możemy podążać, aby uzyskać dostęp do danych przechowywanych pod tym adresem; te dane są własnością innej zmiennej. W przeciwieństwie do wskaźnika, referencja gwarantuje, że wskazuje na ważną wartość określonego typu przez cały okres życia tej referencji.

Oto jak zdefiniować i użyć funkcji calculate_length, która jako parametr przyjmuje referencję do obiektu zamiast przejmować własność wartości:

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

    let len = calculate_length(&s1);

    println!("Długość '{s1}' wynosi {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

Po pierwsze, zauważ, że cały kod krotki w deklaracji zmiennej i wartości zwracanej funkcji zniknął. Po drugie, zauważ, że przekazujemy &s1 do calculate_length i, w jej definicji, przyjmujemy &String zamiast String. Te ampersandy reprezentują referencje i pozwalają odwoływać się do pewnej wartości bez przejmowania jej własności. Rysunek 4-6 przedstawia tę koncepcję.

Rysunek 4-6: Diagram &String s wskazującego na String s1

Uwaga: Przeciwieństwem referencji za pomocą & jest dereferencjowanie, które jest realizowane za pomocą operatora dereferencji, *. Zobaczymy kilka zastosowań operatora dereferencji w Rozdziale 8 i omówimy szczegóły dereferencji w Rozdziale 15.

Przyjrzyjmy się bliżej wywołaniu funkcji:

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

    let len = calculate_length(&s1);

    println!("Długość '{s1}' wynosi {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

Składnia &s1 pozwala nam utworzyć referencję, która odnosi się do wartości s1, ale jej nie posiada. Ponieważ referencja nie jest jej właścicielem, wartość, na którą wskazuje, nie zostanie usunięta, gdy referencja przestanie być używana.

Podobnie, sygnatura funkcji używa & do wskazania, że typ parametru s jest referencją. Dodajmy kilka wyjaśniających adnotacji:

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

    let len = calculate_length(&s1);

    println!("Długość '{s1}' wynosi {len}.");
}

fn calculate_length(s: &String) -> usize { // s jest referencją do String
    s.len()
} // Tutaj s wychodzi z zasięgu. Ale ponieważ s nie posiada własności tego,
  // do czego się odnosi, String nie jest usuwane.

Zasięg, w którym zmienna s jest ważna, jest taki sam jak zasięg każdego parametru funkcji, ale wartość wskazywana przez referencję nie jest usuwana, gdy s przestaje być używane, ponieważ s nie posiada własności. Gdy funkcje mają referencje jako parametry zamiast rzeczywistych wartości, nie będziemy musieli zwracać wartości, aby oddać własność, ponieważ nigdy jej nie posiadaliśmy.

Nazywamy czynność tworzenia referencji pożyczaniem. Jak w prawdziwym życiu, jeśli ktoś posiada coś, możesz to od niego pożyczyć. Kiedy skończysz, musisz to zwrócić. Nie jesteś jego właścicielem.

Więc co się stanie, jeśli spróbujemy zmodyfikować coś, co pożyczamy? Wypróbuj kod z Listingu 4-6. Uwaga, spoiler: To nie działa!

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

    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

Oto błąd:

$ 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

Tak jak zmienne są domyślnie niezmienne, tak samo referencje. Nie wolno nam modyfikować czegoś, do czego mamy referencję.

Mutowalne referencje

Możemy naprawić kod z Listingu 4-6, aby umożliwić modyfikację pożyczonej wartości za pomocą kilku drobnych zmian, które zamiast tego używają mutowalnej referencji:

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

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

Najpierw zmieniamy s na mut. Następnie tworzymy mutowalną referencję za pomocą &mut s w miejscu wywołania funkcji change i aktualizujemy sygnaturę funkcji, aby akceptowała mutowalną referencję za pomocą some_string: &mut String. Dzięki temu bardzo jasno wynika, że funkcja change będzie mutować pożyczoną wartość.

Mutowalne referencje mają jedno duże ograniczenie: jeśli masz mutowalną referencję do wartości, nie możesz mieć żadnych innych referencji do tej wartości. Ten kod, który próbuje utworzyć dwie mutowalne referencje do s, zakończy się niepowodzeniem:

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

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{r1}, {r2}");
}

Oto błąd:

$ 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

Ten błąd mówi, że ten kod jest nieprawidłowy, ponieważ nie możemy pożyczyć s jako mutowalne więcej niż raz w tym samym czasie. Pierwsze mutowalne pożyczenie następuje w r1 i musi trwać, dopóki nie zostanie użyte w println!, ale między utworzeniem tej mutowalnej referencji a jej użyciem próbowaliśmy utworzyć kolejną mutowalną referencję w r2, która pożycza te same dane co r1.

Ograniczenie zapobiegające równoczesnemu posiadaniu wielu mutowalnych referencji do tych samych danych pozwala na mutację, ale w bardzo kontrolowany sposób. Jest to coś, z czym borykają się nowi Rustaceanowie, ponieważ większość języków pozwala mutować, kiedy tylko chcesz. Korzyścią z tego ograniczenia jest to, że Rust może zapobiegać wyścigom danych w czasie kompilacji. Wyścig danych jest podobny do warunku wyścigu i występuje, gdy zachodzą te trzy zachowania:

• Dwa lub więcej wskaźników uzyskuje dostęp do tych samych danych w tym samym czasie.
• Co najmniej jeden ze wskaźników jest używany do zapisu danych.
• Nie ma mechanizmu synchronizującego dostęp do danych.

Wyścigi danych powodują niezdefiniowane zachowanie i mogą być trudne do zdiagnozowania i naprawienia, gdy próbujesz je śledzić w czasie wykonania; Rust zapobiega temu problemowi, odmawiając kompilacji kodu z wyścigami danych!

Jak zawsze, możemy użyć nawiasów klamrowych do stworzenia nowego zasięgu, co pozwala na wiele mutowalnych referencji, ale nie jednoczesnych:

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

    {
        let r1 = &mut s;
    } // r1 wychodzi z zasięgu tutaj, więc możemy stworzyć nową referencję bez problemów.

    let r2 = &mut s;
}

Rust narzuca podobną zasadę dla łączenia mutowalnych i niemutowalnych referencji. Ten kod powoduje błąd:

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

    let r1 = &s; // bez problemu
    let r2 = &s; // bez problemu
    let r3 = &mut s; // DUŻY PROBLEM

    println!("{r1}, {r2}, and {r3}");
}

Oto błąd:

$ 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

Uff! Nie możemy również mieć mutowalnej referencji, gdy mamy niezmienną referencję do tej samej wartości.

Użytkownicy referencji niezmiennej nie spodziewają się, że wartość nagle się zmieni! Jednakże, wiele referencji niezmiennych jest dozwolonych, ponieważ nikt, kto tylko odczytuje dane, nie ma możliwości wpływania na odczytywanie danych przez nikogo innego.

Zauważ, że zasięg referencji rozpoczyna się w miejscu jej wprowadzenia i trwa do ostatniego użycia tej referencji. Na przykład, ten kod skompiluje się, ponieważ ostatnie użycie referencji niezmiennych jest w println!, zanim zostanie wprowadzona referencja mutowalna:

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

    let r1 = &s; // bez problemu
    let r2 = &s; // bez problemu
    println!("{r1} i {r2}");
    // Zmienne r1 i r2 nie będą używane po tym punkcie.

    let r3 = &mut s; // bez problemu
    println!("{r3}");
}

Zasięgi niezmiennych referencji r1 i r2 kończą się po println!, gdzie są ostatnio używane, co następuje przed utworzeniem mutowalnej referencji r3. Te zasięgi nie nakładają się, więc ten kod jest dozwolony: kompilator może stwierdzić, że referencja nie jest już używana w punkcie przed końcem zasięgu.

Chociaż błędy pożyczania mogą czasem frustrować, pamiętaj, że to kompilator Rust wskazuje potencjalny błąd wcześnie (w czasie kompilacji, a nie w czasie wykonania) i pokazuje dokładnie, gdzie leży problem. Wtedy nie musisz szukać przyczyny, dla której twoje dane nie są tym, czego się spodziewałeś.

Zwisające referencje

W językach ze wskaźnikami łatwo jest błędnie utworzyć zwisający wskaźnik — wskaźnik, który odwołuje się do miejsca w pamięci, które mogło zostać przekazane komuś innemu — zwalniając część pamięci, jednocześnie zachowując wskaźnik do tej pamięci. W Rust, natomiast, kompilator gwarantuje, że referencje nigdy nie będą zwisającymi referencjami: jeśli masz referencję do jakichś danych, kompilator zapewni, że dane te nie wyjdą poza zasięg przed referencją do nich.

Spróbujmy utworzyć zwisającą referencję, aby zobaczyć, jak Rust im zapobiega, sygnalizując błąd kompilacji:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String {
    let s = String::from("hello");

    &s
}

Oto błąd:

$ 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

Ten komunikat o błędzie odnosi się do funkcji, której jeszcze nie omówiliśmy: czasów życia. Szczegółowo omówimy czasy życia w Rozdziale 10. Ale jeśli zignorujesz części dotyczące czasów życia, komunikat zawiera klucz do tego, dlaczego ten kod jest problemem:

typ zwracany przez tę funkcję zawiera wartość pożyczoną, ale nie ma wartości,
z której można ją pożyczyć

Przyjrzyjmy się bliżej, co dokładnie dzieje się na każdym etapie naszego kodu dangle:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle zwraca referencję do String

    let s = String::from("hello"); // s to nowy String

    &s // zwracamy referencję do String, s
} // Tutaj s wychodzi z zasięgu i jest usuwane, więc jego pamięć znika.
  // Niebezpieczeństwo!

Ponieważ s jest tworzone wewnątrz dangle, kiedy kod dangle się zakończy, s zostanie dealokowane. Ale próbowaliśmy zwrócić do niego referencję. Oznacza to, że ta referencja wskazywałaby na nieprawidłowy String. To niedobrze! Rust nam na to nie pozwoli.

Rozwiązaniem jest bezpośrednie zwrócenie String:

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

To działa bez problemów. Własność zostaje przeniesiona, a nic nie jest dealokowane.

Zasady referencji

Podsumujmy, co omówiliśmy na temat referencji:

• W dowolnym momencie możesz mieć albo jedną mutowalną referencję albo dowolną liczbę niemutowalnych referencji.
• Referencje muszą być zawsze ważne.

Następnie przyjrzymy się innemu rodzajowi referencji: wycinkom (slices).

Typ Wycinak (Slice)

Typ Wycinak (Slice)

Wycinki (Slices) pozwalają odwoływać się do ciągłej sekwencji elementów w kolekcji. Wycinek jest rodzajem referencji, więc nie posiada własności.

Oto mały problem programistyczny: Napisz funkcję, która przyjmuje ciąg słów oddzielonych spacjami i zwraca pierwsze słowo, które znajdzie w tym ciągu. Jeśli funkcja nie znajdzie spacji w ciągu, cały ciąg musi być jednym słowem, więc powinien zostać zwrócony cały ciąg.

Uwaga: Dla celów wprowadzenia wycinków, w tej sekcji zakładamy tylko ASCII; bardziej szczegółowe omówienie obsługi UTF-8 znajduje się w sekcji „Przechowywanie tekstu kodowanego w UTF-8 za pomocą ciągów znaków” w Rozdziale 8.

Przyjrzyjmy się, jak napisalibyśmy sygnaturę tej funkcji bez użycia wycinków, aby zrozumieć problem, który wycinki rozwiążą:

fn first_word(s: &String) -> ?

Funkcja first_word ma parametr typu &String. Nie potrzebujemy własności, więc to jest w porządku. (W idiomatycznym Rust, funkcje nie przejmują własności swoich argumentów, chyba że jest to konieczne, a powody tego staną się jasne, gdy będziemy kontynuować.) Ale co powinniśmy zwrócić? Nie mamy tak naprawdę sposobu, aby mówić o części ciągu. Jednak moglibyśmy zwrócić indeks końca słowa, wskazany przez spację. Spróbujmy tego, jak pokazano w Listingu 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() {}

Ponieważ musimy przejść przez String element po elemencie i sprawdzić, czy wartość jest spacją, przekształcimy nasz String w tablicę bajtów za pomocą metody 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() {}

Następnie, tworzymy iterator po tablicy bajtów używając metody 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() {}

Iteratory omówimy bardziej szczegółowo w Rozdziale 13. Na razie wystarczy wiedzieć, że iter to metoda, która zwraca każdy element w kolekcji, a enumerate opakowuje wynik iter i zwraca każdy element jako część krotki. Pierwszy element krotki zwróconej z enumerate to indeks, a drugi element to referencja do elementu. Jest to nieco wygodniejsze niż samodzielne obliczanie indeksu.

Ponieważ metoda enumerate zwraca krotkę, możemy użyć wzorców do dekonstrukcji tej krotki. Więcej o wzorcach omówimy w Rozdziale 6. W pętli for określamy wzorzec, który ma i dla indeksu w krotce i &item dla pojedynczego bajtu w krotce. Ponieważ otrzymujemy referencję do elementu z .iter().enumerate(), używamy & we wzorcu.

Wewnątrz pętli for szukamy bajtu reprezentującego spację, używając składni literału bajtowego. Jeśli znajdziemy spację, zwracamy pozycję. W przeciwnym razie zwracamy długość ciągu, używając 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() {}

Mamy teraz sposób na znalezienie indeksu końca pierwszego słowa w ciągu, ale jest problem. Zwracamy samo usize, ale jest to znacząca liczba tylko w kontekście &String. Innymi słowy, ponieważ jest to oddzielna wartość od String, nie ma gwarancji, że będzie ona nadal ważna w przyszłości. Rozważ program z Listingu 4-8, który używa funkcji first_word z Listingu 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 otrzyma wartość 5

    s.clear(); // to opróżnia String, sprawiając, że staje się równy ""

    // word nadal ma wartość 5 tutaj, ale s nie ma już żadnej zawartości, której moglibyśmy
    // sensownie użyć z wartością 5, więc word jest teraz całkowicie nieważne!
}

Ten program kompiluje się bez żadnych błędów i skompilowałby się również, gdybyśmy użyli word po wywołaniu s.clear(). Ponieważ word w żaden sposób nie jest powiązane ze stanem s, word nadal zawiera wartość 5. Moglibyśmy użyć tej wartości 5 ze zmienną s, aby spróbować wyodrębnić pierwsze słowo, ale byłby to błąd, ponieważ zawartość s zmieniła się, odkąd zapisaliśmy 5 w word.

Martwienie się o to, że indeks w word przestaje być zsynchronizowany z danymi w s, jest uciążliwe i podatne na błędy! Zarządzanie tymi indeksami jest jeszcze bardziej kruche, jeśli napiszemy funkcję second_word. Jej sygnatura musiałaby wyglądać tak:

fn second_word(s: &String) -> (usize, usize) {

Teraz śledzimy indeks początkowy i końcowy, i mamy jeszcze więcej wartości, które zostały obliczone na podstawie danych w określonym stanie, ale w ogóle nie są z tym stanem powiązane. Mamy trzy niepowiązane zmienne, które muszą być zsynchronizowane.

Na szczęście Rust ma rozwiązanie tego problemu: wycinki ciągów znaków (string slices).

Wycinki ciągów znaków (String Slices)

Wycinek ciągu znaków to referencja do ciągłej sekwencji elementów String i wygląda tak:

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

    let hello = &s[0..5];
    let world = &s[6..11];
}

Zamiast referencji do całego String, hello jest referencją do fragmentu String, określonego dodatkowym fragmentem [0..5]. Wycinki tworzymy za pomocą zakresu w nawiasach kwadratowych, określając [indeks_początkowy..indeks_końcowy], gdzie indeks_początkowy to pierwsza pozycja w wycinku, a indeks_końcowy to jeden więcej niż ostatnia pozycja w wycinku. Wewnętrznie struktura danych wycinka przechowuje pozycję początkową i długość wycinka, co odpowiada indeks_końcowy minus indeks_początkowy. Zatem w przypadku let world = &s[6..11];, world byłby wycinkiem, który zawiera wskaźnik do bajtu o indeksie 6 w s z wartością długości 5.

Rysunek 4-7 przedstawia to na diagramie.

Rysunek 4-7: Wycinek ciągu znaków odnoszący się do części String

Dzięki składni zakresu .. w Rust, jeśli chcesz zacząć od indeksu 0, możesz pominąć wartość przed dwoma kropkami. Innymi słowy, te są równoważne:

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

let slice = &s[0..2];
let slice = &s[..2];
}

Analogicznie, jeśli twój wycinek zawiera ostatni bajt String, możesz pominąć końcową liczbę. Oznacza to, że te są równoważne:

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

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

Możesz również pominąć obie wartości, aby utworzyć wycinek całego ciągu. W ten sposób te są równoważne:

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

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

Uwaga: Indeksy zakresu wycinka ciągu muszą występować na prawidłowych granicach znaków UTF-8. Jeśli spróbujesz utworzyć wycinek ciągu w środku znaku wielobajtowego, program zakończy się błędem.

Mając na uwadze wszystkie te informacje, przepiszmy first_word, aby zwracało wycinek. Typ, który oznacza „wycinek ciągu znaków”, jest zapisywany jako &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() {}

Indeks końca słowa uzyskujemy w ten sam sposób, jak w Listingu 4-7, szukając pierwszego wystąpienia spacji. Gdy znajdziemy spację, zwracamy wycinek ciągu, używając początku ciągu i indeksu spacji jako indeksów początkowego i końcowego.

Teraz, gdy wywołujemy first_word, otrzymujemy jedną wartość, która jest powiązana z danymi podstawowymi. Wartość ta składa się z referencji do punktu początkowego wycinka i liczby elementów w wycinku.

Zwracanie wycinka działałoby również dla funkcji second_word:

fn second_word(s: &String) -> &str {

Mamy teraz prosty interfejs API, który jest znacznie trudniejszy do popsucia, ponieważ kompilator zapewni, że referencje do String pozostaną ważne. Pamiętasz błąd w programie z Listingu 4-8, kiedy uzyskaliśmy indeks końca pierwszego słowa, ale potem wyczyściliśmy ciąg, więc nasz indeks był nieprawidłowy? Ten kod był logicznie niepoprawny, ale nie wykazywał żadnych natychmiastowych błędów. Problemy pojawiłyby się później, gdybyśmy nadal próbowali używać indeksu pierwszego słowa z opróżnionym ciągiem. Wycinki uniemożliwiają ten błąd i pozwalają nam znacznie wcześniej dowiedzieć się, że mamy problem z naszym kodem. Użycie wersji first_word z wycinkiem spowoduje błąd kompilacji:

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(); // błąd!

    println!("pierwsze słowo to: {word}");
}

Oto błąd kompilatora:

$ 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

Przypomnij sobie z zasad pożyczania, że jeśli mamy niezmienną referencję do czegoś, nie możemy również wziąć mutowalnej referencji. Ponieważ clear musi skrócić String, potrzebuje mutowalnej referencji. println! po wywołaniu clear używa referencji w word, więc referencja niezmienna musi być nadal aktywna w tym punkcie. Rust zabrania istnienia mutowalnej referencji w clear i niezmiennej referencji w word w tym samym czasie, a kompilacja kończy się niepowodzeniem. Rust nie tylko ułatwił nam korzystanie z API, ale także wyeliminował całą klasę błędów w czasie kompilacji!

Literały ciągów znaków jako wycinki

Przypomnijmy, że mówiliśmy o literałach ciągów znaków przechowywanych wewnątrz pliku binarnego. Teraz, gdy wiemy o wycinkach, możemy właściwie zrozumieć literały ciągów znaków:

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

Typ s to &str: jest to wycinek wskazujący na ten konkretny punkt w pliku binarnym. Jest to również powód, dla którego literały ciągów znaków są niezmienne; &str to niezmienna referencja.

Wycinki ciągów znaków jako parametry

Wiedza o tym, że można tworzyć wycinki z literałów i wartości String, prowadzi nas do jeszcze jednego ulepszenia funkcji first_word, a mianowicie jej sygnatury:

fn first_word(s: &String) -> &str {

Bardziej doświadczony Rustacean napisałby sygnaturę pokazaną w Listingu 4-9 zamiast niej, ponieważ pozwala to nam używać tej samej funkcji zarówno dla wartości &String, jak i dla wartości &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` działa na wycinkach `String`ów, częściowych lub całych.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` działa również na referencjach do `String`ów, które są równoważne
    // z całymi wycinkami `String`ów.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` działa na wycinkach literałów ciągu znaków, częściowych lub
    // całych.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Ponieważ literały ciągu znaków *są* już wycinkami ciągu znaków,
    // to również działa, bez składni wycinków!
    let word = first_word(my_string_literal);
}

Jeśli mamy wycinek ciągu znaków, możemy go przekazać bezpośrednio. Jeśli mamy String, możemy przekazać wycinek String lub referencję do String. Ta elastyczność wykorzystuje konwersje dereferencji, cechę, którą omówimy w sekcji „Używanie konwersji dereferencji w funkcjach i metodach” w Rozdziale 15.

Definiowanie funkcji, która przyjmuje wycinek ciągu znaków zamiast referencji do String, sprawia, że nasze API jest bardziej ogólne i użyteczne bez utraty żadnej funkcjonalności:

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` działa na wycinkach `String`ów, częściowych lub całych.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` działa również na referencjach do `String`ów, które są równoważne
    // z całymi wycinkami `String`ów.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` działa na wycinkach literałów ciągu znaków, częściowych lub
    // całych.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Ponieważ literały ciągu znaków *są* już wycinkami ciągu znaków,
    // to również działa, bez składni wycinków!
    let word = first_word(my_string_literal);
}

Inne wycinki

Wycinki ciągów znaków, jak można sobie wyobrazić, są specyficzne dla ciągów. Ale istnieje również bardziej ogólny typ wycinka. Rozważmy tę tablicę:

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

Tak samo jak możemy chcieć odwołać się do części ciągu, możemy chcieć odwołać się do części tablicy. Zrobilibyśmy to w ten sposób:

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

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

Ten wycinek ma typ &[i32]. Działa tak samo jak wycinki ciągów, przechowując referencję do pierwszego elementu i długość. Będziesz używać tego rodzaju wycinków dla wszelkiego rodzaju innych kolekcji. Te kolekcje omówimy szczegółowo, gdy będziemy mówić o wektorach w Rozdziale 8.

Podsumowanie

Koncepcje własności, pożyczania i wycinków zapewniają bezpieczeństwo pamięci w programach Rust w czasie kompilacji. Język Rust daje kontrolę nad wykorzystaniem pamięci w taki sam sposób, jak inne języki programowania systemowego. Ale to, że właściciel danych automatycznie czyści te dane, gdy właściciel wychodzi poza zasięg, oznacza, że nie musisz pisać i debugować dodatkowego kodu, aby uzyskać tę kontrolę.

Własność wpływa na działanie wielu innych części Rust, więc będziemy rozmawiać o tych koncepcjach w dalszej części książki. Przejdźmy do Rozdziału 5 i przyjrzyjmy się grupowaniu fragmentów danych w struct.

Użycie struktur do organizacji powiązanych danych

Struktura to niestandardowy typ danych, który pozwala na grupowanie i nazywanie wielu powiązanych wartości, tworzących spójną grupę. Jeśli znasz języki obiektowe, struktura jest jak atrybuty danych obiektu. W tym rozdziale porównamy krotki ze strukturami, aby rozbudować twoją wiedzę i pokazać, kiedy struktury są lepszym sposobem na grupowanie danych.

Omówimy, jak definiować i tworzyć instancje struktur. Dowiemy się, jak definiować funkcje skojarzone, zwłaszcza metody, aby określać zachowanie związane z typem struktury. Struktury i typy wyliczeniowe (enum, omówione w Rozdziale 6) to elementy składowe do tworzenia nowych typów w domenie twojego programu, aby w pełni wykorzystać sprawdzanie typów w czasie kompilacji w Rust.

Definiowanie i tworzenie instancji struktur

Definiowanie i tworzenie instancji struktur

Struktury są podobne do krotek, omówionych w sekcji „Typ krotki”, w tym, że obie przechowują wiele powiązanych wartości. Podobnie jak krotki, elementy struktury mogą być różnych typów. W przeciwieństwie do krotek, w strukturze nazwiesz każdy element danych, tak aby było jasne, co oznaczają wartości. Dodanie tych nazw sprawia, że struktury są bardziej elastyczne niż krotki: nie musisz polegać na kolejności danych, aby określić lub uzyskać dostęp do wartości instancji.

Aby zdefiniować strukturę, wpisujemy słowo kluczowe struct i nadajemy nazwę całej strukturze. Nazwa struktury powinna opisywać znaczenie grupowanych danych. Następnie, w nawiasach klamrowych, definiujemy nazwy i typy elementów danych, które nazywamy polami. Na przykład, Listing 5-1 przedstawia strukturę, która przechowuje informacje o koncie użytkownika.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

Aby użyć struktury po jej zdefiniowaniu, tworzymy instancję tej struktury, określając konkretne wartości dla każdego z pól. Tworzymy instancję, podając nazwę struktury, a następnie dodajemy nawiasy klamrowe zawierające pary klucz: wartość, gdzie klucze to nazwy pól, a wartości to dane, które chcemy przechowywać w tych polach. Nie musimy określać pól w tej samej kolejności, w jakiej zadeklarowaliśmy je w strukturze. Innymi słowy, definicja struktury jest jak ogólny szablon dla typu, a instancje wypełniają ten szablon konkretnymi danymi, aby utworzyć wartości tego typu. Na przykład, możemy zadeklarować konkretnego użytkownika, jak pokazano w Listingu 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,
    };
}

Aby uzyskać konkretną wartość ze struktury, używamy notacji kropkowej. Na przykład, aby uzyskać dostęp do adresu e-mail tego użytkownika, używamy user1.email. Jeśli instancja jest mutowalna, możemy zmienić wartość, używając notacji kropkowej i przypisując ją do konkretnego pola. Listing 5-3 pokazuje, jak zmienić wartość w polu email mutowalnej instancji 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");
}

Zauważ, że cała instancja musi być mutowalna; Rust nie pozwala nam oznaczać tylko niektórych pól jako mutowalne. Podobnie jak w przypadku każdego wyrażenia, możemy skonstruować nową instancję struktury jako ostatnie wyrażenie w treści funkcji, aby niejawnie zwrócić tę nową instancję.

Listing 5-4 przedstawia funkcję build_user, która zwraca instancję User z podanym adresem e-mail i nazwą użytkownika. Pole active otrzymuje wartość true, a sign_in_count wartość 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"),
    );
}

Logiczne jest nazwanie parametrów funkcji tak samo jak pól struktury, ale powtarzanie nazw pól email i username oraz zmiennych jest trochę uciążliwe. Gdyby struktura miała więcej pól, powtarzanie każdej nazwy stałoby się jeszcze bardziej irytujące. Na szczęście istnieje wygodna skrócona forma!

Używanie skróconej składni inicjalizacji pola

Ponieważ nazwy parametrów i nazwy pól struktury są dokładnie takie same w Listingu 5-4, możemy użyć składni skróconej inicjalizacji pola do przepisania build_user tak, aby zachowywała się dokładnie tak samo, ale nie powtarzała username i email, jak pokazano w Listingu 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"),
    );
}

Tutaj tworzymy nową instancję struktury User, która ma pole o nazwie email. Chcemy ustawić wartość pola email na wartość z parametru email funkcji build_user. Ponieważ pole email i parametr email mają tę samą nazwę, wystarczy napisać email zamiast email: email.

Tworzenie instancji za pomocą składni aktualizacji struktury

Często przydaje się tworzenie nowej instancji struktury, która zawiera większość wartości z innej instancji tego samego typu, ale zmienia niektóre z nich. Możesz to zrobić za pomocą składni aktualizacji struktury.

Najpierw, w Listingu 5-6, pokazujemy, jak utworzyć nową instancję User w user2 w zwykły sposób, bez składni aktualizacji. Ustawiamy nową wartość dla email, ale poza tym używamy tych samych wartości z user1, które utworzyliśmy w Listingu 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,
    };
}

Używając składni aktualizacji struktury, możemy osiągnąć ten sam efekt za pomocą mniejszej ilości kodu, jak pokazano w Listingu 5-7. Składnia .. określa, że pozostałe pola, które nie zostały jawnie ustawione, powinny mieć taką samą wartość jak pola w danej instancji.

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

Kod w Listingu 5-7 również tworzy instancję user2, która ma inną wartość dla email, ale ma te same wartości dla pól username, active i sign_in_count co user1. Instrukcja ..user1 musi znajdować się na końcu, aby określić, że wszelkie pozostałe pola powinny otrzymać swoje wartości z odpowiednich pól w user1, ale możemy wybrać, aby określić wartości dla dowolnej liczby pól w dowolnej kolejności, niezależnie od kolejności pól w definicji struktury.

Zauważ, że składnia aktualizacji struktury używa = jak przypisania; dzieje się tak dlatego, że przenosi ona dane, tak jak widzieliśmy to w sekcji „Zmienne i dane w interakcji przez przeniesienie”. W tym przykładzie nie możemy już używać user1 po utworzeniu user2, ponieważ String z pola username w user1 zostało przeniesione do user2. Gdybyśmy podali user2 nowe wartości String dla email i username, a więc użyli tylko wartości active i sign_in_count z user1, wówczas user1 byłoby nadal ważne po utworzeniu user2. Zarówno active, jak i sign_in_count to typy implementujące cechę Copy, więc zastosowałoby się zachowanie, o którym mówiliśmy w sekcji „Dane tylko na stosie: Kopia”. W tym przykładzie nadal możemy używać user1.email, ponieważ jego wartość nie została przeniesiona z user1.

Tworzenie różnych typów za pomocą struktur krotkowych

Rust obsługuje również struktury, które wyglądają podobnie do krotek, nazywane strukturami krotkowymi. Struktury krotkowe posiadają dodatkowe znaczenie, które nadaje im nazwa struktury, ale nie mają nazw powiązanych z ich polami; zamiast tego mają tylko typy pól. Struktury krotkowe są użyteczne, gdy chcesz nadać całej krotce nazwę i uczynić ją innym typem niż inne krotki, oraz gdy nazwanie każdego pola, jak w zwykłej strukturze, byłoby zbyt rozwlekłe lub redundantne.

Aby zdefiniować strukturę krotkową, zacznij od słowa kluczowego struct i nazwy struktury, a następnie podaj typy w krotce. Na przykład, tutaj definiujemy i używamy dwóch struktur krotkowych o nazwach Color i 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);
}

Zauważ, że wartości black i origin są różnych typów, ponieważ są instancjami różnych struktur krotek. Każda zdefiniowana przez ciebie struktura jest swoim własnym typem, mimo że pola w strukturze mogą mieć te same typy. Na przykład, funkcja, która przyjmuje parametr typu Color, nie może przyjąć Point jako argumentu, mimo że oba typy składają się z trzech wartości i32. W przeciwnym razie, instancje struktur krotek są podobne do krotek w tym sensie, że można je dekomponować na pojedyncze elementy i można użyć . po którym następuje indeks, aby uzyskać dostęp do pojedynczej wartości. W przeciwieństwie do krotek, struktury krotki wymagają podania nazwy typu struktury podczas dekompozycji. Na przykład, napisalibyśmy let Point(x, y, z) = origin;, aby dekomponować wartości punktu origin na zmienne o nazwach x, y i z.

Definiowanie struktur podobnych do jednostek

Można również definiować struktury, które nie mają żadnych pól! Nazywa się je strukturami podobnymi do jednostek, ponieważ zachowują się podobnie do (), typu jednostkowego, o którym wspominaliśmy w sekcji „Typ krotki”. Struktury podobne do jednostek mogą być użyteczne, gdy trzeba zaimplementować cechę dla jakiegoś typu, ale nie ma się żadnych danych do przechowywania w samym typie. O cechach omówimy w Rozdziale 10. Oto przykład deklaracji i tworzenia instancji struktury jednostkowej o nazwie AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Aby zdefiniować AlwaysEqual, używamy słowa kluczowego struct, wybranej nazwy, a następnie średnika. Nie ma potrzeby używania nawiasów klamrowych ani okrągłych! Następnie możemy uzyskać instancję AlwaysEqual w zmiennej subject w podobny sposób: używając zdefiniowanej nazwy, bez nawiasów klamrowych ani okrągłych. Wyobraź sobie, że później zaimplementujemy zachowanie dla tego typu, tak aby każda instancja AlwaysEqual zawsze była równa każdej instancji dowolnego innego typu, być może w celach testowych. Nie potrzebowalibyśmy żadnych danych, aby zaimplementować to zachowanie! W Rozdziale 10 dowiesz się, jak definiować cechy i implementować je na dowolnym typie, w tym na strukturach podobnych do jednostek.

Własność Danych Struktury

W definicji struktury User z Listingu 5-1 użyliśmy własnego typu String zamiast typu wycinka ciągu &str. Jest to celowy wybór, ponieważ chcemy, aby każda instancja tej struktury posiadała wszystkie swoje dane, a dane te były ważne tak długo, jak ważna jest cała struktura.

Możliwe jest również, aby struktury przechowywały referencje do danych należących do czegoś innego, ale do tego wymagane jest użycie czasów życia – funkcji Rust, którą omówimy w Rozdziale 10. Czasy życia zapewniają, że dane, do których odnosi się struktura, są ważne tak długo, jak ważna jest struktura. Powiedzmy, że spróbujesz przechowywać referencję w strukturze bez określania czasów życia, tak jak poniżej w src/main.rs; to nie zadziała:

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.2com",
        sign_in_count: 1,
    };
}

Kompilator będzie narzekał, że potrzebuje specyfikatorów czasu życia:

$ 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

W Rozdziale 10 omówimy, jak naprawić te błędy, aby można było przechowywać referencje w strukturach, ale na razie będziemy naprawiać takie błędy, używając typów posiadanych, takich jak String, zamiast referencji, takich jak &str.

Przykładowy program używający struktur

Przykładowy program używający struktur

Aby zrozumieć, kiedy warto używać struktur, napiszmy program, który oblicza pole prostokąta. Zaczniemy od użycia pojedynczych zmiennych, a następnie zrefaktoryzujemy program, aż będziemy używać struktur.

Stwórzmy nowy projekt binarny za pomocą Cargo o nazwie rectangles, który będzie przyjmował szerokość i wysokość prostokąta podane w pikselach i obliczał pole prostokąta. Listing 5-8 przedstawia krótki program z jednym sposobem na zrobienie tego w pliku src/main.rs naszego projektu.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "Pole prostokąta wynosi {} pikseli kwadratowych.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

Teraz uruchom ten program za pomocą 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.

Ten kod z powodzeniem oblicza pole prostokąta, wywołując funkcję area z każdym wymiarem, ale możemy zrobić więcej, aby uczynić ten kod bardziej przejrzystym i czytelnym.

Problem z tym kodem jest widoczny w sygnaturze area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "Pole prostokąta wynosi {} pikseli kwadratowych.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

Funkcja area ma za zadanie obliczyć pole jednego prostokąta, ale napisana przez nas funkcja ma dwa parametry i nigdzie w naszym programie nie jest jasne, że te parametry są ze sobą powiązane. Byłoby bardziej czytelne i łatwiejsze w zarządzaniu, gdybyśmy zgrupowali szerokość i wysokość. Omówiliśmy już jeden sposób, w jaki moglibyśmy to zrobić w sekcji „Typ krotki” w Rozdziale 3: używając krotek.

Refaktoryzacja za pomocą krotek

Listing 5-9 przedstawia inną wersję naszego programu, która używa krotek.

fn main() {
    let rect1 = (30, 50);

    println!(
        "Pole prostokąta wynosi {} pikseli kwadratowych.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

Pod pewnym względem ten program jest lepszy. Krotki pozwalają nam dodać trochę struktury, a teraz przekazujemy tylko jeden argument. Ale pod innym względem ta wersja jest mniej przejrzysta: krotki nie nazywają swoich elementów, więc musimy indeksować części krotki, co sprawia, że nasze obliczenia są mniej oczywiste.

Pomylenie szerokości i wysokości nie miałoby znaczenia dla obliczania powierzchni, ale gdybyśmy chcieli narysować prostokąt na ekranie, miałoby to znaczenie! Musielibyśmy pamiętać, że width to indeks krotki 0, a height to indeks krotki 1. Byłoby to jeszcze trudniejsze do zrozumienia i zapamiętania dla kogoś innego, kto używałby naszego kodu. Ponieważ nie przekazaliśmy znaczenia naszych danych w naszym kodzie, łatwiej jest teraz wprowadzić błędy.

Refaktoryzacja za pomocą struktur

Używamy struktur, aby dodać znaczenie poprzez etykietowanie danych. Możemy przekształcić krotkę, której używamy, w strukturę z nazwą dla całości, a także nazwami dla części, jak pokazano w Listingu 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "Pole prostokąta wynosi {} pikseli kwadratowych.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

Tutaj zdefiniowaliśmy strukturę i nazwaliśmy ją Rectangle. W nawiasach klamrowych zdefiniowaliśmy pola jako width i height, z których oba mają typ u32. Następnie, w main, utworzyliśmy konkretną instancję Rectangle o szerokości 30 i wysokości 50.

Nasza funkcja area jest teraz zdefiniowana z jednym parametrem, który nazwaliśmy rectangle, którego typem jest niezmienne pożyczenie instancji struktury Rectangle. Jak wspomniano w Rozdziale 4, chcemy pożyczyć strukturę, a nie przejmować jej własności. W ten sposób main zachowuje własność i może nadal używać rect1, co jest powodem, dla którego używamy & w sygnaturze funkcji i tam, gdzie wywołujemy funkcję.

Funkcja area uzyskuje dostęp do pól width i height instancji Rectangle (zauważ, że dostęp do pól pożyczonej instancji struktury nie przenosi wartości pól, dlatego często spotyka się pożyczanie struktur). Nasza sygnatura funkcji area mówi teraz dokładnie, co mamy na myśli: Oblicz pole Rectangle, używając jego pól width i height. Przekazuje to, że szerokość i wysokość są ze sobą powiązane, i nadaje wartościom opisowe nazwy, zamiast używać wartości indeksu krotki 0 i 1. Jest to korzyść dla przejrzystości.

Dodawanie funkcjonalności za pomocą wyprowadzonych cech (derived traits)

Przydałoby się móc wyświetlić instancję Rectangle podczas debugowania programu i zobaczyć wartości wszystkich jej pól. Listing 5-11 próbuje użyć makra println!, tak jak używaliśmy w poprzednich rozdziałach. Jednak to nie zadziała.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 to {rect1}");
}

Kiedy skompilujemy ten kod, otrzymamy błąd z następującym głównym komunikatem:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

Makro println! potrafi wiele rodzajów formatowania, a domyślnie nawiasy klamrowe mówią println!, aby użyć formatowania znanego jako Display: wyjście przeznaczone do bezpośredniego użytku przez użytkownika końcowego. Prymitywne typy, które widzieliśmy do tej pory, domyślnie implementują Display, ponieważ istnieje tylko jeden sposób, w jaki chciałbyś pokazać 1 lub inny typ prymitywny użytkownikowi. Ale w przypadku struktur sposób, w jaki println! powinien sformatować wyjście, jest mniej jasny, ponieważ istnieje więcej możliwości wyświetlania: Czy chcesz przecinków, czy nie? Czy chcesz drukować nawiasy klamrowe? Czy wszystkie pola powinny być wyświetlane? Z powodu tej niejednoznaczności Rust nie próbuje zgadywać, czego chcemy, a struktury nie mają dostarczonej implementacji Display do użycia z println! i symbolem zastępczym {}.

Jeśli będziemy dalej czytać błędy, znajdziemy tę pomocną notatkę:

   |                        |`Rectangle` nie może być sformatowany za pomocą domyślnego formatatora
   |                        wymaganego przez ten parametr formatowania

Spróbujmy! Wywołanie makra println! będzie teraz wyglądać tak: println!("rect1 to {rect1:?}");. Umieszczenie specyfikatora :? w nawiasach klamrowych mówi println!, że chcemy użyć formatu wyjściowego o nazwie Debug. Cecha Debug umożliwia nam wyświetlanie naszej struktury w sposób użyteczny dla programistów, dzięki czemu możemy zobaczyć jej wartość podczas debugowania kodu.

Skompiluj kod z tą zmianą. Cholera! Nadal otrzymujemy błąd:

error[E0277]: `Rectangle` nie implementuje `Debug`

Ale znowu, kompilator daje nam pomocną notatkę:

   |                        wymagany przez ten parametr formatowania
   |

Rust zawiera funkcjonalność do wyświetlania informacji debugujących, ale musimy jawnie ją włączyć, aby ta funkcjonalność była dostępna dla naszej struktury. Aby to zrobić, dodajemy zewnętrzny atrybut #[derive(Debug)] tuż przed definicją struktury, jak pokazano w Listingu 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 to {rect1:?}");
}

Teraz, gdy uruchomimy program, nie otrzymamy żadnych błędów i zobaczymy następujące wyjście:

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

Pięknie! To nie jest najładniejsze wyjście, ale pokazuje wartości wszystkich pól dla tej instancji, co z pewnością pomogłoby podczas debugowania. Kiedy mamy większe struktury, przydatne jest, aby wyjście było nieco łatwiejsze do odczytania; w takich przypadkach możemy użyć {:#?} zamiast {:?} w ciągu println!. W tym przykładzie użycie stylu {:#?} spowoduje wyświetlenie następującego komunikatu:

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

Innym sposobem wydrukowania wartości za pomocą formatu Debug jest użycie makra dbg!, które przejmuje własność wyrażenia (w przeciwieństwie do println!, które przyjmuje referencję), drukuje plik i numer linii, w której występuje wywołanie makra dbg! wraz z wynikową wartością tego wyrażenia i zwraca własność wartości.

Uwaga: Wywołanie makra dbg! drukuje do standardowego strumienia błędów konsoli (stderr), w przeciwieństwie do println!, które drukuje do standardowego strumienia wyjściowego konsoli (stdout). Więcej o stderr i stdout omówimy w sekcji „Przekierowywanie błędów do standardowego strumienia błędów” w Rozdziale 12.

Oto przykład, w którym interesuje nas wartość przypisana do pola width, a także wartość całej struktury w 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);
}

Możemy umieścić dbg! wokół wyrażenia 30 * scale i, ponieważ dbg! zwraca własność wartości wyrażenia, pole width otrzyma tę samą wartość, jakbyśmy nie mieli tam wywołania dbg!. Nie chcemy, aby dbg! przejmowało własność rect1, więc w następnym wywołaniu używamy referencji do rect1. Oto jak wygląda wyjście z tego przykładu:

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

Widzimy, że pierwsza część wyjścia pochodzi z pliku src/main.rs w linii 10, gdzie debugujemy wyrażenie 30 * scale, a jego wynikowa wartość to 60 (formatowanie Debug zaimplementowane dla liczb całkowitych polega na wydrukowaniu tylko ich wartości). Wywołanie dbg! w linii 14 pliku src/main.rs wyprowadza wartość &rect1, czyli struktury Rectangle. To wyjście wykorzystuje ładne formatowanie Debug typu Rectangle. Makro dbg! może być naprawdę pomocne, gdy próbujesz dowiedzieć się, co robi twój kod!

Oprócz cechy Debug, Rust dostarczył szereg cech, których możemy używać z atrybutem derive, które mogą dodawać użyteczne zachowanie do naszych niestandardowych typów. Te cechy i ich zachowania są wymienione w Dodatku C. Omówimy, jak zaimplementować te cechy z niestandardowym zachowaniem, a także jak tworzyć własne cechy w Rozdziale 10. Istnieje również wiele innych atrybutów niż derive; więcej informacji można znaleźć w sekcji „Atrybuty” w dokumentacji Rust Reference.

Nasza funkcja area jest bardzo specyficzna: oblicza tylko pole prostokątów. Pomocne byłoby powiązanie tego zachowania bliżej z naszą strukturą Rectangle, ponieważ nie będzie ono działać z żadnym innym typem. Przyjrzyjmy się, jak możemy kontynuować refaktoryzację tego kodu, zamieniając funkcję area w metodę area zdefiniowaną dla naszego typu Rectangle.

Metody

Metody

Metody są podobne do funkcji: deklarujemy je słowem kluczowym fn i nazwą, mogą mieć parametry i zwracać wartość, oraz zawierają kod, który jest uruchamiany po wywołaniu metody z innego miejsca. W przeciwieństwie do funkcji, metody są definiowane w kontekście struktury (lub typu wyliczeniowego albo obiektu cechy, które omówimy odpowiednio w Rozdziale 6 i Rozdziale 18), a ich pierwszym parametrem jest zawsze self, które reprezentuje instancję struktury, na której wywoływana jest metoda.

Składnia metody

Zmieńmy funkcję area, która ma instancję Rectangle jako parametr, i zamiast tego stwórzmy metodę area zdefiniowaną w strukturze Rectangle, jak pokazano w Listingu 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!(
        "Pole prostokąta wynosi {} pikseli kwadratowych.",
        rect1.area()
    );
}

Aby zdefiniować funkcję w kontekście Rectangle, rozpoczynamy blok impl (implementacji) dla Rectangle. Wszystko w tym bloku impl będzie powiązane z typem Rectangle. Następnie przenosimy funkcję area do nawiasów klamrowych impl i zmieniamy pierwszy (a w tym przypadku jedyny) parametr na self w sygnaturze i wszędzie w treści. W main, gdzie wywołaliśmy funkcję area i przekazaliśmy rect1 jako argument, możemy zamiast tego użyć składni metody do wywołania metody area na naszej instancji Rectangle. Składnia metody występuje po instancji: dodajemy kropkę, po której następuje nazwa metody, nawiasy i wszelkie argumenty.

W sygnaturze area używamy &self zamiast rectangle: &Rectangle. &self to w rzeczywistości skrót od self: &Self. W bloku impl typ Self jest aliasem dla typu, dla którego jest blok impl. Metody muszą mieć parametr o nazwie self typu Self jako swój pierwszy parametr, więc Rust pozwala na skrócenie tego do samej nazwy self w miejscu pierwszego parametru. Zauważ, że nadal musimy używać & przed skrótem self, aby wskazać, że ta metoda pożycza instancję Self, tak jak zrobiliśmy to w rectangle: &Rectangle. Metody mogą przejmować własność self, pożyczać self niezmiennie, jak to zrobiliśmy tutaj, lub pożyczać self mutowalnie, tak jak każdy inny parametr.

Wybraliśmy &self z tego samego powodu, dla którego użyliśmy &Rectangle w wersji funkcyjnej: nie chcemy przejmować własności i chcemy tylko odczytywać dane ze struktury, a nie do niej zapisywać. Gdybyśmy chcieli zmienić instancję, na której wywołaliśmy metodę, w ramach działania metody, użylibyśmy &mut self jako pierwszego parametru. Posiadanie metody, która przejmuje własność instancji, używając tylko self jako pierwszego parametru, jest rzadkie; ta technika jest zazwyczaj używana, gdy metoda przekształca self w coś innego i chcemy uniemożliwić wywołującemu używanie oryginalnej instancji po transformacji.

Głównym powodem używania metod zamiast funkcji, oprócz zapewnienia składni metody i braku konieczności powtarzania typu self w sygnaturze każdej metody, jest organizacja. Umieściliśmy wszystkie rzeczy, które możemy zrobić z instancją typu, w jednym bloku impl, zamiast zmuszać przyszłych użytkowników naszego kodu do szukania możliwości Rectangle w różnych miejscach dostarczanej przez nas biblioteki.

Zauważ, że możemy nadać metodzie taką samą nazwę jak jednemu z pól struktury. Na przykład, możemy zdefiniować metodę w Rectangle, która również nazywa się 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!("Prostokąt ma szerokość różną od zera; wynosi {}", rect1.width);
    }
}

Tutaj, decydujemy, aby metoda width zwracała true, jeśli wartość w polu width instancji jest większa niż 0, a false, jeśli wartość jest 0: możemy użyć pola o tej samej nazwie w metodzie do dowolnego celu. W main, gdy po rect1.width umieścimy nawiasy, Rust wie, że chodzi nam o metodę width. Gdy nie używamy nawiasów, Rust wie, że chodzi nam o pole width.

Często, choć nie zawsze, gdy nadajemy metodzie taką samą nazwę jak polu, chcemy, aby zwracała tylko wartość z pola i nic więcej. Takie metody nazywane są getterami, a Rust nie implementuje ich automatycznie dla pól struktur, tak jak robią to niektóre inne języki. Gettery są użyteczne, ponieważ można uczynić pole prywatnym, ale metodę publiczną, a tym samym umożliwić dostęp tylko do odczytu do tego pola jako części publicznego API typu. Omówimy, czym są publiczne i prywatne, oraz jak oznaczyć pole lub metodę jako publiczną lub prywatną w Rozdziale 7.

Gdzie jest operator ->?

W C i C++ do wywoływania metod używa się dwóch różnych operatorów: . jeśli wywołuje się metodę bezpośrednio na obiekcie, oraz -> jeśli wywołuje się metodę na wskaźniku do obiektu i trzeba najpierw dereferencjować wskaźnik. Innymi słowy, jeśli object jest wskaźnikiem, object->something() jest podobne do (*object).something().

Rust nie ma odpowiednika operatora ->; zamiast tego, Rust ma funkcję zwaną automatycznym referencjowaniem i dereferencjowaniem. Wywoływanie metod jest jednym z niewielu miejsc w Rust z takim zachowaniem.

Działa to w następujący sposób: Kiedy wywołujesz metodę object.something(), Rust automatycznie dodaje &, &mut lub *, tak aby object pasował do sygnatury metody. Innymi słowy, poniższe są takie same:

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

Pierwsza z nich wygląda znacznie czyściej. To automatyczne zachowanie referencjonowania działa, ponieważ metody mają wyraźny odbiornik — typ self. Biorąc pod uwagę odbiornik i nazwę metody, Rust może jednoznacznie określić, czy metoda odczytuje (&self), mutuje (&mut self), czy zużywa (self). Fakt, że Rust sprawia, że pożyczanie jest niejawne dla odbiorników metod, jest dużą częścią sprawiania, że własność jest ergonomiczna w praktyce.

Metody z większą liczbą parametrów

Poćwiczmy używanie metod, implementując drugą metodę w strukturze Rectangle. Tym razem chcemy, aby instancja Rectangle przyjmowała inną instancję Rectangle i zwracała true, jeśli drugi Rectangle może całkowicie zmieścić się w self (pierwszym Rectangle); w przeciwnym razie powinna zwrócić false. Oznacza to, że po zdefiniowaniu metody can_hold, chcemy móc napisać program pokazany w Listingu 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!("Czy rect1 może pomieścić rect2? {}", rect1.can_hold(&rect2));
    println!("Czy rect1 może pomieścić rect3? {}", rect1.can_hold(&rect3));
}

Oczekiwane wyjście wyglądałoby następująco, ponieważ oba wymiary rect2 są mniejsze niż wymiary rect1, ale rect3 jest szerszy niż rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Wiemy, że chcemy zdefiniować metodę, więc będzie ona w bloku impl Rectangle. Nazwa metody będzie can_hold, i przyjmie niezmienne pożyczenie innego Rectangle jako parametr. Możemy stwierdzić, jaki będzie typ parametru, patrząc na kod, który wywołuje metodę: rect1.can_hold(&rect2) przekazuje &rect2, co jest niezmiennym pożyczeniem rect2, instancji Rectangle. Ma to sens, ponieważ musimy tylko odczytywać rect2 (zamiast zapisywać, co oznaczałoby, że potrzebowalibyśmy mutowalnego pożyczenia), i chcemy, aby main zachowało własność rect2, abyśmy mogli go ponownie użyć po wywołaniu metody can_hold. Wartością zwracaną can_hold będzie Boolean, a implementacja sprawdzi, czy szerokość i wysokość self są większe niż szerokość i wysokość drugiego Rectangle, odpowiednio. Dodajmy nową metodę can_hold do bloku impl z Listingu 5-13, pokazanej w Listingu 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!("Czy rect1 może pomieścić rect2? {}", rect1.can_hold(&rect2));
    println!("Czy rect1 może pomieścić rect3? {}", rect1.can_hold(&rect3));
}

Po uruchomieniu tego kodu z funkcją main z Listingu 5-14, otrzymamy pożądane wyjście. Metody mogą przyjmować wiele parametrów, które dodajemy do sygnatury po parametrze self, a te parametry działają tak samo jak parametry w funkcjach.

Funkcje skojarzone

Wszystkie funkcje zdefiniowane w bloku impl nazywane są funkcjami skojarzonymi, ponieważ są powiązane z typem nazwanym po impl. Możemy definiować funkcje skojarzone, które nie mają self jako swojego pierwszego parametru (i dlatego nie są metodami), ponieważ nie potrzebują instancji typu do działania. Użyliśmy już jednej takiej funkcji: funkcji String::from zdefiniowanej dla typu String.

Funkcje skojarzone, które nie są metodami, są często używane jako konstruktory, które zwracają nową instancję struktury. Są one często nazywane new, ale new nie jest specjalną nazwą i nie jest wbudowane w język. Na przykład, moglibyśmy zapewnić funkcję skojarzoną o nazwie square, która miałaby jeden parametr wymiaru i używałaby go zarówno jako szerokości, jak i wysokości, ułatwiając w ten sposób tworzenie kwadratowego Rectangle zamiast konieczności dwukrotnego określania tej samej wartości:

Nazwa pliku: 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);
}

Słowa kluczowe Self w typie zwracanym i w treści funkcji są aliasami dla typu, który pojawia się po słowie kluczowym impl, czyli w tym przypadku Rectangle.

Aby wywołać tę funkcję skojarzoną, używamy składni :: z nazwą struktury; let sq = Rectangle::square(3); jest przykładem. Ta funkcja jest umieszczona w przestrzeni nazw struktury: składnia :: jest używana zarówno dla funkcji skojarzonych, jak i przestrzeni nazw utworzonych przez moduły. Omówimy moduły w Rozdziale 7.

Wiele bloków impl

Każda struktura może mieć wiele bloków impl. Na przykład, Listing 5-15 jest równoważny z kodem pokazanym w Listingu 5-16, który ma każdą metodę w swoim własnym bloku 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!("Czy rect1 może pomieścić rect2? {}", rect1.can_hold(&rect2));
    println!("Czy rect1 może pomieścić rect3? {}", rect1.can_hold(&rect3));
}

Nie ma powodu, aby rozdzielać te metody na wiele bloków impl w tym przypadku, ale jest to poprawna składnia. Zobaczymy przypadek, w którym wiele bloków impl jest użytecznych w Rozdziale 10, gdzie omówimy typy generyczne i cechy.

Podsumowanie

Struktury pozwalają tworzyć niestandardowe typy, które mają znaczenie dla twojej domeny. Używając struktur, możesz zachować powiązane ze sobą fragmenty danych i nazywać każdy z nich, aby Twój kod był przejrzysty. W blokach impl możesz definiować funkcje powiązane z Twoim typem, a metody są rodzajem funkcji powiązanych, które pozwalają określać zachowanie instancji Twoich struktur.

Ale struktury to nie jedyny sposób, w jaki możesz tworzyć niestandardowe typy: przejdźmy do funkcji enum w Rust, aby dodać kolejne narzędzie do Twojego zestawu.

Typy wyliczeniowe (enum) i dopasowywanie wzorców

W tym rozdziale przyjrzymy się wyliczeniom, zwanym również enumami.Enumy pozwalają zdefiniować typ poprzez wyliczenie jego możliwych wariantów.Najpierw zdefiniujemy i użyjemy enum, aby pokazać, jak enum może kodowaćznaczenie wraz z danymi. Następnie zbadamy szczególnie użyteczny enum,nazwany Option, który wyraża, że wartość może być albo czymś, albo niczym.Następnie przyjrzymy się, jak dopasowywanie wzorców w wyrażeniu matchułatwia uruchamianie różnego kodu dla różnych wartości enum. Na koniecomówimy, jak konstrukcja if let jest kolejnym wygodnym i zwięzłym idiomemdostępnym do obsługi enumów w twoim kodzie.

Definiowanie typu wyliczeniowego

Definiowanie typu wyliczeniowego

Podczas gdy struktury dają ci sposób grupowania powiązanych pól i danych, jak Rectangle z jego width i height, enums dają ci sposób powiedzenia, że wartość jest jedną z możliwych zestawów wartości. Na przykład, możemy chcieć powiedzieć, że Rectangle jest jednym z możliwych kształtów, które obejmują również Circle i Triangle. Aby to zrobić, Rust pozwala nam zakodować te możliwości jako enum.

Przyjrzyjmy się sytuacji, którą możemy chcieć wyrazić w kodzie i zobaczmy, dlaczego enums są użyteczne i bardziej odpowiednie niż struktury w tym przypadku. Powiedzmy, że musimy pracować z adresami IP. Obecnie używane są dwa główne standardy dla adresów IP: wersja czwarta i wersja szósta. Ponieważ są to jedyne możliwości dla adresu IP, z którymi nasz program się spotka, możemy wyliczyć wszystkie możliwe warianty, skąd pochodzi nazwa „enumeration”.

Każdy adres IP może być adresem wersji czwartej lub wersji szóstej, ale nie oboma jednocześnie. Ta właściwość adresów IP sprawia, że struktura danych enum jest odpowiednia, ponieważ wartość enum może być tylko jednym ze swoich wariantów. Zarówno adresy wersji czwartej, jak i wersji szóstej są nadal zasadniczo adresami IP, więc powinny być traktowane jako ten sam typ, gdy kod obsługuje sytuacje, które mają zastosowanie do każdego rodzaju adresu IP.

Możemy wyrazić tę koncepcję w kodzie, definiując wyliczenie IpAddrKind i wymieniając możliwe rodzaje adresów IP, którymi mogą być V4 i V6. Są to warianty enum:

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 to teraz niestandardowy typ danych, którego możemy używać w innych miejscach naszego kodu.

Wartości wyliczeniowe

Możemy tworzyć instancje każdego z dwóch wariantów IpAddrKind w następujący sposób:

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

Zauważ, że warianty enum są umieszczone w przestrzeni nazw pod jego identyfikatorem, a my używamy podwójnego dwukropka do rozdzielenia tych dwóch. Jest to przydatne, ponieważ teraz obie wartości IpAddrKind::V4 i IpAddrKind::V6 są tego samego typu: IpAddrKind. Możemy wtedy, na przykład, zdefiniować funkcję, która przyjmuje dowolny 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) {}

I możemy wywołać tę funkcję z dowolnym wariantem:

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

Używanie typów wyliczeniowych (enums) ma jeszcze więcej zalet. Myśląc więcej o naszym typie adresu IP, w tej chwili nie mamy sposobu na przechowywanie rzeczywistych danych adresu IP; wiemy tylko, jakiego jest rodzaju. Biorąc pod uwagę, że właśnie dowiedziałeś się o strukturach w Rozdziale 5, możesz być skłonny do rozwiązania tego problemu za pomocą struktur, jak pokazano w Listingu 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"),
    };
}

Tutaj zdefiniowaliśmy strukturę IpAddr, która ma dwa pola: pole kind typu IpAddrKind (enum, które zdefiniowaliśmy wcześniej) i pole address typu String. Mamy dwie instancje tej struktury. Pierwsza to home i ma wartość IpAddrKind::V4 jako swoje kind z powiązanymi danymi adresu 127.0.0.1. Druga instancja to loopback. Ma ona inny wariant IpAddrKind jako swoją wartość kind, V6, i ma powiązany z nim adres ::1. Użyliśmy struktury do połączenia wartości kind i address, więc teraz wariant jest powiązany z wartością.

Jednakże, reprezentowanie tej samej koncepcji używając tylko typu wyliczeniowego jest bardziej zwięzłe: zamiast typu wyliczeniowego wewnątrz struktury, możemy umieścić dane bezpośrednio w każdym wariancie typu wyliczeniowego. Ta nowa definicja typu wyliczeniowego IpAddr mówi, że zarówno warianty V4, jak i V6 będą miały powiązane wartości 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"));
}

Dane do każdego wariantu enum dołączamy bezpośrednio, więc nie ma potrzeby używania dodatkowej struktury. W tym przypadku łatwiej jest również zauważyć inną cechę działania enumów: nazwa każdego zdefiniowanego przez nas wariantu enum staje się również funkcją, która konstruuje instancję enum. Oznacza to, że IpAddr::V4() jest wywołaniem funkcji, która przyjmuje argument String i zwraca instancję typu IpAddr. Tę funkcję konstruującą otrzymujemy automatycznie w wyniku zdefiniowania enum.

Istnieje jeszcze jedna zaleta używania typu wyliczeniowego zamiast struktury: każdy wariant może mieć różne typy i ilości powiązanych danych. Adresy IP wersji czwartej zawsze będą miały cztery komponenty numeryczne o wartościach od 0 do 255. Gdybyśmy chcieli przechowywać adresy V4 jako cztery wartości u8, ale nadal wyrażać adresy V6 jako pojedynczą wartość String, nie bylibyśmy w stanie tego zrobić za pomocą struktury. Typy wyliczeniowe z łatwością radzą sobie z tym przypadkiem:

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

Pokazaliśmy kilka różnych sposobów definiowania struktur danych do przechowywania adresów IP wersji czwartej i szóstej. Jednak, jak się okazuje, chęć przechowywania adresów IP i kodowania ich rodzaju jest tak powszechna, że biblioteka standardowa ma definicję, której możemy użyć! Przyjrzyjmy się, jak biblioteka standardowa definiuje IpAddr. Ma ona dokładnie ten sam typ wyliczeniowy i warianty, które zdefiniowaliśmy i użyliśmy, ale osadza dane adresowe w wariantach w postaci dwóch różnych struktur, które są definiowane inaczej dla każdego wariantu:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

Ten kod ilustruje, że wariant enum może zawierać dowolny rodzaj danych: ciągi znaków, typy numeryczne lub struktury, na przykład. Może nawet zawierać inny enum! Ponadto, typy biblioteki standardowej często nie są o wiele bardziej skomplikowane niż to, co sam byś wymyślił.

Zauważ, że choć biblioteka standardowa zawiera definicję dla IpAddr, nadal możemy tworzyć i używać własnej definicji bez konfliktu, ponieważ nie wprowadziliśmy definicji z biblioteki standardowej do naszego zasięgu. Więcej o wprowadzaniu typów do zasięgu omówimy w Rozdziale 7.

Przyjrzyjmy się innemu przykładowi typu wyliczeniowego w Listingu 6-2: ten ma szeroką gamę typów osadzonych w swoich wariantach.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

Ten typ wyliczeniowy ma cztery warianty o różnych typach:

• Quit: Nie ma z nim związanych żadnych danych
• Move: Ma nazwane pola, podobnie jak struktura
• Write: Zawiera pojedynczy String
• ChangeColor: Zawiera trzy wartości i32

Definiowanie enum z wariantami takimi jak te w Listingu 6-2 jest podobne do definiowania różnych rodzajów definicji struktur, z tą różnicą, że enum nie używa słowa kluczowego struct, a wszystkie warianty są zgrupowane pod typem Message. Następujące struktury mogłyby przechowywać te same dane, co poprzednie warianty enum:

struct QuitMessage; // struktura jednostkowa
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // struktura krotki
struct ChangeColorMessage(i32, i32, i32); // struktura krotki

fn main() {}

Ale gdybyśmy użyli różnych struktur, z których każda ma swój własny typ, nie moglibyśmy tak łatwo zdefiniować funkcji, która przyjmowałaby dowolny z tych rodzajów wiadomości, jak w przypadku typu wyliczeniowego Message zdefiniowanego w Listingu 6-2, który jest pojedynczym typem.

Istnieje jeszcze jedno podobieństwo między typami wyliczeniowymi a strukturami: tak jak jesteśmy w stanie definiować metody w strukturach za pomocą impl, tak samo jesteśmy w stanie definiować metody w typach wyliczeniowych. Oto metoda o nazwie call, którą moglibyśmy zdefiniować w naszym typie wyliczeniowym Message:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // treść metody zostałaby zdefiniowana tutaj
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

Treść metody użyłaby self, aby uzyskać wartość, na której wywołaliśmy metodę. W tym przykładzie utworzyliśmy zmienną m, która ma wartość Message::Write(String::from("hello")), i to właśnie będzie self w treści metody call, gdy zostanie uruchomione m.call().

Przyjrzyjmy się innemu enumowi w bibliotece standardowej, który jest bardzo powszechny i użyteczny: Option.

Typ wyliczeniowy Option

Ta sekcja bada studium przypadku Option, które jest innym typem wyliczeniowym zdefiniowanym przez bibliotekę standardową. Typ Option koduje bardzo powszechny scenariusz, w którym wartość może być czymś, albo może być niczym.

Na przykład, jeśli zażądasz pierwszego elementu z niepustej listy, otrzymasz wartość. Jeśli zażądasz pierwszego elementu z pustej listy, otrzymasz nic. Wyrażenie tej koncepcji w kategoriach systemu typów oznacza, że kompilator może sprawdzić, czy obsłużyłeś wszystkie przypadki, które powinieneś obsłużyć; ta funkcjonalność może zapobiegać błędom, które są niezwykle powszechne w innych językach programowania.

Projektowanie języków programowania często rozpatruje się w kategoriach tego, jakie funkcje się uwzględnia, ale funkcje, które się wyklucza, również są ważne. Rust nie posiada funkcji null, którą ma wiele innych języków. Null to wartość, która oznacza, że nie ma tam żadnej wartości. W językach z null, zmienne mogą zawsze być w jednym z dwóch stanów: null lub nie-null.

W swojej prezentacji z 2009 roku „Null References: The Billion Dollar Mistake” Tony Hoare, wynalazca wartości null, powiedział:

Nazywam to moim miliardowym błędem. W tamtym czasie projektowałem pierwszy kompleksowy system typów dla referencji w języku obiektowym. Moim celem było zapewnienie, że wszelkie użycie referencji powinno być absolutnie bezpieczne, z automatycznym sprawdzaniem wykonywanym przez kompilator. Ale nie mogłem oprzeć się pokusie wprowadzenia referencji null, po prostu dlatego, że była tak łatwa do zaimplementowania. Doprowadziło to do niezliczonych błędów, luk w zabezpieczeniach i awarii systemów, które prawdopodobnie spowodowały miliard dolarów bólu i szkód w ciągu ostatnich czterdziestu lat.

Problem z wartościami null polega na tym, że jeśli spróbujesz użyć wartości null jako wartości nie-null, otrzymasz jakiś błąd. Ponieważ ta właściwość null lub nie-null jest wszechobecna, niezwykle łatwo jest popełnić tego rodzaju błąd.

Jednak koncepcja, którą null próbuje wyrazić, jest nadal użyteczna: null to wartość, która jest obecnie nieprawidłowa lub nieobecna z jakiegoś powodu.

Problem nie leży w samej koncepcji, lecz w konkretnej implementacji. W związku z tym Rust nie posiada wartości null, ale ma enum, który może kodować koncepcję obecności lub braku wartości. Tym enumem jest Option<T>, i jest on zdefiniowany przez bibliotekę standardową w następujący sposób:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Typ wyliczeniowy Option<T> jest tak użyteczny, że jest nawet włączony do preambuly; nie musisz jawnie wprowadzać go do zasięgu. Jego warianty są również włączone do preambuly: możesz używać Some i None bezpośrednio bez prefiksu Option::. Typ wyliczeniowy Option<T> jest nadal zwykłym typem wyliczeniowym, a Some(T) i None są nadal wariantami typu Option<T>.

Składnia <T> to cecha Rust, o której jeszcze nie mówiliśmy. Jest to ogólny parametr typu, a o ogólnych typach szerzej omówimy w Rozdziale 10. Na razie musisz wiedzieć, że <T> oznacza, że wariant Some typu wyliczeniowego Option może przechowywać pojedynczy element danych dowolnego typu, a każdy konkretny typ, który zostanie użyty zamiast T, sprawia, że cały typ Option<T> staje się innym typem. Oto kilka przykładów użycia wartości Option do przechowywania typów liczbowych i znakowych:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

Typ some_number to Option<i32>. Typ some_char to Option<char>, co jest innym typem. Rust może wywnioskować te typy, ponieważ określiliśmy wartość w wariancie Some. Dla absent_number, Rust wymaga od nas adnotacji całego typu Option: kompilator nie może wywnioskować typu, który będzie przechowywał odpowiadający mu wariant Some, patrząc tylko na wartość None. Tutaj mówimy Rustowi, że chcemy, aby absent_number był typu Option<i32>.

Kiedy mamy wartość Some, wiemy, że wartość jest obecna, a wartość jest przechowywana w Some. Kiedy mamy wartość None, w pewnym sensie oznacza to to samo co null: nie mamy ważnej wartości. Dlaczego więc Option<T> jest lepsze niż null?

Krótko mówiąc, ponieważ Option<T> i T (gdzie T może być dowolnym typem) są różnymi typami, kompilator nie pozwoli nam użyć wartości Option<T> tak, jakby była ona na pewno prawidłową wartością. Na przykład ten kod nie skompiluje się, ponieważ próbuje dodać i8 do Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

Jeśli uruchomimy ten kod, otrzymamy komunikat o błędzie podobny do tego:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` do `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ brak implementacji dla `i8 + Option<i8>`
  |
  = help: cecha `Add<Option<i8>>` nie jest zaimplementowana dla `i8`
  = help: następujące inne typy implementują cechę `Add<Rhs>`:
            `&i8` implementuje `Add<i8>`
            `&i8` implementuje `Add`
            `i8` implementuje `Add<&i8>`
            `i8` implementuje `Add`

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

Intensywnie! W efekcie ten komunikat o błędzie oznacza, że Rust nie rozumie, jak dodać i8 i Option<i8>, ponieważ są to różne typy. Kiedy mamy wartość typu takiego jak i8 w Rust, kompilator zapewni, że zawsze mamy prawidłową wartość. Możemy postępować pewnie, nie musząc sprawdzać wartości null przed użyciem tej wartości. Tylko wtedy, gdy mamy Option<i8> (lub dowolny typ wartości, z którym pracujemy), musimy martwić się o ewentualny brak wartości, a kompilator upewni się, że obsłużymy ten przypadek przed użyciem wartości.

Innymi słowy, musisz przekonwertować Option<T> na T, zanim będziesz mógł wykonywać operacje T. Ogólnie rzecz biorąc, pomaga to wychwycić jeden z najczęstszych problemów z null: założenie, że coś nie jest null, gdy w rzeczywistości jest.

Eliminowanie ryzyka błędnego założenia wartości nie-null pomaga ci być pewniejszym swojego kodu. Aby mieć wartość, która potencjalnie może być null, musisz jawnie się na to zgodzić, czyniąc typ tej wartości Option<T>. Następnie, gdy używasz tej wartości, musisz jawnie obsłużyć przypadek, gdy wartość jest null. Wszędzie tam, gdzie wartość ma typ, który nie jest Option<T>, możesz bezpiecznie założyć, że wartość nie jest null. Była to celowa decyzja projektowa dla Rust, aby ograniczyć wszechobecność wartości null i zwiększyć bezpieczeństwo kodu w Rust.

Więc jak wyciągnąć wartość T z wariantu Some, gdy masz wartość typu Option<T>, aby móc jej użyć? Enum Option<T> ma wiele metod, które są przydatne w różnych sytuacjach; możesz je sprawdzić w jej dokumentacji. Zapoznanie się z metodami w Option<T> będzie niezwykle pomocne w Twojej podróży z Rust.

Ogólnie rzecz biorąc, aby użyć wartości Option<T>, chcesz mieć kod, który obsłuży każdy wariant. Chcesz, aby pewien kod uruchamiał się tylko wtedy, gdy masz wartość Some(T), i ten kod może używać wewnętrznego T. Chcesz, aby inny kod uruchamiał się tylko wtedy, gdy masz wartość None, a ten kod nie ma dostępnej wartości T. Wyrażenie match jest konstrukcją przepływu sterowania, która robi to właśnie w przypadku enumów: uruchamia inny kod w zależności od wariantu enum, który posiada, a ten kod może używać danych zawartych w pasującej wartości.

Konstrukcja kontroli przepływu `match`

Konstrukcja kontroli przepływu match

Rust ma niezwykle potężną konstrukcję kontroli przepływu o nazwie match, która pozwala porównywać wartość z serią wzorców, a następnie wykonywać kod na podstawie pasującego wzorca. Wzorce mogą składać się z literałów, nazw zmiennych, symboli wieloznacznych i wielu innych rzeczy; Rozdział 19 obejmuje wszystkie różne rodzaje wzorców i to, co robią. Siła match pochodzi z ekspresywności wzorców i faktu, że kompilator potwierdza, że wszystkie możliwe przypadki są obsługiwane.

Pomyśl o wyrażeniu match jak o maszynie do sortowania monet: monety zjeżdżają po torze z otworami o różnej wielkości, a każda moneta wpada przez pierwszy otwór, do którego pasuje. W ten sam sposób wartości przechodzą przez każdy wzorzec w match, a przy pierwszym wzorcu, do którego wartość „pasuje”, wartość wpada do skojarzonego bloku kodu, aby zostać użyta podczas wykonania.

Skoro mowa o monetach, użyjmy ich jako przykładu z match! Możemy napisać funkcję, która przyjmuje nieznaną monetę amerykańską i, podobnie jak maszyna licząca, określa, jaka to moneta i zwraca jej wartość w centach, jak pokazano w Listingu 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() {}

Rozłóżmy match w funkcji value_in_cents. Najpierw wymieniamy słowo kluczowe match, po którym następuje wyrażenie, które w tym przypadku jest wartością coin. To wydaje się bardzo podobne do wyrażenia warunkowego używanego z if, ale jest duża różnica: z if warunek musi ewaluować do wartości boolowskiej, ale tutaj może to być dowolny typ. Typ coin w tym przykładzie to enum Coin, który zdefiniowaliśmy w pierwszej linii.

Następne są ramiona match. Ramka składa się z dwóch części: wzorca i pewnego kodu. Pierwsza ramka ma wzorzec, którym jest wartość Coin::Penny, a następnie operator =>, który oddziela wzorzec od kodu do uruchomienia. Kod w tym przypadku to po prostu wartość 1. Każda ramka jest oddzielona od następnej przecinkiem.

Kiedy wyrażenie match jest wykonywane, porównuje ono wynikową wartość z wzorcem każdej gałęzi, po kolei. Jeśli wzorzec pasuje do wartości, kod skojarzony z tym wzorcem jest wykonywany. Jeśli ten wzorzec nie pasuje do wartości, wykonanie przechodzi do następnej gałęzi, podobnie jak w maszynie do sortowania monet. Możemy mieć tyle gałęzi, ile potrzebujemy: w Listingu 6-3, nasz match ma cztery gałęzie.

Kod skojarzony z każdym ramieniem jest wyrażeniem, a wynikowa wartość wyrażenia w pasującym ramieniu jest wartością, która jest zwracana dla całego wyrażenia match.

Zazwyczaj nie używamy nawiasów klamrowych, jeśli kod gałęzi match jest krótki, jak w Listingu 6-3, gdzie każda gałąź po prostu zwraca wartość. Jeśli chcesz uruchomić wiele linii kodu w gałęzi match, musisz użyć nawiasów klamrowych, a przecinek po gałęzi jest wtedy opcjonalny. Na przykład, poniższy kod drukuje „Lucky penny!” za każdym razem, gdy metoda jest wywoływana z Coin::Penny, ale nadal zwraca ostatnią wartość bloku, 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Szczęśliwy grosz!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Wzorce, które wiążą się z wartościami

Inną przydatną cechą ramion match jest to, że mogą one wiązać się z częściami wartości, które pasują do wzorca. W ten sposób możemy wyodrębniać wartości z wariantów enum.

Na przykład, zmieńmy jeden z naszych wariantów enum, aby przechowywał w sobie dane. Od 1999 do 2008 roku Stany Zjednoczone biły ćwierćdolarówki z różnymi wzorami dla każdego z 50 stanów po jednej stronie. Żadne inne monety nie otrzymały wzorów stanów, więc tylko ćwierćdolarówki mają tę dodatkową wartość. Możemy dodać tę informację do naszego enum, zmieniając wariant Quarter tak, aby zawierał wartość UsState przechowywaną w środku, co zrobiliśmy w Listingu 6-4.

#[derive(Debug)] // abyśmy mogli za chwilę sprawdzić stan
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

Wyobraźmy sobie, że przyjaciel próbuje zebrać wszystkie 50 monet stanowych. Podczas gdy my sortujemy naszą drobną monetę według typu monety, będziemy również wywoływać nazwę stanu związanego z każdą monetą, tak aby jeśli jest to moneta, której nasz przyjaciel nie ma, mógł ją dodać do swojej kolekcji.

W wyrażeniu match dla tego kodu dodajemy zmienną o nazwie state do wzorca, który pasuje do wartości wariantu Coin::Quarter. Gdy pasuje Coin::Quarter, zmienna state zostanie powiązana z wartością stanu tej ćwiartki. Następnie możemy użyć state w kodzie dla tego ramienia, w ten sposób:

#[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!("Moneta stanowa z {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

Gdybyśmy wywołali value_in_cents(Coin::Quarter(UsState::Alaska)), coin byłby Coin::Quarter(UsState::Alaska). Kiedy porównamy tę wartość z każdym z ramion match, żadne z nich nie pasuje, dopóki nie dotrzemy do Coin::Quarter(state). W tym momencie wiązanie dla state będzie wartością UsState::Alaska. Możemy następnie użyć tego wiązania w wyrażeniu println!, uzyskując w ten sposób wewnętrzną wartość stanu z wariantu enum Coin dla Quarter.

Wzorzec Option<T> match

W poprzedniej sekcji chcieliśmy wydobyć wewnętrzną wartość T z przypadku Some podczas używania Option<T>; możemy również obsługiwać Option<T> za pomocą match, tak jak zrobiliśmy to z enumem Coin! Zamiast porównywać monety, będziemy porównywać warianty Option<T>, ale sposób działania wyrażenia match pozostaje taki sam.

Powiedzmy, że chcemy napisać funkcję, która przyjmuje Option<i32> i, jeśli w środku jest wartość, dodaje do niej 1. Jeśli w środku nie ma wartości, funkcja powinna zwrócić wartość None i nie próbować wykonywać żadnych operacji.

Tę funkcję bardzo łatwo napisać, dzięki match, i będzie ona wyglądać jak Listing 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);
}

Przyjrzyjmy się dokładniej pierwszemu wykonaniu plus_one. Kiedy wywołujemy plus_one(five), zmienna x w ciele plus_one będzie miała wartość Some(5). Następnie porównujemy ją z każdym ramieniem 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);
}

Wartość Some(5) nie pasuje do wzorca None, więc przechodzimy do następnego ramienia:

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

Czy Some(5) pasuje do Some(i)? Tak! Mamy ten sam wariant. i wiąże się z wartością zawartą w Some, więc i przyjmuje wartość 5. Następnie kod w ramieniu match jest wykonywany, więc dodajemy 1 do wartości i i tworzymy nową wartość Some z naszym łącznym 6 w środku.

Rozważmy teraz drugie wywołanie plus_one w Listingu 6-5, gdzie x jest None. Wchodzimy do match i porównujemy z pierwszym ramieniem:

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

Pasuje! Nie ma wartości do dodania, więc program zatrzymuje się i zwraca wartość None po prawej stronie =>. Ponieważ pierwsze ramię pasowało, żadne inne ramiona nie są porównywane.

Łączenie match i enumów jest przydatne w wielu sytuacjach. Będziesz często widział ten wzorzec w kodzie Rust: match z enumem, powiązanie zmiennej z danymi wewnątrz, a następnie wykonanie kodu na tej podstawie. Na początku jest to trochę trudne, ale gdy się do tego przyzwyczaisz, będziesz żałował, że nie miałeś tego we wszystkich językach. Jest to konsekwentnie ulubiona funkcja użytkowników.

Dopasowania są wyczerpujące

Jest jeszcze jeden aspekt match, który musimy omówić: wzorce ramion muszą obejmować wszystkie możliwości. Rozważmy tę wersję naszej funkcji plus_one, która zawiera błąd i nie skompiluje się:

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

Nie obsłużyliśmy przypadku None, więc ten kod spowoduje błąd. Na szczęście jest to błąd, który Rust potrafi wyłapać. Jeśli spróbujemy skompilować ten kod, otrzymamy taki błąd:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` nie pokryto
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ wzorzec `None` nie pokryto
  |
note: `Option<i32>` zdefiniowano tutaj
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: nie pokryto
  = note: dopasowana wartość jest typu `Option<i32>`
help: upewnij się, że wszystkie możliwe przypadki są obsługiwane, dodając ramię dopasowania z wzorcem wieloznacznym lub jawnym wzorcem, jak pokazano
  |
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 wie, że nie objęliśmy każdego możliwego przypadku i nawet wie, który wzorzec pominęliśmy! Dopasowania w Rust są wyczerpujące: Musimy wyczerpać każdą ostatnią możliwość, aby kod był poprawny. Zwłaszcza w przypadku Option<T>, gdy Rust uniemożliwia nam zapomnienie o jawnej obsłudze przypadku None, chroni nas przed zakładaniem, że mamy wartość, gdy możemy mieć null, co uniemożliwia popełnienie błędu miliarda dolarów, o którym mówiliśmy wcześniej.

Wzorce ogólne (Catch-All) i symbol zastępczy _

Używając typów wyliczeniowych, możemy również podejmować specjalne działania dla kilku konkretnych wartości, ale dla wszystkich innych wartości podjąć jedno domyślne działanie. Wyobraźmy sobie, że implementujemy grę, w której, jeśli na rzucie kostką wypadnie 3, gracz nie rusza się, ale zamiast tego dostaje fantazyjny nowy kapelusz. Jeśli wypadnie 7, gracz traci fantazyjny kapelusz. Dla wszystkich innych wartości, gracz przesuwa się o tę liczbę pól na planszy. Oto match, który implementuje tę logikę, z wynikiem rzutu kostką zakodowanym na stałe, a nie wartością losową, a cała inna logika jest reprezentowana przez funkcje bez ciał, ponieważ ich faktyczne zaimplementowanie wykracza poza zakres tego przykładu:

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 fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

Dla pierwszych dwóch gałęzi wzorcami są literały 3 i 7. Dla ostatniej gałęzi, która obejmuje wszystkie inne możliwe wartości, wzorcem jest zmienna, którą nazwaliśmy other. Kod uruchamiany dla gałęzi other używa zmiennej, przekazując ją do funkcji move_player.

Ten kod kompiluje się, chociaż nie wymieniliśmy wszystkich możliwych wartości, jakie może mieć u8, ponieważ ostatni wzorzec będzie pasował do wszystkich wartości, które nie zostały specjalnie wymienione. Ten wzorzec typu catch-all spełnia wymóg, że match musi być wyczerpujące. Zauważ, że musimy umieścić ramię typu catch-all na końcu, ponieważ wzorce są oceniane po kolei. Gdybyśmy umieścili ramię typu catch-all wcześniej, inne ramiona nigdy by się nie uruchomiły, więc Rust ostrzeże nas, jeśli dodamy ramiona po catch-all!

Rust posiada również wzorzec, którego możemy użyć, gdy chcemy zastosować wzorzec ogólny, ale nie chcemy używać wartości w tym wzorcu: _ to specjalny wzorzec, który pasuje do dowolnej wartości i nie wiąże się z tą wartością. To mówi Rustowi, że nie będziemy używać tej wartości, więc Rust nie ostrzeże nas o nieużywanej zmiennej.

Zmieńmy zasady gry: teraz, jeśli wyrzucisz coś innego niż 3 lub 7, musisz rzucić ponownie. Nie potrzebujemy już używać wartości typu catch-all, więc możemy zmienić nasz kod, aby używał _ zamiast zmiennej o nazwie 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() {}
}

Ten przykład również spełnia wymóg wyczerpującego dopasowania, ponieważ jawnie ignorujemy wszystkie inne wartości w ostatnim ramieniu; niczego nie pominęliśmy.

Na koniec zmienimy zasady gry jeszcze raz, tak aby nic innego nie działo się w Twojej turze, jeśli wyrzucisz coś innego niż 3 lub 7. Możemy to wyrazić, używając wartości jednostkowej (typu pustej krotki, o której wspominaliśmy w sekcji „Typ krotki”) jako kodu, który towarzyszy ramieniu _:

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

Tutaj jawnie mówimy Rustowi, że nie zamierzamy używać żadnej innej wartości, która nie pasuje do wzorca w poprzednim ramieniu, i nie chcemy uruchamiać żadnego kodu w tym przypadku.

Więcej o wzorcach i dopasowywaniu omówimy w Rozdziale 19. Na razie przejdziemy do składni if let, która może być użyteczna w sytuacjach, gdy wyrażenie match jest nieco rozwlekłe.

Zwięzła kontrola przepływu z `if let` i `let...else`

Zwięzła kontrola przepływu z if let i let...else

Składnia if let pozwala połączyć if i let w mniej rozwlekły sposób obsługi wartości pasujących do jednego wzorca, ignorując pozostałe. Rozważ program z Listingu 6-6, który dopasowuje wartość Option<u8> w zmiennej config_max, ale chce wykonać kod tylko wtedy, gdy wartość jest wariantem Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("Maksymalna wartość skonfigurowana to {max}"),
        _ => (),
    }
}

Jeśli wartość jest Some, drukujemy wartość z wariantu Some, wiążąc ją ze zmienną max we wzorcu. Nie chcemy nic robić z wartością None. Aby spełnić wyrażenie match, musimy dodać _ => () po przetworzeniu tylko jednego wariantu, co jest irytującym, powtarzalnym kodem do dodania.

Zamiast tego, moglibyśmy to napisać w krótszy sposób za pomocą if let. Poniższy kod zachowuje się tak samo jak match w Listingu 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("Maksymalna wartość skonfigurowana to {max}");
    }
}

Składnia if let przyjmuje wzorzec i wyrażenie oddzielone znakiem równości. Działa tak samo jak match, gdzie wyrażenie jest przekazywane do match, a wzorzec jest jego pierwszym ramieniem. W tym przypadku wzorzec to Some(max), a max wiąże się z wartością wewnątrz Some. Możemy następnie użyć max w ciele bloku if let w ten sam sposób, w jaki użyliśmy max w odpowiadającym ramieniu match. Kod w bloku if let jest wykonywany tylko wtedy, gdy wartość pasuje do wzorca.

Używanie if let oznacza mniej pisania, mniej wcięć i mniej kodu szablonowego. Tracisz jednak wyczerpujące sprawdzanie, które wymusza match, a które gwarantuje, że nie zapomnisz obsłużyć żadnych przypadków. Wybór między match a if let zależy od tego, co robisz w konkretnej sytuacji i czy zyskanie zwięzłości jest odpowiednim kompromisem za utratę wyczerpującego sprawdzania.

Innymi słowy, if let można traktować jako składnię cukrową dla match, która uruchamia kod, gdy wartość pasuje do jednego wzorca, a następnie ignoruje wszystkie inne wartości.

Możemy dołączyć else do if let. Blok kodu, który towarzyszy else, jest taki sam jak blok kodu, który towarzyszyłby przypadkowi _ w wyrażeniu match równoważnym if let i else. Przypomnij sobie definicję enum Coin w Listingu 6-4, gdzie wariant Quarter zawierał również wartość UsState. Gdybyśmy chcieli zliczać wszystkie monety inne niż ćwierćdolarówki, jednocześnie ogłaszając stan ćwierćdolarówek, moglibyśmy to zrobić za pomocą wyrażenia match, tak jak to:

#[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!("Moneta stanowa z {state:?}!"),
        _ => count += 1,
    }
}

Albo moglibyśmy użyć wyrażenia if let i else, w ten sposób:

#[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!("Moneta stanowa z {state:?}!");
    } else {
        count += 1;
    }
}

Pozostawanie na „szczęśliwej ścieżce” z let...else

Częstym wzorcem jest wykonanie pewnego obliczenia, gdy wartość jest obecna, a w przeciwnym razie zwrócenie wartości domyślnej. Kontynuując nasz przykład monet z wartością UsState, gdybyśmy chcieli powiedzieć coś zabawnego w zależności od wieku stanu na monecie, moglibyśmy wprowadzić metodę w UsState do sprawdzania wieku stanu, w ten sposób:

#[derive(Debug)] // abyśmy mogli za chwilę sprawdzić stan
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:?} jest dość stare, jak na Amerykę!"))
        } else {
            Some(format!("{state:?} jest stosunkowo nowe."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Następnie, moglibyśmy użyć if let, aby dopasować typ monety, wprowadzając zmienną state w treści warunku, jak w Listingu 6-7.

#[derive(Debug)] // abyśmy mogli za chwilę sprawdzić stan
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:?} jest dość stare, jak na Amerykę!"))
        } else {
            Some(format!("{state:?} jest stosunkowo nowe."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

To załatwia sprawę, ale przenosi pracę do ciała instrukcji if let, a jeśli praca do wykonania jest bardziej skomplikowana, trudno może być dokładnie śledzić, jak gałęzie najwyższego poziomu się ze sobą łączą. Moglibyśmy również wykorzystać fakt, że wyrażenia produkują wartość, aby albo wyprodukować state z if let, albo zwrócić wcześnie, jak w Listingu 6-8. (Podobną rzecz można by zrobić z match.)

#[derive(Debug)] // abyśmy mogli za chwilę sprawdzić stan
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:?} jest dość stare, jak na Amerykę!"))
    } else {
        Some(format!("{state:?} jest stosunkowo nowe."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

To jest w pewnym sensie trochę irytujące! Jedna gałąź if let produkuje wartość, a druga całkowicie zwraca z funkcji.

Aby ten powszechny wzorzec był łatwiejszy do wyrażenia, Rust posiada let...else. Składnia let...else przyjmuje wzorzec po lewej stronie i wyrażenie po prawej, bardzo podobnie do if let, ale nie ma gałęzi if, tylko gałąź else. Jeśli wzorzec pasuje, to wiąże wartość ze wzorca w zewnętrznym zasięgu. Jeśli wzorzec nie pasuje, program przechodzi do gałęzi else, która musi zwrócić wartość z funkcji.

W Listingu 6-9 możesz zobaczyć, jak wygląda Listing 6-8, gdy używamy let...else zamiast if let.

#[derive(Debug)] // abyśmy mogli za chwilę sprawdzić stan
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:?} jest dość stare, jak na Amerykę!"))
    } else {
        Some(format!("{state:?} jest stosunkowo nowe."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

Zauważ, że w ten sposób pozostaje ona na „szczęśliwej ścieżce” w głównym ciele funkcji, bez znacząco różniącego się przepływu sterowania dla dwóch gałęzi, tak jak to było w przypadku if let.

Jeśli znajdziesz się w sytuacji, w której logika Twojego programu jest zbyt rozwlekła, aby wyrazić ją za pomocą match, pamiętaj, że if let i let...else również są w Twojej skrzynce narzędziowej Rust.

Podsumowanie

Omówiliśmy, jak używać typów wyliczeniowych do tworzenia niestandardowych typów, które mogą być jednym z zestawu wyliczonych wartości. Pokazaliśmy, jak typ Option<T> z biblioteki standardowej pomaga używać systemu typów do zapobiegania błędom. Gdy wartości wyliczeniowe zawierają dane, możesz użyć match lub if let do wyodrębnienia i użycia tych wartości, w zależności od liczby przypadków, które musisz obsłużyć.

Twoje programy w Rust mogą teraz wyrażać koncepcje w Twojej dziedzinie za pomocą struktur i typów wyliczeniowych. Tworzenie niestandardowych typów do użycia w Twoim API zapewnia bezpieczeństwo typów: kompilator upewni się, że Twoje funkcje otrzymują tylko wartości typu, którego oczekuje każda funkcja.

Aby zapewnić użytkownikom dobrze zorganizowane API, które jest proste w użyciu i eksponuje dokładnie to, czego będą potrzebować, przejdźmy teraz do modułów Rust.

Pakiety, Kapsuły (Crate) i Moduły

W miarę pisania dużych programów organizacja kodu staje się coraz ważniejsza.Grupując powiązane funkcjonalności i oddzielając kod o różnych cechach,wyjaśnisz, gdzie znaleźć kod implementujący określoną funkcję i gdzieudać się, aby zmienić sposób działania funkcji.

Napisane do tej pory programy znajdowały się w jednym module w jednym pliku. W miarę rozrastania się projektu, kod powinien być dzielony na wiele modułów, a następnie na wiele plików. Pakiet może zawierać wiele kapsuł binarnych i opcjonalnie jedną kapsułę biblioteczną. W miarę rozrastania się pakietu, można wyodrębnić jego części do osobnych kapsuł, które stają się zewnętrznymi zależnościami. Ten rozdział obejmuje wszystkie te techniki. Dla bardzo dużych projektów składających się z zestawu powiązanych ze sobą pakietów, które ewoluują razem, Cargo oferuje obszary robocze, które omówimy w sekcji „Obszary robocze Cargo” w Rozdziale 14.

Omówimy również hermetyzację szczegółów implementacji, co pozwala na ponowne wykorzystanie kodu na wyższym poziomie: po zaimplementowaniu operacji, inny kod może wywołać twój kod za pośrednictwem jego publicznego interfejsu, bez konieczności znajomości działania implementacji. Sposób, w jaki piszesz kod, określa, które części są publiczne do użytku przez inny kod, a które są prywatnymi szczegółami implementacji, które zastrzegasz sobie prawo do zmiany. Jest to kolejny sposób na ograniczenie ilości szczegółów, które musisz mieć w głowie.

Powiązaną koncepcją jest zasięg: zagnieżdżony kontekst, w którym pisany jest kod, ma zestaw nazw, które są zdefiniowane jako „w zasięgu”. Podczas czytania, pisania i kompilowania kodu, programiści i kompilatory muszą wiedzieć, czy dana nazwa w danym miejscu odnosi się do zmiennej, funkcji, struktury, typu wyliczeniowego, modułu, stałej lub innego elementu i co ten element oznacza. Możesz tworzyć zasięgi i zmieniać, które nazwy są w zasięgu lub poza nim. Nie możesz mieć dwóch elementów o tej samej nazwie w tym samym zasięgu; dostępne są narzędzia do rozwiązywania konfliktów nazw.

Rust ma szereg funkcji, które pozwalają zarządzać organizacją kodu, w tym to, które szczegóły są ujawniane, które są prywatne i jakie nazwy znajdują się w każdym zasięgu w twoich programach. Te funkcje, czasami zbiorczo nazywane systemem modułów, obejmują:

• Pakiety: Funkcja Cargo, która umożliwia budowanie, testowanie i udostępnianie kapsuł (crates)
• Kapsuły (Crates): Drzewo modułów, które produkuje bibliotekę lub plik wykonywalny
• Moduły i use: Pozwalają kontrolować organizację, zasięg i prywatność ścieżek
• Ścieżki: Sposób nazywania elementu, takiego jak struktura, funkcja lub moduł

W tym rozdziale omówimy wszystkie te funkcje, dowiemy się, jak ze sobą współdziałają i wyjaśnimy, jak używać ich do zarządzania zasięgiem. Na koniec powinieneś mieć solidne zrozumienie systemu modułów i być w stanie pracować z zasięgami jak profesjonalista!

Pakiety i Kapsuły (Crate)

Pakiety i Kapsuły (Crate)

Pierwsze części systemu modułów, które omówimy, to pakiety i kapsuły.

Kapsuła (crate) to najmniejsza ilość kodu, jaką kompilator Rust rozważa w danym momencie. Nawet jeśli uruchomisz rustc zamiast cargo i przekażesz pojedynczy plik źródłowy (tak jak zrobiliśmy to w sekcji „Podstawy programu w Rust” w Rozdziale 1), kompilator traktuje ten plik jako kapsułę. Kapsuły mogą zawierać moduły, a moduły mogą być zdefiniowane w innych plikach, które są kompilowane razem z kapsułą, jak zobaczymy w kolejnych sekcjach.

Kapsuła może występować w jednej z dwóch form: kapsuła binarna lub kapsuła biblioteczna. Kapsuły binarne to programy, które można skompilować do pliku wykonywalnego, który można uruchomić, na przykład program wiersza poleceń lub serwer. Każda z nich musi mieć funkcję o nazwie main, która definiuje, co dzieje się, gdy plik wykonywalny jest uruchamiany. Wszystkie kapsuły, które do tej pory utworzyliśmy, były kapsułami binarnymi.

Kapsuły biblioteczne nie mają funkcji main i nie kompilują się do pliku wykonywalnego. Zamiast tego definiują funkcjonalność przeznaczoną do współdzielenia z wieloma projektami. Na przykład, kapsuła rand, której użyliśmy w Rozdziale 2, zapewnia funkcjonalność generowania liczb losowych. Przez większość czasu, gdy Rustaceans mówią „kapsuła”, mają na myśli kapsułę biblioteczną, i używają „kapsuły” zamiennie z ogólną koncepcją programistyczną „biblioteka”.

Katalog główny kapsuły (crate root) to plik źródłowy, od którego kompilator Rust zaczyna i który stanowi moduł główny twojej kapsuły (szczegółowo wyjaśnimy moduły w sekcji „Kontrola zasięgu i prywatności za pomocą modułów”).

Pakiet to zbiór jednej lub więcej kapsuł (crates), które zapewniają zestaw funkcjonalności. Pakiet zawiera plik Cargo.toml, który opisuje, jak zbudować te kapsuły. Cargo jest faktycznie pakietem, który zawiera kapsułę binarną dla narzędzia wiersza poleceń, którego używałeś do budowania swojego kodu. Pakiet Cargo zawiera również kapsułę biblioteczną, od której zależy kapsuła binarna. Inne projekty mogą zależeć od kapsuły bibliotecznej Cargo, aby używać tej samej logiki, której używa narzędzie wiersza poleceń Cargo.

Pakiet może zawierać dowolną liczbę kapsuł binarnych, ale co najwyżej jedną kapsułę biblioteczną. Pakiet musi zawierać co najmniej jedną kapsułę, niezależnie od tego, czy jest to kapsuła biblioteczna, czy binarna.

Przeanalizujmy, co dzieje się, gdy tworzymy pakiet. Najpierw wpisujemy polecenie 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

Po uruchomieniu cargo new my-project używamy ls, aby zobaczyć, co Cargo tworzy. W katalogu my-project znajduje się plik Cargo.toml, dając nam pakiet. Jest też katalog src, który zawiera main.rs. Otwórz Cargo.toml w swoim edytorze tekstu i zauważ, że nie ma tam wzmianki o src/main.rs. Cargo przestrzega konwencji, że src/main.rs jest katalogiem głównym kapsuły binarnej o tej samej nazwie co pakiet. Podobnie, Cargo wie, że jeśli katalog pakietu zawiera src/lib.rs, pakiet zawiera kapsułę biblioteczną o tej samej nazwie co pakiet, a src/lib.rs jest jej katalogiem głównym. Cargo przekazuje pliki katalogu głównego kapsuły do rustc w celu zbudowania biblioteki lub pliku binarnego.

Tutaj mamy pakiet, który zawiera tylko src/main.rs, co oznacza, że zawiera tylko kapsułę binarną o nazwie my-project. Jeśli pakiet zawiera src/main.rs i src/lib.rs, ma dwie kapsuły: binarną i biblioteczną, obie o tej samej nazwie co pakiet. Pakiet może mieć wiele kapsuł binarnych, umieszczając pliki w katalogu src/bin: każdy plik będzie osobną kapsułą binarną.

Kontrola zasięgu i prywatności za pomocą modułów

Kontrola zasięgu i prywatności za pomocą modułów

W tej sekcji omówimy moduły i inne części systemu modułów, a mianowicie ścieżki, które pozwalają nadawać nazwy elementom; słowo kluczowe use, które wprowadza ścieżkę do zasięgu; oraz słowo kluczowe pub, aby uczynić elementy publicznymi. Omówimy również słowo kluczowe as, pakiety zewnętrzne i operator glob.

Ściągawka z modułów

Zanim przejdziemy do szczegółów modułów i ścieżek, przedstawiamy tutaj szybkie odniesienie do tego, jak działają moduły, ścieżki, słowo kluczowe use i słowo kluczowe pub w kompilatorze, oraz jak większość programistów organizuje swój kod. Przejdziemy przez przykłady każdej z tych reguł w tym rozdziale, ale jest to świetne miejsce, aby odwołać się do nich jako przypomnienie o tym, jak działają moduły.

• Zacznij od korzenia kapsuły (crate root): Podczas kompilowania kapsuły, kompilator najpierw szuka kodu do skompilowania w pliku korzenia kapsuły (zazwyczaj src/lib.rs dla kapsuły bibliotecznej i src/main.rs dla kapsuły binarnej).
• Deklarowanie modułów: W pliku korzenia kapsuły możesz zadeklarować nowe moduły; powiedzmy, że deklarujesz moduł „garden” za pomocą mod garden;. Kompilator będzie szukał kodu modułu w tych miejscach:
  • Wbudowane, w nawiasach klamrowych, które zastępują średnik po mod garden
  • W pliku src/garden.rs
  • W pliku src/garden/mod.rs
• Deklarowanie podmodułów: W dowolnym pliku innym niż korzeń kapsuły możesz deklarować podmoduły. Na przykład, możesz zadeklarować mod vegetables; w src/garden.rs. Kompilator będzie szukał kodu podmodułu w katalogu nazwanym dla modułu rodzicielskiego w tych miejscach:
  • Wbudowane, bezpośrednio po mod vegetables, w nawiasach klamrowych zamiast średnika
  • W pliku src/garden/vegetables.rs
  • W pliku src/garden/vegetables/mod.rs
• Ścieżki do kodu w modułach: Gdy moduł jest częścią twojej kapsuły, możesz odwoływać się do kodu w tym module z dowolnego innego miejsca w tej samej kapsule, o ile zasady prywatności na to pozwalają, używając ścieżki do kodu. Na przykład, typ Asparagus w module warzyw ogrodowych znajdowałby się pod crate::garden::vegetables::Asparagus.
• Prywatne vs publiczne: Kod w module jest domyślnie prywatny dla jego modułów nadrzędnych. Aby moduł był publiczny, zadeklaruj go za pomocą pub mod zamiast mod. Aby elementy w publicznym module były również publiczne, użyj pub przed ich deklaracjami.
• Słowo kluczowe use: W zasięgu, słowo kluczowe use tworzy skróty do elementów, aby zmniejszyć powtarzanie długich ścieżek. W każdym zasięgu, który może odwoływać się do crate::garden::vegetables::Asparagus, możesz utworzyć skrót za pomocą use crate::garden::vegetables::Asparagus;, a odtąd musisz tylko napisać Asparagus, aby użyć tego typu w zasięgu.

Tutaj tworzymy binarną kapsułę o nazwie backyard, która ilustruje te zasady. Katalog kapsuły, również nazwany backyard, zawiera następujące pliki i katalogi:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Plik główny kapsuły w tym przypadku to src/main.rs, i zawiera:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("Rosnę {plant:?}!");
}

Linia pub mod garden; informuje kompilator, aby uwzględnił kod znajdujący się w pliku src/garden.rs, który to plik zawiera:

pub mod vegetables;

Tutaj, pub mod vegetables; oznacza, że kod z src/garden/vegetables.rs również jest włączony. Ten kod to:

#[derive(Debug)]
pub struct Asparagus {}

Teraz przejdźmy do szczegółów tych zasad i pokażmy je w działaniu!

Grupowanie powiązanego kodu w modułach

Moduły pozwalają nam organizować kod w ramach kapsuły w celu zwiększenia czytelności i łatwego ponownego użycia. Moduły pozwalają nam również kontrolować prywatność elementów, ponieważ kod w module jest domyślnie prywatny. Prywatne elementy to wewnętrzne szczegóły implementacji niedostępne do użytku zewnętrznego. Możemy zdecydować się na uczynienie modułów i elementów w nich publicznymi, co udostępnia je, aby umożliwić zewnętrznemu kodowi ich używanie i zależność od nich.

Na przykład, napiszmy bibliotekę, która zapewnia funkcjonalność restauracji. Zdefiniujemy sygnatury funkcji, ale pozostawimy ich ciała puste, aby skoncentrować się na organizacji kodu, a nie na implementacji restauracji.

W branży restauracyjnej niektóre części restauracji są nazywane „front of house”, a inne „back of house”. Front of house to miejsce, gdzie są klienci; obejmuje to miejsca, gdzie gospodarze sadzają klientów, kelnerzy przyjmują zamówienia i płatności, a barmani przygotowują napoje. Back of house to miejsce, gdzie szefowie kuchni i kucharze pracują w kuchni, zmywacze naczyń sprzątają, a menedżerowie wykonują prace administracyjne.

Aby ustrukturyzować naszą kapsułę w ten sposób, możemy zorganizować jej funkcje w zagnieżdżone moduły. Utwórz nową bibliotekę o nazwie restaurant, uruchamiając cargo new restaurant --lib. Następnie wprowadź kod z Listingu 7-1 do pliku src/lib.rs, aby zdefiniować niektóre moduły i sygnatury funkcji; ten kod to sekcja „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() {}
    }
}

Definiujemy moduł za pomocą słowa kluczowego mod, a następnie nazwę modułu (w tym przypadku front_of_house). Ciało modułu znajduje się następnie w nawiasach klamrowych. Wewnątrz modułów możemy umieszczać inne moduły, jak w tym przypadku moduły hosting i serving. Moduły mogą również zawierać definicje innych elementów, takich jak struktury, typy wyliczeniowe, stałe, cechy, oraz, jak w Listingu 7-1, funkcje.

Używając modułów, możemy grupować powiązane definicje i nazywać ich relacje. Programiści korzystający z tego kodu mogą nawigować po kodzie na podstawie grup, zamiast czytać wszystkie definicje, co ułatwia im znalezienie odpowiednich definicji. Programiści dodający nową funkcjonalność do tego kodu wiedzieliby, gdzie umieścić kod, aby program pozostał uporządkowany.

Wcześniej wspomnieliśmy, że pliki src/main.rs i src/lib.rs nazywane są katalogami głównymi kapsuł (crate roots). Powodem ich nazwy jest to, że zawartość któregokolwiek z tych dwóch plików tworzy moduł o nazwie crate w katalogu głównym struktury modułów kapsuły, znanego jako drzewo modułów.

Listing 7-2 przedstawia drzewo modułów dla struktury z Listingu 7-1.

kapsuła (crate)
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

To drzewo pokazuje, jak niektóre moduły zagnieżdżają się w innych modułach; na przykład, hosting zagnieżdża się w front_of_house. Drzewo pokazuje również, że niektóre moduły są sąsiadami, co oznacza, że są zdefiniowane w tym samym module; hosting i serving są sąsiadami zdefiniowanymi w front_of_house. Jeśli moduł A jest zawarty w module B, mówimy, że moduł A jest dzieckiem modułu B, a moduł B jest rodzicem modułu A. Zauważ, że całe drzewo modułów jest zakorzenione pod niejawnym modułem o nazwie crate.

Drzewo modułów może przypominać drzewo katalogów systemu plików na Twoim komputerze; to bardzo trafne porównanie! Podobnie jak katalogi w systemie plików, używasz modułów do organizacji kodu. I podobnie jak pliki w katalogu, potrzebujemy sposobu na znalezienie naszych modułów.

Ścieżki do odwoływania się do elementu w drzewie modułów

Ścieżki do odwoływania się do elementu w drzewie modułów

Aby wskazać Rustowi, gdzie znaleźć element w drzewie modułów, używamy ścieżki w taki sam sposób, jak używamy ścieżki podczas nawigowania po systemie plików. Aby wywołać funkcję, musimy znać jej ścieżkę.

Ścieżka może przyjmować dwie formy:

• Ścieżka absolutna to pełna ścieżka zaczynająca się od korzenia pakietu; dla kodu z zewnętrznego pakietu ścieżka absolutna zaczyna się od nazwy pakietu, a dla kodu z bieżącego pakietu zaczyna się od literału crate.
• Ścieżka względna zaczyna się od bieżącego modułu i używa self, super lub identyfikatora w bieżącym module.

Zarówno ścieżki absolutne, jak i względne są poprzedzone jednym lub większą liczbą identyfikatorów oddzielonych podwójnymi dwukropkami (::).

Wracając do Listingu 7-1, powiedzmy, że chcemy wywołać funkcję add_to_waitlist. To samo, co zapytać: Jaka jest ścieżka do funkcji add_to_waitlist? Listing 7-3 zawiera Listing 7-1 z usuniętymi niektórymi modułami i funkcjami.

Pokażemy dwa sposoby wywołania funkcji add_to_waitlist z nowej funkcji, eat_at_restaurant, zdefiniowanej w korzeniu pakietu. Te ścieżki są poprawne, ale pozostaje jeszcze jeden problem, który uniemożliwi kompilację tego przykładu w obecnej postaci. Wyjaśnimy dlaczego za chwilę.

Funkcja eat_at_restaurant jest częścią publicznego API naszego pakietu bibliotecznego, dlatego oznaczamy ją słowem kluczowym pub. W sekcji „Udostępnianie ścieżek za pomocą słowa kluczowego pub” omówimy pub bardziej szczegółowo.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Ścieżka absolutna
    crate::front_of_house::hosting::add_to_waitlist();

    // Ścieżka względna
    front_of_house::hosting::add_to_waitlist();
}

Za pierwszym razem, gdy wywołujemy funkcję add_to_waitlist w eat_at_restaurant, używamy ścieżki absolutnej. Funkcja add_to_waitlist jest zdefiniowana w tym samym pakiecie co eat_at_restaurant, co oznacza, że możemy użyć słowa kluczowego crate do rozpoczęcia ścieżki absolutnej. Następnie dołączamy każdy kolejny moduł, aż dotrzemy do add_to_waitlist. Można sobie wyobrazić system plików o tej samej strukturze: określilibyśmy ścieżkę /front_of_house/hosting/add_to_waitlist, aby uruchomić program add_to_waitlist; użycie nazwy crate do rozpoczęcia od korzenia pakietu jest podobne do użycia / do rozpoczęcia od korzenia systemu plików w Twojej shellu.

Za drugim razem, gdy wywołujemy add_to_waitlist w eat_at_restaurant, używamy ścieżki względnej. Ścieżka zaczyna się od front_of_house, nazwy modułu zdefiniowanego na tym samym poziomie drzewa modułów co eat_at_restaurant. Tutaj odpowiednikiem w systemie plików byłaby ścieżka front_of_house/hosting/add_to_waitlist. Rozpoczęcie od nazwy modułu oznacza, że ścieżka jest względna.

Wybór między ścieżką względną a absolutną to decyzja, którą podejmiesz w zależności od projektu i od tego, czy bardziej prawdopodobne jest, że będziesz przenosić kod definicji elementu oddzielnie od kodu, który go używa, czy też razem z nim. Na przykład, gdybyśmy przenieśli moduł front_of_house i funkcję eat_at_restaurant do modułu o nazwie customer_experience, musielibyśmy zaktualizować ścieżkę absolutną do add_to_waitlist, ale ścieżka względna nadal byłaby prawidłowa. Jednak gdybyśmy przenieśli funkcję eat_at_restaurant oddzielnie do modułu o nazwie dining, ścieżka absolutna do wywołania add_to_waitlist pozostałaby taka sama, ale ścieżka względna musiałaby zostać zaktualizowana. Ogólnie preferujemy określanie ścieżek absolutnych, ponieważ bardziej prawdopodobne jest, że będziemy chcieli przenosić definicje kodu i wywołania elementów niezależnie od siebie.

Spróbujmy skompilować Listing 7-3 i dowiedzmy się, dlaczego jeszcze się nie skompiluje! Błędy, które otrzymujemy, są pokazane w Listingu 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

Komunikaty o błędach mówią, że moduł hosting jest prywatny. Innymi słowy, mamy poprawne ścieżki do modułu hosting i funkcji add_to_waitlist, ale Rust nie pozwala nam ich używać, ponieważ nie ma dostępu do prywatnych sekcji. W Rust wszystkie elementy (funkcje, metody, struktury, wyliczenia, moduły i stałe) są domyślnie prywatne dla modułów nadrzędnych. Jeśli chcesz uczynić element, taki jak funkcja lub struktura, prywatnym, umieszczasz go w module.

Elementy w module nadrzędnym nie mogą używać prywatnych elementów w modułach podrzędnych, ale elementy w modułach podrzędnych mogą używać elementów w modułach nadrzędnych. Dzieje się tak, ponieważ moduły podrzędne opakowują i ukrywają swoje szczegóły implementacji, ale moduły podrzędne mogą widzieć kontekst, w którym są zdefiniowane. Aby kontynuować naszą metaforę, pomyśl o zasadach prywatności jako o zapleczu restauracji: to, co się tam dzieje, jest prywatne dla klientów restauracji, ale menedżerowie biura mogą widzieć i robić wszystko w restauracji, którą prowadzą.

Rust zdecydował, aby system modułów działał w ten sposób, aby domyślnie ukrywać wewnętrzne szczegóły implementacji. W ten sposób wiesz, które części kodu wewnętrznego możesz zmienić bez uszkadzania kodu zewnętrznego. Jednak Rust daje możliwość udostępniania wewnętrznych części kodu modułów podrzędnych modułom nadrzędnym za pomocą słowa kluczowego pub, aby uczynić element publicznym.

Udostępnianie ścieżek za pomocą słowa kluczowego pub

Wróćmy do błędu z Listingu 7-4, który informował nas, że moduł hosting jest prywatny. Chcemy, aby funkcja eat_at_restaurant w module nadrzędnym miała dostęp do funkcji add_to_waitlist w module potomnym, więc oznaczamy moduł hosting słowem kluczowym pub, jak pokazano w Listingu 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();
}

Niestety, kod w Listingu 7-5 nadal skutkuje błędami kompilatora, jak pokazano w Listingu 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

Co się stało? Dodanie słowa kluczowego pub przed mod hosting sprawia, że moduł staje się publiczny. Dzięki tej zmianie, jeśli mamy dostęp do front_of_house, możemy uzyskać dostęp do hosting. Ale zawartość hosting jest nadal prywatna; uczynienie modułu publicznym nie sprawia, że jego zawartość staje się publiczna. Słowo kluczowe pub na module pozwala tylko kodowi w jego modułach nadrzędnych odwoływać się do niego, a nie uzyskiwać dostępu do jego wewnętrznego kodu. Ponieważ moduły są kontenerami, nie możemy wiele zdziałać, jedynie upubliczniając moduł; musimy pójść dalej i zdecydować się na upublicznienie jednego lub więcej elementów w module.

Błędy w Listingu 7-6 mówią, że funkcja add_to_waitlist jest prywatna. Zasady prywatności dotyczą również struktur, wyliczeń, funkcji i metod, a także modułów.

Upublicznijmy również funkcję add_to_waitlist, dodając słowo kluczowe pub przed jej definicją, jak w Listingu 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();
}

Teraz kod się skompiluje! Aby zobaczyć, dlaczego dodanie słowa kluczowego pub pozwala nam używać tych ścieżek w eat_at_restaurant w odniesieniu do zasad prywatności, spójrzmy na ścieżki absolutne i względne.

W ścieżce absolutnej zaczynamy od crate, korzenia drzewa modułów naszego pakietu. Moduł front_of_house jest zdefiniowany w korzeniu pakietu. Chociaż front_of_house nie jest publiczny, ponieważ funkcja eat_at_restaurant jest zdefiniowana w tym samym module co front_of_house (czyli eat_at_restaurant i front_of_house są rodzeństwem), możemy odwoływać się do front_of_house z eat_at_restaurant. Następny jest moduł hosting oznaczony pub. Mamy dostęp do modułu nadrzędnego hosting, więc możemy uzyskać dostęp do hosting. Na koniec, funkcja add_to_waitlist jest oznaczona pub, a my mamy dostęp do jej modułu nadrzędnego, więc to wywołanie funkcji działa!

W ścieżce względnej logika jest taka sama jak w ścieżce absolutnej, z wyjątkiem pierwszego kroku: zamiast zaczynać od korzenia pakietu, ścieżka zaczyna się od front_of_house. Moduł front_of_house jest zdefiniowany w tym samym module co eat_at_restaurant, więc ścieżka względna zaczynająca się od modułu, w którym zdefiniowano eat_at_restaurant, działa. Następnie, ponieważ hosting i add_to_waitlist są oznaczone jako pub, reszta ścieżki działa, a to wywołanie funkcji jest prawidłowe!

Jeśli planujesz udostępnić swój pakiet biblioteczny, aby inne projekty mogły używać Twojego kodu, Twój publiczny interfejs API jest Twoją umową z użytkownikami Twojego pakietu, która określa, w jaki sposób mogą wchodzić w interakcje z Twoim kodem. Istnieje wiele kwestii związanych z zarządzaniem zmianami w Twoim publicznym interfejsie API, aby ułatwić innym poleganie na Twoim pakiecie. Te rozważania wykraczają poza zakres tej książki; jeśli interesuje Cię ten temat, zobacz Rust API Guidelines.

Rozpoczynanie ścieżek względnych za pomocą super

Możemy konstruować ścieżki względne, które zaczynają się w module nadrzędnym, a nie w bieżącym module lub korzeniu pakietu, używając super na początku ścieżki. Jest to podobne do rozpoczynania ścieżki systemu plików składnią .., która oznacza przejście do katalogu nadrzędnego. Użycie super pozwala nam odwołać się do elementu, o którym wiemy, że znajduje się w module nadrzędnym, co może ułatwić reorganizację drzewa modułów, gdy moduł jest ściśle powiązany z nadrzędnym, ale rodzic może zostać kiedyś przeniesiony w inne miejsce w drzewie modułów.

Rozważmy kod w Listingu 7-8, który modeluje sytuację, w której szef kuchni poprawia nieprawidłowe zamówienie i osobiście dostarcza je klientowi. Funkcja fix_incorrect_order zdefiniowana w module back_of_house wywołuje funkcję deliver_order zdefiniowaną w module nadrzędnym, określając ścieżkę do deliver_order, zaczynając od super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

Funkcja fix_incorrect_order znajduje się w module back_of_house, więc możemy użyć super, aby przejść do modułu nadrzędnego back_of_house, który w tym przypadku jest crate, czyli korzeń. Stamtąd szukamy deliver_order i znajdujemy ją. Sukces! Uważamy, że moduł back_of_house i funkcja deliver_order prawdopodobnie pozostaną w tej samej relacji do siebie i zostaną przeniesione razem, jeśli zdecydujemy się na reorganizację drzewa modułów pakietu. Dlatego użyliśmy super, aby w przyszłości, w przypadku przeniesienia tego kodu do innego modułu, było mniej miejsc do aktualizacji kodu.

Upublicznianie struktur i wyliczeń

Możemy również użyć pub do oznaczenia struktur i wyliczeń jako publicznych, ale istnieje kilka dodatkowych szczegółów dotyczących użycia pub ze strukturami i wyliczeniami. Jeśli użyjemy pub przed definicją struktury, uczynimy ją publiczną, ale pola struktury nadal będą prywatne. Możemy uczynić każde pole publicznym lub nie, w zależności od przypadku. W Listingu 7-9 zdefiniowaliśmy publiczną strukturę back_of_house::Breakfast z publicznym polem toast, ale prywatnym polem seasonal_fruit. To modeluje sytuację w restauracji, gdzie klient może wybrać rodzaj pieczywa, które jest podawane do posiłku, ale szef kuchni decyduje, jakie owoce towarzyszą posiłkowi, w zależności od sezonu i dostępności w magazynie. Dostępne owoce szybko się zmieniają, więc klienci nie mogą wybierać owoców ani nawet widzieć, jakie owoce otrzymają.

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() {
    // Zamów śniadanie latem z tostami żytnimi.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Zmieniamy zdanie co do rodzaju pieczywa.
    meal.toast = String::from("Wheat");
    println!("Poproszę tost {} ", meal.toast);

    // Następna linia się nie skompiluje, jeśli ją odkomentujemy; nie możemy
    // zobaczyć ani modyfikować sezonowych owoców, które są podawane do posiłku.
    // meal.seasonal_fruit = String::from("blueberries");
}

Ponieważ pole toast w strukturze back_of_house::Breakfast jest publiczne, w eat_at_restaurant możemy zapisywać i odczytywać do pola toast używając notacji kropkowej. Zauważ, że nie możemy użyć pola seasonal_fruit w eat_at_restaurant, ponieważ seasonal_fruit jest prywatne. Spróbuj odkomentować linię modyfikującą wartość pola seasonal_fruit, aby zobaczyć, jaki błąd otrzymasz!

Należy również zauważyć, że ponieważ back_of_house::Breakfast ma prywatne pole, struktura musi udostępniać publiczną funkcję skojarzoną, która konstruuje instancję Breakfast (nazwaliśmy ją tutaj summer). Gdyby Breakfast nie miała takiej funkcji, nie moglibyśmy utworzyć instancji Breakfast w eat_at_restaurant, ponieważ nie moglibyśmy ustawić wartości prywatnego pola seasonal_fruit w eat_at_restaurant.

W przeciwieństwie do tego, jeśli upublicznimy wyliczenie, wszystkie jego warianty stają się publiczne. Potrzebujemy tylko pub przed słowem kluczowym enum, jak pokazano w Listingu 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;
}

Ponieważ upubliczniliśmy wyliczenie Appetizer, możemy używać wariantów Soup i Salad w eat_at_restaurant.

Wyliczenia nie są zbyt użyteczne, chyba że ich warianty są publiczne; byłoby uciążliwe, gdybyśmy musieli annotować wszystkie warianty wyliczeń za pomocą pub w każdym przypadku, dlatego domyślnie warianty wyliczeń są publiczne. Struktury są często użyteczne bez publicznych pól, więc pola struktur podlegają ogólnej zasadzie, że wszystko jest domyślnie prywatne, chyba że jest anotowane za pomocą pub.

Istnieje jeszcze jedna sytuacja związana z pub, której nie omówiliśmy, i jest to nasza ostatnia funkcja systemu modułów: słowo kluczowe use. Najpierw omówimy use samo w sobie, a następnie pokażemy, jak łączyć pub i use.

Wprowadzanie ścieżek do zasięgu za pomocą słowa kluczowego use

Wprowadzanie ścieżek do zasięgu za pomocą słowa kluczowego use

Konieczność wypisywania pełnych ścieżek do wywoływania funkcji może być uciążliwa i powtarzalna. W Listing 7-7, niezależnie od tego, czy wybraliśmy ścieżkę absolutną, czy względną do funkcji add_to_waitlist, za każdym razem, gdy chcieliśmy wywołać add_to_waitlist, musieliśmy również określać front_of_house i hosting. Na szczęście istnieje sposób na uproszczenie tego procesu: Możemy utworzyć skrót do ścieżki za pomocą słowa kluczowego use raz, a następnie używać krótszej nazwy wszędzie indziej w danym zasięgu.

W Listing 7-11 wprowadzamy moduł crate::front_of_house::hosting do zasięgu funkcji eat_at_restaurant, tak abyśmy musieli określać jedynie hosting::add_to_waitlist, aby wywołać funkcję add_to_waitlist w 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();
}

Dodanie use i ścieżki w zasięgu jest podobne do tworzenia dowiązania symbolicznego w systemie plików. Dodając use crate::front_of_house::hosting w katalogu głównym skrzynki, hosting jest teraz prawidłową nazwą w tym zasięgu, tak jakby moduł hosting został zdefiniowany w katalogu głównym skrzynki. Ścieżki wprowadzone do zasięgu za pomocą use również sprawdzają prywatność, tak jak każda inna ścieżka.

Zwróć uwagę, że use tworzy skrót tylko dla konkretnego zasięgu, w którym występuje use. Listing 7-12 przenosi funkcję eat_at_restaurant do nowego modułu potomnego o nazwie customer, który jest wówczas innym zasięgiem niż instrukcja use, więc ciało funkcji nie skompiluje się.

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

Błąd kompilatora pokazuje, że skrót nie ma już zastosowania w module 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

Zauważ, że pojawiło się również ostrzeżenie, że use nie jest już używane w swoim zasięgu! Aby rozwiązać ten problem, przenieś use również do modułu customer lub odwołaj się do skrótu w module nadrzędnym za pomocą super::hosting w module potomnym customer.

Tworzenie idiomatycznych ścieżek use

W Listing 7-11 mogłeś się zastanawiać, dlaczego określiliśmy use crate::front_of_house::hosting, a następnie wywołaliśmy hosting::add_to_waitlist w eat_at_restaurant, zamiast określać ścieżkę use aż do funkcji add_to_waitlist, aby osiągnąć ten sam rezultat, jak w Listing 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();
}

Chociaż zarówno Listing 7-11, jak i Listing 7-13 wykonują to samo zadanie, Listing 7-11 jest idiomatycznym sposobem wprowadzania funkcji do zasięgu za pomocą use. Wprowadzenie modułu nadrzędnego funkcji do zasięgu za pomocą use oznacza, że musimy określić moduł nadrzędny podczas wywoływania funkcji. Określanie modułu nadrzędnego podczas wywoływania funkcji jasno informuje, że funkcja nie jest zdefiniowana lokalnie, jednocześnie minimalizując powtarzanie pełnej ścieżki. Kod w Listing 7-13 niejasno określa, gdzie zdefiniowano add_to_waitlist.

Z drugiej strony, podczas wprowadzania struktur, wyliczeń i innych elementów za pomocą use, idiomatyczne jest określanie pełnej ścieżki. Listing 7-14 pokazuje idiomatyczny sposób wprowadzania struktury HashMap ze standardowej biblioteki do zasięgu skrzynki binarnej.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

Nie ma mocnego powodu, dla którego ten idiom: to po prostu konwencja, która się wykształciła, a ludzie przyzwyczaili się do czytania i pisania kodu w Rust w ten sposób.

Wyjątkiem od tego idiomu jest sytuacja, gdy wprowadzamy dwa elementy o tej samej nazwie do zasięgu za pomocą instrukcji use, ponieważ Rust na to nie pozwala. Listing 7-15 pokazuje, jak wprowadzić dwa typy Result do zasięgu, które mają tę samą nazwę, ale różne moduły nadrzędne, oraz jak się do nich odwoływać.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

Jak widać, użycie modułów nadrzędnych odróżnia dwa typy Result. Gdybyśmy zamiast tego określili use std::fmt::Result i use std::io::Result, mielibyśmy dwa typy Result w tym samym zasięgu, a Rust nie wiedziałby, o który nam chodzi, gdybyśmy użyli Result.

Nadawanie nowych nazw za pomocą słowa kluczowego as

Istnieje inne rozwiązanie problemu wprowadzania dwóch typów o tej samej nazwie do tego samego zasięgu za pomocą use: Po ścieżce możemy określić as i nową lokalną nazwę, czyli alias, dla typu. Listing 7-16 pokazuje inny sposób napisania kodu z Listing 7-15 poprzez zmianę nazwy jednego z dwóch typów Result za pomocą as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

W drugiej instrukcji use wybraliśmy nową nazwę IoResult dla typu std::io::Result, która nie będzie kolidować z Result z std::fmt, który również wprowadziliśmy do zasięgu. Listing 7-15 i Listing 7-16 są uważane za idiomatyczne, więc wybór należy do Ciebie!

Ponowne eksportowanie nazw za pomocą pub use

Kiedy wprowadzamy nazwę do zasięgu za pomocą słowa kluczowego use, nazwa jest prywatna dla zasięgu, do którego ją zaimportowaliśmy. Aby umożliwić kodowi spoza tego zasięgu odwoływanie się do tej nazwy tak, jakby została zdefiniowana w tym zasięgu, możemy połączyć pub i use. Ta technika nazywa się re-eksportowaniem, ponieważ wprowadzamy element do zasięgu, ale także udostępniamy ten element innym, aby mogli go wprowadzić do swojego zasięgu.

Listing 7-17 pokazuje kod z Listing 7-11, w którym use w module głównym zostało zmienione na 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();
}

Przed tą zmianą, kod zewnętrzny musiałby wywoływać funkcję add_to_waitlist używając ścieżki restaurant::front_of_house::hosting::add_to_waitlist(), co wymagałoby również, aby moduł front_of_house był oznaczony jako pub. Teraz, gdy pub use ponownie wyeksportowało moduł hosting z modułu głównego, kod zewnętrzny może zamiast tego używać ścieżki restaurant::hosting::add_to_waitlist().

Ponowny eksport jest przydatny, gdy wewnętrzna struktura kodu różni się od sposobu, w jaki programiści wywołujący kod myśleliby o domenie. Na przykład, w tej metaforze restauracji, osoby prowadzące restaurację myślą o „front of house” i „back of house”. Ale klienci odwiedzający restaurację prawdopodobnie nie będą myśleć o częściach restauracji w tych kategoriach. Dzięki pub use możemy pisać kod o jednej strukturze, ale udostępniać inną strukturę. Dzięki temu nasza biblioteka jest dobrze zorganizowana dla programistów pracujących nad biblioteką i programistów wywołujących bibliotekę. Inny przykład pub use i jego wpływu na dokumentację skrzynki omówimy w rozdziale 14 w sekcji „Eksportowanie wygodnego publicznego API”.

Używanie pakietów zewnętrznych

W Rozdziale 2 programowaliśmy projekt gry zgadywanek, który używał zewnętrznego pakietu rand do generowania liczb losowych. Aby użyć rand w naszym projekcie, dodaliśmy następującą linię do Cargo.toml:

rand = "0.8.5"

Dodanie rand jako zależności w Cargo.toml informuje Cargo, aby pobrał pakiet rand i wszystkie jego zależności z crates.io i udostępnił rand naszemu projektowi.

Następnie, aby wprowadzić definicje rand do zasięgu naszego pakietu, dodaliśmy linię use zaczynającą się od nazwy skrzynki, rand, i wymieniliśmy elementy, które chcieliśmy wprowadzić do zasięgu. Przypomnij sobie, że w sekcji „Generowanie liczby losowej” w Rozdziale 2 wprowadziliśmy cechę Rng do zasięgu i wywołaliśmy funkcję 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}");
}

Członkowie społeczności Rust udostępnili wiele pakietów na crates.io, a włączenie któregokolwiek z nich do Twojego pakietu obejmuje te same kroki: wymienienie ich w pliku Cargo.toml Twojego pakietu i użycie use do wprowadzenia elementów z ich skrzynek do zasięgu.

Zauważ, że standardowa biblioteka std jest również skrzynką zewnętrzną dla naszego pakietu. Ponieważ standardowa biblioteka jest dostarczana z językiem Rust, nie musimy zmieniać Cargo.toml, aby uwzględnić std. Musimy jednak odwołać się do niej za pomocą use, aby wprowadzić z niej elementy do zasięgu naszego pakietu. Na przykład, w przypadku HashMap użylibyśmy tej linii:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Jest to ścieżka absolutna zaczynająca się od std, nazwy skrzynki standardowej biblioteki.

Używanie zagnieżdżonych ścieżek do porządkowania list use

Jeśli używamy wielu elementów zdefiniowanych w tej samej skrzynce lub tym samym module, wymienianie każdego elementu w osobnej linii może zajmować dużo miejsca w naszych plikach. Na przykład, te dwie instrukcje use z gry zgadywanek w Listing 2-4 wprowadzają elementy z std do zasięgu:

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!"),
    }
}

Zamiast tego możemy użyć zagnieżdżonych ścieżek, aby wprowadzić te same elementy do zasięgu w jednej linii. Robimy to, określając wspólną część ścieżki, po której następują dwa dwukropki, a następnie nawiasy klamrowe wokół listy części ścieżek, które się różnią, jak pokazano w Listing 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!"),
    }
}

W większych programach wprowadzanie wielu elementów do zasięgu z tej samej skrzynki lub modułu za pomocą zagnieżdżonych ścieżek może znacznie zmniejszyć liczbę oddzielnych instrukcji use!

Możemy używać zagnieżdżonych ścieżek na dowolnym poziomie ścieżki, co jest przydatne przy łączeniu dwóch instrukcji use, które współdzielą podścieżkę. Na przykład, Listing 7-19 pokazuje dwie instrukcje use: jedna, która wprowadza std::io do zasięgu, i druga, która wprowadza std::io::Write do zasięgu.

use std::io;
use std::io::Write;

Wspólną częścią tych dwóch ścieżek jest std::io, i to jest kompletna pierwsza ścieżka. Aby połączyć te dwie ścieżki w jedną instrukcję use, możemy użyć self w zagnieżdżonej ścieżce, jak pokazano w Listing 7-20.

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

Ta linia wprowadza std::io i std::io::Write do zasięgu.

Importowanie elementów za pomocą operatora glob

Jeśli chcemy wprowadzić wszystkie publiczne elementy zdefiniowane w ścieżce do zasięgu, możemy określić tę ścieżkę, po której następuje operator glob *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Ta instrukcja use wprowadza wszystkie publiczne elementy zdefiniowane w std::collections do bieżącego zasięgu. Zachowaj ostrożność podczas używania operatora glob! Glob może utrudnić określenie, jakie nazwy są w zasięgu i gdzie nazwa użyta w programie została zdefiniowana. Dodatkowo, jeśli zależność zmieni swoje definicje, to co zostało zaimportowane, również się zmieni, co może prowadzić do błędów kompilatora podczas aktualizacji zależności, jeśli zależność doda definicję o tej samej nazwie co Twoja definicja w tym samym zasięgu, na przykład.

Operator glob jest często używany podczas testowania, aby wprowadzić wszystko, co jest testowane, do modułu tests; omówimy to w sekcji „Jak pisać testy” w Rozdziale 11. Operator glob jest również czasami używany jako część wzorca preludium: zobacz dokumentację standardowej biblioteki, aby uzyskać więcej informacji na temat tego wzorca.

Dzielenie modułów na różne pliki

Dzielenie modułów na różne pliki

Do tej pory wszystkie przykłady w tym rozdziale definiowały wiele modułów w jednym pliku. Kiedy moduły stają się duże, możesz chcieć przenieść ich definicje do oddzielnego pliku, aby ułatwić nawigację po kodzie.

Na przykład, zacznijmy od kodu z Listing 7-17, który miał wiele modułów restauracji. Wyodrębnimy moduły do plików zamiast definiować wszystkie moduły w pliku głównym skrzynki. W tym przypadku plikiem głównym skrzynki jest src/lib.rs, ale ta procedura działa również w przypadku skrzynek binarnych, których plikiem głównym skrzynki jest src/main.rs.

Najpierw wyodrębnimy moduł front_of_house do jego własnego pliku. Usuń kod w nawiasach klamrowych dla modułu front_of_house, pozostawiając tylko deklarację mod front_of_house;, tak aby src/lib.rs zawierał kod pokazany w Listing 7-21. Zauważ, że to nie skompiluje się, dopóki nie utworzymy pliku src/front_of_house.rs w Listing 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Następnie umieść kod, który znajdował się w nawiasach klamrowych, w nowym pliku o nazwie src/front_of_house.rs, jak pokazano w Listing 7-22. Kompilator wie, aby szukać w tym pliku, ponieważ napotkał deklarację modułu w katalogu głównym skrzynki o nazwie front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Zauważ, że plik należy załadować za pomocą deklaracji mod tylko raz w drzewie modułów. Kiedy kompilator dowie się, że plik jest częścią projektu (i wie, gdzie w drzewie modułów znajduje się kod, ze względu na miejsce, w którym umieszczono instrukcję mod), inne pliki w projekcie powinny odwoływać się do kodu załadowanego pliku, używając ścieżki do miejsca, w którym został zadeklarowany, jak opisano w sekcji „Ścieżki do odwoływania się do elementu w drzewie modułów”. Innymi słowy, mod nie jest operacją „include”, którą mogłeś widzieć w innych językach programowania.

Następnie wyodrębnimy moduł hosting do jego własnego pliku. Proces jest nieco inny, ponieważ hosting jest modułem podrzędnym front_of_house, a nie modułu głównego. Plik dla hosting umieścimy w nowym katalogu, który będzie nazwany od jego przodków w drzewie modułów, w tym przypadku src/front_of_house.

Aby rozpocząć przenoszenie hosting, zmieniamy src/front_of_house.rs, tak aby zawierał tylko deklarację modułu hosting:

pub mod hosting;

Następnie tworzymy katalog src/front_of_house i plik hosting.rs, aby zawierać definicje z modułu hosting:

pub fn add_to_waitlist() {}

Gdybyśmy zamiast tego umieścili hosting.rs w katalogu src, kompilator oczekiwałby, że kod hosting.rs będzie w module hosting zadeklarowanym w katalogu głównym skrzynki, a nie zadeklarowanym jako dziecko modułu front_of_house. Zasady kompilatora dotyczące tego, które pliki sprawdzić pod kątem kodu poszczególnych modułów, oznaczają, że katalogi i pliki bardziej ściśle odpowiadają drzewu modułów.

Alternatywne ścieżki plików

Do tej pory omówiliśmy najbardziej idiomatyczne ścieżki plików używane przez kompilator Rust, ale Rust obsługuje również starszy styl ścieżek plików. Dla modułu o nazwie front_of_house zadeklarowanego w katalogu głównym skrzynki, kompilator będzie szukał kodu modułu w:

• src/front_of_house.rs (to, co omówiliśmy)
• src/front_of_house/mod.rs (starszy styl, nadal obsługiwana ścieżka)

Dla modułu o nazwie hosting, który jest podmodułem front_of_house, kompilator będzie szukał kodu modułu w:

• src/front_of_house/hosting.rs (to, co omówiliśmy)
• src/front_of_house/hosting/mod.rs (starszy styl, nadal obsługiwana ścieżka)

Jeśli użyjesz obu stylów dla tego samego modułu, otrzymasz błąd kompilacji. Mieszanie obu stylów dla różnych modułów w tym samym projekcie jest dozwolone, ale może być mylące dla osób nawigujących po Twoim projekcie.

Główną wadą stylu, który używa plików o nazwie mod.rs, jest to, że projekt może zawierać wiele plików o nazwie mod.rs, co może prowadzić do zamieszania, gdy masz je otwarte w edytorze w tym samym czasie.

Przenieśliśmy kod każdego modułu do osobnego pliku, a drzewo modułów pozostało takie samo. Wywołania funkcji w eat_at_restaurant będą działać bez żadnych modyfikacji, mimo że definicje znajdują się w różnych plikach. Ta technika pozwala przenosić moduły do nowych plików, gdy rosną.

Zauważ, że instrukcja pub use crate::front_of_house::hosting w src/lib.rs również nie uległa zmianie, ani use nie ma wpływu na to, które pliki są kompilowane jako część skrzynki. Słowo kluczowe mod deklaruje moduły, a Rust szuka w pliku o tej samej nazwie co moduł kodu, który należy do tego modułu.

Podsumowanie

Rust pozwala dzielić pakiet na wiele skrzynek, a skrzynkę na moduły, tak aby można było odwoływać się do elementów zdefiniowanych w jednym module z innego modułu. Można to zrobić, określając ścieżki absolutne lub względne. Te ścieżki można wprowadzić do zasięgu za pomocą instrukcji use, aby można było używać krótszej ścieżki dla wielokrotnego użycia elementu w tym zasięgu. Kod modułu jest domyślnie prywatny, ale można uczynić definicje publicznymi, dodając słowo kluczowe pub.

W następnym rozdziale przyjrzymy się niektórym strukturom danych kolekcji w standardowej bibliotece, których można użyć w swoim schludnie zorganizowanym kodzie.

Wspólne kolekcje

Standardowa biblioteka Rusta zawiera szereg bardzo przydatnych struktur danych zwanych kolekcjami. Większość innych typów danych reprezentuje jedną konkretną wartość, ale kolekcje mogą zawierać wiele wartości. W przeciwieństwie do wbudowanych typów tablicowych i krotkowych, dane, na które wskazują te kolekcje, są przechowywane na stercie, co oznacza, że ilość danych nie musi być znana w czasie kompilacji i może rosnąć lub zmniejszać się w trakcie działania programu. Każdy rodzaj kolekcji ma inne możliwości i koszty, a wybór odpowiedniej dla bieżącej sytuacji to umiejętność, którą rozwiniesz z czasem. W tym rozdziale omówimy trzy kolekcje, które są bardzo często używane w programach Rust:

• Wektor umożliwia przechowywanie zmiennej liczby wartości obok siebie.
• Ciąg znaków to kolekcja znaków. Wspomnieliśmy już o typie String, ale w tym rozdziale omówimy go szczegółowo.
• Mapa haszująca umożliwia powiązanie wartości z konkretnym kluczem. Jest to szczególna implementacja bardziej ogólnej struktury danych zwanej mapą.

Aby dowiedzieć się o innych rodzajach kolekcji dostarczanych przez standardową bibliotekę, zobacz dokumentację.

Omówimy, jak tworzyć i aktualizować wektory, ciągi znaków i mapy haszujące, a także co sprawia, że każda z nich jest wyjątkowa.

Przechowywanie list wartości za pomocą wektorów

Przechowywanie list wartości za pomocą wektorów

Pierwszym typem kolekcji, który omówimy, jest Vec<T>, znany również jako wektor. Wektory umożliwiają przechowywanie wielu wartości w jednej strukturze danych, która umieszcza wszystkie wartości obok siebie w pamięci. Wektory mogą przechowywać tylko wartości tego samego typu. Są przydatne, gdy masz listę elementów, takich jak linie tekstu w pliku lub ceny przedmiotów w koszyku na zakupy.

Tworzenie nowego wektora

Aby utworzyć nowy, pusty wektor, wywołujemy funkcję Vec::new, jak pokazano w Listing 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Zauważ, że dodaliśmy tutaj adnotację typu. Ponieważ nie wstawiamy żadnych wartości do tego wektora, Rust nie wie, jakiego rodzaju elementy zamierzamy przechowywać. Jest to ważna uwaga. Wektory są implementowane przy użyciu generyków; jak używać generyków z własnymi typami, omówimy w Rozdziale 10. Na razie wiedz, że typ Vec<T> dostarczany przez standardową bibliotekę może przechowywać dowolny typ. Kiedy tworzymy wektor do przechowywania określonego typu, możemy określić typ w nawiasach ostrych. W Listing 8-1 poinformowaliśmy Rusta, że Vec<T> w v będzie przechowywać elementy typu i32.

Częściej będziesz tworzyć Vec<T> z wartościami początkowymi, a Rust wywnioskuje typ wartości, którą chcesz przechowywać, więc rzadko będziesz musiał dodawać adnotacje typu. Rust wygodnie udostępnia makro vec!, które utworzy nowy wektor przechowujący podane wartości. Listing 8-2 tworzy nowy Vec<i32> przechowujący wartości 1, 2 i 3. Typ liczby całkowitej to i32, ponieważ jest to domyślny typ liczby całkowitej, jak omówiliśmy w sekcji „Typy danych” w Rozdziale 3.

fn main() {
    let v = vec![1, 2, 3];
}

Ponieważ podaliśmy początkowe wartości i32, Rust może wywnioskować, że typ v to Vec<i32>, a adnotacja typu nie jest konieczna. Następnie przyjrzymy się, jak modyfikować wektor.

Aktualizowanie wektora

Aby utworzyć wektor, a następnie dodać do niego elementy, możemy użyć metody push, jak pokazano w Listing 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Jak w przypadku każdej zmiennej, jeśli chcemy móc zmieniać jej wartość, musimy uczynić ją mutowalną za pomocą słowa kluczowego mut, jak omówiono w Rozdziale 3. Liczby, które umieszczamy wewnątrz, są wszystkie typu i32, a Rust wnioskuje to z danych, więc nie potrzebujemy adnotacji Vec<i32>.

Odczytywanie elementów wektorów

Istnieją dwa sposoby odwoływania się do wartości przechowywanej w wektorze: poprzez indeksowanie lub za pomocą metody get. W poniższych przykładach dodaliśmy adnotacje typów wartości zwracanych przez te funkcje dla dodatkowej przejrzystości.

Listing 8-4 pokazuje obie metody dostępu do wartości w wektorze, ze składnią indeksowania i metodą get.

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

    let third: &i32 = &v[2];
    println!("Trzeci element to {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("Trzeci element to {third}"),
        None => println!("Nie ma trzeciego elementu."),
    }
}

Zauważmy kilka szczegółów. Używamy wartości indeksu 2, aby uzyskać trzeci element, ponieważ wektory są indeksowane liczbami, zaczynając od zera. Użycie & i [] daje nam odniesienie do elementu o wartości indeksu. Kiedy używamy metody get z indeksem przekazanym jako argument, otrzymujemy Option<&T>, którego możemy użyć z match.

Rust udostępnia te dwa sposoby odwoływania się do elementu, abyś mógł wybrać, jak program zachowa się, gdy spróbujesz użyć wartości indeksu spoza zakresu istniejących elementów. Na przykład, zobaczmy, co się stanie, gdy mamy wektor pięciu elementów, a następnie spróbujemy uzyskać dostęp do elementu o indeksie 100 za pomocą każdej techniki, jak pokazano w Listing 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);
}

Kiedy uruchomimy ten kod, pierwsza metoda [] spowoduje panikę programu, ponieważ odwołuje się do nieistniejącego elementu. Ta metoda jest najlepiej używana, gdy chcesz, aby program uległ awarii, jeśli istnieje próba dostępu do elementu poza końcem wektora.

Jeśli do metody get zostanie przekazany indeks spoza zakresu wektora, zwraca None bez paniki. Użyłbyś tej metody, jeśli dostęp do elementu spoza zakresu wektora może sporadycznie występować w normalnych okolicznościach. Twój kod będzie wtedy zawierał logikę do obsługi Some(&element) lub None, jak omówiono w Rozdziale 6. Na przykład, indeks może pochodzić od osoby wpisującej liczbę. Jeśli przypadkowo wpisze zbyt dużą liczbę, a program otrzyma wartość None, możesz poinformować użytkownika, ile elementów znajduje się w bieżącym wektorze i dać mu kolejną szansę na wprowadzenie prawidłowej wartości. Byłoby to bardziej przyjazne dla użytkownika niż awaria programu z powodu literówki!

Gdy program ma prawidłową referencję, sprawdzanie pożyczek (borrow checker) egzekwuje zasady własności i pożyczania (omówione w Rozdziale 4), aby upewnić się, że ta referencja i wszelkie inne referencje do zawartości wektora pozostają prawidłowe. Przypomnijmy sobie zasadę, która mówi, że nie można mieć jednocześnie mutowalnych i niemutowalnych referencji w tym samym zakresie. Ta zasada ma zastosowanie w Listing 8-6, gdzie trzymamy niemutowalną referencję do pierwszego elementu w wektorze i próbujemy dodać element na końcu. Ten program nie zadziała, jeśli później spróbujemy odwołać się do tego elementu w funkcji.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("Pierwszy element to: {first}");
}

Kompilowanie tego kodu spowoduje następujący błąd:

$ 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

Kod w Listing 8-6 może wyglądać, jakby powinien działać: Dlaczego referencja do pierwszego elementu miałaby przejmować się zmianami na końcu wektora? Ten błąd wynika ze sposobu działania wektorów: Ponieważ wektory umieszczają wartości obok siebie w pamięci, dodanie nowego elementu na końcu wektora może wymagać alokacji nowej pamięci i skopiowania starych elementów do nowej przestrzeni, jeśli nie ma wystarczająco dużo miejsca, aby umieścić wszystkie elementy obok siebie tam, gdzie wektor jest obecnie przechowywany. W takim przypadku referencja do pierwszego elementu wskazywałaby na zwolnioną pamięć. Zasady pożyczania zapobiegają programom wpadaniu w taką sytuację.

Uwaga: Aby uzyskać więcej informacji na temat szczegółów implementacji typu Vec<T>, zobacz „Rustonomicon”.

Iteracja po wartościach w wektorze

Aby kolejno uzyskiwać dostęp do każdego elementu w wektorze, iterowalibyśmy po wszystkich elementach, zamiast używać indeksów do jednoczesnego dostępu do jednego. Listing 8-7 pokazuje, jak użyć pętli for do uzyskania niemutowalnych referencji do każdego elementu w wektorze wartości i32 i ich wydrukowania.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Możemy również iterować po mutowalnych referencjach do każdego elementu w mutowalnym wektorze, aby wprowadzić zmiany do wszystkich elementów. Pętla for w Listing 8-8 doda 50 do każdego elementu.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Aby zmienić wartość, do której odwołuje się mutowalna referencja, musimy użyć operatora dereferencji *, aby uzyskać dostęp do wartości w i, zanim będziemy mogli użyć operatora +=. Więcej o operatorze dereferencji omówimy w sekcji „Śledzenie referencji do wartości” w Rozdziale 15.

Iteracja po wektorze, niezależnie od tego, czy jest niemutowalna, czy mutowalna, jest bezpieczna dzięki zasadom sprawdzania pożyczek. Gdybyśmy próbowali wstawiać lub usuwać elementy w treściach pętli for w Listing 8-7 i Listing 8-8, otrzymalibyśmy błąd kompilacji podobny do tego, który otrzymaliśmy w kodzie w Listing 8-6. Referencja do wektora, którą przechowuje pętla for, zapobiega jednoczesnej modyfikacji całego wektora.

Używanie Enum do przechowywania wielu typów

Wektory mogą przechowywać tylko wartości tego samego typu. Może to być niewygodne; z pewnością istnieją przypadki użycia, w których trzeba przechowywać listę elementów różnych typów. Na szczęście warianty enum są zdefiniowane pod tym samym typem enum, więc gdy potrzebujemy jednego typu do reprezentowania elementów różnych typów, możemy zdefiniować i użyć enum!

Na przykład, powiedzmy, że chcemy pobrać wartości z wiersza w arkuszu kalkulacyjnym, w którym niektóre kolumny w wierszu zawierają liczby całkowite, niektóre liczby zmiennoprzecinkowe, a niektóre ciągi znaków. Możemy zdefiniować enum, którego warianty będą przechowywać różne typy wartości, a wszystkie warianty enum będą traktowane jako ten sam typ: typ enum. Następnie możemy utworzyć wektor do przechowywania tego enum i w ten sposób ostatecznie przechowywać różne typy. Zilustrowaliśmy to w Listing 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("niebieski")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust musi znać typy, które będą znajdować się w wektorze w czasie kompilacji, aby dokładnie wiedzieć, ile pamięci na stercie będzie potrzebne do przechowywania każdego elementu. Musimy również wyraźnie określić, jakie typy są dozwolone w tym wektorze. Gdyby Rust pozwalał na przechowywanie dowolnego typu w wektorze, istniałoby ryzyko, że jeden lub więcej typów spowodowałoby błędy w operacjach wykonywanych na elementach wektora. Użycie enum plus wyrażenia match oznacza, że Rust zapewni w czasie kompilacji, że każdy możliwy przypadek zostanie obsłużony, jak omówiono w Rozdziale 6.

Jeśli nie znasz wyczerpującego zestawu typów, które program otrzyma w czasie wykonywania, aby przechowywać w wektorze, technika enum nie zadziała. Zamiast tego możesz użyć obiektu cechy, który omówimy w Rozdziale 18.

Teraz, gdy omówiliśmy niektóre z najczęstszych sposobów użycia wektorów, upewnij się, że zapoznałeś się z dokumentacją API, aby zapoznać się ze wszystkimi wieloma przydatnymi metodami zdefiniowanymi w Vec<T> przez standardową bibliotekę. Na przykład, oprócz push, metoda pop usuwa i zwraca ostatni element.

Usuwanie wektora usuwa jego elementy

Podobnie jak każda inna struct, wektor jest zwalniany, gdy wychodzi poza zasięg, jak to zanotowano w Listing 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // rób coś z v
    } // <- v wychodzi z zasięgu i jest zwalniane tutaj
}

Kiedy wektor zostaje usunięty, cała jego zawartość również zostaje usunięta, co oznacza, że przechowywane w nim liczby całkowite zostaną posprzątane. Sprawdzający pożyczki zapewnia, że wszelkie referencje do zawartości wektora są używane tylko wtedy, gdy sam wektor jest prawidłowy.

Przejdźmy do następnego typu kolekcji: String!

Przechowywanie tekstu zakodowanego w UTF-8 za pomocą ciągów znaków

Przechowywanie tekstu zakodowanego w UTF-8 za pomocą ciągów znaków

O ciągach znaków rozmawialiśmy w Rozdziale 4, ale teraz przyjrzymy się im bardziej szczegółowo. Nowi użytkownicy Rusta często mają problemy z ciągami znaków z powodu połączenia trzech czynników: skłonności Rusta do ujawniania możliwych błędów, ciągów znaków będących bardziej skomplikowaną strukturą danych, niż wielu programistów im przypisuje, oraz UTF-8. Czynniki te łączą się w sposób, który może wydawać się trudny, gdy pochodzisz z innych języków programowania.

Ciągi znaków omawiamy w kontekście kolekcji, ponieważ są one implementowane jako kolekcja bajtów, plus kilka metod zapewniających użyteczną funkcjonalność, gdy te bajty są interpretowane jako tekst. W tej sekcji omówimy operacje na String, które posiada każdy typ kolekcji, takie jak tworzenie, aktualizowanie i odczytywanie. Omówimy również różnice między String a innymi kolekcjami, a mianowicie, jak indeksowanie String jest skomplikowane przez różnice między tym, jak ludzie i komputery interpretują dane String.

Definiowanie ciągów znaków

Najpierw zdefiniujemy, co rozumiemy przez termin ciąg znaków. Rust ma tylko jeden typ ciągu znaków w podstawowym języku, który jest wycinkiem ciągu str, zazwyczaj występującym w formie pożyczonej, &str. W Rozdziale 4 rozmawialiśmy o wycinkach ciągów znaków, które są referencjami do danych ciągu znaków zakodowanych w UTF-8, przechowywanych gdzie indziej. Literały ciągów znaków, na przykład, są przechowywane w binarnym pliku programu i dlatego są wycinkami ciągów znaków.

Typ String, który jest dostarczany przez standardową bibliotekę Rusta, a nie zakodowany w podstawowym języku, jest rosnącym, mutowalnym, posiadającym własność, zakodowanym w UTF-8 typem ciągu znaków. Kiedy użytkownicy Rusta odwołują się do „ciągów znaków” w Rust, mogą odnosić się zarówno do typów String, jak i wycinków ciągu &str, a nie tylko do jednego z tych typów. Chociaż ta sekcja dotyczy głównie String, oba typy są intensywnie używane w standardowej bibliotece Rusta, a zarówno String, jak i wycinki ciągów znaków są zakodowane w UTF-8.

Tworzenie nowego ciągu znaków

Wiele z tych samych operacji dostępnych dla Vec<T> jest również dostępnych dla String, ponieważ String jest faktycznie implementowane jako opakowanie wokół wektora bajtów z dodatkowymi gwarancjami, ograniczeniami i możliwościami. Przykładem funkcji, która działa w ten sam sposób z Vec<T> i String, jest funkcja new do tworzenia instancji, pokazana w Listing 8-11.

fn main() {
    let mut s = String::new();
}

Ta linia tworzy nowy, pusty ciąg znaków o nazwie s, do którego możemy następnie załadować dane. Często będziemy mieli pewne początkowe dane, którymi chcemy rozpocząć ciąg znaków. W tym celu używamy metody to_string, która jest dostępna dla każdego typu implementującego cechę Display, tak jak literały ciągów znaków. Listing 8-12 pokazuje dwa przykłady.

fn main() {
    let data = "początkowa zawartość";

    let s = data.to_string();

    // Metoda działa również bezpośrednio na literale:
    let s = "początkowa zawartość".to_string();
}

Ten kod tworzy ciąg znaków zawierający początkową zawartość.

Możemy również użyć funkcji String::from do utworzenia String z literału ciągu znaków. Kod w Listing 8-13 jest równoważny kodowi w Listing 8-12, który używa to_string.

fn main() {
    let s = String::from("początkowa zawartość");
}

Ponieważ ciągi znaków są używane do wielu rzeczy, możemy używać wielu różnych generycznych API dla ciągów znaków, co daje nam wiele opcji. Niektóre z nich mogą wydawać się nadmiarowe, ale wszystkie mają swoje miejsce! W tym przypadku String::from i to_string robią to samo, więc wybór zależy od stylu i czytelności.

Pamiętaj, że ciągi znaków są zakodowane w UTF-8, więc możemy w nich zawrzeć dowolne poprawnie zakodowane dane, jak pokazano w Listing 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");
}

Wszystkie te wartości String są prawidłowe.

Aktualizowanie ciągu znaków

String może rosnąć i zmieniać swoją zawartość, podobnie jak zawartość Vec<T>, jeśli dodasz do niego więcej danych. Ponadto możesz wygodnie użyć operatora + lub makra format! do łączenia wartości String.

Dołączanie za pomocą push_str lub push

Możemy powiększyć String, używając metody push_str do dołączenia wycinka ciągu znaków, jak pokazano w Listing 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

Po tych dwóch liniach s będzie zawierać foobar. Metoda push_str przyjmuje wycinek ciągu znaków, ponieważ niekoniecznie chcemy przejąć własność parametru. Na przykład w kodzie w Listing 8-16 chcemy móc użyć s2 po dołączeniu jego zawartości do s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 to {s2}");
}

Gdyby metoda push_str przejęła własność s2, nie moglibyśmy wydrukować jego wartości w ostatniej linii. Jednak ten kod działa zgodnie z oczekiwaniami!

Metoda push przyjmuje pojedynczy znak jako parametr i dodaje go do String. Listing 8-17 dodaje literę l do String za pomocą metody push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

W rezultacie s będzie zawierać lol.

Łączenie za pomocą + lub format!

Często będziesz chciał połączyć dwa istniejące ciągi znaków. Jednym ze sposobów na to jest użycie operatora +, jak pokazano w Listing 8-18.

fn main() {
    let s1 = String::from("Witaj, ");
    let s2 = String::from("świecie!");
    let s3 = s1 + &s2; // uwaga, s1 zostało przeniesione i nie może być już użyte
}

Ciąg s3 będzie zawierał Witaj, świecie!. Powód, dla którego s1 jest już nieważne po dodaniu, oraz powód, dla którego użyliśmy referencji do s2, ma związek z sygnaturą metody, która jest wywoływana, gdy używamy operatora +. Operator + używa metody add, której sygnatura wygląda mniej więcej tak:

fn add(self, s: &str) -> String {

W standardowej bibliotece zobaczysz add zdefiniowane przy użyciu generyków i typów skojarzonych. Tutaj podstawiliśmy konkretne typy, co dzieje się, gdy wywołujemy tę metodę z wartościami String. Generyki omówimy w Rozdziale 10. Ta sygnatura daje nam wskazówki potrzebne do zrozumienia trudnych aspektów operatora +.

Po pierwsze, s2 ma &, co oznacza, że dodajemy referencję drugiego ciągu znaków do pierwszego ciągu znaków. Dzieje się tak z powodu parametru s w funkcji add: możemy dodać tylko wycinek ciągu znaków do String; nie możemy dodać dwóch wartości String razem. Ale czekaj – typ &s2 to &String, a nie &str, jak określono w drugim parametrze add. Dlaczego więc Listing 8-18 kompiluje się?

Powodem, dla którego możemy użyć &s2 w wywołaniu add, jest to, że kompilator może wymusić konwersję argumentu &String na &str. Kiedy wywołujemy metodę add, Rust używa deref coercion, która tutaj zmienia &s2 na &s2[..]. Omówimy deref coercion szczegółowo w Rozdziale 15. Ponieważ add nie przejmuje własności parametru s, s2 nadal będzie prawidłowym String po tej operacji.

Po drugie, w sygnaturze widzimy, że add przejmuje własność self, ponieważ self nie ma &. Oznacza to, że s1 w Listing 8-18 zostanie przeniesione do wywołania add i po tym nie będzie już ważne. Tak więc, chociaż let s3 = s1 + &s2; wygląda na to, że skopiuje oba ciągi i stworzy nowy, to faktycznie przejmuje własność s1, dołącza kopię zawartości s2, a następnie zwraca własność wyniku. Innymi słowy, wygląda na to, że wykonuje wiele kopii, ale tak nie jest; implementacja jest bardziej wydajna niż kopiowanie.

Jeśli potrzebujemy połączyć wiele ciągów znaków, zachowanie operatora + staje się nieporęczne:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

W tym momencie s będzie tic-tac-toe. Z tymi wszystkimi znakami + i " trudno jest zrozumieć, co się dzieje. Do łączenia ciągów znaków w bardziej skomplikowany sposób możemy zamiast tego użyć makra format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Ten kod również ustawia s na tic-tac-toe. Makro format! działa jak println!, ale zamiast drukować wynik na ekranie, zwraca String z zawartością. Wersja kodu używająca format! jest znacznie łatwiejsza do odczytania, a kod generowany przez makro format! używa referencji, dzięki czemu to wywołanie nie przejmuje własności żadnego z jego parametrów.

Indeksowanie w ciągach znaków

W wielu innych językach programowania, dostęp do pojedynczych znaków w ciągu znaków poprzez odwoływanie się do nich za pomocą indeksu jest prawidłową i powszechną operacją. Jednakże, jeśli spróbujesz uzyskać dostęp do części String za pomocą składni indeksowania w Rust, otrzymasz błąd. Rozważ nieprawidłowy kod w Listing 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

Ten kod spowoduje następujący błąd:

$ 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

Błąd opowiada historię: ciągi znaków w Rust nie obsługują indeksowania. Ale dlaczego? Aby odpowiedzieć na to pytanie, musimy omówić, jak Rust przechowuje ciągi znaków w pamięci.

Reprezentacja wewnętrzna

String jest opakowaniem na Vec<u8>. Spójrzmy na niektóre z naszych poprawnie zakodowanych przykładów ciągów znaków UTF-8 z Listing 8-14. Najpierw ten:

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

W tym przypadku len będzie równe 4, co oznacza, że wektor przechowujący ciąg znaków "Hola" ma 4 bajty długości. Każda z tych liter zajmuje 1 bajt po zakodowaniu w UTF-8. Następna linia może Cię jednak zaskoczyć (zauważ, że ten ciąg zaczyna się od wielkiej cyrylicznej litery Ze, a nie liczby 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");
}

Gdybyś został zapytany, jak długi jest ten ciąg znaków, mógłbyś powiedzieć 12. W rzeczywistości odpowiedź Rusta to 24: to liczba bajtów potrzebna do zakodowania „Здравствуйте” w UTF-8, ponieważ każda skalarna wartość Unicode w tym ciągu zajmuje 2 bajty pamięci. Dlatego indeksowanie bajtów ciągu nie zawsze będzie korelować z prawidłową skalarną wartością Unicode. Aby to zademonstrować, rozważ ten nieprawidłowy kod w Rust:

let hello = "Здравствуйте";
let answer = &hello[0];

Wiesz już, że answer nie będzie З, pierwszą literą. Po zakodowaniu w UTF-8 pierwszy bajt З to 208, a drugi to 151, więc wydawałoby się, że answer powinien faktycznie wynosić 208, ale 208 sam w sobie nie jest prawidłowym znakiem. Zwracanie 208 prawdopodobnie nie jest tym, czego użytkownik chciałby, gdyby poprosił o pierwszą literę tego ciągu; jednak to jedyne dane, które Rust ma pod indeksem bajtowym 0. Użytkownicy generalnie nie chcą, aby zwracana była wartość bajtowa, nawet jeśli ciąg zawiera tylko litery łacińskie: Gdyby &"hi"[0] był prawidłowym kodem zwracającym wartość bajtową, zwróciłby 104, a nie h.

Odpowiedź brzmi zatem, że aby uniknąć zwracania nieoczekiwanej wartości i powodowania błędów, które mogą nie zostać natychmiast wykryte, Rust w ogóle nie kompiluje tego kodu i zapobiega nieporozumieniom na wczesnym etapie procesu rozwoju.

Bajty, wartości skalarne i klastry grafemów

Inną kwestią dotyczącą UTF-8 jest to, że istnieją faktycznie trzy istotne sposoby patrzenia na ciągi znaków z perspektywy Rusta: jako bajty, wartości skalarne i klastry grafemów (najbliższe temu, co nazwalibyśmy literami).

Jeśli spojrzymy na hinduskie słowo „नमस्ते” napisane pismem dewanagari, jest ono przechowywane jako wektor wartości u8, który wygląda tak:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

To 18 bajtów i tak ostatecznie komputery przechowują te dane. Jeśli spojrzymy na nie jako skalarne wartości Unicode, czyli to, czym jest typ char w Rust, te bajty wyglądają tak:

['न', 'म', 'स', '्', 'त', 'े']

Jest tu sześć wartości char, ale czwarta i szósta nie są literami: to znaki diakrytyczne, które same w sobie nie mają sensu. W końcu, jeśli spojrzymy na nie jako klastry grafemów, otrzymamy to, co człowiek nazwałby czterema literami tworzącymi hinduskie słowo:

["न", "म", "स्", "ते"]

Rust udostępnia różne sposoby interpretacji surowych danych ciągu znaków, które przechowują komputery, tak aby każdy program mógł wybrać interpretację, której potrzebuje, niezależnie od tego, w jakim języku ludzkim są dane.

Ostatnim powodem, dla którego Rust nie pozwala nam indeksować String w celu uzyskania znaku, jest to, że operacje indeksowania mają zawsze zajmować stały czas (O(1)). Nie jest jednak możliwe zagwarantowanie takiej wydajności w przypadku String, ponieważ Rust musiałby przechodzić przez zawartość od początku do indeksu, aby określić, ile jest prawidłowych znaków.

Krojenie ciągów znaków

Indeksowanie ciągu znaków jest często złym pomysłem, ponieważ nie jest jasne, jaki powinien być typ zwracany przez operację indeksowania ciągu znaków: wartość bajtowa, znak, klaster grafemów czy wycinek ciągu znaków. Jeśli naprawdę potrzebujesz używać indeksów do tworzenia wycinków ciągu znaków, Rust prosi o większą precyzję.

Zamiast indeksowania za pomocą [] z pojedynczą liczbą, możesz użyć [] z zakresem, aby utworzyć wycinek ciągu znaków zawierający określone bajty:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

W tym przypadku s będzie &str, który zawiera pierwsze 4 bajty ciągu. Wcześniej wspomnieliśmy, że każdy z tych znaków miał 2 bajty, co oznacza, że s będzie Зд.

Gdybyśmy spróbowali podzielić tylko część bajtów znaku za pomocą czegoś takiego jak &hello[0..1], Rust panikowałby w czasie wykonywania w taki sam sposób, jakbyśmy uzyskali dostęp do nieprawidłowego indeksu w wektorze:

$ 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

Powinieneś zachować ostrożność podczas tworzenia wycinków ciągów znaków za pomocą zakresów, ponieważ może to spowodować awarię programu.

Iterowanie po ciągach znaków

Najlepszym sposobem na operowanie na fragmentach ciągów znaków jest wyraźne określenie, czy chcemy znaków, czy bajtów. W przypadku pojedynczych skalarnych wartości Unicode, użyj metody chars. Wywołanie chars na „Зд” rozdziela i zwraca dwie wartości typu char, i możesz iterować po wyniku, aby uzyskać dostęp do każdego elementu:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Ten kod wydrukuje następujące:

З
д

Alternatywnie, metoda bytes zwraca każdy surowy bajt, co może być odpowiednie dla twojej domeny:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Ten kod wydrukuje 4 bajty, które składają się na ten ciąg znaków:

208
151
208
180

Ale pamiętaj, że prawidłowe skalarne wartości Unicode mogą składać się z więcej niż 1 bajta.

Uzyskiwanie klastrów grafemów z ciągów znaków, tak jak w przypadku pisma dewanagari, jest złożone, dlatego ta funkcjonalność nie jest dostarczana przez standardową bibliotekę. Skrzynki są dostępne na crates.io, jeśli to jest funkcjonalność, której potrzebujesz.

Obsługa złożoności ciągów znaków

Podsumowując, ciągi znaków są skomplikowane. Różne języki programowania podejmują różne decyzje dotyczące tego, jak przedstawić tę złożoność programistom. Rust wybrał, aby prawidłowe obchodzenie się z danymi String było domyślnym zachowaniem dla wszystkich programów Rust, co oznacza, że programiści muszą z wyprzedzeniem poświęcić więcej uwagi obsłudze danych UTF-8. Ten kompromis ujawnia więcej złożoności ciągów znaków, niż jest to widoczne w innych językach programowania, ale zapobiega konieczności obsługi błędów związanych ze znakami spoza ASCII w późniejszym cyklu rozwoju.

Dobrą wiadomością jest to, że standardowa biblioteka oferuje wiele funkcjonalności zbudowanych na typach String i &str, aby pomóc w prawidłowym radzeniu sobie z tymi złożonymi sytuacjami. Koniecznie sprawdź dokumentację pod kątem przydatnych metod, takich jak contains do wyszukiwania w ciągu znaków i replace do zastępowania części ciągu znaków innym ciągiem znaków.

Przejdźmy do czegoś nieco mniej skomplikowanego: mapy haszujące!

Przechowywanie kluczy z powiązanymi wartościami w mapach haszujących

Przechowywanie kluczy z powiązanymi wartościami w mapach haszujących

Ostatnią z naszych wspólnych kolekcji jest mapa haszująca. Typ HashMap<K, V> przechowuje mapowanie kluczy typu K na wartości typu V za pomocą funkcji haszującej, która określa, w jaki sposób umieszcza te klucze i wartości w pamięci. Wiele języków programowania obsługuje tego rodzaju strukturę danych, ale często używają innej nazwy, takiej jak hash, map, object, hash table, dictionary lub associative array, by wymienić tylko kilka.

Mapy haszujące są przydatne, gdy chcesz wyszukiwać dane nie za pomocą indeksu, jak w przypadku wektorów, ale za pomocą klucza, który może być dowolnego typu. Na przykład w grze możesz śledzić wyniki każdej drużyny w mapie haszującej, w której każdy klucz to nazwa drużyny, a wartości to wyniki każdej drużyny. Mając nazwę drużyny, możesz pobrać jej wynik.

W tej sekcji omówimy podstawowe API map haszujących, ale wiele innych dobrodziejstw kryje się w funkcjach zdefiniowanych dla HashMap<K, V> przez standardową bibliotekę. Jak zawsze, sprawdź dokumentację standardowej biblioteki, aby uzyskać więcej informacji.

Tworzenie nowej mapy haszującej

Jednym ze sposobów utworzenia pustej mapy haszującej jest użycie new i dodanie elementów za pomocą insert. W Listing 8-20 śledzimy wyniki dwóch drużyn, których nazwy to Niebiescy i Żółci. Drużyna Niebieskich zaczyna z 10 punktami, a drużyna Żółtych z 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Niebiescy"), 10);
    scores.insert(String::from("Żółci"), 50);
}

Zauważ, że musimy najpierw use HashMap z części kolekcji standardowej biblioteki. Spośród naszych trzech wspólnych kolekcji, ta jest najrzadziej używana, więc nie jest ona domyślnie dołączana do zasięgu w preludium. Mapy haszujące mają również mniejsze wsparcie ze strony standardowej biblioteki; nie ma na przykład wbudowanego makra do ich konstruowania.

Podobnie jak wektory, mapy haszujące przechowują swoje dane na stercie. Ta HashMap ma klucze typu String i wartości typu i32. Podobnie jak wektory, mapy haszujące są jednorodne: wszystkie klucze muszą mieć ten sam typ, a wszystkie wartości muszą mieć ten sam typ.

Dostęp do wartości w mapie haszującej

Możemy pobrać wartość z mapy haszującej, podając jej klucz do metody get, jak pokazano w Listing 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Niebiescy"), 10);
    scores.insert(String::from("Żółci"), 50);

    let team_name = String::from("Niebiescy");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Tutaj score będzie miało wartość powiązaną z drużyną Niebieskich, a wynik będzie wynosił 10. Metoda get zwraca Option<&V>; jeśli dla tego klucza nie ma wartości w mapie haszującej, get zwróci None. Ten program obsługuje Option wywołując copied, aby uzyskać Option<i32> zamiast Option<&i32>, a następnie unwrap_or, aby ustawić score na zero, jeśli scores nie ma wpisu dla klucza.

Możemy iterować po każdej parze klucz-wartość w mapie haszującej w podobny sposób, jak to robimy z wektorami, używając pętli for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Niebiescy"), 10);
    scores.insert(String::from("Żółci"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Ten kod wydrukuje każdą parę w dowolnej kolejności:

Żółci: 50
Niebiescy: 10

Zarządzanie własnością w mapach haszujących

W przypadku typów implementujących cechę Copy, takich jak i32, wartości są kopiowane do mapy haszującej. W przypadku wartości posiadanych, takich jak String, wartości zostaną przeniesione, a mapa haszująca będzie właścicielem tych wartości, jak pokazano w Listing 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Ulubiony kolor");
    let field_value = String::from("Niebieski");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name i field_value są w tym momencie nieprawidłowe, spróbuj ich użyć i
    // zobacz, jaki błąd kompilacji otrzymasz!
}

Nie możemy używać zmiennych field_name i field_value po ich przeniesieniu do mapy haszującej za pomocą wywołania insert.

Jeśli wstawimy referencje do wartości do mapy haszującej, wartości nie zostaną przeniesione do mapy haszującej. Wartości, na które wskazują referencje, muszą być ważne przynajmniej tak długo, jak długo ważna jest mapa haszująca. Więcej o tych problemach omówimy w sekcji „Walidacja referencji za pomocą czasów życia” w Rozdziale 10.

Aktualizowanie mapy haszującej

Chociaż liczba par klucz-wartość może rosnąć, każdy unikalny klucz może mieć w danym momencie tylko jedną powiązaną wartość (ale nie na odwrót: na przykład, zarówno drużyna Niebieskich, jak i drużyna Żółtych mogłyby mieć wartość 10 przechowywaną w mapie haszującej scores).

Kiedy chcesz zmienić dane w mapie haszującej, musisz zdecydować, jak postąpić w przypadku, gdy klucz już ma przypisaną wartość. Możesz zastąpić starą wartość nową, całkowicie ignorując starą wartość. Możesz zachować starą wartość i zignorować nową wartość, dodając nową wartość tylko wtedy, gdy klucz nie ma jeszcze wartości. Lub możesz połączyć starą wartość i nową wartość. Przyjrzyjmy się, jak wykonać każdą z tych czynności!

Nadpisywanie wartości

Jeśli wstawimy klucz i wartość do mapy haszującej, a następnie wstawimy ten sam klucz z inną wartością, wartość powiązana z tym kluczem zostanie zastąpiona. Mimo że kod w Listing 8-23 wywołuje insert dwukrotnie, mapa haszująca będzie zawierać tylko jedną parę klucz-wartość, ponieważ dwukrotnie wstawiamy wartość dla klucza drużyny Niebieskich.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Niebiescy"), 10);
    scores.insert(String::from("Niebiescy"), 25);

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

Ten kod wydrukuje {"Niebiescy": 25}. Pierwotna wartość 10 została nadpisana.

Dodawanie klucza i wartości tylko wtedy, gdy klucz nie jest obecny

Często sprawdza się, czy dany klucz już istnieje w mapie haszującej z wartością, a następnie wykonuje następujące działania: Jeśli klucz istnieje w mapie haszującej, istniejąca wartość powinna pozostać taka, jaka jest; jeśli klucz nie istnieje, wstawia się go i wartość dla niego.

Mapy haszujące posiadają specjalne API do tego celu, zwane entry, które jako parametr przyjmuje klucz, który chcesz sprawdzić. Wartością zwracaną przez metodę entry jest enum o nazwie Entry, który reprezentuje wartość, która może istnieć lub nie. Załóżmy, że chcemy sprawdzić, czy klucz dla drużyny Żółtych ma przypisaną wartość. Jeśli nie, chcemy wstawić wartość 50, i to samo dla drużyny Niebieskich. Używając API entry, kod wygląda jak w Listing 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Niebiescy"), 10);

    scores.entry(String::from("Żółci")).or_insert(50);
    scores.entry(String::from("Niebiescy")).or_insert(50);

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

Metoda or_insert w Entry jest zdefiniowana tak, aby zwracać mutowalną referencję do wartości dla odpowiadającego klucza Entry, jeśli ten klucz istnieje, a jeśli nie, wstawia parametr jako nową wartość dla tego klucza i zwraca mutowalną referencję do nowej wartości. Ta technika jest znacznie czystsza niż samodzielne pisanie logiki i, co więcej, lepiej współpracuje z mechanizmem sprawdzania pożyczek.

Uruchomienie kodu w Listing 8-24 wydrukuje {"Żółci": 50, "Niebiescy": 10}. Pierwsze wywołanie entry wstawi klucz dla drużyny Żółtych z wartością 50, ponieważ drużyna Żółtych nie ma jeszcze wartości. Drugie wywołanie entry nie zmieni mapy haszującej, ponieważ drużyna Niebieskich ma już wartość 10.

Aktualizowanie wartości na podstawie starej wartości

Innym częstym przypadkiem użycia map haszujących jest wyszukiwanie wartości klucza, a następnie aktualizowanie jej na podstawie starej wartości. Na przykład, Listing 8-25 pokazuje kod, który zlicza, ile razy każde słowo pojawia się w tekście. Używamy mapy haszującej ze słowami jako kluczami i inkrementujemy wartość, aby śledzić, ile razy widzieliśmy to słowo. Jeśli jest to pierwszy raz, kiedy widzieliśmy słowo, najpierw wstawimy wartość 0.

fn main() {
    use std::collections::HashMap;

    let text = "cześć świat cudowny świat";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

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

Ten kod wydrukuje {"świat": 2, "cześć": 1, "cudowny": 1}. Możesz zobaczyć te same pary klucz-wartość wydrukowane w innej kolejności: przypomnij sobie z sekcji „Dostęp do wartości w mapie haszującej”, że iteracja po mapie haszującej odbywa się w dowolnej kolejności.

Metoda split_whitespace zwraca iterator po podsekcjach, rozdzielonych spacjami, wartości w text. Metoda or_insert zwraca mutowalną referencję (&mut V) do wartości dla określonego klucza. Tutaj przechowujemy tę mutowalną referencję w zmiennej count, więc aby przypisać do tej wartości, musimy najpierw dereferencjować count za pomocą gwiazdki (*). Mutowalna referencja wychodzi poza zasięg na końcu pętli for, więc wszystkie te zmiany są bezpieczne i dozwolone przez zasady pożyczania.

Funkcje haszujące

Domyślnie HashMap używa funkcji haszującej zwanej SipHash, która może zapewnić odporność na ataki typu denial-of-service (DoS) związane z tabelami haszującymi¹. Nie jest to najszybszy dostępny algorytm haszujący, ale kompromis między lepszym bezpieczeństwem a spadkiem wydajności jest tego wart. Jeśli profilujesz swój kod i stwierdzisz, że domyślna funkcja haszująca jest zbyt wolna dla Twoich celów, możesz przełączyć się na inną funkcję, określając inny haszer. Haszer to typ, który implementuje cechę BuildHasher. O cechach i sposobie ich implementacji omówimy w Rozdziale 10. Nie musisz koniecznie implementować własnego haszera od podstaw; crates.io posiada biblioteki udostępnione przez innych użytkowników Rusta, które dostarczają haszerów implementujących wiele popularnych algorytmów haszujących.

Podsumowanie

Wektory, ciągi znaków i mapy haszujące zapewnią dużą funkcjonalność niezbędną w programach, gdy trzeba przechowywać, uzyskiwać dostęp i modyfikować dane. Oto kilka ćwiczeń, które powinieneś być teraz w stanie rozwiązać:

1. Mając listę liczb całkowitych, użyj wektora i zwróć medianę (po posortowaniu, wartość na środkowej pozycji) i dominantę (wartość, która występuje najczęściej; tutaj pomocna będzie mapa haszująca) listy.
2. Przekształć ciągi znaków na języka Pig Latin. Pierwsza spółgłoska każdego słowa jest przenoszona na koniec słowa i dodawane jest ay, więc first staje się irst-fay. Słowa, które zaczynają się samogłoską, mają dodane hay na końcu (apple staje się apple-hay). Pamiętaj o szczegółach kodowania UTF-8!
3. Korzystając z mapy haszującej i wektorów, stwórz interfejs tekstowy, aby umożliwić użytkownikowi dodawanie nazw pracowników do działu w firmie; na przykład „Dodaj Sally do Inżynierii” lub „Dodaj Amira do Sprzedaży”. Następnie pozwól użytkownikowi pobrać listę wszystkich osób w dziale lub wszystkich osób w firmie według działu, posortowanych alfabetycznie.

Dokumentacja API standardowej biblioteki opisuje metody, które mają wektory, ciągi znaków i mapy haszujące, które będą pomocne w tych ćwiczeniach!

Przechodzimy do bardziej złożonych programów, w których operacje mogą zakończyć się niepowodzeniem, więc to idealny czas, aby omówić obsługę błędów. Zrobimy to w następnej kolejności!

1. https://en.wikipedia.org/wiki/SipHash ↩

Obsługa błędów

Błędy są faktem w oprogramowaniu, dlatego Rust posiada szereg funkcji do obsługi sytuacji, w których coś idzie nie tak. W wielu przypadkach Rust wymaga od Ciebie uznania możliwości błędu i podjęcia pewnych działań, zanim Twój kod się skompiluje. Ten wymóg sprawia, że Twój program jest bardziej niezawodny, zapewniając, że odkryjesz błędy i obsłużysz je odpowiednio, zanim wdrożysz swój kod do produkcji!

Rust dzieli błędy na dwie główne kategorie: błędy odzyskiwalne i nieodzyskiwalne. W przypadku błędu odzyskiwalnego, takiego jak błąd pliku nie znaleziono, najprawdopodobniej chcemy po prostu zgłosić problem użytkownikowi i ponowić operację. Błędy nieodzyskiwalne są zawsze objawami błędów, takich jak próba dostępu do lokalizacji poza końcem tablicy, dlatego chcemy natychmiast zatrzymać program.

Większość języków nie rozróżnia tych dwóch rodzajów błędów i obsługuje oba w ten sam sposób, używając mechanizmów takich jak wyjątki. Rust nie ma wyjątków. Zamiast tego, ma typ Result<T, E> dla błędów odzyskiwalnych i makro panic! które zatrzymuje wykonanie, gdy program napotka błąd nieodzyskiwalny. Ten rozdział najpierw omawia wywoływanie panic!, a następnie mówi o zwracaniu wartości Result<T, E>. Dodatkowo, zbadamy rozważania przy podejmowaniu decyzji, czy spróbować odzyskać się po błędzie, czy zatrzymać wykonanie.

Nieodwracalne błędy z panic!

Nieodwracalne błędy z panic!

Czasami w twoim kodzie dzieją się złe rzeczy i nic nie możesz na to poradzić. W takich przypadkach Rust ma makro panic!. W praktyce istnieją dwa sposoby wywołania paniki: poprzez wykonanie akcji, która powoduje panikę kodu (takiej jak dostęp do tablicy poza jej zakresem) lub poprzez jawne wywołanie makra panic!. W obu przypadkach powodujemy panikę w naszym programie. Domyślnie te paniki wyświetlą komunikat o błędzie, rozwiną stos, wyczyszczą stos i zakończą działanie. Za pomocą zmiennej środowiskowej możesz również sprawić, że Rust wyświetli stos wywołań, gdy wystąpi panika, co ułatwi śledzenie źródła paniki.

Rozwijanie stosu lub przerywanie działania w odpowiedzi na panikę

Domyślnie, gdy wystąpi panika, program zaczyna się rozwijać, co oznacza, że Rust cofa się po stosie i czyści dane z każdej napotkanej funkcji. Jednak cofanie się i czyszczenie to dużo pracy. Rust pozwala zatem wybrać alternatywę natychmiastowego przerwania, które kończy program bez czyszczenia.

Pamięć używana przez program będzie musiała zostać wyczyszczona przez system operacyjny. Jeśli w twoim projekcie musisz sprawić, aby wynikowy plik binarny był jak najmniejszy, możesz przełączyć się z rozwijania na przerwanie po panice, dodając panic = 'abort' do odpowiednich sekcji [profile] w pliku Cargo.toml. Na przykład, jeśli chcesz przerwać działanie po panice w trybie wydania, dodaj to:

[profile.release]
panic = 'abort'

Spróbujmy wywołać panic! w prostym programie:

fn main() {
    panic!("awaria i spalenie");
}

Po uruchomieniu programu zobaczysz coś takiego:

$ 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

Wywołanie panic! powoduje komunikat o błędzie zawarty w ostatnich dwóch liniach. Pierwsza linia pokazuje nasz komunikat paniki i miejsce w kodzie źródłowym, gdzie nastąpiła panika: src/main.rs:2:5 wskazuje, że jest to druga linia, piąty znak naszego pliku src/main.rs.

W tym przypadku wskazana linia jest częścią naszego kodu, a jeśli przejdziemy do tej linii, zobaczymy wywołanie makra panic!. W innych przypadkach wywołanie panic! może znajdować się w kodzie, który wywołuje nasz kod, a nazwa pliku i numer linii zgłoszone przez komunikat o błędzie będą kodem kogoś innego, gdzie wywołano makro panic!, a nie linią naszego kodu, która ostatecznie doprowadziła do wywołania panic!.

Możemy użyć śledzenia stosu funkcji, z których pochodzi wywołanie panic!, aby ustalić, która część naszego kodu powoduje problem. Aby zrozumieć, jak używać śledzenia stosu panic!, przyjrzyjmy się innemu przykładowi i zobaczmy, jak to wygląda, gdy wywołanie panic! pochodzi z biblioteki z powodu błędu w naszym kodzie, a nie z naszego kodu bezpośrednio wywołującego makro. Listing 9-1 zawiera kod, który próbuje uzyskać dostęp do indeksu w wektorze poza zakresem prawidłowych indeksów.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Tutaj próbujemy uzyskać dostęp do 100. elementu naszego wektora (który znajduje się pod indeksem 99, ponieważ indeksowanie zaczyna się od zera), ale wektor ma tylko trzy elementy. W tej sytuacji Rust wywoła panikę. Użycie [] ma zwrócić element, ale jeśli podasz nieprawidłowy indeks, Rust nie mógłby zwrócić żadnego prawidłowego elementu.

W C, próba odczytu poza końcem struktury danych jest niezdefiniowanym zachowaniem. Możesz otrzymać cokolwiek, co znajduje się w miejscu w pamięci, które odpowiadałoby temu elementowi w strukturze danych, mimo że pamięć nie należy do tej struktury. Nazywa się to przepełnieniem bufora i może prowadzić do luk w zabezpieczeniach, jeśli atakujący jest w stanie manipulować indeksem w taki sposób, aby odczytać dane, do których nie powinien mieć dostępu, a które są przechowywane po strukturze danych.

Aby chronić program przed tego rodzaju lukami, jeśli spróbujesz odczytać element o indeksie, który nie istnieje, Rust zatrzyma wykonanie i odmówi kontynuowania. Spróbujmy i zobaczmy:

$ 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

Ten błąd wskazuje na linię 4 naszego main.rs, gdzie próbujemy uzyskać dostęp do indeksu 99 wektora w v.

Linia note: mówi nam, że możemy ustawić zmienną środowiskową RUST_BACKTRACE na dowolną wartość inną niż 0, aby uzyskać śledzenie stosu (backtrace) dokładnie tego, co się stało, aby spowodować błąd. Śledzenie stosu to lista wszystkich funkcji, które zostały wywołane, aby dojść do tego punktu. Śledzenia stosu w Rust działają tak samo jak w innych językach: kluczem do odczytania śledzenia stosu jest rozpoczęcie od góry i czytanie, aż zobaczysz pliki, które napisałeś. To jest miejsce, w którym problem się rozpoczął. Linie powyżej tego miejsca to kod, który wywołał Twój kod; linie poniżej to kod, który wywołał Twój kod. Te linie przed i po mogą zawierać podstawowy kod Rust, kod standardowej biblioteki lub skrzynki, których używasz. Spróbujmy uzyskać śledzenie stosu, ustawiając zmienną środowiskową RUST_BACKTRACE na dowolną wartość inną niż 0. Listing 9-2 pokazuje wyjście podobne do tego, co zobaczysz.

$ 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.

To dużo danych wyjściowych! Dokładne dane wyjściowe mogą się różnić w zależności od systemu operacyjnego i wersji Rusta. Aby uzyskać śledzenia stosu z tymi informacjami, symbole debugowania muszą być włączone. Symbole debugowania są domyślnie włączone przy użyciu cargo build lub cargo run bez flagi --release, jak to zrobiliśmy tutaj.

W danych wyjściowych w Listing 9-2, linia 6 śledzenia stosu wskazuje na linię w naszym projekcie, która powoduje problem: linia 4 pliku src/main.rs. Jeśli nie chcemy, aby nasz program panikował, powinniśmy rozpocząć nasze dochodzenie w miejscu wskazanym przez pierwszą linię wspomniającą o pliku, który napisaliśmy. W Listing 9-1, gdzie celowo napisaliśmy kod, który wywołałby panikę, sposobem na naprawienie paniki jest nie żądanie elementu poza zakresem indeksów wektora. Gdy Twój kod panikuje w przyszłości, będziesz musiał dowiedzieć się, jaką akcję podejmuje kod z jakimi wartościami, aby spowodować panikę, i co kod powinien zrobić zamiast tego.

Powrócimy do panic! i do tego, kiedy powinniśmy, a kiedy nie powinniśmy używać panic! do obsługi warunków błędu, w sekcji „Panikować czy nie panikować!” w dalszej części tego rozdziału. Następnie przyjrzymy się, jak odzyskać się po błędzie za pomocą Result.

Błędy odzyskiwalne za pomocą Result

Błędy odzyskiwalne za pomocą Result

Większość błędów nie jest na tyle poważna, aby wymagać całkowitego zatrzymania programu. Czasami, gdy funkcja zawodzi, dzieje się tak z powodu, który można łatwo zinterpretować i na niego zareagować. Na przykład, jeśli próbujesz otworzyć plik, a ta operacja kończy się niepowodzeniem, ponieważ plik nie istnieje, możesz chcieć utworzyć plik zamiast zakończyć proces.

Przypomnij sobie z sekcji „Obsługa potencjalnych awarii za pomocą Result” w Rozdziale 2, że enum Result jest zdefiniowany tak, aby miał dwa warianty, Ok i Err, w następujący sposób:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T i E to generyczne parametry typu: bardziej szczegółowo omówimy generyki w Rozdziale 10. To, co musisz teraz wiedzieć, to to, że T reprezentuje typ wartości, która zostanie zwrócona w przypadku sukcesu w wariancie Ok, a E reprezentuje typ błędu, który zostanie zwrócony w przypadku niepowodzenia w wariancie Err. Ponieważ Result ma te generyczne parametry typu, możemy używać typu Result i zdefiniowanych na nim funkcji w wielu różnych sytuacjach, gdy wartość sukcesu i wartość błędu, którą chcemy zwrócić, mogą się różnić.

Wywołajmy funkcję, która zwraca wartość Result, ponieważ funkcja może zawieść. W Listing 9-3 próbujemy otworzyć plik.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

Typ zwracany przez File::open to Result<T, E>. Generyczny parametr T został wypełniony przez implementację File::open typem wartości sukcesu, std::fs::File, który jest uchwytem pliku. Typ E używany w wartości błędu to std::io::Error. Ten typ zwracany oznacza, że wywołanie File::open może zakończyć się sukcesem i zwrócić uchwyt pliku, z którego możemy czytać lub do którego możemy pisać. Wywołanie funkcji może również zakończyć się niepowodzeniem: na przykład plik może nie istnieć lub możemy nie mieć uprawnień do dostępu do pliku. Funkcja File::open musi mieć sposób, aby poinformować nas, czy zakończyła się sukcesem, czy niepowodzeniem, i jednocześnie podać nam uchwyt pliku lub informacje o błędzie. Te informacje to dokładnie to, co przekazuje enum Result.

W przypadku, gdy File::open zakończy się sukcesem, wartość w zmiennej greeting_file_result będzie instancją Ok, która zawiera uchwyt pliku. W przypadku, gdy zawiedzie, wartość w greeting_file_result będzie instancją Err, która zawiera więcej informacji o rodzaju błędu, który wystąpił.

Musimy uzupełnić kod w Listing 9-3, aby podejmować różne działania w zależności od wartości zwracanej przez File::open. Listing 9-4 pokazuje jeden ze sposobów obsługi Result za pomocą podstawowego narzędzia, wyrażenia match, które omówiliśmy w Rozdziale 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 z otwarciem pliku: {error:?}"),
    };
}

Zauważ, że, podobnie jak enum Option, enum Result i jego warianty zostały wprowadzone do zasięgu przez preludium, więc nie musimy określać Result:: przed wariantami Ok i Err w ramionach match.

Kiedy wynik jest Ok, ten kod zwróci wewnętrzną wartość file z wariantu Ok, a następnie przypisujemy tę wartość uchwytu pliku do zmiennej greeting_file. Po match możemy użyć uchwytu pliku do odczytu lub zapisu.

Drugie ramię match obsługuje przypadek, w którym otrzymujemy wartość Err z File::open. W tym przykładzie zdecydowaliśmy się wywołać makro panic!. Jeśli w naszym bieżącym katalogu nie ma pliku o nazwie hello.txt i uruchomimy ten kod, zobaczymy następujące dane wyjściowe z makra 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

Jak zwykle, to wyjście mówi nam dokładnie, co poszło nie tak.

Dopasowywanie różnych błędów

Kod w Listing 9-4 spowoduje panic! niezależnie od tego, dlaczego File::open zakończyło się niepowodzeniem. My jednak chcemy podejmować różne działania z różnych powodów awarii. Jeśli File::open zakończyło się niepowodzeniem, ponieważ plik nie istnieje, chcemy utworzyć plik i zwrócić uchwyt do nowego pliku. Jeśli File::open zakończyło się niepowodzeniem z jakiegokolwiek innego powodu — na przykład, ponieważ nie mieliśmy uprawnień do otwarcia pliku — nadal chcemy, aby kod spowodował panic! w ten sam sposób, jak w Listing 9-4. W tym celu dodajemy wewnętrzne wyrażenie match, pokazane w Listing 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 z tworzeniem pliku: {e:?}"),
            },
            _ => {
                panic!("Problem z otwarciem pliku: {error:?}");
            }
        },
    };
}

Typ wartości zwracanej przez File::open w wariancie Err to io::Error, który jest strukturą dostarczaną przez standardową bibliotekę. Ta struktura posiada metodę kind, którą możemy wywołać, aby uzyskać wartość io::ErrorKind. Enum io::ErrorKind jest dostarczany przez standardową bibliotekę i ma warianty reprezentujące różne rodzaje błędów, które mogą wynikać z operacji io. Wariant, którego chcemy użyć, to ErrorKind::NotFound, który wskazuje, że plik, który próbujemy otworzyć, jeszcze nie istnieje. Zatem dopasowujemy greeting_file_result, ale mamy również wewnętrzne dopasowanie na error.kind().

Warunkiem, który chcemy sprawdzić w wewnętrznym dopasowaniu, jest to, czy wartość zwrócona przez error.kind() jest wariantem NotFound enum ErrorKind. Jeśli tak, próbujemy utworzyć plik za pomocą File::create. Jednakże, ponieważ File::create również może zakończyć się niepowodzeniem, potrzebujemy drugiego ramienia w wewnętrznym wyrażeniu match. Kiedy plik nie może zostać utworzony, wyświetlany jest inny komunikat o błędzie. Drugie ramię zewnętrznego match pozostaje takie samo, więc program panikuje przy każdym błędzie innym niż błąd braku pliku.

Alternatywy dla używania match z Result<T, E>

To dużo match! Wyrażenie match jest bardzo przydatne, ale także bardzo prymitywne. W Rozdziale 13 poznasz domknięcia, które są używane z wieloma metodami zdefiniowanymi dla Result<T, E>. Te metody mogą być bardziej zwięzłe niż używanie match podczas obsługi wartości Result<T, E> w Twoim kodzie.

Na przykład, oto inny sposób napisania tej samej logiki, jak pokazano w Listing 9-5, tym razem używając domknięć i metody 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 z tworzeniem pliku: {error:?}");
            })
        } else {
            panic!("Problem z otwarciem pliku: {error:?}");
        }
    });
}

Chociaż ten kod ma takie samo zachowanie jak Listing 9-5, nie zawiera żadnych wyrażeń match i jest czytelniejszy. Wróć do tego przykładu po przeczytaniu Rozdziału 13 i wyszukaj metodę unwrap_or_else w dokumentacji standardowej biblioteki. Wiele innych z tych metod może uporządkować ogromne, zagnieżdżone wyrażenia match, gdy masz do czynienia z błędami.

Skróty do paniki przy błędzie: unwrap i expect

Użycie match działa wystarczająco dobrze, ale może być nieco gadatliwe i nie zawsze dobrze komunikuje intencje. Typ Result<T, E> ma wiele pomocniczych metod zdefiniowanych na nim do wykonywania różnych, bardziej specyficznych zadań. Metoda unwrap jest skrótem zaimplementowanym tak samo jak wyrażenie match, które napisaliśmy w Listing 9-4. Jeśli wartość Result jest wariantem Ok, unwrap zwróci wartość wewnątrz Ok. Jeśli Result jest wariantem Err, unwrap wywoła dla nas makro panic!. Oto przykład unwrap w działaniu:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Jeśli uruchomimy ten kod bez pliku hello.txt, zobaczymy komunikat o błędzie z wywołania panic!, które wykonuje metoda 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" }

Podobnie, metoda expect pozwala nam również wybrać komunikat o błędzie panic!. Użycie expect zamiast unwrap i dostarczenie dobrych komunikatów o błędach może przekazać twoje intencje i ułatwić śledzenie źródła paniki. Składnia expect wygląda tak:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt powinien być dołączony do tego projektu");
}

Używamy expect w ten sam sposób co unwrap: aby zwrócić uchwyt pliku lub wywołać makro panic!. Komunikat o błędzie używany przez expect w jego wywołaniu panic! będzie parametrem, który przekazujemy do expect, zamiast domyślnego komunikatu panic!, którego używa unwrap. Oto jak to wygląda:

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

W kodzie produkcyjnym większość Rustacean preferuje expect zamiast unwrap i podaje więcej kontekstu, dlaczego operacja ma zawsze zakończyć się sukcesem. W ten sposób, jeśli twoje założenia kiedykolwiek okażą się błędne, masz więcej informacji do wykorzystania w debugowaniu.

Propagacja błędów

Kiedy implementacja funkcji wywołuje coś, co może zawieść, zamiast obsługiwać błąd w samej funkcji, możesz zwrócić błąd do kodu wywołującego, aby ten mógł zdecydować, co zrobić. Jest to znane jako propagacja błędu i daje większą kontrolę kodowi wywołującemu, gdzie może być więcej informacji lub logiki, która dyktuje, jak błąd powinien być obsłużony, niż to, co masz dostępne w kontekście swojego kodu.

Na przykład, Listing 9-6 pokazuje funkcję, która odczytuje nazwę użytkownika z pliku. Jeśli plik nie istnieje lub nie można go odczytać, funkcja zwróci te błędy do kodu, który wywołał funkcję.

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

Ta funkcja może być napisana w znacznie krótszy sposób, ale zaczniemy od jej ręcznego implementowania, aby zbadać obsługę błędów; na końcu pokażemy krótszy sposób. Spójrzmy najpierw na typ zwracany przez funkcję: Result<String, io::Error>. Oznacza to, że funkcja zwraca wartość typu Result<T, E>, gdzie generyczny parametr T został wypełniony konkretnym typem String, a generyczny typ E został wypełniony konkretnym typem io::Error.

Jeśli ta funkcja zakończy się sukcesem bez żadnych problemów, kod, który ją wywołuje, otrzyma wartość Ok, która zawiera String – username, który ta funkcja odczytała z pliku. Jeśli ta funkcja napotka jakiekolwiek problemy, kod wywołujący otrzyma wartość Err, która zawiera więcej informacji o tym, jakie były problemy. Wybraliśmy io::Error jako typ zwracany tej funkcji, ponieważ jest to typ wartości błędu zwracany przez obie operacje, które wywołujemy w treści tej funkcji i które mogą zawieść: funkcja File::open i metoda read_to_string.

Ciało funkcji zaczyna się od wywołania funkcji File::open. Następnie obsługujemy wartość Result za pomocą match, podobnego do match w Listing 9-4. Jeśli File::open zakończy się sukcesem, uchwyt pliku w zmiennej wzorca file staje się wartością w mutowalnej zmiennej username_file, a funkcja kontynuuje. W przypadku Err, zamiast wywoływać panic!, używamy słowa kluczowego return, aby natychmiast wyjść z funkcji i przekazać wartość błędu z File::open, teraz w zmiennej wzorca e, z powrotem do kodu wywołującego jako wartość błędu tej funkcji.

Zatem, jeśli mamy uchwyt pliku w username_file, funkcja następnie tworzy nowy String w zmiennej username i wywołuje metodę read_to_string na uchwycie pliku w username_file, aby odczytać zawartość pliku do username. Metoda read_to_string również zwraca Result, ponieważ może zawieść, nawet jeśli File::open zakończyło się sukcesem. Musimy więc użyć kolejnego match do obsługi tego Result: Jeśli read_to_string zakończy się sukcesem, to nasza funkcja zakończyła się sukcesem, i zwracamy nazwę użytkownika z pliku, która jest teraz w username, zawiniętą w Ok. Jeśli read_to_string zawiedzie, zwracamy wartość błędu w taki sam sposób, w jaki zwróciliśmy wartość błędu w match, które obsługiwało wartość zwracaną przez File::open. Nie musimy jednak jawnie mówić return, ponieważ jest to ostatnie wyrażenie w funkcji.

Kod wywołujący ten kod będzie następnie obsługiwał otrzymanie wartości Ok, która zawiera nazwę użytkownika, lub wartości Err, która zawiera io::Error. To od kodu wywołującego zależy, co zrobić z tymi wartościami. Jeśli kod wywołujący otrzyma wartość Err, mógłby wywołać panic! i zniszczyć program, użyć domyślnej nazwy użytkownika lub wyszukać nazwę użytkownika gdzie indziej niż w pliku, na przykład. Nie mamy wystarczających informacji o tym, co kod wywołujący faktycznie próbuje zrobić, więc propagujemy wszystkie informacje o sukcesie lub błędzie w górę, aby zostały odpowiednio obsłużone.

Ten wzorzec propagacji błędów jest tak powszechny w Rust, że Rust udostępnia operator znak zapytania ?, aby to ułatwić.

Skrót operatora ? do propagacji błędów

Listing 9-7 pokazuje implementację read_username_from_file, która ma tę samą funkcjonalność co w Listing 9-6, ale ta implementacja używa operatora ?.

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

Operator ? umieszczony po wartości Result działa prawie tak samo jak wyrażenia match, które zdefiniowaliśmy do obsługi wartości Result w Listing 9-6. Jeśli wartość Result to Ok, wartość wewnątrz Ok zostanie zwrócona z tego wyrażenia, a program będzie kontynuował. Jeśli wartość to Err, Err zostanie zwrócone z całej funkcji tak, jakbyśmy użyli słowa kluczowego return, tak aby wartość błędu została propagowana do kodu wywołującego.

Istnieje różnica między tym, co robi wyrażenie match z Listing 9-6, a tym, co robi operator ?: wartości błędów, na których wywołano operator ?, przechodzą przez funkcję from, zdefiniowaną w cesze From w standardowej bibliotece, która jest używana do konwertowania wartości z jednego typu na inny. Gdy operator ? wywołuje funkcję from, otrzymany typ błędu jest konwertowany na typ błędu zdefiniowany w typie zwracanym bieżącej funkcji. Jest to przydatne, gdy funkcja zwraca jeden typ błędu, aby reprezentować wszystkie sposoby, w jakie funkcja może zawieść, nawet jeśli części mogą zawieść z wielu różnych powodów.

Na przykład, moglibyśmy zmienić funkcję read_username_from_file w Listing 9-7 tak, aby zwracała niestandardowy typ błędu o nazwie OurError, który zdefiniujemy. Jeśli zdefiniujemy również impl From<io::Error> for OurError, aby skonstruować instancję OurError z io::Error, to wywołania operatora ? w ciele read_username_from_file wywołają from i przekonwertują typy błędów bez potrzeby dodawania do funkcji żadnego dodatkowego kodu.

W kontekście Listing 9-7, ? na końcu wywołania File::open zwróci wartość wewnątrz Ok do zmiennej username_file. Jeśli wystąpi błąd, operator ? natychmiast wyjdzie z całej funkcji i przekaże dowolną wartość Err do kodu wywołującego. To samo dotyczy ? na końcu wywołania read_to_string.

Operator ? eliminuje wiele szablonowego kodu i upraszcza implementację tej funkcji. Moglibyśmy nawet skrócić ten kod, łącząc wywołania metod bezpośrednio po ?, jak pokazano w Listing 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)
}
}

Tworzenie nowego String w username przenieśliśmy na początek funkcji; ta część nie uległa zmianie. Zamiast tworzyć zmienną username_file, połączyliśmy wywołanie read_to_string bezpośrednio z wynikiem File::open("hello.txt")?. Nadal mamy ? na końcu wywołania read_to_string i nadal zwracamy wartość Ok zawierającą username, gdy zarówno File::open, jak i read_to_string zakończą się sukcesem, zamiast zwracać błędy. Funkcjonalność jest ponownie taka sama jak w Listing 9-6 i Listing 9-7; jest to po prostu inny, bardziej ergonomiczny sposób zapisu.

Listing 9-9 pokazuje sposób na jeszcze większe skrócenie tego za pomocą 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")
}
}

Odczytywanie pliku do ciągu znaków jest dość powszechną operacją, dlatego standardowa biblioteka udostępnia wygodną funkcję fs::read_to_string, która otwiera plik, tworzy nowy String, odczytuje zawartość pliku, umieszcza zawartość w tym String i zwraca go. Oczywiście, użycie fs::read_to_string nie daje nam możliwości wyjaśnienia całej obsługi błędów, dlatego najpierw zrobiliśmy to w dłuższy sposób.

Gdzie można używać operatora ?

Operator ? może być używany tylko w funkcjach, których typ zwracany jest zgodny z wartością, na której użyto ?. Dzieje się tak, ponieważ operator ? jest zdefiniowany do wykonania wczesnego zwrócenia wartości z funkcji, w ten sam sposób, co wyrażenie match, które zdefiniowaliśmy w Listing 9-6. W Listing 9-6 match używał wartości Result, a ramię wczesnego zwrócenia zwracało wartość Err(e). Typ zwracany funkcji musi być Result, aby był zgodny z tym return.

W Listing 9-10 przyjrzyjmy się błędowi, który otrzymamy, jeśli użyjemy operatora ? w funkcji main z typem zwracanym niezgodnym z typem wartości, na której używamy ?.

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Ten kod otwiera plik, co może zakończyć się niepowodzeniem. Operator ? następuje po wartości Result zwracanej przez File::open, ale ta funkcja main ma typ zwracany (), a nie Result. Kiedy skompilujemy ten kod, otrzymamy następujący komunikat o błędzie:

$ 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

Ten błąd wskazuje, że możemy używać operatora ? tylko w funkcji, która zwraca Result, Option lub inny typ implementujący FromResidual.

Aby naprawić błąd, masz dwie możliwości. Jedna to zmiana typu zwracanego przez funkcję, aby był zgodny z wartością, na której używasz operatora ?, o ile nie ma żadnych ograniczeń, które by to uniemożliwiały. Druga to użycie match lub jednej z metod Result<T, E>, aby obsłużyć Result<T, E> w dowolny odpowiedni sposób.

Komunikat o błędzie wspominał również, że ? może być używany z wartościami Option<T>. Podobnie jak w przypadku użycia ? na Result, możesz używać ? na Option tylko w funkcji, która zwraca Option. Zachowanie operatora ? wywoływanego na Option<T> jest podobne do jego zachowania wywoływanego na Result<T, E>: Jeśli wartość to None, None zostanie zwrócone z funkcji w tym momencie. Jeśli wartość to Some, wartość wewnątrz Some jest wartością wynikową wyrażenia, a funkcja kontynuuje. Listing 9-11 zawiera przykład funkcji, która znajduje ostatni znak pierwszej linii w danym tekście.

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Witaj, świecie\nJak się masz dzisiaj?"),
        Some('e')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

Ta funkcja zwraca Option<char>, ponieważ możliwe jest, że tam jest znak, ale możliwe jest również, że go nie ma. Ten kod pobiera argument wycinka ciągu text i wywołuje na nim metodę lines, która zwraca iterator po liniach w ciągu. Ponieważ ta funkcja chce zbadać pierwszą linię, wywołuje next na iteratorze, aby uzyskać pierwszą wartość z iteratora. Jeśli text jest pustym ciągiem, to wywołanie next zwróci None, w którym to przypadku używamy ?, aby zatrzymać i zwrócić None z last_char_of_first_line. Jeśli text nie jest pustym ciągiem, next zwróci wartość Some zawierającą wycinek ciągu pierwszej linii w text.

Operator ? wyodrębnia wycinek ciągu znaków, a my możemy wywołać chars na tym wycinku ciągu znaków, aby uzyskać iterator jego znaków. Interesuje nas ostatni znak w tej pierwszej linii, więc wywołujemy last, aby zwrócić ostatni element w iteratorze. Jest to Option, ponieważ możliwe jest, że pierwsza linia jest pustym ciągiem; na przykład, jeśli text zaczyna się od pustej linii, ale ma znaki w innych liniach, jak w "\nhi". Jednakże, jeśli istnieje ostatni znak w pierwszej linii, zostanie on zwrócony w wariancie Some. Operator ? w środku daje nam zwięzły sposób wyrażenia tej logiki, pozwalając nam zaimplementować funkcję w jednej linii. Gdybyśmy nie mogli użyć operatora ? na Option, musielibyśmy zaimplementować tę logikę, używając większej liczby wywołań metod lub wyrażenia match.

Zauważ, że możesz używać operatora ? na Result w funkcji, która zwraca Result, i możesz używać operatora ? na Option w funkcji, która zwraca Option, ale nie możesz ich mieszać. Operator ? nie przekonwertuje automatycznie Result na Option ani na odwrót; w tych przypadkach możesz użyć metod, takich jak metoda ok na Result lub metoda ok_or na Option, aby wykonać konwersję jawnie.

Do tej pory wszystkie używane przez nas funkcje main zwracały (). Funkcja main jest specjalna, ponieważ jest punktem wejścia i wyjścia programu wykonywalnego, a istnieją ograniczenia dotyczące jej typu zwracanego, aby program działał zgodnie z oczekiwaniami.

Na szczęście, main może również zwrócić Result<(), E>. Listing 9-12 zawiera kod z Listing 9-10, ale zmieniliśmy typ zwracany main na Result<(), Box<dyn Error>> i dodaliśmy wartość zwracaną Ok(()) na końcu. Ten kod teraz się skompiluje.

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

Typ Box<dyn Error> to obiekt cechy, o którym będziemy mówić w sekcji „Używanie obiektów cech do abstrakcji wspólnego zachowania” w Rozdziale 18. Na razie możesz czytać Box<dyn Error> jako „dowolny rodzaj błędu”. Użycie ? na wartości Result w funkcji main z typem błędu Box<dyn Error> jest dozwolone, ponieważ pozwala to na wczesne zwrócenie dowolnej wartości Err. Mimo że ciało tej funkcji main zawsze będzie zwracać błędy typu std::io::Error, poprzez określenie Box<dyn Error>, ta sygnatura będzie nadal poprawna, nawet jeśli do ciała main zostanie dodany więcej kodu, który zwraca inne błędy.

Kiedy funkcja main zwraca Result<(), E>, plik wykonywalny zakończy działanie z wartością 0, jeśli main zwróci Ok(()), a zakończy działanie z wartością różną od zera, jeśli main zwróci wartość Err. Pliki wykonywalne napisane w C zwracają liczby całkowite po zakończeniu działania: programy, które zakończyły działanie pomyślnie, zwracają liczbę całkowitą 0, a programy, które zakończyły się błędem, zwracają jakąś liczbę całkowitą inną niż 0. Rust również zwraca liczby całkowite z plików wykonywalnych, aby być zgodnym z tą konwencją.

Funkcja main może zwracać dowolne typy implementujące cechę std::process::Termination, która zawiera funkcję report zwracającą ExitCode. Zapoznaj się z dokumentacją standardowej biblioteki, aby uzyskać więcej informacji na temat implementacji cechy Termination dla własnych typów.

Teraz, gdy omówiliśmy szczegóły wywoływania panic! lub zwracania Result, wróćmy do tematu, jak zdecydować, który z nich jest odpowiedni do użycia w jakich przypadkach.

Panikować czy nie panikować!

Panikować czy nie panikować!

Jak więc zdecydować, kiedy należy wywołać panic!, a kiedy zwrócić Result? Kiedy kod panikuje, nie ma sposobu na odzyskanie. Możesz wywołać panic! w każdej sytuacji błędu, niezależnie od tego, czy istnieje możliwość odzyskania, czy nie, ale wtedy podejmujesz decyzję, że sytuacja jest nie do odzyskania w imieniu kodu wywołującego. Kiedy zdecydujesz się zwrócić wartość Result, dajesz kodowi wywołującemu opcje. Kod wywołujący może spróbować odzyskać się w sposób odpowiedni dla swojej sytuacji, lub może zdecydować, że wartość Err w tym przypadku jest nie do odzyskania, więc może wywołać panic! i zmienić Twój odzyskiwalny błąd w błąd nie do odzyskania. Dlatego zwracanie Result jest dobrym domyślnym wyborem, gdy definiujesz funkcję, która może zawieść.

W sytuacjach takich jak przykłady, kod prototypowy i testy, bardziej odpowiednie jest pisanie kodu, który panikuje zamiast zwracać Result. Zbadajmy dlaczego, a następnie omówmy sytuacje, w których kompilator nie może stwierdzić, że awaria jest niemożliwa, ale Ty jako człowiek możesz. Rozdział zakończy się ogólnymi wytycznymi dotyczącymi tego, jak zdecydować, czy panikować w kodzie biblioteki.

Przykłady, kod prototypowy i testy

Kiedy piszesz przykład, aby zilustrować jakąś koncepcję, również uwzględnianie solidnego kodu do obsługi błędów może uczynić przykład mniej jasnym. W przykładach rozumie się, że wywołanie metody, takiej jak unwrap, która może spowodować panikę, ma być jedynie symulatorem sposobu, w jaki Twoja aplikacja obsługiwałaby błędy, co może się różnić w zależności od tego, co robi reszta Twojego kodu.

Podobnie, metody unwrap i expect są bardzo przydatne, gdy prototypujesz i nie jesteś jeszcze gotowy, aby zdecydować, jak obsługiwać błędy. Pozostawiają one jasne znaczniki w kodzie, na wypadek gdy będziesz gotowy, aby uczynić swój program bardziej niezawodnym.

Jeśli wywołanie metody zakończy się niepowodzeniem w teście, chciałbyś, aby cały test zakończył się niepowodzeniem, nawet jeśli ta metoda nie jest testowaną funkcjonalnością. Ponieważ panic! oznacza, że test zakończył się niepowodzeniem, wywołanie unwrap lub expect jest dokładnie tym, co powinno się stać.

Kiedy masz więcej informacji niż kompilator

Odpowiednie byłoby również wywołanie expect, gdy masz inną logikę, która gwarantuje, że Result będzie miał wartość Ok, ale logika nie jest czymś, co kompilator rozumie. Nadal będziesz mieć wartość Result, którą musisz obsłużyć: każda operacja, którą wywołujesz, nadal ma możliwość ogólnego niepowodzenia, nawet jeśli jest to logicznie niemożliwe w Twojej konkretnej sytuacji. Jeśli możesz upewnić się, ręcznie sprawdzając kod, że nigdy nie będziesz mieć wariantu Err, jest całkowicie dopuszczalne wywołanie expect i udokumentowanie powodu, dla którego uważasz, że nigdy nie będziesz mieć wariantu Err w tekście argumentu. Oto przykład:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Zakodowany na stałe adres IP powinien być prawidłowy");
}

Tworzymy instancję IpAddr poprzez parsowanie zakodowanego na stałe ciągu znaków. Widzimy, że 127.0.0.1 jest prawidłowym adresem IP, więc w tym przypadku użycie expect jest dopuszczalne. Jednak posiadanie zakodowanego na stałe, prawidłowego ciągu znaków nie zmienia typu zwracanego przez metodę parse: nadal otrzymujemy wartość Result, a kompilator nadal będzie nas zmuszał do obsługi Result, tak jakby wariant Err był możliwy, ponieważ kompilator nie jest wystarczająco sprytny, aby zobaczyć, że ten ciąg znaków jest zawsze prawidłowym adresem IP. Gdyby ciąg znaków adresu IP pochodził od użytkownika, a nie był zakodowany na stałe w programie i dlatego miał możliwość awarii, z pewnością chcielibyśmy obsłużyć Result w bardziej niezawodny sposób. Wspomnienie o założeniu, że ten adres IP jest zakodowany na stałe, skłoni nas do zmiany expect na lepszy kod obsługi błędów, jeśli w przyszłości będziemy musieli uzyskać adres IP z innego źródła.

Wytyczne dotyczące obsługi błędów

Zaleca się, aby kod panikował, gdy możliwe jest, że kod może znaleźć się w złym stanie. W tym kontekście zły stan to sytuacja, w której zostało naruszone jakieś założenie, gwarancja, kontrakt lub niezmiennik, na przykład, gdy do kodu przekazywane są nieprawidłowe wartości, wartości sprzeczne lub brakujące wartości — plus jeden lub więcej z poniższych:

• Zły stan jest czymś nieoczekiwanym, w przeciwieństwie do czegoś, co prawdopodobnie będzie się sporadycznie zdarzać, jak na przykład użytkownik wprowadzający dane w niewłaściwym formacie.
• Twój kod po tym punkcie musi polegać na tym, że nie jest w tym złym stanie, zamiast sprawdzać problem na każdym kroku.
• Nie ma dobrego sposobu na zakodowanie tych informacji w używanych typach. Omówimy przykład tego, co mamy na myśli, w sekcji „Kodowanie stanów i zachowań jako typy” w Rozdziale 18.

Jeśli ktoś wywoła Twój kod i przekaże wartości, które nie mają sensu, najlepiej jest zwrócić błąd, jeśli to możliwe, aby użytkownik biblioteki mógł zdecydować, co chce zrobić w takim przypadku. Jednak w przypadkach, gdy kontynuowanie mogłoby być niebezpieczne lub szkodliwe, najlepszym wyborem może być wywołanie panic! i ostrzeżenie osoby używającej Twojej biblioteki o błędzie w jej kodzie, aby mogła go naprawić podczas developmentu. Podobnie, panic! jest często odpowiednie, jeśli wywołujesz kod zewnętrzny, który jest poza Twoją kontrolą i zwraca nieprawidłowy stan, którego nie masz jak naprawić.

Jednakże, gdy awaria jest oczekiwana, bardziej odpowiednie jest zwrócenie Result niż wywołanie panic!. Przykłady obejmują parser, który otrzymuje źle sformatowane dane, lub żądanie HTTP zwracające status wskazujący, że osiągnięto limit szybkości. W takich przypadkach zwrócenie Result wskazuje, że awaria jest oczekiwaną możliwością, którą kod wywołujący musi zdecydować, jak obsłużyć.

Kiedy Twój kod wykonuje operację, która mogłaby narazić użytkownika na ryzyko, jeśli zostanie wywołana z nieprawidłowymi wartościami, Twój kod powinien najpierw zweryfikować, czy wartości są prawidłowe, i wywołać panikę, jeśli wartości są nieprawidłowe. Jest to głównie ze względów bezpieczeństwa: próba operowania na nieprawidłowych danych może narazić Twój kod na luki. To główny powód, dla którego standardowa biblioteka wywoła panic!, jeśli spróbujesz uzyskać dostęp do pamięci poza jej granicami: próba dostępu do pamięci, która nie należy do bieżącej struktury danych, jest częstym problemem bezpieczeństwa. Funkcje często mają kontrakty: ich zachowanie jest gwarantowane tylko wtedy, gdy dane wejściowe spełniają określone wymagania. Panika, gdy kontrakt jest naruszony, ma sens, ponieważ naruszenie kontraktu zawsze wskazuje na błąd po stronie wywołującego, i nie jest to rodzaj błędu, który kod wywołujący powinien jawnie obsługiwać. W rzeczywistości nie ma rozsądnego sposobu, aby kod wywołujący się odzyskał; programiści wywołujący muszą naprawić kod. Kontrakty funkcji, zwłaszcza gdy naruszenie spowoduje panikę, powinny być wyjaśnione w dokumentacji API funkcji.

Jednakże, posiadanie wielu kontroli błędów we wszystkich funkcjach byłoby rozbudowane i uciążliwe. Na szczęście, możesz użyć systemu typów Rusta (a co za tym idzie, sprawdzania typów wykonywanego przez kompilator), aby wykonać wiele kontroli za Ciebie. Jeśli Twoja funkcja ma określony typ jako parametr, możesz kontynuować logikę kodu, wiedząc, że kompilator już zapewnił, że masz prawidłową wartość. Na przykład, jeśli masz typ zamiast Option, Twój program oczekuje czegoś zamiast niczego. Twój kod nie musi wtedy obsługiwać dwóch przypadków dla wariantów Some i None: będzie miał tylko jeden przypadek dla zdecydowanego posiadania wartości. Kod próbujący przekazać nic do Twojej funkcji nawet się nie skompiluje, więc Twoja funkcja nie musi sprawdzać tego przypadku w czasie wykonywania. Innym przykładem jest użycie typu liczby całkowitej bez znaku, takiego jak u32, co zapewnia, że parametr nigdy nie jest ujemny.

Niestandardowe typy do walidacji

Rozwińmy ideę używania systemu typów Rusta do zapewnienia, że mamy prawidłową wartość, idąc o krok dalej i przyjrzyjmy się tworzeniu niestandardowego typu do walidacji. Przypomnij sobie grę zgadywanek z Rozdziału 2, w której nasz kod prosił użytkownika o odgadnięcie liczby od 1 do 100. Nigdy nie walidowaliśmy, czy odgadnięta przez użytkownika liczba mieściła się w tym zakresie, zanim porównaliśmy ją z naszą tajną liczbą; walidowaliśmy tylko, czy odgadnięta liczba była dodatnia. W tym przypadku konsekwencje nie były zbyt poważne: nasze komunikaty „Za mała” lub „Za duża” nadal byłyby poprawne. Ale przydatnym ulepszeniem byłoby pokierowanie użytkownika w stronę prawidłowych zgadywanek i zapewnienie innego zachowania, gdy użytkownik odgadnie liczbę spoza zakresu, niż gdy użytkownik wpisze na przykład litery.

Jednym ze sposobów na to byłoby parsowanie odgadniętej liczby jako i32 zamiast tylko u32, aby umożliwić potencjalnie ujemne liczby, a następnie dodanie sprawdzenia, czy liczba mieści się w zakresie, tak jak poniżej:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Odgadnij liczbę!");

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

    loop {
        // --snip--

        println!("Wprowadź swoje odgadnięcie.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Nie udało się odczytać linii");

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

        if guess < 1 || guess > 100 {
            println!("Tajny numer będzie między 1 a 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --snip--
            Ordering::Less => println!("Za mała!"),
            Ordering::Greater => println!("Za duża!"),
            Ordering::Equal => {
                println!("Wygrałeś!");
                break;
            }
        }
    }
}

Wyrażenie if sprawdza, czy nasza wartość jest poza zakresem, informuje użytkownika o problemie i wywołuje continue, aby rozpocząć kolejną iterację pętli i poprosić o kolejne odgadnięcie. Po wyrażeniu if możemy kontynuować porównania między guess a tajną liczbą, wiedząc, że guess znajduje się między 1 a 100.

Jednak to nie jest idealne rozwiązanie: gdyby absolutnie kluczowe było to, aby program operował tylko na wartościach od 1 do 100, i miał wiele funkcji z tym wymogiem, posiadanie takiego sprawdzenia w każdej funkcji byłoby uciążliwe (i mogłoby wpłynąć na wydajność).

Zamiast tego, możemy utworzyć nowy typ w dedykowanym module i umieścić walidacje w funkcji, aby utworzyć instancję tego typu, zamiast powtarzać walidacje wszędzie. W ten sposób funkcje będą mogły bezpiecznie używać nowego typu w swoich sygnaturach i śmiało używać otrzymanych wartości. Listing 9-13 pokazuje jeden ze sposobów definiowania typu Guess, który utworzy instancję Guess tylko wtedy, gdy funkcja new otrzyma wartość z zakresu od 1 do 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Wartość odgadnięcia musi być między 1 a 100, otrzymano {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Zauważ, że ten kod w src/guessing_game.rs zależy od dodania deklaracji modułu mod guessing_game; w src/lib.rs, której tutaj nie pokazaliśmy. W pliku tego nowego modułu definiujemy strukturę o nazwie Guess, która ma pole o nazwie value, przechowujące i32. Tutaj będzie przechowywana liczba.

Następnie implementujemy funkcję skojarzoną o nazwie new dla Guess, która tworzy instancje wartości Guess. Funkcja new jest zdefiniowana tak, aby miała jeden parametr o nazwie value typu i32 i zwracała Guess. Kod w treści funkcji new testuje value, aby upewnić się, że mieści się ono w zakresie od 1 do 100. Jeśli value nie przejdzie tego testu, wywołujemy panic!, co ostrzeże programistę piszącego kod wywołujący, że ma błąd do naprawienia, ponieważ utworzenie Guess z value spoza tego zakresu naruszyłoby kontrakt, na którym polega Guess::new. Warunki, w których Guess::new może panikować, powinny być omówione w jego publicznie dostępnej dokumentacji API; konwencje dokumentacji wskazujące na możliwość paniki w dokumentacji API, którą tworzysz, omówimy w rozdziale 14. Jeśli value przejdzie test, tworzymy nowy Guess z jego polem value ustawionym na parametr value i zwracamy Guess.

Następnie implementujemy metodę o nazwie value, która pożycza self, nie ma żadnych innych parametrów i zwraca i32. Taki rodzaj metody jest czasami nazywany getterem, ponieważ jego celem jest pobranie danych z pól i zwrócenie ich. Ta publiczna metoda jest niezbędna, ponieważ pole value struktury Guess jest prywatne. Ważne jest, aby pole value było prywatne, aby kod używający struktury Guess nie mógł bezpośrednio ustawiać value: kod spoza modułu guessing_game musi używać funkcji Guess::new do tworzenia instancji Guess, zapewniając w ten sposób, że nie ma możliwości, aby Guess miało value, które nie zostało sprawdzone przez warunki w funkcji Guess::new.

Funkcja, która ma parametr lub zwraca tylko liczby z zakresu od 1 do 100, mogłaby następnie zadeklarować w swojej sygnaturze, że przyjmuje lub zwraca Guess zamiast i32 i nie musiałaby wykonywać żadnych dodatkowych sprawdzeń w swoim ciele.

Podsumowanie

Funkcje obsługi błędów w Rust są zaprojektowane tak, aby pomóc Ci pisać bardziej niezawodny kod. Makro panic! sygnalizuje, że Twój program jest w stanie, którego nie jest w stanie obsłużyć, i pozwala Ci nakazać procesowi zatrzymanie się, zamiast próbować kontynuować z nieprawidłowymi lub błędnymi wartościami. Enum Result używa systemu typów Rusta, aby wskazać, że operacje mogą zakończyć się niepowodzeniem w sposób, który Twój kod mógłby odzyskać. Możesz użyć Result, aby powiedzieć kodowi, który wywołuje Twój kod, że musi on również obsłużyć potencjalny sukces lub niepowodzenie. Użycie panic! i Result w odpowiednich sytuacjach sprawi, że Twój kod będzie bardziej niezawodny w obliczu nieuniknionych problemów.

Teraz, gdy widziałeś przydatne sposoby, w jakie standardowa biblioteka używa generyków z enumami Option i Result, porozmawiamy o tym, jak działają generyki i jak możesz ich używać w swoim kodzie.

Typy generyczne, cechy i czasy życia

Każdy język programowania posiada narzędzia do efektywnego zarządzania powtarzalnością koncepcji. W Rust, jednym z takich narzędzi są generyki: abstrakcyjne zamienniki dla konkretnych typów lub innych właściwości. Możemy wyrazić zachowanie generyków lub ich relacje z innymi generykami, nie wiedząc, co znajdzie się na ich miejscu podczas kompilacji i uruchamiania kodu.

Funkcje mogą przyjmować parametry jakiegoś typu generycznego, zamiast konkretnego typu, takiego jak i32 lub String, w ten sam sposób, w jaki przyjmują parametry o nieznanych wartościach, aby uruchamiać ten sam kod na wielu konkretnych wartościach. W rzeczywistości, już używaliśmy generyków w Rozdziale 6 z Option<T>, w Rozdziale 8 z Vec<T> i HashMap<K, V>, oraz w Rozdziale 9 z Result<T, E>. W tym rozdziale poznasz, jak definiować własne typy, funkcje i metody za pomocą generyków!

Najpierw przypomnimy, jak wyodrębnić funkcję, aby zmniejszyć duplikację kodu. Następnie użyjemy tej samej techniki, aby stworzyć funkcję generyczną z dwóch funkcji, które różnią się tylko typami swoich parametrów. Wyjaśnimy również, jak używać typów generycznych w definicjach struktur i wyliczeń.

Następnie dowiesz się, jak używać cech (traits) do definiowania zachowania w sposób generyczny. Możesz łączyć cechy z typami generycznymi, aby ograniczyć typ generyczny do akceptowania tylko tych typów, które mają określone zachowanie, w przeciwieństwie do dowolnego typu.

Na koniec omówimy czasy życia: odmianę generyków, która dostarcza kompilatorowi informacji o tym, jak referencje odnoszą się do siebie. Czasy życia pozwalają nam dostarczyć kompilatorowi wystarczających informacji o pożyczonych wartościach, aby mógł on zapewnić, że referencje będą ważne w większej liczbie sytuacji, niż byłoby to możliwe bez naszej pomocy.

Usuwanie duplikacji poprzez wyodrębnianie funkcji

Generyki pozwalają nam zastępować konkretne typy przez placeholder, który reprezentuje wiele typów, aby usunąć duplikację kodu. Zanim zagłębimy się w składnię generyków, najpierw przyjrzyjmy się, jak usunąć duplikację w sposób, który nie obejmuje typów generycznych, poprzez wyodrębnienie funkcji, która zastępuje konkretne wartości przez placeholder reprezentujący wiele wartości. Następnie zastosujemy tę samą technikę do wyodrębnienia funkcji generycznej! Patrząc na to, jak rozpoznać zduplikowany kod, który można wyodrębnić do funkcji, zaczniesz rozpoznawać zduplikowany kod, który może używać generyków.

Zaczniemy od krótkiego programu w Listing 10-1, który znajduje największą liczbę na liście.

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!("Największa liczba to {largest}");
    assert_eq!(*largest, 100);
}

Przechowujemy listę liczb całkowitych w zmiennej number_list i umieszczamy referencję do pierwszej liczby na liście w zmiennej o nazwie largest. Następnie iterujemy po wszystkich liczbach na liście, a jeśli bieżąca liczba jest większa niż liczba przechowywana w largest, zastępujemy referencję w tej zmiennej. Jednakże, jeśli bieżąca liczba jest mniejsza lub równa największej liczbie widzianej do tej pory, zmienna nie zmienia się, a kod przechodzi do następnej liczby na liście. Po rozważeniu wszystkich liczb na liście, largest powinien odnosić się do największej liczby, która w tym przypadku wynosi 100.

Teraz postawiono nam zadanie znalezienia największej liczby na dwóch różnych listach liczb. Aby to zrobić, możemy zdecydować się na zduplikowanie kodu z Listing 10-1 i użycie tej samej logiki w dwóch różnych miejscach w programie, jak pokazano w Listing 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!("Największa liczba to {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!("Największa liczba to {largest}");
}

Chociaż ten kod działa, duplikowanie kodu jest uciążliwe i podatne na błędy. Musimy również pamiętać o aktualizowaniu kodu w wielu miejscach, gdy chcemy go zmienić.

Aby wyeliminować tę duplikację, stworzymy abstrakcję, definiując funkcję, która operuje na dowolnej liście liczb całkowitych przekazanej jako parametr. To rozwiązanie czyni nasz kod jaśniejszym i pozwala nam abstrakcyjnie wyrazić koncepcję znajdowania największej liczby na liście.

W Listing 10-3 wyodrębniamy kod, który znajduje największą liczbę, do funkcji o nazwie largest. Następnie wywołujemy funkcję, aby znaleźć największą liczbę na dwóch listach z Listing 10-2. Moglibyśmy również użyć tej funkcji na dowolnej innej liście wartości i32, które moglibyśmy mieć w przyszłości.

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!("Największa liczba to {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("Największa liczba to {result}");
    assert_eq!(*result, 6000);
}

Funkcja largest ma parametr list, który reprezentuje dowolny konkretny wycinek wartości i32, który możemy przekazać do funkcji. W rezultacie, gdy wywołujemy funkcję, kod działa na konkretnych wartościach, które przekazujemy.

Podsumowując, oto kroki, które podjęliśmy, aby zmienić kod z Listing 10-2 na Listing 10-3:

1. Zidentyfikuj zduplikowany kod.
2. Wyodrębnij zduplikowany kod do ciała funkcji i określ wejścia i wartości zwracane tego kodu w sygnaturze funkcji.
3. Zaktualizuj dwa wystąpienia zduplikowanego kodu, aby zamiast tego wywoływały funkcję.

Następnie użyjemy tych samych kroków z generykami, aby zmniejszyć duplikację kodu. W ten sam sposób, w jaki ciało funkcji może działać na abstrakcyjnej liście zamiast na konkretnych wartościach, generyki pozwalają kodowi działać na abstrakcyjnych typach.

Na przykład, powiedzmy, że mieliśmy dwie funkcje: jedną, która znajduje największy element w wycinku wartości i32, i drugą, która znajduje największy element w wycinku wartości char. Jak wyeliminowalibyśmy tę duplikację? Dowiedzmy się!

Generyczne typy danych

Generyczne typy danych

Używamy generyków do tworzenia definicji dla elementów, takich jak sygnatury funkcji lub struktury, które możemy następnie wykorzystać z wieloma różnymi konkretnymi typami danych. Najpierw przyjrzymy się, jak definiować funkcje, struktury, wyliczenia i metody za pomocą generyków. Następnie omówimy, jak generyki wpływają na wydajność kodu.

W definicjach funkcji

Podczas definiowania funkcji używającej generyków, umieszczamy generyki w sygnaturze funkcji, tam gdzie zazwyczaj określamy typy danych parametrów i wartość zwracaną. Dzięki temu nasz kod jest bardziej elastyczny i zapewnia większą funkcjonalność wywołującym naszą funkcję, jednocześnie zapobiegając duplikacji kodu.

Kontynuując naszą funkcję largest, Listing 10-4 pokazuje dwie funkcje, które obie znajdują największą wartość w wycinku. Następnie połączymy je w jedną funkcję, która używa generyków.

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!("Największa liczba to {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("Największy znak to {result}");
    assert_eq!(*result, 'y');
}

Funkcja largest_i32 jest tą, którą wyodrębniliśmy w Listing 10-3, która znajduje największą i32 w wycinku. Funkcja largest_char znajduje największy char w wycinku. Ciała funkcji mają ten sam kod, więc wyeliminujmy duplikację, wprowadzając generyczny parametr typu w jednej funkcji.

Aby sparametryzować typy w nowej pojedynczej funkcji, musimy nadać nazwę parametrowi typu, tak jak to robimy dla parametrów wartości funkcji. Możesz użyć dowolnego identyfikatora jako nazwy parametru typu. My jednak użyjemy T, ponieważ, zgodnie z konwencją, nazwy parametrów typu w Rust są krótkie, często składają się tylko z jednej litery, a konwencja nazewnictwa typów w Rust to UpperCamelCase. T (skrót od type) jest domyślnym wyborem większości programistów Rusta.

Kiedy używamy parametru w ciele funkcji, musimy zadeklarować nazwę parametru w sygnaturze, aby kompilator wiedział, co ta nazwa oznacza. Podobnie, kiedy używamy nazwy parametru typu w sygnaturze funkcji, musimy zadeklarować nazwę parametru typu, zanim jej użyjemy. Aby zdefiniować generyczną funkcję largest, umieszczamy deklaracje nazw typów w nawiasach ostrych, <>, między nazwą funkcji a listą parametrów, tak:

fn largest<T>(list: &[T]) -> &T {

Tę definicję czytamy jako „funkcja largest jest generyczna względem jakiegoś typu T”. Ta funkcja ma jeden parametr o nazwie list, który jest wycinkiem wartości typu T. Funkcja largest zwróci referencję do wartości tego samego typu T.

Listing 10-5 pokazuje połączoną definicję funkcji largest używającą generycznego typu danych w swojej sygnaturze. Listing pokazuje również, jak możemy wywołać funkcję z wycinkiem wartości i32 lub char. Zauważ, że ten kod jeszcze się nie skompiluje.

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!("Największa liczba to {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("Największy znak to {result}");
}

Jeśli skompilujemy ten kod teraz, otrzymamy następujący błąd:

$ 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

Tekst pomocy wspomina o std::cmp::PartialOrd, który jest cechą (trait), a o cechach będziemy mówić w następnej sekcji. Na razie wiedz, że ten błąd oznacza, że ciało funkcji largest nie zadziała dla wszystkich możliwych typów, którymi mogłoby być T. Ponieważ chcemy porównywać wartości typu T w ciele funkcji, możemy używać tylko typów, których wartości można uporządkować. Aby umożliwić porównania, standardowa biblioteka posiada cechę std::cmp::PartialOrd, którą można zaimplementować na typach (więcej na temat tej cechy znajdziesz w Dodatku C). Aby naprawić Listing 10-5, możemy zastosować się do sugestii tekstu pomocy i ograniczyć typy dozwolone dla T tylko do tych, które implementują PartialOrd. Listing następnie się skompiluje, ponieważ standardowa biblioteka implementuje PartialOrd zarówno dla i32, jak i char.

W definicjach struktur

Możemy również definiować struktury, aby używały generycznego parametru typu w jednym lub więcej polach, używając składni <>. Listing 10-6 definiuje strukturę Point<T> do przechowywania wartości współrzędnych x i y dowolnego typu.

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

Składnia używania generyków w definicjach struktur jest podobna do tej używanej w definicjach funkcji. Najpierw deklarujemy nazwę parametru typu w nawiasach ostrych tuż po nazwie struktury. Następnie używamy typu generycznego w definicji struktury tam, gdzie w przeciwnym razie określilibyśmy konkretne typy danych.

Zauważ, że ponieważ użyliśmy tylko jednego typu generycznego do zdefiniowania Point<T>, ta definicja mówi, że struktura Point<T> jest generyczna względem jakiegoś typu T, a pola x i y są obydwa tego samego typu, niezależnie od tego, jaki to typ. Jeśli stworzymy instancję Point<T>, która ma wartości różnych typów, jak w Listing 10-7, nasz kod się nie skompiluje.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

W tym przykładzie, gdy przypisujemy wartość całkowitą 5 do x, informujemy kompilator, że generyczny typ T będzie liczbą całkowitą dla tej instancji Point<T>. Następnie, gdy określamy 4.0 dla y, które zdefiniowaliśmy jako mające ten sam typ co x, otrzymamy błąd niezgodności typów, taki jak ten:

$ 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

Aby zdefiniować strukturę Point, w której x i y są obydwa generyczne, ale mogą mieć różne typy, możemy użyć wielu generycznych parametrów typu. Na przykład, w Listing 10-8 zmieniamy definicję Point tak, aby była generyczna względem typów T i U, gdzie x jest typu T, a y jest typu 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 };
}

Teraz wszystkie pokazane instancje Point są dozwolone! Możesz używać tylu generycznych parametrów typu w definicji, ile chcesz, ale używanie więcej niż kilku utrudnia czytanie kodu. Jeśli okaże się, że potrzebujesz wielu typów generycznych w swoim kodzie, może to wskazywać na potrzebę restrukturyzacji kodu na mniejsze części.

W definicjach wyliczeń

Podobnie jak w przypadku struktur, możemy definiować wyliczenia, aby zawierały generyczne typy danych w swoich wariantach. Przyjrzyjmy się ponownie wyliczeniu Option<T> dostarczanemu przez standardową bibliotekę, którego użyliśmy w Rozdziale 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Ta definicja powinna być teraz bardziej zrozumiała. Jak widać, enum Option<T> jest generyczny względem typu T i ma dwa warianty: Some, który przechowuje jedną wartość typu T, oraz wariant None, który nie przechowuje żadnej wartości. Używając enum Option<T>, możemy wyrazić abstrakcyjną koncepcję wartości opcjonalnej, a ponieważ Option<T> jest generyczny, możemy używać tej abstrakcji niezależnie od typu wartości opcjonalnej.

Wyliczenia mogą również używać wielu typów generycznych. Definicja wyliczenia Result, którego użyliśmy w Rozdziale 9, jest jednym z przykładów:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Enum Result jest generyczny względem dwóch typów, T i E, i ma dwa warianty: Ok, który przechowuje wartość typu T, oraz Err, który przechowuje wartość typu E. Ta definicja sprawia, że wygodnie jest używać enum Result wszędzie tam, gdzie mamy operację, która może zakończyć się sukcesem (zwrócić wartość jakiegoś typu T) lub niepowodzeniem (zwrócić błąd jakiegoś typu E). W rzeczywistości, tego właśnie użyliśmy do otwarcia pliku w Listing 9-3, gdzie T zostało wypełnione typem std::fs::File, gdy plik został pomyślnie otwarty, a E zostało wypełnione typem std::io::Error, gdy wystąpiły problemy z otwarciem pliku.

Kiedy rozpoznajesz sytuacje w swoim kodzie z wieloma definicjami struktur lub wyliczeń, które różnią się tylko typami przechowywanych wartości, możesz uniknąć duplikacji, używając zamiast tego typów generycznych.

W definicjach metod

Możemy implementować metody na strukturach i wyliczeniach (jak to zrobiliśmy w Rozdziale 5) i używać generycznych typów również w ich definicjach. Listing 10-9 pokazuje strukturę Point<T>, którą zdefiniowaliśmy w Listing 10-6 z zaimplementowaną na niej metodą o nazwie 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());
}

Tutaj zdefiniowaliśmy metodę o nazwie x na Point<T>, która zwraca referencję do danych w polu x.

Zauważ, że musimy zadeklarować T tuż po impl, abyśmy mogli użyć T do określenia, że implementujemy metody na typie Point<T>. Deklarując T jako typ generyczny po impl, Rust może zidentyfikować, że typ w nawiasach ostrych w Point jest typem generycznym, a nie typem konkretnym. Moglibyśmy wybrać inną nazwę dla tego parametru generycznego niż parametr generyczny zadeklarowany w definicji struktury, ale używanie tej samej nazwy jest konwencjonalne. Jeśli napiszesz metodę w impl, która deklaruje typ generyczny, ta metoda zostanie zdefiniowana dla każdej instancji typu, niezależnie od tego, jaki konkretny typ ostatecznie zastąpi typ generyczny.

Możemy również określać ograniczenia dla typów generycznych podczas definiowania metod na tym typie. Moglibyśmy, na przykład, zaimplementować metody tylko na instancjach Point<f32> zamiast na instancjach Point<T> z dowolnym typem generycznym. W Listing 10-10 używamy konkretnego typu f32, co oznacza, że nie deklarujemy żadnych typów po 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());
}

Ten kod oznacza, że typ Point<f32> będzie miał metodę distance_from_origin; inne instancje Point<T>, gdzie T nie jest typu f32, nie będą miały tej metody zdefiniowanej. Metoda mierzy, jak daleko nasz punkt znajduje się od punktu o współrzędnych (0.0, 0.0) i używa operacji matematycznych, które są dostępne tylko dla typów zmiennoprzecinkowych.

Generyczne parametry typu w definicji struktury nie zawsze są takie same, jak te, których używasz w sygnaturach metod tej samej struktury. Listing 10-11 używa generycznych typów X1 i Y1 dla struktury Point oraz X2 i Y2 dla sygnatury metody mixup, aby przykład był jaśniejszy. Metoda tworzy nową instancję Point z wartością x z self Point (typu X1) i wartością y z przekazanego Point (typu 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: "Witaj", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

W funkcji main zdefiniowaliśmy Point, który ma i32 dla x (o wartości 5) i f64 dla y (o wartości 10.4). Zmienna p2 to struktura Point, która ma wycinek ciągu znaków dla x (o wartości "Witaj") i char dla y (o wartości c). Wywołanie mixup na p1 z argumentem p2 daje nam p3, który będzie miał i32 dla x, ponieważ x pochodzi z p1. Zmienna p3 będzie miała char dla y, ponieważ y pochodzi z p2. Wywołanie makra println! wydrukuje p3.x = 5, p3.y = c.

Celem tego przykładu jest zademonstrowanie sytuacji, w której niektóre parametry generyczne są zadeklarowane za pomocą impl, a niektóre za pomocą definicji metody. Tutaj parametry generyczne X1 i Y1 są zadeklarowane po impl, ponieważ pasują do definicji struktury. Parametry generyczne X2 i Y2 są zadeklarowane po fn mixup, ponieważ są istotne tylko dla metody.

Wydajność kodu używającego generyków

Możesz zastanawiać się, czy istnieje koszt czasu wykonania przy używaniu generycznych parametrów typu. Dobra wiadomość jest taka, że używanie typów generycznych nie spowolni programu bardziej niż użycie konkretnych typów.

Rust osiąga to, wykonując monomorfizację kodu używającego generyków w czasie kompilacji. Monomorfizacja to proces przekształcania kodu generycznego w kod specyficzny poprzez wypełnienie konkretnych typów używanych podczas kompilacji. W tym procesie kompilator wykonuje przeciwieństwo kroków, których użyliśmy do utworzenia funkcji generycznej w Listing 10-5: kompilator przegląda wszystkie miejsca, w których wywoływany jest kod generyczny, i generuje kod dla konkretnych typów, z którymi wywoływany jest kod generyczny.

Przyjrzyjmy się, jak to działa, używając generycznego enum Option<T> ze standardowej biblioteki:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Kiedy Rust kompiluje ten kod, wykonuje monomorfizację. Podczas tego procesu kompilator odczytuje wartości, które zostały użyte w instancjach Option<T>, i identyfikuje dwa rodzaje Option<T>: jeden to i32, a drugi to f64. W związku z tym rozszerza generyczną definicję Option<T> na dwie definicje wyspecjalizowane dla i32 i f64, zastępując w ten sposób generyczną definicję specyficznymi.

Monomorfizowana wersja kodu wygląda podobnie do następującej (kompilator używa innych nazw niż te, których używamy tutaj dla ilustracji):

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

Generyczny Option<T> jest zastępowany przez specyficzne definicje utworzone przez kompilator. Ponieważ Rust kompiluje kod generyczny do kodu, który określa typ w każdej instancji, nie ponosimy kosztów wykonania za używanie generyków. Gdy kod działa, zachowuje się tak samo, jakbyśmy ręcznie zduplikowali każdą definicję. Proces monomorfizacji sprawia, że generyki Rusta są niezwykle wydajne w czasie wykonywania.

Definiowanie wspólnego zachowania za pomocą cech

Definiowanie wspólnego zachowania za pomocą cech

Cecha (trait) definiuje funkcjonalność, którą posiada dany typ i którą może dzielić z innymi typami. Możemy używać cech do definiowania wspólnego zachowania w sposób abstrakcyjny. Możemy używać ograniczeń cech (trait bounds) do określania, że typ generyczny może być dowolnym typem, który ma określone zachowanie.

Uwaga: Cechy są podobne do funkcji często nazywanych interfejsami w innych językach, choć z pewnymi różnicami.

Definiowanie cechy

Zachowanie typu składa się z metod, które możemy wywołać dla tego typu. Różne typy dzielą to samo zachowanie, jeśli możemy wywołać te same metody dla wszystkich tych typów. Definicje cech to sposób grupowania sygnatur metod w celu zdefiniowania zestawu zachowań niezbędnych do osiągnięcia pewnego celu.

Na przykład, powiedzmy, że mamy wiele struktur, które przechowują różne rodzaje i ilości tekstu: struktura NewsArticle, która przechowuje artykuł informacyjny z określonej lokalizacji, i SocialPost, która może mieć co najwyżej 280 znaków wraz z metadanymi wskazującymi, czy był to nowy post, repost, czy odpowiedź na inny post.

Chcemy stworzyć skrzynkę biblioteczną agregującą media o nazwie aggregator, która będzie mogła wyświetlać podsumowania danych przechowywanych w instancji NewsArticle lub SocialPost. Aby to zrobić, potrzebujemy podsumowania z każdego typu, a to podsumowanie uzyskamy, wywołując metodę summarize na instancji. Listing 10-12 pokazuje definicję publicznej cechy Summary, która wyraża to zachowanie.

pub trait Summary {
    fn summarize(&self) -> String;
}

Tutaj deklarujemy cechę za pomocą słowa kluczowego trait, a następnie nazwę cechy, która w tym przypadku to Summary. Deklarujemy również cechę jako pub, aby skrzynki zależne od tej skrzynki mogły również korzystać z tej cechy, jak zobaczymy w kilku przykładach. W nawiasach klamrowych deklarujemy sygnatury metod, które opisują zachowania typów implementujących tę cechę, co w tym przypadku jest fn summarize(&self) -> String.

Po sygnaturze metody, zamiast dostarczać implementacji w nawiasach klamrowych, używamy średnika. Każdy typ implementujący tę cechę musi dostarczyć własne, niestandardowe zachowanie dla ciała metody. Kompilator wymusi, aby każdy typ posiadający cechę Summary miał metodę summarize zdefiniowaną dokładnie z tą sygnaturą.

Cecha może mieć wiele metod w swoim ciele: sygnatury metod są wymienione jedna na linię, a każda linia kończy się średnikiem.

Implementowanie cechy na typie

Teraz, gdy zdefiniowaliśmy pożądane sygnatury metod cechy Summary, możemy zaimplementować ją na typach w naszym agregatorze mediów. Listing 10-13 pokazuje implementację cechy Summary na strukturze NewsArticle, która używa nagłówka, autora i lokalizacji do utworzenia wartości zwracanej przez summarize. Dla struktury SocialPost definiujemy summarize jako nazwę użytkownika, a następnie cały tekst posta, zakładając, że zawartość posta jest już ograniczona do 280 znaków.

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

Implementowanie cechy na typie jest podobne do implementowania zwykłych metod. Różnica polega na tym, że po impl umieszczamy nazwę cechy, którą chcemy zaimplementować, następnie używamy słowa kluczowego for, a następnie określamy nazwę typu, dla którego chcemy zaimplementować cechę. W bloku impl umieszczamy sygnatury metod, które zdefiniowano w definicji cechy. Zamiast dodawać średnik po każdej sygnaturze, używamy nawiasów klamrowych i wypełniamy ciało metody konkretnym zachowaniem, które chcemy, aby metody cechy miały dla danego typu.

Teraz, gdy biblioteka zaimplementowała cechę Summary dla NewsArticle i SocialPost, użytkownicy skrzynki mogą wywoływać metody cech na instancjach NewsArticle i SocialPost w taki sam sposób, jak wywołujemy zwykłe metody. Jedyną różnicą jest to, że użytkownik musi wprowadzić cechę do zasięgu, a także typy. Oto przykład, jak skrzynka binarna mogłaby użyć naszej skrzynki bibliotecznej aggregator:

use aggregator::{SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "oczywiście, jak zapewne już wiesz, ludzie",
        ),
        reply: false,
        repost: false,
    };

    println!("1 nowy post: {}", post.summarize());
}

Ten kod drukuje 1 nowy post: horse_ebooks: oczywiście, jak zapewne już wiesz, ludzie.

Inne skrzynki zależne od skrzynki aggregator mogą również wprowadzić cechę Summary do zasięgu, aby zaimplementować Summary na swoich własnych typach. Jednym z ograniczeń jest to, że możemy zaimplementować cechę na typie tylko wtedy, gdy cecha lub typ, albo oba, są lokalne dla naszej skrzynki. Na przykład, możemy zaimplementować cechy standardowej biblioteki, takie jak Display, na niestandardowym typie, takim jak SocialPost, jako część funkcjonalności naszej skrzynki aggregator, ponieważ typ SocialPost jest lokalny dla naszej skrzynki aggregator. Możemy również zaimplementować Summary na Vec<T> w naszej skrzynce aggregator, ponieważ cecha Summary jest lokalna dla naszej skrzynki aggregator.

Ale nie możemy implementować zewnętrznych cech na zewnętrznych typach. Na przykład, nie możemy implementować cechy Display na Vec<T> w naszej skrzynce aggregator, ponieważ Display i Vec<T> są zdefiniowane w standardowej bibliotece i nie są lokalne dla naszej skrzynki aggregator. To ograniczenie jest częścią właściwości zwanej spójnością, a dokładniej zasadą sieroty (orphan rule), nazwaną tak, ponieważ typ nadrzędny nie jest obecny. Ta zasada zapewnia, że kod innych ludzi nie może zepsuć twojego kodu i vice versa. Bez tej zasady, dwie skrzynki mogłyby zaimplementować tę samą cechę dla tego samego typu, a Rust nie wiedziałby, której implementacji użyć.

Używanie domyślnych implementacji

Czasami przydatne jest posiadanie domyślnego zachowania dla niektórych lub wszystkich metod w cesze, zamiast wymagać implementacji dla wszystkich metod na każdym typie. Następnie, implementując cechę na konkretnym typie, możemy zachować lub nadpisać domyślne zachowanie każdej metody.

W Listing 10-14 określamy domyślny ciąg znaków dla metody summarize cechy Summary, zamiast definiować tylko sygnaturę metody, jak to zrobiliśmy w Listing 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Czytaj więcej...)")
    }
}

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

Aby użyć domyślnej implementacji do podsumowywania instancji NewsArticle, określamy pusty blok impl za pomocą impl Summary for NewsArticle {}.

Chociaż nie definiujemy już bezpośrednio metody summarize w NewsArticle, dostarczyliśmy domyślną implementację i określiliśmy, że NewsArticle implementuje cechę Summary. W rezultacie nadal możemy wywołać metodę summarize na instancji NewsArticle, tak jak poniżej:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Pingwiny wygrywają Puchar Stanleya!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "Pittsburgh Penguins po raz kolejny są najlepszą \
             drużyną hokejową w NHL.",
        ),
    };

    println!("Nowy artykuł dostępny! {}", article.summarize());
}

Ten kod drukuje Nowy artykuł dostępny! (Czytaj więcej...).

Stworzenie domyślnej implementacji nie wymaga od nas zmiany czegokolwiek w implementacji Summary na SocialPost w Listing 10-13. Powodem jest to, że składnia nadpisywania domyślnej implementacji jest taka sama jak składnia implementacji metody cechy, która nie ma domyślnej implementacji.

Domyślne implementacje mogą wywoływać inne metody w tej samej cesze, nawet jeśli te inne metody nie mają domyślnej implementacji. W ten sposób cecha może dostarczyć wiele użytecznej funkcjonalności i wymagać od implementatorów jedynie określenia jej małej części. Na przykład, moglibyśmy zdefiniować cechę Summary tak, aby miała metodę summarize_author, której implementacja jest wymagana, a następnie zdefiniować metodę summarize, która ma domyślną implementację, która wywołuje metodę summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Czytaj więcej od {}...)", 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)
    }
}

Aby użyć tej wersji Summary, wystarczy zdefiniować summarize_author podczas implementacji cechy na typie:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Czytaj więcej od {}...)", 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)
    }
}

Po zdefiniowaniu summarize_author możemy wywołać summarize na instancjach struktury SocialPost, a domyślna implementacja summarize wywoła zdefiniowaną przez nas summarize_author. Ponieważ zaimplementowaliśmy summarize_author, cecha Summary dała nam zachowanie metody summarize bez konieczności pisania dodatkowego kodu. Oto jak to wygląda:

use aggregator::{self, SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "oczywiście, jak zapewne już wiesz, ludzie",
        ),
        reply: false,
        repost: false,
    };

    println!("1 nowy post: {}", post.summarize());
}

Ten kod drukuje 1 nowy post: (Czytaj więcej od @horse_ebooks...).

Zauważ, że nie jest możliwe wywołanie domyślnej implementacji z nadpisującej implementacji tej samej metody.

Używanie cech jako parametrów

Teraz, gdy wiesz, jak definiować i implementować cechy, możemy zbadać, jak używać cech do definiowania funkcji, które akceptują wiele różnych typów. Użyjemy cechy Summary, którą zaimplementowaliśmy na typach NewsArticle i SocialPost w Listing 10-13, aby zdefiniować funkcję notify, która wywołuje metodę summarize na swoim parametrze item, który jest jakiegoś typu implementującego cechę Summary. Aby to zrobić, używamy składni impl Trait, tak jak poniżej:

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!("Najświeższe wiadomości! {}", item.summarize());
}

Zamiast konkretnego typu dla parametru item, określamy słowo kluczowe impl i nazwę cechy. Ten parametr akceptuje dowolny typ, który implementuje określoną cechę. W ciele notify możemy wywołać dowolne metody na item, które pochodzą z cechy Summary, takie jak summarize. Możemy wywołać notify i przekazać dowolną instancję NewsArticle lub SocialPost. Kod, który wywołuje funkcję z dowolnym innym typem, takim jak String lub i32, nie skompiluje się, ponieważ te typy nie implementują Summary.

Składnia ograniczeń cech

Składnia impl Trait działa w prostych przypadkach, ale w rzeczywistości jest to cukier syntaktyczny dla dłuższej formy znanej jako ograniczenie cechy (trait bound); wygląda to tak:

pub fn notify<T: Summary>(item: &T) {
    println!("Najświeższe wiadomości! {}", item.summarize());
}

Ta dłuższa forma jest równoważna przykładowi z poprzedniej sekcji, ale jest bardziej rozwlekła. Ograniczenia cech umieszczamy wraz z deklaracją generycznego parametru typu po dwukropku i w nawiasach ostrych.

Składnia impl Trait jest wygodna i sprawia, że kod jest bardziej zwięzły w prostych przypadkach, podczas gdy pełniejsza składnia ograniczeń cech może wyrażać większą złożoność w innych przypadkach. Na przykład, możemy mieć dwa parametry, które implementują Summary. Użycie składni impl Trait wygląda tak:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

Użycie impl Trait jest odpowiednie, jeśli chcemy, aby ta funkcja pozwalała item1 i item2 na posiadanie różnych typów (o ile oba typy implementują Summary). Jeśli jednak chcemy wymusić, aby oba parametry miały ten sam typ, musimy użyć ograniczenia cechy, tak jak poniżej:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

Generyczny typ T określony jako typ parametrów item1 i item2 ogranicza funkcję tak, że konkretny typ wartości przekazanej jako argument dla item1 i item2 musi być taki sam.

Wiele ograniczeń cech za pomocą składni +

Możemy również określić więcej niż jedno ograniczenie cechy. Powiedzmy, że chcieliśmy, aby notify używało formatowania wyświetlania, a także summarize na item: określamy w definicji notify, że item musi implementować zarówno Display, jak i Summary. Możemy to zrobić za pomocą składni +:

pub fn notify(item: &(impl Summary + Display)) {

Składnia + jest również prawidłowa z ograniczeniami cech na typach generycznych:

pub fn notify<T: Summary + Display>(item: &T) {

Dzięki dwóm określonym ograniczeniom cech, ciało notify może wywoływać summarize i używać {} do formatowania item.

Jaśniejsze ograniczenia cech za pomocą klauzul where

Zbyt wiele ograniczeń cech ma swoje wady. Każdy typ generyczny ma swoje własne ograniczenia cech, więc funkcje z wieloma generycznymi parametrami typu mogą zawierać wiele informacji o ograniczeniach cech między nazwą funkcji a listą jej parametrów, co utrudnia czytanie sygnatury funkcji. Z tego powodu Rust ma alternatywną składnię do określania ograniczeń cech w klauzuli where po sygnaturze funkcji. Tak więc, zamiast pisać tak:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

możemy użyć klauzuli where, tak jak poniżej:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

Sygnatura tej funkcji jest mniej zaśmiecona: nazwa funkcji, lista parametrów i typ zwracany są blisko siebie, podobnie jak w funkcji bez wielu ograniczeń cech.

Zwracanie typów, które implementują cechy

Możemy również użyć składni impl Trait w pozycji zwracanej, aby zwrócić wartość jakiegoś typu, który implementuje cechę, jak pokazano tutaj:

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(
            "oczywiście, jak zapewne już wiesz, ludzie",
        ),
        reply: false,
        repost: false,
    }
}

Używając impl Summary jako typu zwracanego, określamy, że funkcja returns_summarizable zwraca pewien typ, który implementuje cechę Summary, bez nazywania konkretnego typu. W tym przypadku returns_summarizable zwraca SocialPost, ale kod wywołujący tę funkcję nie musi o tym wiedzieć.

Możliwość określenia typu zwracanego tylko przez cechę, którą implementuje, jest szczególnie przydatna w kontekście domknięć i iteratorów, które omówimy w Rozdziale 13. Domknięcia i iteratory tworzą typy, które zna tylko kompilator, lub typy, które są bardzo długie do określenia. Składnia impl Trait pozwala zwięźle określić, że funkcja zwraca jakiś typ, który implementuje cechę Iterator, bez konieczności wypisywania bardzo długiego typu.

Możesz jednak używać impl Trait tylko wtedy, gdy zwracasz pojedynczy typ. Na przykład, ten kod, który zwraca NewsArticle lub SocialPost z typem zwracanym określonym jako impl Summary, nie zadziała:

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(
                "Pingwiny wygrywają Puchar Stanleya!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "Pittsburgh Penguins po raz kolejny są najlepszą \
                 drużyną hokejową w NHL.",
            ),
        }
    } else {
        SocialPost {
            username: String::from("horse_ebooks"),
            content: String::from(
                "oczywiście, jak zapewne już wiesz, ludzie",
            ),
            reply: false,
            repost: false,
        }
    }
}

Zwracanie NewsArticle lub SocialPost nie jest dozwolone z powodu ograniczeń związanych z implementacją składni impl Trait w kompilatorze. Omówimy, jak napisać funkcję o takim zachowaniu w sekcji „Używanie obiektów cech do abstrakcji wspólnego zachowania” w Rozdziale 18.

Używanie ograniczeń cech do warunkowej implementacji metod

Używając ograniczenia cechy z blokiem impl, który używa generycznych parametrów typu, możemy warunkowo implementować metody dla typów, które implementują określone cechy. Na przykład, typ Pair<T> w Listing 10-15 zawsze implementuje funkcję new, aby zwrócić nową instancję Pair<T> (przypomnij sobie z sekcji „Składnia metody” w Rozdziale 5, że Self jest aliasem typu dla typu bloku impl, który w tym przypadku to Pair<T>). Ale w następnym bloku impl, Pair<T> implementuje metodę cmp_display tylko wtedy, gdy jej wewnętrzny typ T implementuje cechę PartialOrd, która umożliwia porównanie i cechę Display, która umożliwia drukowanie.

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!("Największy element to x = {}", self.x);
        } else {
            println!("Największy element to y = {}", self.y);
        }
    }
}

Możemy również warunkowo implementować cechę dla dowolnego typu, który implementuje inną cechę. Implementacje cechy na dowolnym typie, który spełnia ograniczenia cechy, nazywane są implementacjami ogólnymi (blanket implementations) i są szeroko stosowane w standardowej bibliotece Rusta. Na przykład, standardowa biblioteka implementuje cechę ToString dla każdego typu, który implementuje cechę Display. Blok impl w standardowej bibliotece wygląda podobnie do tego kodu:

impl<T: Display> ToString for T {
    // --snip--
}

Ponieważ standardowa biblioteka ma tę ogólną implementację, możemy wywołać metodę to_string zdefiniowaną przez cechę ToString na dowolnym typie, który implementuje cechę Display. Na przykład, możemy zamienić liczby całkowite na odpowiadające im wartości String w ten sposób, ponieważ liczby całkowite implementują Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Implementacje ogólne pojawiają się w dokumentacji cechy w sekcji „Implementacje”.

Cechy i ograniczenia cech pozwalają nam pisać kod, który używa generycznych parametrów typu, aby zmniejszyć duplikację, ale także określać kompilatorowi, że chcemy, aby generyczny typ miał określone zachowanie. Kompilator może następnie użyć informacji o ograniczeniach cech, aby sprawdzić, czy wszystkie konkretne typy używane z naszym kodem zapewniają prawidłowe zachowanie. W językach z dynamicznym typowaniem otrzymalibyśmy błąd w czasie wykonywania, gdybyśmy wywołali metodę na typie, który nie definiuje tej metody. Ale Rust przenosi te błędy do czasu kompilacji, tak abyśmy byli zmuszeni do naprawienia problemów, zanim nasz kod w ogóle będzie mógł działać. Dodatkowo, nie musimy pisać kodu, który sprawdza zachowanie w czasie wykonywania, ponieważ sprawdziliśmy to już w czasie kompilacji. Robienie tego poprawia wydajność bez konieczności rezygnacji z elastyczności generyków.

Walidacja referencji za pomocą czasów życia

Walidacja referencji za pomocą czasów życia

Czasy życia to kolejny rodzaj generyków, których już używaliśmy. Zamiast zapewniać, że typ ma pożądane przez nas zachowanie, czasy życia zapewniają, że referencje są ważne tak długo, jak tego potrzebujemy.

Jednym szczegółem, o którym nie rozmawialiśmy w sekcji „Referencje i pożyczanie” w Rozdziale 4, jest to, że każda referencja w Rust ma czas życia, który jest zasięgiem, w którym ta referencja jest ważna. Przez większość czasu, czasy życia są domyślne i wnioskowane, tak jak przez większość czasu, typy są wnioskowane. Jesteśmy zobowiązani do adnotowania typów tylko wtedy, gdy możliwych jest wiele typów. W podobny sposób musimy adnotować czasy życia, gdy czasy życia referencji mogą być powiązane na kilka różnych sposobów. Rust wymaga od nas adnotowania relacji za pomocą ogólnych parametrów czasów życia, aby zapewnić, że rzeczywiste referencje używane w czasie wykonania będą z pewnością ważne.

Adnotowanie czasów życia nie jest nawet koncepcją, którą posiada większość innych języków programowania, więc będzie to wydawać się nieznane. Chociaż w tym rozdziale nie omówimy czasów życia w całości, to jednak przedstawimy typowe sposoby, w jakie można napotkać składnię czasów życia, aby można było się z nią oswoić.

Wiszące referencje

Głównym celem czasów życia jest zapobieganie wiszącym referencjom, które, gdyby były dozwolone, spowodowałyby, że program odnosiłby się do danych innych niż te, do których miał się odnosić. Rozważ program z Listingu 10-16, który ma zasięg zewnętrzny i zasięg wewnętrzny.

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

Uwaga: Przykłady z Listingów 10-16, 10-17 i 10-23 deklarują zmienne bez nadawania im wartości początkowej, więc nazwa zmiennej istnieje w zasięgu zewnętrznym. Na pierwszy rzut oka może to wydawać się sprzeczne z tym, że Rust nie ma wartości null. Jednakże, jeśli spróbujemy użyć zmiennej przed nadaniem jej wartości, otrzymamy błąd kompilacji, co pokazuje, że Rust faktycznie nie zezwala na wartości null.

Zasięg zewnętrzny deklaruje zmienną r bez wartości początkowej, a zasięg wewnętrzny deklaruje zmienną x z wartością początkową 5. Wewnątrz zasięgu wewnętrznego próbujemy ustawić wartość r jako referencję do x. Następnie zasięg wewnętrzny kończy się, a my próbujemy wypisać wartość r. Ten kod nie skompiluje się, ponieważ wartość, do której odnosi się r, wyszła poza zasięg, zanim spróbowaliśmy jej użyć. Oto komunikat o błędzie:

$ 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

Komunikat o błędzie mówi, że zmienna x „nie żyje wystarczająco długo”. Powodem jest to, że x wyjdzie poza zasięg, gdy zasięg wewnętrzny zakończy się w wierszu 7. Ale r jest nadal ważne dla zasięgu zewnętrznego; ponieważ jego zasięg jest większy, mówimy, że „żyje dłużej”. Gdyby Rust pozwolił na działanie tego kodu, r odwoływałoby się do pamięci, która została zwolniona, gdy x wyszło poza zasięg, a wszystko, co próbowalibyśmy zrobić z r, nie działałoby poprawnie. Jak więc Rust ustala, że ten kod jest nieprawidłowy? Używa sprawdzacza pożyczeń.

Sprawdzacz pożyczeń

Kompilator Rust posiada sprawdzacz pożyczeń, który porównuje zasięgi, aby określić, czy wszystkie pożyczki są ważne. Listing 10-17 przedstawia ten sam kod co Listing 10-16, ale z adnotacjami pokazującymi czasy życia zmiennych.

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {r}");   //          |
}                         // ---------+

Tutaj oznaczyliśmy czas życia r jako 'a, a czas życia x jako 'b. Jak widać, wewnętrzny blok 'b jest znacznie mniejszy niż zewnętrzny blok czasu życia 'a. W czasie kompilacji Rust porównuje rozmiar tych dwóch czasów życia i widzi, że r ma czas życia 'a, ale odnosi się do pamięci z czasem życia 'b. Program jest odrzucany, ponieważ 'b jest krótsze niż 'a: podmiot referencji nie żyje tak długo, jak sama referencja.

Listing 10-18 naprawia kod, tak aby nie miał wiszącej referencji i kompilował się bez żadnych błędów.

fn main() {
    let x = 5;            // ----------+-- 'b
                          //           |
    let r = &x;           // --+-- 'a  |
                          //   |       |
    println!("r: {r}");   //   |       |
                          // --+       |
}                         // ----------+

Tutaj x ma czas życia 'b, który w tym przypadku jest większy niż 'a. Oznacza to, że r może odwoływać się do x, ponieważ Rust wie, że referencja w r zawsze będzie ważna, dopóki x jest ważne.

Teraz, gdy wiesz, gdzie znajdują się czasy życia referencji i jak Rust analizuje czasy życia, aby zapewnić, że referencje zawsze będą ważne, przejdźmy do ogólnych czasów życia w parametrach funkcji i wartościach zwracanych.

Ogólne czasy życia w funkcjach

Napiszemy funkcję, która zwraca dłuższy z dwóch wycinków ciągów znaków. Funkcja ta przyjmie dwa wycinki ciągów znaków i zwróci pojedynczy wycinek ciągu znaków. Po zaimplementowaniu funkcji longest, kod z Listingu 10-19 powinien wypisać 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}");
}

Zauważ, że chcemy, aby funkcja przyjmowała wycinki ciągów znaków, które są referencjami, a nie ciągami znaków, ponieważ nie chcemy, aby funkcja longest przejmowała własność swoich parametrów. Więcej informacji na temat tego, dlaczego parametry użyte w Listingu 10-19 są tymi, których chcemy, znajduje się w sekcji „Wycinki ciągów znaków jako parametry” w Rozdziale 4.

Jeśli spróbujemy zaimplementować funkcję longest tak, jak pokazano w Listingu 10-20, nie skompiluje się ona.

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

Zamiast tego otrzymujemy następujący błąd, który dotyczy czasów życia:

$ 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

Tekst pomocy ujawnia, że typ zwracany wymaga parametru ogólnego czasu życia, ponieważ Rust nie może określić, czy zwracana referencja odnosi się do x czy do y. Tak naprawdę my też tego nie wiemy, ponieważ blok if w ciele tej funkcji zwraca referencję do x, a blok else zwraca referencję do y!

Kiedy definiujemy tę funkcję, nie znamy konkretnych wartości, które zostaną do niej przekazane, więc nie wiemy, czy wykona się przypadek if czy else. Nie znamy również konkretnych czasów życia referencji, które zostaną przekazane, więc nie możemy spojrzeć na zasięgi, jak to zrobiliśmy w Listingach 10-17 i 10-18, aby określić, czy zwracana referencja będzie zawsze ważna. Sprawdzacz pożyczeń również nie może tego ustalić, ponieważ nie wie, jak czasy życia x i y odnoszą się do czasu życia wartości zwracanej. Aby naprawić ten błąd, dodamy ogólne parametry czasów życia, które zdefiniują relację między referencjami, aby sprawdzacz pożyczeń mógł przeprowadzić swoją analizę.

Składnia adnotacji czasów życia

Adnotacje czasów życia nie zmieniają długości życia żadnych referencji. Raczej opisują one relacje między czasami życia wielu referencji, nie wpływając na same czasy życia. Tak jak funkcje mogą przyjmować dowolny typ, gdy sygnatura określa ogólny parametr typu, tak samo funkcje mogą przyjmować referencje z dowolnym czasem życia, określając ogólny parametr czasu życia.

Adnotacje czasów życia mają nieco nietypową składnię: nazwy parametrów czasu życia muszą zaczynać się od apostrofu (') i zazwyczaj są małymi literami i bardzo krótkie, podobnie jak typy ogólne. Większość ludzi używa nazwy 'a dla pierwszej adnotacji czasu życia. Adnotacje parametrów czasu życia umieszczamy po & referencji, używając spacji do oddzielenia adnotacji od typu referencji.

Oto kilka przykładów – referencja do i32 bez parametru czasu życia, referencja do i32 z parametrem czasu życia o nazwie 'a, oraz zmienna referencja do i32, która również ma czas życia 'a:

&i32        // referencja
&'a i32     // referencja z jawnym czasem życia
&'a mut i32 // zmienna referencja z jawnym czasem życia

Jedna adnotacja czasu życia sama w sobie nie ma większego znaczenia, ponieważ adnotacje mają na celu poinformowanie Rust, jak ogólne parametry czasu życia wielu referencji odnoszą się do siebie. Przyjrzyjmy się, jak adnotacje czasu życia odnoszą się do siebie w kontekście funkcji longest.

W sygnaturach funkcji

Aby używać adnotacji czasów życia w sygnaturach funkcji, musimy zadeklarować ogólne parametry czasów życia w nawiasach kątowych między nazwą funkcji a listą parametrów, tak jak robiliśmy to z ogólnymi parametrami typów.

Chcemy, aby sygnatura wyrażała następujące ograniczenie: zwracana referencja będzie ważna tak długo, jak długo oba parametry są ważne. Jest to relacja między czasami życia parametrów a wartością zwracaną. Nazwiemy czas życia 'a, a następnie dodamy go do każdej referencji, jak pokazano w Listingu 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 }
}

Ten kod powinien się skompilować i dać pożądany rezultat, gdy użyjemy go z funkcją main z Listingu 10-19.

Sygnatura funkcji informuje teraz Rust, że dla pewnego czasu życia 'a, funkcja przyjmuje dwa parametry, z których oba są wycinkami ciągów znaków, które żyją co najmniej tak długo, jak czas życia 'a. Sygnatura funkcji informuje również Rust, że wycinek ciągu znaków zwrócony z funkcji będzie żył co najmniej tak długo, jak czas życia 'a. W praktyce oznacza to, że czas życia referencji zwróconej przez funkcję longest jest taki sam, jak krótszy z czasów życia wartości, do których odwołują się argumenty funkcji. Te relacje to to, czego chcemy, aby Rust używał podczas analizy tego kodu.

Pamiętaj, że kiedy określamy parametry czasu życia w sygnaturze tej funkcji, nie zmieniamy czasów życia żadnych wartości przekazanych ani zwracanych. Raczej określamy, że sprawdzacz pożyczeń powinien odrzucić wszelkie wartości, które nie przestrzegają tych ograniczeń. Zauważ, że funkcja longest nie musi dokładnie wiedzieć, jak długo będą żyły x i y, tylko że pewien zasięg może zostać podstawiony za 'a, który spełni tę sygnaturę.

Podczas adnotowania czasów życia w funkcjach, adnotacje umieszcza się w sygnaturze funkcji, a nie w jej ciele. Adnotacje czasów życia stają się częścią kontraktu funkcji, podobnie jak typy w sygnaturze. Posiadanie sygnatur funkcji zawierających kontrakt czasów życia oznacza, że analiza wykonywana przez kompilator Rust może być prostsza. Jeśli wystąpi problem z adnotacją funkcji lub sposobem jej wywołania, błędy kompilatora mogą wskazać precyzyjniej na część naszego kodu i ograniczenia. Gdyby kompilator Rust wyciągał więcej wniosków na temat tego, jakie relacje czasów życia zamierzaliśmy, kompilator mógłby wskazać tylko na użycie naszego kodu wiele kroków od przyczyny problemu.

Kiedy przekazujemy konkretne referencje do longest, konkretny czas życia, który jest podstawiany za 'a, to część zasięgu x, która nakłada się na zasięg y. Innymi słowy, ogólny czas życia 'a przyjmie konkretny czas życia, który jest równy krótszemu z czasów życia x i y. Ponieważ oznaczyliśmy zwracaną referencję tym samym parametrem czasu życia 'a, zwracana referencja będzie również ważna przez czas trwania krótszego z czasów życia x i y.

Przyjrzyjmy się, jak adnotacje czasów życia ograniczają funkcję longest poprzez przekazywanie referencji, które mają różne konkretne czasy życia. Listing 10-22 to prosty przykład.