Limbajul de programare Rust

de Steve Klabnik și Carol Nichols, cu contribuții din partea comunității Rust

Această versiune a textului presupune că utilizezi Rust 1.67.1 (lansat pe 2023-02-09) sau o versiune mai nouă. Pentru a instala sau actualiza Rust, accesează secțiunea "Instalare" din Capitolul 1.

Varianta HTML este disponibilă online la https://doc.rust-lang.org/stable/book/ și offline în instalațiile Rust realizate cu rustup; executați rustup docs --book pentru a o deschide.

Câteva traduceri realizate de comunitate sunt de asemenea disponibile.

Textul este de asemenea disponibil în format paperback și ebook de la No Starch Press.

🚨 Îți dorești o experiență de învățare mai interactivă? Încearcă o versiune diferită a Cărții Rust, disponibilă cu: chestionare, funcții de evidențiere, vizualizări și multe altele (în engleză): https://rust-book.cs.brown.edu

Cuvânt înainte

Nu a fost mereu atât de clar, dar limbajul de programare Rust este fundamental despre împuternicire: indiferent de ce tip de cod ești obișnuit să scrii acum, Rust te împuternicește să ajungi mai departe, să programezi cu încredere într-o gamă mai largă de domenii decât ai făcut-o până acum.

De exemplu, să luăm activitățile la nivel de "sistem", care implică detalii de nivel jos legate de managementul memoriei, reprezentarea datelor și concurență. În mod tradițional, această sferă a programării este percepută ca fiind obscură, accesibilă numai pentru câțiva aleși ce și-au dedicat ani de zile pentru a învăța cum să ocolească capcanele infame ale acesteia. Chiar și cei care lucrează în acest domeniu o fac cu mare precauție, pentru a nu-și expune codul la exploatări, căderi sau erori de corupere.

Rust dărâmă aceste bariere, eliminând vechile capcane și oferă un set de instrumente rafinat și prietenos care să te sprijine pe drumul tău. Programatorii care simt nevoia să coboare în straturile inferioare ale controlului pot face acest lucru cu Rust, fără a prelua riscurile obișnuite legate de crash-uri sau vulnerabilități de securitate și fără a fi nevoiți să stăpânească subtilitățile unui toolchain capricios. Mai mult de atât, limbajul este conceput să te îndrume natural către un cod fiabil, eficient din punct de vedere al vitezei și utilizării memoriei.

Programatorii care lucrează deja cu cod de nivel jos pot adopta Rust pentru a-și extinde orizonturile. De pildă, integrarea paralelismului în Rust presupune un risc relativ mic: erorile clasice sunt detectate de către compilator. Și poți încerca optimizări mai îndrăznețe în codul tău fiind încrezător că nu vei insera accidental crash-uri sau breșe de securitate.

Și totuși, Rust nu se limitează la programarea sistemică de nivel jos. Este destul de expresiv și ergonomic, astfel încât să facă scrierea aplicațiilor de consolă, a serverelor web, și a multor altor tipuri de programe o experiență plăcută - vei descoperi exemple simple ale acestor aspecte mai târziu în carte. Lucrând cu Rust, îți dezvolți competențe transferabile de la un domeniu la altul; poți învăța Rust prin scrierea unei aplicații web, apoi aplicând aceleași cunoștințe pentru a programa pe un Raspberry Pi.

Această carte adoptă deplin capacitățile Rust de a-și împuternici utilizatorii. Este un text prietenos și accesibil, menit să te ajute să avansezi nu doar în cunoașterea Rust, ci și în extinderea ambițiilor și încrederii tale ca programator în general. Deci, scufundă-te în lectură, pregătește-te să înveți - și bun venit în comunitatea Rust!

— Nicholas Matsakis și Aaron Turon

Introducere

Notă: Această ediție a cărții este la fel ca The Rust Programming Language disponibilă în format print și ebook de la No Starch Press.

Bine ai venit la The Rust Programming Language, o carte introductivă despre limbajul de programare Rust. Rust te ajută să dezvolți software mai rapid și mai fiabil. Ergonomia avansată și controlul fin al detaliilor sunt adesea văzute ca fiind în contradicție în design-ul limbajelor de programare; Rust își propune să armonizeze aceste aspecte. Echilibrând puterea tehnică avansată cu o experiență de dezvoltare agreabilă, Rust te lasă să gestionezi detalii precise ale utilizării memoriei și alte aspecte la nivel scăzut, fără dificultățile obișnuit asociate cu acest tip de control.

Pentru cine este destinat Rust

Rust este ideal pentru numeroase persoane, din diverse motive. Să vedem câteva dintre cele mai importante categorii.

Echipe de dezvoltatori

Rust se afirmă drept un instrument eficient pentru colaborarea în cadrul echipelor mari de dezvoltatori cu nivel diferit de experiență în programarea sistemelor. Codul low-level este susceptibil la o multitudine de bug-uri subtile, care în majoritatea celorlalte limbaje pot fi identificate doar prin teste riguroase și recenzii meticuloase ale codului efectuate de dezvoltatori experimentați. În Rust, compilatorul acționează ca o santinelă, refuzând să compileze codul care conține aceste erori subtile, inclusiv erorile de concurență. Colaborând îndeaproape cu compilatorul, echipa poate folosi timpul mai eficient pentru a se concentra pe logica programului decât pe urmărirea defectelor.

Rust contribuie la lumea programării de sistem cu setul său de instrumente de dezvoltare de ultimă oră:

• Cargo, managerul de dependențe și instrumentul de build încorporat, simplifică adăugarea, compilarea și coordonarea dependențelor într-un mod fără dureri de cap și omogen pe tot ecosistemul Rust.
• Instrumentul de formatare Rustfmt asigură un stil unic de codificare dintre dezvoltatori.
• Rust Language Server potențează integrarea în Integrated Development Environment (IDE) pentru auto-completarea codului și mesajele de eroare contextualizate.

Utilizând aceste facilități și altele din ecosistemul Rust, dezvoltatorii pot fi foarte eficienți în timpul scrierii codului la nivel de sistem.

Studenți

Rust se adresează studenților și tuturor celor interesați să învețe despre conceptele de sistem. Prin Rust, mulți au aprofundat teme legate de dezvoltarea sistemelor de operare. Comunitatea este extrem de primitoare și dornică să răspundă la întrebările studenților. Prin intermediul acestei cărți și alte inițiative, echipele Rust își propun să faciliteze accesul la conceptele de sistem unui număr și mai mare de persoane, în special celor care sunt la începutul drumului în programare.

Companii

Sute de companii, atât mari, cât și mici, folosesc Rust în producție pentru diverse activități, precum crearea de unelte pentru linia de comandă, servicii web, unelte pentru DevOps, dispozitive embedded, analiza și transcodarea audio-video, criptomonede, bioinformatică, motoare de căutare, aplicații pentru Internet of Things, machine learning și chiar componente esențiale ale browserului web Firefox.

Dezvoltatori open source

Rust este dedicat celor care vor să contribuie la dezvoltarea limbajului de programare Rust, a comunității, uneltelor pentru dezvoltatori și a bibliotecilor. Te așteptăm cu brațele deschise să contribui la dezvoltarea limbajului Rust.

Persoanele care prețuiesc viteza și stabilitatea

Rust se adresează celor care tânjesc după viteză și stabilitate într-un limbaj de programare. Prin viteză, ne referim atât la cât de repede poate rula codul Rust, cât și la rapiditatea cu care Rust te ajută să elaborezi programe. Verificările făcute de compilatorul Rust asigură stabilitatea prin introducerea de noi funcționalități și refactorizarea. Această abordare contrastează cu codul legacy fragil din limbaje fără aceste verificări, cod pe care dezvoltatorii adeseori se tem să-l modifice. Prin urmărirea abstracțiilor cu zero supra-cost, funcții de nivel înalt care se compilează la cod de nivel jos la fel de rapid ca și codul scris manual, Rust își propune să asigure că codul sigur este și cod rapid.

Limbajul Rust își propune să sprijine și alți utilizatori, pe lângă cei menționați; aceștia sunt doar unii dintre cei mai importanți. Per ansamblu, cea mai mare ambiție a Rust este să elimine compromisurile la care programatorii au consimțit de decenii, oferind în același timp siguranță și productivitate, viteză și ergonomie. Încearcă Rust și vezi dacă deciziile sale se potrivesc cu nevoile tale.

Pentru cine este această carte

Această carte presupune că ai deja experiență în scrierea de cod într-un alt limbaj de programare, dar nu se bazează pe presupunerea că ai folosit unul anume. Am adaptat materialul pentru a fi accesibil persoanelor cu experiențe diverse în programare. Nu ne-am concentrat în detaliu asupra discuției despre natura programării sau despre abordarea gândirii în termeni de programare. Dacă ești începător în domeniul programării, ai beneficia mai mult de pe urma unei cărți care oferă o introducere specifică în acest domeniu.

Cum să folosești această carte

De regulă, această carte este concepută să fie citită în ordine, de la prima pagină până la ultima. Capitolul următor se bazează pe conceptele prezentate în capitolele anterioare, și capitolele anterioare pot să nu abordeze în detalii un anumit subiect, ci să revină asupra lui într-un capitol mai înaintat.

Vei găsi două tipuri de capitole în această carte: capitole de concepte și capitole de proiecte. În capitolele de concepte, vei afla detalii despre un aspect al limbajului Rust. În capitolele de proiecte, vom dezvolta împreună programe mici, aplicând ceea ce ai învățat până în momentul acela. Capitolele 2, 12 și 20 sunt capitole de proiecte; celelalte sunt capitole de concepte.

Capitolul 1 explică cum să instalezi Rust, cum să scrii un program „Hello, world!” și cum să folosești Cargo, managerul de pachete și uneltele de construire din Rust. Capitolul 2 oferă o introducere practică în scrierea unui program Rust prin construirea unui joc de ghicit numere. Acolo tratăm conceptele la un nivel mai general, iar capitolele viitoare vor intra în mai multe detalii. Dacă ești nerăbdător să începi practic, Capitolul 2 este ideal pentru acest lucru. Capitolul 3 tratează facilitățile din Rust comune cu alte limbaje de programare, iar în Capitolul 4 vei învăța despre sistemul specific Rust de posesiune. Dacă ești o persoană extrem de meticuloasă și preferi să cunoști fiecare detaliu înainte de a avansa, ai putea să sari peste Capitolul 2 și să treci direct la Capitolul 3, revenind la Capitolul 2 când vrei să exersezi pe un proiect, aplicând detaliile învățate.

Capitolul 5 discută structurile și metodele, iar Capitolul 6 prezintă enumerările, expresiile match și structura de control if let. În Rust, vei folosi structurile și enumerările pentru a defini tipuri de date personalizate.

În Capitolul 7, vei învăța despre sistemul de module al Rust și despre regulile de confidențialitate pentru structurarea codului tău și a Interfeței de Programare a Aplicațiilor (API) publice. Capitolul 8 abordează unele structuri de date de colecții uzuale pe care le furnizează biblioteca standard, cum ar fi vectorii, string-urile și hashmap-urile. Capitolul 9 tratează filosofia și tehnicile de gestionare a erorilor în Rust.

Capitolul 10 aprofundează conceptele de generici, trăsături și durate de viață, ce îți oferă capacitatea de a defini cod util pentru diferite tipuri. Capitolul 11 are în centrul atenției testarea, necesară pentru a verifica corectitudinea raționamentului logic al programului tău, chiar dacă Rust oferă garanții de siguranță. În Capitolul 12, vom crea propria variantă a unei părți din funcționalitățile comenzii grep, care permite căutarea textului în fișiere, folosind multe din conceptele prezentate în capitolele precedente.

Capitolul 13 introduce închiderile și iteratorii, elemente din Rust influențate de limbajele de programare funcționale. Capitolul 14 este dedicat unei analize detaliate a Cargo și discuții despre practicile ideale pentru distribuirea bibliotecilor tale către alții. Capitolul 15 prezintă pointerii inteligenți disponibili în biblioteca standard și trăsăturile care le susțin funcționalitatea.

Capitolul 16 te va ghida prin diferitele paradigme de programare concurentă și va explora cum Rust facilitează programarea pe multe fire de execuție fără temeri. Capitolul 17 compară expresiile Rust cu principiile familiale ale programării orientate-obiect.

Capitolul 18 servește drept ghid pentru pattern-uri și potrivirea pattern-urilor, metode eficace de comunicare a ideilor în cadrul programelor Rust. Capitolul 19 oferă o gamă largă de subiecte avansate captivante, printre care Rust-ul nesigur, macrocomenzile, precum și aspecte suplimentare despre duratele de viață, trăsăturile, tipurile, funcțiile și închiderile.

În Capitolul 20, vom completa un proiect în care vom implementa un server web de nivel scăzut cu fire de execuție multiple!

În final, unele anexe conțin informații utile despre limbaj într-un format mai apropiat de cel de referință. Anexa A este despre cuvintele cheie din Rust, Anexa B despre operatorii și simbolurile din Rust, Anexa C despre trăsăturile derivabile oferite de biblioteca standard, Anexa D despre unele instrumente de dezvoltare utile și Anexa E explică edițiile Rust. În Anexa F poți găsi traduceri ale cărții, iar în Anexa G vom explica cum este dezvoltat Rust și ce înseamnă Nightly Rust.

Nu e nicio metodă greșită de a citi această carte: dacă dorești să sari peste unele părți, fă-o! Poate fi nevoie să te întorci la capitolele anterioare dacă întâmpini greutăți. Dar fă ceea ce ți se potrivește.

O parte importantă a procesului de învățare Rust este să înveți cum să citești mesajele de eroare afișate de compilator: acestea te vor îndruma către un cod funcțional. Prin urmare, vom prezenta multe exemple care nu se compilează, alături de mesajul de eroare pe care compilatorul îl va afișa în fiecare situație. Înainte de a introduce și rula un exemplu la întâmplare, ține cont că s-ar putea să nu se compileze! Asigură-te că ai citit textul înconjurător pentru a vedea dacă exemplul pe care încerci să îl execuți este menit să genereze o eroare. Ferris te va ajuta să distingi și codul care nu este destinat să funcționeze:

Ferris	Semnificație
	Codul nu se compilează!
	Codul generează panică!
	Codul nu are comportamentul așteptat.

În majoritatea situațiilor, te vom îndruma către versiunea corectă a oricărui cod care nu compilează.

Codul sursă

Fișierele sursă din care această carte a fost generată pot fi găsite pe GitHub.

Să începem

Să începem aventura noastră în Rust! Avem multe de învățat, dar orice călătorie începe cu un punct de pornire. În acest capitol, vom acoperi:

• Instalarea Rust pe sistemele de operare Linux, macOS și Windows.
• Crearea unui program care afișează Salut, lume!
• Utilizarea cargo, managerul de pachete și sistemul de build specific Rust.

Instalare

Primul pas este să instalezi Rust. Vom descărca Rust folosind rustup, un instrument de linie de comandă pentru gestionarea versiunilor Rust și a uneltelor asociate. Vei avea nevoie de o conexiune la internet pentru descărcare.

Notă: Dacă preferi să nu folosești rustup dintr-un motiv oarecare, te rugăm să consulți pagina cu Alte metode de instalare Rust pentru mai multe opțiuni.

Următorii pași instalează cea mai recentă versiune stabilă a compilatorului Rust. Rust oferă garanții de stabilitate care asigură că toate exemplele din carte compatibile cu versiuni anterioare vor rămâne funcționale și pe versiunile Rust ulterioare. Ieșirea s-ar putea să difere ușor între versiuni deoarece Rust îmbunătățește adesea mesajele de eroare și avertismentele. Cu alte cuvinte, orice versiune stabilă mai nouă de Rust pe care o instalezi folosind acești pași ar trebui să funcționeze așa cum este de așteptat cu conținutul acestei cărți.

Notația pentru linia de comandă

De-a lungul acestui capitol și a cărții, vom indica diferite comenzi utilizate în terminal. Liniile ce urmează să le tastezi într-un terminal încep cu $. Nu trebuie să tastezi caracterul $; acesta semnalizează începutul unei comenzi în terminal. Liniile care nu încep cu $ reprezintă în mod obișnuit output-ul comenzii anterioare. În plus, exemplele destinate PowerShell vor utiliza > în loc de $.

Instalarea rustup pe Linux sau macOS

Dacă folosești Linux sau macOS, deschide un terminal și introduce următoarea comandă:

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

Comanda descarcă un script și începe instalarea instrumentului rustup, care instalează cea mai recentă versiune stabilă a Rust. S-ar putea să ți se ceară parola. Dacă instalarea este reușită, va apărea următoarea linie:

Rust is installed now. Great!

De asemenea, va trebui să ai un linker, care este un program pe care Rust îl folosește pentru a uni toate afișajele sale compilate într-un singur fișier. Probabil deja ai unul. Dacă primești erori legate de linker, ar trebui să instalezi un compilator C, acesta include de obicei un linker. Un compilator C este util și pentru că unele pachete comune din Rust depind de codul C și vor avea nevoie de un compilator C.

Pe macOS, poți obține un compilator C cu următoarea comandă:

$ xcode-select --install

Utilizatorii de Linux ar trebui să instaleze, în general, GCC sau Clang, conform documentației distribuției lor. De exemplu, dacă folosești Ubuntu, poți instala pachetul build-essential.

Instalarea rustup pe Windows

Pe Windows, accesează https://www.rust-lang.org/tools/install și urmează instrucțiunile pentru instalarea Rust. La un moment dat în procesul de instalare, vei primi un mesaj care îți explică faptul că este necesar să ai și instrumentele de compilare MSVC pentru Visual Studio 2013 sau mai târziu.

Pentru a obține instrumentele de compilare, trebuie să instalezi Visual Studio 2022. Când îți va fi solicitat să alegi ce utilități de lucru să instalezi, asigură-te că incluzi:

• „Desktop Development with C++”
• SDK-ul pentru Windows 10 sau 11
• Componenta pachetului de limbă engleză, împreună cu orice alte pachete de limbă după preferință

Restul acestei cărți utilizează comenzi compatibile atât cu cmd.exe, cât și cu PowerShell. Dacă există diferențe specifice între acestea, noi vom explica care versiune trebuie utilizată.

Depanare

Pentru a verifica dacă ai instalat corect Rust, deschide o consolă și introdu această linie:

$ rustc --version

Ar trebui să vezi numărul versiunii, hash-ul commit-ului și data commit-ului pentru cea mai recent lansată versiune stabilă, în următorul format:

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

Dacă vezi aceste informații, ai instalat cu succes Rust! Dacă nu vezi aceste informații, verifică dacă Rust se află în variabila de sistem %PATH%` în felul următor.

În CMD Windows, folosește:

> echo %PATH%

În PowerShell, folosește:

> echo $env:Path

În Linux și macOS, folosește:

$ echo $PATH

Dacă totul este corect și Rust tot nu funcționează, există mai multe locuri în care poți obține ajutor. Află cum să iei legătura cu alți Rustaceani (un pseudonim amuzant pe care noi îl folosim) pe pagina comunității.

Actualizare și dezinstalare

Odată ce Rust este instalat prin intermediul rustup, actualizarea la o versiune nou lansată este ușoară. Din terminalul tău, rulează următorul script de actualizare:

$ rustup update

Pentru a dezinstala Rust și rustup, rulează următorul script de dezinstalare din terminal:

$ rustup self uninstall

Documentație locală

Instalarea Rust include și o copie locală a documentației, astfel încât să o poți citi offline. Rulează rustup doc pentru a deschide documentația locală în browserul tău.

De fiecare dată când un tip sau o funcție este furnizată de biblioteca standard și nu ești sigur ce face sau cum să o folosești, apelează la documentația interfeței de programare a aplicațiilor (API) pentru a afla!

Salut, lume!

Acum că ai instalat Rust, este timpul să scrii primul tău program în Rust. Tradițional, când învățăm un limbaj nou, scriem un mic program care afișează textul Salut, lume! pe ecran. Așadar, vom face la fel și aici!

Notă: Această carte presupune cunoștințe de bază a liniei de comandă. Rust nu are cerințe specifice despre editarea, uneltele tale sau locul unde se află codul tău, așa că dacă preferi să folosești un mediu de dezvoltare integrat (IDE) în locul liniei de comandă, nu ezita să folosești IDE-ul tău preferat. Multe IDE-uri au acum un anumit grad de suport Rust; verifică documentația IDE-ului pentru detalii. Echipa Rust s-a concentrat pe facilitarea unui suport IDE excelent prin rust-analyzer. Vezi Anexa D pentru mai multe detalii.

Crearea unui directoriu pentru proiect

O să începem prin a crea un directoriu unde să îți stochezi codul Rust. Pentru Rust nu contează unde este situat codul tău, însă pentru exercițiile și proiectele din această carte, recomandăm crearea unui directoriu projects în directoriu tău home și să menții toate proiectele acolo.

Deschide un terminal și execută următoarele comenzi pentru a crea un directoriu projects și un directoriu pentru proiectul "Hello, world!" în cadrul directoriu projects.

Pentru Linux, macOS și PowerShell pe Windows, execută acestea:

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

Pentru CMD pe Windows, introdu asta:

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

Scrierea și rularea unui program Rust

În continuare, creează un nou fișier sursă și numește-l main.rs. Fișierele Rust se termină întotdeauna cu extensiunea .rs. Dacă folosești mai mult de un cuvânt în numele fișierului tău, convenția este să folosești un underscore pentru a le separa. De exemplu, folosește hello_world.rs în loc de helloworld.rs.

Acum deschide fișierul main.rs pe care tocmai l-ai creat și introdu codul din Listarea 1-1.

Numele fișierului: main.rs

fn main() {
    println!("Salut, lume!");
}

Listarea 1-1: Un program care afișează Salut, lume!

Salvează fișierul și întoarce-te la fereastra terminalului în directorul ~/projects/hello_world. Pe Linux sau macOS, introdu următoarele comenzi pentru a compila și a rula fișierul:

$ rustc main.rs
$ ./main
Salut, lume!

Pe Windows, introdu comanda .\main.exe în loc de ./main:

> rustc main.rs
> .\main.exe
Salut, lume!

Indiferent de sistemul tău de operare, Salut, lume! ar trebui să fie afișat în terminal. Dacă nu vezi acest rezultat, verifică din nou partea de „Depanare” a secțiunii de instalare pentru a obține ajutor.

Dacă Salut, lume! a apărut, felicitări! Ai scris oficial un program Rust. Asta te face un programator Rust - bun venit!

Anatomia unui program Rust

Să revizuim în detaliu acest program "Salut, lume!". Iată prima piesă a puzzle-ului:

fn main() {

}

Aceste linii definesc o funcție numită main. Funcția main este specială: este întotdeauna primul cod care rulează în fiecare program Rust executabil. Aici, prima linie declară o funcție numită main care nu are parametri și nu returnează nimic. Dacă ar fi existat parametri, aceștia ar fi fost specificați între parantezele ().

Corpul funcției este înconjurat de {}. Rust necesită acolade în jurul tuturor corpurilor de funcție. Este considerat un stil bun să plasezi acolada de deschidere pe aceeași linie cu declarația funcției, adăugând un spațiu între acestea.

Notă: Dacă vrei să urmezi un stil standard în toate proiectele tale Rust, poți folosi un utilitar de formatare automată denumit rustfmt pentru a-ți formata codul într-o manieră specifică (vei găsi mai multe detalii despre rustfmt în Anexa D). Acest utilitar este inclus de echipa Rust în distribuția standard de Rust, la fel ca rustc, așa că cel mai probabil este deja instalat pe computerul tău!

Corpul funcției main conține următorul cod:

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

Această linie efectuează toată munca în acest program simplu: tipărește textul pe ecran. Sunt patru detalii importante de observat aici.

În primul rând, stilul Rust este de a indenta cu patru spații, nu cu un tab.

În al doilea rând, println! apelează un macro Rust. Dacă ar fi apelat o funcție în loc, ar fi fost introdus ca println (fără !). Vom discuta macrourile Rust în detaliu în Capitolul 19. Deocamdată, trebuie doar să știi că utilizarea unui ! înseamnă că apelezi un macro în locul unei funcții normale și că macrourile nu urmează întotdeauna aceleași reguli ca funcțiile.

În al treilea rând, observăm string-ul "Salut, lume!". Noi trecem acest string ca un argument către println!, iar string-ul este tipărit pe ecran.

În al patrulea rând, încheiem linia cu un punct și virgulă (;), care indică faptul că această expresie s-a încheiat și următoarea este gata să înceapă. Cele mai multe linii de cod Rust se încheie cu un punct și virgulă.

Compilarea și rularea sunt etape separate

Tocmai ai rulat un program nou creat, așadar să examinăm fiecare pas în proces.

Înainte de a rula un program Rust, trebuie să îl compilezi folosind compilatorul Rust, introducând comanda rustc în consolă și trecând numele fișierului tău sursă, astfel:

$ rustc main.rs

Dacă ai experiență cu C sau C++, vei observa că acest lucru este similar cu gcc sau clang. După o compilare reușită, Rust generează un executabil binar.

Pe Linux, macOS, și în PowerShell pe Windows, poți vedea executabilul introducând comanda ls în consolă:

$ ls
main  main.rs

Pe Linux și macOS, vei vedea două fișiere: 'main' și 'main.rs'. Pe Windows, folosind PowerShell sau CMD, vei vedea, de asemenea, fișierul 'main.exe' și un fișier de depanare cu extensia .pdb, alături de main.rs. Cu CMD pe Windows, ai introduce următoarea comandă:

> dir /B %= opțiunea /B indică doar numele fișierelor =%
main.exe
main.pdb
main.rs

Aceasta afişează fișierul sursă cu extensia .rs, fișierul executabil (main.exe pe Windows, dar main pe toate celelalte platforme), și, atunci când folosești Windows, un fișier care conține informații de depanare cu extensia .pdb. De aici, rulezi fișierul main sau main.exe, astfel:

$ ./main # sau .\main.exe pe Windows

Dacă main.rs este programul tău „Salut, lume!”, această linie va afișa în consolă Salut, lume!.

Dacă ai început cu un limbaj dinamic, așa cum sunt Ruby, Python sau JavaScript, este posibil să nu-ți fie clar faptul de a compila și rula un program în pași separați. Rust este un limbaj compilat înainte de execuție, ceea ce înseamnă că poți să compilezi un program și să dai executabilul cuiva altcuiva, și aceștia vor putea să îl ruleze chiar și fără să aibă Rust instalat. În schimb, dacă dai cuiva un fișier .rb, .py, sau .js, persoana respectivă trebuie să aibă instalată o variantă corespunzătoare de Ruby, Python sau JavaScript. Cu toate acestea, în limbaje precum Ruby, Python sau JavaScript, compilezi și rulezi programul tău folosind o singură comandă. Fiecare decizie în designul limbajului de programare reprezintă un compromis.

Compilarea doar cu rustc este adecvată pentru programele simple, dar pe măsură ce proiectul tău se extinde, vei dori să controlezi toate opțiunile și să îți facilitezi partajarea codului. În continuare, vom explora utilizarea utilitarului Cargo, care ne va sprijini în scrierea programelor Rust pentru scenarii din lumea reală.

Salut, Cargo!

Cargo este sistemul de construcție și managerul de pachete al lui Rust. Majoritatea programatorilor Rust folosesc acest instrument pentru a-și gestiona proiectele Rust deoarece Cargo se ocupă de o mulțime de sarcini pentru tine, precum compilarea codului, descărcarea librăriilor de care depinde el și compilarea acestor librării. (Noi, de regulă, numim librăriile dependențe.)

Cele mai simple programe Rust, ca cel pe care l-am scris până acum, nu au nicio dependență. Dacă am fi compilat proiectul „Salut, lume!” cu Cargo, atunci doar partea responsabilă de compilare din Cargo ar fi fost utilizată. Pe măsură ce proiectele tale Rust devin mai complexe, este probabil să adaugi mai multe dependențe și dacă începi un proiect folosind Cargo, adăugarea dependențelor va fi mult mai ușor de făcut.

Deoarece majoritatea covârșitoare a proiectelor Rust folosesc Cargo, în restul acestei cărți vom presupune că și tu folosești Cargo. Cargo vine instalat cu Rust dacă ai folosit instalatoarele oficiale discutate în secțiunea „Instalare”. Dacă ai instalat Rust prin alte mijloace, poți verifica dacă Cargo este instalat prin introducerea următoarei comenzi în terminal:

$ cargo --version

Dacă vezi un număr de versiune, îl ai! Dacă vezi o eroare, cum ar fi command not found, uită-te la documentația metodei tale de instalare pentru a determina cum să instalezi Cargo separat.

Crearea unui proiect cu Cargo

Să creăm un proiect nou folosind Cargo și să vedem cum se deosebește de proiectul nostru original „Salut, lume!”. Navighează înapoi în directoriul tău proiecte (sau oriunde ai ales să-ți stochezi codul). Apoi, pe orice sistem de operare, rulează următoarele:

$ cargo new hello_cargo
$ cd hello_cargo

Prima comandă creează un directoriu și un proiect nou numit hello_cargo. Noi am numit proiectul nostru hello_cargo, iar Cargo creează fișierele sale într-un directoriu cu același nume.

Du-te în directoriul hello_cargo și listează fișierele. Vei vedea că Cargo a generat două fișiere și un directoriu: un fișier Cargo.toml și un directoriu src cu un fișier main.rs în interior.

A creat de asemenea un nou repozitoriu Git împreună cu un fișier .gitignore. Cargo nu va iniția un nou repozitoriu Git dacă comanda cargo new este rulată în interiorul unui repozitoriu Git existent; poți anula această comportare folosind cargo new --vcs=git.

Notă: Git este un sistem popular de control al versiunilor. Poți modifica cargo new pentru a folosi un alt sistem de control al versiunilor sau niciun sistem de control al versiunilor folosind comutația --vcs. Rulează cargo new --help pentru a vedea opțiunile disponibile.

Deschide Cargo.toml în editorul tău de text preferat. Ar trebui să arate similar cu codul din Listarea 1-2.

Numele fișierului: Cargo.toml

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

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

Listarea 1-2: Conținutul lui Cargo.toml generat de cargo new

Acest fișier este în formatul TOML (Tom’s Obvious, Minimal Language), care este formatul de configurare al lui Cargo.

Prima linie, [package], este o rubrică de secțiune care indică faptul că declarațiile următoare configurează un pachet. Pe măsură ce adăugăm mai multe informații la acest fișier, vom adăuga și alte secțiuni.

Următoarele trei linii setează informațiile de configurare de care Cargo are nevoie pentru a compila programul tău: numele, versiunea și ediția Rust pe care să o folosească. Vom vorbi despre cheia edition în Anexa E.

Ultima linie, [dependencies], este începutul unei secțiuni în care poți enumera orice dependențe ale proiectului tău. În Rust, pachetele de cod sunt numite crates. Nu vom avea nevoie de alte crate-uri pentru acest proiect, dar vom avea în primul proiect din Capitolul 2, deci vom folosi această secțiune de dependențe atunci.

Acum deschide src/main.rs și aruncă o privire:

Numele fișierului: src/main.rs

fn main() {
    println!("Salut, lume!");
}

Cargo tocmai a generat un program „Salut, lume!”, identic cu cel pe care l-am realizat noi în Listarea 1-1! Până acum, principalele diferențe dintre proiectul nostru și cel creat de Cargo sunt așezarea codului în directoriul src și existența unui fișier de configurare Cargo.toml în directoriul rădăcină.

Cargo așteaptă ca fișierele sursă să fie poziționate în interiorul directoriului src. Directoriul rădăcină al proiectului este destinat doar pentru fișierele README, informațiile despre licență, fișiere de configurare și orice altceva care nu este direct legat de cod. Utilizarea Cargo contribuie la organizarea eficientă a proiectelor tale, având un loc bine definit pentru fiecare componentă și asigurându-se că toate componentele sunt la locul potrivit.

Dacă ai început un proiect fără să folosești Cargo, așa cum am procedat noi cu proiectul „Salut, lume!”, poți să îl transformi într-un proiect care utilizează Cargo. Trebuie să muti codul în directoriul src și să creezi un fișier Cargo.toml adecvat.

Compilarea și rularea unui proiect Cargo

Acum să ne uităm la ce e diferit când compilăm și rulăm programul „Salut, lume!” cu Cargo! Din directoriul tău hello_cargo, compilează proiectul prin introducerea următoarei comenzi:

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

Această comandă creează un fișier executabil în target/debug/hello_cargo (sau target\debug\hello_cargo.exe pe Windows) mai degrabă decât în directoriul tău curent. Pentru că build-ul implicit este un build de depanare, Cargo pune binarul într-un directoriu numit debug. Poți rula executabilul cu această comandă:

$ ./target/debug/hello_cargo # sau .\target\debug\hello_cargo.exe pe Windows
Salut, lume!

Dacă totul merge conform planului, Hello, world! ar trebui să fie afișat în terminal. Folosirea comenzii cargo build pentru prima oară, de asemenea, determină Cargo să creeze un fișier nou la nivelul cel mai de sus: Cargo.lock. Acest fișier ține evidența versiunilor exacte ale dependențelor din proiectul tău. Proiectul acesta nu are dependențe, așadar fișierul este destul de simplu. Nu va fi necesar să intervenim manual asupra acestui fișier; Cargo va gestiona conținutul pentru noi.

Am compilat un proiect folosind cargo build și l-am executat cu ./target/debug/hello_cargo, însă putem de asemenea să utilizăm comanda cargo run pentru a compila codul și apoi a executa fișierul rezultat, totul printr-o singură comandă:

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

Utilizarea cargo run este mai convenabilă decât să trebuiască să ne amintim să executăm cargo build și apoi să accedem toată calea către executabil, așa că majoritatea dezvoltatorilor preferă cargo run.

Observă că de această dată nu am văzut un afișaj care să indice dacă Cargo a compilat hello_cargo. Cargo a înțeles că fișierele nu au suferit modificări, și prin urmare, nu a necesitat o recompilare ci doar a executat binarul. Dacă ai modificat codul sursă, Cargo ar fi recompilat proiectul înainte de a-l executa, și ai fi observat acest afișaj:

$ 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`
Salut, lume!

Cargo oferă de asemenea o comandă numită cargo check. Această comandă verifică rapid codul tău pentru a se asigura că se compilează, dar nu produce un executabil:

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

De ce nu ai vrea un executabil? Adesea, cargo check este mult mai rapidă decât cargo build pentru că omite pasul de producere a unui executabil. Dacă verifici în continuu ce lucrezi în timp ce scrii codul, folosirea cargo check va accelera procesul de a te informa dacă proiectul tău încă se compilează! Astfel, mulți Rustaceani rulează cargo check periodic în timp ce scriu programul lor pentru a se asigura că se compilează. Apoi ei rulează cargo build când sunt gata să folosească executabilul.

Să recapitulăm ce am învățat până acum despre Cargo:

• Putem crea un proiect folosind cargo new.
• Putem compila un proiect folosind cargo build.
• Putem compila și rula un proiect într-un singur pas folosind cargo run.
• Putem compila un proiect fără a produce un binar pentru a verifica erorile folosind cargo check.
• În loc sa salvăm rezultatul build-ului in același directoriu cu codul nostru, Cargo il stocheaza in directoriul target/debug.

Un avantaj suplimentar al folosirii lui Cargo este că comenzile sunt la fel, indiferent de sistemul de operare pe care lucrezi. Așadar, de la acest punct nu vom mai oferi instrucțiuni specifice pentru Linux și macOS versus Windows.

Compilarea pentru lansare

Când proiectul tău este în sfârșit gata de lansare, poți utiliza cargo build --release pentru a-l compila cu optimizări. Această comandă va crea un executabil în target/release în loc de target/debug. Optimizările fac codul tău Rust să ruleze mai rapid, dar activarea lor mărește timpul necesar pentru compilarea programului. Din acest motiv există două profiluri diferite: unul pentru dezvoltare, când vrei să recompilezi repede și des, și altul pentru compilarea programului final pe care îl vei oferi unui utilizator care nu va fi recompilat în mod repetat și care va rula cât mai rapid posibil. Dacă îți evaluezi timpul de rulare al codului, nu uita să folosești comanda cargo build --release și să realizezi evaluarea cu executabilul din target/release

Cargo în calitate de convenție

Pentru proiecte simple, Cargo nu oferă multă valoare peste utilizarea directă a lui rustc, dar își va demonstra valoarea pe măsură ce programele tale devin mai complexe. Odată ce programele cresc la mai multe fișiere sau au nevoie de o dependență, este mult mai ușor să lași Cargo să coordoneze compilarea.

Deși proiectul hello_cargo este simplu, acum folosește o mare parte din instrumentele reale pe care le vei folosi în restul carierei tale Rust. De fapt, pentru a lucra la orice proiecte existente, poți folosi următoarele comenzi pentru a verifica codul folosind Git, pentru a schimba directoriul către acel proiect și pentru a compila:

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

Pentru mai multe informații despre Cargo, vezi documentația sa.

Sumar

Ești deja pe drumul cel bun în călătoria ta cu Rust! În acest capitol, ai învățat să:

• Instalezi cea mai recentă versiune stabilă a Rust folosind rustup
• Actualizezi la o versiune mai nouă a Rust
• Deschizi documentația instalată local
• Scrii și rulezi un program „Salut, lume!” folosind rustc direct
• Creezi și rulezi un proiect nou folosind convențiile Cargo

Acesta este momentul perfect pentru a crea un program mai substanțial pentru a te familiariza cu citirea și scrierea codului Rust. Așadar, în Capitolul 2, vom scrie un program de joc de ghicit. Dacă ai prefera mai degrabă să începi prin a învăța cum funcționează conceptele comune de programare în Rust, vezi Capitolul 3 și apoi întoarce-te la Capitolul 2.

Programarea unui joc de ghicit

Să ne avântăm în Rust lucrând împreună la un proiect direct aplicabil! În acest capitol o să te familiarizezi cu câteva concepte uzitate în Rust, arătându-ți cum să le aplici într-un program concret. Îți vei însuși cunoștințe despre let, match, metode, funcții asociate, crate-uri externe și mai mult! În capitolele ce urmează, vom aprofunda aceste idei. Pentru moment, ne vom concentra pe exersarea noțiunilor fundamentale.

Vom pune în aplicare o problemă emblematică pentru începătorii în programare: un joc de ghicit. Iată în ce constă: programul va genera un număr întreg aleatoriu între 1 și 100. Va solicita apoi jucătorului să introducă o ghicire. După ce un număr a fost introdus, programul va specifica dacă acesta este prea mic sau prea mare. Dacă răspunsul este corect, jocul va afișa un mesaj de felicitare și se va închide.

Formarea unui proiect nou

Pentru a forma un proiect nou, mergi la directoriul proiecte pe care l-ai creat în Capitolul 1 și fă un proiect nou folosind Cargo, astfel:

$ cargo new guessing_game
$ cd guessing_game

Prima comandă, cargo new, ia numele proiectului (guessing_game) ca prim argument. A doua comandă trece la directoriul noului proiect.

Aruncă o privire la fișierul Cargo.toml generat:

Numele fișierului: Cargo.toml

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

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

După cum ai văzut în Capitolul 1, cargo new generează un program “Salut, lume!” pentru tine. Verifică fișierul src/main.rs:

Numele fișierului: src/main.rs

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

Acum să compilăm acest program „Salut, lume!" și să îl rulăm în același pas folosind comanda cargo run:

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

Comanda run este utilă când ai nevoie să iterezi rapid pe un proiect, așa cum vom face în acest joc, testând rapid fiecare iterație înainte de a trece la următoarea.

Deschide din nou fișierul src/main.rs. Vei scrie tot codul în acest fișier.

Procesarea unei ghiciri

Prima parte a programului de ghicit va cere intrarea utilizatorului, va procesa acea intrare și va verifica dacă intrarea este în forma așteptată. Pentru început, vom permite jucătorului să introducă o ghicire. Introdu codul din Listare 2-1 în src/main.rs.

Numele fișierului: 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}");
}

Lstarea 2-1: Cod care obține o ghicire de la utilizator și o tipărește

Acest cod conține o mulțime de informații, deci să-l parcurgem linie cu linie. Pentru a obține intrarea utilizatorului și apoi a printa rezultatul ca ieșire, avem nevoie să aducem biblioteca io de intrare/ieșire în scopul nostru. Biblioteca io vine din biblioteca standard, cunoscută sub numele de 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}");
}

În mod implicit, Rust are un set de elemente definite în librăria standard pe care le introduce în domeniul de vizibilitatea al fiecărui program. Acest set se numește prelude, și poți vedea tot ce se află în el în documentația librăriei standard.

Dacă un tip pe care dorești să-l folosești nu se află în prelude, trebuie să introduci acel tip explicit în domeniu cu o instrucțiune use. Utilizarea librăriei std::io îți oferă un număr de caracteristici utile, inclusiv capacitatea de a accepta intrarea utilizatorului.

După cum ai văzut în Capitolul 1, funcția main este punctul de intrare în program:

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

Sintaxa fn declară o nouă funcție; parantezele, (), indică faptul că nu există parametri; iar paranteza rotundă, {, începe corpul funcției.

Așa cum ai învățat și în Capitolul 1, println! este o macrocomandă care tipărește un string pe ecran:

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

Acest cod afișează un prompt care indică ce joc este și solicită intrare de la utilizator.

Păstrarea valorilor cu variabile

În continuare, vom crea o variabilă pentru a stoca input-ul utilizatorului, astfel:

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

Acum programul devine interesant! Se întâmplă multe în această mică linie. Folosim declarația let pentru a crea variabila. Iată un alt exemplu:

let apples = 5;

Această linie de cod creează o nouă variabilă numită apples și o leagă de valoarea 5. În Rust, variabilele sunt imutabile în mod implicit, ceea ce înseamnă că odată ce dăm variabilei o valoare, valoarea nu se va schimba. Vom discuta acest concept în detaliu în secțiunea „Variabile și mutabilitate” din Capitolul 3. Pentru a face o variabilă mutabilă, adăugăm mut înainte de numele variabilei:

let apples = 5; // imutabil
let mut bananas = 5; // mutabil

Notă: Sintaxa // începe un comentariu care continuă până la sfârșitul liniei. Rust ignoră totul în comentarii. Vom discuta comentariile în mai multe detalii în Capitolul 3.

Revenind la programul de ghicit, acum știi că let mut guess va introduce o variabilă mutabilă denumită guess. Semnul egal (=) spune lui Rust că dorim să legăm ceva la variabilă acum. Pe dreapta semnului egal se află valoarea la care guess este legată, care este rezultatul apelării functiei String::new, o funcție care returnează o nouă instanță a unui String. String este un tip de string furnizat de librăria standard care este un text codificat UTF-8 care poate să crească.

Sintaxa :: din linia ::new indică că new este o funcție asociată tipului String. O funcție asociată este o funcție care este implementată pe un tip, în acest caz String. Această funcție new creează un string nou și gol. Vei găsi o funcție new în multe tipuri deoarece este un nume obișnuit pentru o funcție care face o valoare nouă de un anume fel.

În întregime, linia let mut guess = String::new(); a creat o variabilă mutabilă care este în prezent legată de o nouă instanță goală a unui String. Uf!

Primirea datelor introduse de utilizator

Ține minte că am inclus funcționalitatea de intrare/ieșire din biblioteca standard cu use std::io; pe prima linie a programului. Acum vom apela funcția stdin din modulul io, care ne va permite să gestionăm datele introduse de utilizator:

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

Dacă nu am fi importat biblioteca io cu use std::io; la începutul programului, am putea totuși să folosim funcția scriind acest apel de funcție ca std::io::stdin. Funcția stdin returnează o instanță a std::io::Stdin, care este un tip care reprezintă un handle la intrarea standard pentru terminalul tău.

Următoarea linie, .read_line(&mut guess) apelează metoda read_line pe handle-ul de intrare standard pentru a primi datele introduse de utilizator. De asemenea, trimitem &mut guess ca argument pentru read_line, pentru a-i spune în ce string să stocheze datele introduse de utilizator. Rolul principal al read_line este de a prelua tot ceea ce tapează utilizatorul în intrarea standard și de a adăuga aceste date într-un string (fără a-i suprascrie conținutul), deci vom trimite acest string ca argument. String-ul de argument trebuie să fie mutabil pentru ca metoda să poată schimba conținutul lui.

Simbolul & indică faptul că acest argument este o referință, care îți oferă o modalitate de a permite mai multor părți ale codului tău să acceseze o singură piesă de date fără a avea nevoie să copiezi acele date în memorie de mai multe ori. Referințele sunt o caracteristică complexă, iar unul dintre principalele avantaje ale Rust este cât de sigur și ușor e de utilizat referințele. Nu ai nevoie să știi o mulțime de acele detalii pentru a termina acest program. Deocamdată, tot ce trebuie să știi este că, la fel ca variabilele, referințele sunt imutabile în mod implicit. De aceea, trebuie să scrii &mut guess în loc de &guess pentru a-l face mutabil. (Capitolul 4 va explica referințele mai detaliat.)

Gestionarea potențialelor eșecuri cu Result

Încă lucrăm la această linie de cod. Acum discutăm despre a treia linie de text, dar reține că aceasta face încă parte dintr-o singură linie logică de cod. Partea următoare este această metodă:

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

Am fi putut scrie acest cod astfel:

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

Cu toate acestea, o linie lungă este dificil de citit, deci este cel mai bine să o împărțim. Este adesea înțelept să introduci o linie nouă și alte spații albe pentru a ajuta la divizarea liniilor lungi atunci când apelezi o metodă cu sintaxa .nume_metoda(). Acum să discutăm ce face această linie.

După cum am menționat mai devreme, read_line introduce ceea ce introduce utilizatorul în string-ul pe care îl transmitem, dar returnează și o valoare de tip Result. Result este o enumerare, adesea numită și enum, care este un tip care poate fi într-una din multiple stări posibile. Fiecare stare posibilă o numim variantă.

Capitolul 6 va acoperi enumerările în mai mult detaliu. Scopul acestor tipuri Result este de a codifica informațiile de gestionare a erorilor.

Variantele Result sunt Ok și Err. Varianta Ok indică faptul că operațiunea a fost reușită, iar în interiorul Ok se află valoarea generată cu succes. Varianta Err înseamnă că operațiunea a eșuat, iar Err conține informații despre cum sau de ce a eșuat operațiunea.

Valorile de tip Result, ca și valorile de orice alt tip, au metode definite asupra lor. O instanță a Result are o metodă expect pe care o poți apela. Dacă această instanță a Result este o valoare Err, expect va provoca căderea programului și afișarea mesajului pe care l-ai transmis ca argument către expect. Dacă metoda read_line întoarce o Err, ar fi probabil rezultatul unei erori provenite de la sistemul de operare de baza. Dacă această instanță a Result este o valoare Ok, expect va prelua valoarea de return pe care Ok o deține și îți va returna doar acea valoare pentru a o putea folosi. În acest caz, acea valoare este numărul de octeți în intrarea utilizatorului.

Dacă nu apelezi expect, programul se va compila, dar vei primi un avertisment:

$ 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

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

Rust avertizează că nu ai folosit valoarea Result returnată de read_line, indicând faptul că programul nu a gestionat o posibilă eroare.

Modul corect de a suprima avertismentul este de a scrie într-adevăr cod de gestionare a erorilor, dar în cazul nostru dorim doar să prăbușim acest program atunci când apare o problemă, așa că putem folosi expect. Vei învăța despre recuperarea din erori în Capitolul 9.

Afișarea valorilor cu substituții println!

Afară de acolada de închidere, nu ne-a mai rămas decât un singur rând de discutat din codul de până acum:

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

Acest rând afișează șirul de caractere care conține acum intrarea utilizatorului. Setul de acolade {} este un substituent: consideră {} ca fiind niște clești de crab care țin o valoare pe loc. La afișarea valorii unei variabile, numele variabilei poate intra în acolade. La afișarea rezultatului evaluării unei expresii, plasați acoladele goale în string-ul de format, apoi urmați string-ul de format cu o listă separată prin virgulă cu expresii care trebuie afișate în fiecare substituent de acolade goale, în aceeași ordine. Afișarea unei variabile și a rezultatului unei expresii într-un singur apel către println! ar arăta astfel:

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

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

Acest cod ar afișa x = 5 and y + 2 = 12.

Testarea primei părți

Să testăm prima parte a jocului de ghicit. Rulează-l folosind cargo run:

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

Până în acest punct, prima parte a jocului este gata: noi primim input de la tastatură și apoi îl afișăm.

Generarea unui număr secret

În continuare, trebuie să generăm un număr secret pe care utilizatorul va încerca să îl ghicească. Numărul secret ar trebui să fie diferit de fiecare dată pentru ca jocul să fie distractiv de jucat de mai multe ori. Vom folosi un număr aleatoriu între 1 și 100 astfel încât jocul să nu fie prea dificil. Rust nu include încă funcționalitatea numerelor aleatorii în biblioteca sa standard. Cu toate acestea, echipa Rust oferă un rand crate cu această funcționalitate.

Utilizarea unui crate pentru a obține mai multă funcționalitate

Este important să ținem minte că un crate este o colecție de fișiere sursă Rust. Proiectul nostru este un crate binar, adică un executabil. În contrast, crate-ul rand este un crate de bibliotecă, conținând cod destinat să fie utilizat în cadrul altor programe și care nu poate fi executat de sine stătător.

Capacitatea lui Cargo de a coordona crate-uri externe este aspectul în care Cargo se evidențiază cu adevărat. Pentru a putea scrie cod ce folosește rand, este necesar să facem o ajustare în fișierul Cargo.toml, incluzând crate-ul rand între dependențe. Deschide fișierul chiar acum și adaugă la partea de jos următoarea linie, dedesubtul secțiunii [dependencies] pe care Cargo a generat-o automat pentru tine. E vital să specifici rand exact cum e indicat aici, cu această versiune, deoarece în caz contrar exemplele de cod din acest tutorial pot să nu funcționeze normal:

Numele fișierului: Cargo.toml

[dependencies]
rand = "0.8.5"

În fișierul Cargo.toml, tot ce se află după un antet aparține acelei secțiuni care continuă până când o altă secțiune începe. În [dependencies] indicăm lui Cargo care crate-uri externe sunt necesare proiectului tău și ce versiuni ale acestor crate-uri trebuie utilizate. În acest caz, specificăm crate-ul rand cu specificatorul de versiune semantică 0.8.5. Cargo cunoaște Versionarea semantică (adesea numit SemVer), care e un standard pentru a scrie numerele de versiune. Specificantul 0.8.5 este de fapt o scurtătură pentru ^0.8.5, ceea ce înseamnă orice versiune cel puțin 0.8.5 dar mai mică de 0.9.0.

Cargo consideră aceste versiuni ca având API-uri publice compatibile cu versiunea 0.8.5, iar această specificare garantează că vei obține cea mai recentă versiune cu patch-uri compatibile care vor compila corect cu codul din acest capitol. Nu este garantat ca versiunile 0.9.0 sau mai mari să păstreze același API ca exemplele utilizate aici.

Acum, fără a modifica vreun cod, să construim proiectul, așa cum este ilustrat în Listarea 2-2.

$ cargo build
    Updating crates.io index
  Downloaded rand v0.8.5
  Downloaded libc v0.2.127
  Downloaded getrandom v0.2.7
  Downloaded cfg-if v1.0.0
  Downloaded ppv-lite86 v0.2.16
  Downloaded rand_chacha v0.3.1
  Downloaded rand_core v0.6.3
   Compiling libc v0.2.127
   Compiling getrandom v0.2.7
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.16
   Compiling rand_core v0.6.3
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s

Listarea 2-2: Afișajul rezultat după executarea cargo build în urma adăugării crate-ului rand ca dependență

Poți întâlni numere de versiuni diferite (dar toate vor fi compatibile cu codul, datorită SemVer!) și linii diferite (care vor varia în funcție de sistemul de operare), iar ordinea liniilor poate fi diferită.

Atunci când introducem o dependență externă, Cargo caută și descarcă versiunile cele mai recente ale tuturor elementelor necesare acelei dependențe din registru, o copie a datelor de pe Crates.io. Crates.io este platforma unde comunitatea Rust își publică proiectele Rust open source, disponibile pentru folosirea de către toți.

Cargo verifică secțiunea [dependencies] după ce actualizează registrul și descarcă crate-urile enumerate ce nu au fost încă descărcate. Deși am specificat doar rand ca dependență, Cargo a descărcat și alte crate-uri de care rand are nevoie pentru funcționarea sa. Odată ce crate-urile sunt descărcate, Rust le compilează, și apoi compilarea proiectului nostru are loc cu aceste dependențe incluse.

Dacă rulezi cargo build din nou imediat, fără a modifica ceva, nu vei obține niciun afișaj în afară de linia Finished. Cargo știe că a descărcat și compilat deja dependențele și că tu nu ai modificat nimic în fișierul Cargo.toml. De asemenea, Cargo înțelege că nici codul tău nu a fost schimbat, așadar nu recompilează nimic. Neavând ce să facă, se închide simplu.

Dacă ești în src/main.rs, faci o mică schimbare, salvezi și compilezi din nou, vei observa doar două linii de afișaj:

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

Aceste linii arată că Cargo actualizează build-ul doar cu micuța ta modificare la fișierul src/main.rs. Dependențele tale nu s-au schimbat, așa că Cargo știe că poate reutiliza ceea ce deja a descărcat și compilat pentru acestea.

Asigurarea compilărilor reproductibile cu fișierul Cargo.lock

Cargo are un mecanism care garantează că poți reconstrui același artefact de fiecare dată când tu sau altcineva compilați codul: Cargo va utiliza doar versiunile specificate de dependențe, până nu decizi altceva. De exemplu, presupunem că săptămâna viitoare va fi lansată versiunea 0.8.6 a crate-ului rand și că aceasta include o reparație critică de bug, dar totodată și o regresie care îți va afecta codul. Pentru a gestiona aceasta, Rust generează fișierul Cargo.lock prima oară când execuți cargo build, deci acum îl avem în directoriul guessing_game.

La prima compilare a proiectului, Cargo determină toate versiunile compatibile pentru dependențe și le înscrie în fișierul Cargo.lock. La compilările ulterioare, Cargo va recunoaște prezența fișierului Cargo.lock și va folosi versiunile înregistrate acolo, evitând astfel munca repetitivă de selecție a versiunilor. Astfel, construcția proiectului tău devine reproductibilă automat. În alte cuvinte, proiectul va rămâne la versiunea 0.8.5 până când alegi explicit să faci o actualizare, datorită existenței fișierului Cargo.lock. Fiind esențial pentru reproduceri consecvente, fișierul Cargo.lock este adesea inclus în controlul de versiune alături de restul codului proiectului tău.

Actualizarea unui crate pentru a obține o versiune nouă

Atunci când dorești să actualizezi un crate, Cargo pune la dispoziție comanda update, care va ignora fișierul Cargo.lock și va determina cele mai recente versiuni ce se potrivesc specificațiilor din Cargo.toml. Cargo va înregistra aceste versiuni în fișierul Cargo.lock. Implicit, Cargo caută versiuni care sunt mai mari decât 0.8.5 și mai mici de 0.9.0. Dacă crate-ul rand a introdus două noi versiuni, 0.8.6 și 0.9.0, ai vedea următorul rezultat dacă ai executa cargo update:

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

Cargo va ignora lansarea versiunii 0.9.0. De asemenea, ai remarca o modificare în fișierul tău Cargo.lock, care arată că acum folosești versiunea 0.8.6 a crate-ului rand. Pentru a utiliza versiunea rand 0.9.0 sau orice altă versiune din seria 0.9.x, trebuie să actualizezi fisierul Cargo.toml astfel:

[dependencies]
rand = "0.9.0"

Data următoare când rulezi cargo build, Cargo va actualiza lista de crate-uri disponibile și va reevalua cerința ta pentru rand în funcție de noua versiune pe care ai specificat-o.

Există multe alte lucruri de spus despre Cargo și ecosistemul său, pe care le vom discuta în Capitolul 14. Până acum, aceste informații sunt tot ce trebuie să știi. Cargo facilitează în mare măsură reutilizarea bibliotecilor, ceea ce permite programatorilor Rust să creeze proiecte mai compacte, compuse din diverse pachete.

Generarea unui număr aleatoriu

Să începem folosirea bibliotecii rand pentru a genera un număr de ghicit. Următorul pas este să actualizăm fișierul src/main.rs, așa cum se arată în Listarea 2-3.

Numele fișierului: src/main.rs

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

Listarea 2-3: Adăugarea de cod pentru a genera un număr aleatoriu

În primul rând, adăugăm linia use rand::Rng;. Trăsătura Rng definește metodele pe care le implementează generatorii de numere aleatorii și trebuie să fie în domeniul de vizibilitate pentru a folosi acele metode. Trăsăturile vor fi explicate în detaliu în Capitolul 10.

Următoarea parte implică adăugarea a două linii noi în cod. În prima linie apelăm funcția rand::thread_rng, care ne oferă generatorul de numere aleatorii specific firului de execuție curent și care este inițiat de sistemul de operare. Apoi utilizăm metoda gen_range de la acel generator de numere. Metoda gen_range, definită de trăsătura Rng adusă în context cu instrucțiunea use rand::Rng;, primește o expresie de diapazon și generează un număr aleatoriu în interiorul acelui diapazon. Expresia de diapazon pe care o utilizăm este start..=end, care este inclusivă pentru ambele limite, deci specificăm 1..=100 pentru a obține un număr între 1 și 100.

Notă: Nu vei cunoaște întotdeauna care trăsături trebuie utilizate și ce metode și funcții să apelezi de la un crate, prin urmare, fiecare crate vine echipat cu propria documentație și instrucțiuni pentru a te ghida în utilizarea sa. O funcționalitate practică a Cargo este că executarea comenzii cargo doc --open va genera documentația furnizată de toate dependențele tale local și o va deschide în navigatorul web. Dacă ai curiozitatea de a explora alte funcții ale crate-ului rand, de exemplu, execută cargo doc --open și selectează rand din bara laterală din partea stângă.

Cea de-a doua linie nouă afișează numărul secret, ceea ce este util pe durata dezvoltării programului pentru a-l putea testa, însă o vom șterge în versiunea finală. Nu se poate spune că este un joc prea incitant dacă programul dezvăluie soluția imediat ce este lansat.

Încearcă să rulezi programul de câteva ori:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s
     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 [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

Ar trebui să obții numere aleatorii diferite, iar toate ar trebui să fie numere între 1 și 100. Excelentă treabă!

Compararea ghicirii cu numărul secret

Acum că avem o intrare de la utilizator și un număr aleator, le putem compara. Acest pas este arătat în Listarea 2-4. Reține că acest cod nu se va compila încă, așa cum vom explica.

Numele fișierului: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

Listarea 2-4: Gestionarea posibilelor rezultate ale comparării a două numere

Mai întâi, adăugăm o altă declarație use, introducând în scopul nostru un tip numit std::cmp::Ordering din biblioteca standard. Tipul Ordering este o altă enumerare și are variantele Less, Greater și Equal. Acestea sunt cele trei rezultate posibile când compari două valori.

Apoi, adăugăm cinci linii noi la final care utilizează tipul Ordering. Metoda cmp compară două valori și poate fi apelată pe orice tip de valori comprabile. E primește o referință la ce se dorește de a fi comparat: aici se face compararea între guess și secret_number. Apoi returnează o variantă a enumerației Ordering pe care am adus-o în scop cu declarația use. Folosim o expresie match pentru a decide ce să facem în continuare bazat pe ce variantă a Ordering a fost returnată de apelul la cmp cu valorile din guess și secret_number.

O expresie match este compusă din brațe. Un braț constă dintr-un model (numit și pattern) pentru care se face potrivirea, și din codul care ar trebui să ruleze dacă valoarea dată lui match se potrivește cu modelul acelui braț. Rust ia valoarea dată lui match și o compară cu modelul fiecărui braț pe rând. Modelele și constructul match reprezintă caracteristici forte ale lui Rust: îți permit să exprimi o varietate de situații pe care codul tău le-ar putea întâlni și se asigură că le gestionezi pe toate. Aceste caracteristici vor fi acoperite în detaliu în Capitolul 6 și Capitolul 18, respectiv.

Acum să trecem printr-un exemplu cu expresia match pe care o folosim aici. Să presupunem că utilizatorul a ghicit numărul 50 și de data aceasta numărul secret generat aleator este 38.

Atunci când codul compară numărul 50 cu 38, metoda cmp va returna Ordering::Greater, deoarece 50 este mai mare decât 38. Expresia match primește valoarea Ordering::Greater și începe să verifice modelul pentru fiecare braț. Analizează primul tipar de braț, Ordering::Less, și vede că valoarea Ordering::Greater nu se potrivește cu Ordering::Less, deci ignoră codul din acel braț și trece la brațul următor. Modelul următorului braț este Ordering::Greater, care se potrivește cu Ordering::Greater! Codul asociat acestui braț va fi executat și va imrima pe ecran Too big!. Expresia match se încheie după prima potrivire reușită, deci nu se va uita la ultimul braț în acest scenariu.

Totuși, codul din Listarea 2-4 încă nu se va compila. Să încercăm:

$ 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:22:21
   |
22 |     match guess.cmp(&secret_number) {
   |                 --- ^^^^^^^^^^^^^^ expected struct `String`, found integer
   |                 |
   |                 arguments to this function are incorrect
   |
   = note: expected reference `&String`
              found reference `&{integer}`
note: associated function defined here
  --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/cmp.rs:783:8

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

Esența erorii indică existența unor tipuri incompatibile. Rust se bazează pe un sistem de tipuri puternic și tipizat static. În același timp, Rust suportă inferență de tipuri. Atunci când am scris let mut guess = String::new(), Rust a inferat că guess ar trebui să fie un String fără să fie necesar să specificăm tipul. Pe de altă parte, secret_number este de un tip numeric. Există mai multe tipuri numerice în Rust care pot avea valori între 1 și 100: i32, un număr pe 32 de biți; u32, un număr nesemnat pe 32 de biți; i64, un număr pe 64 de biți; printre altele. Dacă nu se indică altfel, Rust alege i32 în mod implicit, care este tipul pentru secret_number dacă nu adăugăm informații despre tip în altă parte care ar determina Rust să infereze un alt tip numeric. Eroarea apare pentru că Rust nu poate face comparație între un string și un tip numeric.

Pentru a o rezolva, intenționăm să convertim String-ul primit ca input într-un tip numeric real, astfel încât să putem face comparația numerică cu numărul secret. Acest lucru se realizează adăugând următoarea linie în corpul funcției main:

Numele fișierului: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

    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 este:

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

Creăm o variabilă numită guess. Dar așteaptă, nu există deja o variabilă cu numele guess în program? Da, dar, convenabil, Rust ne permite să umbrim precedentul guess cu unul nou. Umbrirea ne permite să reutilizăm numele variabilei guess în loc să fim obligați să creăm două variabile diferite, cum ar fi guess_str și guess, de exemplu. Vom detalia acest concept în Capitolul 3, dar pentru moment, să știi că această funcționalitate este adesea folosită când vrei să convertești o valoare dintr-un tip în altul.

Noua variabilă este asociată expresiei guess.trim().parse(). Partea guess din cadrul expresiei se referă la variabila originală guess care conținea input-ul ca un string. Metoda trim pe o instanță String va elimina orice spațiu alb (whitespace) de la început și sfârșitul string-ului, lucru necesar pentru a putea compara string-ul cu un u32, ce poate conține doar date numerice. Utilizatorul trebuie să apese enter pentru a completa read_line și așa să introducă ghicirea sa, adăugând prin asta un caracter de linie nouă la string. De exemplu, dacă utilizatorul scrie 5 și apasă enter, guess arată așa: 5\n. \n reprezintă „newline” (linie nouă). (Pe Windows, apăsarea enter aduce un carriage return și un newline, \r\n.) Metoda trim înlătură \n sau \r\n, lăsând doar 5.

Metoda parse de pe string-uri transformă un string într-un alt tip. În acest caz, o utilizăm pentru a converti un string într-un număr. Trebuie să specificăm în Rust tipul exact de număr pe care îl dorim, utilizând let guess: u32. Două puncte (:) care urmează după guess indică faptul că vom adnota tipul variabilei. Rust include diferite tipuri de numere; u32, pe care îl vedem aici, reprezintă un întreg pozitiv fără semn și de 32 de biți. Este o opțiune predilectă pentru reprezentarea unui număr mic și pozitiv. Despre alte tipuri de numere vei afla în Capitolul 3.

De asemenea, prin folosirea adnotării u32 în acest exemplu și prin comparația cu secret_number, Rust va înțelege că și secret_number trebuie să fie u32. Astfel, comparația se va face între două valori de același tip!

Metoda parse este aplicabilă doar caracterelor ce pot fi convertite în mod logic către numere și, prin urmare, este susceptibilă de erori. Dacă, spre exemplu, string-ul ar conţine A👍%, nu ar exista nicio modalitate de a-l converti într-un număr. Fiind posibil să eșueze, metoda parse returnează un tip Result, într-un mod similar cu metoda read_line (abordată anterior în „Tratarea eșecurilor potențiale cu Result”). Vom reacționa în fața acestui Result în același mod, utilizând din nou metoda expect. Dacă parse întoarce o variantă de Err a tipului Result, deoarece nu a putut transforma string-ul într-un număr, apelul expect va opri jocul și va tipări mesajul specificat de noi. În situația în care parse reușește să convertească string-ul într-un număr cu succes, va returna varianta Ok a Result, iar metoda expect va extrage numărul dorit din valoarea Ok.

Să rulăm acum programul:

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

Foarte bine! Deși au fost adăugate spații înainte de ghicire, programul a reușit totuși să-și dea seama că utilizatorul a ghicit numărul 76. Rulează programul de câteva ori pentru a verifica comportamentul diferit cu diferite tipuri de input: ghicește numărul corect, ghicește un număr care este prea mare sau ghicește un număr care este prea mic.

Acum avem majoritatea jocului funcțional, dar utilizatorul poate face doar o singură ghicire. Să schimbăm asta adăugând o buclă!

Permiterea multiplelor ghiciri cu bucle

Cuvântul cheie loop creează o buclă infinită. Vom adăuga o buclă pentru a oferi utilizatorilor mai multe încercări de a ghici numărul:

Numele fișierului: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

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

După cum se poate observa, am mutat tot de la promptul de introducere a ghicirii într-o buclă. Asigură-te că liniile din interiorul buclei sunt indentate cu patru spații suplimentare fiecare și rulează din nou programul. Acum programul va solicita o nouă ghicire la nesfârșit, ceea ce introduce efectiv o nouă problemă: pare că utilizatorul nu are posibilitatea să părăsească programul!

Utilizatorul poate întrerupe întotdeauna programul utilizând combinația de taste ctrl-c. Există însă și o altă cale de a se elibera de acest ciclu infinit, așa cum am menționat în discuția despre parse din secțiunea “Compararea ghicirii cu numărul secret”: dacă utilizatorul scrie ceva ce nu este un număr, atunci programul va da eroare și se va opri. Putem folosi acest comportament ca o metodă prin care utilizatorul poate opri programul, după cum urmează:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 1.50s
     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.
adio
thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Dacă introduci adio, jocul se va opri, însă vei observa că se va întâmpla același lucru dacă introduci orice alt input care nu e un număr. Aceasta este departe de a fi ideal; ne dorim ca jocul să se încheie și atunci când numărul ghicit este cel corect.

Terminarea jocului la o ghicire corectă

Să programăm jocul să se termine atunci când utilizatorul câștigă, prin adăugarea unei instrucțiuni break:

Numele fișierului: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

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

Introducerea liniei break imediat după You win! determină programul să părăsească bucla atunci când utilizatorul ghicește numărul secret în mod corect. Părăsirea buclei înseamnă de asemenea finalizarea programului, deoarece bucla reprezintă ultima secțiune a funcției main.

Procesarea intrărilor non-valide

Pentru a îmbunătăți comportamentul jocului, în loc de a opri programul când utilizatorul introduce ceva ce nu este un număr, putem configura jocul să ignore acest tip de input, permițând utilizatorului să continue să ghicească. Acest lucru poate fi realizat modificând linia în care valoarea guess este convertită din String în u32, așa cum este ilustrat în Listarea 2-5.

Numele fișierului: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

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

Listarea 2-5: Ignorarea unui input care nu este un număr și solicitarea unei noi încercări în locul oprii programului

Trecem de la o funcție expect la o expresie match pentru a gestiona erorile în locul oprii programului. Este important să ne amintim că parse returnează un tip Result și că Result este o enumerare cu variantele Ok și Err. Folosim o expresie match, la fel ca atunci când lucrăm cu Ordering rezultatul metodei cmp.

Când parse poate să convertească în mod eficient string-ul într-un număr, ne întoarce o valoare Ok care include numărul rezultat. Această valoare Ok se va potrivi cu modelul din primul caz al expresiei match, iar ca rezultat, vom primi numărul creat de parse și inclus în Ok. Numărul va fi pus exact unde trebuie în noua variabilă guess pe care o definim.

Dacă parse nu poate să convertească string-ul într-un număr, ne va da o valoare Err care deține detalii despre eroare. Valoarea Err nu se potrivește cu modelul Ok(num) din primul caz al match, dar se potrivește cu Err(_) din cel de-al doilea caz. Folosind _ ca wildcard, spunem că dorim să captăm orice fel de valoare Err, fără a ne preocupa de conținutul acesteia. Programul va rula codul corespunzător celui de-al doilea caz, adică continue, care comandă programului să treacă la următoarea iterație a buclei loop și să solicite o încercare nouă. Astfel, ignorăm orice posibilă eroare care ar putea apărea în timpul funcției parse.

Acum totul în program ar trebui să funcționeze conform așteptărilor. Să încercăm:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 4.45s
     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!

Minunat! Cu o mică ultimă ajustare, vom termina jocul de ghicit. Amintește-ți că programul încă afișează numărul secret. Acest lucru a funcționat bine pentru testare, dar strică jocul. Să ștergem println! care afișează numărul secret. Listarea 2-6 arată codul final.

Filename: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

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

Listarea 2-6: Codul complet al jocului de ghicire

La acest moment, ai reușit să construiești cu succes jocul de ghicire. Felicitări!

Sumar

Acest proiect a fost o modalitate practică de a face cunoștință cu multe concepte noi din Rust: let, match, funcții, utilizarea crate-urilor externe, și multe altele. În următoarele câteva capitole, vei învăța despre aceste concepte în mai multe detalii. Capitolul 3 acoperă funcționalități pe care majoritatea limbajelor de programare le au, cum ar fi variabile, tipuri de date și funcții, și arată cum să le folosești în Rust. Capitolul 4 explorează posesiunea (ownership), o caracteristică ce distinge Rust de alte limbaje. Capitolul 5 discută despre structuri și sintaxa metodelor, iar Capitolul 6 explică cum funcționează enumerările.

Concepte comune de programare

Acest capitol descrie concepte care apar în aproape fiecare limbaj de programare și cum funcționează ele în Rust. Multe limbaje de programare au foarte multe în comun la baza lor. Niciunul dintre conceptele prezentate în acest capitol nu sunt unice pentru Rust, dar le vom discuta în contextul Rust și vom explica convențiile legate de utilizarea acestor concepte.

În mod specific, vei învăța despre variabile, tipuri de bază, funcții, comentarii, și fluxul de control. Aceste fundamente vor fi în fiecare program Rust, iar învățarea lor devreme îți va oferi un nucleu solid de pornire.

Cuvinte cheie

Limbajul Rust are un set de cuvinte cheie care sunt rezervate pentru utilizarea de către limbajul în sine, la fel ca în alte limbaje. Reține că nu poți folosi aceste cuvinte ca nume de variabile sau funcții. Majoritatea cuvintelor cheie au semnificații speciale, iar tu le vei folosi pentru a realiza diverse sarcini în programele tale Rust; câteva nu au nicio funcționalitate actuală asociată cu ele, dar au fost rezervate pentru funcționalități care ar putea fi adăugate în Rust în viitor. Poți găsi lista cuvintelor cheie în Anexa A.

Variabile și mutabilitate

Așa cum am menționat în secțiunea „Păstrarea valorilor cu variabile”, în mod implicit, variabilele sunt imutabile. Acesta este unul dintre numeroasele stimulente pe care Rust ți le oferă pentru a scrie codul tău într-un mod care să profite de siguranța și concurența ușoară pe care Rust le oferă. Cu toate acestea, ai încă opțiunea de a-ți face variabilele mutabile. Să explorăm cum și de ce Rust încurajează preferința pentru imutabilitate și de ce uneori ai putea vrea să alegi variabilele mutabile.

Când o variabilă este imutabilă, odată ce o valoare este atribuită unui nume, nu poți schimba acea valoare. Pentru a ilustra acest lucru, generează un nou proiect numit variables în directoriul tău projects utilizând cargo new variables.

Apoi, în noul tău directoriu variables, deschide src/main.rs și înlocuiește codul său cu următorul cod, care încă nu se va compila:

Numele fișierului: src/main.rs

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

Salvează și rulează programul folosind cargo run. Ar trebui să primești un mesaj de eroare privind o eroare de imutabilitate, așa cum se arată în această ieșire:

$ 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`
  |         help: consider making this binding mutable: `mut x`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable

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

Acest exemplu arată cum compilatorul te ajută să găsești erorile din programele tale. Erorile de compilare pot fi frustrante, dar în realitate ele înseamnă doar că programul tău nu face încă în siguranță ceea ce vrei să facă; ele nu înseamnă că nu ești un bun programator! Rustaceanii cu experiență tot primesc erori de compilare.

Ai primit mesajul de eroare cannot assign twice to immutable variable `x` pentru că ai încercat să atribui o a doua valoare variabilei imutabile x.

Este important să primim erori la timpul compilării când încercăm să schimbăm o valoare care este desemnată ca imutabilă, deoarece această situație poate duce la bug-uri. Dacă o parte a codului nostru funcționează pe presupunerea că o valoare nu se va schimba niciodată și o altă parte a codului nostru schimbă acea valoare, este posibil ca prima parte a codului să nu facă ceea ce a fost proiectat să facă. Cauza acestui tip de bug poate fi dificil de urmărit ulterior, mai ales când a doua parte a codului schimbă valoarea doar uneori. Compilatorul Rust garantează că atunci când declari că o valoare nu se va schimba, ea cu adevărat nu se va schimba, astfel încât nu trebuie să urmărești asta singur. Astfel, codul tău este mai ușor de înțeles.

Dar mutabilitatea poate fi foarte utilă și poate face codul mai convenabil de scris. Deși variabilele sunt imutabile în mod implicit, le poți face mutabile adăugând mut în fața numelui variabilei, așa cum ai făcut în Capitolul 2. Adăugarea mut transmite și intenția cititorilor viitori ai codului, indicând că alte părți ale codului vor schimba această valoare a variabilei.

De exemplu, să schimbăm src/main.rs în următorul mod:

Numele fișierului: src/main.rs

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

Când rulăm acum programul, obținem asta:

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

Ni se permite să modificăm valoarea legată la x de la 5 la 6 când este utilizat mut. În cele din urmă, decizia de a utiliza sau nu mutabilitatea depinde de tine și de ceea ce crezi că este cel mai evident în acea situație particulară.

Constante

La fel ca variabilele imutabile, constantele sunt valori care sunt legate de un nume și nu li se permite să se schimbe, dar există câteva diferențe între constante și variabile.

În primul rând, nu ai voie să folosești mut cu constante. Constantele nu sunt doar imutabile în mod implicit - sunt întotdeauna imutabile. Declari constante folosind cuvântul cheie const, în loc de cuvântul cheie let, iar tipul valorii trebuie să fie adnotat. Vom acoperi tipurile și adnotările de tip în următoarea secțiune, „Tipuri de date”, așa că nu-ți face griji despre aceste detalii acum. Trebuie doar să știi că trebuie întotdeauna să adnotezi tipul.

Constantele pot fi declarate în orice domeniul de vizibilitatea, inclusiv în cel global, ceea ce le face utile pentru valorile de care multe părți ale codului au nevoie să știe.

Ultima diferență este că constantele pot fi setate numai la o expresie constantă, nu la rezultatul unei valori care ar putea fi calculate doar în timpul rulării.

Iată un exemplu de declarare a unei constante:

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

Numele constantei este THREE_HOURS_IN_SECONDS și valoarea sa este setată la rezultatul înmulțirii cu 60 (numărul de secunde într-un minut) cu 60 (numărul de minute într-o oră) cu 3 (numărul de ore pe care dorim să le numărăm în acest program). Convenția de denumire a Rust pentru constante este să folosească doar majuscule cu subliniere între cuvinte. Compilatorul este capabil să evalueze un set limitat de operațiuni la momentul compilării, ceea ce ne permite să alegem să scriem această valoare într-un mod mai ușor de înțeles și de verificat, decât să setăm această constantă la valoarea 10,800. Vezi secțiunea Rust Reference privind evaluarea constantă pentru mai multe informații despre ce operațiuni pot fi utilizate la declararea constantelor.

Constantele sunt valabile pentru întreaga durată a rulării unui program, în cadrul în care au fost declarate. Această proprietate face ca constantele să fie utile pentru valorile din domeniul aplicației tale despre care multe părți ale programului ar putea avea nevoie să știe, cum ar fi numărul maxim de puncte pe care orice participant al unui joc are voie să le câștige, sau viteza luminii.

Specificând valorile particulare folosite într-un program ca fiind constante este util în a transmite semnificația acelei valori către viitorii întreținători ai codului. De asemenea, este util să avem doar un singur loc în codul nostru unde ar trebui să modificăm dacă eventual valoarea codificată ar trebui să fie actualizată în viitor.

Umbrirea

Cum am văzut în tutorialul jocului de ghicit în capitolul 2, putem declara o nouă variabilă cu același nume ca o variabilă anterioară. Rustacenii spun că prima variabilă este umbrită de a doua, ceea ce înseamnă că a doua variabilă este cea pe care compilatorul o va vedea atunci când folosești numele variabilei. Practic, a doua variabilă eclipsează prima, preluând orice utilizări ale numelui variabilei până când este la rândul său umbrită sau până când se termină contextul. Putem umbri o variabilă folosind același nume de variabilă și repetând utilizarea cuvântului cheie let astfel:

Numele fișierului: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

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

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

Acest program leagă întâi x la o valoare de 5. Apoi creează o nouă variabilă x repetând let x =, luând valoarea originală și adăugând 1, astfel încât valoarea x este apoi 6. Apoi, într-un context intern creat cu acolade, a treia declarație let umbrește, de asemenea, x și creează o nouă variabilă, înmulțind valoarea anterioară cu 2, pentru a da x o valoare de 12. Când acest context se termină, umbrirea internă se termină și x revine la a fi 6. Când rulăm acest program, va afișa următoarele:

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

Umbrirea este diferită de marcarea unei variabile ca mut, deoarece vom obține o eroare la compilare dacă încercăm accidental să realocăm această variabilă fără a folosi cuvântul cheie let. Folosind let, putem efectua câteva transformări pe o valoare, dar avem variabila imutabilă după ce aceste transformări au fost finalizate.

Cea de-a doua diferență între mut și umbrire este că, deoarece creăm efectiv o nouă variabilă atunci când folosim din nou cuvântul cheie let, putem schimba tipul valorii, dar refolosim același nume. De exemplu, spunem că programul nostru cere unui utilizator să arate câte spații dorește între un text prin introducerea de caractere spațiu și apoi dorim să stocăm această intrare ca număr:

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

Prima variabilă spaces este de tip string și a doua variabilă spaces este de tip număr. Astfel, umbrirea ne scutește să găsim nume diferite, cum ar fi spaces_str și spaces_num; în schimb, putem reutiliza numele mai simplu spaces. Cu toate acestea, dacă încercăm să folosim mut pentru acest lucru, așa cum se arată aici, vom obține o eroare la timpul de compilare:

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

Eroarea spune că nu avem voie să modificăm tipul unei variabile:

$ 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` due to previous error

Acum că am explorat cum funcționează variabilele, să examinăm mai multe tipuri de date pe care le pot avea.

Tipuri de date

Fiecare valoare în Rust este de un anumit tip de date, care indică Rust ce fel de date sunt specificate pentru a ști cum să lucreze cu acele date. Vom analiza două subansamble de tipuri de date: scalar și compus.

Amintiți-vă că Rust este un limbaj cu tipizare statică, ceea ce înseamnă că trebuie să cunoaște tipurile tuturor variabilelor la momentul compilării. În general, compilatorul poate infera ce tip dorim să folosim în funcție de valoare și cum o utilizăm. În cazurile când sunt posibile mai multe tipuri, cum ar fi atunci când am convertit un String într-un tip numeric folosind parse în secțiunea „Comparând guess-ul cu numărul secret” din Capitolul 2, trebuie să adăugăm o adnotare de tip, astfel:

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Nu este un număr!");
}

Dacă nu adăugăm adnotarea de tip : u32 arătată în codul precedent, Rust va afișa următoarea eroare, ceea ce înseamnă că compilatorul are nevoie de mai multe informații de la noi pentru a ști ce tip dorim să folosim:

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0282]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^
  |
help: consider giving `guess` an explicit type
  |
2 |     let guess: _ = "42".parse().expect("Not a number!");
  |              +++

For more information about this error, try `rustc --explain E0282`.
error: could not compile `no_type_annotations` due to previous error

Vei vedea adnotări de tip diferite pentru alte tipuri de date.

Tipuri scalare

Un tip scalar reprezintă o singură valoare. Rust are patru tipuri scalare principale: numere întregi, numere în virgulă mobilă, Booleani și caractere. S-ar putea ca acestea să ți se pară familiare din alte limbaje de programare. Să trecem la modul în care funcționează tipurile scalabile în Rust.

Tipuri de întregi

Un întreg este un număr fără componentă fracționară. Am folosit un tip de întreg în Capitolul 2, tipul u32. Această declarație de tip indică faptul că valoarea cu care este asociată ar trebui să fie un întreg fără semn (tipurile de întregi cu semn încep cu i în loc de u) care ocupă 32 de biți de spațiu. Tabelul 3-1 arată tipurile de întregi integrate în Rust. Putem folosi fiecare dintre aceste variante pentru a declara tipul unei valori întregi.

Tabelul 3-1: Tipuri de întregi în Rust

Fiecare variantă poate fi fie cu semn, fie fără semn, și are o dimensiune explicită. Cu semn și fără semn se referă la faptul dacă este posibil ca numărul să fie negativ - cu alte cuvinte, dacă numărul are nevoie să aibă un semn asociat (signed) sau dacă va fi mereu pozitiv și deci poate fi reprezentat fără un semn (unsigned). Este similar cu scrierea numerelor pe hârtie: când semnul contează, un număr este prezentat cu un semn plus sau un semn minus; totuși, când este sigur că numărul este pozitiv, acesta este prezentat fără semn. Numerele cu semn sunt stocate folosind reprezentarea de complement față de doi .

Fiecare variantă cu semn poate stoca numere de la -(2^{n - 1}) la 2^{n - 1} - 1 inclusiv, unde n este numărul de biți pe care îl folosește acea variantă. Așadar un i8 poate stoca numere de la -(2⁷) la 2⁷ - 1, care este egal cu -128 până la 127. Variantele fără semn pot stoca numere de la 0 la 2ⁿ - 1, așadar un u8 poate stoca numere de la 0 la 2⁸ - 1, care este egal cu 0 până la 255.

În plus, tipurile isize si usize depind de arhitectura computerului pe care rulează programul, care este notată în tabelul de mai sus ca „arhitectura sistemului”: 64 de biți dacă te afli pe o arhitectură de 64-biți și 32 de biți dacă te afli pe o arhitectură de 32-biți.

Poți scrie literali întregi în oricare dintre formele prezentate în Tabelul 3-2. Observă că literali numerici care pot fi de mai multe tipuri numerice permit un sufix de tip, cum ar fi 57u8, pentru a desemna tipul. Literalii numerici pot de asemenea folosi _ ca separator vizual pentru a face numărul mai ușor de citit, precum 1_000, care va avea aceeași valoare ca și cum ai fi specificat 1000.

Tabelul 3-2: Literali întregi în Rust

Deci, cum să știi ce tip de întreg să folosești? Dacă nu ești sigur, valorile setate inițial de Rust sunt în general un punct bun de plecare: tipurile întregi au implicit setat i32. Principala situație în care ai folosi isize sau usize este atunci când indexezi o colecție de elemente.

Depășirea întregilor

Să presupunem că ai o variabilă de tip u8 care poate stoca valori între 0 și 255. Dacă încerci să schimbi valoarea variabilei în afara acestui interval, cum ar fi 256, va apărea o depășire a întregilor (integer overflow), care poate produce unul dintre două comportamente. Atunci când compilezi în modul de depanare, Rust include verificări pentru depășirea întregilor care cauzează panica programului la runtime dacă acest comportament apare. Rust utilizează termenul de panică când un program se închide cu o eroare; vom discuta despre panici în profunzime în secțiunea „Erorile irecuperabile cu panic!” în Capitolul 9.

Când compilezi în modul de release cu opțiunea --release, Rust nu include verificări pentru depășirea întregilor care cauzează panici. În schimb, dacă apare o depășire, Rust efectuează împachetarea complementul lui doi. Pe scurt, valorile mai mari decât valoarea maximă pe care o poate deține tipul „este împachetat” la minimul valorilor pe care tipul le poate deţine. În cazul unui u8, valoarea 256 devine 0, valoarea 257 devine 1 și așa mai departe. Programul nu va genera panică, dar variabila va avea o valoare care probabil nu este ceea ce te așteptai să aibă. Să te bazezi pe comportamentul de împachetare a întregilor depășiți este considerat greșit.

Pentru a gestiona în mod explicit posibilitatea de depășire, poți folosi aceste familii de metode oferite de biblioteca standard pentru tipurile numerice primitive:

• Împachetează toate operațiunile cu metodele wrapping_*, cum ar fi wrapping_add.
• Întoarce valoarea None dacă există depășire cu metodele checked_*.
• Întoarce valoarea și un boolean care indică dacă a existat depășire cu metodele overflowing_*.
• Saturează la valorile minime sau maxime ale valorii cu metodele saturating_*.

Tipurile cu virgulă mobilă

Rust are, de asemenea, două tipuri primitive pentru numerele în virgulă mobilă, care sunt numerele cu puncte zecimale. Tipurile Rust cu virgulă mobilă sunt f32 și f64, care au 32 de biți și 64 de biți în dimensiune, respectiv. Tipul implicit este f64 deoarece pe procesoarele moderne este aproximativ la fel de rapid ca f32, dar este capabil de mai multă precizie. Toate tipurile cu virgulă mobilă sunt semnate.

Iată un exemplu care arată numerele cu virgulă mobilă în acțiune:

Numele fișierului: src/main.rs

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

    let y: f32 = 3.0; // f32
}

Numerele cu virgulă mobilă sunt reprezentate conform standardului IEEE-754. Tipul f32 este un număr cu precizie simplă, iar f64 are precizie dublă.

Operațiuni numerice

Rust suportă operațiunile matematice de bază pe care le-ai aștepta pentru toate tipurile de numere: adunare, scădere, înmulțire, împărțire și rest. Împărțirea întreagă trunchiază spre zero la cel mai apropiat număr întreg. Următorul cod arată cum ai folosi fiecare operațiune numerică într-o declarație let:

Numele fișierului: src/main.rs

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

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

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

    // remainder
    let remainder = 43 % 5;
}

Fiecare expresie în aceste declarații folosește un operator matematic și evaluează la o singură valoare, care este apoi legată la o variabilă. Anexa B conține o listă cu toți operatorii pe care Rust îi pune la dispoziție.

Tipul Boolean

Ca în majoritatea celorlalte limbaje de programare, un tip Boolean în Rust are două posibile valori: true și false. Booleanii au dimensiunea de un octet. Tipul Boolean în Rust este specificat folosind bool. De exemplu:

Numele fișierului: src/main.rs

fn main() {
    let t = true;

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

Principalul mod de a folosi valorile Boolean este prin condiționale, cum ar fi o expresie if. Vom discuta cum funcționează expresiile if în Rust în secțiunea „Fluxul de control”.

Tipul caracter

Tipul char al lui Rust este cel mai primitiv tip alfabetic al limbajului. Aici avem câteva exemple de declarare a valorilor char:

Numele fișierului: src/main.rs

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

Observați că specificăm constantele de tip char cu ghilimele simple, spre deosebire de sirurile de caractere, care utilizează ghilimele duble. Tipul char al lui Rust este de patru octeți și reprezintă o valoare scalară Unicode, ceea ce înseamnă că poate reprezenta mult mai mult decât doar ASCII. Litere accentuate; caractere chinezești, japoneze și coreene; emoji și spații de lățime zero sunt toate valori char valide în Rust. Valorile scalare Unicode variază de la U+0000 la U+D7FF și U+E000 la U+10FFFF inclusiv. Totuși, un „caracter” nu este chiar un concept în Unicode, așa că intuiția ta umană pentru ceea ce este un „caracter” s-ar putea să nu se potrivească cu ceea ce este un char în Rust. Vom discuta acest subiect în detaliu în „Stocarea textului codificat UTF-8 cu string-uri” în Capitolul 8.

Tipuri compuse

Tipurile compuse pot grupa mai multe valori într-un singur tip. Rust are două tipuri compuse primitive: tuple și array-uri.

Tipul tuplă

O tuplă este o modalitate generală de a grupa împreună un număr de valori cu o varietate de tipuri într-un singur tip compus. Tuplele au o lungime fixă: odată declarate, nu pot crește sau scădea în dimensiune.

Creăm o tuplă scriind o listă de valori separate prin virgulă între paranteze. Fiecare poziție din tuplă are un tip, și tipurile diferitelor valori din tuplă nu trebuie să fie aceleași. Am adăugat în acest exemplu opțional adnotări de tip:

Numele fișierului: src/main.rs

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

Variabila tup se leagă de întreaga tuplă pentru că o tuplă este considerată un singur element compus. Pentru a obține valorile individuale dintr-o tuplă, putem folosi potrivirea de modele pentru a destrucura o valoare a tuplei, așa cum este arătat aici:

Numele fișierului: src/main.rs

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

    let (x, y, z) = tup;

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

Acest program creează mai întâi o tuplă și o leagă la variabila tup. Apoi folosește un model cu let pentru a lua tup și a o transforma în trei variabile separate, x, y, și z. Acest lucru este numit destructurare pentru că descompune singura tuplă în trei părți. În final, programul afișează valoarea lui y, care este 6.4.

Putem accesa direct un element al tuplei folosind un punct (.) urmat de indexul valorii pe care dorim să o accesăm. De exemplu:

Numele fișierului: 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;
}

Acest program creează tupla x și apoi accesează fiecare element al tuplei folosind indicii lor respectivi. La fel ca în majoritatea limbajelor de programare, primul index într-o tuplă este 0.

Tupla fără nicio valoare are un nume special, unit. Această valoare și tipul său corespunzător sunt ambele scrise () și reprezintă o valoare goală sau un tip de returnare gol. Expresiile returnează implicit valoarea unit dacă nu returnează nicio altă valoare.

Tipul array

Un alt mod de a avea o colecție de valori multiple este cu un array. Spre deosebire de o tuplă, fiecare element al unui array trebuie să aibă același tip. Spre deosebire de array-urile din alte limbaje, array-urile din Rust au o lungime fixă.

Scriem valorile într-un array ca o listă separată prin virgule în interiorul parantezelor pătrate:

Numele fișierului: src/main.rs

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

Array-urile sunt utile când vrem ca datele să fie alocate pe stivă, nu pe heap (vom discuta mai mult despre stivă și heap în Capitolul 4) sau când dorim să ne asigurăm că avem întotdeauna un număr fix de elemente. Un array nu este la fel de flexibil precum tipul vector, totuși. Un vector este un tip de colecție similar oferit de biblioteca standard dar care are voie să crească sau să scadă în dimensiune. Dacă nu ești sigur dacă să folosești un array sau un vector, atunci probabil că ar trebui să folosești un vector. Capitolul 8 discută vectorii în mai multe detalii.

Totuși, array-urile sunt mai utile când știi că numărul de elemente nu va avea nevoie să se schimbe. De exemplu, dacă ai folosi numele lunilor într-un program, ai folosi probabil un array în loc de un vector, deoarece știi că acesta va conține întotdeauna 12 elemente:

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

Scrii tipul unui array folosind paranteze pătrate cu tipul fiecărui element, un punct și virgulă, și apoi numărul de elemente din array, așa:

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

Aici, i32 este tipul fiecărui element. După punctul și virgula, numărul 5 indică faptul că array-ul conține cinci elemente.

Poți de asemenea inițializa un array pentru a conține aceeași valoare pentru fiecare element, specificând valoarea inițială, urmată de un punct și virgulă, și apoi lungimea array-ului în paranteze pătrate, așa cum este afișat aici:

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

Array-ul numit a va conține 5 elemente care vor fi inițializate toate cu valoarea 3. Acest lucru este la fel ca scrierea let a = [3, 3, 3, 3, 3];, dar într-un mod mai concis.

Accesarea elementelor unui array

Un array este un singur segment de memorie de o dimensiune cunoscută, fixă, care poate fi alocat pe stiva. Poți accesa elementele unui array folosind indexarea, în acest fel:

Numele fișierului: src/main.rs

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

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

În acest exemplu, variabila numită first va primi valoarea 1 pentru că aceasta este valoarea la indexul [0] în array. Variabila numită second va primi valoarea 2 de la indexul [1] în array.

Acces invalid la un element al unui array

Să vedem ce se întâmplă dacă începi să accesezi un element al unui array care este după sfârșitul array-ului. Să zicem că rulezi acest cod, asemănător cu jocul de ghicit din Capitolul 2, pentru a obține un index de array de la utilizator:

Numele fișierului: 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}");
}

Cod se compilează cu succes. Dacă rulezi acest cod folosind cargo run și introduci 0, 1, 2, 3, sau 4, programul va afișa valoarea corespunzătoare acelui index în array. Dacă introduci un număr după sfârșitul array-ului, cum ar fi 10, vei vedea o ieșire de acest gen:

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

Programul a rezultat într-o eroare de runtime în momentul utilizării unei valori invalide în operația de indexare. Programul se închide cu un mesaj de eroare și nu execută instrucțiunea finală println!. Când încerci să accesezi un element folosind indexarea, Rust va verifica dacă indexul specificat de tine este mai mic decât lungimea array-ului. Dacă indexul este mai mare sau egal cu lungimea, Rust va stopa cu panică. Verificarea dată trebuie să se întâmple la runtime, în special în așa caz, pentru că compilatorul nu poate ști cu siguranță ce valoare va introduce un utilizator când va rula codul mai târziu.

Acesta este un exemplu al principiilor de siguranță ale memoriei din Rust în acțiune. În multe limbaje de nivel scăzut, verificare de acces în array nu se face, și, când furnizezi un index incorect, poate fi accesată memorie invalidă. Rust te protejează împotriva acestui fel de erori prin ieșirea imediată în loc de a permitere accesul la memorie și continuare. Capitolul 9 discută mai multe despre gestionarea erorilor în Rust și cum poți să scrii un cod lizibil și sigur, care nu face niciun fel de panică nici nu permite acces la memorie invalidă.

Funcții

Funcțiile sunt omniprezente în codul Rust. Ai văzut deja una dintre cele mai importante funcții din limbaj: funcția main, care este punctul de intrare în multe programe. Ai văzut deja și cuvântul cheie fn, care îți permite să declari funcții noi.

Codul Rust folosește snake case ca stil convențional pentru numele funcțiilor și variabilelor, în care toate literele sunt minuscule și cuvintele sunt separate de caracterele de underscore. Iată un program care conține o definiție exemplară a unei funcții:

Numele fișierului: src/main.rs

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

    another_function();
}

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

Definim o funcție în Rust prin introducerea fn urmată de un nume de funcție și un set de paranteze. Parantezele acolade indică compilatorului unde începe și se termină corpul funcției.

Putem apela orice funcție pe care am definit-o introducând numele său urmat de un set de paranteze. Deoarece another_function este definită în program, ea poate fi apelată din interiorul funcției main. Observă că am definit another_function după funcția main în codul sursă; am fi putut să o definim și înainte. Rust nu îi pasă unde definim funcțiile noastre, doar că sunt definite într-un loc vizibil pentru codul apelant.

Să începem un nou proiect binar denumit functions pentru a continua explorarea funcțiilore. Pune exemplul another_function în src/main.rs și rulează-l. Ar trebui să vezi următoarea ieșire:

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

Liniile se execută în ordinea în care apar în funcția main. Mai întâi mesajul „Salut, lume!” este tipărit, apoi another_function este apelată și mesajul său este tipărit.

Parametri

Funcțiile pot fi definite cu parametri, aceștia fiind variabile speciale care fac parte din semnătura unei funcții. Când o funcție are parametri ea poate fi apelată cu valori concrete pentru acești parametri. Tehnic, aceste valori concrete se numesc argumente, dar în conversațiile de zi cu zi, oamenii tind să folosească termenii parametru și argument în mod interschimbabil atât pentru fiecare variabilă în definiția unei funcții, cât și pentru valorile concrete transmise când o funcție este apelată.

În această versiune a lui another_function, noi adăugăm un parametru:

Numele fișierului: src/main.rs

fn main() {
    another_function(5);
}

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

Încearcă să rulezi acest program; ar trebui să primești următoarea ieșire:

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

Declarația another_function are un parametru numit x. Tipul lui x este specificat ca fiind i32. Când transmitem 5 la another_function, macro println! plasează 5 acolo unde perechea de acolade cu x era în șirul de caractere format.

În semnăturile funcțiilor, trebuie să declari tipul fiecărui parametru. Acest lucru este o decizie deliberată în designul Rust: cererea de adnotații de tip în definițiile funcțiilor înseamnă că compilatorul aproape niciodată nu are nevoie de ele în alte părți din cod pentru a afla ce tip ai vrut să spui. De asemenea, compilatorul este capabil să ofere mesaje de eroare mult mai utile dacă știe ce tipuri așteaptă funcția.

Când definești mai mulți parametri, separă declarațiile de parametri cu virgule, în acest fel:

Numele fișierului: src/main.rs

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

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

Acest exemplu creează o funcție numită print_labeled_measurement cu doi parametri. Primul parametru se numește value și este i32. Al doilea se numește unit_label și este de tip char. Funcția apoi afișează text care conține atât value cât și unit_label.

Să încercăm să rulăm acest cod: înlocuiește programul curent din fișierul src/main.rs al proiectului tău functions cu exemplul de mai sus și rulează-l folosind cargo run:

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

Deoarece am apelat funcția cu 5 ca valoare pentru value și 'h' ca valoare pentru unit_label, ieșirea programului conține anume aceste valori.

Instrucțiuni și expresii

Corpurile funcțiilor sunt compuse dintr-o serie de instrucțiuni, care se pot încheia opțional cu o expresie. Până acum, funcțiile pe care le-am discutat nu au inclus o expresie finală, însă ai observat expresii utilizate ca parte a instrucțiunilor. Spre deosebire de multe alte limbaje de programare, Rust este un limbaj bazat pe expresii - o distincție importantă de înțeles. În continuare, să analizăm ce reprezintă instrucțiunile și expresiile și cum această diferențiere influențează structura corpurilor funcțiilor.

• Instrucțiunile sunt directive care realizează o anumită acțiune și nu returnează o valoare.
• Expresiile evaluează o valoare rezultantă. Să vedem câteva exemple.

De fapt, am folosit deja instrucțiuni și expresii. Crearea unei variabile și atribuirea unei valori cu un cuvânt cheie let este o instrucțiune. În listarea 3-1, let y = 6; este o instrucțiune.

Numele fișierului: src/main.rs

fn main() {
    let y = 6;
}

Listarea 3-1: O declarație a funcției main conținând o instrucțiune

Definițiile de funcții sunt, de asemenea, instrucțiuni; întregul exemplu precedent este o instrucțiune în sine.

Instrucțiunile nu returnează valori. Prin urmare, nu poți atribui o instrucțiune let unei alte variabile, așa cum încearcă să facă următorul cod; vei obține o eroare:

Numele fișierului: src/main.rs

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

Când rulezi acest program, eroarea pe care o obții arată așa:

$ 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);
  |              ^^^

error: expected expression, found statement (`let`)
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^^^^^^^
  |
  = note: variable declaration using `let` is a statement

error[E0658]: `let` expressions in this position are unstable
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^^^^^^^
  |
  = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for more information

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

For more information about this error, try `rustc --explain E0658`.
warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` due to 3 previous errors; 1 warning emitted

Instrucțiunea let y = 6 nu returnează o valoare, deci nu există nimic de atribuit lui x. Acest lucru este diferit față de ceea ce se întâmplă în alte limbaje, cum ar fi C și Ruby, unde atribuirea returnează valoarea atribuirii. În acele limbaje, poți scrie x = y = 6 și atât x, cât și y vor avea valoarea 6; însă nu în cazul lui Rust.

Expresiile evaluează o valoare și alcătuiesc majoritatea celorlalte coduri pe care le vei scrie în Rust. Consideră o operație matematică, cum ar fi 5 + 6, care este o expresie care evaluează la valoarea 11. Expresiile pot face parte din instrucțiuni: în Listarea 3-1, 6 în instrucțiunea let y = 6; este o expresie care evaluează valoarea 6. Apelarea unei funcții este o expresie. Apelarea unui macro este o expresie. Și un nou bloc de cod creat cu acolade este o expresie, spre exemplu:

Numele fișierului: src/main.rs

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

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

Expresia:

{
    let x = 3;
    x + 1
}

este un bloc care, în acest caz, evaluează la 4. În continuare această valoare este atribuită lui y ca parte a instrucțiunii let. Reține că linia x + 1 nu are un punct și virgulă la sfârșit, spre deosebire de cele mai multe linii pe care le-ai văzut până acum. Cauza e că expresiile nu includ semicoalone la sfârșit. Dacă adaugi un punct și virgulă la sfârșitul unei expresii, o transformi într-o instrucțiune, și ea nu va mai returna o valoare. Ține acest lucru în minte pe măsură ce vom explora în continuare valorile de retur a funcțiilor și expresiile.

Funcții cu valori de retur

Funcțiile pot întoarce valori codului care le apelează. Noi nu dăm un nume valorilor de retur, dar trebuie să le declarăm tipul după o săgeată (->). În Rust, valoarea de retur a funcției este sinonimă cu valoarea ultimei expresii din blocul corpului acelei funcții. Poți returna mai devreme dintr-o funcție folosind cuvântul cheie return și specificând o valoare, dar majoritatea funcțiilor returnează ultima expresie în mod implicit. Iată un exemplu de funcție care returnează o valoare:

Numele fișierului: src/main.rs

fn five() -> i32 {
    5
}

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

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

Nu sunt apeluri de funcții, macrouri sau chiar declarații let în funcția five - doar numărul 5 în sine. Aceasta este o funcție perfect valabilă în Rust. Observă că tipul de retur al funcției este specificat și el, ca -> i32. Încearcă să rulezi acest cod; rezultatul ar trebui să arate așa:

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

Numărul 5 în five este valoarea de retur a funcției, motiv pentru care tipul de retur este i32. Să examinăm acest lucru mai detaliat. Sunt două aspecte importante: În primul rând, linia let x = five(); arată că folosim valoarea de retur a unei funcții pentru a inițializa o variabilă. Deoarece funcția five returnează un 5, această linie ar fi echivalentă cu următoarea:

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

În al doilea rând, funcția five nu are parametri și definește tipul valorii de retur, dar corpul funcției este un singur 5, fără punct și virgulă, pentru că este anume expresia a cărei valoare vrem să o returnăm.

Să vedem un alt exemplu:

Numele fișierului: src/main.rs

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

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

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

Rularea acestui cod va afișa Valoarea lui x este: 6. Dar dacă punem un punct și virgulă la finalul liniei care conține x + 1, schimbând-o dintr-o expresie într-o declarație, vom obține o eroare:

Numele fișierului: src/main.rs

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

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

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

Compilarea acestui cod produce o eroare, astfel:

$ 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` due to previous error

Mesajul principal de eroare, mismatched types, relevă problema de bază cu acest cod. Definiția funcției plus_one spune că va returna un i32, dar declarațiile nu evaluează la o valoare, ceea ce este exprimat prin (), tipul unit. Prin urmare, nu se returnează nimic, ceea ce contrazice definiția funcției și duce la o eroare. În această ieșire Rust chiar oferă un mesaj care ar putea ajuta la corectarea problemei: sugerează eliminarea punctului și virgulei, care într-adevăr ar remedia eroarea.

Comentarii

Toți programatorii se străduiesc să facă codul lor ușor de înțeles, dar uneori este necesară o explicație suplimentară. În aceste cazuri, programatorii lasă comentarii în codul lor sursă pe care compilatorul îl va ignora, dar persoanele care citesc codul sursă le-ar considera utile.

Acesta este un comentariu simplu:

#![allow(unused)]
fn main() {
// salutare, lume
}

În Rust, stilul idiomatic de a scrie comentarii începe cu două liniuțe, și comentariul continuă până la sfârșitul liniei. Pentru comentarii care se extind mai mult decât o linie, va trebui să includeți // pe fiecare linie, așa:

#![allow(unused)]
fn main() {
// Deci facem ceva complex aici, suficient de lung încât avem nevoie
// de mai multe linii de comentarii pentru a face asta! Uff! Sperăm că acest comentariu va 
// clarifica ce se întâmplă.
}

Comentariile pot fi, de asemenea, plasate la sfârșitul liniilor care conțin cod:

Numele fișierului: src/main.rs

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

Dar le vei vedea mai des utilizate în acest format, cu comentariul pe o linie separată, deasupra codului pe care îl comentează:

Numele fișierului: src/main.rs

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

Rust dispune și de un alt tip de comentariu, comentariile de documentare, despre care vom discuta în secțiunea „Publicarea unui crate la crates.io” a Capitolului 14.

Controlul fluxului

Abilitatea de a rula unele coduri în funcție dacă o condiție este true și de a rula un cod în mod repetat dacă o condiție este true sunt blocuri de bază în majoritatea limbajelor de programare. Cele mai comune constructe care îți permit să controlezi fluxul de execuție al codului Rust sunt expresiile if și buclele.

Expresiile if

O expresie if îți permite să amifici codul în funcție de condiții. Tu furnizezi o condiție și apoi afirmi: „Dacă această condiție este îndeplinită, rulează acest bloc de cod. Dacă condiția nu este îndeplinită, nu rula acest bloc de cod”.

Creează un proiect nou numit branches în directoriul tău projects pentru a explora expresia if. În fișierul src/main.rs, introdu următoarea linie:

Numele fișierului: src/main.rs

fn main() {
    let number = 3;

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

Toate expresiile if încep cu cuvântul cheie if, urmate de o condiție. În acest caz, condiția verifică dacă variabila number are o valoare mai mică de 5. Plasăm blocul de cod care urmează să se execute dacă condiția este true imediat după condiție între parantezele acolade. Blocurile de cod asociate cu condițiile din expresiile if sunt uneori numite arms (ramuri), la fel ca ramurile din expresiile match despre care am discutat în [secțiunea „Compararea supoziției cu numărul secret”][comparison-the supposition-the secret-number] a capitolului 2.

Opțional, putem include și o expresie else, pe care am ales să o facem aici, pentru a oferi programului un bloc alternativ de cod care să se execute în cazul în care condiția evaluatează la false. Dacă nu oferi o expresie else și condiția este false, programul va omite blocul if și va trece la următoarea parte de cod.

Încearcă să rulezi acest cod; ar trebui să vezi următoarea ieșire:

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

Să încercăm să schimbăm valoarea lui number într-o valoare care face ca condiția să fie false pentru a vedea ce se întâmplă:

fn main() {
    let number = 7;

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

Rulează din nou programul și uită-te la ieșire:

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

Este de asemenea important de menționat că în acest cod condiția trebuie să fie un bool. Dacă condiția nu este un bool, vom obține o eroare. De exemplu, încearcă să rulezi următorul cod:

Numele fișierului: src/main.rs

fn main() {
    let number = 3;

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

De această dată, condiția if evaluează valoarea 3 și Rust aruncă o eroare:

$ 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` due to previous error

Eroarea indică faptul că Rust se aștepta la un bool, dar a primit un integer. Spre deosebire de limbajele precum Ruby și JavaScript, Rust nu va încerca să convertească automat tipurile non-Boolean într-un Boolean. Trebuie să fii explicit și să furnizezi întotdeauna if cu un Boolean ca și condiție. Dacă vrem ca blocul de cod if să ruleze doar atunci când un număr nu este egal cu 0, de exemplu, putem schimba expresia if astfel:

Numele fișierului: src/main.rs

fn main() {
    let number = 3;

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

Rulând acest cod se va afișa numărul a fost altceva decât zero.

Tratarea mai multor condiții cu else if

Poți utiliza mai multe condiții prin combinarea if și else într-o expresie else if. De exemplu:

Numele fișierului: src/main.rs

fn main() {
    let number = 6;

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

Acest program are patru căi posibile pe care le poate urma. După ce îl rulezi, ar trebui să vezi următoarea ieșire:

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

Când acest program este executat, el verifică fiecare expresie if pe rând și execută primul bloc pentru care condiția se evaluează la true. Reține că, deși 6 este divizibil cu 2, nu vedem ieșirea numărul este divizibil cu 2, nici nu vedem textul numărul nu este divizibil cu 4, 3 sau 2 din blocul else. Asta pentru că Rust execută doar blocul pentru prima condiție true, iar odată ce o găsește, nu mai verifică restul.

Folosirea prea multor expresii else if poate încărca codul tău, așa că dacă ai mai mult de una, s-ar putea să vrei să refactorizezi codul. Capitolul 6 descrie o structură avansată de instrucțiuni condiționale în Rust numită match pentru aceste cazuri.

Folosirea if într-o instrucțiune let

Deoarece if este o expresie, o putem folosi în partea dreaptă a unei instrucțiuni let pentru a atribui rezultatul unei variabile, așa cum se vede în Listarea 3-2.

Numele fișierului: src/main.rs

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

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

Listarea 3-2: Atribuirea rezultatului unei expresii if unei variabile

Variabila number va fi legată de o valoare în funcție de rezultatul expresiei if. Rulează acest cod pentru a vedea ce se întâmplă:

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

Amintește-ți că blocurile de cod se evaluează până la ultima expresie din ele, iar numerele în sine sunt, de asemenea, expresii. În acest caz, valoarea întregii expresii if depinde de ce bloc de cod se execută. Acest lucru înseamnă că valorile care au potențialul de a fi rezultate din fiecare ramură a if trebuie să fie același tip; în Listarea 3-2, rezultatele atât ale ramurii if, cât și ale celei else erau numere întregi i32. Dacă tipurile nu se potrivesc, așa cum este cazul în următorul exemplu, vom primi o eroare:

Numele fișierului: src/main.rs

fn main() {
    let condition = true;

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

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

La compilarea acestui cod primim o eroare deoarece ramurile if și else au tipuri de valori incompatibile, și Rust indică exact unde să găsim problema în textul programului:

$ 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` due to previous error

Expresia în blocul if se evaluează ca un număr întreg, iar expresia din blocul else se evaluează ca un string. Acest lucru nu funcționează deoarece variabilele trebuie să aibă un singur tip, iar Rust trebuie să știe în timpul compilării care este tipul variabilei number, decisiv. Cunoașterea tipului number îi permite compilatorului să verifice dacă tipul este valid oriunde folosim number. Rust nu ar putea face asta dacă tipul number ar fi fost determinat doar la runtime; compilatorul ar fi fost mai complex sau ar fi făcut mai puține garanții despre cod, dacă ar fi trebuit să țină cont de mai multe tipuri ipotetice pentru orice variabilă.

Repetarea cu bucle

Este adesea util să execuți un bloc de cod de mai multe ori. Pentru acest lucru, Rust oferă mai multe bucle, care vor rula prin codul din interiorul corpului buclei până la sfârșit și apoi vor începe imediat de la început. Pentru a experimenta cu buclele, să facem un nou proiect numit loops.

Rust are trei tipuri de bucle: loop, while și for. Să încercăm fiecare.

Repetarea codului cu loop

Cuvântul cheie loop indică Rust să execute un bloc de cod iar și iar pentru totdeauna sau până când îi spunem explicit să se oprească.

Ca exemplu, modifică fișierul src/main.rs din directoriul tău loops pentru a arăta în felul următor:

Numele fișierului: src/main.rs

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

Când rulăm acest program, vom vedea din nou! afișat iar și iar continuu până când oprim manual programul. Majoritatea terminalelor suportă comanda rapidă ctrl-c pentru a întrerupe un program care este blocat într-o buclă continuă. Încearcă:

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

Simbolul ^C reprezintă locul în care ai apăsat ctrl-c. Este posibil să vezi sau nu cuvântul din nou! afișat după ^C, în funcție de unde era codul în buclă când a primit semnalul de întrerupere.

Rust oferă de asemenea un mod prin care poți ieși dintr-o buclă folosind cod. Poți plasa cuvântul cheie break în interiorul buclei pentru a indica programului când să se oprească execuția buclei. Amintește-ți că am făcut asta în jocul de ghicire din secțiunea “Oprirea după o ghicire corectă” din Capitolul 2 pentru a opri programul când utilizatorul a câștigat jocul prin ghicirea numărului corect.

Am folosit de asemenea continue în jocul de ghicire, care într-o buclă indică programul să sară peste orice cod rămas în această iterație a buclei și să treacă la următoarea iterație.

Returnarea valorilor din bucle

Una dintre utilizările unei instrucțiuni loop este de a reîncerca o operație despre care știi că ar putea eșua, cum ar fi verificarea dacă un thread și-a terminat treaba. Probabil că vei avea nevoie și de a trece rezultatul acelei operațiuni în afara buclei către restul codului tău. Pentru a face asta, poți adăuga valoarea pe care vrei să o returnezi după expresia break pe care o folosești pentru a opri bucla; acea valoare va fi returnată din bucla astfel încât să o poți utiliza, așa cum se arată aici:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

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

Înainte de buclă, noi declarăm o variabilă numită counter și o inițializăm la 0. Apoi declaram o variabilă numită result pentru a deține valoarea returnată din buclă. La fiecare iterație a buclei, adăugăm 1 la variabila counter, și apoi verificăm dacă counter este egal cu 10. Când este, folosim cuvântul cheie break cu valoarea counter * 2. După buclă, folosim un punct și virgulă pentru a încheia declarația care alocă valoarea pentru result. În final, noi afișăm valoarea în result, care în acest caz este 20.

Etichete de buclă pentru deosebirea între bucle multiple

Dacă ai bucle în interioarele altei bucle, break și continue se aplică buclei interne din acel punct. Poți specifica opțional o etichetă de buclă pe o buclă pe care o poți folosi apoi cu break sau continue pentru a specifica că acele cuvinte cheie se aplică buclei etichetate în locul celei mai interne bucle. Etichetele de buclă trebuie să înceapă cu un singur apostrof. Iată un exemplu cu două bucle îmbricate:

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

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

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

Bucla externă are eticheta 'counting_up, și va număra în sus de la 0 la 2. Bucla internă fără o etichetă numără în jos de la 10 la 9. Primul break care nu specifică o etichetă va ieși doar din bucla internă. Declarația break 'counting_up; va ieși din bucla externă. Acest cod afișează:

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

Buclele condiționale cu while

Un program va avea frecvent nevoie să verifice o condiție în timpul unei bucle. Cât timp condiția rămâne true, bucla se execută. Când condiția nu mai este true, programul apelează break, ceea ce oprește bucla. Comportamentul acesta poate fi realizat printr-o combinație de loop, if, else și break; poți să încerci chiar acum acest lucru într-un program, dacă vrei. Cu toate acestea, acest pattern este atât de frecvent încât Rust include o construcție specială pentru acesta, numită buclă while. În Listarea 3-3, utilizăm while pentru a rula bucla de trei ori, numărând în jos de fiecare dată, și după aceea, în afara buclei, afișăm un mesaj și ieșim din program.

Numele fișierului: src/main.rs

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

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

Listarea 3-3: Utilizarea unei bucle while pentru a rula cod atât timp cât o condiție este adevărată

Această construcție reduce semnificativ imbricările care ar fi fost necesare dacă s-ar folosi loop, if, else și break, oferind în același timp o mai mare claritate. Atâta timp cât o condiție este evaluată ca fiind true, codul rulează; în caz contrar, acesta iese din buclă.

Parcurgerea unei colecții cu for

Ai opțiunea de a folosi structura while pentru a parcurge elementele unei colecții, cum ar fi un array. De exemplu, bucla din listarea 3-4 afișează fiecare element din array-ul a.

Numele fișierului: src/main.rs

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

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

        index += 1;
    }
}

Listarea 3-4: Parcurgerea fiecărui element al unei colecții folosind o buclă while

Aici, codul numără elementele din array. Începe de la indexul 0, și apoi rulează până atinge indexul final din array (adică, când expresia index < 5 nu mai este true). Rularea acestui cod va afișa fiecare element din array:

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

Toate cele cinci valori ale array-ului apar în terminal, după cum și ne așteptam. Deși index va atinge la un moment dat valoarea 5, bucla se oprește înainte de a încerca să extragă o a șasea valoare din array.

Cu toate acestea, această abordare este predispusă la erori; am putea provoca panică programului dacă valoarea indexului sau condiția de test este incorectă. De exemplu, dacă ai modificat definiția array-ului a pentru a avea patru elemente, dar ai uitat să actualizezi condiția la while index < 4, codul s-ar opri cu panică. De asemenea rularea este lentă, deoarece compilatorul adaugă cod de execuție pentru a efectua verificarea condițională a indexului în granițele array-ului la fiecare parcurgere a buclei.

O alternativă mai concisă ar fi o buclă for cu executarea unui cod pentru fiecare element din colecție. O buclă for arată ca în codul din listarea 3-5.

Numele fișierului: src/main.rs

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

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

Listarea 3-5: Parcurgerea fiecărui element al unei colecții folosind o buclă for

Dacă vom rula acest cod vom vedea aceeași ieșire ca în listarea 3-4. Mai important, noi am îmbunătățit acum securitatea codului și am eliminat riscul de bug-uri care ar putea rezulta din depășirea sfârșitului array-ului sau din ne-parcurgerea integrală și omisiunea unor elemente.

Folosind bucla for, nu mai e nevoie să îți amintești să modifici orice alt cod dacă schimbi numărul de valori din array, cum ar fi cazul cu metoda folosită în listarea 3-4.

Siguranța și conciziunea buclelor for le fac cel mai des folosit concept de bucle în Rust. Chiar și în situații în care se dorește de rulat un anumit cod de un număr de ori, cum ar fi exemplul cu numărătoarea inversă care a folosit o buclă while în listarea 3-3, majoritatea programatorilor Rust ar folosi o buclă for utilizând un Range furnizat de biblioteca standard, care generează toate numerele în ordine începând de la un număr și terminând înainte de un alt număr.

Iată cum ar arăta numărătoarea inversă folosind o buclă for și o altă metodă despre care încă nu am vorbit, rev, pentru a inversa șirul:

Numele fișierului: src/main.rs

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

Acest cod pare mai elegant, nu-i așa?

Sumar

Ai reușit! Acesta a fost un capitol considerabil: ai învățat despre variabile, tipuri de date scalare și compuse, funcții, comentarii, expresii if și bucle! Pentru a te antrena cu conceptele discutate în acest capitol, încearcă să scrii programe care să facă următoarele lucruri:

• Convertarea temperaturilor între Fahrenheit și Celsius.
• Generearea unui al n-lea număr Fibonacci.
• Imprimarea versurile „Un elefant se legăna”, profitând de repetiția din cântec.

Când ești gata să continui, vom discuta despre un concept din Rust care nu există în mod obișnuit în alte limbaje de programare: posesiunea.

Înțelegerea posesiunii

Posesiunea este cea mai distinctă trăsătură a Rust și are implicații profunde pentru restul limbajului. Aceasta permite Rust să facă garanții de siguranță a memoriei fără a necesita un colector de gunoi (garbage collector, GC), deci este important să înțelegi cum funcționează posesiunea. În acest capitol, vom discuta despre posesiune, dar și despre câteva caractereistici conexe: împrumutarea, secționarea și cum Rust structurează datele în memorie.

Ce este posesiunea?

Posesiunea reprezintă un set de reguli care guvernează modul în care un program Rust gestionează memoria. Toate programele trebuie să gestioneze modul în care utilizează memoria unui calculator în timp ce rulează. Unele limbaje de programare dispun de colectare a gunoiului (garbage collector), care caută în mod regulat memoria care nu mai este utilizată pe măsură ce programul rulează; în alte limbaje de programare, programatorul trebuie să aloce și să elibereze explicit memoria. Rust folosește o a treia abordare: memoria este gestionată prin intermediul unui sistem de posesiune cu un set de reguli pe care compilatorul le verifică. Dacă oricare dintre reguli sunt încălcate, programul nu va fi compilat. Totuși nici o caracteristică a posesiunii nu va încetini viteza de rulare a programului.

Deoarece posesiunea este un concept nou pentru mulți programatori, este nevoie de ceva timp pentru a te obișnui cu acesta. Vestea bună este că cu cât devii mai experimentat cu Rust și cu regulile sistemului de posesiune, cu atât îți va fi mai ușor să dezvolți în mod natural cod care este sigur și eficient. Continuă să o faci!

Odată ce vei înțelege posesiunea, vei avea o bază solidă pentru înțelegerea caracteristicilor ce fac din Rust un limbaj unic. În acest capitol vei învăța despre posesiune prin câteva exemple care se concentrează asupra unei structuri de date foarte comune: string-urile.

Stiva și heap-ul

Multe limbaje de programare nu cer să te gândești prea mult la stivă și heap. Dar într-un limbaj de programare pentru sisteme ca Rust, în dependență dacă o valoare se află pe stivă sau heap afectează modul în care limbajul se comportă și necesită să iei anumite decizii. Părți din noțiunea de posesiune în raport cu stiva și heap-ul vor fi descrise mai târziu în acest capitol, așa că iată o scurtă explicație anticipată.

Atât stiva cât și heap-ul sunt părți ale memoriei disponibile codului tău pentru a fi folosite la runtime, dar care sunt structurate în moduri diferite. Stiva stochează valorile în ordinea în care le primește și elimină valorile în ordinea inversă. Acest lucru este menționat ca ultimul intrat, primul ieșit. Gândește-te la o stivă de farfurii: când adaugi mai multe farfurii, le pui în vârful grămezii, și când ai nevoie de o farfurie, o iei de pe vârful grămezii. Adăugarea sau eliminarea de farfurii de la mijloc sau de jos nu ar funcționa la fel de bine! Adăugarea de date se numește împingerea pe stivă și eliminarea de date se numește scoaterea de pe stivă. Toate datele stocate pe stivă trebuie să aibă o dimensiune cunoscută și fixă. Datele cu o dimensiune necunoscută în momentul compilării sau o dimensiune care s-ar putea schimba trebuie să fie stocate pe heap.

Heap-ul este mai puțin organizat: când pui date pe heap, ceri o anumită cantitate de spațiu. Alocatorul de memorie găsește un loc liber în heap care este suficient de mare, îl marchează ca fiind în uz și returnează un pointer, care este adresa acelui loc. Acest proces se numește alocare pe heap și este uneori abreviat drept doar alocare (împingerea valorilor pe stivă nu este considerată alocare). Deoarece pointer-ul către heap are o dimensiune cunoscută, fixă, poți stoca pointer-ul pe stivă, dar când vrei datele efective, trebuie să urmezi pointer-ul. Gândește-te că te-ai așezat la un restaurant. Când intri, precizezi numărul de persoane din grupul tău, iar gazda găsește o masă liberă care se potrivește tuturor și te conduce acolo. Dacă cineva din grupul tău vine târziu, poate întreba unde ai fost așezat să te găsească.

Împingerea pe stivă este mai rapidă decât alocarea pe heap deoarece alocatorul nu trebuie să caute niciodată un loc unde să stocheze date noi; acel loc este întotdeauna în partea de sus a stivei. Comparativ, alocarea spațiului pe heap necesită mai multă muncă deoarece alocatorul trebuie mai întâi să găsească un spațiu suficient de mare pentru a susține datele și apoi să efectueze o evidență a datelor acum alocate pentru a se pregăti pentru următoarea alocare.

Accesarea datelor în heap este mai lentă decât accesarea datelor pe stivă deoarece trebuie să urmezi un pointer pentru a ajunge acolo. Procesoarele contemporane sunt mai rapide dacă sar mai puțin prin memorie. Continuând analogia, ia în considerare un chelner la un restaurant care ia comenzi de la mai multe mese. Este mai eficient să obții toate comenzile de la o masă înainte de a trece la următoarea. Luând o comandă de la masa A, apoi o comandă de la masa B, apoi una de la A din nou, și apoi din nou una din B ar fi un proces mult mai lent. Din același motiv, un procesor își poate face treaba mai bine dacă lucrează pe date care sunt apropiate una de alta (așa cum este pe stivă) și mai lent când sunt răzlețite (așa cum poate fi pe heap).

Când codul tău apelează o funcție, valorile transmise în funcție (inclusiv, potențial, pointeri către date pe heap) și variabilele locale ale funcției sunt introduse pe stivă. Când funcția se încheie, aceste valori sunt eliminate de pe stivă.

Urmărirea care părți ale codului folosesc ce date pe heap, minimizarea cantității de date duplicate pe heap și eliberarea datelor neutilizate de pe heap astfel încât să nu rămâi fără spațiu sunt toate probleme pe care posesiunea le abordează. Odată ce înțelegi posesiunea, nu va trebui să te gândești prea des la stivă și la heap, dar știind că scopul principal al posesiunii este de a gestiona datele de pe heap poate ajuta la explicarea modului în care aceasta funcționează.

Regulile posesiunii

În primul rând, să aruncăm o privire asupra regulilor posesiunii. Ține minte aceste reguli în timp ce lucrăm la exemplele care le ilustrează:

• Fiecare valoare în Rust are un posesor.
• Poate exista doar un singur posesor la un moment dat.
• Când posesorul iese din domeniul de vizibilitate (eng. out of scope), valoarea va fi eliminată.

Domeniu de vizibilitate a variabilelor

Acum că am trecut de baza sintaxei Rust, nu vom include în toate exemplele codul fn main() {, astfel că în continuare asigură-te că introduci manual exemplele ce vor urma într-o funcție main. Ca rezultat exemplele noastre vor fi ceva mai concise, permițându-ne să ne concentrăm pe detaliile esențiale, fără prea mult cod de umplutură.

Ca prim exemplu de posesiune vom analiza domeniul de vizibilitate al unor variabile. Un domeniu de vizibilitate este intervalul în cadrul unui program în care un element este valid. Să luăm în considerare următoarea variabilă:

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

Variabila s se referă la un string literal, unde valoarea string-ului este inclusă direct în textul programului nostru. Variabila este validă de la punctul în care este declarată până la sfârșitul domeniului de vizibilitate curent. Listarea 4-1 arată un program cu comentarii care anunță unde ar fi validă variabila s.

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

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

Listarea 4-1: O variabilă și domeniul de vizibilitate în care este validă

Cu alte cuvinte, există două momente importante aici:

• Când s intră în domeniul de vizibilitate, este validă.
• Rămâne validă până când iese din domeniul de vizibilitate.

La acest moment, relația dintre domeniile de vizibilitate și momentele în care variabilele sunt valide este similară cu cea din alte limbaje de programare. Acum să continuăm studierea relațiilor de posesiune în Rust cu introducerea tipului String.

Tipul String

Pentru a ilustra regulile de posesiune, avem nevoie de un tip de date mai complex decât cele pe care le-am descris în secțiunea „Tipuri de date” a Capitolului 3. Tipurile menționate anterior sunt de dimensiune cunoscută, deci pot fi stocate în stivă și eliminate din stivă când domeniul lor de vizibilitate se termină, și pot fi copiate rapid și trivial pentru a crea o nouă instanță independentă în cazul în care o altă parte a codului are nevoie să folosească aceeași valoare, dar într-un alt domeniu de vizibilitate. Însă noi vrem să accesăm datele care sunt stocate în heap și să explorăm cum anume Rust știe când să elibereze acele date, iar tipul String este un exemplu excelent.

Acum ne vom concentra doar asupra aspectelor tipului String care sunt relevante posesiunii. Aceste aspecte se aplică și altor tipuri de date complexe, fie că sunt furnizate de biblioteca standard sau create de tine. Mai pe larg vom discuta despre String în Capitolul 8.

Am văzut deja literali ai tipului string, în care o valoare string este codificată direct în programul nostru. Literalii de string sunt convenabili, dar nu sunt potriviți pentru toate situațiile în care am dori să folosim text. Un motiv este că sunt imutabili. Altul este că nu fiecare valoare de string poate fi cunoscută din timp când scriem codul: de exemplu, ce se întâmplă dacă dorim să preluăm inputul de la utilizator și să îl stocăm? Pentru aceste situații Rust are un al doilea tip de string, String. Acest tip administrează date alocate în heap și astfel este capabil să stocheze un text care nu ne este cunoscut la momentul compilării. Poți crea un String dintr-un literal de string folosind funcția from, astfel:

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

Operatorul cu dublu două puncte :: ne permite să definim această funcție from în spațiul de nume al tipului String în loc să o numim cumva cum ar fi string_from. Vom discuta mai mult această sintaxă în secțiunea „Sintaxa metodei” din Capitolul 5, și când vorbim despre spațiul de nume cu module în „Căi pentru referirea la un element în arborele modulelor” din Capitolul 7.

Acest tip de string poate fi mutat:

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

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

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

Deci, care este diferența aici? De ce poate fi String mutat, dar literalii nu? Diferența o constituie felul în care aceste două tipuri sunt reprezentate în memorie.

Memorie și alocare

În cazul unui literal de string, cunoaștem conținutul în timpul compilării, astfel încât textul este codificat direct în executabilul final. Din acest motiv, literalele de string sunt rapide și eficiente. Dar aceste proprietăți provin doar din imutabilitatea literalului de string. Din păcate, nu putem pune un bloc de memorie în binar pentru fiecare fragment de text a cărui dimensiune este necunoscută în timpul compilării și a cărui mărime s-ar putea schimba în timpul rulării programului.

Cu tipul String, pentru a menține o bucată de text mutabilă, în creștere, trebuie să alocăm o cantitate de memorie pe heap, necunoscută în timpul compilării, pentru a deține conținutul. Aceasta înseamnă:

• Memoria trebuie solicitată de la alocatorul de memorie la runtime.
• Avem nevoie de o modalitate de a returna această memorie la alocator atunci când am terminat cu String-ul nostru.

Prima parte este realizată de noi: când apelăm String::from, implementarea sa solicită memoria de care are nevoie. Aceasta parte este comună pentru mai toate limbajele de programare.

Cu toate acestea, a doua parte este diferită. În limbajele cu un colector de gunoi (garbage collector (GC)), GC ține evidența și eliberează memoria care nu mai este folosită, programatorul nu mai având necesitatea de a se gândi la asta. Pe când în majoritatea limbajelor fără un GC e responsabilitatea noastră să identificăm când memoria nu mai este folosită și să apelăm codul pentru a o elibera explicit, la fel cum am solicitat-o. A face acest lucru corect este, de obicei, o problemă dificilă de programare. Dacă uităm, vom irosi memorie. Dacă o facem prea devreme, vom avea o variabilă nevalidă. Dacă o facem de două ori tot este o problemă. Trebuie să menținem perechi de exact o alocare cu exact o dealocare.

Rust alege o cale diferită: memoria este returnată automat odată ce variabila care o deține iese din domeniu de vizibilitate. Iată o versiune a exemplului nostru despre domeniu de vizibilitate de la Listarea 4-1 folosind un String în loc de un literal de string:

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

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

Există un punct natural la care putem returna memoria ocupată de String-ul nostru la alocator: atunci când s iese din domeniu de vizibilitate. Când o variabilă iese din domeniu de vizibilitate, Rust apelează o funcție specială. Această funcție se numește drop, și este chiar locul unde autorul String-ului poate pune codul de returnare a memoriei. Rust apelează drop automat la închiderea acoladei.

Notă: În C++, acest model de dealocare a resurselor la sfârșitul duratei de viață a unui element se numește uneori Resource Acquisition Is Initialization (RAII). Funcția drop din Rust îți va fi familiară dacă ai folosit modele RAII.

Felul acesta de operare a memoriei are un impact profund asupra modului în care este scris codul Rust. Poate părea simplu acum, dar comportamentul codului poate fi destul de neașteptat în situații mai complicate, atunci când avem mai multe variabile care utilizează datele pe care le-am alocat pe heap. Să explorăm acum unele așa situații.

Variabile și interacționarea cu date folosind permutarea

Variabilele pot interacționa cu aceleași date în diferite moduri în Rust. Să privim la un exemplu utilizând un întreg în Lista 4-2.

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

Lista 4-2: Atribuirea valorii întregului de la variabila x la y

Probabil putem ghici ce face acest cod: „atribuie valoarea 5 lui x; apoi face o copie a valorii din x și o atribuie lui y.” Acum avem două variabile, x și y, și ambele sunt egale cu 5. Așa și este, deoarece întregii în Rust sunt valori simple cu o mărime cunoscută, fixă, și aceste două valori 5 sunt împinse pe stivă.

Acum să ne uităm la versiunea cu un String:

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

Aceasta arată foarte asemănător, printr urmare s-ar putea presupune că modul în care funcționează ar fi la fel: adică, a doua linie ar face o copie a valorii din s1 și o atribuie lui s2. Doar că de data aceasta nu e chiar așa.

Priviți la Figura 4-1 pentru a vedea ce se întâmplă cu String în fundal. Un String este format din trei părți, arătate în stânga: un pointer spre memoria care deține conținutul string-ului, o lungime și o capacitate. Acest grup de date este stocat pe stivă. Pe dreapta e reprezentată memoria de pe heap care deține conținutul.

Figura 4-1: Reprezentare în memorie a unui String care deține valoarea "hello" și este atribuită lui s1

Lungimea reprezintă câtă memorie, în octeți, folosește în prezent conținutul String-ului. Capacitatea este cantitatea totală de memorie, în octeți, pe care String-ul a primit-o de la alocator. Diferența între lungime și capacitate contează, dar nu în acest context, deci, pentru moment ignorăm capacitatea.

Când atribuim s1 la s2, datele din String sunt copiate, însemnând că noi copiem pointer-ul, lungimea și capacitatea care sunt pe stivă. Noi nu copiem datele de pe heap pe care pointer-ul le referă. Cu alte cuvinte, reprezentarea datelor în memorie arată ca Figura 4-2.

Figura 4-2: Reprezentare în memorie a variabilei s2 care are o copie a pointer-ului, lungimii și capacității lui s1

Reprezentarea nu e ca în figura 4-3, ea prezintă cum ar fi arătat memoria dacă Rust copia și datele din heap. Dacă Rust ar face acest lucru, operațiunea s2 = s1 ar deveni foarte costisitoare în termeni de performanță la execuție, mai ales când datele de pe heap sunt mari.

Figura 4-3: O altă posibilitate pentru ce ar putea face s2 = s1 dacă Rust ar copia de asemenea datele de pe heap

Mai devreme, am spus că atunci când o variabilă iese din domeniul de vizibilitate, Rust apelează automat funcția drop și curăță memoria heap pentru acea variabilă. Dar Figura 4-2 arată ambele pointer-e de date adresând aceeași locație. Ar fi o problemă: când s2 și s1 ies din domeniul de vizibilitate, vor încerca amândouă să elibereze aceeași memorie. Acest lucru este cunoscut ca eroarea de eliberare dublă (double free) și este una dintre erorile de securitate a memoriei pe care le-am menționat anterior. Eliberarea memoriei de două ori poate duce la coruperea memoriei, ceea ce potențial poate provoca vulnerabilități de securitate.

Pentru a asigura securitatea memoriei, după linia let s2 = s1;, Rust consideră că s1 nu mai este valid. Prin urmare, Rust nu trebuie să elibereze nimic atunci când s1 iese din domeniul de vizibilitate. Să vedem ce se întâmplă când încercăm să folosim s1 după ce s2 este creat; nu va funcționa:

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

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

Vom primi o eroare similară, deoarece Rust ne împiedică să utilizăm referința invalidată:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:28
  |
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!("{}, world!", s1);
  |                            ^^ 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` due to previous error

Dacă ai auzit termenii copiere superficială (shallow copy) și copiere profundă (deep copy) în timp ce lucrezi cu alte limbaje, conceptul de copiere a pointerului, lungimii și capacității fără a copia datele probabil sună ca făcând o copiere superficială. Dar deoarece Rust de asemenea invalidează prima variabilă, în loc să fie numită o copiere superficială, este cunoscută ca o permutare. În acest exemplu, am spune că s1 a fost permutată în s2. Deci, ceea ce se întâmplă de fapt este ilustrat în Figura 4-4.

Figura 4-4: Reprezentarea în memorie după ce s1 a fost invalidat

Aceasta rezolvă problema noastră! Cu doar s2 validă, atunci când iese din domeniul de vizibilitate variabila va elibera singură memoria.

În plus, rezultă un fapt important pentru design-ul limbajului: Rust nu va crea niciodată automat o „copiere profundă” a datelor noastre. Prin urmare, orice copiere automată poate fi presupusă a fi ieftină în ceea ce privește performanța la runtime.

Variabile și interacționarea cu date folosind clonarea

Dacă vrem să copiem în profunzime datele unui String din heap, nu doar datele din stivă, putem folosi o metodă des întâlnită, numită clone. Vom discuta sintaxa metodelor în Capitolul 5, însă deoarece metodele sunt o caracteristică comună în multe limbaje de programare, probabil le-ai întâlnit deja.

Iată un exemplu al utilizării metodei clone:

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

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

Acest lucru funcționează foarte bine și produce în mod explicit comportamentul prezentat în Figura 4-3, unde datele din heap sunt copiate.

Când vezi un apel către clone, știi că se execută un anumit cod arbitrar și că acest cod poate fi costisitor. Este un indicator vizual că se întâmplă ceva diferit.

Date doar pe stivă: trăsătura Copy

Există o altă nuanță despre care nu am discutat încă. Acest cod care folosește numere întregi, o parte din el a fost arătată în Listarea 4-2, funcționează și este valid:

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

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

Dar acest cod pare să contrazică ceea ce tocmai am învățat: nu avem un apel la clone, dar x este încă valid și nu a fost permutat în y.

Motivul este că unele tipuri, cum ar fi numerele întregi care au o dimensiune cunoscută la compilare, sunt stocate în întregime pe stivă, astfel încât copierea valorilor lor este foarte rapidă. Astfel nu avem niciun motiv să vrem să prevenim x de a fi valid după ce am creat variabila y. Cu alte cuvinte, nu există nicio diferență între copierea profundă și cea superficială aici, deci apelarea la clone nu ar face nimic diferit de copierea superficială obișnuită, așa că o putem lăsa pentru alte cazuri.

Rust are o adnotare specială numită trăsătura Copy pe care o putem aplica la tipuri care sunt stocate pe stivă, la fel ca numerele întregi (vom vorbi mai multe despre trăsături în Capitolul 10). Dacă un tip implementează trăsătura Copy, variabilele care îl utilizează nu se permută, ci sunt copiate superficial, lucru care le păstrează valide după atribuirea lor altei variabile.

Rust nu ne va lăsa să adnotăm un tip cu Copy dacă tipul, sau oricare dintre părțile sale, a implementat trăsătura Drop. Dacă tipul are nevoie de ceva special să se întâmple când valoarea iese din domeniul de vizibilitate și adăugăm adnotarea Copy la acel tip, vom primi o eroare la compilare. Pentru a afla cum să adăugați adnotarea Copy la tipul tău pentru a implementa trăsătura, vedeți “Trăsături derivate” în Anexa C.

Deci, ce tipuri implementează trăsătura Copy? Puteți verifica documentația pentru tipul dat pentru a fi sigur, dar ca o regulă generală, orice grup de valori scalare simple poate implementa Copy, și nimic care necesită alocare sau este o formă de resursă nu poate implementa Copy. Iată câteva tipuri care implementează Copy:

• Toate tipurile de numere întregi, cum ar fi u32.
• Tipul Boolean, bool, cu valorile true și false.
• Toate tipurile de numere în virgulă mobilă, cum ar fi f64.
• Tipul de caractere, char.
• Tuple, dacă acestea conțin numai tipuri care de asemenea implementează Copy. De exemplu, (i32, i32) implementează Copy, dar (i32, String) nu.

Funcțiile și posesiunea

Transmiterea unei valori către o funcție e similară cu atribuirea acelei valori unei variabile. A transmite o variabilă către o funcție implică fie permutarea, fie copierea acelei valori, exact așa cum se întâmplă și la atribuire. În Lista 4-3, am pregătit un exemplu cu adnotări pentru a ilustra când intră și ies variabilele din domeniul de vizibilitate.

Numele fișierului: src/main.rs

fn main() {
    let s = String::from("hello");  // s comes into scope

    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope

    makes_copy(x);                  // x would move into the function,
                                    // but i32 is Copy, so it's okay to still
                                    // use x afterward

} // Here, x goes out of scope, then s. But because s's value was moved, nothing
  // special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{}", some_string);
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{}", some_integer);
} // Here, some_integer goes out of scope. Nothing special happens.

Listarea 4-3: Funcții cu posesiunea și domeniul de vizibilitate adnotat

Dacă am încercat să utilizăm s după apelul la takes_ownership, Rust ar genera o eroare la compilare. Aceste verificări statice ne protejează de greșeli. Încearcă să adaugi cod la main care folosește s și x pentru a vedea unde le poți folosi și unde regulile de posesiune te împiedică să faci asta.

Valorile returnate și domeniul de vizibilitate

Returul valorilor poate transmite, de asemenea, posesiunea. Listarea 4-4 ilustrează un exemplu de funcție care returnează o valoare, folosind adnotări similare cu cele din Listarea 4-3.

Numele fișierului: src/main.rs

fn main() {
    let s1 = gives_ownership();         // gives_ownership moves its return
                                        // value into s1

    let s2 = String::from("hello");     // s2 comes into scope

    let s3 = takes_and_gives_back(s2);  // s2 is moved into
                                        // takes_and_gives_back, which also
                                        // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
  // happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {             // gives_ownership will move its
                                             // return value into the function
                                             // that calls it

    let some_string = String::from("yours"); // some_string comes into scope

    some_string                              // some_string is returned and
                                             // moves out to the calling
                                             // function
}

// This function takes a String and returns one
fn takes_and_gives_back(a_string: String) -> String { // a_string comes into
                                                      // scope

    a_string  // a_string is returned and moves out to the calling function
}

Listarea 4-4: Transferul posesiunii prin valorile returnate

Posesiunea unei variabile urmează același model de fiecare dată: atribuirea unei valori unei alte variabile determină permutarea acesteia. Când variabila, care include date pe heap, iese din domeniul de vizibilitate, valoarea este eliberată prin funcția drop, cu excepția situației în care posesiunea datelor a fost permutată către o altă variabilă.

Această abordare este funcțională, dar preluarea posesiunii și ulterior returnarea acesteia cu fiecare funcție se poate dovedi a fi un proces anevoios. Ce facem dacă vrem ca o funcție să utilizeze o valoare, fără a-i lua posesiunea? Este laborios faptul că tot ce trimitem în interiorul unei funcții trebuie să fie returnat înapoi dacă dorim să-l utilizăm din nou, în plus față de orice rezultate obținute în corpul funcției pe care am dori să le returnăm.

Rust ne oferă posibilitatea de a returna mai multe valori prin utilizarea unei tuple, așa cum este ilustrat în Listarea 4-5.

Numele fișierului: src/main.rs

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

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

    println!("The length of '{}' is {}.", s2, len);
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String

    (s, length)
}

Listarea 4-5: Returnarea posesiunii parametrilor

Însă acest proces este prea laborios și complex pentru un concept ce ar trebui să fie simplu. Din fericire pentru noi, Rust dispune de o funcționalitate ce ne permite să folosim o valoare fără a-i transfera posesiunea, funcționalitate cunoscută sub numele de referințe.

Referințe și procesul de împrumutare

Dificultatea pe care o întâmpinăm cu codul pentru tuplă, din Listarea 4-5, este că trebuie să returnăm String-ul către funcția apelantă pentru a putea utiliza în continuare String-ul după apelul funcției calculate_length. Aceasta se datorează faptului că String-ul a fost permutat în interiorul funcției calculate_length. O soluție alternativă ar fi să furnizăm o referință la valoarea String-ului. O referință funcționează similar unui pointer - ea reprezintă o adresă ce permite accesul la datele stocate la acea adresă; aceste date fiind deținute de o altă variabilă. Însă, spre deosebire de un pointer, o referință este garantată să indice o valoare validă a unui anumit tip, pe toată durata vieții acestei referințe.

Iată cum definim și utilizăm funcția calculate_length care are ca parametru o referință la un obiect, în loc să preia posesiunea valorii:

Numele fișierului: src/main.rs

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

    let len = calculate_length(&s1);

    println!("The length of '{}' is {}.", s1, len);
}

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

În primul rând, observăm că tot codul referitor la tuplă, din declarația variabilei și valoarea de return a funcției, a dispărut. În al doilea rând, remarcăm faptul că transmitem &s1 către funcția calculate_length și că, în definiția sa, preluăm &String și nu String. Aceste semne de ampersand reprezintă referințe și permit să te referi la o anumită valoare fără a-i prelua posesiunea. Conceptul este reprezentat în Figura 4-5.

Figura 4-5: Diagrama ilustrând &String s care direcționează spre String s1

Notă: Procesul invers referențierii prin utilizarea & este dereferențierea, realizată cu ajutorul operatorului de dereferențiere, *. Vom explora câteva situații de utilizare a operatorului de dereferențiere în Capitolul 8 și vom discuta în detaliu despre dereferențiere în Capitolul 15.

Să examinăm mai în detaliu apelul funcției de aici:

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

    let len = calculate_length(&s1);

    println!("The length of '{}' is {}.", s1, len);
}

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

Sintaxa &s1 ne permite să creăm o referință care indică valoarea s1 însă fără a o deține. Dat fiind faptul că nu o deține, valoarea la care face referire nu va fi abandonată (dropped) când referința nu mai este folosită.

În mod similar, semnătura funcției folosește & pentru a indica faptul că tipul parametrului s este o referință. Să adăugăm câteva adnotări care să clarifice aceste aspecte:

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

    let len = calculate_length(&s1);

    println!("The length of '{}' is {}.", s1, len);
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because it does not have ownership of what
  // it refers to, it is not dropped.

Domeniul în care este validă variabila s coincide cu cel al oricărui parametru de funcție. Cu toate acestea, valoarea către care se referă nu este eliminată când nu mai folosim s. Motivul este simplu: s nu are posesiunea acestei valori. Dacă funcțiile noastre folosesc referințe ca parametri, în locul valorilor propriu-zise, nu trebuie să returnăm valorile pentru a restitui posesiunea, deoarece, de fapt, nu am avut niciodată posesiunea acestora.

Acest act de a crea o referință îl numim împrumutare. În mod similar cu viața de zi cu zi, dacă o persoană deține ceva, tu poți să îi împrumuți acel lucru. Odată ce ai terminat cu acel lucru, trebuie să îl restitui. Întrucât nu îți aparține.

Așadar, ce se întâmplă dacă încercăm să modificăm ceva ce doar împrumutăm? Încearcă codul din Listarea 4-6. Dar te previn: nu o să iasă exact cum te-ai așteptat!

Numele fișierului: src/main.rs

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

    change(&s);
}

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

Listarea 4-6: Tentativa de a modifica o valoare împrumutată

Aceasta este eroarea întâlnită:

$ 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
  |
7 | fn change(some_string: &String) {
  |                        ------- help: consider changing this to be a mutable reference: `&mut String`
8 |     some_string.push_str(", world");
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` due to previous error

Exact așa cum sunt imutabile variabilele, în mod implicit, la fel sunt și referințele. Nu ne este permisă modificarea unei valori la care deținem doar o referință.

Referințe mutabile

Putem corecta codul din Listarea 4-6 pentru a ne oferi posibilitatea de a modifica o valoare împrumutată, prin câteva ajustări minore care implică utilizarea unei referințe mutabile:

Numele fișierului: src/main.rs

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

    change(&mut s);
}

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

În primul rând, modificăm s pentru a fi mut. Apoi, creăm o referință mutabilă cu &mut s în momentul în care invocăm funcția change, și actualizăm semnătura funcției pentru a accepta o referință mutabilă cu some_string: &mut String. Astfel, devine foarte clar că funcția change va modifica valoarea pe care o împrumută.

Referințele mutabile vin însă cu o limitare importantă: dacă deții o referință mutabilă la o valoare, nu poți deține alte referințe către aceeași valoare. Acest cod, care încearcă să creeze două referințe mutabile la s, va da eroare:

Filename: src/main.rs

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

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

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

Și eroarea:

$ 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` due to previous error

Această eroare ne informează că respectivul cod nu este valid, întrucât nu se poate împrumuta s în mod mutabil de mai multe ori concomitent. Primul împrumut mutabil se realizează în r1 și trebuie să continue până când este folosit în instrucțiunea println!. Cu toate acestea, între momentul creării acestei referințe mutabile și momentul utilizării sale, am încercat să generăm o altă referință mutabilă în r2, care împrumută aceleași date ca și r1.

Restricția care interzice mai multe referințe mutabile simultane la aceleași date ne permite să modificăm datele, dar într-un mod extrem de controlat. Aceasta este o provocare des întâlnită pentru cei nou-veniți în lumea Rust, deoarece majoritatea limbajelor de programare permit modificarea datelor oricând. Avantajul acestei restricții este faptul că Rust poate preveni apariția curselor de date în timpul compilării. O cursă de date este similară cu o condiție de cursă și se produce atunci când au loc următoarele trei evenimente:

• Două sau mai multe pointere accesează simultan aceleași date.
• Cel puțin un pointer este utilizat pentru a scrie date.
• Nu există niciun mecanism în vigoare care să sincronizeze accesul la date.

Cursele de date creează un comportament nedefinit și pot fi dificile de diagnosticat și remediat atunci când încerci să le detectezi în timpul execuției; Rust preîntâmpină acest gen de problemă prin faptul că refuză să compileze codul în care apar curse de date!

Ca de obicei, avem posibilitatea de a utiliza acolade pentru a iniția un nou domeniu de vizibilitate, astfel facilitând existența mai multor referințe mutabile; singura condiție este aceea de a nu fi simultane:

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

    {
        let r1 = &mut s;
    } // r1 goes out of scope here, so we can make a new reference with no problems.

    let r2 = &mut s;
}

Rust impune o regulă similară pentru combinarea referințelor mutabile și imutabile. Acest cod generează o eroare:

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

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    let r3 = &mut s; // BIG PROBLEM

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

Eroarea:

$ 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!("{}, {}, and {}", r1, r2, r3);
  |                                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` due to previous error

De asemenea, nu ne este permis să avem o referință mutabilă în același timp cu o referință imutabilă către aceeași valoare.

Cei ce folosesc o referință imutabilă nu se așteaptă ca valoarea să se schimbe brusc, fără un avertisment! Totuși, sunt permise multiple referințe imutabile, deoarece nicio persoană ce doar citește datele nu are abilitatea de a interfera cu lectura altcuiva a acelor date.

Trebuie să reții că domeniul de vizibilitate al unei referințe începe de unde este aceasta introdusă și continuă până la ultima utilizare a respectivei referințe. De pildă, acest cod se va compila deoarece ultima folosire a referințelor imutabile, și anume println!, are loc înainte de a fi introdusă referința mutabilă:

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

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{} and {}", r1, r2);
    // variables r1 and r2 will not be used after this point

    let r3 = &mut s; // no problem
    println!("{}", r3);
}

Domeniile de vizibilitate pentru referințele imutabile r1 și r2 se încheie imediat după ce au fost utilizate pentru ultima dată în println!. Asta se întâmplă înainte ca referința mutabilă r3 să fie creată. Aceste domenii nu se intersectează, deci nu interferă unul cu celălalt, făcând acest cod valid. Compilatorul Rust este în stare să determine că referința nu mai este folosită înainte de sfârșitul domeniului de vizibilitate.

Știm că erorile legate de împrumutări pot fi frustrante uneori. Totuși, trebuie să înțelegem că acesta este un mecanism prin care compilatorul Rust ne avertizează asupra unui potențial bug în stadiul de compilare, nu în timpul rulării. În plus, ne indică exact locul unde apare problema. Aceasta îți va economisi timp deoarece nu va trebui să cauți motivul pentru care datele tale nu corespund cu ceea ce te așteptai.

Referințe fără destinație

În limbajele de programare ce utilizează pointeri, este foarte ușor să generăm, chiar și involuntar, un pointer în aer (dangling) - un pointer ce își pierde legătura cu o parte de memorie care poate fi atribuită altei operațiuni - prin simpla eliberare a unei părți din memoria alocate, în timp ce pointerul către acea memorie rămâne încă activ. În contrast, Rust, prin intermediul compilatorului, garantează că niciodată nu vor exista referințe fără destinație: dacă avem o referință la niște date, compilatorul se va asigura că acele date nu vor fi scoase din domeniul de vizibilitate înainte ca referința spre ele să o facă.

Acum, să încercăm să generăm o referință fără destinație, doar pentru a observa cum Rust previne acest lucru printr-o eroare la etapa de compilare:

Numele fișierului: src/main.rs

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

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

    &s
}

Vom primi eroarea:

$ 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
  |
5 | fn dangle() -> &'static String {
  |                 +++++++

For more information about this error, try `rustc --explain E0106`.
error: could not compile `ownership` due to previous error

Acest mesaj de eroare face referire la un concept pe care încă nu l-am abordat: durate de viață. Vom aprofunda această temă în Capitolul 10. Cu toate acestea, chiar dacă nu ținem cont de porțiunile ce se referă la durate de viață, mesajul (tradus) ne oferă o pistă esențială pentru a intelege de ce acest fragment de cod nu funcționează:

tipul de retur al acestei funcții conține o valoare împrumutată, dar nu există nicio valoare pentru a fi împrumutată

Să examinăm mai atent ce se petrece la fiecare pas în codul nostru dangle:

Numele fișierului: src/main.rs

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

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope, and is dropped. Its memory goes away.
  // Danger!

Dat fiind că s este generat în interiorul dangle, la finalizarea rulării codului din dangle, s va fi dezalocat. Cu toate acestea, noi am încercat să returnăm o referință către s. Aceasta presupune că referința noastră ar fi îndreptată către un String ce devine invalid. Situația nu este deloc favorabilă! Rust nu ne va permite să desfășurăm o astfel de acțiune.

Soluția în acest caz constă în returnarea directă a String:

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

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

    s
}

Aceasta funcționează fără nici o problemă. Posesiunea este permutată și nimic nu este dezalocat.

Regulamentul referințelor

Să reamintim principiile pe care le-am discutat despre referințe:

• În orice clipă, ai voie să deții ori o singură referință mutabilă sau o cantitate nelimitată de referințe imutabile.
• Referințele trebuie să fie valide în permanență.

Următoarea etapă va fi examinarea unui alt tip de referință: slice-urile.

Tipul Slice

Secționarea (slicing) îți permite să referențiezi o secvență contiguă de elemente dintr-o colecție, fără a face referire la întreaga colecție. O secțiune este un fel de referință și, prin urmare, ea nu deține posesiunea.

Iată o problemă de programare interesantă: scrie o funcție care acceptă un string format din cuvinte separate de spații și care returnează primul cuvânt descoperit în acest string. Dacă funcția nu găsește vreun spațiu în string, atunci întregul string este un singur cuvânt, caz în care întregul string ar trebui returnat.

Să analizăm cum am formula semnătura acestei funcții fără a utiliza secționări, pentru a înțelege mai bine problema pe care secționarea o va soluționa:

fn first_word(s: &String) -> ?

Funcția first_word utilizează un parametru de tip &String. Nu ne interesează posesiunea asupra valorii, deci acesta este modul corect de a proceda. Însă, ce valoare ar trebui să returneze funcția? În momentul de față, nu dispunem de un mijloc prin care să ne referim la o porțiune a unui string. Totuși, o soluție ar fi să returnăm indexul la care se încheie cuvântul, index care este marcat de un spațiu. Să încercăm această abordare, așa cum este prezentată în Listarea 4-7.

Numele fișierului: src/main.rs

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

Listare 4-7: Funcția first_word care returnează un index de byte în cadrul parametrului de tip String

Avem nevoie să parcurgem String-ul element cu element și să determinăm dacă o valoare este un spațiu. Pentru aceasta, vom converti String într-un array de byte utilizând metoda 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() {}

În pasul următor, vom crea un iterator care să parcurgă array-ul de bytes, folosind metoda 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() {}

Vom detalia mai mult despre iteratori în Capitolul 13. Până atunci, este important de ştiut că iter este o metodă care returnează fiecare element al unei colecții, iar enumerate este un înveliş peste rezultatul lui iter. Ea returnează fiecare element ca parte a unei tuple. Primul element al tuplei returnate de enumerate este indexul, iar al doilea este o referință la element. Acest lucru este mai practic decât să calculăm noi înșine indexul.

Faptul că metoda enumerate returnează o tuplă ne dă posibilitatea de a folosi anumite modele pentru a destrăma acea tuplă. Vom detalia mai mult despre aceste modele în Capitolul 6. În cadrul buclei for, folosim un model care plasează i pe postura de index în tuplă, și &item pentru unicul byte din tuplă. Din moment ce .iter().enumerate() ne furnizează o referință la element, folosim & în model.

În interiorul buclei for, căutăm byte-ul care semnifică spațiul, folosind sintaxa literală a byte-ului. Dacă găsim un spațiu, vom returna poziția acestuia. Dacă nu, returnăm lungimea string-ului prin utilizarea 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() {}

Avem acum o metodă prin care putem identifica indexul corespunzător sfârșitului primului cuvânt din string. Totuși, întâmpinăm o problemă. Valoarea pe care o returnăm este un usize care, luat izolat, este doar un număr cu semnificație în contextul &String. Altfel spus, dat fiind faptul că acesta este o valoare separată de String, nu putem garanta faptul că aceasta va rămâne validă în viitor. Ia în considerare programul din Listarea 4-8 care utilizează funcția first_word din Listarea 4-7.

Numele fișierului: src/main.rs

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

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

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but there's no more string that
    // we could meaningfully use the value 5 with. word is now totally invalid!
}

Listarea 4-8: Stocarea rezultatului obținut în urma apelării funcției first_word, urmată de modificarea conținutului variabilei tip String

Acest program este compilat fără nicio eroare și ar continua să funcționeze corect chiar și dacă am folosi word după apelarea metodei s.clear(). Întrucât word nu este legat de starea lui s în nici un fel, word păstrează în continuare valoarea 5. Am putea utiliza valoarea 5 cu variabila s pentru a încerca să extragem primul cuvânt, însă am avea de-a face cu un bug, deoarece conținutul lui s s-a modificat de la momentul stocării valorii 5 în word.

Preocuparea constantă legată de faptul că indexul din word ar putea să nu mai fie în sincronizare cu datele din s este anevoioasă și ne expune erorilor! Administrarea acestor indici devine și mai fragilă dacă am scrie o funcție second_word. Semnătura acesteia ar trebui să arate în felul următor:

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

Acum există doi indici pe care trebuie să-i urmărim: cel de început și cel de sfârșit. În plus, avem din ce în ce mai multe valori care rezultă din date procesate într-o anumită stare, dar nu se conectează cu acea stare. Suntem înconjurați de trei variabile nelegate care trebuie să rămână sincronizate.

Din fericire, Rust oferă o soluție eficientă la această problemă: secționarea string-urilor.

Secțiuni de string-uri

O secțiune de string reprezintă o referință la o porțiune dintr-un String, având următoarea formă:

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

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

hello nu este o referință la întregul String, ci la o secțiune din acesta, secțiune specificată prin adăugarea elementului [0..5]. Secțiunile sunt create utilizând un interval în cadrul parantezelor pătrate, prin specificarea formatului [indexul_de_start..indexul_de_sfârșit], unde indexul_de_start reprezintă prima poziție din secțiune, iar indexul_de_sfârșit este cu o unitate mai mare decât ultima poziție din secțiune. Intern, structura de date a secțiunii stochează poziția de start și lungimea secțiunii, lungime care corespunde cu diferența dintre indexul_de_sfârșit și indexul_de_start. Astfel, în cazul let world = &s[6..11];, world este o secțiune care conține un pointer către octetul din poziția 6 din s, având lungimea de 5.

Figura 4-6 ilustrează clar acest aspect.

Figura 4-6: Secțiune de string ce face referire la o parte a unui String

Folosind sintaxa specifică Rust pentru diapazoane, .., dacă vrei să începi de la indexul 0, poți omite valoarea înaintea celor două puncte. Altfel spus, cele două exemple de mai jos sunt echivalente:

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

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

La fel, dacă secțiunea ta include ultimul byte al string-ului, poți omite numărul de la final. Prin urmare, următoarele două exemple sunt echivalente:

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

let len = s.len();

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

De asemenea, poți renunța la ambele valori pentru a prelua o secțiune din întregul string. Acest fapt înseamnă că următoarele două exemple sunt identice:

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

let len = s.len();

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

Notă: Indicii de interval pentru secțiunea de string-uri trebuie să corespundă la limitele caracterelor UTF-8 valide. Dacă încerci să creezi o secțiune de string în mijlocul unui caracter multi-byte, programul tău va ieși cu o eroare. Pentru a introduce conceptul de secțiuni de string-uri, presupunem că utilizăm doar ASCII în această secțiune. O discuție mai detaliată despre manipularea UTF-8 se găsește în secțiunea „Stocarea textului codificat UTF-8 cu String-uri” din Capitolul 8.

Cu toate aceste informații în minte, să rescriem funcția first_word pentru a returna o secțiune. Tipul ce denotă "secțiunea de string" se scrie ca &str.

Numele fișierului: src/main.rs

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

Obținem indexul corespunzător sfârșitului cuvântului într-un mod similar cu cel prezentat în Listarea 4-7, prin identificarea primei apariții a unui spațiu. În momentul în care identificăm un spațiu, returnăm o secțiune din string folosind punctul de început al string-ului și indexul spațiului ca indici de început și sfârșit.

Astfel, la apelul funcției first_word, primim o singură valoare, care este strâns legată de datele inițiale. Această valoare este constituită dintr-o referință către punctul de start al secțiunii și numărul de elemente ce se regăsesc în secțiune.

Similar, returnarea unei secțiuni ar funcționa și în cazul unei funcții numite second_word:

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

Acum dispunem de o interfață API simplificată, al cărei utilizare eronată este semnificativ redusă, deoarece compilatorul se va asigura că referințele din String rămân valide. Îți amintești de erorile din programul prezentat în Listarea 4-8? Acolo, am obținut indexul care indica sfârșitul primului cuvânt, dar ulterior am golit string-ul, ceea ce a făcut ca indexul nostru să devină inutilizabil. Deși acest cod era logic incorect, nu am întâmpinat nicio eroare imediată. Problemele ar fi devenit vizibile mai târziu, dacă am fi continuat să folosim indexul primului cuvânt cu un string gol. Utilizarea secțiunilor face această eroare imposibilă și ne avertizează mult mai devreme cu privire la problemele din codul nostru. Folosind versiunea de secțiune a first_word, vom întâmpina o eroare în timpul compilării:

Numele fișierului: src/main.rs

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {}", word);
}

Avem următoarea eroare de compilare:

$ 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` due to previous error

Luați în considerare regulile de împrumutare: dacă avem o referință imutabilă la un anumit element, nu putem obține, în același timp, și o referință mutabilă la acel element. Funcția clear are nevoie să trunchieze o variabilă de tip String, deci trebuie să obțină o referință mutabilă la aceasta. Funcția println!, care urmează după apelul la clear, utilizează referința la variabila word. Deci, referința imutabilă utilizată de println! trebuie să fie încă activă la momentul acela. Cu toate acestea, limbajul Rust nu permite ca o referință mutabilă (utilizată în clear) și o referință imutabilă (utilizată în word) să existe simultan, fapt care conduce la eșecul compilării. Acesta este un exemplu de cum Rust nu doar că face API-ul nostru mai ușor de utilizat, dar elimină eficient și o întreagă clasă de erori chiar în timpul compilării!

Literalii de string ca secțiuni

Vă reamintim că am discutat anterior despre modul în care literalii de tip string sunt stocați în interiorul codului binar. Acum, având cunoștințe despre secțiuni, putem înțelege într-un mod mai profund literalii de tip string:

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

Aici, tipul variabilei s este &str: reprezintă o secțiune care indică un anumit punct specific în codul binar. Acesta este, de asemenea, motivul pentru care literalii de tip string sunt imutabili; &str este o referință imutabilă.

Utilizarea secțiunilor de string ca parametri

Înțelegând faptul că putem prelua secțiuni din literale și valori String, acest lucru ne permite să facem o îmbunătățire suplimentară a funcției first_word, însemnând în special modificarea modului în care aceasta este semnată:

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

Un programator Rust mai experimentat ar opta pentru semnătura de tip prezentată în Listarea 4-9, deoarece aceasta ne permite să utilizăm aceeași funcție atât pentru valorile &String, cât și pentru cele &str.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or whole
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Listare 4-9: Optimizarea funcției first_word prin folosirea unei secțiuni de string ca tip pentru parametrul s

Dacă dispunem de o secțiune de string, o putem transmite direct. Dacă avem un String, putem transmite fie o secțiune a String-ului, fie o referință la String. Această versatilitate profită de funcționalitatea deref coercions, un aspect pe care îl vom explora în secțiunea „Coerciții Deref implicite cu funcții și metode” din Capitolul 15.

Definind o funcție care să preia o secțiune de string în locul unei referințe la un String, API-ul nostru devine mai general și util, fără a compromite orice altă funcționalitate:

Numele fișierului: src/main.rs

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or whole
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Alte tipuri de secțiuni

Secțiunile de string-uri, așa cum probabil ți-ai imaginat deja, sunt specifice pentru string-uri. Totuși, există și un tip de secțiune cu o aplicabilitate mai largă. Gândește-te la următorul array:

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

La fel cum am dori să facem referire la o anumită porțiune dintr-un string, ne-ar putea interesa să ne referim la o anumită parte a unui array. Am face-o astfel:

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

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

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

Această secțiune are tipul &[i32]. Funcționează exact la fel ca secțiunile de string-uri, prin stocarea unei referințe la primul element și a lungimii acestuia. Vei utiliza acest tip de secțiune pentru o multitudine de alte categorii de colecții. Vom adresa aceste colecții în mod detaliat când vom discuta despre vectori în Capitolul 8.

Sumar

Conceptele de posesiune, împrumutare și utilizarea secțiunilor garantează siguranța memoriei în programele Rust la momentul compilării. Limbajul Rust îți oferă autonomie în gestionarea memoriei, asemenea altor limbaje de programare de sistem. Avantajul remarcabil al Rust constă în faptul că deținătorul datelor efectuează automat o curățenie a acestora atunci când iese din domeniul de vizibilitate. Astfel, nu este nevoie de scrierea și depanarea de cod adițional.

Posesiunea influențează modul în care funcționează multe alte componente ale limbajului Rust; de aceea, ne vom aprofunda în discutarea acestor concepte pe tot parcursul cărții. Să mergem mai departe la Capitolul 5, unde vom examina gruparea datelor în cadrul unei structuri.

Folosirea structurilor pentru organizarea datelor interconectate

O structură, sau mai simplu struct, este un tip de date personalizat care ne permite să grupăm împreună și să denumim valorile diferite, dar conexate, într-un ansamblu unitar și însemnat. Dacă ești familiarizat cu un limbaj de programare orientat pe obiecte, o structură ar putea fi similară cu atributele de date ale unui obiect. În acest capitol, vom face o analiză comparativă între tuple și structuri, bazându-ne pe ceea ce deja cunoști, și vom arăta când este mai avantajos să folosim structurile pentru a grupa datele.

Vom exemplifica cum se definesc și se inițializează structurile. Vom discuta cum se definesc funcțiile asociate, în special tipul de funcții asociate, cunoscute sub numele de metode, pentru a descrie comportamentul asociat cu un tip de structură. Structurile și enumerările (discutate în Capitolul 6) stau la baza creării de noi tipuri în domeniul propriului tău program, pentru a beneficia la maximum de verificarea tipurilor datelor în timpul compilării în limbajul Rust.

Definirea și crearea instanțelor de structuri

Structurile prezintă anumite asemănări cu tuplele, pe care le-am discutat în secțiunea “Tipul tuplă”. Ambele pot deține mai multe valori direct correlate. Similar tuplelor, elementele unei structuri pot avea tipuri diferite. Cu toate acestea, în cazul unei structuri vei atribui un nume fiecărui segment de date, astfel încât să fie evident ce semnifică aceste valori. Prin adăugarea acestor denumiri, structurile devin mai flexibile decât tuplele: nu va trebui să te bazezi pe ordinea datelor pentru a specifica sau accesa valorile unei instanțe.

Pentru a defini o structură, folosim cuvântul cheie struct și atribuim un nume întregii structuri. Numele unei structuri ar trebui să descrie întreaga semnificație a fragmentelor de date grupate împreună. Apoi, în interiorul acoladelor, definim numele și tipurile fragmentelor de date, pe care le numim câmpuri (fields). De exemplu, în Listarea 5-1 prezentăm o structură care stochează informații legate de un cont de utilizator.

Numele fișierului: src/main.rs

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

fn main() {}

Listarea 5-1: Definirea structurii User

Odată ce am definit o structură, pentru a o putea utiliza, trebuie să creăm o instanță a acesteia. Creăm o instanță stabilind valorile specifice pentru fiecare dintre câmpurile structurii. Acest lucru se realizează prin menționarea numelui structurii urmat de paranteze acolade, care includ perechi de tip cheie: valoare. 'Cheile' sunt denumirile câmpurilor, iar 'valorile' reprezintă informațiile pe care intenționăm să le stocăm în aceste câmpuri. Ordinea în care specificăm câmpurile nu trebuie să respecte neapărat ordinea în care acestea au fost declarate în structură. Cu alte cuvinte, putem privi definiția structurii ca pe un șablon general pentru tipul de date, iar instanțele completează acest șablon cu date specifice, formând astfel valori ale acelui tip. De exemplu, putem declara un utilizator specific conform exemplului din Listarea 5-2.

Numele fișierului: src/main.rs

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

Listing 5-2: Creating an instance of the User struct

Pentru a extrage o anumită valoare dintr-o structură, apelăm la notația cu punct. De pildă, dacă dorim să accesăm adresa de email a acestui utilizator, utilizăm expresia user1.email. În cazul în care instanța noastră este mutabilă, avem posibilitatea de a modifica o valoare folosind aceeași notație cu punct, dar realizând o atribuire într-un câmp specific. În Listarea 5-3 este prezentată modalitatea de schimbare a valorii în câmpul email al unei instanțe mutabile de tip User.

Numele fișierului: src/main.rs

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

Listing 5-3: Changing the value in the email field of a User instance

Listarea 5-3: Schimbarea valorii în câmpul email pentru o instanţă User

Este important de notat, că toată instanța trebuie să fie mutabilă; Rust nu ne oferă posibilitatea de a defini doar anumite câmpuri ca fiind mutabile. Similar cu alte expresii, putem crea o instanță nouă a structurii în calitate de ultimă expresie în corpul funcției, astfel încât noua instanță să fie returnată în mod implicit.

Listarea 5-4 prezintă o funcție build_user, care returnează o instanță User, în funcție de email-ul și numele de utilizator specificat. Câmpul active ia valoarea true, iar sign_in_count primește valoarea 1.

Numele fișierului: src/main.rs

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

Listarea 5-4: O funcție build_user care preia un email și un nume de utilizator, returnând o instanță User

Este firesc să folosim aceleași denumiri pentru parametrii funcției precum cele ale câmpurilor din structură. Cu toate acestea, repetarea numelor câmpurilor email și username și a variabilelor poate deveni monotonă. Dacă structura ar conține mai multe câmpuri, repetarea fiecărui nume s-ar transforma într-o sarcină mai mult decât fastidioasă. Din fericire, există o prescurtare foarte convenabilă!

Aplicarea sintaxei de inițializare abreviată a câmpurilor

Dând luare de seama că în Listarea 5-4 numele parametrilor se potrivesc perfect cu denumirile câmpurilor din structură, avem posibilitatea de a utiliza sintaxa de inițializare abreviată a câmpurilor (field init shorthand). Acest lucru ne permite să rescriem funcția build_user astfel încât aceasta să funcționeze identic, însă eliminând repetarea neceasră a numelor username și email. Acest proces este ilustrat în Listarea 5-5.

Numele fișierului: src/main.rs

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

Listarea 5-5: O funcție build_user care utilizează sintaxa abreviată de inițializare a câmpurilor, având în vedere faptul că parametrii username și email corespund cu numele câmpurilor din structură

În acest caz, noi generăm o nouă instanță a structurii User, ce include un câmp denumit email. Intenția noastră este de a atribui valoarea câmpului email cu valoarea corespunzătoare parametrului email din funcția build_user. Grație faptului că numele câmpului email și cel al parametrului email sunt identice, este suficient să scriem o singură dată email, în loc de email: email.

Crearea de instanțe din alte instanțe utilizând sintaxa de actualizare a structurii

Adeseori este util să generezi o nouă instanță a unei structuri care păstrează majoritatea valorilor provenite din altă instanță, dar modifică câteva dintre ele. Aceasta se poate realiza utilizând sintaxa de actualizare a structurii.

Pentru început, în Listarea 5-6, ilustrăm cum să creăm o nouă instanță User în user2, fără a folosi sintaxa de actualizare. Atribuim o nouă valoare pentru email, dar pentru restul valorilor, le păstrăm pe cele din user1, pe care l-am creat în Listarea 5-2.

Numele fișierului: src/main.rs

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

Listarea 5-6: Crearea unei noi instanțe de tip 'User', folosind o valoare din 'user1'

Utilizând sintaxa de actualizare a structurii, putem atinge același rezultat cu un cod mult mai concis, așa cum se arată în Listarea 5-7. Sintaxa .. indică faptul că toate celelalte câmpuri care nu au fost explicit stabilite trebuie să aibă valorile identice cu cele din instanța sursă.

Numele fișierului: src/main.rs

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

fn main() {
    // --snip--

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

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

Listing 5-7: Using struct update syntax to set a new email value for a User instance but to use the rest of the values from user1

Codul prezentat în Listarea 5-7 generează de asemenea o instanță în user2, care are o valoare distinctă pentru email, dar păstrează aceleași valori pentru câmpurile username, active și sign_in_count ca în user1. Elementul ..user1 trebuie poziționat la final pentru a indica faptul că orice alt câmp rămas ar trebui să își preia valorile de la câmpurile corespondente din user1. În același timp, ne este permis să stabilim valorile pentru oricâte câmpuri dorim, fără a fi impusă vreo ordine, indiferent de succesiunea câmpurilor în cadrul definiției structurii.

Este important de remarcat faptul că sintaxa de actualizare a structurilor utilizează = la fel ca într-o atribuire; acest lucru se produce deoarece datele sunt permutate, așa cum am observat în secțiunea “Variabile și interacționarea cu date folosind permutarea”. În acest exemplu, după ce am creat user2, nu mai putem folosi în totalitate user1 deoarece string-ul din câmpul username al user1 a fost permutat în user2. Dacă am fi atribuit user2 noi valori de string atât pentru email cât și pentru username, utilizând astfel doar valorile active și sign_in_count de la user1, atunci user1 ar fi rămas valid după crearea user2. Atât active cât și sign_in_count sunt tipuri care implementează trăsătura Copy, astfel comportamentul de care am discutat în secțiunea “Date doar pe stivă: trăsătura Copy” va fi aplicabil.

Utilizarea structurilor tuplă fără câmpuri denumite pentru a genera tipuri diferite

Rust suportă de asemenea structuri care se aseamănă cu tuplele, denumite structuri tuplă. Acestea îmbogățesc semnificația pe care o conferă numele structurii, deși nu dispun de nume asociate câmpurilor lor; în loc, acestea sunt definite doar prin tipurile câmpurilor. Structurile tuplă sunt utile atunci când dorești să atribui un nume întregii tuple, configurându-l ca un tip distinct față de alte tuple, precum și atunci când ar fi redundant să denumești fiecare câmp, așa cum s-ar întâmpla într-o structură obișnuită.

Pentru a defini o structură tuplă, începeți cu cuvântul-cheie struct, urmat de numele structurii și de tipurile componente ale tuplei. De exemplu, în continuare definim și folosim două structuri tuplă, denumite Color și Point:

Numele fișierului: src/main.rs

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

Observă că black și origin sunt de tipuri diferite, deoarece reprezintă instanțe ale unor structuri tuplă distincte. Fiecare structură pe care o definești în program constituie un tip inedit, chiar dacă toate câmpurile acelei structuri au același tip. De exemplu, o funcție care necesită un argument de tip Color nu va putea primi un Point ca și parametru, chiar dacă ambele tipuri sunt formate din trei valori i32. La fel ca și în cazul tuplă, la structurile tuplă avem posibilitatea de a le descompune în elementele individuale și putem accesa o anumită valoare folosind un . urmat de indexul respectiv.

Structuri asemănătoare cu unit, fără niciun câmp

Poate vei fi surprins, dar este posibil să definești și structuri care nu includ niciun câmp! Acestea se numesc structuri asemănătoare cu unit (unit-like structs) deoarece comportamentul lor este similar cu cel al (), tipul unit pe care l-am menționat în secțiunea dedicată Tipul tuplă. Asemenea structuri pot dovedi a fi utile când ai nevoie să implementezi o trăsătură pe un anumit tip, dar concomitent nu ai nicio dată pe care dorești să o stochezi direct în tipul respectiv. Ne vom dedica mai mult acestui concept de trăsătură în Capitolul 10. Ca exemplu, iată cum poți declara și instanția o structură asemănătoare cu unit, pe care o vom numi AlwaysEqual:

Numele fișierului: src/main.rs

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Pentru a defini structura AlwaysEqual, utilizăm cuvântul cheie struct, urmat de numele ales de noi și semnul punct și virgulă. Nu este necesar să folosim paranteze sau acolade! Ulterior, putem obține o instanță a structurii AlwaysEqual în variabila subject prin intermediu unui proces similar: utilizând numele definit de noi, în absența oricăror paranteze sau acolade. Concepe următorul scenariu: la un moment dat, vom implementa o funcționalitate pentru acest tip, astfel încât orice instanță a AlwaysEqual să fie considerată egală cu orice instanță a altui tip, aceasta urmând să fie folosită probabil pentru a obține un rezultat standard în cazul unor teste. Pentru a implementa această funcționalitate, nu ne va fi nevoie de nicio informație suplimentară! În Capitolul 10 vei afla cum se definesc trăsăturile și cum acestea pot fi implementate pe orice tip, inclusiv pe structurile asemănătoare cu unit.

Proprietatea datelor din cadrul unei structuri

În definiția structurii User prezentată în Listarea 5-1, am optat pentru folosirea tipului String, care reprezintă un string deținut, în locul tipului de secțiune de string &str. Aceasta nu este o decizie la întâmplare, obiectivul nostru fiind ca fiecare instanță a respectivei structuri să dețină întreaga sa colecție de date, dată ce vor rămâne valabile atât timp cât structura în sine este în vigoare.

De asemenea, structurile pot stoca referințe către date deținute de alte elemente, dar pentru asta este necesară utilizarea duratelor de viață, o caracteristică specifică limbajului Rust pe care o vom detalia în Capitolul 10. Duratele de viață garantează că datele referențiate de o structură rămân valabile pe întreaga durată de existență a structurii. Să presupunem că dorești să stochezi o referință într-o structură fără a indica duratele de viață, exact ca în exemplul următor; vei constata că acest lucru nu este posibil:

Numele fișierului: src/main.rs

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

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

Compilatorul va semnala eroare, solicitând specificatori pentru durata de viață:

$ 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` due to 2 previous errors

În Capitolul 10, vom discuta cum putem rezolva aceste erori pentru a stoca referințe în structuri. Până atunci însă, vom remedia astfel de erori prin folosirea tipurilor ce se află sub posesiunea noastră, precum String, în locul referințelor de tip &str.

Un program exemplu ce utilizează structurile

Pentru a înțelege când și cum ne-ar fi util să utilizăm structurile, propunem să dezvoltăm împreună un program care calculează aria unui dreptunghi. Vom începe construind acest program cu ajutorul unor variabile simple și apoi ne vom concentra pe îmbunătățirea și refactorizarea lui prin utilizarea structurilor.

Să creăm un nou proiect binar cu Cargo, numit rectangles. Scopul acestui program va fi de a prelua lățimea și înălțimea unui dreptunghi, specificate în pixeli, și de a calcula aria acestuia. Listarea 5-8 ne arată un exemplu de program scurt care realizează exact acest lucru, modelul fiind implementat în fișierul src/main.rs al proiectului nostru.

Numele fișierului:: src/main.rs

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

Listarea 5-8: Calculul ariei unui dreptunghi, definit prin variabile separate pentru lățime și înălțime

Acum, execută acest program utilizând cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

Deși codul calculează corect aria dreptunghiului, invocând funcția area cu fiecare dimensiune, acest lucru poate fi îmbunătățit pentru a crea un cod mai clar și mai lizibil.

Neclaritatea acestui cod devine evidentă atunci când ne uităm la semnătura funcției area:

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

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

Funcția area este destinată calculării ariei unui dreptunghi. Totuși, funcția pe care noi am redactat-o are doi parametri, și în niciun loc din programul nostru nu se menționează explicit faptul că acești parametri sunt interconectați. Ameliorarea lizibilității și gestionării codului s-ar putea realiza prin gruparea înălțimii și lățimii. Un astfel de procedeu a fost deja discutat în secțiunea “Tipul Tuplă”, din Capitolul 3, prin utilizarea tuplelor.

Refactorizarea prin utilizarea tuplelor

Lista 5-9 ilustrează o nouă variantă a programului nostru, în care am integrat utilizarea tuplelor.

Numele fișierului:: src/main.rs

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

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

Listarea 5-9: Definirea lățimii și înălțimii dreptunghiului prin intermediul unei tuple

Acest program, privit dintr-o anumită perspectivă, este mai eficient. Prin utilizarea tuplelor, adăugăm o structură și trimitem un singur argument. Totuși, acestă abordare este mai puțin clară: elementele unei tuple nu sunt denumite, astfel că trebuie să indexăm părțile tuplei, ceea ce face ca procesul de calcul să devină mai greu de înțeles.

Dacă am confunda lățimea cu înălțimea nu ar avea un impact semnificativ asupra calculării ariei, dar în cazul în care am dori să reprezentăm dreptunghiul pe un ecran, atunci acest lucru ar conta! Ar trebui să ne amintim că width (lățimea) este indexul 0 al tuplei, iar height (înălțimea) este indexul 1. Aceasta ar putea fi un lucru greu de înțeles și de reținut de către o altă persoană care ar urma să utilizeze codul nostru. Deoarece nu am transmis semnificația datelor în codul nostru, introducerea erorilor devine acum mult mai ușoară.

Refactorizarea folosind structuri: Introducerea unui sens mai amplu

Folosim structurile pentru a adăuga mai mult sens datelor prin etichetarea acestora. Avem posibilitatea de a transforma tupla pe care o utilizăm într-o structură, acordând un nume atât pentru întreg, cât și pentru părțile acesteia. Acest lucru este ilustrat în Listarea 5-10.

Numele fișierului:: src/main.rs

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

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

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

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

Listarea 5-10: Crearea structurii Rectangle

În acest fragment de cod, am definit o structură numită Rectangle. În cadrul acoladelor, am precizat câmpurile acesteia: width (lăţime) şi height (înălţime), ambele de tipul u32. Apoi, în funcția main, am inițiat o instanță specifică Rectangle cu o lăţime de 30 şi o înălţime de 50.

Acum, funcţia noastră area este definită având un singur parametru numit rectangle, de tip împrumut imutabil al unei instanţe Rectangle. După cum am menţionat anterior în Capitolul 4, dorim să împrumutăm structura mai degrabă decât să îi preluăm total posesiunea. Astfel, funcţia main îşi păstrează posesiunea şi poate continua să utilizeze rect1, motiv pentru care utilizăm & în semnătura funcţiei şi la apelarea acesteia.

Funcţia area accesează câmpurile width şi height ale instanţei Rectangle. Notăm că accesul la câmpurile unei instanţe împrumutate nu permută valorile acestor câmpuri, acesta fiind motivul pentru care în cod Rust deseori vedem structuri anume împrumutate. Semnătura actuală a funcţiei area exprimă în mod precis intenţia noastră: de a calcula aria lui Rectangle utilizând câmpurile sale width și height. Acest lucru subliniază relaţia dintre lăţime şi înălţime şi le conferă nume descriptive, în locul folosirii valorilor de index ale tuplei 0 şi 1, implicând un câştig semnificativ în ceea ce priveşte claritatea.

Îmbunătățirea funcționalității prin folosirea de trăsături derivate

Ne-ar fi de folos să putem afișa o instanță a Rectangle în timp ce depanăm programul, vizualizând valorile tuturor câmpurilor sale. În Listarea 5-11, încercăm să utilizăm macro-ul println!, așa cum am făcut în capitolele anterioare. Totuși, aceasta nu va funcționa.

Numele fișierului:: src/main.rs

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

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

    println!("rect1 is {}", rect1);
}

Listare 5-11: Tentativa de a afișa o instanță de Rectangle

Atunci când rulăm procesul de compilare pentru acest cod, obținem o eroare ce conține următorul mesaj principal:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

Macroul println! are capacitatea de a realiza diferite formate de afișare. În mod implicit, acoladele indică faptul că println! ar trebui să utilizeze un tip de formatare numit Display, care reprezintă o ieșire destinată direct consumului de către utilizatorul final. Tipurile primitive pe care le-am întâlnit până acum implementează Display în mod automat, deoarece există o singură modalitate în care ai dori să arăți un 1 sau orice alt tip primitiv unui utilizator. Însă, în cazul structurilor, modul în care println! ar trebuie să formateze ieșirea este mai puțin evident, existând numeroase variante de afișare: vrei să se utilizeze virgule sau nu? Dorești ca acoladele să fie afișate? Ar trebui toate câmpurile să fie vizibile? Din cauza acestor incertitudini, Rust nu încearcă să presupună intențiile noastre, astfel că structurile nu au o implementare predefinită a Display pentru utilizare cu println! și substituentul {}.

Dacă vom urmări în continuare mesajele de eroare, vom descoperi o notă foarte utilă:

   = help: the trait `std::fmt::Display` is not implemented for `Rectangle`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead

Să încercăm acest lucru! Acum, apelul macro println! ar urma să arate astfel: println!("rect1 este {:?}", rect1);. Prin adăugarea specificatorului :? în interiorul acoladelor, îi indicăm macro-ului println! că dorim să utilizăm un format de afișare numit Debug. Trăsătura Debug ne oferă capacitatea de a afișa structura noastră într-un mod care este eficient pentru dezvoltatori, permițându-ne să vizualizăm valoarea acesteia în timp ce lucrăm la depanarea codului.

Încearcă să compilezi codul cu această modificare. Drăcie! Încă o eroare:

error[E0277]: `Rectangle` doesn't implement `Debug`

Dar, din nou, compilatorul ne oferă o sugestie utilă:

   = help: the trait `Debug` is not implemented for `Rectangle`
   = note: add `#[derive(Debug)]` to `Rectangle` or manually `impl Debug for Rectangle`

Rust dispune de funcționalitatea de a afișa informații pentru depanare, dar pentru a face această funcționalitate disponibilă structurii noastre, trebuie să optăm în mod explicit. Putem face asta prin adăugarea atributului extern #[derive(Debug)] imediat înainte de definiția structurii, așa cum este ilustrat în Listarea 5-12.

Numele fișierului:: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

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

    println!("rect1 is {:?}", rect1);
}

Listarea 5-12: Incorporarea atributului pentru a deriva trăsătura Debug și afișarea instanței Rectangle prin intermediul formatării de depanare

La rularea programului, acum nu vom întâlni nici o eroare, iar rezultatul arată astfel:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

Excelent! Rezultatul nu este cel mai estetic, dar afișează valorile tuturor câmpurilor pentru instanța dată, ceea ce cu siguranță ne este de folos în timpul depanării. Când lucrăm cu structuri mai complexe, este util să obținem un rezultat mai ușor de analizat; în acele cazuri, putem aplica {:#?} în loc de {:?} in interiorul string-ului println!. De exemplu, folosirea stilului {:#?} va produce următorul rezultat:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

Un alt mod de a afișa o valoare utilizând formatul Debug este prin intermediul macro-ului dbg!. Acesta preia în posesiune o anumită expresie (în contradicție cu println!, care folosește o referință), afișează fișierul și linia de cod unde macro-ul dbg! este apelat în programul tău, împreună cu rezultatul acelei expresii, după care restituie posesiunea valorii.

Notă: Apelarea macro-ului dbg! afișează informațiile în fluxul standard de erori (stderr), spre deosebire de println!, care afișează în fluxul standard de ieșire (stdout). Vom vorbi mai mult despre stderr și stdout în secțiunea „Scrierea mesajelor de eroare la fluxul standard de erori în loc de fluxul standard de ieșire” din Capitolul 12.

Iată un exemplu în care ne interesează valoarea atribuită câmpului width, precum și valoarea întregii structuri numită 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);
}

Putem înconjura expresia 30 * scale cu dbg! și, din moment ce dbg! ne redă posesiunea valorii expresiei, câmpul width va primi aceeași valoare ca și în cazul în care nu am fi apelat dbg!. Nu dorim ca dbg! să preia posesiunea asupra rect1, astfel încât utilizăm o referință la rect1 în următorul apel. Iată cum se prezintă rezultatul acestui exemplu:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10] 30 * scale = 60
[src/main.rs:14] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

Putem observa că primul fragment de output provine de la src/main.rs, linia 10, unde depanăm expresia 30 * scale. Valoarea rezultată este 60, având în vedere că formatarea Debug pentru numerele întregi este realizată prin afișarea exclusivă a valorilor acestora. Apelul dbg! de pe linia 14 din src/main.rs afișează valoarea &rect1, care reprezintă structura Rectangle. Acest output utilizează o formatare frumoasă, Debug, specifice tipului Rectangle. Macro-ul dbg! poate fi foarte util atunci când încerci să înțelegi ce face codul tău!

Pe lângă trăsătură Debug, Rust ne oferă numeroase trăsături pe care le putem folosi cu atributul derive. Acestea pot adăuga comportamente utile tipurilor noastre. Trăsăturile date și comportamentele lor se găsesc în Anexa C. Vom discuta în Capitolul 10 modul de implementare a acestor trăsături cu funcționalitate particularizată, dar și modul de creare a propriilor trăsături. De asemenea, există și alte atribute în afară de derive; pentru mai multe informații, vezi secțiunea "Atribute".

Funcția noastră area este foarte specifică. Aceasta calculează doar ariile dreptunghiurilor. Ar fi benefic să legăm mai strâns acest comportament de structura noastră Rectangle, având în vedere faptul că nu funcționează cu niciun alt tip. Să vedem cum putem continua să îmbunătățim acest cod, transformând funcția area într-o metodă area definită pe tipul nostru Rectangle.

Sintaxa pentru metode

Metodele sunt similare cu funcțiile. Le definim folosind cuvântul-cheie fn, urmat de un nume. Metodele pot avea parametri și pot returna o valoare, exact ca funcțiile. De asemenea, ele conțin un bloc de cod care este executat atunci când metoda este invocată de undeva.

Totuși, există o diferență importantă: spre deosebire de funcții, metodele sunt definite în cadrul unei structuri (sau a unei enumerări ori a unui obiect de tip trăsătură, subiecte pe care le vom aborda în Capitolul 6 și Capitolul 17, respectiv). Primul lor parametru este întotdeauna self, care reprezintă instanța curentă a structurii pe care este invocată metoda.

Definirea metodelor

Vom modifica funcția area care primește o instanță Rectangle ca parametru și vom crea o metodă area, definită direct pe structura Rectangle. Această modificare este prezentată în Listarea 5-13.

Numele fișierului: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

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

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

Listarea 5-13: Definirea metodei area asociate cu structura Rectangle

Pentru a adăuga funcția în cadrul Rectangle, vom începe prin a iniția un bloc de implementare impl specific pentru Rectangle. Orice element care va fi inclus în acest bloc impl va fi asociat direct cu tipul Rectangle. Apoi, funcția area trebuie să fie mutată în interiorul acoladelor blocului impl. Primul parametru (unicul, în acest caz) va deveni self, atât în semnătura funcției, cât și în corpul acesteia. În funcția main, unde anterior funcția area era apelată cu rect1 ca argument, vom utiliza în schimb sintaxa metodei. Astfel, metoda area va fi apelată direct pe instanța Rectangle. Sintaxa metodei intervine după instanță: adăugăm un punct, urmat de numele metodei, paranteze și oricare argumente necesare.

În semnătura pentru funcția area, am preferat să folosim &self în loc de rectangle: &Rectangle. De fapt, &self nu este altceva decât o formă prescurtată a expresiei self: &Self. În cadrul unui bloc impl, Self denotă tipul pentru care este destinat blocul impl. Orice metodă trebuie să aibă un parametru denumit self de tipul Self ca primul său parametru. Rust ne permite să simplificăm aceasta folosind doar termenul self ca prim parametru. Este important de remarcat că & trebuie să precedă scurtătura self pentru a indica faptul că această metodă împrumută instanța Self, exact cum am procedat în rectangle: &Rectangle. Metodele pot lua posesia self, pot împrumuta self în mod imutabil, cum este cazul de față, sau pot împrumuta self în mod mutabil, exact ca în cazul oricărui alt parametru.

Am optat pentru &self din același motiv pentru care am folosit &Rectangle în cazul funcției: nu dorim să preluăm posesiunea și aspirăm să citim doar datele din structură, nu și să scriem în aceasta. Dacă intenția noastră ar fi fost să modificăm instanța pe care am invocat-o în cadrul metodei, am fi folosit &mut self ca prim parametru. Este destul de neobișnuit să avem o metodă care preia posesiunea instanței folosind doar self ca prim parametru. În mod obișnuit, ne folosim de acest procedeu când metoda transformă self în ceva diferit, iar scopul nostru este de a împiedica autorul apelului să folosească instanța originală după finalizarea transformării.

Motivul principal de a opta pentru metode în detrimentul funcțiilor, dincolo de a oferi sintaxa metodei și de a evita repetarea tipului self în fiecare semnătură a metodei, este legat de organizare. Practic, am concentrat într-un singur bloc impl tot ceea ce putem realiza cu o instanță a unui anumit tip. Astfel, nu obligăm viitorii utilizatori ai codului nostru să caute capacitățile Rectangle împrăștiate în diverse colțuri ale bibliotecii pe care o furnizăm.

Trebuie să reții că avem libertatea de a denumi o metodă identic cu unul dintre câmpurile structurii. De exemplu, putem defini o metodă în structura Rectangle și o putem numi tot width:

Numele fișierului: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

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

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

În acest caz, optăm să configurăm metoda width astfel încât să returneze true dacă valoarea din câmpul width al instanței este mai mare decât 0 și false în caz contrar, când valoarea este 0. Este important de subliniat faptul că avem libertatea de a utiliza un câmp în cadrul unei metode cu același nume, în funcție de necesități. De exemplu, în funcția main, atunci când denumirea rect1.width este urmată de paranteze, compilatorul Rust înțelege că ne referim la metoda width. În schimb, în absența parantezelor, Rust interpretează că ne referim la câmpul width.

Deși nu este întotdeauna cazul, frecvent, atunci când atribuim unei metode același nume cu un câmp, intenția este ca aceasta să returneze exclusiv valoarea din acel câmp, fără a efectua alte operații. Asemenea metode sunt denumite getteri. Este important de subliniat faptul că, spre deosebire de unele limbaje de programare, Rust nu generează în mod automat asemenea getteri pentru câmpurile structurilor. Getterii se dovedesc a fi utili deoarece permit transformarea câmpului într-unul privat și a metodei într-una publică, oferind astfel accesul în regim doar-de-citire a acelui câmp, rol ce intră în alcătuirea API-ului public al tipului respectiv. Conceptele de public și privat, precum și modalitatea de a desemna un câmp sau o metodă ca fiind publice sau private, vor fi detaliate în Capitolul 7.

Care este echivalentul operatorului -> în Rust?

În limbajele de programare C și C++, sunt folosiți doi operatori diferiți pentru apelarea metodelor: se utilizează . atunci când metoda este apelată direct pe obiect, iar -> este folosit dacă metoda este apelată pe un pointer către obiect, caz în care este necesar să se realizeze o dereferențiere a pointerului. Adică, dacă object este un pointer, atunci object->something() este similar cu (*object).something().

Rust nu are un echivalent direct pentru operatorul ->. În schimb, oferă o caracteristică numită referențiere și dereferențiere automată. Această caracteristică este aplicată în contextul apelării metodelor, unul dintre puținele locuri în Rust unde se întâmplă acest lucru.

Iată cum funcționează: când apelezi o metodă cu object.something(), Rust include automat operatorii &, &mut, sau * pentru a se asigura că object corespunde semnăturii metodei. Așadar, următoarele două apeluri de metode sunt echivalente:

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

Primul mod de apelare pare mult mai elegant. Acest procedeu de referențiere automată este posibil datorită faptului că metodele au un receptor distinct - tipul self. Cunoscând receptorul și numele unei metode, Rust poate deduce cu precizie dacă metoda este de citire (&self), modificare (&mut self), sau consumă (self) receptorul. Aceasta abordare implicită de împrumutare pentru receptorii de metode contribuie semnificativ la eficiența posesiunii în practică.

Metode cu parametri multipli

Să ne familiarizăm mai bine cu metodele prin crearea unei a doua metode în structura Rectangle. În acest caz, vrem ca o instanță a Rectangle să poată primi o altă instanță de Rectangle și să returneze true dacă al doilea Rectangle poate fi încorporat integral în interiorul primului (self); în caz contrar, ar trebui să returneze false. Mai pe scurt, după ce am definit metoda can_hold, dorim să fim în măsură să scriem programul prezentat în Listarea 5-14.

Numele fișierului: src/main.rs

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Listarea 5-14: Apelarea metodei încă nedefinite can_hold

Avem următoarea ieșire anticipată, deoarece dimensiunile rect2 sunt mai mici decât cele ale lui rect1, pe când rect3 este mai lat decât rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Știm că intenționăm să definim o metodă, așadar aceasta se va găsi în blocul impl Rectangle. Metoda se va numi can_hold, iar ca parametru va prelua un împrumut imutabil către un alt Rectangle. Tipul parametrului este deducibil inspectând codul care apelează metoda: rect1.can_hold(&rect2) transmite &rect2, adică un împrumut imutabil către rect2, o instanță a Rectangle. Acest lucru este logic, de vreme ce avem nevoie doar să citim rect2, nu să-l și scriem (în acest ultim caz, am avea nevoie de un împrumut mutabil). Mai mult, dorim ca main să-și păstreze posesiunea asupra rect2, pentru a putea folosi din nou instanța după ce apelăm metoda can_hold. Valoarea returnată de can_hold va fi de tip Boolean, iar implementarea va verifica dacă atât lățimea, cât și înălțimea instanței self, sunt mai mari decât cele corespunzătoare altui Rectangle. Acum putem adăuga noua metodă can_hold în blocul impl extras din Lista 5-13, și prezentat în Lista 5-15.

Numele fișierului: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Listarea 5-15: Implementăm metoda can_hold pentru Rectangle, aceasta acceptând o altă instanță Rectangle ca argument

Atunci când rulăm acest cod împreună cu funcția main prezentată în Listarea 5-14, obținem rezultatul scontat. Metodele pot accepta mai mulți parametri, pe care îi adăugăm în semnătură după parametrul self. Acești parametri se comportă exact ca parametrii standard din funcții.

Funcții asociate

Toate funcțiile care sunt definite în interiorul unui bloc impl poartă denumirea de funcții asociate, deoarece sunt legate de tipul ce este indicat după impl. Avem posibilitatea de a defini funcții asociate care nu au self drept prim parametru (acestea, prin urmare, nu sunt metode), întrucât nu necesită o instanță a respectivului tip pentru a putea funcționa. Deja am întâlnit o funcție de acest fel: funcția String::from, care este definită pentru tipul String.

Funcțiile asociate care nu sunt metode sunt frecvent utilizate în rol de constructori, aceștia având menirea de a returna o nouă instanță a unei structuri. În mod obișnuit, acestea poartă numele de new, dar new nu este un nume special sau implicit în limbaj. De exemplu, am putea opta să oferim o funcție asociată sub numele de square (pătrat), care să aibă un singur parametru ce reprezintă dimensiunea, utilizând-o atât pentru lățime, cât și pentru înălțime, simplificând astfel procesul de creare a unui dreptunghi Rectangle pătrat, fără a fi nevoie să introducem aceeași valoare de două ori.

Numele fișierului: 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);
}

Cuvintele cheie Self, prezente atât în tipul de retur, cât și în corpul funcției, reprezintă alias-uri pentru tipul care urmează după cuvântul cheie impl. În acest context, acest tip este Rectangle.

Pentru a invoca această funcție asociată, utilizăm sintaxa :: împreună cu numele structurii. De exemplu, let sq = Rectangle::square(3);. Această funcție este asociată unui spațiu de nume definit de structura respectivă: sintaxa :: este folosită în ambele situații, atât pentru funcțiile asociate, cât și pentru spațiile de nume generate de module. Vom aborda subiectul modulelor în detaliu în Capitolul 7.

Multiple blocuri impl

Fiecare structură are permisiunea de a avea mai multe blocuri impl. De exemplu, codul din Listarea 5-15 corespunde cu cel prezentat în Listarea 5-16, unde fiecare metodă este separată în propriul său bloc impl.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Listarea 5-16: Rescrierea Listării 5-15 utilizând mai multe blocuri impl

Deși în acest context nu există un motiv anume pentru a separa aceste metode în diverse blocuri impl, este important de menționat că aceasta este o sintaxă validă. Vom întâlni un caz de utilizare util pentru multiple blocuri impl în Capitolul 10, unde vom discuta despre tipurile generice și trăsături.

Sumar

Structurile permit crearea tipurilor personalizate relevante pentru domeniul în care lucrezi. Folosind structurile, poți menține conexiuni între diverse date asociate și le poți numi pe fiecare în parte, astfel încât codul tău să fie mai clar. În blocurile impl, poți defini funcții care sunt legate de tipul tău și metodele, care sunt un fel de funcții asociate și care îți permit să definești comportamentul pe care instanțele structurilor tale îl au.

Totuși, structurile nu sunt singura metodă de a crea tipuri personalizate: să ne îndreptăm atenția către caracteristica enum a limbajului Rust pentru a adăuga un nou instrument în trusa ta de unelte.

Enumerări și potrivirea modelelor

În cadrul acestui capitol, ne vom concentra asupra enumerărilor, sau cum sunt ele numite în mod obișnuit, enum. Enum-urile ne oferă posibilitatea de a defini un tip prin enumerarea variantelor sale posibile. Vom începe prin a defini și utiliza un enum pentru a ilustra cum putem încorpora atât sens, cât și date în cadrul unui enum. Ulterior, vom explora un exemplu specific de enum, numit Option, care exprimă ideea că o valoare poate reprezenta fie ceva, fie nimic. În continuare, vom analiza cum potrivirea modelelor în cadrul expresiei match ne facilitează posibilitatea de a executa diferite bucăți de cod, în funcție de valorile diferite pe care le poate lua un enum. În final, vom discuta despre cum construcția if let reprezintă un alt instrument convenabil și concis pe care îl avem la dispoziție pentru a manipula enum-urile în codul nostru.

Definirea unei enumerări

Structura de control match

Rust dispune de o structură de control extrem de puternică numită match, care permite compararea unei valori cu o serie de șabloane și executarea codului în funcție de șablonul care se potrivește. Șabloanele pot fi realizate din valori literale, nume de variabile, wildcard-uri și multe altele. Capitolul 18 acoperă toate aspectele referitoare la șabloane și funcționalitatea acestora. Puterea lui match vine din expresivitatea șabloanelor și faptul că compilatorul verifică dacă toate cazurile posibile sunt gestionate.

O expresie match poate fi înțeleasă ca o mașină de sortat monede: monedele alunecă pe o pistă cu găuri de diferite mărimi iar fiecare monedă cade prin prima gaură în care se încadrează. Similar, valorile parcurg fiecare șablon într-un match, iar la primul șablon unde valoarea se "potrivește", ea este redirecționată în blocul de cod asociat pentru a fi utilizat în timpul execuției.

Luând exemplul monedelor, putem crea o funcție care primește o monedă necunoscută din SUA și, asemenea mașinii de numărat, determină tipul monedei și returnează valoarea acesteia în cenți, așa cum se arată în Listarea 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() {}

Listarea 6-3: O enumerare și o expresie match ce include variantele enum ca șabloane

Să analizăm match în funcția value_in_cents. Începând, scriem cuvântul-cheie match urmat de o expresie, în acest caz, valoarea coin. Aceasta poate părea similară cu o expresie condițională folosită împreună cu if, dar există o diferență semnificativă: dacă în cazul if condiția trebuie să evalueze o valoare Booleană, aici, poate fi orice tip. coin în acest exemplu este enum-ul Coin pe care l-am definit în prima linie.

Apoi, avem ramurile match. Fiecare ramură conține două părți: un șablon și un cod. Prima ramură are un șablon care corespunde valorii Coin::Penny și apoi operatorul => care separă șablonul de codul care trebuie executat. În acest caz, codul este doar valoarea 1. Fiecare ramură este separată de cea următoare printr-o virgulă.

Când expresia match se execută, valoarea rezultată se compară cu șablonul fiecărei ramuri, în ordine. Dacă un șablon corespunde valorii, codul asociat cu acel șablon este executat. Dacă șablonul nu se potrivește valorii, execuția continuă la următoarea ramură, similar cu mașina de sortat monede. Putem avea câte ramuri dorim: în Listarea 6-3, match-ul nostru are patru ramuri.

Codul asociat fiecărei ramuri este o expresie, iar valoarea rezultată din expresia ramurii care se potrivește este returnată pentru întreaga expresie match.

Nu folosim, de regulă, acolade dacă codul ramurii match este scurt, așa cum se vede în Listarea 6-3, unde fiecare ramură returnează doar o valoare. Dacă dorești să execuți mai multe linii de cod într-o ramură match, trebuie să folosești acolade, iar virgula care urmează ramurii devine atunci opțională. De exemplu, în codul de mai jos textul "Penny norocos!" este afișat de fiecare dată când metoda este apelată cu Coin::Penny, totuși, ultima valoare a blocului, 1, este returnată:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Șabloane ce se leagă de valori

O altă particularitate valoroasă a segmentelor match este că ele pot încorpora elementele valorilor care corespund cu șablonul definit. Exact în acest mod putem desprinde valori din variantele unei enumerări.

Pentru exemplificare, modificăm una dintre variantele enumerării noastre, astfel încât să cuprindă date. În perioada 1999 - 2008, Statele Unite ale Americii au emis monede "quarter" personalizate, cu design-uri distincte pentru fiecare dintre cele 50 de state. Niciun alt tip de monedă nu a primit acest tratament special, de aceea doar "quarter"-urile au această extra valoare. Putem îngloba această informație în enumerarea noastră prin modificarea variantei Quarter, astfel încât să includă o valoare UsState în interiorul ei, așa cum am făcut în Listarea 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

Listare 6-4: O enumerare Coin în care și varianta Quarter deține o valoare UsState

Să presupunem că un prieten se străduiește să colecționeze monedele "quarter" pentru toate cele 50 de state. În timp ce noi sortăm restul de monede după tip, vom menționa și numele statului asociat cu fiecare "quarter", astfel încât, dacă este una pe care prietenul nostru nu o deține, să o poată adăuga în colecția sa.

În expresia match pentru acest segment de cod, adăugăm o variabilă numită state la șablon, care se potrivește cu valorile variantei Coin::Quarter. Când un Coin::Quarter se potrivește, variabila state se va lega de valoarea statului respectivului "quarter". Apoi putem utiliza state în codul specfic acelui segment din match, astfel:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {:?}!", state);
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

Dacă am apela value_in_cents(Coin::Quarter(UsState::Alaska)), coin ar fi Coin::Quarter(UsState::Alaska). Când comparam valoarea aceasta cu fiecare segment al match-ului, niciunul nu se potrivește până la segmentul Coin::Quarter(state). În acest punct, legătura pentru state va fi valoarea UsState::Alaska. Putem folosi apoi acea legătură în expresia println!, extrăgând astfel valoarea internă a statului din varianta "Quarter" din enumerarea Coin.

Corelarea cu Option<T>

În secțiunea precedentă, am aspirat să extragem valoarea internă T din variantă Some, folosind structura Option<T>. În ciuda schimbării obiectului de la enum Coin la Option<T>, funcționarea expresiei match rămâne neschimbată.

Consideră că avem nevoie de o funcție care acceptă ca parametru o structură Option<i32>. Rolul ei este de a adaugă 1 la valoarea conținută, dacă aceasta există. În caz negativ, funcția nu ar trebui să execute nicio operație și să returneze None.

Având la dispoziție expresia match, implementarea funcției devine extrem de simplă și intuitivă, asemenea exemplelor prezentate în Lista 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);
}

Listarea 6-5: O funcție care utilizează o expresie match pe variabila Option<i32>

Să examinăm cu mai multă atenție prima execuție a plus_one. Atunci când invocăm plus_one(five), variabila x din interiorul funcției plus_one va primi valoarea Some(5). Aceasta este apoi comparată cu fiecare ramură din instrucțiunea 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);
}

Valoarea Some(5) nu corespunde modelului None, așa că trecem mai departe la următoarea ramură:

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

Se potrivește Some(5) cu Some(i)? Chiar se potrivește! Avem aceeași variantă. Simbolul i se leagă apoi de valoarea stocată în Some, astfel că i devine 5. Codul din această ramură match este executat, deci adăugăm 1 la valoarea lui i și producem o nouă valoare Some care încapsulează rezultatul nostru, 6.

Analizăm acum a doua apelare a funcției plus_one din Listarea 6-5, unde x este None. Pătrundem în interiorul match pentru a compara cu prima ramură:

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

Într-adevăr, se potrivește! Nu există o valoare la care să adăugăm, așadar programul încetează și returnează valoarea None aflată în partea dreaptă a =>. De vreme ce prima ramură s-a potrivit, nicio altă ramură nu va mai fi evaluată.

Folosirea împreună a match și a enumerărilor este extrem de utilă în numeroase situații. Astfel de constructe îți vor fi familiare în lucrul tău cu Rust: match asociat unui enum, creare de legături cu o variabilă către datele interne și apoi execuția codului în funcție de aceasta. Deși poate părea complex la început, pe măsură ce te obișnuiești cu acesta, vei începe să îți dorești ca acesta să fie disponibil în toate limbajele de programare. Nu întâmplător este unul dintre cele mai îndrăgite caracteristici ale limbajului de către comunitatea de utilizatori.

Corelările de tip match sunt exhaustive

Mai există un aspect important legat de sintaxa match: șabloanele asociate fiecărei ramuri din match trebuie să acopere toate scenariile posibile. Să luăm în considerare o versiune modificată a funcției noastre plus_one, care conține o eroare și, prin urmare, nu va reuși să compileze:

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

Am omis gestionarea cazului None, deci acest cod implicit va conține o eroare. Din fericire, aceasta este o eroare pe care Rust o poate identifica. Dacă încercăm să compilăm acest cod, vom întâmpina următoarea eroare:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:518:1
  |
  = note: 
/rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:522:5: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` due to previous error

Rust e conștient că nu am cuprins fiecare scenariu posibil și indică inclusiv șablonul pe care l-am omis! Corelările de șabloane din Rust sunt exhaustive: trebuie să epuizăm fiecare posibilitate pentru ca codul să fie considerat valid. În special în cazul Option<T>, atunci când Rust ne împiedică să trecem cu vederea cazul None, ne protejează de a face presupuneri incorecte - că avem o valoare, când de fapt ne-am putea confrunta cu o valoare null. Astfel, se evită genul de eroare costisitoare pe care l-am discutat mai devreme.

Șabloane universale și substituentul _

Prin intermediul enumerărilor, putem declanșa acțiuni specifice pentru unele valori speciale, dar pentru restul valorilor vom adopta o acțiune prestabilită. Imaginați-vă că implementăm un joc în care, dacă la o aruncare de zar iese 3, jucătorul nu se mișcă, ci primește o pălărie nouă și elegantă. Dacă zarul arată 7, jucătorul își pierde pălăria elegantă. Pentru orice altă valoare, jucătorul avansează pe tabla de joc cu numărul de spații egal cu valoarea zarului. Iată o implementare cu match a aceastei logici, unde rezultatul aruncării cu zarul este hardcoded, în locul unei valori aleatorii, iar restul logicii este reprezentat de funcții fără corpuri deoarece actuala implementare nu intră în sfera acestui exemplu:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

Pentru primele două ramuri, șabloanele sunt valoriile exacte 3 și 7. Pentru ultima ramură care acoperă toate celelalte valori posibile, șablonul este variabila pe care am ales-o cu numele other. Codul ce rulează pentru ramura other utilizează această variabilă, trimițând-o către funcția move_player.

Acest cod este valid și se va compila, chiar dacă nu am enumerat explicit toate valorile pe care tipul u8 le poate avea, deoarece ultimul șablon este conceput să acopere toate aceste situații. Acest șablon universal satisface cerința ca match să fie exhaustiv. Este important de reținut că acest șablon universal trebuie plasat ultimul, pentru că șabloanele sunt evaluate în ordinea în care au fost scrise. Dacă am adăuga acest șablon universal mai devreme, celelalte ramuri nu ar mai fi accesate, de aceea Rust ne va da o alertă dacă încercăm să adăugăm alte ramuri după șablonul universal!

Rust pune la dispoziție un șablon numit _, pe care îl putem folosi atunci când dorim să implementăm un mecanism universal, însă nu suntem interesați să utilizăm valoarea pe care o captează acest mecanism. Acest șablon special se potrivește cu orice valoare și nu realizează o legătură cu acea valoare, ceea ce indică faptul că nu avem de gând să o utilizăm. Rust ne scutește de avertismentul privind o variabilă neutilizată în acest context.

Analizăm acum un scenariu în care schimbăm regulile jocului: dacă rulezi alt rezultat decât un 3 sau un 7, va trebui să rulezi din nou zarul. Ne putem dispensa de utilizarea valorii universale, deci putem modifica codul pentru a utiliza _ în locul variabilei denumite 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() {}
}

Acest exemplu îndeplinește și cerința de exhaustivitate, întrucât ignorăm în mod explicit toate celelalte valori în ultimul braț al structurii de control; nu am omis nimic.

Urcăm miza și schimbăm regulile jocului o dată în plus: nimic nu se va întâmpla în tura ta dacă rolezi un rezultat care nu este nici 3, nici 7. Putem exprima acest lucru prin utilizarea valorii unit (tipul de tuplă vidă despre care am vorbit în secțiunea “Tipul tuplă”), value care să fie asociată brațului de cod _:

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

Aici, clarificăm explicit că nu intenționăm să folosim orice altă valoare care nu corespunde unui șablon dintr-un braț anterior, și că nu dorim să se execute vreun cod în acest caz.

Vom aprofunda modul în care funcționează șabloanele și mecanismul de potrivire a acestora în Capitolul 18. Deocamdată, ne vom concentra pe sintaxa if let, utilă în situațiile în care expresia match pare a fi prea stufoasă.

Control concis al executării cu if let

Sintaxa if let îți oferă posibilitatea de a combina if și let pentru a manipula, într-un mod mai concis, valorile care corespund unui anumit șablon, ignorând în același timp restul. Ia în considerare programul din Listarea 6-6, care creează o potrivire pentru o valoare Option<u8> în variabila config_max, dar care intenționează să execute codul doar dacă valoarea este variantă Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {}", max),
        _ => (),
    }
}

Listarea 6-6: Un match care este interesat doar de execuția codului atunci când valoarea este Some

Dacă valoarea este Some, afișăm valoarea din variantă Some prin asocierea acesteia cu variabila max în șablon. Nu dorim să facem nimic cu valoarea None. Pentru a respecta cerințele expresiei match, suntem obligați să adăugăm _ => () după procesarea unei singure variante, ceea ce des reprezintă un cod suplimentar, inutil și iritant.

În loc să abordăm problema în modul complicat, putem simplifica procesul folosind if let. Următorul fragment de cod funcționează identic cu instrucțiunea match prezentată în Listarea 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {}", max);
    }
}

Sintaxa if let preia un șablon și o expresie, separate de un semn de egalitate. Funcționează în mod similar cu match, unde expresia este atribuită instrucțiunii match, iar șablonul constituie prima sa ramură. În acest caz, șablonul este Some(max), iar max se leagă de valoarea din interiorul Some. Apoi, putem utiliza max în corpul blocului if let, la fel cum am folosit max în ramura corespunzătoare a instrucțiunii match. Codul din blocul if let nu se execută dacă valoarea nu corespunde șablonului.

Folosind if let, vor rezulta mai puține caractere introduse, mai puțină indentare și mai puțin cod redundant. Totuși, pierdem verificarea completă pe care instrucțiunea match o asigură. Alegerea între match și if let depinde de natura situației cu care te confrunți și dacă economisirea spațiului este un compromis acceptabil pentru a nu realiza o verificare exhaustivă.

Cu alte cuvinte, poți percepe if let drept un zahăr sintactic pentru un match care rulează codul atunci când valoarea corespunde cu un anumit șablon, ignorând toate celelalte valori.

Avem posibilitatea de a include un else în structura if let. Blocul de cod alăturat lui else este identic cu cel care ar apărea în cazul _ în expresia match, expresie care este echivalentă cu structura if let și else. Acum să-ți reamintim de definiția enumerării Coin din listarea 6-4, unde varianta Quarter deține, de asemenea, o valoare UsState. Dacă vom dori să numărăm toate monedele care nu sunt de tipul quarter, dar și să anunțăm starea acestora, putem realiza acest lucru cu ajutorul unei expresii match, astfel:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {:?}!", state),
        _ => count += 1,
    }
}

Sau am putea folosi o expresie if let și else, în felul următor:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {:?}!", state);
    } else {
        count += 1;
    }
}

Dacă te afli în situația în care logica din programul tău este prea complexă pentru a fi exprimată folosind un match, nu uita că if let este și el un instrument util în limbajul Rust.

Sumar

Am tratat felul în care putem folosi enumerările pentru a crea tipuri personalizate care pot avea una dintre o mulțime de valori enumerate. Am evidențiat felul în care tipul Option<T> din biblioteca standard ne ajută a preveni erorile prin folosirea sistemului de tipuri. Atunci când valorile enumerărilor conțin date, putem utiliza match sau if let pentru a extrage și folosi acele valori, în funcție de numărul de cazuri pe care trebuie să le gestionăm.

Acum, programele tale Rust sunt capabile să exprime conceptele specifice domeniului tău folosind structuri și enumerări. Crearea de tipuri personalizate pentru utilizare în API-ul tău garantează securitatea tipurilor: compilatorul se va asigura că funcțiile tale primesc doar valori ale tipului așteptat de fiecare funcție.

Cu scopul de a oferi utilizatorilor tăi un API bine structurat, ușor de utilizat și care expune doar ceea ce aceștia realmente necesită, să ne focusăm acum pe modulele din Rust.

Administrarea proiectelor în expansiune cu ajutorul pachetelor, crate-urilor și modulelor

Compunerea programelor de amploare invocă o importanță crescută asupra organizării codului tău. Grupând funcționalitățile corelate și separând codul cu particularități distincte, vei desluși unde să identifici codul care susține o anumită caracteristică și unde să intervii pentru a modifică cum acea caracteristică funcționează.

Până în prezent, programele pe care le-am creat au fost cuprinse într-un singur modul, într-un singur fișier. Odată cu expansiunea unui proiect, este esențial să organizezi codul împărțindu-l în diverse module și ulterior într-o multitudine de fișiere. Un pachet poate cuprinde multiple crate-uri binare și eventual un crate de bibliotecă. Odată cu dezvoltarea unui pachet, poți desprinde diverse componente în crate-uri distincte care vor deveni dependențe externe. Acest capitol îți prezintă toate aceste procedee. Pentru proiectele de o amploare considerabilă, compuse dintr-un ansamblu de pachete interconectate care evoluează împreună, Cargo oferă spațiile de lucru (workspaces), pe care le vom descrie în secțiunea „Spații de lucru Cargo” din Capitolul 14.

De asemenea, vom aborda subiectul încapsulării detaliilor de implementare. Acesta este un instrument esențial care îți permite să reutilizezi codul la un nivel superior. Odată ce ai implementat o operațiune, alt cod poate interacționa cu implementarea ta prin intermediul interfeței publice, fără a trebui să înțeleagă complexitatea acesteia. Modul în care structurezi codul stabilește care părți sunt accesibile altor bucăți de cod (publice) și care părți sunt detalii private ale implementării, pe care ai dreptul de a le modifica. Aceasta este o altă cale de a restrânge cantitatea de detalii pe care trebuie să o reții.

Un concept strâns legat este cel de domeniu de vizibilitate. Acesta se referă la contextul în care codul este scris, unde un set de nume sunt definite ca fiind „în domeniul de vizibilitate”. Atunci când se citește, scrie sau compilează cod, atât programatorii, cât și compilatoarele trebuie să știe dacă un anumit nume, într-un anumit context, se referă la o variabilă, o funcție, o structură, o enumerare, un modul, o constantă, sau alt element și ce semnificație are acel element. Ai libertatea de a crea domenii de vizibilitate și de a schimba ce nume sunt sau nu în vigoare. În același domeniu de vizibilitate, nu poți folosi același nume pentru două entități distincte, dar există unelte care te pot ajuta să rezolvi astfel de conflicte de nume.

Rust dispune de o varietate de funcții care îți facilitează gestionarea structurii codului, incluzând nivelul de accesibilitate a detaliilor, gradul de protecție al acestora, precum și gestionarea numelor din fiecare domeniu de vizibilitate din programele tale. Aceste facilități, adesea denumite în ansamblu ca sistemul de module, cuprind:

• Pachetele: O caracteristică proprie Cargo care îți permite să creezi, testezi și să distribui crate-uri.
• Crate-urile: Reprezintă un arbore de module ce produce o librărie sau un executabil.
• Modulele și utilizarea: Permite controlul asupra organizării, domeniului de vizibilitate și privației căilor.
• Căile: O modalitate de a denumi un element, precum o structură, o funcție sau un modul.

În cadrul acestui capitol, vom trece în revistă toate aceste facilități, vom discuta interacțiunea dintre ele și vom explica modul în care pot fi utilizate în gestionarea domeniului de vizibilitate. La final, vei avea o înțelegere profundă a sistemului de module și vei putea lucra cu domeniile de vizibilitate precum un expert!

Pachete și crate-uri

Începem explorarea sistemului de module cu pachete și crate-uri.

Un crate reprezintă unitatea minimă de cod pe care compilatorul Rust o procesează la un moment dat. Chiar dacă alegi să rulezi rustc în loc de cargo și transmiți un singur fișier sursă (așa cum am făcut în capitolul 1, la secțiunea "Scrierea și Rularea unui Program în Rust"), compilatorul tratează acel fișier ca fiind un crate. Un crate poate include module, iar aceste module pot fi definite în alte fișiere care sunt compilate împreună cu crate-ul, așa cum vom vedea în secțiunile următoare.

Există două tipuri de crate-uri: crate-uri binare și crate-uri de bibliotecă. Crate-urile binare sunt programe pe care le poți compila în fișiere executabile pe care poți să le rulezi, precum ar fi un program de linie de comandă sau un server. Fiecare crate binar trebuie să aibă o funcție numită main care definește comportamentul său atunci când este rulat. Toate crate-urile pe care le-am creat până acum au fost crate-uri binare.

Crate-urile de bibliotecă nu dispun de o funcție main și nu se compilează sub formă de executabil. Acestea conțin funcționalități concepute pentru a fi utilizate în comun de diferite proiecte. De pildă, crate-ul rand, pe care l-am utilizat în Capitolul 2, furnizează funcționalitatea de a genera numere aleatorii. De cele mai multe ori, când utilizatorii de Rust spun “crate”, se referă la crate-uri de bibliotecă. De asemenea, ei folosesc termenul "crate" alternativ cu conceptul general de "bibliotecă" în programare.

Radacina unui crate este un fișier sursă principal, punctul de start al compilatorului Rust. El alcătuiește modulul rădăcină al crate-ului tău (vom discuta în detaliu despre module în secțiunea „Definirea modulelor pentru controlul domeniului de vizibilitate și a confidențialității”).

Un pachet este un ansamblu ce poate cuprinde unul sau mai multe crate-uri, având rolul de a oferi diverse funcționalități. Fiecare pachet conține un fișier numit Cargo.toml, care servește drept ghid pentru construcția respectivelor crate-uri. Un exemplu concret este Cargo, care nu este altceva decât un pachet. Acesta include un crate de tip binar utilizat pentru instrumentul de linie de comandă cu care ai lucrat pentru a construi propriul cod. Pachetul Cargo găzduiește și un crate de tip bibliotecă, de care depinde crate-ul binar. Alte proiecte pot recurge la acest crate de tip bibliotecă pentru a folosi aceeași logică pe care o implementează instrumentul de linie de comandă.

Reflectând liber, un pachet are capacitatea de a găzdui oricâte crate-uri binare dorești, cu însă o limitare: poate conține cel mult un singur crate de tip bibliotecă. Este obligatoriu ca un pachet să aibă cel puțin un crate, indiferent dacă este vorba de unul de tip bibliotecă sau de tip binar.

În continuare, vom descrie pașii ce intervin în procesul de creare a unui pachet. Mai întâi, vom introduce comanda cargo new:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

După ce executăm comanda cargo new, putem folosi ls pentru a vedea ceea ce a generat comanda Cargo. În directoriul proiectului, vom găsi un fișier numit Cargo.toml, care ne creează un pachet. Tot acolo, se află și un directoriu src ce conține fișierul main.rs.

Dacă deschizi fișierul Cargo.toml într-un editor de text, vei observa că nu există nicio referire la src/main.rs. De fapt, Cargo urmează o convenție specifică prin care src/main.rs reprezintă rădăcina unui crate binar având același nume ca și pachetul. În același timp, Cargo recunoaște că dacă directoriul pachetului conține src/lib.rs, înseamnă că pachetul include un crate de bibliotecă cu același nume ca pachetul, iar src/lib.rs reprezintă rădăcina acestui tip de crate. Cargo transmite fișierele rădăcină ale crate-urilor către compilatorul rustc pentru a construi fie biblioteca, fie binarul.

În exemplul nostru, avem un pachet care include doar src/main.rs, ceea ce semnifică faptul că conține un singur crate binar numit my-project. Dacă un pachet ar conține atât src/main.rs cât și src/lib.rs, ar însemna că are două crate-uri: unul binar și unul de bibliotecă, ambele având același nume ca pachetul. Un pachet poate conține mai multe crate-uri binare dacă fișierele lor sunt plasate în directoriul src/bin: fiecare fișier reprezentând un crate binar separat.

Stabilirea modulelor pentru a gestiona domeniul de vizibilitate și confidențialitatea

In cadrul acestei secțiuni, vom discuta despre module și despre alte componente ale sistemului de module, în special calea care permite denumirea elementelor; cuvântul cheie use care introduce o cale în domeniul de vizibilitate; și cuvântul cheie pub, utilizat pentru a face elemente publice. Vom aborda, de asemenea, cuvântul cheie as, pachete externe și operatorul glob.

Înainte de toate, vom începe cu o listă de reguli pe care le poți consulta ușor atunci când vă organizați codul în viitor. Ulterior, vom explica fiecare regulă în detaliu.

Ghid rapid despre Module

Următoarea recapitulare oferă o privire lucrurilor esențiale despre cum modulele, căile, cuvântul-cheie use, precum și cuvântul-cheie pub colaborează cu compilatorul și cum, de obicei, dezvoltatorii își structurează codul. Deși vom discuta fiecare din aceste reguli, pe parcursul acestui capitol, referirea la acest ghid este un mod eficient de reamintire a modului în care funcționează modulele.

• Începând de la rădăcina crate-ului: În momentul compilării unui crate, compilatorul începe de la fișierul rădăcina al crate-ului (care este, de obicei, src/lib.rs pentru un crate de tip bibliotecă sau src/main.rs pentru un crate binar) în căutare de cod pentru a-l compila.
• Declararea modulelor: În fișierul rădăcină, poți introduce noi module. Să zicem că declarăm un modul numit "garden" cu mod garden;. Compilatorul va căuta codul asociat acestui modul în următoarele locații:
  • În mod direct în cod, folosind acolade în locul semicolonului, după mod garden
  • În fișierul src/garden.rs
  • În fișierul src/garden/mod.rs
• Declararea submodulelor: În orice alt fișier în afara celui rădăcină, poți declara submodule. De exemplu, ai putea declara mod vegetables; în src/garden.rs. Compilatorul va căuta codul asociat acestui submodul în directoriul numit după modulul părinte în locațiile următoare:
  • Direct în cod, folosind acolade în locul semicolonului după mod vegetables,
  • În fișierul src/garden/vegetables.rs
  • În fișierul src/garden/vegetables/mod.rs
• Referirea către codul în module: Odată ce un modul este inclus în crate-ul tău, poți face referință la codul acestuia din orice alt loc în același crate, atât timp cât regulile de confidențialitate permit, folosind calea către acel cod. De exemplu, un tip Asparagus din modulul de legumă a grădinii ar putea fi referit folosind următoarea cale: crate::garden::vegetables::Asparagus.
• Privat versus public: În mod implicit, codul din cadrul unui modul este privat față de modulele părinte. Pentru a face un modul public, se declară folosind pub mod în loc de mod. Pentru a face item-urile din interiorul unui modul public să fie, de asemenea, publice, folosește pub înaintea declarațiilor acestora.
• Cuvântul-cheie use: Utilizat într-un domeniu de vizibilitate, cuvântul-cheie use creează scurtături spre item-uri pentru a minimiza repetarea de căi lungi. În orice domeniu de vizibilitate care face referire la crate::garden::vegetables::Asparagus, poți crea o scurtătură folosind use crate::garden::vegetables::Asparagus;. După aceea, vei avea nevoie doar să scrii Asparagus pentru a putea folosi acest tip în cadrul domeniului de vizibilitate.

În acest exemplu, vom crea un crate binar numit "backyard" pentru a ilustra aceste reguli. Directoriul asociat cu crate-ul, care se numește și el "backyard", va conține următoarele fișiere și directoare:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Fișierul principal al acestui crate se numește src/main.rs și conține următorul cod:

Numele fișierului: src/main.rs

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {:?}!", plant);
}

Linia pub mod garden; le indică compilatorului să adauge codul pe care îl găsește în fișierul src/garden.rs. Codul din acest fișier este următorul:

Numele fișierului: src/garden.rs

pub mod vegetables;

De asemenea, linia pub mod vegetables; anunță compilatorul că trebuie să includă codul din fișierul src/garden/vegetables.rs. Codul din respectivul fișier este:

#[derive(Debug)]
pub struct Asparagus {}

Acum, să detaliem aceste reguli și să le ilustrăm în acțiune!

Organizarea codului în module

Modulele ne oferă posibilitatea de a structura codul în interiorul unui crate, în scopul facilitării citirii și reutilizării acestuia. Prin intermediul modulelor, putem controla gradul de confidențialitate al elementelor, deoarece, în mod implicit, codul din interiorul unui modul este privat. Elementele private reprezintă detalii de implementare interne și nu pot fi utilizate în afara modulului. Cu toate acestea, avem opțiunea de a transforma modulele și elementele lor în entități publice, ceea ce le face accesibile pentru a fi utilizate și interconectate cu alte coduri externe.

Ca exemplu de utilizare, să presupunem că dorim să scriem un crate de bibliotecă care să reprezinte funcționalitatea unui restaurant. Vom defini semnăturile funcțiilor și vom lăsa corpurile lor goale, pentru a ne concentra pe structurarea codului, mai degrabă decât pe detaliile de implementare ale funcționării restaurantului.

În industria restaurantelor, unele zone ale unui restaurant sunt denumite zona din față a casei și, respectiv, zona din spate a casei. Zona din față a casei include spațiile în care sunt primiți clienții: locul în care ospătarii îi îndrumă pe aceștia la mese, preiau comenzi și încasează contravaloarea serviciilor, iar barmanii prepară băuturile. Zona din spate a casei este locul în care chefii și bucătarii își desfășoară activitatea în bucătărie, personalul se ocupă de curățenie, iar managerii își îndeplinesc sarcinile administrative.

Pentru a structura crate-ul nostru într-un mod optim, avem posibilitatea de a organiza funcțiile sale în module încorporate. Începe prin a crea o nouă bibliotecă pe care o vom numi restaurant. Acest lucru se poate realiza prin executarea comenzi cargo new restaurant --lib. Apoi, introdu codul afișat în Listarea 7-1 în fișierul src/lib.rs. Acest pas ne va permite definirea unor module și semnăturilor funcțiilor aferente. Să aruncăm o privire asupra secțiunii frontale a casei:

Numele fișierului: src/lib.rs

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

Listarea 7-1: Un modul front_of_house ce include alte module ce conțin, la rândul lor, diverse funcții

Un modul se definește folosind cuvântul-cheie mod, urmat de numele ales pentru modulul respectiv -ăm făcut acest lucru mai sus cu front_of_house. Corpul modulului este închis între acolade. În interiorul modulelor, avem posibilitatea de a plasa alte module, exact cum am procedat cu modulele hosting și serving. Nu în ultimul rând, modulele pot găzdui definiții pentru alte tipuri de elemente precum structuri, enumerări, constante, trăsături și, așa cum am ilustrat în Listarea 7-1, funcții.

Utilizând module, avem posibilitatea de a grupa definițiile corelate și de a justifica această corelare. În acest mod, programatorii care vor folosi codul vor putea naviga mai ușor în funcție de grupele de definițiile create, în loc să fie nevoiți să parcurgă toate definițiile. Astfel devine mai simplu de identificat definițiile care sunt relevante pentru ei. De asemenea, când adaugă noi funcționalități în cod, vor ști exact unde să le plaseze pentru a menține organizarea programului.

Am menționat anterior că fișierele src/main.rs și src/lib.rs le denumim rădăcinile crate-urilor. Această denumire vine de la faptul că, conținutul oricăruia dintre aceste două fișiere, formează un modul numit crate, situat la baza structurii de module a crate-ului. Aceasta e cunoscută sub denumirea de arbore de module.

Listarea 7-2 prezintă arborele de module pentru structura prezentată în Listarea 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Listarea 7-2: Structura ierarhică a modulelor pentru codul din Listarea 7-1

Acest arbore ilustrează modul în care anumite module sunt incluse în altele; spre exemplu, modulul hosting este inclus în front_of_house. De asemenea, structura evidențiază că anumite module sunt simultane sau coexistente, adică sunt definite în același modul; hosting și serving sunt astfel de module simultane, definite în cadrul front_of_house. Dacă modulul A este inserat în modulul B, spunem că A este descendent al lui B iar B este asendent sau părinte pentru A. Observă că întregul arbore de module își are rădăcina în modulul implicit denumit crate.

Structura modulelor s-ar putea să-ți evoce structura ierarhică a directoriilor pe calculatorul tău; este o comparație extrem de adecvată! Așa cum utilizezi directoriile într-un sistem de operare pentru a-ți organiza fișierele, tot astfel folosești modulele pentru a-ți structura codul. Și exact ca în cazul fișierelor dintr-un directoriu, avem nevoie de o modalitate de a localiza modulele noastre.

Utilizarea căilor pentru a face referire la un element în structura de module

Când dorim să arătăm lui Rust unde să găsească un anumit element în structura de module, folosim o cale, exact cum am proceda atunci când navigăm printr-un sistem de fișiere. Pentru a apela o funcție este necesar să cunoaștem calea către aceasta.

Există două forme pe care o cale le poate lua:

• O cale absolută reprezintă calea completă începând de la rădăcina unui crate; în cazul codului ce provine dintr-un crate extern, calea absolută debutează cu numele crate-ului. Pentru codul din crate-ul actual, calea începe cu literalul crate.
• O cale relativă pornește de la modulul curent și utilizează self, super, sau un identificator din cadrul modulului curent.

Fie că vorbim despre căi absolute sau relative, acestea sunt urmate de unul sau mai multe identificatori separați de patru puncte (::).

Revenind la Lista 7-1, presupunem că vrem să convocăm funcția add_to_waitlist. Asta este echivalent cu a întreba: care este calea către funcția add_to_waitlist? Lista 7-3 include Lista 7-1, dar unele dintre module și funcții au fost eliminate.

Vom prezenta în cele ce urmează două moduri de a apela funcția add_to_waitlist din cadrul unei noi funcții, eat_at_restaurant, definită la rădăcina crate-ului. Desi aceste căi sunt corecte, există o altă problemă și care va împiedica compilarea cu succes a acestui exemplu în forma lui actuală. Vom explica motivul în scurt timp.

Funcția eat_at_restaurant este parte componentă a interfeței de programare a aplicației (API) publice a crate-ului nostru de tip bibliotecă, motiv pentru care o marcam cu cuvântul cheie pub. În secțiunea “Expunerea căilor cu ajutorul cuvântului cheie pub”, vom discuta mai pe larg despre pub.

Numele fișierului: src/lib.rs

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Listarea 7-3: Apelul funcției add_to_waitlist utilizând căi absolute și relative

În momentul în care apelăm pentru prima dată funcția add_to_waitlist în interiorul eat_at_restaurant, folosim o cale absolută. Funcția add_to_waitlist se află în același crate cu eat_at_restaurant, ceea ce înseamnă că avem posibilitatea de a folosi cuvântul cheie crate pentru a începe calea absolută. Includem apoi toate modulele succesive până ajungem la add_to_waitlist. Poți vizualiza această structură ca pe un sistem de fișiere: am specifica calea /front_of_house/hosting/add_to_waitlist pentru a executa programul add_to_waitlist; utilizarea termenului crate pentru a porni de la rădăcina unui crate este similară cu utilizarea / pentru a porni de la rădăcina sistemului de fișiere în shell-ul tău.

A doua oară când apelăm add_to_waitlist în cadrul eat_at_restaurant, utilizăm o cale relativă. Această cale începe cu front_of_house, numele modulului care este definit la același nivel în ierarhia de module ca și eat_at_restaurant. Echivalentul în contextul unui sistem de fișiere ar fi utilizarea căii front_of_house/hosting/add_to_waitlist. Pornirea de la numele unui modul indică faptul că calea este relativă.

Decizia de a utiliza o cale relativă sau una absolută va depinde de specificul proiectului tău și de probabilitatea de a mișca codul de definiție a unui element separat sau împreună cu codul care face referire la acel element. De exemplu, dacă am muta modulul front_of_house și funcția eat_at_restaurant într-un modul numit customer_experience, am fi nevoiți să actualizăm calea absolută către add_to_waitlist, însă calea relativă ar rămâne validă. În contrast, dacă am muta funcția eat_at_restaurant într-un modul numit dining, calea absolută către apelul add_to_waitlist nu s-ar schimba, doar calea relativă ar necesita o actualizare. În general, preferăm să folosim căi absolute deoarece este mai probabil să dorim să mișcăm definițiile de cod și apelurile de funcții independent unul de celălalt.

Să încercăm să compilăm Listarea 7-3 pentru a înțelege motivul pentru care nu se compilează! Eroarea pe care o întâlnim este expusă în Listarea 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();
  |                            ^^^^^^^ 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();
   |                     ^^^^^^^ 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` due to 2 previous errors

Listarea 7-4: Erorile de compilare a codului din Listarea 7-3

Mesajele de eroare indică faptul că modulul hosting este declarat ca fiind privat. Astfel, noi avem referințele corecte pentru modulul hosting și funcția add_to_waitlist, însă Rust nu acceptă utilizarea acestora datorită accesului restricționat la secțiunile private ale codului. În Rust, implicit, toate elementele - funcțiile, metodele, structurile, enumerările, modulele și constantele - sunt private în raport cu modulele părinte. Dacă vrei să faci un element anume, precum o funcție sau o structură, privat, îl introduci într-un modul.

Elementele dintr-un modul părinte nu pot utiliza elementele private din interiorul modulelor copil. În schimb, elementele din modulele copil au permisiunea de a folosi elementele prezentate în modulele lor ancestrale. Acest lucru se întâmplă deoarece modulele copil încapsulează și ascund detaliilor lor de implementare. Cu toate acestea, aceste module copil pot vedea contextul în care sunt definite. Într-un mod analog, putem vedea regulile de confidențialitate ca fiind similare cu gestionarea unei bucătării dintr-un restaurant: tot ceea ce se întâmplă în interior este privat din perspectiva clienților, dar managerii au capacitatea de a vedea și a coordona toate activitățile din restaurantul pe care îl administrează.

Decizia Rust de a proiecta sistemul de module în acest mod are la bază intenția de a ascunde, prin definiție, detaliile interne de implementare. În consecință, te vei putea ghida mai ușor în cunoașterea părților din cod pe care le poți modifica fără a afecta funcționarea restului de cod. Deși, Rust îți oferă posibilitatea de a dezvălui părți din interiorul codului modulelor copil către modulele ancestrale externe prin folosirea cuvântului cheie pub pentru a face un element anume public.

Expunerea căilor private cu cuvântul cheie pub

Să ne reamintim de eroarea din Listarea 7-4, care ne indica faptul că modulul hosting este privat. Obiectivul nostru este ca funcția eat_at_restaurant, din modulul părinte, să aibă acces la funcția add_to_waitlist, localizată în modulul copil. Pentru a realiza acest lucru, vom marca modulul hosting cu cuvântul cheie pub, după cum observăm în Listarea 7-5.

Numele fișierului: src/lib.rs

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Listarea 7-5: Declararea modulului hosting ca fiind pub pentru a-l putea folosi în eat_at_restaurant

Totuși, codul din Listarea 7-5 încă generează o eroare, așa cum vedem în Listarea 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
 --> src/lib.rs:9:37
  |
9 |     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:12:30
   |
12 |     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` due to 2 previous errors

Listarea 7-6: Erorile de compilare a codului din Listarea 7-5

Ce s-a întâmplat, de fapt? Adăugând cuvântul cheie pub în fața lui mod hosting, acest modul devine public. Cu această schimbare, dacă putem accesa front_of_house, atunci putem accesa și hosting. Cu toate acestea, conținutul modulului hosting rămâne în continuare privat. Transformarea unui modul într-unul public nu implică și transformarea conținutului său în public. Cuvântul cheie pub pentru un modul le permite doar modulelor ancestrale să facă referire la acesta, fără a-i putea accesa codul intern. Deoarece modulele sunt practic containere, simpla lor transformare în publice nu este de ajuns; este necesar și să decidem dacă transformăm unul sau mai multe elemente din modul în publice.

Erorile din Listarea 7-6 ne indică faptul că funcția add_to_waitlist are un statut privat. Aceste reguli privind confidențialitatea se aplică atât structurilor, enumerărilor, funcțiilor și metodelor, cât și modulelor.

Să transformăm funcția add_to_waitlist într-una publică, adăugând cuvântul cheie pub înainte de definiția sa, așa cum este ilustrat în Listarea 7-7.

Numele fișierului: src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Listarea 7-7: Prin adăugarea cuvântului cheie pub înainte de mod hosting și fn add_to_waitlist, putem apela funcția din eat_at_restaurant

Acum codul se va compila cu succes! Ca să înțelegem de ce utilizarea cuvântului cheie pub ne permite să folosim aceste căi în cadrul funcției add_to_waitlist, respectând astfel regulile de confidențialitate, să examinăm căile atât absolute, cât și cele relative.

În calea absolută, pornim de la crate, rădăcina arborelui de module ale crate-ului nostru. Modulul front_of_house este definit chiar la rădăcina crate-ului. Deși front_of_house nu are statutul de public, putem totuși referi front_of_house în cadrul funcției eat_at_restaurant, întrucât ambele sunt definite în același modul (adică, sunt "surori"). Următorul pas este modulul hosting marcat cu pub. Putem accesa modulul părinte al hosting, ceea ce înseamnă că putem accesa hosting. În final, funcția add_to_waitlist este marcată cu pub și putem accesa modulul ei părinte, deci apelul funcției noastre funcționează!

În calea relativă, procesul este identic cu cel din calea absolută, cu excepția primului pas: în loc să înceapă de la rădăcina crate-ului, calea demarează de la front_of_house. Modulul front_of_house este definit în cadrul aceluiași modul cu eat_at_restaurant, așadar calea relativă ce pornește din modulul unde eat_at_restaurant este definit este funcțională. Ulterior, pentru că hosting și add_to_waitlist sunt etichetate cu pub, restul căii este funcțional și acest apel de funcție este valid!

Dacă vrei să îți distribui crate-ul de librărie pentru ca alte proiecte să utilizeze codul tău, API-ul tău public este contractul tău cu utilizatorii crate-ului tău. Acesta va stabili modul în care aceștia pot interacționa cu codul tău. E mult de luat în considerare atunci când vine vorba de gestionarea modificărilor la API-ul tău public pentru a facilita dependența utilizatorilor față de crate-ul tău. Aceste aspecte nu sunt cuprinse în sfera acestei cărți; dacă acest subiect te interesează, consultă Ghidul pentru API-ul Rust.

Practici recomandate pentru pachete cu un executabil și o bibliotecă

Am precizat anterior că un pachet poate include atât un crate de tip executabil în src/main.rs, cât și un crate de tip bibliotecă în src/lib.rs, ambele având în mod implicit numele pachetului. De obicei, pachetele construite astfel încât să dispună de un crate de tip bibliotecă și unul de tip executabil, vor avea un cod minim în crate-ul executabil, necesar doar pentru a iniția un executabil care va apela codul din crate-ul de tip bibliotecă. Aceasta abordare permite altor proiecte să beneficieze de funcționalitățile oferite la maximum de pachet, întrucât codul crate-ului de tip bibliotecă poate fi distribuit. Structura arborelui de module trebuie definită în src/lib.rs. Apoi, elementele publice pot fi folosite în crate-ul de tip executabil, prin specificarea numelui pachetului la începutul căilor. Astfel, crate-ul de tip executabil devine un utilizator al crate-ului de tip bibliotecă, exact cum un crate complet extern ar utiliza crate-ul de tip bibliotecă: are acces doar la API-ul public. Acest lucru ajută la conceperea unui API eficient; nu numai că ești autor, dar ești și utilizator! În Capitolul 12, vom ilustra această bună practică organizatorică printr-un program de linie de comandă, care va include atât un crate de tip executabil, cât și unul de tip bibliotecă.

Inițierea căilor relative cu super

Putem crea căi relative care încep direct cu modulul părinte, în loc să le începem cu modulul curent sau cu rădăcina crate-ului. Aceasta se realizează utilizând super la începutul căii. Acest concept este similar cu începutul unei căi de sistem de fișiere cu sintaxa ... Prin utilizarea super avem capacitatea de a referi un element de care știm că se găsește în modulul părinte. Aceasta poate facilita procesul de rearanjare a structurii modulelor, în special dacă modulul este strâns legat de modulul părinte, dar acesta din urmă ar putea fi mutat în altă parte a structurii de module în viitor.

Luăm în considerare codul din Listarea 7-8, în care este prezentată situația în care un bucătar corectează o comandă greșită și o duce personal clientului. Funcția fix_incorrect_order definită în modulul back_of_house apelează funcția deliver_order definită în modulul părinte, indicația către funcția deliver_order începând cu super:

Numele fișierului: src/lib.rs

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

Listare 7-8: Apelul unei funcții folosind o cale relativă, care începe cu super

Funcția fix_incorrect_order se află în modulul back_of_house, așa că folosim super pentru a ajunge la modulul părinte al back_of_house, care, în acest caz, este crate, rădăcina. De acolo, căutăm deliver_order și îl găsim. Succes! Considerăm că modulul back_of_house și funcția deliver_order vor păstra aceeași relație și că acestea vor fi mutate împreună în cazul în care decidem să reorganizăm structura modulelor în crate. Prin urmare, utilizăm super pentru a avea mai puține locuri de actualizat în codul sursă în viitor, dacă acest cod va fi mutat într-un modul diferit.

Setarea structurilor și enumerărilor ca fiind publice

Avem posibilitatea de a folosi pub pentru a seta structurile și enumerările ca fiind publice. Cu toate acestea, există câteva aspecte suplimentare referitoare la modul în care pub interacționează cu structurile și enumerările. Dacă aplicăm pub înaintea definiției unei structuri, facem structura publică, dar câmpurile acesteia vor rămâne private. Putem decide individual dacă fiecare câmp în parte va fi sau nu public. În Listarea 7-9, am definit o structură publică back_of_house::Breakfast care conține un câmp public toast, dar și un câmp privat seasonal_fruit. Acest lucru este similar cu situația dintr-un restaurant în care clientul poate alege tipul de pâine care însoțește masa, însă bucătarul hotărăște care fruct va acompania masa, în funcție de fructele de sezon disponibile. Deoarece varietatea de fructe disponibile se schimbă frecvent, clienții nu au posibilitatea de a alege fructul sau chiar de a vedea ce fruct vor primi.

Numele fișierului: src/lib.rs

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal
    // meal.seasonal_fruit = String::from("blueberries");
}

Listarea 7-9: O structură cu anumite câmpuri publice și altele private

Datorită faptului că în structura back_of_house::Breakfast, câmpul toast este public, putem citi și scrie în câmpul toast folosind notația cu punct, în funcția eat_at_restaurant. Rețineți că nu putem utiliza câmpul 'seasonal_fruit' în eat_at_restaurant, deoarece 'seasonal_fruit' este privat. Încearcă să de-comentezi linia care modifică valoarea câmpului seasonal_fruit pentru a vedea ce eroare apare!

Trebuie remarcat și faptul că, deoarece back_of_house::Breakfast conține un câmp privat, structura trebuie să ofere o funcție asociată publică pentru a construi o instanță a Breakfast (în acest caz, am numit-o summer). Dacă Breakfast nu ar avea o astfel de funcție, în funcția eat_at_restaurant nu am putea crea o instanță a Breakfast, deoarece nu am putea seta valoarea câmpului privat seasonal_fruit.

În contrast, dacă stabilim o enumerare ca fiind publică, toate variantele acesteia devin publice. Ne este suficient să aplicăm pub înainte de cuvântul-cheie enum, așa cum este ilustrat în Listarea 7-10.

Numnele fișierului: src/lib.rs

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

Listarea 7-10: Selectarea unei enumerări ca publică face ca toate variantele acesteia să fie accesibile

Am declarat enum-ul Appetizer ca fiind public, ceea ce ne permite să folosim variantele Soup și Salad în codul eat_at_restaurant.

Enumerările nu sunt foarte utile dacă variantelor lor nu le este permis accesul public; ar fi incomod să trebuiască să adnotăm fiecare variantă a enumerării cu pub în fiecare caz. Din acest motiv, modul implicit pentru variantele de enumerări este acela de a fi public. Pe de altă parte, structurile sunt frecvent folosite fără ca câmpurile lor să fie publice, astfel că câmpurile unei structuri urmează regula generală unde totul este privat în mod implicit, cu excepția cazului în care este adnotat cu pub.

Există încă o situație în care este implicată utilizarea pub și pe care nu am discutat-o încă, aceasta fiind ultima caracteristică a sistemului de module, și anume cuvântul cheie use. Vom discuta mai întâi use în mod independent, apoi vom demonstra cum să combinăm pub și use.

Utilizarea cuvântului cheie use pentru a aduce căile în domeniul de vizibilitate

Scrierea completă a căilor pentru apelarea funcțiilor poate fi incomod de repetitivă. În Listarea 7-7, indiferent dacă optăm pentru drumul absolut sau cel relativ către funcția add_to_waitlist, am trebuit de fiecare dată să specificăm și front_of_house și hosting. Din fericire, există o modalitate de a simplifica acest proces: putem crea o scurtătură către o cale cu ajutorul cuvântului cheie use. Astfel, putem folosi un nume mai scurt în restul domeniului de vizibilitate.

În Listarea 7-11, introducem modulul crate::front_of_house::hosting în domeniul de vizibilitate al funcției eat_at_restaurant. Astfel, pentru apelarea funcției add_to_waitlist în contextul eat_at_restaurant, trebuie doar să specificăm hosting::add_to_waitlist.

Numele fișierului: src/lib.rs

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

Listarea 7-11: Introducerea unui modul în domeniul de vizibilitate cu use

Adăugarea use și a unei căi într-un domeniu este similară cu operațiunea de creare a unui link simbolic în sistemul de fișiere. Prin introducerea use crate::front_of_house::hosting la nivelul rădăcinii crate-ului, hosting devine un nume valid în cadrul acestui domeniu de vizibilitate, ca și cum modulul hosting ar fi fost definit chiar în rădăcina crate-ului. Căile aduse în vizibilitate cu use au capacitatea de a verifica confidențialitatea, la fel ca toate celelalte căi.

Trebuie să ținem minte că use creează o scurtătură doar în cadrul specific al domeniului de vizibilitate în care este folosit. Listarea 7-12 plasează funcția eat_at_restaurant într-un nou submodul numit customer. Acesta reprezintă un domeniu diferit de cel al declarației use, așa că funcția nu va putea fi compilată:

Filename: src/lib.rs

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

Listarea 7-12: Instrucțiunea use este aplicabilă doar în domeniul de vizibilitate în care se găsește

Eroarea de compilare indică faptul că scurtătura nu mai este valabilă în interiorul modulului customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
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

error[E0433]: failed to resolve: use of undeclared crate or module `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of undeclared crate or module `hosting`

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` due to previous error; 1 warning emitted

Este important de observat că există de asemenea un avertisment care ne informează că instrucțiunea use nu mai este folosită în domeniul său de vizibilitate! Pentru a remediat această problemă, putem muta instrucțiunea use direct în interiorul modulului customer sau putem face referire la scurtătură din modulul părinte folosind super::hosting, în interiorul modulului copil customer.

Căi use idiomatice

E posibil să te fi întrebat, privind Listarea 7-11, de ce am utilizat use crate::front_of_house::hosting și apoi am apelat funcția hosting::add_to_waitlist în cadrul funcției eat_at_restaurant. De ce nu am specificat calea completă în use până la funcția add_to_waitlist pentru a obține același rezultat? Acest ultim mod de a proceda este ilustrat în Listarea 7-13.

Numele fișierului: src/lib.rs

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

Listarea 7-13: Introducerea funcției add_to_waitlist în domeniul de vizibilitate cu use, o abordare care nu respectă normele idiomatice ale limbajului

Deși ambele metode, ilustrate în Listările 7-11 și 7-13, îndeplinesc aceeași sarcină, abordarea din Listarea 7-11 este considerată a fi cea corectă, conform obiceiurilor limbajului. Utilizarea lui use pentru a introduce modulul părinte al funcției în domeniul de vizibilitate necesită specificarea modulului părinte când apelăm funcția. Însă, astfel, devine evident că funcția nu este definită local, minimizând în același timp repetarea căii complete. În schimb, codul din Listarea 7-13 lasă în incertitudine locul unde add_to_waitlist este definită.

Cu toate acestea, când introducem în domeniul de vizibilitate structuri, enumerări și alte elemente cu ajutorul lui use, este idiomatic să se specifice calea completă. Listarea 7-14 arată metoda adecvată de a aduce structura HashMap din biblioteca standard în domeniul de vizibilitate al unui crate binar.

Numele fișierului: src/main.rs

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

Listarea 7-14: Introducerea HashMap în domeniu de vizibilitate în modul consecvent

Această idiomă nu are o cauză anume, este doar o tradiție care a fost adoptată pentru scrierea și citirea codului Rust.

Excepția la această convenție este dacă aducem în domeniul de vizibilitate două elemente care au același nume, folosind declarațiile use. Rust nu permite asta. Listarea 7-15 ilustrează cum să introducem în domeniul de vizibilitate două tipuri Result cu același nume, dar provenind din module părinte diferite și cum să le referim.

Numele fișierului: src/lib.rs

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

Listarea 7-15: Introducerea simultană a două tipuri cu același nume în același domeniu de vizibilitate impune utilizarea modulelor părinte.

După cum poți observa, specificarea modulelor părinte ne ajută să distingem între cele două tipuri Result. Dacă am fi folosit use std::fmt::Result și use std::io::Result, am fi ajuns cu două tipuri Result în același domeniu și Rust nu ar fi putut distinge la care tip Result ne referim.

Utilizarea cuvântului cheie as pentru a atribui nume noi

O altă soluție la problema aducerii a două tipuri cu același nume în același domeniu de vizibilitate cu use implică folosirea cuvântului cheie as. După ce specificăm calea, putem adăuga as și un nume local nou, sau un alias, pentru tipul respectiv. Listarea 7-16 ne prezintă o altă variantă de a scrie codul din Listarea 7-15 prin redenumirea unuia dintre cele două tipuri Result folosind as.

Numele fișierului: src/lib.rs

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

Listarea 7-16: Redenumirea unui tip la momentul introducerii acestuia în domeniul de vizibilitate, folosind cuvântul cheie as

În cel de-al doilea enunț use, noi am decis să alegem numele IoResult pentru tipul std::io::Result. Acesta nu va intra în conflict cu tipul Result din std::fmt pe care tot l-am adus în domeniul de vizibilitate. Atât Listarea 7-15 cât și Listarea 7-16 reprezintă abordări idiomatice, deci ai libertatea de a alege cea care ți se potrivește cel mai bine!

Re-exportarea numelor cu pub use

Când aducem un nume în domeniul de vizibilitate cu ajutorul cuvântului cheie use, numele disponibil în noul domeniu de vizibilitate este privat. Pentru a permite codului care apelează codul nostru să se refere la acel nume ca și cum ar fi fost definit în domeniul de vizibilitate al acelui cod, putem combina pub și use. Această tehnică se numește re-exportare deoarece aducem un element în domeniul de vizibilitate, dar de asemenea face acel element disponibil și pentru cei ce importă codul nostru.

Listarea 7-17 prezintă codul din Listarea 7-11 cu use în modulul root modificat în pub use.

Numele fișierului: src/lib.rs

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

Listarea 7-17: Facem un nume disponibil pentru orice cod de utilizat dintr-un nou domeniu de vizibilitate cu pub use

Înainte de această modificare, codul extern ar trebui să apeleze funcția add_to_waitlist utilizând calea restaurant::front_of_house::hosting::add_to_waitlist(). Acum, având în vedere că pub use a re-exportat modulul hosting din modulul root, codul extern poate acum utiliza calea restaurant::hosting::add_to_waitlist() în schimb.

Re-exportarea este utilă când structura internă a codului tău este diferită de felul în care programatorii care apelează codul tău ar gândi despre domeniu. De exemplu, în această metaforă despre restaurant, oamenii care administrează restaurantul gândesc despre "fața casei" și "spatele casei". Dar clienții care vizitează un restaurant probabil nu vor gândi despre părțile restaurantului în acești termeni. Cu pub use, putem scrie codul nostru cu o structură, dar expunem o structură diferită. Făcând acest lucru, biblioteca noastră este bine organizată atât pentru programatorii care lucrează în bibliotecă cât și pentru programatorii care apelează biblioteca. Vom privi un alt exemplu de pub use și cum acesta afectează documentația crate-ului tău în secțiunea „Exportarea unui API public și accesibil cu pub use” din Capitolul 14.

Utilizarea pachetelor externe

În capitolul 2, am creat un joc de ghicit numere, care se baza pe un pachet extern numit rand pentru generarea numerelor aleatorii. Pentru a folosi rand în cadrul proiectului nostru, am inclus următoarea linie în fișierul Cargo.toml:

Numele fișierului: Cargo.toml

rand = "0.8.5"

Adăugarea rand ca o dependență în fișierul Cargo.toml instruiește sistemul Cargo să descarce pachetul rand și orice dependențe asociate de pe crates.io și să-l predea la dispoziția proiectului nostru.

Ulterior, pentru a aduce definițiile din rand în domeniul de vizibilitate al pachetului nostru, am inclus o instrucțiune use. Aceasta era precedată de numele pachetului, rand, și continuată cu lista elementelor pe care am dorit să le aducem în vizibilitate. Îți poți aduce aminte de secțiunea „Generarea unui număr aleator” din capitolul 2, unde am introdus trăsătura Rng în domeniul de vizibilitate și am apelat funcția 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}");
}

Membrii comunității Rust au pus la dispoziție multe pachete pe crates.io, iar integrarea oricăruia dintre acestea în pachetul tău presupune aceeași pași: listarea pachetelor în fișierul Cargo.toml și utilizarea instrucțiunii use pentru a introduce elemente din aceste pachete în domeniul de vizibilitate.

Este important de notat că și biblioteca standard std este de asemenea un crate extern pachetului nostru. Totuși, deoarece biblioteca standard este inclusă în setul de livrare standard al limbajului Rust, nu trebuie să modificăm Cargo.toml pentru a include std. Trebuie doar să folosim instrucțiunea use pentru a introduce elemente din aceasta în domeniul de vizibilitate al pachetului nostru. De exemplu, pentru a folosi HashMap, am utiliza următoarea linie:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Aceasta este o cale absolută care începe cu std, numele crate-ului bibliotecii standard.

Utilizarea căilor îmbinate pentru a economisi spațiu în listele lungi de use

Când lucrăm cu numeroase elemente definite în același crate sau în același modul, este obositor și consumator de spațiu să le listăm pe fiecare în parte pe linii separate. Să luăm ca exemplu jocul Ghicitoarea din Listarea 2-4, unde am folosit două declarații use pentru a importa elemente din std în domeniul nostru de vizibilitate:

Numele fișierului: src/main.rs

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

În loc de aceasta, putem utiliza căi îmbinate pentru a aduce aceleași elemente în domeniul de vizibilitate într-o singură linie. Acest lucru se face prin specificarea părții comune a căii, continuată cu două puncte și cu acolade ce îngrădesc părțile diferite ale căilor. Acest concept este prezentat in Listarea 7-18.

Numele fișierului: src/main.rs

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

Listarea 7-18: Utilizarea unei căi îmbinate pentru a importa mai multe elemente cu același prefix în domeniul de vizibilitate

În cadrul programelor mari, tehnica importării unui număr mare de elemente din același crate sau modul prin căi îmbinate poate reduce considerabil numărul de declarații use separate.

O cale îmbinată poate fi utilizată la orice nivel într-o cale, fapt util atunci când dorim să combinăm două declarații use care au o sub-cale comună. De exemplu, Lista 7-19 ne arată două declarații use: una ce aduce std::io în domeniul de vizibilitate și una care aduce std::io::Write în domeniul de vizibilitate.

Numele fișierului: src/lib.rs

use std::io;
use std::io::Write;

Listarea 7-19: Două declarații use cu o sub-cale comună

Pentru a combina cele două căi într-o singură declarație use, folosim self în cadrul căii îmbinate, așa cum vedem în Listarea 7-20.

Numele fișierului: src/lib.rs

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

Listarea 7-20: Combinarea căilor din Lista 7-19 într-o singură declarație use

În urma acestei operațiuni, std::io și std::io::Write sunt aduse în domeniul de vizibilitate.

Utilizarea operatorului * (glob)

Daca dorim să includem toate elementele publice definite printr-o anumită cale în domeniul nostru de vizibilitate, atunci trebuie sa utilizăm calea dorită completată cu operatorul *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Această instrucțiune use face ca toate elementele publice definite în std::collections să fie disponibile în domeniul de vizibilitate actual. Trebuie să fim prudenți când utilizăm operatorul *! Ne poate face dificilă identificarea numelor care sunt în domeniul de vizibilitate și localizarea locului unde a fost definit un nume folosit în programul nostru.

De obicei, utilizăm operatorul * atunci când realizăm teste pentru a include totul în modulul tests. Vom aborda acest subiect în secțiunea „Cum să scriem teste” din Capitolul 11. De asemenea, uneori operatorul * face parte din pattern-ul 'preludiu'. Poți accesa documentația bibliotecii standard pentru a afla mai multe detalii despre acest pattern.

Separarea modulelor în diferite fișiere

Toate exemplele prezentate până acum în acest capitol au învățat cum să definim mai multe module într-un singur fișier. Când modulele devin mai complexe, ai putea dori să separi definițiile acestora în fișiere diferite pentru a naviga mai ușor prin cod.

Ca punct de plecare, vom lua codul din Listarea 7-17 care conține multiple module restaurant. Scopul este să extragem modulele în diferite fișiere, în loc să le păstrăm toate în fișierul rădăcină al crate-ului. În cazul de față, fișierul rădăcină este src/lib.rs. Cu toate acestea, același proces se aplică și crate-urilor binare, unde fișierul rădăcină este src/main.rs.

Începem prin a delega modulul front_of_house în propriul fișier. Pentru asta, eliminăm codul din interiorul acoladelor modulului front_of_house, lăsând doar declarația mod front_of_house;. Astfel, src/lib.rs va conține codul prezentat în Listarea 7-21. Atenție: acest cod nu va putea fi compilat până când nu vom crea fișierul src/front_of_house.rs, așa cum este prezentat în Listarea 7-22.

Numele fișierului: src/lib.rs

{{#includefile_rustdoc ../lista/ch07-gestionand-proiecte-in-crestere/listare-07-21-si-22/src/lib.rs}}

Listarea 7-21: Declararea modulului front_of_house care va fi conținut în src/front_of_house.rs

În etapa următoare, trebuie să mută codul din interiorul acoladelor într-un fișier nou, numit src/front_of_house.rs, conform Listării 7-22. Compilatorul va găsi acest fișier datorită declarației de modul din rădăcina crate-ului, unde se specifică numele front_of_house.

Numele fișierului: src/front_of_house.rs

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Listarea 7-22: Definim anumite aspecte în interiorul modulului front_of_house localizat în src/front_of_house.rs

Reține că trebuie să încarci un fișier folosind o declarație mod o singură dată în arborele tău de module. Odată ce compilatorul este informat că fișierul aparține proiectului (și cunoaște locul în care se găsește codul datorită poziției declarației mod ), restul fișierelor din proiect trebuie să se refere la codul fișierului încărcat utilizând o cale spre locul declarării acestuia. Această metodă este descrisă în secțiunea „Cum să referi un element în structura modulelor”. În cuvinte mai simple, mod nu este o comandă de "include", așa cum este utilizată în alte limbaje de programare.

Următorul pas va fi mutarea modulului hosting în propriul său fișier. Procesul este ușor diferit deoarece hosting este un submodul al front_of_house, nu un modul rădăcină. Noua locație a fișierului va fi un nou directoriu, care va purta numele submodulului în structura de module - în cazul nostru, src/front_of_house/.

Pentru mutarea hosting, modificăm src/front_of_house.rs pentru a găzdui doar declarația modulului hosting:

Numele fișierului: src/front_of_house.rs

pub mod hosting;

Apoi, creăm directoriul src/front_of_house și fișierul hosting.rs, care va conține definițiile din cadrul modulului hosting:

Numele fișierului: src/front_of_house/hosting.rs

pub fn add_to_waitlist() {}

Daca am plasa hosting.rs în directoriul src, compilatorul s-ar aștepta ca fișierul hosting.rs să fie un modul rădăcină hosting din structura proiectului, și nu un submodul al front_of_house. Regulile interne ale compilatorului referitoare la asocierea fișierelor cu modulele specifice fac ca structura de directorii și fișiere să urmeze cu exactitate structura de module.

Căi alternative de fișiere

Până în prezent, am discutat despre căile de fișiere cel mai des utilizate în Rust, dar trebuie să știi că acest limbaj de programare acceptă și un stil mai vechi de definire a acestora. Să luăm exemplul unui modul numit front_of_house, pe care îl avem declarat la rădăcina unui crate - compilatorul Rust va căuta codul acestuia în următoarele locații:

• src/front_of_house.rs (am discutat deja despre aceasta)
• src/front_of_house/mod.rs (o variantă mai veche, care este încă acceptată)

Referitor la un modul numit hosting, definit ca submodul al front_of_house, compilatorul va căuta codul său în:

• src/front_of_house/hosting.rs (am menționat deja acesta)
• src/front_of_house/hosting/mod.rs (încă o versiune veche, încă valabilă)

Dacă alegi să utilizezi ambele stiluri pentru același modul, vei obține o eroare din partea compilatorului. Deși ești liber să utilizezi o combinație a celor două stiluri pentru diferite module din același proiect, aceasta ar putea genera confuzii pentru cei care explorează proiectul.

Unul dintre dezavantajele metodei care implică utilizarea de fișiere numite mod.rs este că proiectul poate ajunge să conțină un număr mare de astfel de fișiere, ceea ce poate fi confuz atunci când le avem deschise simultan în editor.

Noutatea este că acum avem codul fiecărui modul într-un fișier separat, dar structura modulelor în sine nu s-a schimbat. Chiar dacă acum definițiile lor se află în fișiere diferite, apelurile funcției în eat_at_restaurant vor funcționa în mod normal, fără a necesita vreo modificare. Aceasta ne permite să mutăm modulele în fișiere noi pe măsură ce acestea se măresc în dimensiune.

Observăm că linia pub use crate::front_of_house::hosting din src/lib.rs nu a fost afectată, la fel cum nici folosirea cuvântului cheie use nu influențează fișierele care sunt compilate ca parte a crate-ului. Cuvântul cheie mod este folosit pentru a declara module, iar Rust va căuta codul acestora în fișiere care au același nume precum modulul în sine.

Sumar

Rust îți oferă posibilitatea de a diviza un pachet în crate-uri multiple și un crate în diverse module. Acest lucru permite referirea la elemente definite într-un anumit modul dintr-un altul. Această acțiune poate fi realizată prin specificarea unor căi absolute sau relative. Cu ajutorul instrucțiunii use, aceste căi pot fi aduse în domeniul de vizibilitate, permițând astfel un acces mai rapid și mai eficient. Deși codul unui modul este inițial privat, acesta poate fi făcut public adăugând termenul pub.

În capitolul următor, vom explora unele structuri de colecție din librăria standard, pe care le vei putea folosi în codul tău bine organizat.

Colecțiile comune în Rust

Biblioteca standard Rust ne pune la dispoziție o serie de structuri de date foarte utile, denumite generic colecții. Spre deosebire de celelalte tipuri de date care reprezintă o singură valoare, colecțiile pot stoca multiple valori. În plus, nu ca tipurile native array și tuplă, datele la care se referă aceste colecții sunt stocate în heap, deci volumul acestora nu trebuie să fie cunoscut în momentul compilării și poate varia pe parcursul execuției programului. Fiecare tip de colecție vine cu propriile sale capabilități și costuri asociate, așadar selectarea celei potrivite pentru situația curentă este o abilitate care se dezvoltă în timp. În acest capitol ne vom concentra pe trei colecții foarte utilizate în programele Rust:

• Vectorul ne permite stocarea unui număr variabil de valori alături.
• String-ul reprezintă o colecție de caractere. Deși am menționat anterior tipul String, în acest capitol îl vom aborda în profunzime.
• O hartă hash ne dă posibilitatea de a asocia o valoare cu o cheie specifică, fiind un caz particular de implementare a structurii de date denumite map.

Consultează documentația pentru a afla despre celelalte tipuri de colecții disponibile în biblioteca standard.

Vom discuta despre cum putem crea și actualiza vectori, string-uri și hărți hash, precum și despre ce caracteristici unice are fiecare.

Păstrarea listelor de valori folosind vectori

Primul tip de colecție pe care îl vom discuta se numește Vec<T>, cunoscut mai bine ca vector. Vectorii ne permit să păstrăm mai multe valori într-o singură structură de date care plasează toate valorile una lângă alta în memorie. Un aspect important este că vectorii pot conține doar valori de același tip. Aceștia se dovedesc a fi foarte utili când ai o listă de elemente, precum liniile de text dintr-un fișier sau prețurile produselor dintr-un coș de cumpărături.

Crearea unui vector nou

Pentru a crea un vector nou și gol, utilizăm funcția Vec::new, după cum urmează în Listarea 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Listarea 8-1: Crearea unui vector nou și gol pentru valori de tip i32

Aici am adăugat o adnotare de tip deoarece nu introducem valori și Rust nu poate deduce tipul elementelor pe care dorim să le stocăm. Acest aspect este crucial. Vectorii sunt construiți folosind generice, iar utilizarea genericelor cu tipurile proprii le vom explora în Capitolul 10. Până atunci, este important să știi că tipul Vec<T> din biblioteca standard poate conține orice alt tip. Când inițializăm un vector pentru un anumit tip, specificăm acest tip între paranteze unghiulare. În Listarea 8-1, i-am indicat lui Rust că Vec<T> de la variabila v va conține elemente de tip i32.

De obicei, cel mai frecvent vei inițializa vectorii Vec<T> cu valori specifice și Rust va infera automat tipul de date pe care dorești să-l stochezi. Prin urmare, este rar necesar să oferi adnotări de tip. Rust oferă macro-ul vec!, care te ajută să creezi direct un vector nou cu valorile specificate. Listarea 8-2 arată cum să creezi un Vec<i32> care stochează valorile 1, 2 și 3. Tipul de date pentru întregi este i32, conform predefinirii pentru tipul întreg, așa cum am discutat în secțiunea „Tipuri de date” din Capitolul 3.

fn main() {
    let v = vec![1, 2, 3];
}

Listarea 8-2: Crearea unui vector nou care include anumite valori

Deoarece am furnizat valori inițiale de tip i32, Rust poate determina că v este de tipul Vec<i32>, așadar adnotarea de tip nu este necesară. Următorul pas este să învățăm cum putem modifica un vector.

Actualizarea unui vector

Pentru a crea un vector și a-i adăuga elemente, putem utiliza metoda push. Urmărește exemplul din Listarea 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Listarea 8-3: Adăugarea valorilor într-un vector folosind metoda push

Dacă vrem să modificăm o variabilă, trebuie să o declarăm ca fiind mutabilă, utilizând cuvântul cheie mut, după cum am explicat în Capitolul 3. Toate numerele inserate sunt de tip i32. Rust înțelege acest lucru automat din datele furnizate, astfel încât nu este necesară specificarea explicită a tipului Vec<i32>.

Accesarea elementelor din vectori

Există două modalități prin care poți referenția o valoare stocată într-un vector: prin indexare sau utilizând metoda get. Pentru claritate, în exemplele următoare am specificat tipurile valorilor returnate de aceste două funcții.

În Listarea 8-4, sunt ilustrate ambele metode de accesare a unei valori dintr-un vector - prin indexare directă și folosind metoda get.

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

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

Listarea 8-4: Accesarea unui element dintr-un vector folosind sintaxa de indexare sau metoda get

Aici trebuie să remarcăm anumite detalii. Folosim indicele 2 pentru a ajunge la al treilea element, având în vedere că vectorii sunt indexați începând cu zero. Operatorul & împreună cu [] ne oferă o referință către elementul situat la indicele specificat. Când apelăm metoda get cu un indice ca argument, primim o variantă Option<&T>, pe care putem să o utilizăm într-o instrucțiune match.

Rust ne oferă aceste două metode de referențiere astfel încât să putem alege cum dorești să răspundă programul atunci când accesăm un indice din afara limitelor vectorului. Să luăm un exemplu: ce se întâmplă dacă avem un vector cu cinci elemente și încercăm să accesăm un element la indicele 100 folosind fiecare metodă, așa cum vedem în Listarea 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);
}

Listarea 8-5: Tentativa de a accesa elementul la indicele 100 dintr-un vector cu cinci elemente

Rulând acest cod, prima metodă, cea cu [], va provoca o eroare fără recuperare (panică), din cauza referinței la un element inexistent. Această methodă e utilă când vrem ca programul să se oprească în cazul unei tentative de a accesa un element dincolo de capătul vectorului.

Pe de altă parte, când metoda get primește un indice ce depășește limitele vectorului, aceasta returnează None fără a genera o panică. Ai alege această cale dacă posibilitatea unui acces la un indice în afara vectorului aparține situațiilor normale în aplicația ta. Astfel, codul va include logica de tratare a cazurilor atunci când rezultatul e Some(&element) sau None, după cum am analizat în Capitolul 6. De exemplu, un utilizator poate introduce accidental un număr prea mare, iar programul ar returna None. În acest caz, ai putea să-l informezi despre numărul de elemente din vector și să-i oferi o nouă șansă pentru a introduce un număr valabil, o soluție mult mai favorabilă decât închiderea programului.

Atunci când avem o referință valabilă, verificatorul de împrumut verifică regulile de proprietate și împrumut (abordate în Capitolul 4), pentru a se asigura că această referință, precum și orice alte referințe la conținutul vectorului, sunt valide. Amintește-ți de regula importantă care impune că nu poți deține referințe mutabile și imutabile simultan. Această regulă este ilustrată în Listarea 8-6, unde avem o referință imutabilă la primul element din vector, iar în același timp încercăm să adăugăm un element la final. Programul nu va funcționa dacă apoi încercăm să accesăm din nou acel element:

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

Listarea 8-6: Încercarea de adăugare a unui element la vector în timp ce există o referință către un element al său

Compilarea acestui cod va genera următoarea eroare:

$ 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` due to previous error

Poate părea surprinzător că acest cod generează o eroare, deoarece te-ai putea întreba de ce o referință la primul element ar fi afectată de modificările produse la capătul vectorului. Motivul erorii este legat de cum vectorii își gestionează memoria: adăugând un nou element, poate fi necesară alocarea unui nou segment de memorie și copierea elementelor vechi în acesta, dacă spațiul actual nu este suficient. Într-o astfel de situație, referința la primul element ar indica spre memorie care a fost eliberată. Regulile de împrumut împiedică astfel de situații neplăcute.

Notă: Pentru mai multe detalii despre implementarea tipului Vec<T>, poți consulta “The Rustonomicon”.

Iterând prin elementele unui vector

Pentru a accesa elementele unui vector rând pe rând, cel mai eficient este să folosim o iterație completă, decât să accesăm elementele individual prin indici. Listarea 8-7 demonstrează modul în care putem utiliza un ciclu for pentru a parcurge un vector de valori de tip i32, obținând referințe imutabile la fiecare element și afișându-le.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

Listarea 8-7: Afișarea fiecărui element al unui vector prin iterare cu ajutorul unui ciclu for

Este posibil să iterăm și prin referințe mutabile ale elementelor unui vector mutabil, pentru a modifica toate elementele acestuia. Ciclul for din Listarea 8-8 adaugă 50 la valoarea fiecărui element.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Listarea 8-8: Iterarea prin referințe mutabile ale elementelor dintr-un vector

Pentru a modifica valoarea la care se referă o referință mutabilă, folosim operatorul de dereferențiere * pentru a accesa valoarea efectivă din i înainte să aplicăm operatorul +=. Vom discuta mai detaliat despre operatorul de dereferențiere în secțiunea "Urmărind pointer-ul până la valoare cu ajutorul operatorului de dereferențiere"deref din Capitolul 15.

Iterația printr-un vector, fie că face acces imutabil sau mutabil, este sigură datorită regulilor impuse de verificatorul de împrumuturi. Dacă încercăm să adăugăm sau să eliminăm elemente în timpul execuției unui ciclu for, așa cum se face în Listările 8-7 și 8-8, ne vom confrunta cu o eroare de compilare similară cu cea întâmpinată în Listarea 8-6. Referința la vector menținută de ciclul for previne orice modificare simultană asupra întregului vector.

Folosirea unui enum pentru a combina mai multe tipuri într-un vector

Vectorii sunt limitați la stocarea valorilor de același tip, ceea ce poate fi restrictiv în anumite situații. Spre norocul nostru, variantele unui enum sunt grupate sub același tip de enum, permițându-ne să folosim un singur enum pentru a reprezenta elemente de tipuri diferite. Așadar, atunci când dorim să combinăm diverse tipuri într-o singură structură, putem apela la un enum!

Să presupunem că dorim să extragem valori dintr-un rând al unui tabel, unde coloanele acelui rând conțin întregi, numere în virgulă mobilă sau string-uri. Ne putem defini un enum cu variante pentru fiecare tip de valoare, iar aceste variante de enum vor fi considerate același tip: tipul enum-ului în sine. Putem crea apoi un vector care să păstreze acest enum și, în final, să cuprindă tipuri variate. Acest concept este ilustrat în Listarea 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Listarea 8-9: Crearea unui enum pentru stocarea valorilor de diferite tipuri într-un vector

Rust trebuie să cunoască de la momentul compilării ce tipuri vor fi incluse în vector, astfel încât să aloce în mod corespunzător memoria necesară pe heap pentru fiecare element. De asemenea, trebuie să specificăm în mod explicit care tipuri sunt acceptate în vector. Dacă Rust ar permite unui vector să conțină orice tip, ar exista riscul ca unele tipuri să genereze erori în momentul operațiilor executate asupra elementelor. Utilizând un enum în combinare cu o expresie match, Rust garantează la compilare că fiecare caz posibil este luat în considerație, conform discuției din Capitolul 6.

Dacă nu știm dinainte toate tipurile de date cu care programul nostru va opera la executare, abordarea cu enum nu este aplicabilă. Ca alternativă, se poate folosi un obiect de tip trăsătură, subiect pe care îl vom aborda în Capitolul 17.

După ce am explorat unele dintre cele mai frecvente utilizări ale vectorilor, te încurajez să consulți documentația API pentru a descoperi multitudinea de metode utile definite pentru Vec<T> de către biblioteca standard. De exemplu, pe lângă metoda push, există și metoda pop, care elimină și returnează ultimul element din vector.

Un vector își eliberează elementele la distrugere

Ca orice struct, un vector este eliberat automat când domeniul său de vizibilitate se încheie, după cum vedem în Listarea 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

Listarea 8-10: Ilustrarea punctelor unde vectorul și elementele sale sunt eliberate

Eliberarea unui vector implică și curățarea tuturor elementelor sale; în cazul nostru, numerele întregi vor fi de asemenea eliminate. Verificatorul de împrumuturi se asigură că referințele la elementele vectorului sunt folosite numai atât timp cât vectorul respectiv este în vigoare.

Acum să ne îndreptăm atenția spre următorul tip de colecție: String!

Manipularea textelor codate UTF-8 utilizând string-uri

Am introdus noțiunile despre string-uri în Capitolul 4, dar acum vom aprofunda subiectul. Utilizatorii noi de Rust au adesea dificultăți cu string-urile din cauza unei combinații a trei aspecte: abordarea Rust de a evidenția posibilele greșeli, complexitatea neașteptată a string-urilor ca structură de date și particularitățile codării UTF-8. Toate acestea pot crea provocări, mai ales pentru cei veniți din alte limbaje de programare.

Vorbim despre string-uri în cadrul temei colecțiilor pentru că, în esență, un string este o colecție de octeți (bytes), completată de metode care facilitează lucrul cu textul. În această secțiune, ne vom concentra pe operațiunile comune oricărui tip de colecție, care se aplică și pentru String: cum le creăm, le actualizăm și le citim. Vom discuta și despre caracteristicile care diferențiază String de alte tipuri de colecții, concentrându-ne în special pe complexitatea indexării într-un String, dată de modul diferit în care oamenii și calculatoarele procesează informația dintr-un String.

Ce este un string?

Să clarificăm ce înțelegem noi prin "string". În limbajul Rust, există un singur tip fundamental de string, anume secțiunea de string - str, care de obicei apare sub forma împrumutată &str. În Capitolul 4, am abordat conceptul de secțiuni de string, care reprezintă referințe la date de tip string codificate în UTF-8 și stocate în altă parte. Spread exemplu, literalele de string sunt incluse în fișierul binar al programului, motiv pentru care sunt considerate secțiuni de string.

Pe de altă parte, avem tipul String, oferit de biblioteca standard a limbajului Rust și nu parte integrantă a nucleului limbajului. Acesta este un tip de string extensibil, mutabil, cu proprietate asupra datelor și codificat în UTF-8. Când vorbim despre "string-uri" în Rust, ne referim atât la tipul String, cât și la secțiunile de string &str, nu exclusiv la unul dintre ele. Deși accentul acestei secțiuni este pe String, ambele forme sunt fundamentale în biblioteca standard și, atât String, cât și secțiunile de string respectă codificarea UTF-8.

Crearea unui string nou

Operațiunile pe care le facem cu Vec<T> pot fi aplicate și pe String, deoarece String este efectiv o încapsulare peste un vector de octeți, având anumite garanții suplimentare, restricții și funcționalități. Să luăm drept exemplu funcția new, care ne permite să creăm o nouă instanță de String, ilustrată în Listarea 8-11.

fn main() {
    let mut s = String::new();
}

Listarea 8-11: Crearea unui String gol

Această linie de cod creează un String nou și gol, pe nume s, în care putem încărca date ulterior. Adesea avem date inițiale pe care dorim să le folosim pentru a popula string-ul. Pentru acest caz folosim metoda to_string, disponibilă pentru orice tip ce implementează trăsătura Display, așa cum fac literalele string. Listarea 8-12 prezintă două exemple.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // the method also works on a literal directly:
    let s = "initial contents".to_string();
}

Listarea 8-12: Crearea unui String dintr-un literal string folosind metoda to_string

Codul de mai sus generează un string ce conține textul initial contents.

Putem folosi, de asemenea, funcția String::from pentru a crea un String pornind de la un literal string. Codul din Listarea 8-13 este similar celui din Listarea 8-12, care a utilizat to_string.

fn main() {
    let s = String::from("initial contents");
}

Listarea 8-13: Utilizarea funcției String::from pentru a obține un String dintr-un literal string

Având în vedere numărul mare de aplicații ale string-urilor, există multe API-uri generice pentru lucrul cu acestea, oferindu-ne o varietate mare de opțiuni. Unele dintre acestea par redundante, dar fiecare își are rostul său! În acest caz, String::from și to_string îndeplinesc aceeași funcție, astfel alegerea dintre cele două este bazată mai mult pe preferințe de stil și claritate.

Rețineți că string-urile sunt codate în UTF-8, astfel orice date codate adecvat pot fi inclusă în acestea, așa cum este demonstrat în Listarea 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");
}

Listarea 8-14: Salvarea mesajelor de salut în diferite limbi în string-uri

Toate acestea reprezintă valori String corecte.

Actualizarea unui string

Un String poate să se extindă și să-și schimbe conținutul, similar cu Vec<T>, atunci când adaugi mai multe date. De asemenea, e simplu să concatenezi valori String folosind operatorul + sau macro-ul format!.

Adăugând la un string cu push_str și push

Un String poate fi mărit adăugând o secțiune de string cu ajutorul metodei push_str, așa cum vedem în Listarea 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

Listarea 8-15: Adăugarea unei secțiuni de string la un String cu push_str

După aceste operațiuni, s va conține foobar. Metoda push_str primește o secțiune de string pentru că nu dorește, de obicei, să preia controlul acestuia. De exemplu, în exemplul din Listarea 8-16, vrem ca s2 să fie utilizabil și după ce l-am concatenat cu s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Listarea 8-16: Utilizarea unei secțiuni de string după ce a fost adăugată la un String

Dacă metoda push_str ar fi solicitat posesiunea asupra lui s2, nu am fi putut afișa valoarea acestuia la sfârșit. Însă, codul funcționează cum ne-am așteptat!

Metoda push acceptă un caracter și îl adaugă la String. În Listarea 8-17, adăugăm litera "l" la un String folosind push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

Listarea 8-17: Adăugarea unui caracter la un String cu push

Rezultatul va fi că s va conține lol.

Concatenarea cu operatorul + sau macro-ul format!

Adesea, ai nevoie să unifici două string-uri existente. Poți face asta folosind operatorul +, cum este arătat în Listarea 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

Listarea 8-18: Utilizarea operatorului + pentru a concatena două valori de tip String într-una nouă

String-ul s3 va conține textul Hello, world!. După această operație, s1 nu mai este valid, iar motivul pentru care am utilizat o referință la s2 este legat de semnătura metodei add, apelată prin operatorul +. Iată cum arată semnătura:

fn add(self, s: &str) -> String {

Deși în biblioteca standard add este definit cu generice, noi am folosit tipuri specifice pentru a putea explica. Acest lucru se întâmplă automat când invoci metoda cu valori de tip String. Vom detalia genericele în Capitolul 10. Semnătura ne oferă indicii pentru a demistifica operatorul +.

Mai întâi, observăm că s2 este precedat de &, ceea ce indică faptul că adăugăm o referință la al doilea string. Aceasta este necesar, deoarece funcția add acceptă doar o referință &str pentru concatenare, nu două valori de tip String. Dar de ce funcționează codul din Listarea 8-18, având în vedere că &s2 este de fapt de tip &String şi nu &str?

Explicația este că compilatorul poate converti &String la &str prin intermediul unei coerciții de dereferențiere. Când apelăm metoda add, &s2 este convertit la &s2[..]. Aflăm mai multe despre aceasta în Capitolul 15. Deoarece add nu preia posesiunea parametrului s, s2 rămâne un String valid după operație.

În al doilea rând, add preia posesiunea lui self, care nu este marcat cu un &. Acest lucru înseamnă că s1 va fi consumat de apelul add și nu va mai putea fi folosit în continuare. Prin urmare, instrucțiunea let s3 = s1 + &s2; poate părea că doar copiază string-urile pentru a crea unul nou, dar, de fapt, preia s1, adaugă la el conținutul copiat din s2, și returnează noua valoare. Astfel, în loc să efectueze multe copieri inutile, operația este de fapt mai eficientă.

Pentru concatenarea mai multor string-uri, folosirea operatorului + poate deveni incomodă:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

Aici, s va fi tic-tac-toe. Însă, cu atâtea + și ", codul devine încărcat și greu de urmărit. Pentru cazuri mai complexe, putem apela la macro-ul format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Acest fragment de cod atribuie tot tic-tac-toe pentru s. Macro-ul format!, similar cu println!, nu afișează rezultatul pe ecran, ci returnează un String cu conținutul formatat. Varianta cu format! este clar mai lizibilă și nu preia posesiunea niciunui parametru, lucru de preferat în anumite contexte.

Accesarea elementelor unui string prin index

Accesul la caracterele unui string folosind indexul lor este o practică obișnuită în multe limbaje de programare. Cu toate acestea, în Rust, încercarea de a accesa elemente dintr-un String prin indexare va genera o eroare. Iată codul incorect prezentat în Listarea 8-19.

fn main() {
    let s1 = String::from("hello");
    let h = s1[0];
}

Listarea 8-19: Tentativa de utilizare a indexării cu un String

Executarea acestui cod va produce următoarea eroare:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `String` cannot be indexed by `{integer}`
 --> src/main.rs:3:13
  |
3 |     let h = s1[0];
  |             ^^^^^ `String` cannot be indexed by `{integer}`
  |
  = help: the trait `Index<{integer}>` is not implemented for `String`
  = help: the following other types implement trait `Index<Idx>`:
            <String as Index<RangeFrom<usize>>>
            <String as Index<RangeFull>>
            <String as Index<RangeInclusive<usize>>>
            <String as Index<RangeTo<usize>>>
            <String as Index<RangeToInclusive<usize>>>
            <String as Index<std::ops::Range<usize>>>

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` due to previous error

Mesajul de eroare explică problema: string-urile din Rust nu permit folosirea indexării. De ce se întâmplă asta? Pentru a înțelege motivul, trebuie să discutăm despre modul în care Rust gestionează string-urile în memorie.

Structura internă a unui string

Un String este practic un Vec<u8>. Să analizăm câteva exemple de string-uri corect codificate în UTF-8 din Listarea 8-14. Începem cu exemplul acesta:

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

Aici, len va fi 4, ceea ce înseamnă că vectorul care păstrează string-ul "Hola" are o lungime de 4 bytes. Fiecare literă ocupă 1 byte în codificarea UTF-8. Totuși, următoarea linie te poate surprinde. (Observă că acest string începe cu litera mare chirilică Ze, nu numărul 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");
}

La întrebarea despre lungimea string-ului, ai putea răspunde că este de 12. În realitate, Rust îți spune că este 24: acesta este numărul de bytes necesari pentru a codifica "Здравствуйте" în UTF-8. Acest lucru se datorează faptului că fiecare valoare scalară Unicode în acel string ocupă 2 bytes. Așadar, un indice al octeților string-ului nu corespunde întotdeauna unei valori scalare Unicode valide. Ca exemplu, iată un cod Rust incorect:

let hello = "Здравствуйте";
let answer = &hello[0];

Știm că answer nu va fi З, prima literă. În codificarea UTF-8, primul byte pentru З este 208, iar al doilea este 151. Prin urmare, ai putea crede că answer ar trebui să fie 208, dar 208 nu reprezintă un caracter valid de sine stătător. Acest rezultat nu este probabil ceea ce un utilizator ar aștepta când solicită prima literă a string-ului; în orice caz, Rust nu are la dispoziție alte date la indicele de byte zero. În general, utilizatorii nu doresc valoarea octetului în sine, chiar dacă string-ul constă doar din litere latine: dacă &"hello"[0] ar fi un cod valid care returnează valoarea octetului, acesta ar returna 104, nu h.

Concluzia este că pentru a evita generarea unei valori neașteptate și introducerea de bug-uri ce ar putea rămâne nedetectate pentru o perioadă, Rust alege să nu compileze acest cod deloc, prevenind astfel confuziile încă din fazele incipiente ale dezvoltării software.

Octeți, valori scalare și grupuri de grafeme

Un alt aspect legat de UTF-8 este faptul că există trei moduri în care Rust consideră string-urile: ca octeți, valori scalare, și grupuri de grafeme (cel mai apropiat termen pentru ceea ce numim "litere").

De exemplu, cuvântul hindi "नमस्ते" scris în scriptul Devanagari este stocat ca un vector de valori u8 în felul următor:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Acestea sunt 18 octeți și reprezintă modul în care calculatoarele stochează aceste date. Privindu-le ca valori scalare Unicode, care sunt reprezentate de tipul char în Rust, acești octeți arată astfel:

['न', 'म', 'स', '्', 'त', 'े']

Avem aici șase valori char, dar a patra și a șasea nu reprezintă litere: ele sunt diacritice fără sens de sine stătător. În final, dacă le privim ca grupuri de grafeme, obținem cele patru "litere" care formează cuvântul hindi:

["न", "म", "स्", "ते"]

Rust oferă diferite metode de interpretare a datelor brute ale unui string pentru ca fiecare program să își poată alege abordarea necesară, indiferent de limba umană în care sunt datele.

Un motiv suplimentar pentru care Rust nu permite indexarea unui String pentru a extrage un caracter este că se așteaptă ca operațiile de indexare să se efectueze într-un timp constant (O(1)). Dar acest lucru nu poate fi garantat cu String, deoarece Rust ar trebui să parcurgă conținutul de la început până la index pentru a identifica numărul de caractere valide.

Secționarea string-urilor

A accesa un string folosind indici este adesea nerecomandat deoarece nu este clar ce tip de valoare ar trebui să returneze operația de indexare: un octet, un caracter, un cluster de grafeme sau o secțiune de string. Din acest motiv, Rust necesită specificații mai exacte atunci când vrei să folosești indici pentru a obține secțiuni de string.

În loc să te bazezi pe [] cu un singur număr, este posibil să utilizezi [] cu un diapazon pentru a crea o secțiune ce include anumiți octeți:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

În exemplul de mai sus, s este un &str care cuprinde primii 4 octeți din string. Anterior, am menționat că fiecare caracter este reprezentat de 2 octeți, deci s va conține Зд.

Dacă am încerca să extragem doar o parte a octeților unui caracter, cum ar fi cu &hello[0..1], Rust va genera o eroare la rulare asemănătoare celei întâmpinate când se accesează un index invalid într-un array:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished dev [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`
thread 'main' panicked at 'byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`', src/main.rs:4:14
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Utilizează cu atenție diapazoanele când creezi secțiuni de string, deoarece acest lucru poate duce la erori grave în timpul execuției programului.

Metode de iterație pentru string-uri

Când lucrezi cu părți din string-uri, e important să specifici clar dacă dorești să accesezi caractere sau octeți. Dacă ai nevoie de valori scalare Unicode individuale, folosește metoda chars. Dacă aplici chars pe textul “Зд”, vei obține două valori de tip char, pe care le poți parcurge prin iterare pentru a accesa fiecare caracter:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Acest exemplu de cod va afișa caracterele:

З
д

Pe de altă parte, metoda bytes îți returnează octeții individuali ai textului, ceea ce poate fi util în anumite scenarii:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Acest cod va afișa cei patru octeți care formează textul dat:

208
151
208
180

Este important să ții minte că o valoare scalară validă în Unicode poate fi alcătuită din mai mulți octeți.

Extragerea clusterelor de grafeme din string-uri, cum ar fi cele din scrierea Devanagari, este o operație complexă și, din acest motiv, nu este inclusă în biblioteca standard. Pentru această nevoie, poți găsi crate-uri specializate pe crates.io.

Simplitatea înșelătoare a string-urilor

Pentru a rezuma, lucrurile cu string-urile sunt complexe. Fiecare limbaj de programare alege diferit cum să îţi prezinte această complexitate. Rust optează pentru gestionarea corectă a datelor String ca opțiune standard în orice program Rust. Acest lucru înseamnă că trebuie să acorzi o atenție sporită procesării datelor UTF-8 din start. Această abordare scoate la iveală complexitatea string-urilor mai mult decât în alte limbaje, însă astfel, eviți întâmpinarea erorilor legate de caractere non-ASCII în etapele avansate de dezvoltare a proiectelor tale.

Partea încurajatoare este că biblioteca standard vine la pachet cu multe funcționalități, bazate pe String și &str, care sunt gândite să ajute la navigarea cu succes prin aceste complexități. Nu rata documentația, unde vei găsi metode valoroase cum ar fi contains, pentru căutarea într-un string, sau replace, pentru înlocuirea secțiunilor dintr-un string cu alte string-uri.

Acum, să ne îndreptăm atenția spre ceva mai simplu: hash map-urile!

Utilizarea hash map-urilor pentru a asocia chei cu valori

Ultima dintre colecțiile fundamentale pe care le vom discuta este hash map-ul. Structura HashMap<K, V> permite stocarea unei asocieri între chei de tipul K și valori de tipul V, printr-o funcție de hash care stabilește cum sunt așezate aceste chei și valori în memorie. Această structură de date este cunoscută în multe limbaje de programare sub diverse nume precum hash, map, object, hash table, dictionary sau associative array.

Hash map-urile sunt de mare ajutor atunci când dorești să accesezi datele folosind o cheie de orice tip, nu un index, cum este cazul la vectori. De exemplu, într-un joc, poți urmări scorul diferitelor echipe folosind un hash map în care cheile sunt numele echipelor, iar valorile sunt scorurile acestora. Astfel, cu numele unei echipe, poți să obții rapid scorul aferent.

În această secțiune, vom explora funcționalitățile de bază ale hash map-urilor, dar biblioteca standard oferă multe alte capabilități interesante asociate cu HashMap<K, V>. Pentru detalii suplimentare, te încurajăm să consulți documentația bibliotecii standard.

Cum să creezi un hash map nou

Pentru a inițializa un hash map gol, putem folosi metoda new și apoi adăugăm elemente prin metoda insert. În Listarea 8-20, monitorizăm scorurile a două echipe, denumite Blue și Yellow. Echipa Blue debutează cu 10 puncte, pe când Yellow începe jocul cu 50 de puncte.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Listarea 8-20: Inițializarea unui hash map nou și inserarea unor perechi cheie-valoare

Este important de observat că, înainte de toate, trebuie să includem HashMap în sfera noastră de lucru prin intermediul instrucțiunii use, din secțiunea de colecții a bibliotecii standard. Dintre cele trei tipuri principale de colecții, hash map-ul este cel mai rar utilizat, motiv pentru care nu este importat implicit în preludiul Rust. Hash map-urile beneficiază, de asemenea, de un suport mai limitat din partea bibliotecii standard - nu există, de exemplu, un macro predefinit pentru construirea acestora.

Similar vectorilor, hash map-urile păstrează datele în heap. Acest HashMap utilizează chei de tip String și valori de tip i32. Și, precum în cazul vectorilor, has hmap-urile sunt colecții omogene - toate cheile trebuie să fie de același tip și toate valorile de alt tip, dar uniform între ele.

Accesul la valorile dintr-un hash map

Noi putem extrage o valoare dintr-un hash map oferind cheia corespunzătoare metodei get, după cum se arată în Listarea 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Listarea 8-21: Obținerea scorului pentru echipa Albastră din hash map

În acest exemplu, variabila score va prelua valoarea asociată echipei Albastre, care va fi 10. Metoda get returnează Option<&V>, semnificând că dacă nu se află o valoare pentru cheia dată în hash map, get va oferi ca răspuns None. În acest program, opționalitatea este tratată prin folosirea metodei copied, care transformă Option<&i32> în Option<i32>, iar apoi, cu ajutorul metodei unwrap_or, setăm score la zero dacă hash map-ul scores nu conține o valoare pentru cheia respectivă.

Pentru a parcurge fiecare pereche cheie/valoare dintr-un hash map, noi putem folosi o abordare similară cu cea pentru vectori, aplicând o buclă for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Acest fragment de cod va afișa fiecare pereche într-o ordine aleatoare:

Galben: 50
Albastru: 10

Hash map-uri și posesiunea datelor

Când inserăm date într-un hash map, ce se întâmplă cu acestea depinde de tipul lor. Dacă tipul de date implementează trăsătura Copy, cum este cazul lui i32, atunci valorile sunt duplicate și inserate în hash map fără a-și pierde originalul. Pe de altă parte, pentru tipuri de date cu posesiune unică, precum String, inserarea înseamnă transferul posesiunii: hash map-ul devine noul proprietar al acestor valori. Următoarea listare ilustrează această comportare:

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

Listarea 8-22: Ilustrarea modului în care hash map-ul devine posesorul cheilor și valorilor după ce sunt inserate

După această operațiune de inserare, nu mai putem utiliza variabilele field_name și field_value; ele au fost permutate în hash map și acum hash map-ul deține drepturile asupra lor.

Dacă dorim să păstrăm drepturile asupra datelor și să inserăm doar referințe în hash map, va trebui să ne asigurăm că acele date originale rămân valabile pentru toată durata de viață a hash map-ului. Această temă este aprofundată în secțiunea despre „Validarea referințelor prin durate de viață”, pe care o vom explora în Capitolul 10.

Cum actualizăm un hash map

Deși numărul de perechi cheie-valoare dintr-un hash map poate crește, fiecare cheie unică poate avea atribuită o singură valoare în același timp (ceea ce nu este valabil și invers; spre exemplu, echipa Blue și echipa Yellow ar putea ambele să aibă valoarea 10 în hash map-ul scores).

Când dorești să schimbi datele dintr-un hash map, trebuie să alegi cum să procedezi atunci când o cheie are deja atribuită o valoare. Există câteva opțiuni: poți înlocui valoarea veche cu cea nouă, ignorând complet valoarea anterioară. Poți păstra valoarea veche și să ignori pe cea nouă, adăugându-o doar dacă cheia nu are încă o valoare asignată. Sau, poți combina valoarea veche cu cea nouă. Să explorăm cum putem aplica fiecare dintre aceste metode!

Înlocuirea unei valori

Când adăugăm într-un hash map o pereche de cheie și valoare, iar mai apoi inserăm din nou aceeași cheie cu o valoare diferită, valoarea asociată cu cheia respectivă va fi înlocuită. Chiar dacă în codul prezentat în Listarea 8-23 executăm funcția insert de două ori, hash map-ul va conține o singură pereche de cheie și valoare, deoarece ambele inserări se referă la cheia echipei Blue.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

    println!("{:?}", scores);
}

Listarea 8-23: Înlocuirea unei valori asociate cu o anumită cheie

Acest cod va afișa rezultatul {"Blue": 25}. Prima valoare, 10, a fost înlocuită cu noua valoare, 25.

Adăugarea unei chei și valori numai dacă cheia lipsește

Un scenariu frecvent în lucrul cu hash map-uri este verificarea prezenței unei chei specifice înainte de a adăuga o valoare. Dacă cheia este deja prezentă, valoarea existentă trebuie să rămână neschimbată. În caz contrar, cheia și valoarea ei trebuie inserate în map.

Pentru aceasta, hash map-urile oferă o metodă specială numită entry, care primește ca parametru cheia de verificat. Rezultatul metodei entry este o enumerare Entry care indică dacă o valoare există sau nu pentru acea cheie. De exemplu, dacă vrem să verificăm dacă echipa Yellow are o valoare atribuită cheii sale și, în caz negativ, să inserăm valoarea 50; procedăm similar pentru echipa Blue. Utilizând API-ul entry, codul arată ca în Listarea 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

    println!("{:?}", scores);
}

Listarea 8-24: Utilizarea metodei entry pentru a insera valori doar când cheia nu există

Metoda or_insert de pe Entry returnează o referință mutabilă la valoarea asociată cheii respective, dacă cheia există. Dacă nu, aceasta inserează valoarea primită ca parametru pentru cheia respectivă și returnează o referință mutabilă la noua valoare inserată. Această abordare este mult mai elegantă și mai eficientă decât să implementăm manual această logică, având și avantajul unei mai bune compatibilități cu verificatorul de împrumuturi.

Execuția codului din Listarea 8-24 va genera rezultatul {"Yellow": 50, "Blue": 10}. Prima invocare a metodei entry va adăuga cheia pentru echipa Yellow cu valoarea 50, deoarece aceasta nu are o valoare predefinită. Cea de-a doua invocare nu va modifica hash map-ul, deoarece echipa Blue dispune deja de valoarea 10.

Actualizarea unei valori în funcție de valoarea precedentă

Folosirea hash map-urilor pentru a actualiza valori pe baza celor anterioare este o practică obișnuită. De exemplu, în Listarea 8-25, codul prezentat numără cât de des apare fiecare cuvânt într-un text dat. Folosim un hash map cu cuvintele drept chei și creștem valoarea asociată pentru a contoriza numărul de apariții ale fiecărui cuvânt. Dacă întâlnim un cuvânt pentru prima dată, inserăm inițial valoarea 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{:?}", map);
}

Listarea 8-25: Numărarea aparițiilor cuvintelor cu ajutorul unui hash map care stochează cuvinte și contoare

Acest cod va rezulta în afișarea {"world": 2, "hello": 1, "wonderful": 1}. Însă, ordinea acestor perechi cheie/valoare ar putea fi diferită, deoarece, așa cum am menționat în secțiunea “Accesarea valorilor într-un hash map”, ordinea de iterație a unui hash map este întâmplătoare.

Metoda split_whitespace generează un iterator care oferă acces la sub-șirurile de caractere, separate prin spații, din text. Metoda or_insert furnizează o referință mutabilă (&mut V) la valoarea corespunzătoare cheii indicate. Stocăm această referință mutabilă în variabila count și, pentru a-i modifica valoarea, folosim dereferențierea cu ajutorul simbolului asterisc (*). Referința mutabilă își încheie domeniul de vizibilitate la finalul buclei for, astfel încât toate modificările sunt sigure și respectă regulile de împrumutare ale limbajului Rust.

Funcția de hash în HashMap

Implicit, HashMap folosește o funcție de hash denumită SipHash. Aceasta oferă protecție împotriva atacurilor cibernetice de tip Denial of Service (DoS) care vizează tabelele de hash. SipHash nu este neapărat cel mai rapid algoritm de hash, însă avantajele în ceea ce privește securitatea compensează pentru scăderea în performanță. Dacă, în urma analizei performanței codului tău, descoperi că funcția de hash standard este prea înceată, poți opta pentru un alt algoritm de hash alegând un hasher diferit. Un hasher este un tip de date ce implementează trăsătura BuildHasher. Vom explora conceptul de trăsături și implementarea acestora mai detaliat în Capitolul 10. Nu este obligatoriu să scrii un hasher de la zero; pe crates.io găsești biblioteci create de comunitatea Rust care includ hasheri cu o varietate de algoritmi de hash cunoscuți.

Sumar

Aflăm că vectorii, string-urile și hash map-urile sunt esențiali pentru manipularea și gestionarea datelor în programe. În continuare, vei avea prilejul să aplici cunoștințele dobândite prin rezolvarea următoarelor sarcini:

• În cazul unei liste de numere întregi, folosește un vector pentru a determina mediana (elementul din mijlocul listei sortate) și moda (elementul care apare de cele mai multe ori; un hash map va fi de ajutor aici).
• Transformă string-urile în pig latin în felul următor: mută prima consoană a fiecărui cuvânt la sfârșitul acestuia și adaugă sufixul "ay", ca în "first" care devine "irst-fay". Cuvintele ce încep cu vocală primesc sufixul "hay" la final ("apple" se transformă în "apple-hay"), având în vedere specificitățile codificării UTF-8.
• Utilizând un hash map și vectori, dezvoltă o interfață text prin care un utilizator poate adăuga nume de angajați la un anumit departament într-o firmă, de exemplu "Adaugă pe Sally în departamentul de Inginerie" sau "Adaugă pe Amir în departamentul de Vânzări". În plus, asigură posibilitatea de a obține lista angajaților unui departament sau lista completă a angajaților companiei, împărțită pe departamente, organizată alfabetic.

Documentația API a bibliotecii standard detaliază metodele disponibile pentru vectori, string-uri și hash map-uri, care îți vor fi utile pentru a completa aceste exerciții.

Pe măsură ce programarea se complică și operațiunile pot eșua, este esențial să învățăm despre gestionarea erorilor. Este subiectul pe care îl vom aborda în continuare!

Tratarea erorilor

În lumea dezvoltării software-ului, întâlnirea cu erori este inevitabilă. Din acest motiv, Rust include diverse mecanisme pentru a aborda situațiile în care lucrurile nu funcționează conform așteptărilor. Rust te forțează adesea să recunoști posibilitatea apariției unei erori și să iei măsuri corespunzătoare înainte ca codul să fie compilat. Această abordare îmbunătățește fiabilitatea programului tău, asigurându-te că vei identifica și gestiona erorile în mod adecvat înainte ca software-ul să ajungă în mediul de producție.

Rust clasifică erorile în două categorii principale: erori recuperabile și irecuperabile. În cazul unei erori recuperabile, cum ar fi "fișier negăsit", de obicei, dorim să informăm utilizatorul și să încercăm din nou acțiunea. Pe de altă parte, erorile irecuperabile indică prezența unor bug-uri, ca de exemplu o tentativă de acces la o zonă din afara limitelor unui array, caz în care este imperios să oprim programul de îndată.

Multe limbaje de programare nu fac distincție între aceste tipuri de erori și le abordează în același mod, adesea prin intermediul excepțiilor. Rust nu utilizează excepții. În schimb, oferă tipul Result<T, E> pentru gestionarea erorilor recuperabile și macro-ul panic! pentru situațiile irecuperabile, când execuția programului trebuie oprită de urgență. În acest capitol, vom începe prin a discuta folosirea panic! și apoi ne vom concentra pe întoarcerea valorilor de tip Result<T, E>. De asemenea, vom lua în considerare când este potrivit să recuperăm după o eroare și când este mai bine să întrerupem execuția.

Gestionarea erorilor irecuperabile cu panic!

În codul tău pot apărea situații neașteptate și iremediabile. Pentru aceste cazuri, Rust oferă macro-ul panic!. Poți declanșa o panică în două moduri: fie realizând o acțiune care duce la panică în codul nostru - de exemplu, accesând un array dincolo de capacitatea sa, fie apelând direct macro-ul panic!. Ambele variante vor provoca o panică în programul nostru care, implicit, va afișa un mesaj de eroare, va desface stiva, va efectua curățarea acesteia și va încheia execuția programului. Prin setarea unei variabile de mediu, poți de asemenea instrui Rust să afișeze stiva de apeluri în momentul unei panici, facilitând astfel identificarea cauzei problemei.

Gestionarea panicii: Dezactivarea stivei sau abandonarea programului

Implicit, când se declanșează o panică, programul începe procesul de dezactivare a stivei (unwinding): Rust urcă stiva invers și eliberează memoria ocupată de datele din fiecare funcție întâlnită. Totuși, acest procedeu este destul de laborios. De aceea, Rust îți oferă opțiunea de abandonare, care oprește programul direct, fără a elibera resursele utilizate. În acest caz, sistemul de operare va trebui să curețe memoria folosită de program. Dacă ai nevoie să minimizezi dimensiunea executabilului în proiectul tău, poți opta pentru încheierea abruptă a programului în caz de panică prin adăugarea liniei panic = 'abort' în secțiunile [profile] relevante din fișierul Cargo.toml. De exemplu, pentru a seta această opțiune în modul Release, inserează:

[profile.release]
panic = 'abort'

Să folosim panic! într-un program simplu:

Numele fișierului: src/main.rs

fn main() {
    panic!("crash and burn");
}

Când executăm programul, vom observa un mesaj similar cu acesta:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`
thread 'main' panicked at 'crash and burn', src/main.rs:2:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Utilizarea panic! generează mesajul de eroare afișat în ultimele două rânduri. Primul rând îți prezintă mesajul nostru de panică, precum și locul din sursa noastră unde panica a avut loc: src/main.rs:2:5 ne indică faptul că problema se află la linia a doua, caracterul cinci din fișierul nostru src/main.rs.

În exemplul nostru, linia indicată ne duce direct la codul scris de noi, unde găsim apelul macro-ului panic!. Cu toate acestea, uneori apelul panic! s-ar putea să fie în cod la care codul nostru face referire și atunci, numele fișierului și numărul liniei raportate de mesajul de eroare vor semnala locația din codul altei persoane unde a fost invocat panic!, nu punctul din codul nostru care a cauzat în ultimă instanță invocarea panic!. Putem să folosim backtrace-ul pentru a urmări din ce funcții vine apelul panic! și să identificăm astfel partea din codul nostru responsabilă pentru eroare. Vom discuta backtrace-urile mai în detaliu în curând.

Urmărirea stivei cu panic!

Să analizăm un exemplu în care panic! este declanșat de o bibliotecă din pricina unei greșeli în codul nostru, în loc de a proveni direct din codul care invocă macrocomanda. Listarea 9-1 prezintă cod care încearcă să acceseze un index inexistent într-un vector, dincolo de limita indexurilor valide.

Numele fișierului: src/main.rs

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Listarea 9-1: Tentativa de accesare a unui element în afara limitelor unui vector, ce va declanșa un apel la panic!

În acest caz, încercăm să accesăm elementul cu indexul 100 din vectorul nostru (care ar fi de fapt la indexul 99, deoarece numerotarea începe de la zero), însă vectorul nostru conține doar 3 elemente. In această situație, Rust va apela panica. Folosirea operatorului [] presupune a extrage un element, dar când indexul este incorect, Rust nu poate furniza un răspuns adecvat.

În limbajul C, citirea datelor dincolo de capătul unei structuri de date este un comportament nedefinit. S-ar putea să primești date aleatoare din memoria ce corespunde acelui index în structura de date, chiar dacă acea porțiune de memorie nu face parte din structură. Acest fenomen, cunoscut sub numele de supracitire a buffer-ului, poate crea vulnerabilități de securitate dacă un atacator reușește să modifice indexul în așa fel încât să citească date neautorizate, plasate în memorie după structura de date.

Pentru a proteja programul tău de vulnerabilități, Rust va opri execuția dacă încerci să accesezi un element la un index inexistent, refuzând astfel să continue. Să vedem cum se întâmplă asta:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Mesajul de eroare arată că greșeala se află la linia 4 din fișierul nostru main.rs, unde am încercat să accesăm elementul cu indexul 99. Nota atașată ne spune că putem seta variabila de mediu RUST_BACKTRACE pentru a primi un backtrace detaliat, care să ne arate exact ce a cauzat eroarea. Un backtrace reprezintă o listă cu toate funcțiile invocate până în punctul erorii. Interpretarea unui backtrace în Rust se face la fel ca în alte limbaje: pornește de la începutul listei și continuă să citești până când recunoști fișiere pe care le-ai scris tu. Acolo se găsește originea problemei. Liniile care preced această marcă sunt codul apelat de codul tău; cele care urmează sunt cele care l-au apelat pe al tău. Aceasta implică posibil codul fundamental Rust, librăriile standard sau crate-urile utilizate. Să obținem un backtrace setând variabila de mediu RUST_BACKTRACE la orice altceva decât 0. În Listarea 9-2 vei găsi un exemplu de afișaj similar cu cel pe care îl vei întâlni.

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5
stack backtrace:
   0: rust_begin_unwind
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/std/src/panicking.rs:584:5
   1: core::panicking::panic_fmt
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:142:14
   2: core::panicking::panic_bounds_check
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:84:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:242:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:18:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/alloc/src/vec/mod.rs:2591:9
   6: panic::main
             at ./src/main.rs:4:5
   7: core::ops::function::FnOnce::call_once
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/ops/function.rs:248:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Listarea 9-2: Backtrace generat de panic!, vizibil când variabila de mediu RUST_BACKTRACE este activă

Este o mulțime de informație afișată! Afișajul pe care îl vei vedea poate varia în funcție de sistemul de operare și versiunea de Rust utilizată. Pentru a obține backtrace-uri detaliate ca acestea, este necesar ca simbolurile de depanare să fie activate. Aceste simboluri sunt activate automat când folosești cargo build sau cargo run fară opțiunea --release, cum este cazul aici.

În afișajul din Listarea 9-2, linia 6 din backtrace ne conduce direct la linia din proiectul nostru care generează problema: linia 4 din src/main.rs. Dacă dorim să evităm panica în program, ar trebui să începem analiza acolo unde prima linie indică un fișier creat de noi. De exemplu, în Listarea 9-1, unde codul a fost scris intenționat pentru a genera o panică, soluția pentru a evita aceasta este să nu accesăm un element dintr-un vector ce depășește limitele indicilor acestuia. Când codul tău generează o panică în viitor, va trebui să identifici care acțiune și valori conduc la acea panică și ce ar trebui de fapt să facă codul tău.

Vom reveni la discuția despre panic!, când ar trebui și când nu ar trebui să folosim panic! pentru a trata erorile, în secțiunea „Când să folosim panic! și când nu” mai târziu în acest capitol. În continuare, vom explora cum să gestionăm recuperarea dintr-o eroare folosind Result.

Gestionarea erorilor recuperabile cu Result

Nu toate erorile sunt atât de grave încât să necesite oprirea completă a programului. Când o funcție eșuează, uneori motivul poate fi ușor de interpretat și de abordat. Spre exemplu, dacă încerci să deschizi un fișier iar operațiunea nu reușește pentru că fișierul lipsește, ai putea să optezi pentru crearea fișierului în loc să oprești programul.

Reamintește-ți din Capitolul 2, secțiunea „Gestionarea potențialelor eșecuri cu Result” . Am discutat atunci că enum-ul Result este definit cu două variante: Ok și Err.

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T și E sunt parametri de tip generic. Vom discuta despre generice mai pe larg în Capitolul 10. Important de știut acum este că T reprezintă tipul valorii returnate în caz de succes de varianta Ok, iar E tipul erorii returnate în caz de eșec de varianta Err. Cu acești parametri generici, tipul Result poate fi utilizat în multe contexte diferite, unde valorile succesului și ale erorii pot varia.

Imaginează-ți că apelăm o funcție care returnează o valoare Result pentru că funcția ar putea să nu reușească. În Listarea 9-3, încercăm să deschidem un fișier.

Numele fișierului: src/main.rs

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

Listarea 9-3: Deschiderea unui fișier

Tipul returnat de File::open este Result<T, E>. În acest context, T este std::fs::File, adică un descriptor al fișierului, iar E este std::io::Error. Acest lucru înseamnă că apelul la File::open poate reuși sau eșua — fișierul să nu existe sau să nu avem permisiunea necesară. Funcția File::open trebuie astfel să ne poată informa despre reușită sau eșec și să ne furnizeze descriptorul fișierului sau date despre eroare. Result este exact mecanismul care transmite aceste informații.

Dacă File::open reușește, variabila greeting_file_result va conține o instanță Ok cu descriptorul fișierului. Dacă eșuează, va conține Err cu informații suplimentare privind eroarea survenită.

Trebuie să extindem codul din Listarea 9-3 pentru a gestiona diferite rezultate ale funcției File::open. Listarea 9-4 prezintă cum putem folosi expresia match pentru aceasta, discutată în Capitolul 6.

Numele fișierului: src/main.rs

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {:?}", error),
    };
}

Listarea 9-4: Utilizarea match pentru gestionarea variantelor Result

La fel ca Option, și Result și variantele sale sunt importate automat, deci nu avem nevoie să precizăm Result:: înainte de Ok și Err în ramurile match.

Când rezultatul este Ok, codul extrage valoarea file din varianta Ok și o atribuie variabilei greeting_file. Ulterior, descriptorul fișierului poate fi folosit pentru citire sau scriere.

Ramura pentru Err din match gestionează situația eșecului de la File::open. În acest exemplu, optăm pentru panică, prin panic!. Dacă nu există un fișier denumit hello.txt în directoriul nostru curent atunci când rulăm codul, panic! ne va arăta următoarea ieșire:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished dev [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`
thread 'main' panicked at 'Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:8:23
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Ca de obicei, această ieșire ne detaliază cu precizie problema întâmpinată.

Diferențiind reacția la erori

Codul prezentat în Listarea 9-4 va genera o panică (panic!) indiferent de cauza eșecului funcției File::open. Totuși, noi intenționăm să abordăm diferit motivele specifice ale eșecului: dacă File::open nu reușește datorită inexistenței fișierului, intenționăm să creăm fișierul și să returnăm un descriptor către acesta. În schimb, dacă File::open eșuează din alte motive - de exemplu, lipsa permisiunilor de acces - dorim să menținem reacția inițială de panică, așa cum este ilustrat în Listarea 9-4. Pentru a gestiona acest comportament, includem o expresie match suplimentară, ilustrată în Listarea 9-5.

Numele fișierului: src/main.rs

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {:?}", e),
            },
            other_error => {
                panic!("Problem opening the file: {:?}", other_error);
            }
        },
    };
}

Listarea 9-5: Abordări diferențiate ale gestionării erorilor

Tipul valorii returnate de File::open când întâlnește o eroare (Err) este io::Error, o structură definită în biblioteca standard. Această structură include metoda kind, prin care putem obține o valoare de tip io::ErrorKind. Enum-ul io::ErrorKind, de asemenea furnizat de biblioteca standard, categorizează potențialele erori ce pot apărea în timpul unei operațiuni io. Pentru cazul nostru, ne folosim de varianta ErrorKind::NotFound, care semnalizează că fișierul pe care dorim să-l deschidem nu există încă. Acest lucru ne conduce la aplicarea unui match pe variabila greeting_file_result, dar în interiorul acestuia aplicăm și un match pe rezultatul apelării error.kind().

Ne interesează să verificăm, în cadrul match-ului intern, dacă valoarea întoarsă de error.kind() corespunde cu varianta NotFound a enum-ului ErrorKind. Dacă este așa, înaintăm cu încercarea de creare a fișierului folosind File::create. Însă, cum și această operațiune poate să eșueze, introducem un al doilea braț în expresia de match din interior. În situația în care crearea fișierului nu este posibilă, se va afișa un mesaj de eroare diferit. Cel de-al doilea braț al match-ului exterior rămâne neschimbat, astfel programul va genera o panică pentru orice alt tip de eroare, în afara erorii generată de absența fișierului.

Metode alternative la utilizarea match cu Result<T, E>

Expresia match este extrem de utilă, însă poate deveni încărcată în anumite contexte. În Capitolul 13, veți descoperi closures, care facilitează lucrul cu diverse metode definite pentru Result<T, E>. Aceste metode oferă abordări mai concise comparativ cu match pentru gestionarea valorilor Result<T, E> în cod.

De pildă, vă prezentăm o altă cale de a implementa logica din Listarea 9-5, utilizând de această dată closures și metoda unwrap_or_else:

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {:?}", error);
            })
        } else {
            panic!("Problem opening the file: {:?}", error);
        }
    });
}

Deși acest fragment de cod produce același efect ca Listarea 9-5, el nu conține niciun match, ceea ce îl face mai curat și mai lizibil. Vă sugerăm să reveniți la acest exemplu după parcurgerea Capitolului 13 și să consultați documentația metodei unwrap_or_else din biblioteca standard a Rust. Vei descoperi că există multe alte metode care pot simplifica expresii complexe și îmbinate de match, mai ales atunci când tratați erori în codul dvs.

Scurtături pentru panică la eroare: unwrap și expect

Deși este destul de eficientă, utilizarea expresiei match poate deveni oneroasă și nu întotdeauna exprimă clar intenția programatorului. Tipul Result<T, E> dispune de numeroase metode auxiliare destinate efectuării de operații specifice. Una dintre aceste metode este unwrap, care funcționează similar cu expresia match pe care am detaliat-o în Listarea 9-4. Dacă Result este varianta Ok, unwrap extrage și returnează valoarea conținută. În schimb, dacă Result este varianta Err, unwrap va apela macro-ul panic!. Iată unwrap în aplicare:

Numele fișierului: src/main.rs

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Dacă executăm acest cod fără a avea fișierul hello.txt, vom întâlni un mesaj de eroare generat de apelul panic! pe care îl face metoda unwrap:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os {
code: 2, kind: NotFound, message: "No such file or directory" }',
src/main.rs:4:49

Metoda expect ne oferă posibilitatea de a alege mesajul de eroare pentru panic!. Prin folosirea lui expect în locul lui unwrap și prin oferirea de mesaje explicite de eroare, îți poți clarifica intenția și facilita identificarea sursei unei erori fatale. Sintaxa metodei expect este următoarea:

Numele fișierului: src/main.rs

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

Expect se utilizează la fel cum procedăm cu unwrap: intenționăm să extragem descriptorul fișierului sau să declanșăm macro-ul panic!. Cu toate acestea, mesajul de eroare dat de expect când apelează panic! va fi textul specific pe care îl pasăm către expect, spre deosebire de mesajul prestabilit al lui unwrap. Iată cum arată în practică:

thread 'main' panicked at 'hello.txt should be included in this project: Os {
code: 2, kind: NotFound, message: "No such file or directory" }',
src/main.rs:5:10

În codul destinat producției, Rustaceanii aleg de obicei expect în loc de unwrap, furnizând mai multe detalii legate de motivul pentru care operațiunea ar trebui să reușească întotdeauna. În acest fel, dacă ipotezele tale se dovedesc a fi incorecte, vei dispune de mai multe informații utile pentru depanare.

Propagarea erorilor

Când o funcție se confruntă cu posibilitatea unui eșec în timpul executării, poți alege să nu soluționezi eroarea în interiorul acelei funcții. În schimb, poți redirecționa eroarea către codul care a inițiat apelul funcției, permițându-i să decidă cum să procedeze. Această abordare se numește propagarea erorii și conferă un grad mai mare de control codului apelant, care ar putea deține informații suplimentare sau o logică specifică pentru tratamentul erorii, comparativ cu ce este disponibil în contextul funcției tale.

De exemplu, în Listarea 9-6 este prezentată o funcție ce încearcă să citească numele de utilizator dintr-un fișier. Dacă fișierul nu există sau nu poate fi accesat, această funcție va returna erorile întâmpinate direct codului ce a solicitat funcția.

Numele fișierului: src/main.rs

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

Listarea 9-6: Funcție care gestionează erorile prin match

Funcția prezentată poate fi scrisă într-o formă mult mai concisă. Totuși, pentru a înțelege mai bine gestionarea erorilor, vom începe cu o abordare manuală, pas cu pas. La final, vom prezenta și versiunea simplificată. Mai întâi, să ne concentrăm asupra tipului de retur: Result<String, io::Error>. Acesta indică faptul că funcția returnează Result<T, E>, unde parametrul generic T este specificat ca String, iar E ca io::Error.

Dacă funcția se execută corect, rezultatul va fi un Ok conținând un String—numele de utilizator citit din fișier. În cazul apariției unei erori, se va returna Err cu un io::Error, detaliind problema survenită. Alegem să folosim io::Error ca tip de eroare pentru că acesta este returnat atunci când operațiunile File::open sau read_to_string eșuează, acestea fiind funcțiile utilizate în cadrul funcției noastre.

Începem corpul funcției apelând funcția File::open. Gestionăm rezultatul Result printr-un match asemănător celui din Listarea 9-4. Dacă File::open reușește, variabila de tip șablon file, care acum stochează descriptorul fișierului, este asignată variabilei mutabile username_file, iar execuția funcției continuă. În caz de eroare Err, în loc să utilizăm macro-ul panic!, preferăm să ieșim din funcție folosind cuvântul cheie return, returnând direct eroarea primită de la File::open, acum stocată în variabila șablon e.

Dacă avem un descriptor de fișier valid în username_file, funcția trece la crearea unui nou String în variabila username. Apoi invocăm metoda read_to_string pe descriptorul din username_file pentru a citi conținutul fișierului în username. Metoda read_to_string returnează și ea un Result, deoarece poate eșua, chiar și când File::open a avut succes. Prin urmare, aplicăm un nou match pentru acest Result. Dacă read_to_string se finalizează cu succes, funcția noastră este și ea un succes și returnăm numele de utilizator din fișier, acum aflat în username, încapsulat într-un Ok. Dacă read_to_string dă greș, tratăm eroarea în mod similar cu cel din match-ul precedent, dar fără a mai folosi explicit cuvântul return, fiindcă aceasta este ultima expresie din funcție, iar valorile erorilor sunt întoarse implicit.

Codul care cheamă funcția noastră va trebui să gestioneze rezultatul: fie o valoare Ok ce conține un nume de utilizator, fie o valoare Err ce include o eroare io::Error. Depinde de codul apelant să decidă cum va proceda cu aceste rezultate. În cazul unei valori Err, codul respectiv poate alege să genereze panică folosind panic! și astfel să oprească execuția programului, să utilizeze un nume de utilizator prestabilit sau să caute numele de utilizator prin alte metode, care nu implică accesul la un fișier. Noi nu cunoaștem intențiile specifice ale codului apelant, prin urmare, transmitem informațiile despre succes sau eroare mai departe pentru ca acesta să le gestioneze în cel mai potrivit mod.

Această metodă de a transmite erorile este atât de răspândită în Rust, încât limbajul include operatorul ? pentru a simplifica acest proces.

Propagarea erorilor cu operatorul ?

Listarea 9-7 ne prezintă cum să folosim funcția read_username_from_file pentru a obține aceleași rezultate ca și în Listarea 9-6, dar de această dată folosind operatorul ?.

Numele fișierului: src/main.rs

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

Listarea 9-7: O funcție care returnează erori către codul apelant folosind operatorul ?

Atunci când se pune operatorul ? după o valoare de tip Result, acesta funcționează similar cu expresiile match pe care le-am utilizat anterior pentru a gestiona valorile Result în Listarea 9-6. Dacă rezultatul de tip Result este Ok, conținutul lui Ok este returnat și execuția programului continuă. Dacă rezultatul este Err, atunci Err este returnat de întreaga funcție, ca și cum am folosi cuvântul cheie return, astfel propagând eroarea către codul care a invocat funcția.

Însă, există o diferență între expresiile match din Listarea 9-6 și operatorul ?: erorile asupra cărora este aplicat operatorul ? sunt trecute prin funcția from, definită de trăsătura From din biblioteca standard. Funcția from transformă valorile dintr-un tip în altul. Când operatorul ? invocă from, tipul erorii revine convertit la tipul de eroare specificat în semnătura funcției curente. Acest aspect se dovedește a fi util atunci când o funcție trebuie să returneze un singur tip de eroare pentru a reprezenta diferitele cauze care pot conduce la eșecul acesteia.

De exemplu, putem modifica funcția read_username_from_file prezentată în Listarea 9-7 astfel încât să returneze un tip propriu de eroare, denumit OurError, pe care îl definim noi. De asemenea, dacă implementăm impl From<io::Error> pentru OurError pentru a crea o instanță OurError dintr-un io::Error, apelurile operatorului ? din funcția read_username_from_file vor utiliza automat from pentru a converti erorile, fără să mai adăugăm cod suplimentar.

În cazul prezentat în Listarea 9-7, semnul ? de la sfârșitul apelului File::open va extrage valoarea dintr-un rezultat Ok și o va asigna variabilei username_file. Dacă întâmpinăm o eroare, operatorul ? va opri execuția funcției imediat și va transmite valoarea Err codului care a făcut apelul. Același principiu se aplică și pentru ? de la sfârșitul apelului read_to_string.

Operatorul ? reduce semnificativ redundanța codului și facilitează simplificarea implementării funcției. Mai mult, prin înlănțuirea directă a apelurilor de metode după ?, putem condensa codul și mai mult, aspect ilustrat în Listarea 9-8.

Numele fișierului: src/main.rs

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

Listarea 9-8: Lănțuirea metodelor după operatorul ?

Am inițializat noul string username la începutul funcției, ca și înainte. În loc să declarăm o variabilă username_file, acum apelăm metoda read_to_string imediat după File::open("hello.txt")?. Continuăm să folosim ? la sfârșitul lui read_to_string și returnăm un Ok care conține username dacă atât File::open, cât și read_to_string reușesc, evitând returnarea de erori. Practic, obținem aceeași funcționalitate ca în Listarea 9-6 și Listarea 9-7, dar printr-o scriere mai compactă și ergonomică.

Listarea 9-9 va prezenta cum să simplificăm și mai mult codul, utilizând fs::read_to_string.

Filename: src/main.rs

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

Listarea 9-9: Folosirea funcției fs::read_to_string pentru a evita deschiderea și citirea explicită a fișierului

Citirea conținutului unui fișier într-un string este o operaţie frecventă, iar biblioteca standard facilitează această operație prin funcția practică fs::read_to_string. Această funcție deschide fișierul, inițializează un nou String, citește conținutul fișierului, îl stochează în acel String și apoi îl returnează. Desigur, prin utilizarea fs::read_to_string nu putem ilustra în detaliu gestionarea erorilor, motiv pentru care am ales inițial metoda mai elaborată.

Unde poate fi folosit operatorul ?

Operatorul ? poate fi utilizat numai în funcții a căror valoare de retur este compatibilă cu tipul de valoare asupra căruia se aplică ?. Acest lucru se datorează faptului că operatorul ? este conceput pentru a efectua un retur prematur din funcție, similar cu expresia match pe care am descris-o în Listarea 9-6. În cazul Listării 9-6, match opera cu o valoare de tip Result, iar ramura de retur prematur returna o valoare Err(e). Funcția trebuie să aibă ca tip de retur un Result pentru a fi compatibil cu acțiunea de return.

În Listarea 9-10 vom vedea ce eroare apare atunci când utilizăm operatorul ? într-o funcție main care are un tip de retur incompatibil cu tipul valorii pentru care aplicăm ?:

Numele fișierului: src/main.rs

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Listarea 9-10: Tentativa de a folosi ? în funcția main care returnează () nu va funcționa

Acest cod încearcă să deschidă un fișier, operațiune care poate să eșueze. Operatorul ? este aplicat valorii Result returnate de File::open, însă funcția main are definit ca tip de retur (), nu Result. Când încercăm să compilăm acest cod, ne întâmpină următorul mesaj de eroare:

$ 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: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not implemented for `()`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` due to previous error

Această eroare semnalează faptul că putem utiliza operatorul ? exclusiv în cadrul funcțiilor care returnează Result, Option, sau alte tipuri ce implementează FromResidual.

Pentru a corecta eroarea, ai două opțiuni. Prima este să modifici tipul de retur al funcției tale astfel încât să corespundă cu tipul valorii peste care aplici operatorul ?, cu condiția să nu existe restricții care te împiedică. Alternativa este folosirea unei structuri match sau a metodelor disponibile pentru Result<T, E> pentru a gestiona rezultatul Result<T, E> în modul cel mai potrivit pentru contextul tău.

Mesajul de eroare a subliniat, de asemenea, că operatorul ? poate fi aplicat pe valori de tip Option<T>. Asemenea utilizării ? pe Result, acesta poate fi folosit pe Option numai într-o funcție care returnează un Option. Atunci când ? este utilizat pe un Option<T>, comportamentul său este asemănător: dacă valoarea este None, atunci None se returnează imediat, întrerupând execuția funcției. Dacă valoarea este de tip Some, conținutul lui Some devine valoarea expresiei, iar execuția funcției continuă. Următoarea listare, 9-11, conține un exemplu de funcție care identifică ultimul caracter din prima linie a unui text furnizat:

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

Listarea 9-11: Utilizarea operatorului ? pentru o valoare Option<T>

Funcția aceasta returnează Option<char> deoarece există posibilitatea ca un caracter să fie prezent, dar de asemenea e posibil ca acesta să lipsească. Codul ia secțiunea de string text ca argument și îi aplică metoda lines, care oferă un iterator pentru liniile din string. Pentru a examina prima linie, folosim metoda next pe iterator, pentru a extrage prima valoare. Dacă text este un string gol, next va returna None; în acest caz, operatorul ? intervine pentru a opri execuția și a returna None din last_char_of_first_line. Dacă în schimb text nu este gol, next va returna un Some ce conține slice-ul primei linii din text.

Operatorul ? extrage acea secțiune, permițându-ne apoi să apelăm metoda chars pentru a obține un iterator al caracterelor sale. Ne interesează ultimul caracter din prima linie, deci apelăm last pentru a obține ultimul element al iteratorului, care este tot un Option. Este posibil ca prima linie să fie și ea un string gol – de exemplu, dacă text începe cu o linie goală, urmată de alte linii cu caractere, cum ar fi "\nhi". În cazul în care există un caracter final în prima linie, acesta va fi returnat într-o valoare Some. Folosind operatorul ?, putem exprima această verificare concis, permițând implementarea funcției într-o singură linie. Altfel, fără operatorul ? aplicabil pe Option, am fi nevoiți să reconstruim această logică prin mai multe apeluri de metode sau printr-o expresie match.

Trebuie să reții că operatorul ? poate fi utilizat pentru a propaga erorile într-o funcție care returnează un Result atunci când lucrezi cu un Result, iar în cazul în care lucrezi cu un Option, poți utiliza operatorul ? într-o funcție care returnează un Option. Însă nu este posibilă utilizarea mixtă a ambelor. Cu alte cuvinte, operatorul ? nu realizează automat conversia între Result și Option sau invers; în acele situații, trebuie să apelezi metode specifice, cum ar fi ok pentru Result sau ok_or pentru Option, pentru a efectua conversia în mod explicit.

Până în prezent, toate funcțiile main pe care le-am utilizat returnau (). Merită să subliniem că funcția main este unică, fiind punctul de start și de terminare al programelor executabile. Există restricții specifice legate de tipul de retur pe care îl poate avea, astfel încât programul să funcționeze corespunzător.

Noutatea bună e că main poate de asemenea să returneze Result<(), E>. În Listarea 9-12, prezentăm codul din Listarea 9-10, dar cu tipul de retur al funcției main modificat în Result<(), Box<dyn Error>> și adăugăm la final valoarea de retur Ok(()). Cu aceste modificări, codul este gata de compilat:

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

Listarea 9-12: Modificând funcția main pentru a returna Result<(), E>, permitem folosirea operatorului ? pe valorile Result

Tipul Box<dyn Error> este un obiect trăsătură, concept pe care îl vom aborda mai detaliat în secțiunea „Utilizarea obiectelor trăsături care permit valori de diferite tipuri” din Capitolul 17. Până atunci, poți gândi la Box<dyn Error> ca o modalitate de a desemna „orice fel de eroare”. Utilizarea operatorului ? pe o valoare de tip Result în funcția main este posibilă atunci când tipul erorii este Box<dyn Error>, pentru că aceasta acceptă returnarea anticipată a oricărei valori de eroare Err. Deși corpul funcției main va genera, în mod normal, doar erori de tip std::io::Error, prin definirea tipului de eroare ca fiind Box<dyn Error>, semnătura acestuia rămâne validă chiar și atunci când adăugăm mai mult cod care generează alte tipuri de erori în main.

Când funcția main returnează un Result<(), E>, aplicația va termina execuția cu valoarea 0 dacă main returnează Ok(()) și va închide cu o valoare diferită de zero dacă main generează o eroare Err. Executabilele în limbajul C returnează valori întregi când se încheie execuția: programele care se termină corect returnează întregul 0, în timp ce programele care se închid cu o eroare returnează un întreg diferit de 0. Rust adoptă această convenție, returnând întregi de la executabile pentru compatibilitate.

Funcția main poate returna orice tip de date care implementează trăsătura std::process::Termination, care include funcția report rezultând într-un ExitCode. Consultă documentația bibliotecii standard Rust pentru mai multe detalii despre cum să implementezi trăsătura Termination pentru tipurile tale.

După ce am clarificat modul în care apelăm panic! sau returnăm Result, să discutăm cum alegem între aceste opțiuni în funcție de situație.

Să panic!-ăm sau nu?

Cum alegi când să apelezi la panic! și când e preferabil să returnezi un Result? Odată ce codul intră în panică, nu mai există cale de recuperare. Ai putea utiliza panic! pentru orice eroare, indiferent dacă există o șansă de reparare sau nu, dar astfel decizi tu că o situație e de nerezolvat, în locul celui care folosește codul tău. Prin furnizarea unei valori Result, permiți utilizatorului codului să aleagă soluția adecvată contextului său sau să determine că o valoare Err este una definitivă, apelând la panic! pentru a-și asuma ireversibilitatea. De aceea, este indicat să returnezi un Result când concepi o funcție care ar putea să nu funcționeze cum trebuie.

În situații precum documentația de exemplu, prototipuri și teste, e mai potrivit să optezi pentru codul ce induce panic! decât să returnezi un Result. Explorăm acum de ce este asta așa, și vom discuta cazurile în care compilatorul nu detectează imposibilitatea unui eșec, dar tu în calitate de programator înțelegi situația. Capitolul se va încheia cu un set de linii directoare fundamentale pentru a decide dacă să folosești panic! în codul bibliotecilor.

Exemple, cod de prototipare și teste

Când elaborezi un exemplu pentru a ilustra un concept, includerea codului complex pentru gestionarea erorilor poate aduce un minus de claritate. Se înțelege că, în exemple, utilizarea unei metode cum ar fi unwrap, care ar putea declanșa o panică, este doar un substituent temporar pentru modul în care ai gestiona normal erorile în aplicația ta, acest mod variind în funcție de codul existent.

Similar, metodele unwrap și expect sunt de mare ajutor în stadiul de prototipare, când încă nu ai hotărât cum să abordezi gestionarea erorilor. Ele lasă semne evidente în cod pentru momentul în care ești pregătit să îți consolidezi programul.

Dacă un apel al metodei nu reușește în timpul testării, ideal este ca întreg testul să fie afectat de acest eșec, chiar dacă metoda în cauză nu este funcționalitatea principală care se testează. Deoarece instrucțiunea panic! semnalează eșecul unui test, utilizarea unwrap sau expect este tocmai procedura adecvată în acest context.

Situațiile în care ai mai multe informații decât compilatorul

Este recomandabil să apelezi unwrap sau expect atunci când deții o anumită logică de asigurare că Result va fi Ok, chiar dacă logica respectivă nu este interpretată de compilator. În asemenea cazuri, încă trebuie să gestionăm valoarea Result: orice funcție invocată are potențialul de a eșua în principiu, chiar dacă eșecul este logic imposibil în situația particulară actuală. Dacă ești capabil prin verificarea manuală a codului să asiguri absența unei variante Err, apelarea lui unwrap este complet justificată și chiar încurajată. În plus, documentarea motivului pentru care este exclusă o variantă Err în mesajul metodei expect este o practică deosebit de beneficiară. Aici este un exemplu:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

Aici instanțiăm o structură IpAddr prin parsarea unui string predefinit. Cum 127.0.0.1 este clar o adresă IP validă, este logic să apelăm expect. Totuși, prezența unui string valid și predefinit nu influențează tipul de retur pentru metoda parse: rămânem cu o valoare de tip Result, iar compilatorul ne va solicita să gestionăm Result ca și când varianta Err ar fi o eventualitate, deoarece nu este echipat să recunoască automat că acest string este mereu o adresă IP validă. Dacă sursa string-ului cu adresa IP ar fi exterioară, adică provenind de la un utilizator și nu fiind stabilită inițial în cod, atunci cu certitudine am prefera o abordare mai atentă a valorii Result. Evidențierea faptului că adresa IP este predefinită în cod ne stimulează să actualizăm expect cu un cod de gestionare a erorilor mai avansat dacă e necesar să adaptăm sursa de unde obținem adresa IP în viitor.

Recomandări pentru tratarea erorilor

Este prudent să lași codul tău să declanșeze panică în momentele când s-ar putea să ajungă într-o stare critică. Prin stare critică înțelegem situația în care o anumită asumpție, garanție, acord sau invariant a fost compromis, exemplificat prin primirea de valori invalide, contradictorii sau inexistente - plus una sau mai multe dintre următoarele circumstanțe:

• Starea critică este una imprevizibilă, nu una care ar apărea frecvent, cum ar fi erorile de introducere a datelor de către un utilizator.
• Codul tău de după acest punct presupune că nu se află în acea stare critică și nu verifică problema la fiecare etapă.
• Nu este posibil să exprimi aceste informații suficient de clar utilizând tipurile curente. Vom explora această idee prin intermediul unui exemplu în secțiunea „Exprimarea stărilor și comportamentelor prin tipuri” din capitolul 17.

Dacă cineva folosește codul tău și introduce valori nesigure, este ideal să returnezi o eroare, dacă este posibil, astfel încât cel ce folosește biblioteca ta să determine cea mai bună acțiune de urmat. Totuși, în situații unde continuarea ar putea fi riscantă sau dăunătoare, decizia cea mai judicioasă ar fi să folosești panic!. Asta va notifica persoana care utilizează biblioteca ta despre defectul din codul său, permițând corectarea acestuia în cadrul dezvoltării. De asemenea, este adesea adecvat să folosești panic! atunci când execuți cod extern peste care nu ai control și acesta returnează o stare defectuoasă pe care nu ai cum să o corectezi.

Totuși, când un eșec este prevăzut, este preferabil să returnăm un Result în loc să apelăm panic!. Exemplele pot include situația în care un parser primește date corupte sau o solicitare HTTP care returnează un statut ce arată că s-a atins limita de rată. În aceste cazuri, returnarea unui Result indică faptul că eșecul este recunoscut ca o posibilitate așteptată, pe care codul apelant trebuie să o manajeze.

Când codul efectuează o operație care poate fi riscantă pentru un utilizator dacă este chemată cu valori invalide, trebuie să verifice dacă valorile sunt valide înainte și să panicheze dacă acestea nu sunt. Motivul principal este securitatea: lucrul cu date invalide poate crea vulnerabilități în codul tău. Acesta este motivul pentru care biblioteca standard va produce panic! dacă se încearcă accesul la memorie dincolo de limitele permise: încercarea de a accesa memoria care nu face parte din structura de date actuală este o problemă obișnuită de securitate. Funcțiile au adesea contracte: comportamentul lor este garantat doar dacă intrările îndeplinesc cerințele specificate. A panica atunci când un contract este încălcat este justificat deoarece o încălcare a contractului indică mereu o problemă din partea celui care apelează și nu este un tip de eroare care ar trebui gestionat explicit de către codul apelant. În esență, nu există o modalitate rezonabilă prin care codul apelant să poată remedia; programatorii apelanți trebuie să repare codul. Contractele unei funcții, în special atunci când nerespectarea lor conduce la panică, ar trebui să fie explicite în documentația API a respectivei funcții.

A include numeroase verificări de erori în toate funcțiile poate deveni copleșitor și plictisitor. Din fericire, sistemul de tipizare oferit de Rust și verificarea tipurilor efectuată de compilatorul lui Rust îți permit să automatizezi multe din aceste controale. Atunci când funcția ta specifică un anumit tip pentru un parametru, îți poți duce execuția codului mai departe având certitudinea că ai primit o valoare validă, grație compilatorului. De exemplu, dacă preferi un tip concret în locul tipului Option, programul se așteaptă să opereze cu ceva și nu cu nimic. Acest lucru înseamnă că nu trebuie să gestionezi separat cazurile Some și None, ci doar situația în care ai deja o valoare garantată. Astfel, încercările de a folosi funcția cu valori nule sunt oprite în faza de compilare, eliminând necesitatea efectuării acestei verificări în timpul execuției. Un alt exemplu, optarea pentru tipuri de numere întregi fără semn, precum u32, îți asigură că parametrul nu va putea fi niciodată negativ.

Crearea de tipuri particularizate pentru validare

Să explorăm cum putem utiliza sistemul de tipuri din Rust pentru a ne asigura că avem valori valide, prin crearea de tipuri personalizate pentru validarea acestora. Revenind la jocul cu ghicirea numărului din Capitolul 2, unde codul cerea utilizatorului să ghicească un număr între 1 și 100, observăm că nu am validat dacă ghicirea utilizatorului se încadra în acest interval înainte de a o compara cu numărul secret; ne-am limitat doar la verificarea pozitivității ghicirii. Cu toate că în acest caz consecințele nerespectării intervalului nu erau majore – răspunsurile „Prea mare” sau „Prea mic” fiind adecvate –, tot ar fi benefică îndrumarea utilizatorilor spre ghiciri corecte și o diferențiere clară a comportamentului programului atunci când utilizatorul introduce un număr în afara intervalului sau, de exemplu, litere.

Un mod de a implementa acest lucru ar fi prin parsarea ghicirii ca un i32, care permite numere negative, și adăugarea unei verificări care să confirme că numărul se află în intervalul dorit:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

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

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

    loop {
        // --snip--

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

        let mut guess = String::new();

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

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

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

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

Instrucțiunea if verifică dacă valoarea introdusă este în afara intervalului, informează utilizatorul în privința erorii și execută continue pentru a iniția o nouă iterație a buclei și a solicita o altă ghicire. După această verificare, comparațiile dintre guess și numărul secret pot fi efectuate cu certitudinea că guess cade între 1 și 100.

Cu toate acestea, soluția nu este optimă într-un context în care este critic ca programul să lucreze exclusiv cu valori între 1 și 100 – mai ales dacă mai multe funcții impun această limită –, căci inserarea aceluiași tip de verificare în fiecare dintre ele ar fi monotonă și ar putea influența performanța.

Ca alternativă, am putea defini un tip nou și să centralizăm validările într-o funcție dedicată creării de instanțe ale acestui tip, evitând astfel repetarea validărilor. Astfel, este sigur de utilizat noul tip în semnăturile funcțiilor, care ar putea opera cu încredere folosind valorile primite. În Listarea 9-13, prezentăm o metodă de a defini un tip Guess, care va crea o instanță validă a acestuia numai dacă funcția new este invocată cu o valoare între 1 și 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {}.", value);
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Listarea 9-13: Tipul Guess ce acceptă numai valorile între 1 și 100

Inițial, definim o structură cu denumirea Guess, având un câmp numit value care conține un i32. Acesta este locul unde va fi stocat numărul.

Ulterior, implementăm o funcție asociată intitulată new pentru structura Guess, pentru a crea instanțe ale tipului Guess. Funcția new este configurată să primească un parametru numit value, de tip i32, și să returneze un Guess. În corpul funcției new, verificăm valoarea lui value pentru a ne asigura că se încadrează între 1 și 100. În cazul în care value nu îndeplinește acest criteriu, utilizăm macro-ul panic!, care va semnala programatorului care a apelat codul despre prezența unui defect ce necesită rezolvare, deoarece constituirea unui Guess cu o valoare value exterioară acelui interval ar încălca prerogativele funcției Guess::new. Situațiile în care Guess::new ar putea cauza o panică trebuie detaliate în documentația API destinată publicului; vom aborda standardele de documentare ce marchează posibilitatea unei panici în documentația API pe care o veți alcătui în Capitolul 14. Dacă value satisface cerința, compilăm o nouă structură Guess, stabilind valoarea câmpului value la parametrul primit și întorcând Guess.

Mai departe, implementăm o metodă denumită value ce împrumută self și returnează un i32, fără a solicita alți parametri. Această metodă este adesea identificată ca getter, deoarece scopul ei este de a extrage informații din câmpurile proprii și de a le furniza extern. Această metodă publică este esențială dat fiind că atributul value al structurii Guess este privat. Este crucial pentru atributul value să fie privat, astfel încât codul care utilizează structura Guess să nu fie în măsură să seteze value în mod direct: codul din afara modulului trebuie să recurgă la funcția Guess::new pentru a asambla o instanță de Guess, garantându-se în acest mod că orice Guess posedă un value validat de condițiile prezentate în funcția Guess::new.

O funcție care manipulează numai numere între 1 și 100 poate alege să indice în semnătura sa că primește sau returnează o structură Guess în loc de un i32, ceea ce ar permite să ocolească efectuarea unor verificări în plus în conținutul său.

Sumar

Capacitățile de gestionare a erorilor din Rust sunt concepute pentru a sprijini scrierea unui cod cât mai solid. Macro-ul panic! indică o stare irecuperabilă a programului și oferă posibilitatea de a întrerupe execuția, evitând continuarea cu valori greșite sau invalide. Enum-ul Result exploatează sistemul de tipuri al Rust pentru a scoate în evidență potențialul eșec al operațiunilor, din care codul tău ar putea să revină. Result poate fi folosit pentru a informa codul client că trebuie gestionată atât reușita, cât și eșecul. Folosirea judicioasă a panic! și a Result va crește fiabilitatea codului tău în fața problemelor inevitabile.

Având în vedere utilizările benefice ale genericilor în enum-urile Option și Result de către biblioteca standard, vom discuta în continuare despre funcționarea genericilor și modul în care pot fi implementați în codul tău.

Tipuri generice, trăsături și durate de viață

Fiecare limbaj de programare dispune de unelte specifice pentru a gestiona eficient duplicarea conceptelor. În Rust, un asemenea instrument sunt genericele: substituenți abstracți pentru tipuri concrete sau alte caracteristici. Ne permite să descriem comportamentul genericelor sau relațiile acestora cu alte generice fără a cunoaște ce le va înlocui atunci când codul este compilat și executat.

Funcțiile pot accepta parametri de orice tip generic, în locul unui tip concret precum i32 sau String, similar modului în care o funcție acceptă parametri cu valori necunoscute pentru a rula același cod peste multiple valori concrete. De fapt, am utilizat genericele în Capitolul 6 cu Option<T>, în Capitolul 8 cu Vec<T> și HashMap<K, V>, și în Capitolul 9 cu Result<T, E>. În acest capitol, vei explora cum să-ți definești propriile tipuri, funcții și metode utilizând generice!

Vom începe cu o recapitulare a metodei de extragere a unei funcții în scopul reducerii duplicării de cod. Vom folosi aceeași tehnică pentru a deriva o funcție generică din două funcții care diferă numai prin tipurile parametrilor lor. Îți vom arăta cum se aplică tipurile generice în definițiile structurilor și enumerărilor.

Mai departe, vei învăța să folosești trăsături (trait) pentru a defini comportamente într-un mod generic. Combinând trăsăturile cu tipuri generice, putem limita un tip generic să accepte doar acele tipuri care prezintă un anumit comportament, spre deosebire de orice tip.

La final, vom discuta despre duratele de viață: o categorie specială de generice ce furnizează compilatorului date privind modul în care referințele interacționează unele cu altele. Duratele de viață ne permit să înzestrăm compilatorul cu informații suficiente despre valorile împrumutate, permițându-i acestuia să asigure că referințele sunt valide într-o paletă mai largă de scenarii decât ar fi posibil fără sprijinul nostru.

Reducerea duplicării prin extragerea unei funcții

Genericele ne permit să substituim tipuri specifice cu un placeholder, ce reprezintă mai multe tipuri, și astfel să eliminăm duplicarea în cod. Înainte de a ne familiariza cu sintaxa de generice, să vedem prima dată cum putem înlătura duplicările într-un mod care nu implică tipuri generice. Acest lucru se realizează prin extragerea unei funcții care înlocuiește valorile specifice cu un placeholder pentru multiple valori. Apoi, vom aplica aceeași abordare pentru a defini o funcție generică! Înțelegând cum să recunoaștem codul duplicat care se poate transforma într-o funcție, vei începe să identifici și codul duplicat care poate beneficia de generice.

Pornim cu un program simplu prezentat în Listarea 10-1, care determină cel mai mare număr dintr-o listă.

Numele fișierului: src/main.rs

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {}", largest);
    assert_eq!(*largest, 100);
}

Listarea 10-1: Identificarea celui mai mare număr dintr-o listă de numere

Noi salvăm o listă de numere întregi în variabila number_list și atribuim o referință la primul număr din listă variabilei largest. Procedăm apoi la iterarea prin fiecare număr din listă, iar dacă numărul curent este mai mare decât cel referențiat de largest, actualizăm referința din această variabilă. Pe de altă parte, dacă numărul curent este mai mic sau egal cu cel mai mare număr întâlnit până în acel moment, variabila largest rămâne neschimbată, iar codul continuă cu următorul număr din listă. După ce toate numerele din listă sunt evaluate, largest va indica cel mai mare număr, care în acest exemplu este 100.

Ne-am propus acum să găsim cel mai mare număr din două seturi diferite de numere. Putem alege să duplicăm codul din Listarea 10-1 sau să aplicăm aceeași logică în două locuri diferite din program, așa cum este prezentat în Listarea 10-2.

Numele fișierului: src/main.rs

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {}", largest);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {}", largest);
}

Listarea 10-2: Cod pentru identificarea celui mai mare număr din două liste de numere

Chiar dacă acest cod este funcțional, duplicarea sa este monotonă și predispusă la erori. În plus, trebuie să ne amintim să actualizăm codul în diverse locuri atunci când dorim să facem modificări.

Pentru a elimina această duplicare, vom introduce o abstracție prin definirea unei funcții care operează pe orice array de numere întregi dat ca parametru. Această metodă îmbunătățește claritatea codului și ne permite să formulăm conceptul de identificare a celui mai mare număr dintr-un array într-un mod abstract.

În Listarea 10-3, extragem codul care identifică cel mai mare număr într-o funcție numită largest. Apoi invocăm funcția pentru a determina cel mai mare număr din cele două liste prezentate în Listarea 10-2. Totodată, putem utiliza funcția pentru orice alte array-uri de valori i32 pe care le-am putea avea în viitor.

Numele fișierului: src/main.rs

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {}", result);
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {}", result);
    assert_eq!(*result, 6000);
}

Listarea 10-3: Cod abstractizat pentru găsirea celui mai mare număr din două liste

Funcția largest are un parametru denumit list, care poate reprezenta orice secțiune concretă de valori i32 introdusă în funcție. În consecință, când apelăm funcția, codul se execută folosind valorile specifice furnizate.

Rezumând, aceștia sunt pașii pe care i-am urmat pentru a transforma codul din Listarea 10-2 în Listarea 10-3:

1. Identifică codul duplicat.
2. Extrage codul duplicat în corpul funcției și specifică intrările și valorile de retur ale acestui cod în semnătura funcției.
3. Actualizează cele două instanțe de cod duplicat pentru a apela funcția în locul acestuia.

În continuare, vom folosi acești pași împreună cu genericele pentru a reduce și mai mult duplicarea codului. La fel cum corpul unei funcții poate opera pe o list abstractă și nu pe valori concrete, genericele ne permit să lucrăm cu tipuri abstracte.

De pildă, să ne imaginăm că avem două funcții: una care determină elementul cel mai mare dintr-o secțiune de valori i32 și una care găsește cel mai mare element într-o secțiune de valori char. Cum am putea elimina această duplicare? Să explorăm!

Tipuri de date generice

Genericile sunt instrumente pe care le utilizăm pentru a construi definiții de elemente, cum ar fi semnăturile de funcții sau structurile, ce pot fi apoi folosite cu o multitudine de tipuri de date concrete. Înainte de toate, să ne uităm cum putem defini funcții, structuri, enumerări și metode folosind genericile. Ulterior, vom aborda impactul pe care îl au genericile asupra performanței codului.

Definirea funcțiilor cu generici

Atunci când definim o funcție ce folosește generici, introducem genericii în semnătura funcției acolo unde, în mod obișnuit, am specifica tipurile de date pentru parametri și valoarea returnată. Acest demers face codul nostru mai maleabil și oferă mai multă funcționalitate celor ce apelează funcția, prevenind duplicarea de cod.

Continuând cu funcția noastră largest, Listarea 10-4 prezintă două funcții care identifică valoarea cea mai mare dintr-o secțiune. Apoi, vom unifica acestea într-o singură funcție care încorporează generici.

Numele fișierului: src/main.rs

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {}", result);
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {}", result);
    assert_eq!(*result, 'y');
}

Listarea 10-4: Două funcții care se diferențiază prin numele și tipurile specificate în semnăturile lor

Funcția largest_i32, pe care am extras-o în Listarea 10-3, localizează cel mai mare i32 dintr-o secțiune. Funcția largest_char identifică cel mai mare char dintr-o secțiune. Cum ambele funcții au corpuri identice, vom elimina duplicarea introducând un parametru de tip generic într-o funcție singulară.

Pentru a parametriza tipurile în noua funcție singulară, trebuie să numim parametrul de tip, la fel cum nominalizăm parametrii valorici ai unei funcții. Orice identificator poate fi folosit ca nume de parametru de tip. Totuși, ne vom folosi de T conform convenției uzuale în Rust, unde numele parametrilor de tip sunt scurte, frecvent doar o literă, și urmează stilul de denumire UpperCamelCase. T, fiind prescurtarea pentru „type”, este alegerea preferată de majoritatea dezvoltatorilor de Rust.

Când utilizăm un parametru în corpul funcției, trebuie să îl declarăm în semnătură pentru ca compilatorul să înțeleagă la ce ne referim. În mod similar, atunci când utilizăm un nume pentru un parametru de tip în semnătura unei funcții, trebuie să declarăm acest nume de tip înainte de a-l folosi. Pentru a defini funcția generică largest, vom insera numele de tip în interiorul parantezelor unghiulare, <>, așezate între numele funcției și lista de parametri, în felul următor:

fn largest<T>(list: &[T]) -> &T {

Descifrăm această definiție în felul următor: funcția largest funcționează generic pentru un anumit tip T. Funcția dispune de un parametru denumit list, care este o secțiune de elemente de tip T. Funcția largest va returna o referință către o valoare de același tip T.

Listarea 10-5 ne oferă definiția combinată a funcției largest, care incorporează tipul de date generic în semnătura sa. Listarea ilustrează și cum putem invoca funcția folosind fie o secțiune de valori i32, fie una de char. Observăm că acest cod nu va compila încă, dar vom adresa această problemă mai târziu în capitul curent.

Numele fișierului: src/main.rs

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {}", result);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {}", result);
}

Listarea 10-5: Funcția largest utilizând parametrii de tip generic; în stadiul actual codul nu se compilează

Dacă încercăm să compilăm acest cod acum, ne vom confrunta cu următoarea eroare:

$ 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`
  |
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` due to previous error

Mesajul de ajutor ne îndreaptă atenția spre std::cmp::PartialOrd, care este o trăsătură, subiect ce va fi abordat în secțiunea următoare. Pentru moment, este important să înțelegem că această eroare ne transmite că implementarea funcției largest nu va opera corect pentru toate tipurile posibile ale lui T. Pentru că dorim să comparăm valorile de tip T în corpul funcției, ne limităm la acele tipuri ale căror valori pot fi comparate în ordine. Biblioteca standard facilitează acest lucru prin intermediul trăsăturii std::cmp::PartialOrd, pe care o puteți implementa pentru diverse tipuri (pentru mai multe detalii referitoare la această trăsătură, consultați Anexa C). Urmând sugestia din mesajul de ajutor, vom restricționa tipurile valide pentru T la cele care implementează PartialOrd, și astfel exemplul nostru va compila fără probleme, dat fiind că biblioteca standard furnizează implementări pentru PartialOrd atât pentru tipul i32, cât și pentru char.

În definiția structurilor

Noi putem defini structuri care să încorporeze unul sau mai multe câmpuri care folosesc parametri de tip generic, prin intermediul sintaxei cu paranteze unghiulare <>. Listarea 10-6 înfățișează definiția structurii Point<T>, care reține valori ale coordonatelor x și y de orice tip.

Numele fișierului: src/main.rs

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

Listarea 10-6: O structură Point<T> ce conține valori x și y de tip T

Utilizarea genericilor în definirea structurilor urmează o sintaxă similară cu aceea din definițiile funcțiilor. Inițial, numele parametrului de tip generic e declarat între paranteze unghiulare după denumirea structurii. În continuare, folosim tipul generic în cadrul definiției structurii în locul unde, de obicei, sunt specificate tipuri de date fixe.

Este esențial să avem în vedere că, prin utilizarea unui unic tip generic în definirea Point<T>, noi comunicăm că structura Point<T> este generică peste un anumit tip T, și că câmpurile x și y sunt în ambele situații de același tip, oricare ar fi acesta. Astfel, dacă creăm o instanță Point<T> cu valori ale tipurilor diferite, așa cum arată Listarea 10-7, codul nu va fi compilabil.

Numele fișierului: src/main.rs

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

Listarea 10-7: Câmpurile x și y trebuie să fie de același tip din cauză că ambele folosesc tipul de date generic T.

În exemplul de față, o dată ce atribuim x-ului valoarea întreagă 5, îi semnalăm compilatorului că pentru această instanță de Point<T>, tipul generic T va fi un întreg. Apoi, dacă pentru y specificăm valoarea 4.0, care ar trebui să fie de același tip ca x, vom întâmpina o eroare de incompatibilitate a tipurilor, după cum urmează:

$ 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` due to previous error

Dacă dorim să definim o structură Point în care x și y să fie generice și să accepte tipuri diferite, ne putem folosi de parametri de tip generic multipli. Ca exemplu, în Listarea 10-8, am modificat definiția lui Point pentru a deveni generică peste tipurile de date T și U, unde x este de tip T și y de tip U.

Numele fișierului: src/main.rs

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

Listarea 10-8: Structura Point<T, U>, generică peste două tipuri, permițând ca x și y să fie de tipuri diferite

Acum fiecare dintre exemplele prezentate pentru Point sunt posibile! Este permisă utilizarea unei varietăți de parametri de tip generic în definiția unei structuri, însă un exces în acest sens poate mări complexitatea codului și îl face greu de urmărit. Dacă-ți dai seama că ai nevoie de multe tipuri generice în codul tău, probabil ar fi benefică o restructurare pentru simplificarea codului.

În definiția enumerărilor

Ca și în cazul structurilor, putem defini enumerări ce includ tipuri de date generice în variantele lor. Să revizuim enumerarea Option<T>, pusă la dispoziție de biblioteca standard, pe care am utilizat-o anterior în Capitolul 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Această definiție ar trebui acum să fie mai inteligibilă pentru tine. După cum poți vedea, enumerarea Option<T> este generică peste tipul T și are două variante: Some, care include o valoare de tipul T, și None, care nu include nicio valoare. Utilizând enumerarea Option<T>, putem exprima conceptul abstract al unei valori facultative și, fiindcă Option<T> este generic, această noțiune poate fi aplicată indiferent de tipul valorii facultative.

De asemenea, enumerările pot folosi mai multe tipuri generice. Definiția enumerării Result, pe care am folosit-o în Capitolul 9, este un astfel de exemplu:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Enumerarea Result este generică peste două tipuri, T și E, și încorporează două variante: Ok, ce include o valoare de tip T, și Err, ce include o valoare de tip E. Această definiție facilitează folosirea enumerării Result în orice context avem o operațiune ce ar putea avea succes (întorcând o valoare de un anumit tip T) sau ar putea eșua (întorcând o eroare de un anumit tip E). Aceasta este metoda pe care am aplicat-o atunci când am deschis un fișier în Listarea 9-3, unde T a fost înlocuit cu tipul std::fs::File pentru un caz de succes și E a fost înlocuit cu std::io::Error pentru cazurile de eroare în deschiderea fișierului.

Atunci când întâmpini în codul tău situații în care multiple structuri sau enumerări se diferențiază doar prin tipul valorilor pe care le conțin, poți evita repetiția prin aplicarea tipurilor generice.

În definiția metodelor

Noi putem implementa metode pe structuri și enumerări, așa cum am făcut în Capitolul 5, utilizând și tipuri generice în definițiile lor. În Listarea 10-9 este prezentată structura Point<T>, definită anterior în Listarea 10-6, cu o metodă numită x implementată pe ea.

Numele fișierului: src/main.rs

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

Listarea 10-9: Implementarea unei metode denumite x pe structura Point<T>, care returnează o referință către câmpul x de tip T

Aici, am definit o metodă x pe Point<T> care oferă o referință către datele din câmpul x.

Este necesar să declarăm T imediat după impl pentru a putea folosi T în specificarea că implementăm metode pe structura Point<T>. Declarând T ca tip generic după impl, Rust înțelege că tipul din parantezele unghiulare din Point este generic și nu concret. Desigur, am fi putut alege un nume diferit pentru acest parametru generic, comparativ cu cel din definiția structurii, dar convenția sugerează utilizarea aceluiași nume. Metodele definite într-un bloc impl care declară tipul generic vor fi aplicabile pe orice instanță de Point<T>, indiferent de substituția tipului generic cu un tip concret.

Putem impune, de asemenea, anumite restricții asupra tipurilor generice când definim metode pe un anumit tip. De exemplu, putem implementa metode exclusiv pe instanțe de Point<f32> și nu pe Point<T> cu orice tip generic. În Listarea 10-10, utilizăm tipul concret f32, fără a declarăm tipuri după impl.

Numele fișierului: src/main.rs

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

Listarea 10-10: Un bloc impl specific pentru o structură cu un tip concret dat pentru parametrul generic T

Prin acest cod, Point<f32> va avea o metodă distance_from_origin, în timp ce alte instanțe de Point<T>, unde T nu este f32, nu vor avea definită această metodă. Metoda calculează cât de departe este un punct de originea de coordonate (0.0, 0.0), folosind operațiuni matematice specifice pentru tipurile cu virgulă mobilă.

Parametrii generici din definiția unei structuri nu trebuie să corespundă întotdeauna cu cei din semnăturile metodelor respectivei structuri. Listarea 10-11 folosește tipurile generice X1 și Y1 pentru structura Point și X2, Y2 pentru semnătura metodei mixup, pentru a ilustra mai clar concepția. Metoda creează o nouă instanță Point cu valoarea x din instanța self de tip X1 și valoarea y din instanța de Point primită ca argument, de tip Y2.

Numele fișierului: src/main.rs

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

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

Listarea 10-11: O metodă care utilizează tipuri generice diferite de cele ale definiției structurii sale

În funcția main, am definit un Point cu un i32 pentru x (valoare 5) și un f64 pentru y (valoare 10.4). Variabila p2 este un Point care conține o secțiune de string pentru x (cu valoarea "Hello") și un char pentru y (cu valoarea c). Apelând metoda mixup pe p1 cu argumentul p2 generăm variabila p3, ce va prelua valoarea x de tip i32 de la p1 și valoarea y de tip char de la p2. Apelul macro-ului println! va afișa: p3.x = 5, p3.y = c.

Exemplul servește la demonstrarea unei situații în care unii parametri generici sunt definiți în blocul impl și alții sunt incluși în definiția metodei propriu-zise. În acest context, parametrii generici X1 și Y1 sunt declarați alături de impl deoarece sunt asociați cu definiția structurii, în vreme ce X2 și Y2 sunt introduși odată cu definiția funcției mixup, având relevanță doar în contextul acelei metode.

Performanța codului folosind generici

Ai putea să te întrebi dacă folosirea parametrilor de tip generic implică un cost la rulare. Vestea excelentă este că utilizarea genericilor nu va încetini executarea programului tău comparativ cu folosirea tipurilor concrete.

Rust atinge acest performanță prin monomorfizarea codului cu generici în timpul compilării. Monomorfizarea este procesul prin care codul generic este transformat în cod specific, prin completarea cu tipurile concrete utilizate în momentul compilării. În acest proces, compilatorul face contrariul demersurilor noastre din crearea funcției generice prezentată în Listarea 10-5: acesta analizează toate locurile unde este invocat codul generic și generează cod pentru tipurile concrete utilizate.

Explorăm acest mecanism prin intermediul enum-ului generic Option<T> din biblioteca standardă a limbajului Rust:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

La compilarea acestui cod, Rust efectuează monomorfizarea. Compilatorul identifică valorile folosite în instanțele Option<T> și recunoaște două variante ale lui Option<T>: una pentru i32 și alta pentru f64. În consecință, extinde definiția generică a Option<T> în două versiuni specializate pentru i32 și f64, substituind astfel definiția generică.

Versiunea monomorfizată a codului ar putea arăta astfel (compilatorul folosește denumiri diferite de cele alese de noi aici pentru exemplificare):

Numele fișierului: src/main.rs

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

Genericul Option<T> este substituit cu definițiile specifice generate de compilator. Deoarece Rust transformă codul generic în cod care precizează tipul pentru fiecare instanță, nu întâmpinăm niciun cost suplimentar la rulare atunci când folosim genericii. Astfel, când codul este executat, performanța este echivalentă cu cea pe care am obține-o dacă am duplica manual fiecare definiție. Procesul de monomorfizare face ca genericii din Rust să fie extrem de performanți la executare.

Traits: definirea comportamentului partajat

O trăsătură (trait) definește funcționalitățile pe care un tip le posedă și care pot fi partajate cu alte tipuri. Noi utilizăm trăsăturile pentru a stabili în mod abstract comportamentul partajat. Totodată, prin limitele trăsăturii specificăm că un tip generic poate fi orice tip care manifestă anumite comportamente.

Notă: Trăsăturile sunt similare cu o funcționalitate frecvent întâlnită în alte limbaje de programare, des numită interfețe, deși există diferențe notabile.

Definirea unei trăsături

Comportamentul unui tip este caracterizat de metodele care pot fi invocate pe acel tip. Diverse tipuri au un comportament comun dacă este posibil să apelăm aceleași metode pe fiecare dintre ele. Definițiile trăsăturilor reprezintă o metodă de a grupa semnături de metode pentru a contura un set de comportamente necesare pentru îndeplinirea unui obiectiv anume.

Să presupunem, de exemplu, că dispunem de structuri multiple care stochează diferite cantități și tipuri de text: o structură NewsArticle care conține o știre legată de o locație specifică și un Tweet care poate avea până la 280 de caractere, împreună cu metadate care precizează dacă acesta este un tweet nou, un retweet sau un răspuns la un alt tweet.

Ne propunem să construim o crate de bibliotecă de agregare ale articolelor media numită aggregator, capabilă să prezinte sumare ale datelor care pot fi conținute de instanțe ale NewsArticle sau Tweet. Pentru acest lucru, avem nevoie de un rezumat din partea fiecărui tip, pe care îl solicităm prin apelarea metodei summarize pe o instanță respectivă. Listarea 10-12 ilustrează definiția unei trăsături publice Summary ce exprimă acest comportament.

Numele fișierului: src/lib.rs

pub trait Summary {
    fn summarize(&self) -> String;
}

Listarea 10-12: O trăsătură Summary ce constă din comportamentul oferit de metoda summarize

În acest caz, introducem o trăsătură utilizând cuvântul cheie trait urmat de numele trăsăturii, care este Summary. Am declarat trăsătura ca fiind publică (pub), astfel încât alte crate-uri care depind de acesta să aibă posibilitatea de a o folosi, așa cum vom observa în unele exemple ulterioare. În spațiul dintre acolade, sunt prezentate semnăturile metodelor care definesc comportamentele asumate de tipurile care implementează această trăsătură; în cazul de față fiind fn summarize(&self) -> String.

În loc să furnizăm o implementare a metodei între acolade, punem un punct și virgulă după semnătură. Fiecărui tip care realizează această trăsătură îi revine sarcina de a implementa propriul comportament pentru corpul metodei. Compilatorul va asigura că orice tip cu trăsătura Summary va avea definită metoda summarize cu anume această semnătură exactă.

O trăsătură poate include în corpul său mai multe metode: semnăturile acestora sunt enumerate independent, pe rânduri separate, iar fiecare rând se încheie cu un punct și virgulă.

Implementarea unei trăsături pentru un tip

Noi am definit semnăturile dorite ale metodelor trăsăturii Summary și acum e timpul să le implementăm pentru tipurile din agregatorul nostru de media. Listarea 10-13 ilustrează implementarea trăsăturii Summary pentru structura NewsArticle, utilizând titlul, autorul și locația pentru a crea valoarea de retur a metodei summarize. În cazul structurii Tweet, metoda summarize este definită ca numele de utilizator urmat de întregul text al tweet-ului, având în vedere că conținutul tweet-ului este limitat la 280 de caractere.

Numele fișierului: src/lib.rs

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 Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Listarea 10-13: Implementarea trăsăturii Summary pentru tipurile NewsArticle și Tweet

Implementarea unei trăsături pentru un tip este similară cu implementarea metodelor obișnuite. Diferența constă în faptul că, după impl, specificăm numele trăsăturii pe care dorim să o realizăm, folosim cuvântul cheie for, și apoi numele tipului pentru care implementăm trăsătura. În blocul impl, includem semnăturile metodelor definite de trăsătura respectivă. În loc să finalizăm fiecare semnătură cu un punct și virgulă, adăugăm acolade și detaliem corpul fiecărei metode pentru a defini comportamentul specific pe care îl dorim de la metodele trăsăturii pentru tipul respectiv.

Odată ce biblioteca noastră a implementat trăsătura Summary pentru NewsArticle și Tweet, utilizatori crate-ului pot folosi metodele trăsăturii pe instanțe de NewsArticle și Tweet, similar cu modul în care sunt apelate metodele obișnuite. Singura diferență este că utilizatorii trebuie să includă atât trăsătura cât și tipurile în domeniul de vizibilitate. Aici este un exemplu de cum ar putea fi utilizată biblioteca noastră aggregator în cadrul unui crate binar:

use aggregator::{Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 new tweet: {}", tweet.summarize());
}

Acest exemplu de cod va afișa 1 new tweet: horse_ebooks: of course, as you probably already know, people.

Alte crate-uri care utilizează crate-ul aggregator pot de asemenea să își aducă trăsătura Summary în domeniul de vizibilitate pentru a o implementa pe tipurile proprii. O restricție de reținut este că putem implementa o trăsătură pe un tip doar în cazul în care cel puțin unul dintre elemente - trăsătura sau tipul - este definit local în propriul nostru crate. De exemplu, putem implementa trăsături standard ale bibliotecii, cum ar fi Display, pentru un tip nativ crate-ului nostru ca Tweet, ca parte a funcționalității aggregator. De asemenea, putem implementa Summary pentru Vec<T> în cadrul aggregator, din moment ce trăsătura Summary este locală crate-ului nostru.

Cu toate acestea, nu avem posibilitatea să implementăm trăsături externe pentru tipuri externe. Spre exemplu, nu putem să realizăm implementarea trăsăturii Display pentru Vec<T> în cadrul crate-ului aggregator, pentru că atât Display cât și Vec<T> sunt parte din biblioteca standard și nu sunt locale lui aggregator. Această limitare este o parte din principiul de coerență, mai precis din regula orfanilor. Această regulă asigură că codul altor persoane nu poate interfera cu al tău și în același timp protejează codul tău de a fi afectat de alții. Fără această regulă, ar exista posibilitatea ca două crate-uri diferite să implementeze aceeași trăsătură pentru același tip, ceea ce ar crea confuzie pentru Rust cu privire la care implementare ar trebui utilizată.

Implementări implicite

Câteodată e util să avem un comportament implicit pentru unele sau pentru toate metodele unei trăsături în loc să necesităm implementări pentru toate metodele pe fiecare tip. Prin urmare, atunci când implementăm trăsătura pe un anumit tip, putem menține sau suprascrie comportamentul implicit al fiecărei metode.

În Listarea 10-14, am specificat un string implicit pentru metoda summarize a trăsăturii Summary în loc doar să definim semnătura metodei, cum am făcut în Listarea 10-12.

Numele fișierului: src/lib.rs

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Listarea 10-14: Definirea trăsăturii Summary cu o implementare implicită a metodei summarize

Pentru a folosi o implementare implicită în rezumarea instanțelor de NewsArticle, specificăm un bloc impl gol cu impl Summary for NewsArticle {}.

Deși nu mai definim metoda summarize în mod direct pe NewsArticle, am furnizat o implementare implicită și am specificat că NewsArticle implementează trăsătura Summary. Drept rezultat, putem totuși apela metoda summarize pe o instanță de NewsArticle, astfel:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

Acest cod afișează New article available! (Read more...).

Crearea unei implementări implicite nu ne obligă să modificăm nimic în ceea ce privește implementarea Summary pentru Tweet, conform Listării 10-13. Acest lucru este datorat faptului că sintaxa pentru a suprascrie o implementare implicită este identică cu sintaxa pentru implementarea unei metode de trăsătură care nu are nicio implementare implicită.

Implementările implicite pot apela alte metode din aceeași trăsătură, chiar dacă aceste alte metode nu dispun de implementări implicite. Astfel, o trăsătură poate oferi multe funcționalități utile și poate cere implementatorilor să definească doar o mică parte din acelea. De exemplu, am putea defini trăsătura Summary să includă o metodă summarize_author ce necesită implementare, și apoi să definim o metodă summarize care are o implementare implicită ce invocă summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Când folosim această versiune de Summary, trebuie să definim summarize_author doar când implementăm trăsătura pentru un tip:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

După ce definim summarize_author, putem invoca summarize pe instanțele structurii Tweet, iar implementarea implicită a summarize va utiliza definiția de summarize_author pe care am furnizat-o. Întrucât am implementat summarize_author, trăsătura Summary ne oferă funcționalitatea metodei summarize fără să fie nevoie să scriem cod suplimentar.

use aggregator::{self, Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 new tweet: {}", tweet.summarize());
}

Acest cod afișează 1 new tweet: (Read more from @horse_ebooks...).

Notă: nu este posibil să apelăm implementarea implicită din cadrul unei implementări care o suprascrie pe aceeași metodă.

Utilizarea trăsăturilor drept parametri

Înarmat cu abilitatea de a defini și implementa trăsături, ești acum pregătit să descoperi cum să folosești trăsături pentru a concepe funcții care să accepte o varietate de tipuri diferite. Vom apela la trăsătura Summary, implementată pentru NewsArticle și Tweet în Listarea 10-13, pentru a defini funcția notify care invocă metoda summarize pe parametrul său item. Acest item trebuie să fie de un tip care implementează trăsătura Summary. Procedăm astfel folosind sintaxa impl Trait, în modul următor:

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 Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

În loc de un tip explicit pentru parametrul item, specificăm cuvântul cheie impl și numele trăsăturii. Acest parametru va accepta orice tip care implementează trăsătura indicată. În cadrul funcției notify, avem posibilitatea să apelăm orice metode asociate cu item ce derivă din trăsătura Summary, precum summarize. Funcția notify poate fi apelată utilizând orice exemplar de NewsArticle sau Tweet. Încercarea de a folosi funcția cu tipuri care nu implementează Summary, cum ar fi String sau i32, nu va fi compilată, deoarece aceste tipuri nu îndeplinesc cerința trăsăturii Summary.

Sintaxa delimitării de trăsături

Sintaxa impl Trait este practică în situații simple, dar de fapt reprezintă o formă abreviată pentru o formă mai extinsă, cunoscută ca delimitare de trăsături (trait bound); aceasta se prezintă astfel:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

Această variantă completă este identică cu exemplul din secțiunea anterioară, dar mai explicită. Plasăm delimitările de trăsături împreună cu declararea parametrului de tip generic după două puncte (:) și în interiorul parantezelor unghiulare.

Sintaxa impl Trait oferă concizie în cazurile simple, în timp ce sintaxa extinsă a delimitărilor de trăsături poate să exprime mai multă complexitate în alte situații. De pildă, putem avea doi parametri ce implementează Summary. Aplicarea sintaxei impl Trait apare în felul următor:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

Utilizarea impl Trait este adecvată dacă dorim ca funcția să permită lui item1 și item2 să fie de tipuri diferite (atât timp cât ambele tipuri implementează Summary). Totuși, dacă vrem să constrângem ambii parametri să fie de același tip, atunci trebuie să apelăm la delimitarea de trăsături, ca în exemplul următor:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

Tipul generic T, specificat ca tip pentru parametrii item1 și item2, restricționează funcția astfel încât tipul concret al valorilor transmise ca argumente pentru item1 și item2 trebuie să fie același.

Indicarea mai multor delimitări de trăsătură folosind sintaxa +

Este posibil să specificăm concurent mai multe delimitări de trăsătă. De exemplu, dacă dorim ca notify să utilizeze formatare prin afișare, precum și metoda summarize pentru item, trebuie să notăm în definiția notify că item trebuie să implementeze trăsăturile Display și Summary. Putem realiza acest lucru utilizând sintaxa +:

pub fn notify(item: &(impl Summary + Display)) {

Această sintaxă + poate fi folosită și în cazul limitelor impuse pe trăsături pentru tipuri generice:

pub fn notify<T: Summary + Display>(item: &T) {

Odată ce ambele trăsături sunt specificate, în cadrul lui notify putem invoca summarize și folosi {} pentru a formata item, ceea ce este posibil datorită implementării trăsăturii Display.

Delimitări de trăsătură mai clare cu clauza where

Abundența de delimitări de trăsătură pe generici poate avea dezavantaje. Fiecare tip generic vine cu propriile sale restricții de trăsătură, astfel funcțiile cu mai mulți parametri generici pot fi supraîncărcate cu informații privind trăsăturile între numele funcției și lista parametrilor, complicând citirea semnăturii funcției. Pentru a simplifica această problemă, Rust oferă o sintaxă alternativă prin utilizarea unei clauze where care se plasează după semnătura funcției. Astfel, în loc de a scrie în modul următor:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

putem opta pentru utilizarea unei clauze where, cum ar fi:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

Semnătura funcției este astfel mai clară: numele funcției, lista parametrilor și tipul returnat sunt regrupate în proximitate, similar unei funcții simple care nu include numeroase restricții de trăsătură.

Returnarea tipurilor ce implementează trăsături

Este posibil de asemenea să utilizăm sintaxa impl Trait în poziția de returnare pentru a returna o valoare de un tip care implementează o trăsătură, așa cum este arătat în exemplul de mai jos:

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 Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    }
}

Prin aplicarea impl Summary ca tip de retur, indicăm că funcția returns_summarizable va întoarce un tip ce implementează trăsătura Summary, fără a specifica tipul concret. În acest caz specific, returns_summarizable returnează un Tweet, dar codul care cheamă această funcție nu are nevoie să cunoască acest amănunt.

Posibilitatea de a specifica un tip de retur exclusiv prin trăsătura implementată se dovedește a fi extrem de valoroasă în contextul închiderilor (closure) și iteratorilor, teme ce vor fi explorate în Capitolul 13. Aceste închideri și iteratori produc tipuri cunoscute doar de compilator sau tipuri care ar fi oneros de specificat complet. Sintaxa impl Trait facilitează specificarea succintă a faptului că o funcție returnează un tip care implementează trăsătura Iterator, eliminând necesitatea de a descrie un tip extensiv.

Totuși, impl Trait poate fi folosit doar atunci când se returnează un tip unic. Spre exemplu, codul care face returnarea unui NewsArticle sau un Tweet, având tipul de retur definit ca impl Summary, nu va funcționa:

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 Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        Tweet {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            retweet: false,
        }
    }
}

Este interzisă returnarea fie a unui NewsArticle, fie a unui Tweet, pe fondul restricțiilor asociate modului de implementare a sintaxei impl Trait în compilator. Metodologia de scriere a unei funcții cu acest comportament va fi detaliată în secțiunea „Utilizând obiecte de trăsătură ce permit valori pentru tipuri diverse” din Capitolul 17.

Folosirea delimitărilor de trăsături pentru implementarea condiționată a metodelor

Prin utilizarea unei delimitări de trăsături într-un bloc impl ce include parametri de tip generic, noi putem să implementăm metode în mod condiționat pentru tipurile care implementează trăsăturile specificate. Spre exemplu, tipul Pair<T> din Listarea 10-15 implementează constant funcția new pentru a crea o nouă instanță de Pair<T> (reîmprospătăm aici din secțiunea “Definirea Metodelor” a Capitolului 5 că Self este un sinonim pentru tipul blocului impl, care în acest caz este Pair<T>). Totuși, în următorul bloc impl, Pair<T> implementează metoda cmp_display doar dacă tipul său intern T aderă atât la trăsătura PartialOrd ce face posibilă compararea cât și la trăsătura Display ce permite afișarea.

Numele fișierului: src/lib.rs

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

Listarea 10-15: Implementarea condiționată a metodelor pe un tip generic, în dependență de delimitările de trăsătură

De asemenea, putem implementa condiționat o trăsătură pentru orice tip care implementează o altă trăsătură. Aceste implementări, realizate pentru orice tip care îndeplinește delimitările de trăsătură, poartă numele de implementări generalizate (blanket implementations) și sunt utilizate extensiv în biblioteca standard Rust. De exemplu, biblioteca standard oferă implementarea trăsăturii ToString pentru orice tip care implementează trăsătura Display. Blocul impl din biblioteca standard este similar cu acest fragment de cod:

impl<T: Display> ToString for T {
    // --snip--
}

Datorită acestei implementări generalizate prezente în biblioteca standard, noi putem invoca metoda to_string, definită de trăsătura ToString, pe orice tip ce implementează trăsătura Display. Ca urmare, avem posibilitatea de a transforma numere întregi în echivalentele lor String pentru că întregii implementează Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Implementările generalizate pot fi găsite în documentația referitoare la trăsătura respectivă, în secțiunea “Implementors”.

Trăsăturile și delimitările de trăsături ne permit să concepem cod care utilizează parametrii de tip generic pentru a reduce dublarea, dar ne și permit să indicăm compilatorului că dorim ca tipul generic să prezinte un anumit comportament. Compilatorul, folosind informațiile delimitărilor de trăsături, poate verifica dacă toate tipurile concrete folosite în codul nostru corespund comportamentului cerut. În limbajele de programare cu tipizare dinamică, erorile legate de apeluri ale unor metode nedefinite pe un tip apar la runtime, pe când Rust transferă aceste erori la timpul de compilare, obligându-ne să rezolvăm problemele înainte ca programul nostru să fie capabil să ruleze. Mai mult, evităm necesitatea de a scrie cod care să verifice comportamentul la runtime deoarece verificările au loc în timpul compilării. Acest proces îmbunătățește performanța fără a renunța la flexibilitatea oferită de utilizarea genericilor.

Validarea referințelor cu ajutorul lifetimes

Lifetimes sunt un alt fel de generici pe care i-am utilizat deja. Aceștia nu doar că asigură faptul că un tip are comportamentul pe care îl dorim, ci și că referințele rămân valide pentru durata necesară.

Un aspect pe care nu l-am discutat în secțiunea „Referințe și împrumutare” din Capitolul 4 este acela că fiecare referință în Rust deține un lifetime, adică un domeniu de vizibilitate pentru care referința este validă. În cele mai multe situații, lifetimes sunt impliciți și inferați, așa cum sunt și tipurile, în mod obișnuit. Adnotarea tipurilor este necesară doar atunci când mai multe tipuri sunt posibile. Analog, adnotarea lifetimes este necesară atunci când duratele de viață ale referințelor pot fi interpretate diferit. Rust ne cere să definim aceste relații utilizând parametri de lifetime generici pentru a garanta că referințele utilizate în timpul execuției vor fi valide în mod cert.

Conceptul de adnotare a lifetimes nu există în multe alte limbaje de programare, ceea ce îl face să ni se pară neobișnuit. Deși nu vom trata lifetimes în totalitatea lor în acest capitol, vom explora modalitățile comune prin care este posibil să întâlnim sintaxa specifică lifetimes astfel încât să ne obișnuim cu conceptul.

Combaterea referințelor suspendate prin intermediul duratelor de viață

Scopul esențial al duratelor de viață (lifetimes) este de a înlătura referințele suspendate (dangling references), care determină programul să referențieze alte date decât cele destinate. Analizează programul din Listarea 10-16, ce conține un domeniu de vizibilitate extern și unul intern.

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {}", r);
}

Listarea 10-16: Tentativa de a folosi o referință a cărei valoare nu mai este în domeniul de vizibilitate

Notă: În Listările 10-16, 10-17 și 10-23 sunt declarate variabile fără valori inițiale, astfel numele lor sunt prezente în domeniul extern. La prima vedere, acest lucru poate părea că intră în conflict cu faptul că Rust nu permite valori null. Cu toate acestea, dacă încercăm să utilizăm o variabilă înainte să îi atribuim o valoare, vom întâlni o eroare la compilare, confirmând astfel că Rust nu acceptă valori null.

În domeniul extern este declarată o variabilă r fără valoare inițială, iar în domeniul intern este declarată o variabilă x cu valoarea inițială de 5. În domeniul intern, încercăm să stabilim r ca referință la x. La încheierea domeniului intern, încercăm să afișăm valoarea referită de r. Acest cod nu va compila deoarece valoarea la care r face referire a ieșit din domeniul de vizibilitate înainte de a fi folosită. Iată mesajul de eroare:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
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` due to previous error

Variabila x nu "durează" suficient de mult. Aceasta iese din domeniul de vizibilitate când domeniul intern se sfârșește la linia 7. Cu toate acestea, r rămâne în domeniul extern; deoarece domeniul său de vizibilitate este mai amplu, spunem că "are o durată de viață mai mare". Dacă Rust ar permite ca acest cod să funcționeze, r ar face referință la memorie care a fost dezalocată când x a ieșit din domeniu, și orice tentativă de interacțiune cu r nu ar avea rezultate corecte. Cum determină Rust că acest cod este nevalid? Prin utilizarea unui verificator de împrumut (borrow checker).

Verificatorul de împrumut

Compilatorul Rust beneficiază de un verificator de împrumut care evaluează domeniile de vizibilitate și stabilește dacă toate împrumuturile sunt conforme. Listarea 10-17 îți prezintă același cod ca Listarea 10-16, dar cu adnotări ce indică durata de viață a variabilelor.

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {}", r); //          |
}                         // ---------+

Listarea 10-17: Adnotările duratelor de viață ale r și x, denumite 'a și 'b, în ordine

În exemplul de față, am însemnat durata de viață a r cu 'a și pe cea a lui x cu 'b. Remarcăm că blocul intern 'b este considerabil mai restrâns decât blocul extern 'a. În etapa de compilare, Rust analizează și compară extinderea celor două durate și identifică faptul că r există pentru 'a, dar face referire la memorie ale cărei valori au durata 'b. Programul este respins pentru că durata 'b este inferioară lui 'a: entitatea la care face referire nu persistă atât cât durează referința.

Listarea 10-18 rezolvă problema referinței suspendate și se compilează fără niciun fel de eroare.

fn main() {
    let x = 5;            // ----------+-- 'b
                          //           |
    let r = &x;           // --+-- 'a  |
                          //   |       |
    println!("r: {}", r); //   |       |
                          // --+       |
}                         // ----------+

Listarea 10-18: O referință corectă, având în vedere că informațiile referite au o durată de viață mai lungă decât referința însăși

În această situație, x deține durata de viață 'b, care de această dată excede 'a. Astfel, r are libertatea de a referi x, deoarece Rust confirmă că referința din r va fi întotdeauna în vigoare pe durata existenței lui x.

Acum, cunoscând localizarea duratelor de viață ale referințelor și metodologia prin care Rust le evaluează pentru a asigura validitatea neîntreruptă a acestora, să ne orientăm spre examinarea duratelor de viață generice pentru parametri și valori returnate în contextul funcțiilor.

Durate de viață generice în funcții

Să dezvoltăm o funcție care identifică care dintre două secțiuni de string-uri este mai lungă. Această funcție va accepta două secțiuni și va oferi ca rezultat o singură secțiune de string. Implementarea corespunzătoare pentru funcția longest va face ca exemplul prezentat în Listarea 10-19 să genereze output-ul The longest string is abcd.

Numele fișierului: src/main.rs

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {}", result);
}

Listarea 10-19: Funcția main apelează longest pentru a afla cea mai lungă secțiune dintre două secțiuni de string-uri

Trebuie subliniat faptul că funcția trebuie să opereze cu secțiuni de string-uri, adică referințe, nu cu string-uri, pentru că nu ne dorim ca longest să preia posesiunea asupra parametrilor săi. Consultă secțiunea “Secțiuni de string-uri ca parametri” din Capitolul 4 pentru mai multe explicații privind alegerea acestor parametri în Listarea 10-19.

Dacă vom încerca să implementăm longest așa cum e exemplificat în Listarea 10-20, vom observa că nu va compila.

Numele fișierului: src/main.rs

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

Listarea 10-20: O încercare de implementare a longest, care urmează să returneze secțiunea de string mai lungă, dar care în prezent nu compilează

Eroarea întâmpinată se referă la duratele de viață:

$ 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` due to previous error

Indicațiile de ajutor arată că tipul care se returnează necesită un parametru de durată de viață generic, pentru că Rust nu este capabil să determine dacă referința ce se returnează aparține lui x sau y. Și noi suntem în aceeași incertitudine, de vreme ce funcția poate returna fie o referință către x, fie una către y, în funcție de rezultatul condiției if.

Nu avem informațiile despre valorile exacte care vor fi introduse în funcție la definirea acesteia, deci nu putem prevedea care dintre cazurile if sau else se va întâmpla. Nu cunoaștem nici care vor fi duratele de viață concrete ale referințelor ce vor fi folosite, așa că nu putem estima domeniile lor de vizibilitate pentru a decide dacă referința returnată va fi mereu validă. Verificatorul de împrumut al lui Rust nu este capabil să facă aceste deducții singur; nu are cunoștințe despre cum se corelează duratele de viață ale lui x și y cu durata de viață a valorii ce urmează să fie returnată. Pentru a rectifica eroarea, trebuie să introducem parametri generici de durată de viață, care vor clarifica relația dintre referințele implicate, permițând astfel verificatorului de împrumut să realizeze analiza necesară.

Sintaxa adnotărilor pentru duratele de Viață

Adnotările pentru duratele de viață nu influențează cât timp supraviețuiesc referințele. În realitate, ele stabilesc relații între duratele de viață ale mai multor referințe, neavând impact asupra acestora. Asemănător cu funcțiile ce acceptă orice tip când sunt definite cu parametri generici de tip, funcțiile pot accepta referințe cu orice durată de viață specificând un parametru generic de durată de viață.

Adnotările pentru duratele de viață utilizează o sintaxă ceva mai neobișnuită: numele acestor parametri încep cu apostrof (') și sunt de regulă foarte scurte și scrise cu litere mici, în manieră similară tipurilor generice. Denumirea 'a este adesea prima opțiune pentru o adnotare de durată de viață. Aceste adnotări se plasează după simbolul & al unei referințe, cu un spațiu între adnotarea și tipul referinței.

Iată nişte exemple: o referință către un i32 fără un parametru de durată de viață, o referință către un i32 cu un parametru de durată de viață 'a, și o referință mutabilă către un i32 care are de asemenea durata de viață 'a.

&i32        // o referință
&'a i32     // o referință cu durată de viață explicită
&'a mut i32 // o referință mutabilă cu durată de viață explicită

O singură adnotare de durată de viață, luată individual, nu aduce multă claritate, deoarece aceste adnotări sunt proiectate să descrie pentru Rust cum relaționează între ele parametrii de durată de viață generici ai diferitelor referințe. Să analizăm cum aceste adnotări pentru duratele de viață interacționează reciproc în contextul funcției longest.

Adnotarea duratelor de viață în semnăturile funcțiilor

Pentru a aplica adnotări ale duratelor de viață în semnăturile funcțiilor, este necesar să declarăm parametrii de durată de viață generici, plasându-i între parantezele unghiulare care se află între numele funcției și lista de parametri, procedând astfel ca în cazul parametrilor de tip generici.

Semnătura trebuie să exprime următoarea restricție: referința returnată rămâne validă pe durata de viață a ambilor parametri. Aceasta descrie relația dintre duratele de viață ale parametrilor și valoarea returnată. Durata de viață 'a este numele pe care îl vom da acestei relații, pe care o vom adnota pe fiecare referință, așa cum este ilustrat în Listarea 10-21.

Numele fișierului: src/main.rs

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

Listarea 10-21: Definirea funcției longest, indicând că toate referințele din semnătură trebuie să aibă durata de viață 'a

Acest cod ar trebui să compileze și să genereze rezultatul dorit atunci când este folosit odată cu funcția main din Listarea 10-19.

Semnătura funcției ne anunță că pentru o anumită durată de viață 'a, aceasta primește doi parametri, ambii fiind secțiuni de string-uri care persistă minim pe durata de viață 'a. De asemenea, semnătura precizează că secțiunea de string returnată de funcție va persista cel puțin pe durata de viață 'a. În practică, acest lucru sugerează că durata de viață a referinței întoarse de funcțialongest corespunde cu cea mai scurtă durată de viață a valorilor referite de argumentele funcției. Aceste legături sunt relațiile pe care dorim ca Rust să le folosească în evaluarea codului nostru.

Trebuie reținut că atunci când definim parametri de durată de viață în această semnătură, nu modificăm duratele de viață ale valorilor care sunt transmise sau întoarse de funcție. În schimb, stabilim condițiile pe care verificatorul de împrumut trebuie să le aplice, respingând valorile care nu se încadrează în aceste limite. Cu alte cuvinte, funcția longest nu trebuie să cunoască exact cât timp x și y vor exista, ci trebuie să fie garantat că va exista o durată de viață care poate fi atribuită lui 'a și care va îndeplini cerințele acestei semnături.

Când vine vorba de adnotarea duratelor de viață în funcții, acestea sunt specificate în semnătura funcției, nu în corpul acesteia. Astfel adnotările devin parte integrantă a contractului funcției, pe picior de egalitate cu tipurile din semnătură. Includerea acestui contract de durată de viață în semnătura funcției simplifică analiza realizată de compilatorul Rust. Dacă întâmpinăm probleme legate de adnotările unei funcții sau de modul în care este invocată, erorile generate de compilator pot indica precis unde în codul nostru se află problemele și care sunt constrângerile nerespectate. Dacă ar exista o dependență mai mare pe inferențele Rust în ceea ce privește intențiile noastre legate de relațiile duratelor de viață, atunci compilatorul ar putea indica problemele abia după urmărirea utilizării codului la câteva niveluri de la cauza de bază.

Când folosim referințe specifice cu funcția longest, durata de viață concretă substituită pentru 'a este acea parte din durata de viață a lui x care coincide cu durata de viață a lui y. Mai direct spus, durata de viață generică 'a se va concretiza în cea mai scurtă durată de viață dintre cele ale lui x și y. Dat fiind că am adnotat referința returnată cu același parametru de durată de viață 'a, și referința returnată va fi validă pentru aceeași perioadă de timp cât sunt valide x și y.

Evaluăm acum modul în care adnotările de durată de viață limitează funcția longest printr-o demonstrație unde sunt folosite referințe cu durate de viață concrete diferite. Listarea 10-22 ne furnizează un astfel de exemplu explicit.

Numele fișierului: src/main.rs

fn main() {
    let string1 = String::from("long string is long");

    {
        let string2 = String::from("xyz");
        let result = longest(string1.as_str(), string2.as_str());
        println!("The longest string is {}", result);
    }
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

Listarea 10-22: Utilizarea funcției longest cu referințe la valori String ce au durate de viață concrete diferite

În acest caz, string1 rămâne valid până la încheierea domeniului de vizibilitate exterior, string2 este valid până la încheierea domeniului de vizibilitate interior, iar result indică o valoare care rămâne validă până la finalul domeniului de vizibilitate interior. Dacă executăm acest cod, vom constata că este acreditat de verificatorul de împrumut; va compila și va crea afișajul „The longest string is long string is long”.

Continuând, să analizăm un exemplu care ilustrează necesitatea ca durata de viață a referinței în `result` să fie mai scurtă decât duratele de viață ale celor două argumente. Declararea variabilei `result` va fi efectuată în afara domeniului de vizibilitate intern, în timp ce asignarea valorii pentru aceasta va rămâne în interiorul acelui domeniu împreună cu `string2`. Vom muta instrucțiunea `println!`, ce utilizează `result`, în afara domeniului intern, după ce acesta se încheie. Codul prezentat în Listarea 10-23 nu va fi compilabil.

<span class="filename">Numele fișierului: src/main.rs</span>

```rust,ignore,does_not_compile
fn main() {
    let string1 = String::from("long string is long");
    let result;
    {
        let string2 = String::from("xyz");
        result = longest(string1.as_str(), string2.as_str());
    }
    println!("The longest string is {}", result);
}
# 
# fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
#     if x.len() > y.len() {
#         x
#     } else {
#         y
#     }
# }

Listarea 10-23: Tentativa de utilizare a result după ce string2 nu se mai află în domeniul de vizibilitate

La încercarea de a compila acest cod, întâmpinăm eroarea:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `string2` does not live long enough
 --> src/main.rs:6:44
  |
6 |         result = longest(string1.as_str(), string2.as_str());
  |                                            ^^^^^^^^^^^^^^^^ borrowed value does not live long enough
7 |     }
  |     - `string2` dropped here while still borrowed
8 |     println!("The longest string is {}", result);
  |                                          ------ borrow later used here

For more information about this error, try `rustc --explain E0597`.
error: could not compile `chapter10` due to previous error

Eroarea ne arată că, pentru a fi valid pentru instrucțiunea println!, string2 ar necesita să fie disponibil până la finalul domeniului extern. Rust înțelege acest aspect deoarece am adnotat duratele de viață ale parametrilor funcției și ale valorii de retur utilizând același parametru 'a.

Noi, oamenii, putem privi acest cod și înțelege că string1 este disponibil mai mult timp decât string2 și, prin urmare, result va conține o referință către string1, care, nefiind încă ieșită din domeniul de vizibilitate, rămâne validă pentru instrucțiunea println!. Cu toate acestea, compilatorul nu este capabil să deducă că referința este validă în acest caz. I-am indicat compilatorului Rust că durata de viață a referinței returnate de funcția longest coincide cu durata cea mai scurtă a referințelor primite. În consecință, verificatorul de împrumut respinge codul din Listarea 10-23 pentru că s-ar putea să aibă o referință invalidă.

Propune-ți să experimentezi cu diverse scenarii care alterează valorile și duratele de viață ale referințelor transmise funcției longest, precum și modul în care este utilizată referința retur. Înainte de compilare, formulează presupuneri referitoare la rezultatele verificatorului de împrumut și verifică ulterior dacă acestea sunt corecte!

Gândirea în termeni de durate de viață

Alegerea parametrilor de durată de viață este strâns legată de lucrul efectuat de funcția în cauză. Dacă, spre exemplu, am decide ca funcția longest să returneze constant primul argument în locul celei mai lungi secțiuni de string, indicația de durată de viață pentru parametrul y nu ar fi necesară. Așadar, următorul cod va fi considerat valid de către compilator:

Numele fișierului: src/main.rs

fn main() {
    let string1 = String::from("abcd");
    let string2 = "efghijklmnopqrstuvwxyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {}", result);
}

fn longest<'a>(x: &'a str, y: &str) -> &'a str {
    x
}

Prin introducerea parametrului de durată de viață 'a pentru argumentul x și pentru tipul de retur, dar omițându-l pe y, recunoaștem că durata de viață a lui y nu are conexiuni cu durata de viață a lui x ori cu valoarea returnată.

O funcție care returnează o referință trebuie să sincronizeze durata de viață a tipului de retur cu durata de viață a unuia dintre argumente. Dacă referința returnată nu corespunde niciunui argument, atunci ea trebuie să indică spre o valoare creată intern în funcție, ceea ce inevitabil va crea o referință suspendată, dat fiind că respectivele valori vor părăsi domeniul de vizibilitate când funcția se încheie. Să luăm spre analiză un caz de implementare eșuată a funcției longest, care va fi respins de compilator:

Numele fișierului: src/main.rs

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: &str, y: &str) -> &'a str {
    let result = String::from("really long string");
    result.as_str()
}

Deși am definit parametrul de durată de viață 'a pentru tipul returnat, codul nu trece de etapa de compilare, pentru că durata de viață a valorii returnate nu are nicio legătură cu duratele de viață ale argumentelor. Acesta este mesajul de eroare afișat:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0515]: cannot return reference to local variable `result`
  --> src/main.rs:11:5
   |
11 |     result.as_str()
   |     ^^^^^^^^^^^^^^^ returns a reference to data owned by the current function

For more information about this error, try `rustc --explain E0515`.
error: could not compile `chapter10` due to previous error

Complicația de aici provine din faptul că result nu mai există după închiderea funcției longest, încercând totodată să returneze o referință către aceasta. Nu putem remedia prin parametrii de durată de viață acest tip de referință suspendată, iar in sistemul Rust, acestea sunt inacceptabile. În situații similare, soluția cea mai potrivită ar fi să optăm pentru returnarea unei date cu posesiune completă, nu sub formă de referință, astfel încât funcția apelatoare să preia responsabilitatea gestiunii acesteia.

Concluzionând, aplicarea corectă a sintaxei duratelor de viață leagă duratele de viață ale diverselor argumente de cele ale valorilor returnate, permițându-i astfel limbajului Rust să asigure operațiuni de gestionare a memoriei în mod sigur și să interzică orice operațiune ce ar putea duce la apariția referințelor suspendate sau care ar putea pune în pericol siguranța manipulării memoriei.

Adnotări de durată de viață în definițiile de structuri

Până acum, structurile pe care le-am descris includ tipuri de date cu posesiune proprie. Avem posibilitatea să definim structuri ce conțin referințe, dar pentru aceasta este necesar să adăugăm adnotări de durată de viață pentru toate referințele din definiția structurii. În Listarea 10-24, este prezentată structura ImportantExcerpt, care încorporează o secțiune de tip string.

Numele fișierului: src/main.rs

struct ImportantExcerpt<'a> {
    part: &'a str,
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let first_sentence = novel.split('.').next().expect("Could not find a '.'");
    let i = ImportantExcerpt {
        part: first_sentence,
    };
}

Listarea 10-24: Structura care include o referință necesitând adnotare de durată de viață

Structura posedă un unic câmp part, ce conține o secțiune dintr-un string, iar aceasta este o referință. În maniera tipurilor generice, numele parametrului generic al duratei de viață se declară în paranteze unghiulare după numele structurii, ceea ce ne permite să folosim parametrul în cadrul definiției structurii. Adnotarea indică faptul că o instanță de ImportantExcerpt nu are voie să depășească durata de viață a referinței din câmpul part.

Funcția main generează o instanță a structurii ImportantExcerpt, care înglobează o referință la prima sentință din String aparținând variabilei novel. Informația conținută în novel este disponibilă cu mult înainte de crearea instanței ImportantExcerpt. În plus, novel nu devine inaccesibil până după ce structura ImportantExcerpt este retrasă din domeniul de vizibilitate, făcând astfel ca referința din instanța ImportantExcerpt să fie validă.

Eliziunea duratei de viață

Am învățat că fiecare referință are o durată de viață şi trebuie să specificăm parametrii de durată de viață pentru funcții sau structuri care folosesc referințe. Totuși, în Capitolul 4, am prezentat o funcție în Listarea 4-9, reafirmată în Listarea 10-25, ce s-a compilat fără adnotări de durată de viață.

Numele fişierului: src/lib.rs

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // first_word works on slices of `String`s
    let word = first_word(&my_string[..]);

    let my_string_literal = "hello world";

    // first_word works on slices of string literals
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

Listarea 10-25: O funcție definită în Listarea 4-9 care s-a compilat fără adnotările de durată de viață, deși parametrul și tipul de retur sunt referințe

Funcția se compilează fără adnotări de durată de viață din motive istorice: în versiunile timpurii (pre-1.0) ale Rust, codul respectiv nu ar fi funcționat, fiind necesară o durată de viață explicită pentru fiecare referință. Semnătura funcției de atunci ar fi arătat astfel:

fn first_word<'a>(s: &'a str) -> &'a str {

După redactarea unei cantități considerabile de cod Rust, echipa a identificat situații specifice unde programatorii Rust repetă adnotări similare de durată de viață. Având un șablon previzibil și determinist, dezvoltatorii au înscris aceste modele în comportamentul compilatorului, astfel încât verificatorul de împrumut să poată înțelege duratele de viață implicit, eliminând necesitatea adnotărilor explicite.

Această parte din istoria Rust este relevantă, deoarece este posibil ca în viitor, pe măsură ce sunt identificate alte șabloane deterministe, să avem nevoie de și mai puține adnotări de durată de viață.

Regulile care guvernează această analiză a referințelor în Rust se numesc regulile de eliziune a duratei de viață. Acestea nu sunt directive pentru programatori, ci cazuri specifice pe care compilatorul le recunoaște, iar în prezența acestora, nu este nevoie să specifice durate de viață în cod.

Eliziunea nu implică inferență totală. Dacă, după aplicarea regulilor în mod deterministic, rămân ambiguități cu privire la duratele de viață ale anumitor referințe, compilatorul nu va specula asupra lor. În schimb, va emite o eroare ce poate fi rezolvată prin adăugarea explicită a adnotărilor necesare.

Duratele de viață asociate parametrilor de funcție sau metodei sunt cunoscute drept durate de viață de intrare, iar cele legate de valori returnate sunt durate de viață de ieșire.

Pentru deducerea duratelor de viață ale referințelor lipsite de adnotări explicite, compilatorul urmează trei reguli. Prima se aplică la duratele de viață de intrare, iar următoarele două la duratele de viață de ieșire. Dacă, după aceste trei reguli, există referințe având în continuare o durată de viață nedeterminată, compilatorul va întrerupe procesul și va raporta o eroare. Regulile sunt aplicabile atât definițiilor de fn, cât și blocurilor impl.

Prima regulă pe care compilatorul o impune este aceea că atribuie un parametru de durată de viață pentru fiecare parametru care este o referință. Concret, o funcție cu un singur parametru va avea un parametru de durată de viață: fn foo<'a>(x: &'a i32). În cazul unei funcții cu doi parametri, vor exista doi parametri de durată de viață separați: fn foo<'a, 'b>(x: &'a i32, y: &'b i32) și așa mai departe.

Conform celei de-a doua reguli, dacă avem un singur parametru de intrare cu durată de viață, atunci aceasta se aplică întregii ieșiri: fn foo<'a>(x: &'a i32) -> &'a i32.

Când intervin mai mulți parametri de intrare cu durate de viață și unul dintre aceștia este &self sau &mut self – adică în contextul unei metode – durata de viață a self se va atribui la întreaga ieșire. Acest lucru simplifică scrierea și citirea metodelor, deoarece nu este nevoie de atât de multe simboluri.

Imaginându-ne în rolul compilatorului, aplicăm aceste reguli pentru a înțelege duratele de viață ale referințelor din semnătura funcției first_word, așa cum e prezentată în Listarea 10-25. Semnătura inițială nu conține nicio durată de viață asociată referințelor:

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

Aplicând prima regulă, compilatorul acordă fiecărui parametru propria durată de viață, etichetată în mod tradițional cu 'a:

fn first_word<'a>(s: &'a str) -> &str {

Datorită prezenței unui unic parametru de intrare cu durată de viață, a doua regulă intervine pentru a atribui aceeași durată de viață și la ieșire, rezultând în următoarea semnătură:

fn first_word<'a>(s: &'a str) -> &'a str {

Astfel, toate referințele din această semnătură de funcție sunt acum prevăzute cu durate de viață, dând voie compilatorului să progreseze în analiză fără ca programatorul să fie nevoit să adnoteze manual aceste durate.

Luăm ca exemplu funcția longest, care la început nu includea parametri de durată de viață, așa cum vedem în Listarea 10-20:

fn longest(x: &str, y: &str) -> &str {