Rust-ohjelmointikieli

kirjoittanut Steve Klabnik, Carol Nichols ja Chris Krycho, Rust-yhteisön kontribuutioilla

Tämä tekstin versio olettaa, että käytät Rustia 1.96.0 (julkaistu 28.5.2026) tai uudempaa versiota ja että kaikissa projekteissa on Cargo.toml-tiedostossa edition = "2024", jotta ne käyttävät Rust 2024 -editionin idiomeja. Katso luvun 1 ”Asennus”-osio ohjeista Rustin asentamiseen tai päivittämiseen ja liite E tietoa editioneista.

HTML-muoto on saatavilla verkossa osoitteessa https://doc.rust-lang.org/stable/book/ ja offline-tilassa rustup-asennuksen mukana; avaa kirja komennolla rustup doc --book.

Useita yhteisön [käännöksiä] on myös saatavilla.

Teksti on saatavilla No Starch Pressin painettuna ja e-kirjana.

🚨 Haluatko interaktiivisemman oppimiskokemuksen? Kokeile toista versiota Rust-kirjasta, jossa on: kyselyitä, korostuksia, visualisointeja ja muuta: https://rust-book.cs.brown.edu

Esipuhe

Rust-ohjelmointikieli on edennyt pitkälle muutamassa vuodessa pienestä ja vasta syntyneestä harrastajayhteisöstä yhdeksi maailman rakastetuimmista ja kysytyimmistä ohjelmointikielistä. Taaksepäin katsottuna oli väistämätöntä, että Rustin voima ja lupaus herättäisivät huomiota ja saisivat jalansijaa järjestelmäohjelmoinnissa. Se, mikä ei ollut väistämätöntä, oli globaali kiinnostuksen ja innovaation kasvu, joka levisi avoimen lähdekoodin yhteisöihin ja nopeutti laajaa käyttöönottoa eri toimialoilla.

Tässä vaiheessa on helppo viitata Rustin upeisiin ominaisuuksiin selittääkseen tämän kiinnostuksen ja käyttöönoton räjähdysmäisen kasvun. Kuka ei haluaisi muistiturvallisuutta, ja nopeaa suorituskykyä, ja ystävällistä kääntäjää, ja loistavia työkaluja — muiden upeiden ominaisuuksien ohella? Rust-kieli, jota näet tänään, yhdistää vuosien tutkimuksen järjestelmäohjelmoinnissa elävän ja intohimoisen yhteisön käytännön viisauden kanssa. Kieli on suunniteltu tarkoituksella ja hiottu huolella, tarjoten kehittäjille työkalun, joka helpottaa turvallisen, nopean ja luotettavan koodin kirjoittamista.

Mutta mikä tekee Rustista todella erityisen, ovat sen juuret voimaannuttaa sinut saavuttamaan tavoitteesi. Tämä on kieli, joka haluaa sinun onnistuvan, ja voimaannuttamisen periaate kulkee läpi yhteisön, joka rakentaa, ylläpitää ja edistää tätä kieltä. Edellisen painoksen jälkeen Rust on kehittynyt entistä enemmän aidosti globaaliksi ja luotettavaksi kieleksi. Rust-projektia tukee nyt vankasti Rust Foundation, joka investoi myös keskeisiin aloitteisiin varmistaakseen, että Rust on turvallinen, vakaa ja kestävä.

Tämä painos Rust-ohjelmointikielestä on kattava päivitys, joka heijastaa kielen kehitystä vuosien varrella ja tarjoaa arvokasta uutta tietoa. Se ei kuitenkaan ole vain opas syntaksiin ja kirjastoihin — se on kutsu liittyä yhteisöön, joka arvostaa laatua, suorituskykyä ja harkittua suunnittelua. Olitpa kokenut kehittäjä, joka tutustuu Rustiin ensimmäistä kertaa, tai kokenut rustilainen, joka haluaa hioa taitojaan, tästä painoksesta on hyötyä kaikille.

Rust-matka on ollut yhteistyötä, oppimista ja iterointia. Kielen ja sen ekosysteemin kasvu heijastaa suoraan sen elävää ja monimuotoista yhteisöä. Tuhansien kehittäjien panos — ydinkielen suunnittelijoista satunnaisiin kontribuutioihin — tekee Rustista ainutlaatuisen ja tehokkaan työkalun. Ottamalla tämän kirjan käteesi et vain opi uutta ohjelmointikieltä — liityt liikkeeseen, joka pyrkii tekemään ohjelmistoista parempia, turvallisempia ja miellyttävämpiä työstää.

Tervetuloa Rust-yhteisöön!

• Bec Rumbul, Rust Foundationin toimitusjohtaja

Johdanto

Huom: Tämä kirjan painos on sama kuin The Rust Programming Language, joka on saatavilla painettuna ja e-kirjana No Starch Press -kustantajalta.

Tervetuloa lukemaan The Rust Programming Language -kirjaa, joka on johdatus Rust-ohjelmointikieleen. Rust-ohjelmointikieli auttaa sinua kirjoittamaan nopeampaa ja luotettavampaa ohjelmistoa. Korkean tason ergonomia ja matalan tason hallinta ovat usein ristiriidassa ohjelmointikielten suunnittelussa; Rust haastaa tämän ristiriidan. Tasapainottamalla tehokasta teknistä kapasiteettia ja erinomaista kehittäjäkokemusta Rust antaa sinulle mahdollisuuden hallita matalan tason yksityiskohtia (kuten muistin käyttöä) ilman perinteisesti näihin liittyvää vaivannäköä.

Kenelle Rust sopii

Rust sopii monille ihmisille monista syistä. Katsotaan muutamia tärkeimpiä ryhmiä.

Kehittäjätiimit

Rust on osoittautunut tuottavaksi työkaluksi suurten kehittäjätiimien yhteistyöhön, joissa on eri tasoisia järjestelmäohjelmoinnin osaamista. Matalan tason koodi on altis monille hienovaraisille bugeille, jotka useimmissa muissa kielissä havaitaan vasta laajan testauksen ja kokeneiden kehittäjien huolellisen koodikatselmuksen kautta. Rustissa kääntäjä toimii portinvartijana kieltäytymällä kääntämästä koodia, jossa on näitä vaikeasti havaittavia bugeja, mukaan lukien rinnakkaisuusbugeja. Työskennellessään kääntäjän rinnalla tiimi voi keskittyä ohjelman logiikkaan sen sijaan, että jahtaisi bugeja.

Rust tuo myös nykyaikaiset kehittäjätyökalut järjestelmäohjelmoinnin maailmaan:

• Cargo, mukana tuleva riippuvuuksien hallintatyökalu ja build-työkalu, tekee riippuvuuksien lisäämisestä, kääntämisestä ja hallinnasta vaivatonta ja yhtenäistä koko Rust-ekosysteemissä.
• rustfmt-muotoilutyökalu varmistaa yhtenäisen koodaustyylin eri kehittäjien välillä.
• Rust Language Server tarjoaa integroidun kehitysympäristön (IDE) tuen koodin täydennykselle ja rivikohtaisille virheilmoituksille.

Käyttämällä näitä ja muita Rust-ekosysteemin työkaluja kehittäjät voivat olla tuottavia kirjoittaessaan järjestelmätason koodia.

Opiskelijat

Rust sopii opiskelijoille ja niille, jotka ovat kiinnostuneita oppimaan järjestelmäkäsitteistä. Rustin avulla monet ovat oppineet aiheita, kuten käyttöjärjestelmien kehitystä. Yhteisö on erittäin vieraanvarainen ja vastaa mielellään opiskelijoiden kysymyksiin. Tämän kirjan kaltaisten ponnistusten kautta Rust-tiimit haluavat tehdä järjestelmäkäsitteistä helpommin saavutettavia useammille ihmisille, erityisesti ohjelmointiin vasta tutustuville.

Yritykset

Satoja yrityksiä, suuria ja pieniä, käyttää Rustia tuotannossa monenlaisiin tehtäviin, mukaan lukien komentorivityökalut, web-palvelut, DevOps-työkalut, sulautetut laitteet, äänen ja videon analysointi ja transkoodaus, kryptovaluutat, bioinformatiikka, hakukoneet, esineiden internet -sovellukset, koneoppiminen ja jopa merkittäviä osia Firefox-selaimesta.

Avoimen lähdekoodin kehittäjät

Rust on niille, jotka haluavat rakentaa Rust-ohjelmointikieltä, yhteisöä, kehittäjätyökaluja ja kirjastoja. Haluaisimme mielellämme sinun osallistuvan Rust-kielen kehitykseen.

Nopeutta ja vakautta arvostavat

Rust on niille, jotka kaipaavat nopeutta ja vakautta kielessä. Nopeudella tarkoitamme sekä sitä, kuinka nopeasti Rust-koodi voi suorittua, että sitä, kuinka nopeasti Rustin avulla voi kirjoittaa ohjelmia. Rust-kääntäjän tarkistukset varmistavat vakauden ominaisuuksien lisäysten ja refaktoroinnin aikana. Tämä eroaa hauraasta legacy-koodista kielissä, joissa näitä tarkistuksia ei ole ja jota kehittäjät usein pelkäävät muokata. Pyrkimällä nollakustannuksisiin abstraktioihin— korkean tason ominaisuuksiin, jotka kääntyvät matalan tason koodiksi yhtä nopeasti kuin käsin kirjoitettu koodi—Rust pyrkii tekemään turvallisesta koodista myös nopeaa koodia.

Rust-kieli toivoo tukevansa monia muitakin käyttäjiä; tässä mainitut ovat vain joitakin suurimpia sidosryhmiä. Kaiken kaikkiaan Rustin suurin tavoite on poistaa kompromissit, jotka ohjelmoijat ovat hyväksyneet vuosikymmeniä, tarjoamalla turvallisuuden ja tuottavuuden, nopeuden ja ergonomian. Kokeile Rustia ja katso, toimivatko sen valinnat sinulle.

Kenelle tämä kirja on tarkoitettu

Tämä kirja olettaa, että olet kirjoittanut koodia toisella ohjelmointikielellä, mutta se ei tee oletuksia siitä, millä kielellä. Olemme pyrkineet tekemään materiaalista laajasti saavutettavaa erilaisista ohjelmointitaustoista tuleville. Emme käytä paljon aikaa siihen, mitä ohjelmointi on tai miten siitä ajatellaan. Jos olet täysin uusi ohjelmoinnissa, saat paremman hyödyn kirjasta, joka on erityisesti suunnattu ohjelmoinnin johdatukseksi.

Kuinka käyttää tätä kirjaa

Yleensä tämä kirja olettaa, että luet sen järjestyksessä alusta loppuun. Myöhemmät luvut rakentuvat aiempien lukujen käsitteiden varaan, ja aiemmat luvut eivät välttämättä syvenny tiettyyn aiheeseen, vaan palaavat siihen myöhemmässä luvussa.

Löydät tästä kirjasta kahta lajia lukuja: käsite- ja projektilukuja. Käsite-luvuissa opit Rustin jonkin puolen. Projektiluvuissa rakennamme yhdessä pieniä ohjelmia soveltaen tähän mennessä oppimaasi. Luvut 2, 12 ja 21 ovat projektilukuja; muut ovat käsite-lukuja.

Luku 1 selittää, miten Rust asennetaan, miten kirjoitetaan “Hello, world!” -ohjelma ja miten käytetään Cargo-työkalua, Rustin paketinhallintaa ja build-työkalua. Luku 2 on käytännönläheinen johdatus Rust-ohjelman kirjoittamiseen, jossa rakennat arvauspeliä. Tässä käsittelemme asioita korkealla tasolla, ja myöhemmät luvut tarjoavat lisätietoa. Jos haluat päästä heti käsiksi koodiin, Luku 2 on oikea paikka. Jos olet erityisen huolellinen oppija, joka haluaa oppia jokaisen yksityiskohdan ennen seuraavaan siirtymistä, voit ohittaa Luvun 2 ja siirtyä suoraan Lukuun 3, joka käsittelee Rustin ominaisuuksia, jotka ovat samankaltaisia kuin muissa ohjelmointikielissä; voit sitten palata Lukuun 2, kun haluat työskennellä projektin parissa soveltaen oppimaasi.

Luvussa 4 opit Rustin omistajuusjärjestelmästä. Luku 5 käsittelee structeja ja metodeja. Luku 6 käsittelee enumeja, match-lausekkeita sekä if let- ja let...else-ohjausrakenteita. Käytät structeja ja enumeja mukautettujen tyyppien luomiseen.

Luvussa 7 opit Rustin moduulijärjestelmästä ja yksityisyysäännöistä koodin ja sen julkisen sovellusohjelmointirajapinnan (API) järjestämiseen. Luku 8 käsittelee joitakin yleisiä kokoelmien tietorakenteita, joita standardikirjasto tarjoaa: vektoreita, merkkijonoja ja hash-taulukoita. Luku 9 tutkii Rustin virheenkäsittelyfilosofiaa ja -tekniikoita.

Luku 10 syventyy geneerisyyteen, traitteihin ja elinikäihin, jotka antavat sinulle mahdollisuuden määritellä koodia, joka soveltuu useille tyypeille. Luku 11 käsittelee testausta, joka on tarpeen Rustin turvallisuustakuista huolimatta varmistamaan ohjelmasi logiikan oikeellisuus. Luvussa 12 rakennamme oman toteutuksemme osasta grep-komentorivityökalun toiminnallisuudesta, joka etsii tekstiä tiedostoista. Tähän käytämme monia aiemmissa luvuissa käsittelemiämme käsitteitä.

Luku 13 tutkii sulkeumia ja iteraattoreita: Rustin ominaisuuksia, jotka tulevat funktionaalisista ohjelmointikielistä. Luvussa 14 tarkastelemme Cargo-työkalua tarkemmin ja puhumme parhaista käytännöistä kirjastojesi jakamiseen muiden kanssa. Luku 15 käsittelee älykkäitä osoittimia, joita standardikirjasto tarjoaa, ja traitteja, jotka mahdollistavat niiden toiminnallisuuden.

Luvussa 16 käymme läpi erilaisia rinnakkaisohjelmoinnin malleja ja puhumme siitä, miten Rust auttaa sinua ohjelmoimaan useissa säikeissä pelottomasti. Luvussa 17 rakennamme tämän päälle tutkien Rustin async- ja await-syntaksia sekä tehtäviä, futureja ja streameja ja niiden mahdollistamaa kevyttä rinnakkaisuusmallia.

Luku 18 tarkastelee, miten Rustin idiomit vertautuvat tuttuihin olio-ohjelmoinnin periaatteisiin. Luku 19 on viite kuvioihin ja kuvioiden täsmäyttämiseen, jotka ovat tehokkaita tapoja ilmaista ideoita Rust-ohjelmissa. Luku 20 sisältää valikoiman edistyneitä aiheita, mukaan lukien unsafe Rust, makrot ja lisätietoa elinikäistä, traitteista, tyypeistä, funktioista ja sulkeumista.

Luvussa 21 viimeistelemme projektin, jossa toteutamme matalan tason monisäikeisen web-palvelimen!

Lopuksi joissakin liitteissä on hyödyllistä tietoa kielestä viitemuotoisemmassa muodossa. Liite A käsittelee Rustin avainsanoja, Liite B Rustin operaattoreita ja symboleja, Liite C standardikirjaston tarjoamia johdettavia traitteja, Liite D hyödyllisiä kehitystyökaluja ja Liite E selittää Rustin editioneja. Liitteestä F löydät kirjan käännökset, ja Liitteessä G käsittelemme, miten Rustia tehdään ja mitä nightly Rust on.

Tätä kirjaa voi lukea monella tavalla: jos haluat hypätä eteenpäin, tee se! Saatat joutua palaamaan aiempiin lukuihin, jos kohtaat hämmennystä. Tee kuitenkin miten parhaalta tuntuu.

Tärkeä osa Rustin oppimista on oppia lukemaan kääntäjän näyttämiä virheilmoituksia: ne ohjaavat sinua kohti toimivaa koodia. Siksi tarjoamme monia esimerkkejä, jotka eivät käänny, sekä kääntäjän näyttämän virheilmoituksen kussakin tilanteessa. Huomaa, että jos kirjoitat ja suoritat satunnaisen esimerkin, se ei välttämättä käänny! Varmista, että luet ympäröivän tekstin nähdäksesi, onko esimerkki, jota yrität suorittaa, tarkoitettu virheeseen. Useimmissa tilanteissa ohjaamme sinut oikeaan versioon koodista, joka ei käänny. Ferris auttaa myös erottamaan koodin, joka ei ole tarkoitettu toimimaan:

Ferris	Merkitys
	Tämä koodi ei käänny!
	Tämä koodi panikoi!
	Tämä koodi ei tuota haluttua käyttäytymistä.

Useimmissa tilanteissa ohjaamme sinut oikeaan versioon koodista, joka ei käänny.

Lähdekoodi

Tämän kirjan lähdekooditiedostot löytyvät GitHubista.

Aloittaminen

Aloitetaan Rustin matka! On paljon opittavaa, mutta jokainen matka alkaa jostain. Tässä luvussa käsittelemme:

• Rustin asentaminen Linuxille, macOS:lle ja Windowsille
• Ohjelman kirjoittaminen, joka tulostaa Hello, world!
• cargo-työkalun käyttö, joka on Rustin paketinhallinta- ja rakennusjärjestelmä

Asennus

Asennus

Ensimmäinen askel on Rustin asentaminen. Lataamme Rustin rustup-työkalun kautta, joka on komentorivityökalu Rust-versioiden ja niihin liittyvien työkalujen hallintaan. Tarvitset internet-yhteyden latausta varten.

Huom: Jos et halua käyttää rustup-työkalua jostain syystä, katso muut Rustin asennustavat -sivulta lisää vaihtoehtoja.

Seuraavat vaiheet asentavat uusimman vakaan version Rust-kääntäjästä. Rustin vakaustakuut varmistavat, että kaikki tämän kirjan esimerkit, jotka kääntyvät, kääntyvät edelleen myös uudemmissa Rust-versioissa. Tuloste voi hieman erota versioiden välillä, koska Rust parantaa virheilmoituksia ja varoituksia säännöllisesti. Toisin sanoen, mikä tahansa näillä ohjeilla asennettu uudempi vakaa Rust-versio toimii odotetusti tämän kirjan sisällön kanssa.

rustup-asennus Linuxilla tai macOS:llä

Jos käytät Linuxia tai macOS:ää, avaa terminaali ja kirjoita seuraava komento:

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

Komento lataa skriptin ja käynnistää rustup-työkalun asennuksen, joka asentaa uusimman vakaan Rust-version. Sinua saatetaan pyytää salasanaasi. Jos asennus onnistuu, näet seuraavan rivin:

Rust is installed now. Great!

Tarvitset myös linkkerin, joka on ohjelma, jota Rust käyttää yhdistääkseen kääntämänsä tulosteet yhdeksi tiedostoksi. Sinulla on todennäköisesti jo sellainen. Jos saat linkkerivirheitä, sinun pitäisi asentaa C-kääntäjä, joka yleensä sisältää linkkerin. C-kääntäjä on hyödyllinen myös siksi, että jotkin yleiset Rust-paketit riippuvat C-koodista ja tarvitsevat C-kääntäjän.

macOS:llä voit hankkia C-kääntäjän suorittamalla:

$ xcode-select --install

Linux-käyttäjien tulisi yleensä asentaa GCC tai Clang jakelunsa dokumentaation mukaisesti. Esimerkiksi Ubuntussa voit asentaa build-essential-paketin.

rustup-asennus Windowsilla

Windowsissa siirry osoitteeseen https://www.rust-lang.org/tools/install ja seuraa Rustin asennusohjeita. Asennuksen aikana sinua pyydetään asentamaan Visual Studio. Se tarjoaa linkkerin ja natiivit kirjastot, joita ohjelmien kääntäminen tarvitsee. Jos tarvitset lisäapua tässä vaiheessa, katso https://rust-lang.github.io/rustup/installation/windows-msvc.html.

Tämän kirjan loppuosa käyttää komentoja, jotka toimivat sekä cmd.exe:ssä että PowerShellissä. Jos on erityisiä eroja, selitämme, kumpaa käyttää.

Vianmääritys

Voit tarkistaa, onko Rust asennettu oikein, avaamalla komentorivin ja kirjoittamalla:

$ rustc --version

Sinun pitäisi nähdä versionumero, commit-hash ja commit-päivämäärä uusimmalle julkaistulle vakaalle versiolle seuraavassa muodossa:

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

Jos näet nämä tiedot, Rust on asennettu onnistuneesti! Jos et näe niitä, tarkista, että Rust on %PATH%-järjestelmämuuttujassasi seuraavasti.

Windows CMD:ssä käytä:

> echo %PATH%

PowerShellissä käytä:

> echo $env:Path

Linuxissa ja macOS:ssä käytä:

$ echo $PATH

Jos kaikki on oikein ja Rust ei silti toimi, voit saada apua monista paikoista. Ota selvää, miten voit olla yhteydessä muihin Rustaceaneihin (leikkisä lempinimi, jolla kutsumme itseämme) yhteisösivulta.

Päivittäminen ja poistaminen

Kun Rust on asennettu rustup-työkalun kautta, uuteen julkaistuun versioon päivittäminen on helppoa. Suorita komentorivillä seuraava päivitysskripti:

$ rustup update

Poistaaksesi Rustin ja rustup-työkalun, suorita seuraava poistoskripti komentorivillä:

$ rustup self uninstall

Paikallisen dokumentaation lukeminen

Rustin asennuksen mukana tulee paikallinen kopio dokumentaatiosta, joten voit lukea sitä offline-tilassa. Avaa paikallinen dokumentaatio selaimessasi komennolla rustup doc.

Aina kun standardikirjasto tarjoaa tyypin tai funktion etkä ole varma, mitä se tekee tai miten sitä käytetään, käytä sovellusohjelmointirajapinnan (API) dokumentaatiota selvittääksesi!

Tekstieditorien ja IDE:iden käyttö

Tämä kirja ei tee oletuksia siitä, mitä työkaluja käytät Rust-koodin kirjoittamiseen. Melkein mikä tahansa tekstieditori hoitaa homman! Monet tekstieditorit ja integroidut kehitysympäristöt (IDE) tarjoavat kuitenkin sisäänrakennettua Rust-tukea. Löydät melko ajantasaisen listan monista editoreista ja IDE:istä työkalusivulta Rustin verkkosivustolla.

Tämän kirjan käyttö offline-tilassa

Useissa esimerkeissä käytämme Rust-paketteja standardikirjaston ulkopuolelta. Työskennelläksesi näiden esimerkkien parissa tarvitset joko internet-yhteyden tai olet ladannut riippuvuudet etukäteen. Ladataksesi riippuvuudet etukäteen voit suorittaa seuraavat komennot. (Selitämme myöhemmin tarkemmin, mikä cargo on ja mitä kukin komento tekee.)

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

Tämä tallentaa näiden pakettien lataukset välimuistiin, joten sinun ei tarvitse ladata niitä myöhemmin. Kun olet suorittanut tämän komennon, sinun ei tarvitse säilyttää get-dependencies-kansiota. Jos olet suorittanut tämän komennon, voit käyttää --offline-lippua kaikissa cargo-komennoissa kirjan loppuosassa käyttääksesi näitä välimuistissa olevia versioita verkon käytön sijaan.

Hei, maailma!

Hello, World!

Nyt kun olet asentanut Rustin, on aika kirjoittaa ensimmäinen Rust-ohjelmasi. Uutta kieltä opiskellessa on perinteistä kirjoittaa pieni ohjelma, joka tulostaa tekstin Hello, world! näytölle, joten teemme saman tässä!

Huom: Tämä kirja olettaa perustuntemusta komentorivistä. Rust ei aseta erityisiä vaatimuksia editorillesi, työkaluillesi tai koodisi sijainnille, joten jos haluat käyttää IDE:tä komentorivin sijaan, käytä vapaasti suosikki-IDE:täsi. Monilla IDE:illä on nyt jonkin verran Rust-tukea; katso IDE:n dokumentaatiosta yksityiskohdat. Rust-tiimi on keskittynyt erinomaisen IDE-tuen mahdollistamiseen rust-analyzer-työkalun kautta. Katso Liite D lisätietoja varten.

Projektikansion luominen

Aloitat luomalla kansion Rust-koodillesi. Rustille ei ole väliä, missä koodisi sijaitsee, mutta tämän kirjan harjoituksia ja projekteja varten suosittelemme projects-kansion luomista kotihakemistoosi ja kaikkien projektiesi säilyttämistä siellä.

Avaa terminaali ja kirjoita seuraavat komennot luodaksesi projects-kansion ja “Hello, world!” -projektin kansion projects-kansion sisään.

Linuxissa, macOS:ssä ja PowerShellissä Windowsilla kirjoita tämä:

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

Windows CMD:ssä kirjoita tämä:

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

Rust-ohjelman perusteet

Seuraavaksi luo uusi lähdekooditiedosto ja kutsu sitä main.rs. Rust-tiedostot päättyvät aina .rs-päätteeseen. Jos käytät tiedostonimessä useampaa sanaa, käytä niiden erottamiseen alaviivaa. Käytä esimerkiksi hello_world.rs eikä helloworld.rs.

Avaa juuri luomasi main.rs-tiedosto ja kirjoita siihen Listauksen 1-1 koodi.

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

Tallenna tiedosto ja palaa terminaali-ikkunaan ~/projects/hello_world-kansiossa. Linuxissa tai macOS:ssä kirjoita seuraavat komennot tiedoston kääntämiseksi ja suorittamiseksi:

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

Windowsissa kirjoita komento .\main ./main-komennon sijaan:

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

Käyttöjärjestelmästä riippumatta merkkijono Hello, world! pitäisi tulostua terminaaliin. Jos et näe tätä tulostetta, katso Vianmääritys -osio asennusluvusta saadaksesi apua.

Jos Hello, world! tulostui, onnittelut! Olet virallisesti kirjoittanut Rust-ohjelman. Se tekee sinusta Rust-ohjelmoijan—tervetuloa!

Rust-ohjelman rakenne

Käydään tämä “Hello, world!” -ohjelma läpi yksityiskohtaisesti. Tässä on ensimmäinen palanen:

fn main() {

}

Nämä rivit määrittelevät funktion nimeltä main. main-funktio on erityinen: se on aina ensimmäinen koodi, joka suoritetaan jokaisessa ajettavassa Rust-ohjelmassa. Tässä ensimmäinen rivi julistaa main-nimisen funktion, jolla ei ole parametreja eikä se palauta mitään. Jos parametreja olisi, ne olisivat sulkeissa (()).

Funktion runko on kääritty {}-merkkeihin. Rust vaatii aaltosulkeet kaikkien funktioiden runkojen ympärille. On hyvä tyyli sijoittaa avaava aaltosulje samalle riville funktion julistuksen kanssa ja jättää niiden väliin yksi välilyönti.

Huom: Jos haluat noudattaa yhtenäistä tyyliä Rust-projekteissa, voit käyttää automaattista muotoilutyökalua nimeltä rustfmt muotoillaksesi koodisi tietyssä tyylissä (lisätietoa rustfmt-työkalusta Liitteessä D). Rust-tiimi on sisällyttänyt tämän työkalun standardiin Rust-jakeluun, kuten rustc-kääntäjäkin, joten sen pitäisi olla jo asennettuna tietokoneellesi!

main-funktion rungossa on seuraava koodi:

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

Tämä rivi tekee kaiken työn tässä pienessä ohjelmassa: se tulostaa tekstiä näytölle. Tässä on kolme tärkeää yksityiskohtaa.

Ensinnäkin println! kutsuu Rust-makroa. Jos se olisi kutsunut funktiota, se kirjoitettaisiin println (ilman !-merkkiä). Rust-makrot ovat tapa kirjoittaa koodia, joka generoi koodia laajentaakseen Rustin syntaksia, ja käsittelemme niitä tarkemmin Luvussa 20. Toistaiseksi sinun tarvitsee vain tietää, että !-merkin käyttö tarkoittaa, että kutsut makroa tavallisen funktion sijaan ja että makrot eivät aina noudata samoja sääntöjä kuin funktiot.

Toiseksi näet merkkijonon "Hello, world!". Välitämme tämän merkkijonon argumenttina println!-makrolle, ja merkkijono tulostetaan näytölle.

Kolmanneksi päätteemme rivin puolipisteellä (;), joka osoittaa, että tämä lauseke on ohi ja seuraava on valmis alkamaan. Useimmat Rust-koodin rivit päättyvät puolipisteeseen.

Kääntäminen ja suorittaminen

Suoritit juuri juuri luomasi ohjelman, joten tarkastellaan prosessin jokaista vaihetta.

Ennen Rust-ohjelman suorittamista sinun on käännettävä se Rust-kääntäjällä kirjoittamalla rustc-komento ja välittämällä sille lähdekooditiedostosi nimi, näin:

$ rustc main.rs

Jos sinulla on C- tai C++-tausta, huomaat, että tämä on samankaltaista kuin gcc tai clang. Onnistuneen kääntämisen jälkeen Rust tuottaa binäärisen ajettavan tiedoston.

Linuxissa, macOS:ssä ja PowerShellissä Windowsilla näet ajettavan tiedoston kirjoittamalla ls-komennon komentorivilläsi:

$ ls
main  main.rs

Linuxissa ja macOS:ssä näet kaksi tiedostoa. PowerShellissä Windowsilla näet samat kolme tiedostoa kuin CMD:ssä. CMD:ssä Windowsilla kirjoittaisit seuraavan:

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

Tämä näyttää lähdekooditiedoston .rs-päätteellä, ajettavan tiedoston (main.exe Windowsilla, mutta main kaikilla muilla alustoilla) ja Windowsilla käytettäessä tiedoston, joka sisältää virheenkorjaustietoja .pdb-päätteellä. Tästä eteenpäin suoritat main- tai main.exe-tiedoston näin:

$ ./main # or .\main on Windows

Jos main.rs on “Hello, world!” -ohjelmasi, tämä rivi tulostaa Hello, world! terminaaliisi.

Jos olet tottunut dynaamiseen kieleen, kuten Rubyyn, Pythoniin tai JavaScriptiin, et ehkä ole tottunut kääntämisen ja ohjelman suorittamisen erottamiseen eri vaiheiksi. Rust on etukäteen käännettävä kieli, mikä tarkoittaa, että voit kääntää ohjelman ja antaa ajettavan tiedoston jollekin toiselle, ja he voivat suorittaa sen vaikka heillä ei olisi Rustia asennettuna. Jos annat jollekulle .rb-, .py- tai .js-tiedoston, he tarvitsevat Ruby-, Python- tai JavaScript-toteutuksen asennettuna (vastaavasti). Mutta näissä kielissä tarvitset vain yhden komennon ohjelmasi kääntämiseen ja suorittamiseen. Kaikki on kompromissi kielen suunnittelussa.

Pelkkä kääntäminen rustc-kääntäjällä riittää yksinkertaisiin ohjelmiin, mutta projektisi kasvaessa haluat hallita kaikkia vaihtoehtoja ja helpottaa koodisi jakamista. Seuraavaksi esittelemme sinulle Cargo-työkalun, joka auttaa kirjoittamaan tosielämän Rust-ohjelmia.

Hei, Cargo!

Hello, Cargo!

Cargo on Rustin build-järjestelmä ja paketinhallinta. Useimmat Rustaceanit käyttävät tätä työkalua Rust-projektiensa hallintaan, koska Cargo hoitaa puolestasi monia tehtäviä, kuten koodisi kääntämisen, koodisi tarvitsemien kirjastojen lataamisen ja näiden kirjastojen kääntämisen. (Kutsumme koodisi tarvitsemia kirjastoja riippuvuuksiksi.)

Yksinkertaisimmilla Rust-ohjelmilla, kuten tähän asti kirjoittamallamme, ei ole riippuvuuksia. Jos olisimme rakentaneet “Hello, world!” -projektin Cargolla, se käyttäisi vain Cargon osaa, joka hoitaa koodisi kääntämisen. Kun kirjoitat monimutkaisempia Rust-ohjelmia, lisäät riippuvuuksia, ja jos aloitat projektin Cargolla, riippuvuuksien lisääminen on paljon helpompaa.

Koska valtava enemmistö Rust-projekteista käyttää Cargo-työkalua, tämän kirjan loppuosa olettaa, että käytät sitä myös. Cargo tulee Rustin mukana, jos käytit virallisia asennusohjelmia, joita käsiteltiin Asennus -osiossa. Jos asensit Rustin jollain muulla tavalla, tarkista, onko Cargo asennettu kirjoittamalla terminaaliisi:

$ cargo --version

Jos näet versionumeron, sinulla on se! Jos näet virheen, kuten command not found, katso asennustapasi dokumentaatiosta, miten Cargo asennetaan erikseen.

Projektin luominen Cargolla

Luodaan uusi projekti Cargolla ja katsotaan, miten se eroaa alkuperäisestä “Hello, world!” -projektistamme. Palaa projects-kansioosi (tai minne päätit tallentaa koodisi). Suorita sitten millä tahansa käyttöjärjestelmällä seuraavat:

$ cargo new hello_cargo
$ cd hello_cargo

Ensimmäinen komento luo uuden kansion ja projektin nimeltä hello_cargo. Olemme nimenneet projektimme hello_cargo, ja Cargo luo tiedostonsa samannimiseen kansioon.

Siirry hello_cargo-kansioon ja listaa tiedostot. Näet, että Cargo on luonut meille kaksi tiedostoa ja yhden kansion: Cargo.toml-tiedoston ja src-kansion, jonka sisällä on main.rs-tiedosto.

Se on myös alustanut uuden Git-repositorion .gitignore-tiedoston kera. Git-tiedostoja ei luoda, jos suoritat cargo new olemassa olevassa Git-repositoriossa; voit ohittaa tämän käyttämällä cargo new --vcs=git.

Huom: Git on yleinen versionhallintajärjestelmä. Voit muuttaa cargo new -komennon käyttämään eri versionhallintajärjestelmää tai ei lainkaan versionhallintaa --vcs-lipulla. Suorita cargo new --help nähdäksesi käytettävissä olevat vaihtoehdot.

Avaa Cargo.toml valitsemassasi tekstieditorissa. Sen pitäisi näyttää samankaltaiselta kuin Listauksen 1-2 koodi.

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

[dependencies]

Tämä tiedosto on TOML (Tom’s Obvious, Minimal Language) -muodossa, joka on Cargon konfiguraatiomuoto.

Ensimmäinen rivi [package] on osion otsikko, joka osoittaa, että seuraavat lausekkeet konfiguroivat pakettia. Kun lisäämme tähän tiedostoon lisätietoa, lisäämme muita osioita.

Seuraavat kolme riviä asettavat konfiguraatiotiedot, joita Cargo tarvitsee ohjelmasi kääntämiseen: nimen, version ja käytettävän Rust-editionin. Puhumme edition-avaimesta Liitteessä E.

Viimeinen rivi [dependencies] on osion alku, johon voit listata projektisi riippuvuudet. Rustissa koodipaketteja kutsutaan crateiksi. Emme tarvitse muita crateja tähän projektiin, mutta tarvitsemme Luvun 2 ensimmäisessä projektissa, joten käytämme tätä riippuvuuksien osiota silloin.

Avaa nyt src/main.rs ja katso:

Filename: src/main.rs

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

Cargo on luonut sinulle “Hello, world!” -ohjelman, aivan kuten Listauksessa 1-1 kirjoittamamme! Tähän asti erot projektimme ja Cargon luoman projektin välillä ovat, että Cargo sijoitti koodin src-kansioon ja meillä on Cargo.toml-konfiguraatiotiedosto ylätason kansiossa.

Cargo odottaa lähdekooditiedostojesi olevan src-kansiossa. Ylätason projektikansio on vain README-tiedostoille, lisenssitiedoille, konfiguraatiotiedostoille ja kaikelle muulle, mikä ei liity koodiisi. Cargon käyttö auttaa järjestämään projektisi. Kaikella on paikkansa, ja kaikki on paikallaan.

Jos aloitit projektin, joka ei käytä Cargo-työkalua, kuten teimme “Hello, world!” -projektissa, voit muuntaa sen Cargoa käyttäväksi projektiksi. Siirrä projektikoodi src-kansioon ja luo sopiva Cargo.toml-tiedosto. Helppo tapa saada Cargo.toml-tiedosto on suorittaa cargo init, joka luo sen automaattisesti.

Cargo-projektin kääntäminen ja suorittaminen

Katsotaan nyt, mikä on erilaista, kun käännetään ja suoritetaan “Hello, world!” -ohjelma Cargolla! hello_cargo-kansiostasi käänä projektisi kirjoittamalla seuraava komento:

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

Tämä komento luo ajettavan tiedoston target/debug/hello_cargo (tai target\debug\hello_cargo.exe Windowsilla) nykyisen kansiosi sijaan. Koska oletuskäännös on debug-käännös, Cargo sijoittaa binäärin kansioon nimeltä debug. Voit suorittaa ajettavan tiedoston tällä komennolla:

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

Jos kaikki menee hyvin, Hello, world! pitäisi tulostua terminaaliin. Ensimmäinen cargo build -komennon suoritus saa myös Cargon luomaan uuden tiedoston ylätasolle: Cargo.lock. Tämä tiedosto pitää kirjaa projektisi riippuvuuksien tarkoista versioista. Tällä projektilla ei ole riippuvuuksia, joten tiedosto on hieman niukka. Sinun ei koskaan tarvitse muuttaa tätä tiedostoa manuaalisesti; Cargo hallitsee sen sisältöä puolestasi.

Käänsimme juuri projektin cargo build -komennolla ja suoritimme sen ./target/debug/hello_cargo -komennolla, mutta voimme myös käyttää cargo run -komentoa kääntääksemme koodin ja suorittaaksemme syntyneen ajettavan tiedoston yhdellä komennolla:

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

cargo run -komennon käyttö on kätevämpää kuin muistaa suorittaa cargo build ja käyttää sitten koko polkua binääriin, joten useimmat kehittäjät käyttävät cargo run -komentoa.

Huomaa, että tällä kertaa emme nähneet tulostetta, joka osoittaa Cargon kääntävän hello_cargo-projektia. Cargo päätteli, että tiedostot eivät olleet muuttuneet, joten se ei kääntänyt uudelleen vaan suoritti vain binäärin. Jos olisit muokannut lähdekoodiasi, Cargo olisi kääntänyt projektin uudelleen ennen suorittamista, ja olisit nähnyt tämän tulosteen:

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

Cargo tarjoaa myös komennon nimeltä cargo check. Tämä komento tarkistaa nopeasti koodisi varmistaakseen, että se kääntyy, mutta ei tuota ajettavaa tiedostoa:

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

Miksi et haluaisi ajettavaa tiedostoa? Usein cargo check on paljon nopeampi kuin cargo build, koska se ohittaa ajettavan tiedoston tuottamisen. Jos tarkistat työtäsi jatkuvasti koodia kirjoittaessasi, cargo check -komennon käyttö nopeuttaa prosessia, jolla saat tietää, kääntyykö projektisi edelleen! Siksi monet Rustaceanit suorittavat cargo check -komennon säännöllisesti ohjelmaa kirjoittaessaan varmistaakseen, että se kääntyy. Sitten he suorittavat cargo build -komennon, kun ovat valmiita käyttämään ajettavaa tiedostoa.

Kerrataan, mitä olemme tähän mennessä oppineet Cargosta:

• Voimme luoda projektin cargo new -komennolla.
• Voimme kääntää projektin cargo build -komennolla.
• Voimme kääntää ja suorittaa projektin yhdellä askeleella cargo run -komennolla.
• Voimme kääntää projektin tuottamatta binääriä virheiden tarkistamiseksi cargo check -komennolla.
• Sen sijaan, että tallentaisimme käännöstuloksen samaan kansioon kuin koodimme, Cargo säilyttää sen target/debug-kansiossa.

Cargon käytön lisäetu on, että komennot ovat samat riippumatta siitä, millä käyttöjärjestelmällä työskentelet. Tästä eteenpäin emme enää anna erityisiä ohjeita Linuxille ja macOS:lle verrattuna Windowsiin.

Julkaisua varten kääntäminen

Kun projektisi on vihdoin valmis julkaistavaksi, voit käyttää cargo build --release -komentoa kääntääksesi sen optimoinneilla. Tämä komento luo ajettavan tiedoston target/release-kansioon target/debug-kansion sijaan. Optimoinnit tekevät Rust-koodistasi nopeammin suoritettavan, mutta niiden käyttöönotto pidentää ohjelmasi kääntämiseen kuluvaa aikaa. Siksi on kaksi eri profiilia: yksi kehitystä varten, kun haluat kääntää nopeasti ja usein, ja toinen lopullisen ohjelman rakentamiseen, jota et rakenna uudelleen toistuvasti ja joka suoritetaan mahdollisimman nopeasti. Jos vertailet koodisi suoritusaikaa, muista suorittaa cargo build --release ja vertailla target/release-kansion ajettavalla tiedostolla.

Cargon käytäntöjen hyödyntäminen

Yksinkertaisissa projekteissa Cargo ei tarjoa paljon lisäarvoa pelkän rustc-kääntäjän käyttöön verrattuna, mutta se osoittaa arvonsa ohjelmiesi monimutkaistuessa. Kun ohjelmat kasvavat useiksi tiedostoiksi tai tarvitsevat riippuvuuden, on paljon helpompaa antaa Cargon koordinoida käännös.

Vaikka hello_cargo-projekti on yksinkertainen, se käyttää nyt suurta osaa tosielämän työkaluista, joita käytät Rust-urasi loppuosassa. Itse asiassa voit työskennellä olemassa olevien projektien parissa käyttämällä seuraavia komentoja koodin hakemiseen Gitillä, siirtymiseen projektin kansioon ja kääntämiseen:

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

Lisätietoa Cargosta löydät sen dokumentaatiosta.

Yhteenveto

Olet jo päässyt hyvään alkuun Rust-matkallasi! Tässä luvussa opit:

• Rustin uusimman vakaan version asentamisen rustup-työkalulla.
• Päivittämisen uudempaan Rust-versioon.
• Paikallisesti asennetun dokumentaation avaamisen.
• “Hello, world!” -ohjelman kirjoittamisen ja suorittamisen suoraan rustc-kääntäjällä.
• Uuden projektin luomisen ja suorittamisen Cargon käytäntöjen mukaisesti.

Nyt on hyvä aika rakentaa laajempi ohjelma totuttuaksesi Rust-koodin lukemiseen ja kirjoittamiseen. Luvussa 2 rakennamme arvauspeli-ohjelman. Jos haluat mieluummin aloittaa oppimalla, miten yleiset ohjelmointikäsitteet toimivat Rustissa, katso Luku 3 ja palaa sitten Lukuun 2.

Arvauspelin ohjelmointi

Hypätään suoraan Rustin pariin työstämällä yhdessä käytännön projekti! Tämä luku esittelee sinulle muutamia yleisiä Rust-käsitteitä näyttämällä, miten voit käyttää niitä oikeassa ohjelmassa. Opit let-määrittelyistä, match-lausekkeista, metodeista, assosioiduista funktioista, ulkoisista crateista ja paljon muusta! Seuraavissa luvuissa perehdymme näihin ideoihin tarkemmin. Tässä luvussa harjoittelet vain perusasioita.

Toteutamme klassisen aloittelijatason ohjelmointitehtävän: arvauspelin. Näin se toimii: ohjelma generoi satunnaisen kokonaisluvun väliltä 1–100. Se pyytää sitten pelaajaa syöttämään arvauksen. Kun arvaus on annettu, ohjelma kertoo, onko arvaus liian pieni vai liian suuri. Jos arvaus on oikein, peli tulostaa onnitteluviestin ja sulkeutuu.

Uuden projektin luominen

Luo uusi projekti siirtymällä projects-hakemistoon, jonka loit luvussa 1, ja luo uusi projekti käyttäen Cargoa näin:

$ cargo new guessing_game
$ cd guessing_game

Ensimmäinen komento cargo new ottaa projektin nimen (guessing_game) ensimmäisenä argumenttina. Toinen komento siirtyy uuden projektin hakemistoon.

Tarkastele luotua Cargo.toml-tiedostoa:

Filename: Cargo.toml

{{#include ../listings/ch02-guessing-game-tutorial/no-listing-01-cargo-new/Cargo.toml}}

Kuten näit luvussa 1, cargo new generoi sinulle ”Hello, world!” -ohjelman. Tarkista src/main.rs-tiedosto:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-01-cargo-new/src/main.rs}}
}

Käännetään ja ajetaan nyt tämä ”Hello, world!” -ohjelma samassa vaiheessa käyttämällä cargo run -komentoa:

{{#include ../listings/ch02-guessing-game-tutorial/no-listing-01-cargo-new/output.txt}}

run-komento on kätevä, kun täytyy nopeasti iteroida projektia, kuten teemme tässä pelissä, testaten nopeasti jokaisen version ennen siirtymistä seuraavaan.

Avaa src/main.rs-tiedosto uudelleen. Kirjoitat kaiken koodin tähän tiedostoon.

Arvauksen käsittely

Arvauspeli-ohjelman ensimmäinen osa pyytää käyttäjän syötettä, käsittelee sen ja tarkistaa, että syöte on odotetussa muodossa. Aloitamme sallimalla pelaajan syöttää arvauksen. Syötä listauksen 2-1 koodi tiedostoon src/main.rs.

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:all}}

Tämä koodi sisältää paljon tietoa, joten käydään se läpi rivi riviltä. Saadaksemme käyttäjän syötteen ja tulostaaksemme tuloksen, meidän täytyy tuoda io-kirjasto näkyviin. io-kirjasto tulee standardikirjastosta, joka tunnetaan nimellä std:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:io}}

Oletuksena Rustilla on joukko kohteita, jotka on määritelty standardikirjastossa ja jotka se tuo näkyviin jokaisessa ohjelmassa. Tätä joukkoa kutsutaan preludiksi, ja voit nähdä kaiken siinä standardikirjaston dokumentaatiossa.

Jos haluamasi tyyppi ei ole preludissa, sinun täytyy tuoda kyseinen tyyppi näkyviin eksplisiittisesti use-lauseella. std::io-kirjaston käyttö tarjoaa useita hyödyllisiä ominaisuuksia, mukaan lukien mahdollisuuden hyväksyä käyttäjän syöte.

Kuten näit luvussa 1, main-funktio on ohjelman sisääntulopiste:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:main}}

fn-syntaksi julistaa uuden funktion; sulkeet () osoittavat, ettei ole parametreja; ja aaltosulje { aloittaa funktion rungon.

Kuten opit myös luvussa 1, println! on makro, joka tulostaa merkkijonon näytölle:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:print}}

Tämä koodi tulostaa kehotteen, joka kertoo mistä pelissä on kyse, ja pyytää syötettä käyttäjältä.

Arvojen tallentaminen muuttujilla

Seuraavaksi luomme muuttujan tallentaaksemme käyttäjän syötteen, näin:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:string}}

Nyt ohjelma alkaa olla mielenkiintoinen! Tässä lyhyessä rivissä tapahtuu paljon. Käytämme let-lauseketta luodaksemme muuttujan. Tässä toinen esimerkki:

let apples = 5;

Tämä rivi luo uuden muuttujan nimeltä apples ja sitoo sen arvoon 5. Rustissa muuttujat ovat oletuksena muuttumattomia, eli kun annamme muuttujalle arvon, arvo ei muutu. Käsittelemme tätä käsitettä tarkemmin ”Muuttujat ja muutettavuus” -osiossa luvussa 3. Tehdäksemme muuttujan muutettavaksi lisäämme mut-avainsanan ennen muuttujan nimeä:

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

Huom: //-syntaksi aloittaa kommentin, joka jatkuu rivin loppuun. Rust jättää huomiotta kaiken kommenteissa. Käsittelemme kommentteja tarkemmin luvussa 3.

Palatessa arvauspeli-ohjelmaan, tiedät nyt että let mut guess esittelee muutettavan muuttujan nimeltä guess. Yhtäsuuruusmerkki (=) kertoo Rustille, että haluamme sitoa jotain muuttujaan nyt. Yhtäsuuruusmerkin oikealla puolella on arvo, johon guess sidotaan, eli String::new-funktion kutsumisen tulos, funktio joka palauttaa uuden String-instanssin. String on standardikirjaston tarjoama merkkijonotyyppi, joka on kasvava, UTF-8 -koodattu tekstinpätkä.

::-syntaksi ::new-rivillä osoittaa, että new on assosioitu funktio String-tyypille. Assosioitu funktio on funktio, joka on toteutettu tyypille, tässä tapauksessa String:lle. Tämä new-funktio luo uuden, tyhjän merkkijonon. Löydät new-funktion monilta tyypeiltä, koska se on yleinen nimi funktiolle, joka luo jonkinlaisen uuden arvon.

Kokonaisuudessaan let mut guess = String::new(); -rivi on luonut muutettavan muuttujan, joka on tällä hetkellä sidottu uuteen, tyhjään String-instanssiin. Huh!

Käyttäjän syötteen vastaanottaminen

Muista, että sisällytimme syöte-/tulostustoiminnallisuuden standardikirjastosta use std::io; -lauseella ohjelman ensimmäisellä rivillä. Kutsumme nyt stdin-funktiota io-moduulista, mikä antaa meidän käsitellä käyttäjän syötettä:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:read}}

Jos emme olisi tuoneet io-kirjastoa näkyviin use std::io; -lauseella ohjelman alussa, voisimme silti käyttää funktiota kirjoittamalla funktiokutsun muodossa std::io::stdin. stdin-funktio palauttaa instanssin std::io::Stdin -tyypistä, joka edustaa käsittelijää päätteen standardisyötteelle.

Seuraavaksi rivi .read_line(&mut guess) kutsuu read_line -metodia standardisyötteen käsittelijällä saadakseen syötteen käyttäjältä. Välitämme myös &mut guess argumenttina read_line-metodille kertoaksemme sille, mihin merkkijonoon tallentaa käyttäjän syötteen. read_line-metodin tehtävä on ottaa mitä tahansa käyttäjä kirjoittaa standardisyötteeseen ja liittää se merkkijonoon (ylikirjoittamatta sen sisältöä), joten välitämme tuon merkkijonon argumenttina. Merkkijonoargumentin täytyy olla muutettava, jotta metodi voi muuttaa merkkijonon sisältöä.

& osoittaa, että tämä argumentti on viittaus, joka antaa tavan antaa useiden koodin osien käyttää samaa dataa ilman, että dataa täytyy kopioida muistiin useita kertoja. Viittaukset ovat monimutkainen ominaisuus, ja yksi Rustin suurista eduista on, kuinka turvallista ja helppoa viittausten käyttö on. Et tarvitse tietää paljoa näistä yksityiskohdista tämän ohjelman viimeistelyyn. Toistaiseksi sinun tarvitsee tietää vain, että kuten muuttujat, viittaukset ovat oletuksena muuttumattomia. Siksi sinun täytyy kirjoittaa &mut guess eikä &guess tehdäksesi sen muutettavaksi. (Luku 4 selittää viittaukset tarkemmin.)

Mahdollisen epäonnistumisen käsittely Result-tyypillä

Työstämme vielä tätä koodiriviä. Käsittelemme nyt kolmatta tekstiriviä, mutta huomaa, että se on edelleen osa yhtä loogista koodiriviä. Seuraava osa on tämä metodi:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:expect}}

Olisimme voineet kirjoittaa tämän koodin näin:

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

Yksi pitkä rivi on kuitenkin vaikea lukea, joten on parasta jakaa se. On usein viisasta lisätä rivinvaihto ja muuta välilyöntiä auttamaan jakamaan pitkiä rivejä, kun kutsut metodia .method_name() -syntaksilla. Käsitellään nyt, mitä tämä rivi tekee.

Kuten aiemmin mainittiin, read_line laittaa mitä tahansa käyttäjä syöttää merkkijonoon, jonka välitämme sille, mutta se palauttaa myös Result-arvon. Result on enum, usein kutsuttu enumiksi, joka on tyyppi, joka voi olla yhdessä useista mahdollisista tiloista. Kutakin mahdollista tilaa kutsutaan variantiksi.

Luku 6 käsittelee enumeja tarkemmin. Näiden Result-tyyppien tarkoitus on koodata virheenkäsittelytietoa.

Result-tyypin variantit ovat Ok ja Err. Ok-variantti osoittaa, että operaatio onnistui, ja se sisältää onnistuneesti generoidun arvon. Err-variantti tarkoittaa, että operaatio epäonnistui, ja se sisältää tietoa siitä, miten tai miksi operaatio epäonnistui.

Result-tyypin arvoilla, kuten minkä tahansa tyypin arvoilla, on niille määriteltyjä metodeja. Result-instanssilla on expect-metodi, jota voit kutsua. Jos tämä Result-instanssi on Err-arvo, expect saa ohjelman kaatumaan ja näyttämään viestin, jonka välitit argumenttina expect-metodille. Jos read_line-metodi palauttaa Err-arvon, se olisi todennäköisesti käyttöjärjestelmän virheen seurausta. Jos tämä Result-instanssi on Ok-arvo, expect ottaa palautusarvon, jonka Ok pitää sisällään, ja palauttaa sen sinulle, jotta voit käyttää sitä. Tässä tapauksessa tuo arvo on käyttäjän syötteen tavumäärä.

Jos et kutsu expect-metodia, ohjelma kääntyy, mutta saat varoituksen:

{{#include ../listings/ch02-guessing-game-tutorial/no-listing-02-without-expect/output.txt}}

Rust varoittaa, ettet ole käyttänyt read_line-metodin palauttamaa Result-arvoa, osoittaen, ettei ohjelma ole käsitellyt mahdollista virhettä.

Oikea tapa hiljentää varoitus on todella kirjoittaa virheenkäsittelykoodi, mutta tapauksessamme haluamme vain kaataa ohjelman, kun ongelma ilmenee, joten voimme käyttää expect-metodia. Opit virheistä toipumisesta luvussa 9.

Arvojen tulostaminen println!-paikkamerkeillä

Sulkevan aaltosulkeen lisäksi on vielä yksi rivi käsiteltävänä tähänastisessa koodissa:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:print_guess}}

Tämä rivi tulostaa merkkijonon, joka sisältää nyt käyttäjän syötteen. {}-merkkien joukko on paikkamerkki: ajattele {}:tä pieninä rapupihdeinä, jotka pitävät arvon paikallaan. Kun tulostat muuttujan arvon, muuttujan nimi voi mennä aaltosulkeiden sisään. Kun tulostat lausekkeen evaluoinnin tuloksen, laita tyhjät aaltosulkeet muotoilumerkkijonoon ja lisää sen jälkeen pilkulla erotettu lista lausekkeista, jotka tulostetaan kuhunkin tyhjään aaltosuljepaikkamerkkiin samassa järjestyksessä. Muuttujan ja lausekkeen tulostaminen yhdessä println!-kutsussa näyttäisi tältä:

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

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

Tämä koodi tulostaisi x = 5 and y + 2 = 12.

Ensimmäisen osan testaaminen

Testataan arvauspelin ensimmäistä osaa. Aja se käyttämällä cargo run-komentoa:

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

Tässä vaiheessa pelin ensimmäinen osa on valmis: saamme syötteen näppäimistöltä ja tulostamme sen.

Salaisen luvun generointi

Seuraavaksi meidän täytyy generoida salainen luku, jota käyttäjä yrittää arvata. Salaisen luvun pitäisi olla eri joka kerta, jotta peli on hauska pelata useammin kuin kerran. Käytämme satunnaista lukua väliltä 1–100, jotta peli ei ole liian vaikea. Rust ei vielä sisällytä satunnaislukutoiminnallisuutta standardikirjastoonsa. Rust-tiimi tarjoaa kuitenkin rand-craten, jossa kyseinen toiminnallisuus on.

Craten käyttö lisätoiminnallisuuden saamiseksi

Muista, että crate on kokoelma Rust-lähdekooditiedostoja. Projekti, jota olemme rakentaneet, on binaaricrate, joka on suoritettava ohjelma. rand- crate on kirjastocrate, joka sisältää koodia, joka on tarkoitettu käytettäväksi muissa ohjelmissa eikä sitä voi suorittaa itsenäisesti.

Cargon koordinointi ulkoisista crateista on se, missä Cargo todella loistaa. Ennen kuin voimme kirjoittaa koodia, joka käyttää rand-cratea, meidän täytyy muokata Cargo.toml-tiedostoa sisällyttääksemme rand-craten riippuvuudeksi. Avaa tiedosto nyt ja lisää seuraava rivi pohjaan, [dependencies]-osion otsikon alle, jonka Cargo loi sinulle. Varmista, että määrittelet rand:in täsmälleen kuten tässä, tällä versionumerolla, tai tämän opetusohjelman koodiesimerkit eivät välttämättä toimi:

Filename: Cargo.toml

{{#include ../listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml:8:}}

Cargo.toml-tiedostossa kaikki otsikon jälkeen tuleva kuuluu siihen osioon, joka jatkuu, kunnes toinen osio alkaa. [dependencies]-osiossa kerrot Cargolle, mistä ulkoisista crateista projektisi riippuu ja mitä versioita näistä crateista tarvitset. Tässä tapauksessa määrittelemme rand-craten semanttisella versionumerolla 0.10.1. Cargo ymmärtää semanttisen versionhallinnan (joskus kutsutaan SemVeriksi), joka on standardi versionumeroiden kirjoittamiseen. Määrite 0.10.1 on itse asiassa lyhennys muodolle ^0.10.1, mikä tarkoittaa mitä tahansa versiota, joka on vähintään 0.10.1 mutta alle 0.11.0.

Cargo pitää näitä versioita julkisesti yhteensopivina version 0.10.1 API:n kanssa, ja tämä määrite varmistaa, että saat uusimman korjausjulkaisun, joka vielä kääntyy tämän luvun koodin kanssa. Mikään versio 0.11.0 tai suurempi ei ole taattu sisältävän samaa API:a kuin seuraavat esimerkit käyttävät.

Nyt, muuttamatta mitään koodia, käännetään projekti, kuten listauksessa 2-2.

$ cargo build
    Updating crates.io index
     Locking 8 packages to latest Rust 1.96.0 compatible versions
  Downloaded rand_core v0.10.1
  Downloaded chacha20 v0.10.1
  Downloaded rand v0.10.1
  Downloaded 3 crates (162.9KiB) in 0.59s
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling getrandom v0.4.3
   Compiling cfg-if v1.0.4
   Compiling chacha20 v0.10.1
   Compiling rand v0.10.1
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.03s

Saatat nähdä eri versionumerot (mutta ne ovat kaikki yhteensopivia koodin kanssa SemVerin ansiosta!) ja eri rivejä (käyttöjärjestelmästä riippuen), ja rivit voivat olla eri järjestyksessä.

Kun sisällytämme ulkoisen riippuvuuden, Cargo hakee uusimmat versiot kaikesta, mitä kyseinen riippuvuus tarvitsee, rekisteristä, joka on kopio dataa Crates.io-sivustolta. Crates.io on paikka, jossa Rust-ekosysteemin ihmiset julkaisevat avoimen lähdekoodin Rust-projektejaan muiden käytettäväksi.

Rekisterin päivityksen jälkeen Cargo tarkistaa [dependencies]-osion ja lataa kaikki listatut cratet, joita ei ole vielä ladattu. Tässä tapauksessa, vaikka listasimme vain rand:in riippuvuudeksi, Cargo haki myös muita crateja, joista rand riippuu toimiakseen. Cratet ladattuaan Rust kääntää ne ja kääntää sitten projektin riippuvuuksien ollessa käytettävissä.

Jos ajat heti cargo build-komennon uudelleen tekemättä muutoksia, et saa mitään tulostetta Finished-rivin lisäksi. Cargo tietää, että se on jo lataanut ja kääntänyt riippuvuudet, etkä ole muuttanut mitään niistä Cargo.toml-tiedostossasi. Cargo tietää myös, ettet ole muuttanut mitään koodissasi, joten se ei käännä sitäkään uudelleen. Kun ei ole mitään tehtävää, se yksinkertaisesti lopettaa.

Jos avaat src/main.rs-tiedoston, teet pienen muutoksen, tallennat sen ja käännät uudelleen, näet vain kaksi riviä tulostetta:

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

Nämä rivit osoittavat, että Cargo päivittää käännöksen vain pienellä muutoksellasi src/main.rs-tiedostoon. Riippuvuutesi eivät ole muuttuneet, joten Cargo tietää voivansa käyttää uudelleen jo ladattua ja kääntämäänsä.

Toistettavien käännösten varmistaminen Cargo.lock-tiedostolla

Cargolla on mekanismi, joka varmistaa, että voit kääntää saman artefaktin joka kerta, kun sinä tai kuka tahansa kääntää koodisi: Cargo käyttää vain niitä riippuvuuksien versioita, joita määritit, kunnes ilmoitat toisin. Sanotaan esimerkiksi, että ensi viikolla rand-craten versio 0.10.2 julkaistaan, ja tuo versio sisältää tärkeän bugikorjauksen, mutta myös regressiota, joka rikkoo koodisi. Tätä varten Rust luo Cargo.lock-tiedoston ensimmäisellä cargo build -ajolla, joten meillä on nyt tämä guessing_game- hakemistossa.

Kun käännät projektin ensimmäistä kertaa, Cargo selvittää kaikki riippuvuuksien versiot, jotka sopivat kriteereihin, ja kirjoittaa ne sitten Cargo.lock-tiedostoon. Kun käännät projektisi tulevaisuudessa, Cargo näkee Cargo.lock-tiedoston olevan olemassa ja käyttää siellä määriteltyjä versioita sen sijaan, että tekisi kaiken työn versioiden selvittämiseksi uudelleen. Tämä antaa sinulle toistettavan käännöksen automaattisesti. Toisin sanoen projektisi pysyy versiossa 0.10.1, kunnes päivität eksplisiittisesti, Cargo.lock-tiedoston ansiosta. Koska Cargo.lock-tiedosto on tärkeä toistettaville käännöksille, se tarkistetaan usein versionhallintaan muun projektikoodin kanssa.

Craten päivittäminen uuden version saamiseksi

Kun haluat päivittää craten, Cargo tarjoaa update-komennon, joka ohittaa Cargo.lock-tiedoston ja selvittää kaikki uusimmat versiot, jotka sopivat määrittelyihisi Cargo.toml-tiedostossa. Cargo kirjoittaa sitten nämä versiot Cargo.lock-tiedostoon. Muuten Cargo etsii oletuksena vain versioita, jotka ovat suurempia kuin 0.10.1 ja pienempiä kuin 0.11.0. Jos rand-cratella on julkaistu kaksi uutta versiota 0.10.2 ja 0.999.0, näkisit seuraavan, jos ajaisit cargo update-komennon:

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

Cargo jättää huomiotta version 0.999.0 julkaisun. Tässä vaiheessa huomaisit myös muutoksen Cargo.lock-tiedostossasi, joka osoittaa, että käyttämäsi rand-craten versio on nyt 0.10.2. Käyttääksesi rand-version 0.999.0 tai mitä tahansa versiota 0.999.x- sarjassa, sinun täytyisi päivittää Cargo.toml-tiedosto näyttämään tältä sen sijaan (älä tee tätä muutosta, koska seuraavat esimerkit olettavat käyttäväsi rand-versiota 0.10):

[dependencies]
rand = "0.999.0"

Seuraavalla cargo build -ajolla Cargo päivittää saatavilla olevien cratejen rekisterin ja arvioi rand-vaatimuksesi uudelleen määrittämäsi uuden version mukaan.

Cargosta ja sen ekosysteemistä on paljon enemmän sanottavaa, joita käsittelemme luvussa 14, mutta toistaiseksi se on kaikki mitä sinun täytyy tietää. Cargo tekee kirjastojen uudelleenkäytöstä hyvin helppoa, joten rustilaiset voivat kirjoittaa pienempiä projekteja, jotka koostuvat useista paketeista.

Satunnaisluvun generointi

Aloitetaan rand-craten käyttö luvun generoimiseksi arvattavaksi. Seuraava vaihe on päivittää src/main.rs, kuten listauksessa 2-3.

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-03/src/main.rs:all}}

Ensin lisäämme rivin use rand::prelude::*;. prelude-moduuli sisältää rand-craten yleisimmin käytetyt osat, ja use tuo nämä kohteet ohjelmamme näkyvyysalueelle.

Seuraavaksi lisäämme kaksi riviä keskelle. Ensimmäisellä rivillä kutsumme rand::rng-funktiota, joka antaa meille tietyn satunnaislukugeneraattorin, jota käytämme: sellaisen, joka on paikallinen nykyiselle suoritussäikeelle ja jonka käyttöjärjestelmä siemenöi. Sitten kutsumme random_range- metodia satunnaislukugeneraattorilla. Tämän metodin määrittelee RngExt-trait, joka on osa rand::prelude-moduulia, jonka toimme näkyviin use rand::prelude::*; -lauseella. random_range-metodi ottaa alueen lausekkeena argumenttina ja generoi satunnaisluvun alueella. Käyttämämme alueen lauseke on muodossa start..=end ja on sisältävä molemmissa rajoissa, joten meidän täytyy määritellä 1..=100 pyytääksemme lukua väliltä 1–100.

Huom: Et vain tiedä, mitä traitteja käyttää ja mitä metodeja ja funktioita kutsua cratesta, joten jokaisella cratella on dokumentaatio ohjeineen käyttöön. Cargon toinen hieno ominaisuus on, että cargo doc --open -komennon ajaminen kääntää kaikkien riippuvuuksiesi tarjoaman dokumentaation paikallisesti ja avaa sen selaimessasi. Jos olet kiinnostunut muusta toiminnallisuudesta rand-cratessa, aja esimerkiksi cargo doc --open ja napsauta rand vasemman sivupalkin kohdasta.

Toinen uusi rivi tulostaa salaisen luvun. Tämä on hyödyllistä ohjelmaa kehittäessä testataksemme sitä, mutta poistamme sen lopullisesta versiosta. Se ei ole kovin hauska peli, jos ohjelma tulostaa vastauksen heti käynnistyessään!

Kokeile ajaa ohjelma muutaman kerran:

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

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

Sinun pitäisi saada eri satunnaislukuja, ja niiden kaikkien pitäisi olla lukuja väliltä 1–100. Jos saat varoituksia, ne ovat turvallisia ohittaa. Jos saat virheitä, tarkista, että sinulla on rand = "0.10.1" Cargo.toml-tiedostossasi, koska tulevat rand-versiot voivat sisältää erilaisen API:n, mutta mikä tahansa versio 0.10-sarjassa pitäisi toimia tämän luvun koodin kanssa.

Arvauksen vertaaminen salaiseen lukuun

Nyt kun meillä on käyttäjän syöte ja satunnainen luku, voimme vertailla niitä. Tämä vaihe näytetään listauksessa 2-4. Huomaa, että tämä koodi ei vielä käänny, kuten selitämme.

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-04/src/main.rs:here}}

Ensin lisäämme toisen use-lauseen tuoden tyypin nimeltä std::cmp::Ordering näkyviin standardikirjastosta. Ordering-tyyppi on toinen enum ja sillä on variantit Less, Greater ja Equal. Nämä ovat kolme mahdollista tulosta, kun vertaat kahta arvoa.

Sitten lisäämme viisi uutta riviä pohjaan, jotka käyttävät Ordering-tyyppiä. cmp-metodi vertaa kahta arvoa ja sitä voi kutsua millä tahansa, jota voi verrata. Se ottaa viittauksen siihen, mihin haluat verrata: tässä se vertaa guess:ia secret_number:iin. Sitten se palauttaa Ordering-enumin variantin, jonka toimme näkyviin use-lauseella. Käytämme match -lauseketta päättääksemme, mitä tehdä seuraavaksi sen perusteella, mikä Ordering-variantti palautettiin cmp-kutsusta arvoilla guess ja secret_number.

match-lauseke koostuu haaroista. Haara koostuu kuviosta, jota vasten matchataan, ja koodista, joka pitäisi suorittaa, jos match-lausekkeelle annettu arvo sopii haaran kuvioon. Rust ottaa match-lausekkeelle annetun arvon ja katsoo jokaisen haaran kuviota vuorollaan. Kuviot ja match-rakenne ovat voimakkaita Rust-ominaisuuksia: ne antavat sinun ilmaista monenlaisia tilanteita, joita koodisi saattaa kohdata, ja varmistavat, että käsittelet ne kaikki. Nämä ominaisuudet käsitellään tarkemmin luvuissa 6 ja 19.

Käydään läpi esimerkki käyttämällä tässä käyttämäämme match-lauseketta. Sanotaan, että käyttäjä on arvannut 50 ja tällä kertaa generoitu salainen luku on 38.

Kun koodi vertaa 50:tä 38:een, cmp-metodi palauttaa Ordering::Greater, koska 50 on suurempi kuin 38. match-lauseke saa Ordering::Greater-arvon ja alkaa tarkistaa kunkin haaran kuviota. Se katsoo ensimmäisen haaran kuviota Ordering::Less ja näkee, ettei arvo Ordering::Greater matchaa Ordering::Less:ia, joten se jättää huomiotta koodin kyseisessä haarassa ja siirtyy seuraavaan haaraan. Seuraavan haaran kuvio on Ordering::Greater, joka matchaa Ordering::Greater:in! Kyseiseen haaraan liittyvä koodi suoritetaan ja tulostaa Too big! näytölle. match- lauseke päättyy ensimmäisen onnistuneen matchin jälkeen, joten se ei katso viimeistä haaraa tässä skenaariossa.

Listauksen 2-4 koodi ei kuitenkaan vielä käänny. Kokeillaan sitä:

{{#include ../listings/ch02-guessing-game-tutorial/listing-02-04/output.txt}}

Virheen ydin sanoo, että tyypit eivät täsmää. Rustilla on vahva, staattinen tyyppijärjestelmä. Sillä on kuitenkin myös tyyppipäättely. Kun kirjoitimme let mut guess = String::new(), Rust pystyi päättelemään, että guess:n pitäisi olla String eikä pakottanut meitä kirjoittamaan tyyppiä. secret_number sen sijaan on lukutyyppi. Muutama Rustin lukutyyppi voi olla arvolla välillä 1 ja 100: i32, 32-bittinen luku; u32, etumerkittömä 32-bittinen luku; i64, 64- bittinen luku; ja muita. Ellei toisin määritellä, Rust oletuksena käyttää i32:ta, joka on secret_number:n tyyppi, ellei lisää tyyppitietoa muualla, mikä saisi Rustin päättelemään eri numeerisen tyypin. Virheen syy on, että Rust ei voi verrata merkkijonoa ja lukutyyppiä.

Lopulta haluamme muuntaa String-merkkijonon, jonka ohjelma lukee syötteenä, lukutyyppiin, jotta voimme verrata sitä numeerisesti salaiseen lukuun. Teemme sen lisäämällä tämän rivin main-funktion runkoon:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/src/main.rs:here}}

Rivi on:

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

Luomme muuttujan nimeltä guess. Mutta odota, eikö ohjelmalla jo ole muuttujaa nimeltä guess? On, mutta Rust sallii meille hyödyllisesti varjostaa guess:n aiemman arvon uudella. Varjostus antaa meidän käyttää uudelleen guess- muuttujan nimeä sen sijaan, että pakottaisimme meidät luomaan kaksi erillistä muuttujaa, kuten guess_str ja guess. Käsittelemme tätä tarkemmin luvussa 3, mutta toistaiseksi tiedä, että tätä ominaisuutta käytetään usein, kun haluat muuntaa arvon tyypistä toiseen.

Sidoimme tämän uuden muuttujan lausekkeeseen guess.trim().parse(). guess lausekkeessa viittaa alkuperäiseen guess-muuttujaan, joka sisälsi syötteen merkkijonona. trim-metodi String-instanssilla poistaa kaiken väliylityksen alusta ja lopusta, mikä meidän täytyy tehdä ennen kuin voimme muuntaa merkkijonon u32:ksi, joka voi sisältää vain numeerista dataa. Käyttäjän täytyy painaa enter tyydyttääkseen read_line-metodin ja syöttääkseen arvauksensa, mikä lisää rivinvaihtomerkin merkkijonoon. Jos käyttäjä kirjoittaa 5 ja painaa enter, guess näyttää tältä: 5\n. \n edustaa ”rivinvaihtoa.” (Windowsissa enter-näppäimen painaminen tuottaa rivinvaihdon ja rivinvaihdon, \r\n.) trim-metodi poistaa \n:n tai \r\n:n, jolloin jäljelle jää vain 5.

Merkkijonojen parse-metodi muuntaa merkkijonon toiseen tyyppiin. Tässä käytämme sitä muuntamaan merkkijonosta luvuksi. Meidän täytyy kertoa Rustille tarkka lukutyyppi, jota haluamme käyttämällä let guess: u32. Kaksoispiste (:) guess:n jälkeen kertoo Rustille, että annotoimme muuttujan tyypin. Rustilla on muutama sisäänrakennettu lukutyyppi; tässä nähty u32 on etumerkittömä 32-bittinen kokonaisluku. Se on hyvä oletusvalinta pienelle positiiviselle luvulle. Opit muista lukutyypeistä luvussa 3.

Lisäksi tämän esimerkkiohjelman u32-annotaatio ja vertailu secret_number:iin tarkoittavat, että Rust päättelee secret_number:n olevan myös u32. Joten nyt vertailu on kahden saman tyypin arvon välillä!

parse-metodi toimii vain merkeillä, jotka voidaan loogisesti muuntaa luvuiksi, ja voi siksi helposti aiheuttaa virheitä. Jos esimerkiksi merkkijono sisältäisi A👍%, sitä ei voisi muuntaa luvuksi. Koska se saattaa epäonnistua, parse-metodi palauttaa Result-tyypin, aivan kuten read_line- metodi (käsiteltiin aiemmin ”Mahdollisen epäonnistumisen käsittely Result-tyypillä” -osiossa). Käsittelemme tämän Result-arvon samalla tavalla käyttämällä jälleen expect-metodia. Jos parse palauttaa Err-Result-variantin, koska se ei voinut luoda lukua merkkijonosta, expect-kutsu kaataa pelin ja tulostaa antamamme viestin. Jos parse voi onnistuneesti muuntaa merkkijonon luvuksi, se palauttaa Ok-variantin Result-tyypistä, ja expect palauttaa haluamamme luvun Ok-arvosta.

Ajetaan ohjelma nyt:

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

Hienoa! Vaikka arvauksen eteen lisättiin välilyöntejä, ohjelma silti selvitti, että käyttäjä arvasi 76. Aja ohjelma muutaman kerran varmistaaksesi erilaisen käyttäytymisen eri syötteillä: arvaa luku oikein, arvaa liian suuri luku ja arvaa liian pieni luku.

Meillä on nyt suurin osa pelistä toiminnassa, mutta käyttäjä voi tehdä vain yhden arvauksen. Muutetaan sitä lisäämällä silmukka!

Useiden arvausten salliminen silmukalla

loop-avainsana luo äärettömän silmukan. Lisäämme silmukan antaaksemme käyttäjille enemmän mahdollisuuksia arvata luku:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-04-looping/src/main.rs:here}}

Kuten näet, olemme siirtäneet kaiken arvauskehotteesta eteenpäin silmukkaan. Muista sisentää silmukan sisällä olevat rivit neljä välilyöntiä lisää ja aja ohjelma uudelleen. Ohjelma pyytää nyt uutta arvausta ikuisesti, mikä itse asiassa tuo uuden ongelman. Käyttäjä ei näytä pystyvän lopettamaan!

Käyttäjä voisi aina keskeyttää ohjelman näppäinyhdistelmällä ctrl-c. Mutta on toinen tapa paeta tämä tyydyttämätön hirviö, kuten mainittiin parse-keskustelussa ”Arvauksen vertaaminen salaiseen lukuun” -osiossa: jos käyttäjä syöttää ei-numeerisen vastauksen, ohjelma kaatuu. Voimme hyödyntää sitä salliaksemme käyttäjän lopettaa, kuten tässä:

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

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

quit-kirjoittaminen lopettaa pelin, mutta kuten huomaat, myös mikä tahansa muu ei-numeerinen syöte lopettaa sen. Tämä on lievästi sanottuna epäoptimaalista; haluamme pelin pysähtyvän myös, kun oikea luku arvataan.

Lopettaminen oikean arvauksen jälkeen

Ohjelmoidaan peli lopettamaan, kun käyttäjä voittaa, lisäämällä break-lause:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-05-quitting/src/main.rs:here}}

break-rivin lisääminen You win!-tekstin jälkeen saa ohjelman poistumaan silmukasta, kun käyttäjä arvaa salaisen luvun oikein. Silmukasta poistuminen tarkoittaa myös ohjelman päättymistä, koska silmukka on main-funktion viimeinen osa.

Virheellisen syötteen käsittely

Hienosäätääksemme pelin käyttäytymistä sen sijaan, että kaataisimme ohjelman, kun käyttäjä syöttää ei-numeerisen arvon, tehdään pelistä sellainen, että se jättää huomiotta ei-numeerisen syötteen, jotta käyttäjä voi jatkaa arvaamista. Voimme tehdä sen muuttamalla riviä, jossa guess muunnetaan String:stä u32:ksi, kuten listauksessa 2-5.

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-05/src/main.rs:here}}

Vaihdamme expect-kutsusta match-lausekkeeseen siirtyäksemme kaatumisesta virheenkäsittelyyn. Muista, että parse palauttaa Result-tyypin ja Result on enum, jolla on variantit Ok ja Err. Käytämme tässä match-lauseketta, kuten teimme cmp-metodin Ordering-tuloksen kanssa.

Jos parse pystyy onnistuneesti muuttamaan merkkijonon luvuksi, se palauttaa Ok-arvon, joka sisältää tuloksena olevan luvun. Tuo Ok-arvo matchaa ensimmäisen haaran kuvion, ja match-lauseke palauttaa vain num-arvon, jonka parse tuotti ja laittoi Ok-arvon sisään. Tuo luku päätyy juuri sinne, minne haluamme uudessa guess-muuttujassa, jonka luomme.

Jos parse ei pysty muuttamaan merkkijonoa luvuksi, se palauttaa Err-arvon, joka sisältää lisätietoa virheestä. Err-arvo ei matchaa ensimmäisen match-haaran kuviota Ok(num), mutta se matchaa toisen haaran kuvion Err(_). Alaviiva _ on catch-all-arvo; tässä esimerkissä sanomme haluavamme matchata kaikki Err- arvot riippumatta siitä, mitä tietoa niissä on. Joten ohjelma suorittaa toisen haaran koodin continue, joka kertoo ohjelman siirtyä seuraavaan silmukan iteratioon ja pyytää uutta arvausta. Eli käytännössä ohjelma jättää huomiotta kaikki virheet, joita parse saattaa kohdata!

Nyt kaiken pitäisi toimia odotetusti. Kokeillaan:

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

Mahtavaa! Pienellä viimeisellä hienosäädöllä viimeistelemme arvauspelin. Muista, että ohjelma tulostaa edelleen salaisen luvun. Se toimi hyvin testauksessa, mutta se pilaa pelin. Poistetaan println!, joka tulostaa salainen luvun. Listausta 2-6 näyttää lopullisen koodin.

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-06/src/main.rs}}

Tässä vaiheessa olet onnistuneesti rakentanut arvauspelin. Onnittelut!

Yhteenveto

Tämä projekti oli käytännönläheinen tapa esitellä sinulle monia uusia Rust-käsitteitä: let, match, funktiot, ulkoisten cratejen käyttö ja paljon muuta. Seuraavissa luvuissa opit näistä käsitteistä tarkemmin. Luku 3 käsittelee käsitteitä, joita useimmissa ohjelmointikielissä on, kuten muuttujat, data- tyypit ja funktiot, ja näyttää, miten niitä käytetään Rustissa. Luku 4 tutkii omistajuutta, ominaisuutta, joka tekee Rustista erilaisen kuin muut kielet. Luku 5 käsittelee rakenteita ja metodisyntaksia, ja luku 6 selittää, miten enumit toimivat.

Yleiset ohjelmointikäsitteet

Tämä luku käsittelee käsitteitä, jotka esiintyvät lähes jokaisessa ohjelmointikielessä, ja sitä, miten ne toimivat Rustissa. Monilla ohjelmointikielillä on paljon yhteistä ytimessään. Mikään tässä luvussa esitelty käsite ei ole ainutlaatuinen Rustille, mutta käsittelemme ne Rustin kontekstissa ja selitämme niiden käyttöön liittyvät käytännöt.

Erityisesti opit muuttujista, perustyypeistä, funktioista, kommenteista ja ohjausrakenteista. Nämä perusteet ovat jokaisessa Rust-ohjelmassa, ja niiden oppiminen varhain antaa sinulle vahvan ytimen, josta lähteä.

Muuttujat ja muuttumattomuus

Muuttujat ja muuttuvuus

Kuten mainittiin “Arvojen tallentaminen muuttujilla” -osiossa, muuttujat ovat oletuksena muuttumattomia. Tämä on yksi monista Rustin antamista vihjeistä kirjoittaa koodia tavalla, joka hyödyntää Rustin tarjoamaa turvallisuutta ja helppoa rinnakkaisuutta. Sinulla on kuitenkin edelleen mahdollisuus tehdä muuttujistasi muuttuvia. Tutkitaan, miten ja miksi Rust kannustaa suosimaan muuttumattomuutta ja miksi joskus saatat haluta poiketa siitä.

Kun muuttuja on muuttumaton, kun arvo on sidottu nimeen, et voi muuttaa sitä arvoa. Havainnollistamiseksi luo uusi projekti nimeltä variables projects-kansioosi komennolla cargo new variables.

Avaa sitten uudessa variables-kansiossasi src/main.rs ja korvaa sen koodi seuraavalla koodilla, joka ei vielä käänny:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-01-variables-are-immutable/src/main.rs}}

Tallenna ja suorita ohjelma cargo run -komennolla. Sinun pitäisi saada virheilmoitus muuttumattomuusvirheestä, kuten tässä tulosteessa:

{{#include ../listings/ch03-common-programming-concepts/no-listing-01-variables-are-immutable/output.txt}}

Tämä esimerkki näyttää, miten kääntäjä auttaa löytämään virheitä ohjelmissasi. Kääntäjävirheet voivat olla turhauttavia, mutta todellisuudessa ne vain tarkoittavat, että ohjelmasi ei vielä turvallisesti tee sitä, mitä haluat sen tekevän; ne eivät tarkoita, ettet olisi hyvä ohjelmoija! Kokeneetkin Rustaceanit saavat kääntäjävirheitä.

Sait virheilmoituksen cannot assign twice to immutable variable `x` koska yritit antaa toisen arvon muuttumattomalle x-muuttujalle.

On tärkeää, että saamme käännösaikaisia virheitä, kun yritämme muuttaa arvoa, joka on merkitty muuttumattomaksi, koska juuri tämä tilanne voi johtaa bugeihin. Jos yksi osa koodistamme toimii olettaen, että arvo ei koskaan muutu, ja toinen osa koodistamme muuttaa sitä arvoa, on mahdollista, että koodin ensimmäinen osa ei tee sitä, mitä se oli suunniteltu tekemään. Tällaisen bugin syy voi olla vaikea jäljittää jälkikäteen, erityisesti kun koodin toinen osa muuttaa arvoa vain joskus. Rust-kääntäjä takaa, että kun ilmoitat arvon olevan muuttumaton, se todella ei muutu, joten sinun ei tarvitse seurata sitä itse. Koodisi on siten helpompi ymmärtää.

Mutta muuttuvuus voi olla hyvin hyödyllistä ja tehdä koodin kirjoittamisesta kätevämpää. Vaikka muuttujat ovat oletuksena muuttumattomia, voit tehdä niistä muuttuvia lisäämällä mut-avainsanan muuttujan nimen eteen, kuten teit Luvussa 2. mut-avainsanan lisääminen myös välittää aikomuksen koodin tuleville lukijoille osoittaen, että koodin muut osat muuttavat tämän muuttujan arvoa.

Muutetaan esimerkiksi src/main.rs seuraavaksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-02-adding-mut/src/main.rs}}
}

Kun suoritamme ohjelman nyt, saamme tämän:

{{#include ../listings/ch03-common-programming-concepts/no-listing-02-adding-mut/output.txt}}

Saamme muuttaa x:ään sidottua arvoa 5:stä 6:een, kun mut on käytössä. Lopulta päätös muuttuvuuden käytöstä on sinun ja riippuu siitä, mikä on selkeintä kyseisessä tilanteessa.

Vakioiden julistaminen

Kuten muuttumattomat muuttujat, vakiot ovat arvoja, jotka on sidottu nimeen eikä niitä saa muuttaa, mutta vakioiden ja muuttujien välillä on muutamia eroja.

Ensinnäkin et saa käyttää mut-avainsanaa vakioiden kanssa. Vakiot eivät ole vain oletuksena muuttumattomia—ne ovat aina muuttumattomia. Julistat vakiot const-avainsanalla let-avainsanan sijaan, ja arvon tyyppi täytyy annotoida. Käsittelemme tyyppejä ja tyyppiannotaatioita seuraavassa osiossa “Tietotyypit”, joten älä huoli yksityiskohdista vielä. Tiedä vain, että sinun täytyy aina annotoida tyyppi.

Vakioita voidaan julistaa missä tahansa näkyvyysalueessa, mukaan lukien globaalissa näkyvyysalueessa, mikä tekee niistä hyödyllisiä arvoille, jotka monien koodin osien tarvitsevat tietää.

Viimeinen ero on, että vakioille voidaan asettaa vain vakiolauseke, ei arvon tulos, joka voitaisiin laskea vain ajonaikana.

Tässä on esimerkki vakion julistuksesta:

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

Vakion nimi on THREE_HOURS_IN_SECONDS, ja sen arvo on 60 (sekuntien määrä minuutissa) kerrottuna 60:llä (minuuttien määrä tunnissa) kerrottuna 3:lla (tuntien määrä, jonka haluamme laskea tässä ohjelmassa). Rustin nimeämiskäytäntö vakioille on käyttää kaikkia kirjaimia isoina ja alaviivoja sanojen välissä. Kääntäjä pystyy arvioimaan rajoitetun joukon operaatioita käännösaikana, mikä antaa meille mahdollisuuden kirjoittaa tämän arvon tavalla, joka on helpompi ymmärtää ja tarkistaa, sen sijaan että asettaisimme vakion arvoksi 10 800. Katso Rust Referencen osio vakioiden arvioinnista lisätietoja siitä, mitä operaatioita voidaan käyttää vakioita julistaessa.

Vakiot ovat voimassa koko ohjelman ajon ajan niiden julistusalueella. Tämä ominaisuus tekee vakioista hyödyllisiä sovellusalueesi arvoille, jotka useat ohjelman osat saattavat tarvita tietää, kuten maksimipisteet, jotka mikä tahansa pelaaja voi ansaita, tai valon nopeus.

Kovakoodattujen arvojen nimeäminen vakioiksi koko ohjelmassasi on hyödyllistä välittääkseen arvon merkityksen koodin tuleville ylläpitäjille. Se auttaa myös sillä, että sinun tarvitsee muuttaa vain yhtä paikkaa koodissasi, jos kovakoodattua arvoa pitää päivittää tulevaisuudessa.

Varjostaminen

Kuten näit arvauspeli-oppaassa Luvussa 2, voit julistaa uuden muuttujan samalla nimellä kuin aiempi muuttuja. Rustaceanit sanovat, että ensimmäinen muuttuja varjostetaan toisella, mikä tarkoittaa, että toinen muuttuja on se, jonka kääntäjä näkee, kun käytät muuttujan nimeä. Käytännössä toinen muuttuja peittää ensimmäisen, ohjaten kaikki muuttujan nimen käytöt itseensä, kunnes se itse varjostetaan tai näkyvyysalue päättyy. Voimme varjostaa muuttujan käyttämällä samaa muuttujan nimeä ja toistamalla let-avainsanan käytön seuraavasti:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-03-shadowing/src/main.rs}}
}

Tämä ohjelma sitoo ensin x:n arvoon 5. Sitten se luo uuden muuttujan x toistamalla let x =, ottaen alkuperäisen arvon ja lisäten 1, jolloin x:n arvo on 6. Sitten sisäisessä näkyvyysalueessa, joka luotiin aaltosulkeilla, kolmas let-lauseke varjostaa myös x:n ja luo uuden muuttujan, kertomalla edellisen arvon kahdella antaakseen x:lle arvon 12. Kun tämä näkyvyysalue päättyy, sisäinen varjostaminen loppuu ja x palaa arvoon 6. Kun suoritamme tämän ohjelman, se tulostaa seuraavan:

{{#include ../listings/ch03-common-programming-concepts/no-listing-03-shadowing/output.txt}}

Varjostaminen eroaa muuttujan merkitsemisestä mut-avainsanalla, koska saamme käännösaikaisen virheen, jos yritämme vahingossa antaa uuden arvon tälle muuttujalle käyttämättä let-avainsanaa. Käyttämällä let-avainsanaa voimme suorittaa muutamia muunnoksia arvolle, mutta muuttuja on muuttumaton näiden muunnosten jälkeen.

Toinen ero mut-avainsanan ja varjostamisen välillä on, että koska luomme käytännössä uuden muuttujan, kun käytämme let-avainsanaa uudelleen, voimme muuttaa arvon tyyppiä mutta käyttää samaa nimeä. Esimerkiksi ohjelmamme saattaa pyytää käyttäjää näyttämään, kuinka monta välilyöntiä hän haluaa tekstin väliin syöttämällä välilyöntimerkkejä, ja sitten haluamme tallentaa tämän syötteen numerona:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-04-shadowing-can-change-types/src/main.rs:here}}
}

Ensimmäinen spaces-muuttuja on merkkijonotyyppiä, ja toinen spaces-muuttuja on numerotyyppiä. Varjostaminen säästää meidät keksimästä eri nimiä, kuten spaces_str ja spaces_num; sen sijaan voimme käyttää uudelleen yksinkertaisempaa spaces-nimeä. Jos kuitenkin yritämme käyttää mut-avainsanaa tähän, kuten tässä näytetään, saamme käännösaikaisen virheen:

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-05-mut-cant-change-types/src/main.rs:here}}

Virhe sanoo, ettemme saa muuttaa muuttujan tyyppiä:

{{#include ../listings/ch03-common-programming-concepts/no-listing-05-mut-cant-change-types/output.txt}}

Nyt kun olemme tutkineet, miten muuttujat toimivat, katsotaan lisää tietotyyppejä, joita niillä voi olla.

Tietotyypit

Tietotyypit

Jokainen arvo Rustissa on tiettyä tietotyyppiä, joka kertoo Rustille, millaista dataa määritellään, jotta se tietää, miten datan kanssa työskennellään. Tarkastelemme kahta tietotyyppien osajoukkoa: skalaareja ja yhdistelmiä.

Muista, että Rust on staattisesti tyypitetty kieli, mikä tarkoittaa, että sen täytyy tietää kaikkien muuttujien tyypit käännösaikana. Kääntäjä pystyy yleensä päättelemään, mitä tyyppiä haluamme käyttää arvon ja sen käytön perusteella. Tilanteissa, joissa useita tyyppejä on mahdollisia, kuten kun muunnimme String-tyypin numerotyypiksi parse-funktiolla “Arvauksen vertaaminen salaisnumeroon” -osiossa Luvussa 2, meidän täytyy lisätä tyyppiannotaatio, kuten tässä:

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

Jos emme lisää edellä olevan koodin : u32 -tyyppiannotaatiota, Rust näyttää seuraavan virheen, mikä tarkoittaa, että kääntäjä tarvitsee meiltä lisätietoa tietääkseen, mitä tyyppiä haluamme käyttää:

{{#include ../listings/ch03-common-programming-concepts/output-only-01-no-type-annotations/output.txt}}

Näet erilaisia tyyppiannotaatioita muille tietotyypeille.

Skalaarityypit

Skalaari-tyyppi edustaa yksittäistä arvoa. Rustissa on neljä pääasiallista skalaarityyppiä: kokonaisluvut, liukuluvut, totuusarvot ja merkit. Saatat tunnistaa nämä muista ohjelmointikielistä. Katsotaan, miten ne toimivat Rustissa.

Kokonaislukutyypit

Kokonaisluku on luku ilman murto-osaa. Käytimme yhtä kokonaislukutyyppiä Luvussa 2, u32-tyyppiä. Tämä tyyppijulistus osoittaa, että siihen liitetyn arvon pitäisi olla etumerkitön kokonaisluku (etumerkityt kokonaislukutyypit alkavat i:llä u:n sijaan), joka vie 32 bittiä tilaa. Taulukko 3-1 näyttää Rustin sisäänrakennetut kokonaislukutyypit. Voimme käyttää mitä tahansa näistä muunnoksista kokonaislukuarvon tyypin julistamiseen.

Taulukko 3-1: Kokonaislukutyypit Rustissa

Jokainen muunnos voi olla joko etumerkitty tai etumerkitön ja sillä on eksplisiittinen koko. Etumerkitty ja etumerkitön viittaavat siihen, voiko luku olla negatiivinen—toisin sanoen, tarvitseeko luvulla olla etumerkki (etumerkitty) vai onko se aina positiivinen ja voidaan siten esittää ilman etumerkkiä (etumerkitön). Se on kuin lukujen kirjoittaminen paperille: Kun etumerkillä on merkitystä, luku näytetään plus- tai miinusmerkillä; kun on turvallista olettaa luvun olevan positiivinen, sitä ei näytetä etumerkillä. Etumerkityt luvut tallennetaan kahden komplementin esityksellä.

Jokainen etumerkitty muunnos voi tallentaa lukuja väliltä −(2^{n − 1}) – 2^{n − 1} − 1, missä n on kyseisen muunnoksen käyttämien bittien määrä. Eli i8 voi tallentaa lukuja −(2⁷) – 2⁷ − 1, mikä vastaa −128 – 127. Etumerkittömät muunnokset voivat tallentaa lukuja 0 – 2ⁿ − 1, joten u8 voi tallentaa lukuja 0 – 2⁸ − 1, mikä vastaa 0 – 255.

Lisäksi isize- ja usize-tyypit riippuvat tietokoneen arkkitehtuurista, jolla ohjelmasi suoritetaan: 64 bittiä 64-bittisellä arkkitehtuurilla ja 32 bittiä 32-bittisellä arkkitehtuurilla.

Voit kirjoittaa kokonaislukuliteraaleja missä tahansa Taulukossa 3-2 näytetyssä muodossa. Huomaa, että lukuliteraaleilla, jotka voivat olla useita numeerisia tyyppejä, voi olla tyyppiliite, kuten 57u8, tyypin määrittämiseksi. Lukuliteraalit voivat myös käyttää _-merkkiä visuaalisen erottimen roolissa lukujen lukemisen helpottamiseksi, kuten 1_000, jolla on sama arvo kuin 1000:lla.

Taulukko 3-2: Kokonaislukuliteraalit Rustissa

Mistä siis tiedät, mitä kokonaislukutyyppiä käyttää? Jos et ole varma, Rustin oletusarvot ovat yleensä hyvä lähtökohta: Kokonaislukutyypit oletuksena i32. Pääasiallinen tilanne, jossa käyttäisit isize- tai usize-tyyppiä, on kun indeksoit jotakin kokoelmaa.

Liukulukutyypit

Rustissa on myös kaksi primitiivistä liukulukutyyppiä, jotka ovat lukuja desimaalipisteellä. Rustin liukulukutyypit ovat f32 ja f64, joiden koot ovat 32 ja 64 bittiä. Oletustyyppi on f64, koska nykyaikaisilla prosessoreilla se on suunnilleen yhtä nopea kuin f32, mutta tarjoaa enemmän tarkkuutta. Kaikki liukulukutyypit ovat etumerkittyjä.

Tässä on esimerkki liukuluvuista toiminnassa:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-06-floating-point/src/main.rs}}
}

Liukuluvut esitetään IEEE-754-standardin mukaisesti.

Numeeriset operaatiot

Rust tukee perusmatemaattisia operaatioita, joita odotat kaikille lukutyypeille: yhteenlasku, vähennyslasku, kertolasku, jakolasku ja jakojäännös. Kokonaislukujako katkaisee kohti nollaa lähimpään kokonaislukuun. Seuraava koodi näyttää, miten käyttäisit kutakin numeerista operaatiota let-lausekkeessa:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-07-numeric-operations/src/main.rs}}
}

Jokainen näiden lausekkeiden lauseke käyttää matemaattista operaattoria ja evaluoituu yhdeksi arvoksi, joka sidotaan sitten muuttujaan. Liite B sisältää listan kaikista Rustin tarjoamista operaattoreista.

Totuusarvotyyppi

Kuten useimmissa muissa ohjelmointikielissä, totuusarvotyypillä Rustissa on kaksi mahdollista arvoa: true ja false. Totuusarvot ovat yhden tavun kokoisia. Rustin totuusarvotyyppi määritellään bool-avainsanalla. Esimerkiksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-08-boolean/src/main.rs}}
}

Pääasiallinen tapa käyttää totuusarvoja on ehtolausekkeiden kautta, kuten if-lauseke. Käsittelemme, miten if-lausekkeet toimivat Rustissa “Ohjausrakenteet” -osiossa.

Merkkityyppi

Rustin char-tyyppi on kielen primitiivisin aakkosellinen tyyppi. Tässä on esimerkkejä char-arvojen julistamisesta:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-09-char/src/main.rs}}
}

Huomaa, että määrittelemme char-literaalit yksinkertaisilla lainausmerkeillä toisin kuin merkkijonoliteraalit, jotka käyttävät kaksinkertaisia lainausmerkkejä. Rustin char-tyyppi on 4 tavun kokoinen ja edustaa Unicode-skaalaariarvoa, mikä tarkoittaa, että se voi edustaa paljon enemmän kuin pelkkää ASCII:a. Aksenttimerkit; kiina-, japani- ja koreankieliset merkit; emojit ja nollaleveyden välilyönnit ovat kaikki kelvollisia char-arvoja Rustissa. Unicode-skaalaariarvot ovat välillä U+0000 – U+D7FF ja U+E000 – U+10FFFF. Unicode:ssa “merkki” ei kuitenkaan ole oikea käsite, joten intuitiosi siitä, mikä on “merkki”, ei välttämättä vastaa sitä, mikä on char Rustissa. Käsittelemme tämän aiheen tarkemmin “UTF-8-koodatun tekstin tallentaminen merkkijonoilla” -osiossa Luvussa 8.

Yhdistelmätyypit

Yhdistelmätyypit voivat ryhmitellä useita arvoja yhdeksi tyypiksi. Rustissa on kaksi primitiivistä yhdistelmätyyppiä: tuplat ja taulukot.

Tuplatyyppi

Tupla on yleinen tapa ryhmitellä useita erityyppisiä arvoja yhdeksi yhdistelmätyypiksi. Tuplalla on kiinteä pituus: kun se on julistettu, se ei voi kasvaa tai kutistua.

Luomme tuplan kirjoittamalla pilkuilla erotetun listan arvoista sulkeiden sisään. Jokaisella paikalla tuplassa on tyyppi, eivätkä tuplan eri arvojen tyypit tarvitse olla samoja. Olemme lisänneet valinnaiset tyyppiannotaatiot tähän esimerkkiin:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-10-tuples/src/main.rs}}
}

Muuttuja tup sitoo koko tuplan, koska tuplaa pidetään yhtenä yhdistelmäelementtinä. Saadaksemme yksittäiset arvot tuplasta voimme käyttää kuvioiden täsmäyttämistä tuplan purkamiseen, näin:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-11-destructuring-tuples/src/main.rs}}
}

Tämä ohjelma luo ensin tuplan ja sitoo sen muuttujaan tup. Sitten se käyttää kuviota let-avainsanan kanssa ottaakseen tup:n ja muuttaakseen sen kolmeksi erilliseksi muuttujaksi, x, y ja z. Tätä kutsutaan purkamiseksi, koska se jakaa yhden tuplan kolmeen osaan. Lopuksi ohjelma tulostaa y:n arvon, joka on 6.4.

Voimme myös käyttää tuplaelementtiä suoraan pisteellä (.) ja sen jälkeen sen arvon indeksillä, johon haluamme päästä. Esimerkiksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-12-tuple-indexing/src/main.rs}}
}

Tämä ohjelma luo tuplan x ja käyttää sitten kunkin tuplaelementin indeksiä. Kuten useimmissa ohjelmointikielissä, tuplan ensimmäinen indeksi on 0.

Tuplaa ilman arvoja kutsutaan erityisellä nimellä yksikkö. Tämä arvo ja sen vastaava tyyppi kirjoitetaan molemmat () ja edustavat tyhjää arvoa tai tyhjää paluutyyppiä. Lausekkeet palauttavat implisiittisesti yksikköarvon, jos ne eivät palauta mitään muuta arvoa.

Taulukkotyyppi

Toinen tapa kerätä useita arvoja on taulukko. Toisin kuin tuplassa, jokaisella taulukon elementillä täytyy olla sama tyyppi. Toisin kuin joissakin muissa kielissä, Rustin taulukoilla on kiinteä pituus.

Kirjoitamme taulukon arvot pilkuilla erotettuna listana hakasulkeiden sisään:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-13-arrays/src/main.rs}}
}

Taulukot ovat hyödyllisiä, kun haluat datasi allokoituvan pinolle, kuten muutkin tähän mennessä nähdyistä tyypeistä, eikä keolle (käsittelemme pinoa ja keon tarkemmin Luvussa 4), tai kun haluat varmistaa, että sinulla on aina kiinteä määrä elementtejä. Taulukko ei kuitenkaan ole yhtä joustava kuin vektorityyppi. Vektori on standardikirjaston tarjoama samankaltainen kokoelmatyyppi, jonka koko saa kasvaa tai kutistua, koska sen sisältö on keossa. Jos et ole varma, käytätkö taulukkoa vai vektoria, käytä todennäköisesti vektoria. Luku 8 käsittelee vektoreita tarkemmin.

Taulukot ovat kuitenkin hyödyllisempiä, kun tiedät, ettei elementtien määrän tarvitse muuttua. Esimerkiksi jos käyttäisit kuukausien nimiä ohjelmassa, käyttäisit todennäköisesti taulukkoa vektorin sijaan, koska tiedät sen sisältävän aina 12 elementtiä:

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

Kirjoitat taulukon tyypin hakasulkeilla, jokaisen elementin tyypillä, puolipisteellä ja sitten taulukon elementtien määrällä, näin:

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

Tässä i32 on kunkin elementin tyyppi. Puolipisteen jälkeen luku 5 osoittaa, että taulukko sisältää viisi elementtiä.

Voit myös alustaa taulukon sisältämään saman arvon jokaiselle elementille määrittämällä alkuarvon, sitten puolipisteen ja taulukon pituuden hakasulkeissa, kuten tässä:

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

a-niminen taulukko sisältää 5 elementtiä, jotka kaikki asetetaan aluksi arvoon 3. Tämä on sama kuin kirjoittaisi let a = [3, 3, 3, 3, 3];, mutta tiiviimmällä tavalla.

Taulukkoelementtien käyttö

Taulukko on yksi muistilohko tunnetulla, kiinteällä koolla, joka voidaan allokoida pinolle. Voit käyttää taulukon elementtejä indeksoinnilla, näin:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-14-array-indexing/src/main.rs}}
}

Tässä esimerkissä first-niminen muuttuja saa arvon 1, koska se on taulukon indeksin [0] arvo. second-niminen muuttuja saa arvon 2 taulukon indeksistä [1].

Virheellinen taulukkoelementin käyttö

Katsotaan, mitä tapahtuu, jos yrität käyttää taulukon elementtiä taulukon lopun jälkeen. Sanotaan, että suoritat tämän koodin, samankaltaisena kuin arvauspeli Luvussa 2, saadaksesi taulukon indeksin käyttäjältä:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-15-invalid-array-access/src/main.rs}}

Tämä koodi kääntyy onnistuneesti. Jos suoritat tämän koodin cargo run -komennolla ja kirjoitat 0, 1, 2, 3 tai 4, ohjelma tulostaa vastaavan arvon taulukon kyseisessä indeksissä. Jos sen sijaan kirjoitat numeron taulukon lopun jälkeen, kuten 10, näet tulosteen kuten tämä:

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

Ohjelma johti ajonaikaiseen virheeseen virheellisen arvon käytössä indeksointioperatiossa. Ohjelma päättyi virheilmoitukseen eikä suorittanut viimeistä println!-lausetta. Kun yrität käyttää elementtiä indeksoinnilla, Rust tarkistaa, että määrittämäsi indeksi on pienempi kuin taulukon pituus. Jos indeksi on suurempi tai yhtä suuri kuin pituus, Rust panikoi. Tämä tarkistus täytyy tehdä ajonaikana, erityisesti tässä tapauksessa, koska kääntäjä ei voi mahdollisesti tietää, minkä arvon käyttäjä kirjoittaa, kun hän suorittaa koodin myöhemmin.

Tämä on esimerkki Rustin muistiturvallisuusperiaatteista käytännössä. Monissa matalan tason kielissä tällaista tarkistusta ei tehdä, ja kun annat virheellisen indeksin, virheelliseen muistiin voidaan päästä. Rust suojaa sinua tämänkaltaiselta virheeltä poistumalla välittömästi sen sijaan, että sallisi muistin käytön ja jatkuisi. Luku 9 käsittelee lisää Rustin virheenkäsittelystä ja siitä, miten voit kirjoittaa luettavaa, turvallista koodia, joka ei panikoi eikä salli virheellistä muistin käyttöä.

Funktiot

Funktiot

Funktiot ovat yleisiä Rust-koodissa. Olet jo nähnyt yhden tärkeimmistä kielen funktioista: main-funktion, joka on monien ohjelmien käynnistyspiste. Olet myös nähnyt fn-avainsanan, jonka avulla voit julistaa uusia funktioita.

Rust-koodi käyttää käärmeenpolku-tyyliä (snake case) funktioiden ja muuttujien nimien perinteisenä tyylinä, jossa kaikki kirjaimet ovat pieniä ja alaviivat erottavat sanat. Tässä on ohjelma, joka sisältää esimerkin funktion määrittelystä:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-16-functions/src/main.rs}}
}

Määrittelemme funktion Rustissa kirjoittamalla fn ja sen jälkeen funktion nimen ja joukon sulkeita. Aaltosulkeet kertovat kääntäjälle, missä funktion runko alkaa ja päättyy.

Voimme kutsua mitä tahansa määrittelemäämme funktiota kirjoittamalla sen nimen ja joukon sulkeita. Koska another_function on määritelty ohjelmassa, sitä voidaan kutsua main-funktion sisältä. Huomaa, että määrittelimme another_function-funktion main-funktion jälkeen lähdekoodissa; olisimme voineet määritellä sen ennenkin. Rust ei välitä, missä määrittelet funktiosi, vain siitä, että ne on määritelty jossakin näkyvyysalueessa, jonka kutsuja näkee.

Aloitetaan uusi binääriprojekti nimeltä functions tutkiaksemme funktioita tarkemmin. Sijoita another_function-esimerkki src/main.rs-tiedostoon ja suorita se. Sinun pitäisi nähdä seuraava tuloste:

{{#include ../listings/ch03-common-programming-concepts/no-listing-16-functions/output.txt}}

Rivit suoritetaan siinä järjestyksessä, jossa ne esiintyvät main-funktiossa. Ensin “Hello, world!” -viesti tulostetaan, sitten another_function kutsutaan ja sen viesti tulostetaan.

Parametrit

Voimme määritellä funktioita, joilla on parametreja, jotka ovat erityisiä muuttujia, jotka ovat osa funktion allekirjoitusta. Kun funktiolla on parametreja, voit antaa sille konkreettisia arvoja näille parametreille. Teknisesti konkreettisia arvoja kutsutaan argumenteiksi, mutta arkikeskusteluissa ihmiset käyttävät usein sanoja parametri ja argumentti vaihdellen joko funktion määritelmän muuttujille tai konkreettisille arvoille, jotka välitetään funktiota kutsuttaessa.

Tässä versiossa another_function-funktiosta lisäämme parametrin:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-17-functions-with-parameters/src/main.rs}}
}

Kokeile suorittaa tämä ohjelma; sinun pitäisi saada seuraava tuloste:

{{#include ../listings/ch03-common-programming-concepts/no-listing-17-functions-with-parameters/output.txt}}

another_function-funktion julistuksessa on yksi parametri nimeltä x. x:n tyyppi on määritelty i32:ksi. Kun välitämme 5:n another_function-funktiolle, println!-makro asettaa 5:n muotoilumerkkijonon aaltosulkeisiin, jotka sisältävät x:n.

Funktion allekirjoituksissa sinun täytyy julistaa kunkin parametrin tyyppi. Tämä on tarkoituksellinen päätös Rustin suunnittelussa: Tyyppiannotaatioiden vaatiminen funktioiden määritelmissä tarkoittaa, että kääntäjä tuskin koskaan tarvitsee sinua käyttämään niitä muualla koodissa selvittääkseen, mitä tyyppiä tarkoitat. Kääntäjä pystyy myös antamaan hyödyllisempiä virheilmoituksia, jos se tietää, mitä tyyppejä funktio odottaa.

Kun määrittelet useita parametreja, erota parametrijulistukset pilkuilla, näin:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-18-functions-with-multiple-parameters/src/main.rs}}
}

Tämä esimerkki luo funktion nimeltä print_labeled_measurement kahdella parametrilla. Ensimmäinen parametri on nimeltä value ja on i32. Toinen on nimeltä unit_label ja on tyyppiä char. Funktio tulostaa sitten tekstiä, joka sisältää sekä value- että unit_label-arvot.

Kokeillaan suorittaa tämä koodi. Korvaa functions-projektisi src/main.rs-tiedoston ohjelma edellä olevalla esimerkillä ja suorita se cargo run -komennolla:

{{#include ../listings/ch03-common-programming-concepts/no-listing-18-functions-with-multiple-parameters/output.txt}}

Koska kutsuimme funktiota arvolla 5 value-parametrille ja 'h' unit_label-parametrille, ohjelman tuloste sisältää nämä arvot.

Lausekkeet ja lauseet

Funktioiden rungot koostuvat sarjasta lauseita, jotka valinnaisesti päättyvät lausekkeeseen. Tähän mennessä käsittelemämme funktiot eivät ole sisältäneet päättyvää lauseketta, mutta olet nähnyt lausekkeen osana lausetta. Koska Rust on lausekepohjainen kieli, tämä on tärkeä ero ymmärtää. Muissa kielissä ei ole samoja erotteluja, joten katsotaan, mitä lauseet ja lausekkeet ovat ja miten niiden erot vaikuttavat funktioiden runkoihin.

• Lauseet ovat ohjeita, jotka suorittavat jonkin toiminnon eivätkä palauta arvoa.
• Lausekkeet evaluoituvat tulosarvoksi.

Katsotaan joitakin esimerkkejä.

Olemme itse asiassa jo käyttäneet lauseita ja lausekkeita. Muuttujan luominen ja arvon antaminen sille let-avainsanalla on lause. Listauksessa 3-1 let y = 6; on lause.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-01/src/main.rs}}
}

Funktioiden määritelmät ovat myös lauseita; koko edellinen esimerkki on itsessään lause. (Kuten näemme pian, funktion kutsuminen ei ole lause, vaikka se olisikin.)

Lauseet eivät palauta arvoja. Siksi et voi sijoittaa let-lausetta toiseen muuttujaan, kuten seuraava koodi yrittää; saat virheen:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-19-statements-vs-expressions/src/main.rs}}

Kun suoritat tämän ohjelman, saamasi virhe näyttää tältä:

{{#include ../listings/ch03-common-programming-concepts/no-listing-19-statements-vs-expressions/output.txt}}

let y = 6 -lause ei palauta arvoa, joten x:llä ei ole mitään, mihin sitoutua. Tämä eroaa siitä, mitä tapahtuu muissa kielissä, kuten C:ssä ja Rubyssä, joissa sijoitus palauttaa sijoituksen arvon. Näissä kielissä voit kirjoittaa x = y = 6 ja molemmilla x:llä ja y:llä on arvo 6; näin ei ole Rustissa.

Lausekkeet evaluoituvat arvoksi ja muodostavat suurimman osan muusta koodista, jonka kirjoitat Rustissa. Harkitse matemaattista operaatiota, kuten 5 + 6, joka on lauseke, joka evaluoituu arvoksi 11. Lausekkeet voivat olla osa lauseita: Listauksessa 3-1 6 lauseessa let y = 6; on lauseke, joka evaluoituu arvoksi 6. Funktion kutsuminen on lauseke. Makron kutsuminen on lauseke. Uusi näkyvyysalueen lohko, joka luodaan aaltosulkeilla, on lauseke, esimerkiksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-20-blocks-are-expressions/src/main.rs}}
}

Tämä lauseke:

{
    let x = 3;
    x + 1
}

on lohko, joka tässä tapauksessa evaluoituu arvoksi 4. Tämä arvo sidotaan y:hyn osana let-lausetta. Huomaa x + 1 -rivi ilman puolipistettä lopussa, toisin kuin useimmat tähän mennessä näkemäsi rivit. Lausekkeet eivät sisällä päättyvää puolipistettä. Jos lisäät puolipisteen lausekkeen loppuun, muutat sen lauseeksi, eikä se sitten palauta arvoa. Pidä tämä mielessä, kun tutkit funktioiden paluuarvoja ja lausekkeita seuraavaksi.

Funktiot paluuarvoilla

Funktiot voivat palauttaa arvoja koodille, joka kutsuu niitä. Emme nimeä paluuarvoja, mutta meidän täytyy julistaa niiden tyyppi nuolen (->) jälkeen. Rustissa funktion paluuarvo on synonyymi funktion rungon lohkon viimeisen lausekkeen arvolle. Voit palata aikaisin funktiosta return-avainsanalla ja määrittämällä arvon, mutta useimmat funktiot palauttavat viimeisen lausekkeen implisiittisesti. Tässä on esimerkki funktiosta, joka palauttaa arvon:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-21-function-return-values/src/main.rs}}
}

five-funktiossa ei ole funktiokutsuja, makroja eikä edes let-lauseita—vain numero 5 itsestään. Se on täysin kelvollinen funktio Rustissa. Huomaa, että funktion paluutyyppi on myös määritelty -> i32:ksi. Kokeile suorittaa tämä koodi; tulosteen pitäisi näyttää tältä:

{{#include ../listings/ch03-common-programming-concepts/no-listing-21-function-return-values/output.txt}}

5 five-funktiossa on funktion paluuarvo, minkä vuoksi paluutyyppi on i32. Tarkastellaan tätä tarkemmin. Kaksi tärkeää asiaa: Ensinnäkin rivi let x = five(); osoittaa, että käytämme funktion paluuarvoa muuttujan alustamiseen. Koska five-funktio palauttaa 5:n, tämä rivi on sama kuin seuraava:

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

Toiseksi five-funktiolla ei ole parametreja ja se määrittelee paluuarvon tyypin, mutta funktion runko on yksinäinen 5 ilman puolipistettä, koska se on lauseke, jonka arvon haluamme palauttaa.

Katsotaan toista esimerkkiä:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-22-function-parameter-and-return/src/main.rs}}
}

Tämän koodin suorittaminen tulostaa The value of x is: 6. Mutta mitä tapahtuu, jos laitamme puolipisteen rivin loppuun, joka sisältää x + 1, muuttaen sen lausekkeesta lauseeksi?

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/src/main.rs}}

Tämän koodin kääntäminen tuottaa virheen seuraavasti:

{{#include ../listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt}}

Päävirheilmoitus mismatched types paljastaa tämän koodin ydinongelman. plus_one-funktion määritelmä sanoo, että se palauttaa i32:n, mutta lauseet eivät evaluoidu arvoksi, mikä ilmaistaan ():lla, yksikkötyypillä. Siksi mitään ei palauteta, mikä on ristiriidassa funktion määritelmän kanssa ja johtaa virheeseen. Tässä tulosteessa Rust tarjoaa viestin, joka saattaa auttaa korjaamaan ongelman: Se ehdottaa puolipisteen poistamista, mikä korjaisi virheen.

Kommentit

Kommentit

Kaikki ohjelmoijat pyrkivät tekemään koodistaan helposti ymmärrettävää, mutta joskus tarvitaan lisäselitystä. Näissä tapauksissa ohjelmoijat jättävät kommentteja lähdekoodiinsa, joita kääntäjä ohittaa, mutta joita lähdekoodia lukevat ihmiset saattavat pitää hyödyllisinä.

Tässä on yksinkertainen kommentti:

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

Rustissa idiomaattinen kommenttityyli aloittaa kommentin kahdella kauttaviivalla, ja kommentti jatkuu rivin loppuun. Kommenteille, jotka ulottuvat useammalle riville, sinun täytyy sisällyttää // jokaiselle riville, näin:

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

Kommentit voidaan myös sijoittaa koodia sisältävien rivien loppuun:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-24-comments-end-of-line/src/main.rs}}
}

Mutta näet ne useammin tässä muodossa, kommentti erillisellä rivillä sen koodin yläpuolella, jota se selittää:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-25-comments-above-line/src/main.rs}}
}

Rustissa on myös toinenlaisia kommentteja, dokumentaatiokommentteja, joita käsittelemme “Craten julkaiseminen Crates.io:hon” -osiossa Luvussa 14.

Ohjausrakenne

Ohjausrakenteet

Mahdollisuus suorittaa koodia riippuen siitä, onko ehto true, ja mahdollisuus suorittaa koodia toistuvasti, kun ehto on true, ovat perusrakennuspalikoita useimmissa ohjelmointikielissä. Yleisimmät rakenteet, jotka antavat hallita Rust-koodin suoritusvirtaa, ovat if-lausekkeet ja silmukat.

if-lausekkeet

if-lauseke antaa haarauttaa koodiasi ehtojen mukaan. Annat ehdon ja sanot sitten: “Jos tämä ehto täyttyy, suorita tämä koodilohko. Jos ehto ei täyty, älä suorita tätä koodilohkoa.”

Luo uusi projekti nimeltä branches projects-kansioosi tutkiaksesi if-lauseketta. Kirjoita src/main.rs-tiedostoon seuraava:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-26-if-true/src/main.rs}}
}

Kaikki if-lausekkeet alkavat avainsanalla if, jota seuraa ehto. Tässä tapauksessa ehto tarkistaa, onko muuttujan number arvo pienempi kuin 5. Sijoitamme koodilohkon, joka suoritetaan, jos ehto on true, heti ehdon jälkeen aaltosulkeiden sisään. if-lausekkeiden ehtoihin liittyviä koodilohkoja kutsutaan joskus haaroiksi, aivan kuten match-lausekkeiden haaroiksi, joita käsittelimme “Arvauksen vertaaminen salaisnumeroon” -osiossa Luvussa 2.

Valinnaisesti voimme myös sisällyttää else-lausekkeen, kuten teimme tässä, antaaksemme ohjelmalle vaihtoehtoisen koodilohkon suoritettavaksi, jos ehto evaluoituu false:ksi. Jos et anna else-lauseketta ja ehto on false, ohjelma ohittaa if-lohkon ja siirtyy seuraavaan koodinpalaan.

Kokeile suorittaa tämä koodi; sinun pitäisi nähdä seuraava tuloste:

{{#include ../listings/ch03-common-programming-concepts/no-listing-26-if-true/output.txt}}

Kokeillaan muuttaa number-muuttujan arvoksi sellainen, joka tekee ehdosta false, ja katsotaan, mitä tapahtuu:

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-27-if-false/src/main.rs:here}}

Suorita ohjelma uudelleen ja katso tuloste:

{{#include ../listings/ch03-common-programming-concepts/no-listing-27-if-false/output.txt}}

On myös syytä huomata, että tämän koodin ehdon täytyy olla bool. Jos ehto ei ole bool, saamme virheen. Kokeile esimerkiksi suorittaa seuraava koodi:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-28-if-condition-must-be-bool/src/main.rs}}

if-ehto evaluoituu tällä kertaa arvoksi 3, ja Rust heittää virheen:

{{#include ../listings/ch03-common-programming-concepts/no-listing-28-if-condition-must-be-bool/output.txt}}

Virhe osoittaa, että Rust odotti bool-tyyppiä mutta sai kokonaisluvun. Toisin kuin kielet kuten Ruby ja JavaScript, Rust ei automaattisesti yritä muuntaa ei-totuusarvoisia tyyppejä totuusarvoiksi. Sinun täytyy olla eksplisiittinen ja antaa if:lle aina totuusarvo ehtona. Jos haluamme if-koodilohkon suorittuvan vain, kun luku ei ole yhtä suuri kuin 0, voimme muuttaa if-lausekkeen seuraavaksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-29-if-not-equal-0/src/main.rs}}
}

Tämän koodin suorittaminen tulostaa number was something other than zero.

Useiden ehtojen käsittely else if:llä

Voit käyttää useita ehtoja yhdistämällä if- ja else-lausekkeet else if -lausekkeeseen. Esimerkiksi:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-30-else-if/src/main.rs}}
}

Tällä ohjelmalla on neljä mahdollista polkua. Suoritettuasi sen sinun pitäisi nähdä seuraava tuloste:

{{#include ../listings/ch03-common-programming-concepts/no-listing-30-else-if/output.txt}}

Kun tämä ohjelma suoritetaan, se tarkistaa jokaisen if-lausekkeen vuorollaan ja suorittaa ensimmäisen rungon, jonka ehto evaluoituu true:ksi. Huomaa, että vaikka 6 on jaollinen 2:lla, emme näe tulostetta number is divisible by 2, emmekä number is not divisible by 4, 3, or 2 -tekstiä else-lohkosta. Tämä johtuu siitä, että Rust suorittaa vain ensimmäisen true-ehdon lohkon, eikä tarkista loputkaan sen jälkeen.

Liian monen else if -lausekkeen käyttö voi sotkea koodiasi, joten jos sinulla on useampi kuin yksi, saatat haluta refaktoroida koodisi. Luku 6 kuvaa tehokkaan Rust-haarautumisrakenteen nimeltä match näihin tapauksiin.

if:n käyttö let-lausekkeessa

Koska if on lauseke, voimme käyttää sitä let-lausekkeen oikealla puolella sijoittaaksemme tuloksen muuttujaan, kuten Listauksessa 3-2.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-02/src/main.rs}}
}

number-muuttuja sidotaan arvoon if-lausekkeen tuloksen perusteella. Suorita tämä koodi nähdäksesi, mitä tapahtuu:

{{#include ../listings/ch03-common-programming-concepts/listing-03-02/output.txt}}

Muista, että koodilohkot evaluoituvat viimeiseen lausekkeeseensa, ja numerot itsessään ovat myös lausekkeita. Tässä tapauksessa koko if-lausekkeen arvo riippuu siitä, mikä koodilohko suoritetaan. Tämä tarkoittaa, että arvojen, joilla on potentiaalia olla tuloksia kustakin if-haarasta, täytyy olla sama tyyppi; Listauksessa 3-2 sekä if- että else-haaran tulokset olivat i32-kokonaislukuja. Jos tyypit eivät täsmää, kuten seuraavassa esimerkissä, saamme virheen:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-31-arms-must-return-same-type/src/main.rs}}

Kun yritämme kääntää tämän koodin, saamme virheen. if- ja else-haaroilla on yhteensopimattomat arvotyypit, ja Rust osoittaa tarkalleen, mistä ongelma löytyy ohjelmasta:

{{#include ../listings/ch03-common-programming-concepts/no-listing-31-arms-must-return-same-type/output.txt}}

if-lohkon lauseke evaluoituu kokonaisluvuksi, ja else-lohkon lauseke evaluoituu merkkijonoksi. Tämä ei toimi, koska muuttujilla täytyy olla yksi tyyppi, ja Rustin täytyy tietää varmasti käännösaikana, mikä number-muuttujan tyyppi on. number-muuttujan tyypin tunteminen antaa kääntäjälle mahdollisuuden tarkistaa, että tyyppi on kelvollinen kaikkialla, missä käytämme number-muuttujaa. Rust ei pystyisi siihen, jos number-muuttujan tyyppi määräytyisi vasta ajonaikana; kääntäjä olisi monimutkaisempi ja antaisi vähemmän takeita koodista, jos sen täytyisi seurata useita hypoteettisia tyyppejä mille tahansa muuttujalle.

Toisto silmukoilla

On usein hyödyllistä suorittaa koodilohkoa useammin kuin kerran. Tätä tehtävää varten Rust tarjoaa useita silmukoita, jotka suorittavat silmukan rungon koodin loppuun ja alkavat sitten heti alusta. Kokeillaksemme silmukoita luodaan uusi projekti nimeltä loops.

Rustissa on kolmelaista silmukkaa: loop, while ja for. Kokeillaan kutakin.

Koodin toistaminen loop:lla

loop-avainsana käskee Rustia suorittamaan koodilohkon uudelleen ja uudelleen joko ikuisesti tai kunnes kerrot sille eksplisiittisesti lopettamaan.

Esimerkkinä muuta loops-kansiosi src/main.rs-tiedosto näyttämään tältä:

Filename: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-32-loop/src/main.rs}}

Kun suoritamme tämän ohjelman, näemme again! tulostuvan yhä uudelleen, kunnes pysäytämme ohjelman manuaalisesti. Useimmat terminaalit tukevat näppäinyhdistelmää ctrl-C keskeyttääkseen ohjelman, joka on jumissa jatkuvassa silmukassa. Kokeile:

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

Symboli ^C edustaa kohtaa, jossa painoit ctrl-C.

Saatat tai et näe sanaa again! tulostuvan ^C:n jälkeen riippuen siitä, missä koodissa silmukka oli, kun se vastaanotti keskeytystsignaalin.

Onneksi Rust tarjoaa myös tavan poistua silmukasta koodilla. Voit sijoittaa break-avainsanan silmukan sisään kertoaksesi ohjelmalle, milloin lopettaa silmukan suorittaminen. Muistathan, että teimme tämän arvauspelissä “Lopettaminen oikean arvauksen jälkeen” -osiossa Luvussa 2 poistuaksemme ohjelmasta, kun käyttäjä voitti pelin arvaamalla oikean numeron.

Käytimme myös continue-avainsanaa arvauspelissä, joka silmukassa käskee ohjelmaa ohittamaan kaiken jäljellä olevan koodin tässä iteraatiossa ja siirtymään seuraavaan iteraatioon.

Arvojen palauttaminen silmukoista

Yksi loop-silmukan käyttötarkoitus on yrittää uudelleen operaatiota, jonka tiedät saattavan epäonnistua, kuten tarkistaa, onko säie suorittanut työnsä loppuun. Saatat myös tarvita välittää kyseisen operaation tuloksen silmukasta koodisi loppuosan. Voit tehdä tämän lisäämällä palautettavan arvon break-lausekkeen jälkeen, jota käytät silmukan pysäyttämiseen; tämä arvo palautetaan silmukasta, jotta voit käyttää sitä, kuten tässä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-33-return-value-from-loop/src/main.rs}}
}

Ennen silmukkaa julistamme muuttujan nimeltä counter ja alustamme sen arvoon 0. Sitten julistamme muuttujan nimeltä result pitämään silmukasta palautettavan arvon. Jokaisella silmukan iteraatiolla lisäämme 1:n counter-muuttujaan ja tarkistamme sitten, onko counter yhtä suuri kuin 10. Kun se on, käytämme break-avainsanaa arvolla counter * 2. Silmukan jälkeen käytämme puolipistettä lopettaaksemme lausekkeen, joka sijoittaa arvon result:iin. Lopuksi tulostamme result:in arvon, joka tässä tapauksessa on 20.

Voit myös return-palata silmukan sisältä. Vaikka break poistuu vain nykyisestä silmukasta, return poistuu aina nykyisestä funktiosta.

Erottelu silmukkamerkinnöillä

Jos sinulla on silmukoita silmukoiden sisällä, break ja continue koskevat sisintä silmukkaa kyseisessä kohdassa. Voit valinnaisesti määrittää silmukkamerkinnän silmukalle, jota voit sitten käyttää break- tai continue-avainsanojen kanssa määrittääksesi, että nämä avainsanat koskevat merkittyä silmukkaa sisimmän silmukan sijaan. Silmukkamerkintöjen täytyy alkaa yksittäisellä heittomerkillä. Tässä on esimerkki kahdella sisäkkäisellä silmukalla:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-32-5-loop-labels/src/main.rs}}
}

Ulompi silmukka on merkitty 'counting_up, ja se laskee ylöspäin 0:sta 2:een. Sisempi silmukka ilman merkintää laskee alaspäin 10:stä 9:ään. Ensimmäinen break, joka ei määritä merkintää, poistuu vain sisemmästä silmukasta. break 'counting_up; -lauseke poistuu ulommasta silmukasta. Tämä koodi tulostaa:

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-32-5-loop-labels/output.txt}}

Ehdollisten silmukoiden virtaviivaistaminen while:lla

Ohjelman täytyy usein arvioida ehto silmukan sisällä. Niin kauan kuin ehto on true, silmukka suoritetaan. Kun ehto ei enää ole true, ohjelma kutsuu break:ia pysäyttääkseen silmukan. Tällaisen käyttäytymisen voi toteuttaa yhdistelmällä loop, if, else ja break; voit kokeilla sitä nyt ohjelmassa, jos haluat. Tämä malli on kuitenkin niin yleinen, että Rustissa on siihen sisäänrakennettu kielenrakenne nimeltä while-silmukka. Listauksessa 3-3 käytämme while-silmukkaa silmukan suorittamiseen kolme kertaa, laskemalla alas joka kerta, ja sitten silmukan jälkeen tulostamaan viestin ja poistumaan.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-03/src/main.rs}}
}

Tämä rakenne poistaa paljon sisäkkäisyyttä, joka olisi tarpeen, jos käyttäisit loop, if, else ja break, ja se on selkeämpi. Niin kauan kuin ehto evaluoituu true:ksi, koodi suoritetaan; muuten silmukasta poistutaan.

Kokoelman läpikäynti for-silmukalla

Voit valita käyttää while-rakennetta silmukan läpikäymiseen kokoelman elementtien yli, kuten taulukon. Esimerkiksi Listauksen 3-4 silmukka tulostaa jokaisen elementin taulukossa a.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-04/src/main.rs}}
}

Tässä koodi laskee ylöspäin taulukon elementtien läpi. Se alkaa indeksistä 0 ja silmukoi, kunnes se saavuttaa taulukon viimeisen indeksin (eli kun index < 5 ei enää ole true). Tämän koodin suorittaminen tulostaa jokaisen elementin taulukossa:

{{#include ../listings/ch03-common-programming-concepts/listing-03-04/output.txt}}

Kaikki viisi taulukon arvoa ilmestyvät terminaaliin odotetusti. Vaikka index saavuttaa arvon 5 jossain vaiheessa, silmukka lopettaa suorittamisen ennen kuin yrittää hakea kuudetta arvoa taulukosta.

Tämä lähestymistapa on virhealtis; voisimme saada ohjelman panikoimaan, jos indeksiarvo tai testiehto on virheellinen. Esimerkiksi jos muuttaisit a-taulukon määritelmää sisältämään neljä elementtiä mutta unohtaisit päivittää ehdon while index < 4:ksi, koodi panikoisi. Se on myös hidas, koska kääntäjä lisää ajonaikaista koodia tarkistamaan jokaisella silmukan iteraatiolla, onko indeksi taulukon rajojen sisällä.

Tiiviimpänä vaihtoehtona voit käyttää for-silmukkaa ja suorittaa koodia jokaiselle kokoelman kohteelle. for-silmukka näyttää Listauksen 3-5 koodilta.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-05/src/main.rs}}
}

Kun suoritamme tämän koodin, näemme saman tulosteen kuin Listauksessa 3-4. Tärkeämpää on, että olemme nyt lisänneet koodin turvallisuutta ja poistaneet bugien mahdollisuuden, jotka voisivat johtua taulukon lopun ylittämisestä tai liian vähäisestä etenemisestä ja joidenkin kohteiden ohittamisesta. Konekoodi, joka generoidaan for-silmukoista, voi myös olla tehokkaampaa, koska indeksiä ei tarvitse verrata taulukon pituuteen jokaisella iteraatiolla.

Käyttämällä for-silmukkaa sinun ei tarvitse muistaa muuttaa muuta koodia, jos muutat taulukon arvojen määrää, toisin kuin Listauksessa 3-4 käytetyllä menetelmällä.

for-silmukoiden turvallisuus ja tiiviys tekevät niistä yleisimmin käytetyn silmukkarakenteen Rustissa. Jopa tilanteissa, joissa haluat suorittaa koodia tietyn määrän kertoja, kuten Listauksen 3-3 while-silmukassa käytetyssä lähtölaskentaesimerkissä, useimmat Rustaceanit käyttäisivät for-silmukkaa. Tapa tehdä se olisi käyttää standardikirjaston tarjoamaa Range-tyyppiä, joka generoi kaikki numerot peräkkäin yhdestä numerosta toiseen numeroon asti.

Tässä on, miltä lähtölaskenta näyttäisi for-silmukalla ja toisella menetelmällä, josta emme ole vielä puhuneet, rev:llä kääntääksemme alueen:

Filename: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-34-for-range/src/main.rs}}
}

Tämä koodi on hieman siistimpi, eikö?

Yhteenveto

Sinä teit sen! Tämä oli laaja luku: Opit muuttujista, skaari- ja yhdistelmätietotyypeistä, funktioista, kommenteista, if-lausekkeista ja silmukoista! Harjoitellaksesi tässä luvussa käsiteltyjä käsitteitä, kokeile rakentaa ohjelmia, jotka:

• Muuntavat lämpötiloja Fahrenheit- ja Celsius-asteiden välillä.
• Generoivat n:nnen Fibonacci-luvun.
• Tulostavat joululaulun “The Twelve Days of Christmas” -laulun sanat hyödyntäen laulun toistoa.

Kun olet valmis jatkamaan, puhumme Rustin käsitteestä, jota ei yleensä ole muissa ohjelmointikielissä: omistajuudesta.

Omistajuuden ymmärtäminen

Omistajuus on Rustin ainutlaatuisin ominaisuus, ja sillä on syvällisiä vaikutuksia koko kieleen. Sen ansiosta Rust pystyy takaamaan muistiturvallisuuden ilman roskienkerääjää, joten on tärkeää ymmärtää, miten omistajuus toimii. Tässä luvussa käsittelemme omistajuutta sekä siihen liittyviä ominaisuuksia: lainaamista, viipaleita ja sitä, miten Rust asettelee tietoa muistiin.

Mikä on omistajuus?

Mikä on omistajuus?

Omistajuus on joukko sääntöjä, jotka määräävät, miten Rust-ohjelma hallitsee muistia. Kaikki ohjelmat joutuvat hallitsemaan muistinkäyttöään suorituksen aikana. Joissakin kielissä on roskienkerääjä, joka säännöllisesti vapauttaa käyttämättömän muistin ohjelman suorittaessa; toisissa kielissä ohjelmoijan on itse varattava ja vapautettava muisti manuaalisesti. Rust käyttää kolmatta lähestymistapaa: muisti hallitaan omistajuusjärjestelmällä, jonka sääntöjä kääntäjä tarkistaa. Jos sääntöjä rikotaan, ohjelma ei käänny. Omistajuuden ominaisuudet eivät hidasta ohjelman suorittamista.

Koska omistajuus on monille ohjelmoijille uusi käsite, sen omaksuminen vie aikaa. Hyvä uutinen on, että mitä enemmän harjoittelet Rustia ja sen omistajuussääntöjä, sitä helpommaksi turvallisen ja tehokkaan koodin kirjoittaminen tulee. Jatka harjoittelua!

Kun ymmärrät omistajuuden, sinulla on vahva pohja Rustin ainutlaatuisten ominaisuuksien ymmärtämiselle. Tässä luvussa opit omistajuudesta käyttämällä esimerkkejä hyvin yleisestä tietorakenteesta: merkkijonoista.

Omistajuussäännöt

Ensinnäkin tarkastellaan omistajuuden sääntöjä. Muista nämä säännöt, kun käsittelemme niitä havainnollistavia esimerkkejä:

• Jokaisella arvolla Rustissa on omistaja.
• Vain yksi omistaja voi olla kerrallaan.
• Kun omistaja poistuu näkyvyysalueelta, arvo poistetaan.

Muuttujan näkyvyysalue

Nyt kun olemme käyneet läpi Rustin perussyntaksia, emme sisällytä kaikkiin esimerkkeihin fn main() { -koodia, joten jos seuraat mukana, varmista, että sijoitat seuraavat esimerkit main-funktion sisään manuaalisesti. Näin esimerkkimme ovat hieman tiiviimpiä, jotta voimme keskittyä varsinaisiin yksityiskohtiin eikä pohjakoodiin.

Ensimmäisenä omistajuusesimerkkinä tarkastelemme joidenkin muuttujien näkyvyysaluetta. Näkyvyysalue on ohjelman osa, jossa kohde on voimassa. Tarkastele seuraavaa muuttujaa:

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

Muuttuja s viittaa merkkijonoliteraaliin, jossa merkkijonon arvo on kovakoodattu ohjelman tekstiin. Muuttuja on voimassa siitä hetkestä, jolloin se on määritelty, nykyisen näkyvyysalueen loppuun asti. Listaus 4-1 näyttää ohjelman, jossa kommenteissa on merkitty, missä muuttuja s olisi voimassa.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-01/src/main.rs:here}}
}

Toisin sanoen tässä on kaksi tärkeää ajankohtaa:

• Kun s tulee näkyvyysalueelle, se on voimassa.
• Se pysyy voimassa, kunnes se poistuu näkyvyysalueelta.

Tässä vaiheessa näkyvyysalueen ja muuttujien voimassaolon välinen suhde on samanlainen kuin muissa ohjelmointikielissä. Rakennamme tämän ymmärryksen päälle esittelemällä String-tyypin.

String-tyyppi

Omistajuussääntöjen havainnollistamiseksi tarvitsemme monimutkaisemman tietotyypin kuin ne, jotka käsittelimme Luvun 3 ”Tietotyypit” -osiossa. Aiemmin käsitellyt tyypit ovat tunnetun kokoisia, ne voidaan tallentaa pinolle ja poistaa pinolta, kun niiden näkyvyysalue päättyy, ja ne voidaan nopeasti ja helposti kopioida uudeksi, riippumattomaksi instanssiksi, jos koodin toinen osa tarvitsee saman arvon eri näkyvyysalueella. Haluamme kuitenkin tarkastella kekoon tallennettuja tietoja ja tutkia, miten Rust tietää, milloin siivota nämä tiedot, ja String-tyyppi on erinomainen esimerkki.

Keskitymme String-tyypin osiin, jotka liittyvät omistajuuteen. Nämä näkökohdat pätevät myös muihin monimutkaisiin tietotyyppeihin, olivatpa ne standardikirjaston tarjoamia tai itse luomiasi. Käsittelemme String-tyyppiä tarkemmin Luvussa 8.

Olemme jo nähneet merkkijonoliteraaleja, joissa merkkijonoarvo on kovakoodattu ohjelmaamme. Merkkijonoliteraalit ovat käteviä, mutta ne eivät sovi kaikkiin tilanteisiin, joissa haluamme käyttää tekstiä. Yksi syy on, että ne ovat muuttumattomia. Toinen on, että kaikkia merkkijonoarvoja ei voida tietää, kun kirjoitamme koodiamme: esimerkiksi jos haluamme ottaa käyttäjän syötteen ja tallentaa sen? Näihin tilanteisiin Rustissa on toinen merkkijonotyyppi, String. Tämä tyyppi hallitsee kekoon allokoituja tietoja ja voi siksi tallentaa tekstimäärän, joka ei ole tiedossa käännösaikana. Voit luoda String-tyypin merkkijonoliteraalista from-funktiolla näin:

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

Kaksoispiste :: -operaattori antaa meidän nimetä tämän tietyn from-funktion String-tyypin alle sen sijaan, että käyttäisimme jotain nimeä kuten string_from. Käsittelemme tätä syntaksia tarkemmin Luvun 5 ”Metodit” -osiossa ja kun puhumme nimiavaruuksista moduuleilla Luvun 7 ”Polut viittaamiseen moduulipuun kohteeseen” -osiossa.

Tämänkaltainen merkkijono voidaan muuttaa:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-01-can-mutate-string/src/main.rs:here}}
}

Eli mikä ero täällä on? Miksi String voidaan muuttaa mutta literaaleja ei? Ero on siinä, miten nämä kaksi tyyppiä käsittelevät muistia.

Muisti ja allokointi

Merkkijonoliteraalin tapauksessa tiedämme sisällön käännösaikana, joten teksti kovakoodataan suoraan lopulliseen suoritettavaan tiedostoon. Siksi merkkijonoliteraalit ovat nopeita ja tehokkaita. Nämä ominaisuudet johtuvat kuitenkin merkkijonoliteraalin muuttumattomuudesta. Valitettavasti emme voi laittaa muistipätkää binääritiedostoon jokaiselle tekstiosalle, jonka koko ei ole tiedossa käännösaikana ja jonka koko voi muuttua ohjelman suorituksen aikana.

String-tyypin tapauksessa muuttuvan, kasvavan tekstin tukemiseksi meidän täytyy allokoida kekoon tietty määrä muistia, joka ei ole tiedossa käännösaikana, sisällön säilyttämiseksi. Tämä tarkoittaa:

• Muisti täytyy pyytää muistin allokoijalta suorituksen aikana.
• Tarvitsemme tavan palauttaa tämä muisti allokoijalle, kun olemme valmiita String-tyypin kanssa.

Ensimmäisen osan teemme itse: kun kutsumme String::from, sen toteutus pyytää tarvitsemansa muistin. Tämä on melkein yleispätevää kaikissa ohjelmointikielissä.

Toinen osa on kuitenkin erilainen. Kielissä, joissa on roskienkerääjä (GC), GC seuraa ja siivoaa muistin, jota ei enää käytetä, emmekä meidän tarvitse ajatella sitä. Useimmissa kielissä ilman GC:tä vastuullamme on tunnistaa, milloin muistia ei enää käytetä, ja kutsua koodia vapauttamaan se eksplisiittisesti, aivan kuten teimme pyytäessämme sitä. Tämän tekeminen oikein on historiallisesti ollut vaikea ohjelmointiongelma. Jos unohdamme, tuhlaamme muistia. Jos teemme sen liian aikaisin, meillä on virheellinen muuttuja. Jos teemme sen kahdesti, sekin on bugi. Meidän täytyy yhdistää täsmälleen yksi allocate täsmälleen yhteen free-kutsuun.

Rust valitsee eri polun: muisti palautetaan automaattisesti, kun muuttujan, joka omistaa sen, näkyvyysalue päättyy. Tässä on versio näkyvyysalueesimerkistämme Listauksesta 4-1 käyttäen String-tyyppiä merkkijonoliteraalin sijaan:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-02-string-scope/src/main.rs:here}}
}

On luonnollinen kohta, jossa voimme palauttaa String-tyypin tarvitseman muistin allokoijalle: kun s poistuu näkyvyysalueelta. Kun muuttuja poistuu näkyvyysalueelta, Rust kutsuu erityistä funktiota puolestamme. Tätä funktiota kutsutaan drop -funktioksi, ja siihen String-tyypin tekijä voi sijoittaa koodin muistin palauttamiseksi. Rust kutsuu drop-funktiota automaattisesti sulkevassa aaltosulussa.

Huom: C++:ssa tätä resurssien vapauttamisen mallia kohteen elinkaaren lopussa kutsutaan joskus Resource Acquisition Is Initialization (RAII) -malliksi. Rustin drop-funktio on tuttu sinulle, jos olet käyttänyt RAII-malleja.

Tällä mallilla on syvällinen vaikutus siihen, miten Rust-koodia kirjoitetaan. Se saattaa vaikuttaa yksinkertaiselta nyt, mutta koodin käyttäytyminen voi olla odottamatonta monimutkaisemmissa tilanteissa, kun haluamme useiden muuttujien käyttävän kekoon allokoimiamme tietoja. Tutkitaan joitakin näistä tilanteista nyt.

Muuttujien ja tietojen vuorovaikutus siirron (move) kautta

Useat muuttujat voivat vuorovaikuttaa samojen tietojen kanssa eri tavoin Rustissa. Tarkastellaan esimerkkiä kokonaisluvulla Listauksessa 4-2.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-02/src/main.rs:here}}
}

Voimme todennäköisesti arvata, mitä tämä tekee: ”sido arvo 5 muuttujaan x; tee sitten kopio arvosta x:ssä ja sido se muuttujaan y.” Meillä on nyt kaksi muuttujaa, x ja y, ja molemmat ovat 5. Näin todellakin tapahtuu, koska kokonaisluvut ovat yksinkertaisia arvoja tunnetulla, kiinteällä koolla, ja nämä kaksi 5-arvoa työnnetään pinolle.

Tarkastellaan nyt String-versiota:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-03-string-move/src/main.rs:here}}
}

Tämä näyttää hyvin samankaltaiselta, joten voisimme olettaa, että se toimisi samalla tavalla: toinen rivi tekisi kopion arvosta s1:ssä ja sitoisi sen s2:een. Mutta näin ei aivan tapahdu.

Katso Kuvaa 4-1 nähdäksesi, mitä String-tyypille tapahtuu konepellin alla. String koostuu kolmesta osasta, jotka näkyvät vasemmalla: osoitin muistiin, joka sisältää merkkijonon sisällön, pituus ja kapasiteetti. Tämä tietoryhmä tallennetaan pinolle. Oikealla on keon muisti, joka sisältää sisällön.

Kuva 4-1: String-tyypin esitys muistissa, kun se sisältää arvon "hello" ja on sidottu s1:een

Pituus on se, kuinka paljon muistia tavussa String-tyypin sisältö tällä hetkellä käyttää. Kapasiteetti on kokonaismäärä muistia tavuina, jonka String on saanut allokoijalta. Ero pituuden ja kapasiteetin välillä on merkityksellinen, mutta ei tässä kontekstissa, joten toistaiseksi kapasiteetin voi jättää huomiotta.

Kun sidomme s1:n s2:een, String-tyypin tiedot kopioidaan, eli kopioimme pinolla olevan osoittimen, pituuden ja kapasiteetin. Emme kopioi keon tietoja, joihin osoitin viittaa. Toisin sanoen tietojen esitys muistissa näyttää Kuvalta 4-2.

Kuva 4-2: Muuttujan s2 esitys muistissa, jolla on kopio s1:n osoittimesta, pituudesta ja kapasiteetista

Esitys ei näytä Kuvalta 4-3, miltä muisti näyttäisi, jos Rust kopioisi myös keon tiedot. Jos Rust tekisi näin, operaatio s2 = s1 voisi olla erittäin kallis suorituskyvyn kannalta, jos keon tiedot olisivat suuria.

Kuva 4-3: Toinen mahdollisuus sille, mitä s2 = s1 voisi tehdä, jos Rust kopioisi myös keon tiedot

Aiemmin sanoin, että kun muuttuja poistuu näkyvyysalueelta, Rust kutsuu automaattisesti drop-funktion ja siivoaa kyseisen muuttujan keon muistin. Kuva 4-2 kuitenkin näyttää molempien tietojen osoittimien osoittavan samaan sijaintiin. Tämä on ongelma: kun s2 ja s1 poistuvat näkyvyysalueelta, ne yrittävät molemmat vapauttaa saman muistin. Tätä kutsutaan kaksoisvapautus-virheeksi, ja se on yksi aiemmin mainituista muistiturvallisuusbugeista. Muistin vapauttaminen kahdesti voi johtaa muistin korruptoitumiseen, mikä voi puolestaan johtaa tietoturva-aukkoja.

Muistiturvallisuuden varmistamiseksi rivin let s2 = s1; jälkeen Rust pitää s1:tä enää voimassa olemattomana. Siksi Rustin ei tarvitse vapauttaa mitään, kun s1 poistuu näkyvyysalueelta. Katso, mitä tapahtuu, kun yrität käyttää s1:tä s2:n luomisen jälkeen; se ei toimi:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/src/main.rs:here}}

Saat virheen, joka on tämänkaltainen, koska Rust estää sinua käyttämästä mitätöityä viitettä:

{{#include ../listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/output.txt}}

Jos olet kuullut termit pinnallinen kopiointi ja syvä kopiointi työskennellessäsi muiden kielten kanssa, käsite osoittimen, pituuden ja kapasiteetin kopioimisesta kopioimatta tietoja kuulostaa todennäköisesti pinnalliselta kopioinnilta. Koska Rust myös mitätöi ensimmäisen muuttujan, sitä ei kutsuta pinnalliseksi kopioinniksi vaan siirroksi (move). Tässä esimerkissä sanoisimme, että s1 siirrettiin s2:een. Eli mitä todella tapahtuu, näkyy Kuvassa 4-4.

Kuva 4-4: Esitys muistissa sen jälkeen, kun s1 on mitätöity

Tämä ratkaisee ongelmamme! Kun vain s2 on voimassa, se yksin vapauttaa muistin poistuessaan näkyvyysalueelta, ja olemme valmiita.

Lisäksi tässä on implisiittinen suunnittelupäätös: Rust ei koskaan luo automaattisesti tietojesi ”syviä” kopioita. Siksi voidaan olettaa, että mikä tahansa automaattinen kopiointi on suorituskyvyn kannalta edullista.

Näkyvyysalue ja sijoitus

Tämän käänteinen on totta myös näkyvyysalueen, omistajuuden ja drop-funktion kautta vapautetun muistin suhteen. Kun sijoitat täysin uuden arvon olemassa olevaan muuttujaan, Rust kutsuu drop-funktion ja vapauttaa alkuperäisen arvon muistin välittömästi. Tarkastele esimerkiksi tätä koodia:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-04b-replacement-drop/src/main.rs:here}}
}

Määrittelemme aluksi muuttujan s ja sidomme sen String-tyyppiin arvolla "hello". Sitten luomme heti uuden String-tyypin arvolla "ahoy" ja sijoitamme sen s:ään. Tässä vaiheessa mikään ei enää viittaa alkuperäiseen keon arvoon.

Kuva 4-5: Esitys muistissa sen jälkeen, kun alkuperäinen arvo on korvattu kokonaan.

Alkuperäinen merkkijono poistuu siis välittömästi näkyvyysalueelta. Rust suorittaa drop-funktion sille, ja sen muisti vapautetaan heti. Kun tulostamme arvon lopussa, se on "ahoy, world!".

Muuttujien ja tietojen vuorovaikutus kloonauksen (clone) kautta

Jos haluamme kopioida String-tyypin keon tiedot syvästi, eikä vain pinon tietoja, voimme käyttää yleistä clone-metodia. Käsittelemme metodisyntaksia Luvussa 5, mutta koska metodit ovat yleisiä monissa ohjelmointikielissä, olet todennäköisesti nähnyt ne aiemmin.

Tässä on esimerkki clone-metodista käytössä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-05-clone/src/main.rs:here}}
}

Tämä toimii hyvin ja tuottaa eksplisiittisesti Kuvassa 4-3 näytetyn käyttäytymisen, jossa keon tiedot todella kopioidaan.

Kun näet clone-kutsun, tiedät, että jotain mielivaltaista koodia suoritetaan ja se koodi voi olla kallista. Se on visuaalinen merkki siitä, että jotain erilaista on meneillään.

Vain pinolla olevat tiedot: Copy

Meillä on vielä yksi mutka, josta emme ole puhuneet. Tämä koodi kokonaisluvuilla — osa näytettiin Listauksessa 4-2 — toimii ja on kelvollinen:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-06-copy/src/main.rs:here}}
}

Mutta tämä koodi näyttää ristiriitaiselta sen suhteen, mitä juuri opimme: meillä ei ole clone-kutsua, mutta x on silti voimassa eikä sitä siirretty y:hyn.

Syy on, että tyypit kuten kokonaisluvut, joiden koko on tiedossa käännösaikana, tallennetaan kokonaan pinolle, joten varsinaisten arvojen kopiot ovat nopeita tehdä. Tämä tarkoittaa, ettei ole syytä estää x:ää olemassa muuttujan y luomisen jälkeen. Toisin sanoen syvän ja pinnallisen kopioinnin välillä ei ole eroa tässä, joten clone-kutsu ei tekisi mitään erilaista tavalliseen pinnalliseen kopiointiin verrattuna, ja voimme jättää sen pois.

Rustissa on erityinen annotaatio nimeltä Copy-trait, jonka voimme sijoittaa pinolla tallennettuihin tyyppeihin, kuten kokonaisluvut (puhumme traiteista tarkemmin Luvussa 10). Jos tyyppi toteuttaa Copy-traitin, sitä käyttävät muuttujat eivät siirry vaan kopioidaan triviaalisti, joten ne ovat edelleen voimassa toiseen muuttujaan sijoittamisen jälkeen.

Rust ei anna meidän annotoida tyyppiä Copy:lla, jos tyyppi tai jokin sen osista on toteuttanut Drop-traitin. Jos tyypille täytyy tapahtua jotain erityistä, kun arvo poistuu näkyvyysalueelta, ja lisäämme Copy-annotaation kyseiseen tyyppiin, saamme käännösaikaisen virheen. Opit lisäämään Copy-annotaation omaan tyyppiisi traitin toteuttamiseksi liitteessä C kohdassa ”Johdettavat traitit”.

Mitä tyypit toteuttavat Copy-traitin? Voit tarkistaa tietyn tyypin dokumentaatiosta varmuuden vuoksi, mutta yleissääntönä mikä tahansa yksinkertaisten skalaariarvojen ryhmä voi toteuttaa Copy:n, eikä mikään, mikä vaatii allokointia tai on jonkinlainen resurssi, voi toteuttaa Copy:tä. Tässä on joitakin Copy:n toteuttavia tyyppejä:

• Kaikki kokonaislukutyypit, kuten u32.
• Totuusarvotyyppi bool arvoilla true ja false.
• Kaikki liukulukutyypit, kuten f64.
• Merkkityyppi char.
• Tuplet, jos ne sisältävät vain tyyppejä, jotka myös toteuttavat Copy:n. Esimerkiksi (i32, i32) toteuttaa Copy:n, mutta (i32, String) ei.

Omistajuus ja funktiot

Arvon välittämisen mekaniikka funktiolle on samanlainen kuin arvon sijoittaminen muuttujaan. Muuttujan välittäminen funktiolle siirtää tai kopioi sen, aivan kuten sijoitus. Listaus 4-3 sisältää esimerkin, jossa on annotaatioita siitä, missä muuttujat tulevat näkyvyysalueelle ja poistuvat sieltä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-03/src/main.rs}}
}

Jos yrittäisimme käyttää s:tä takes_ownership-kutsun jälkeen, Rust antaisi käännösaikaisen virheen. Nämä staattiset tarkistukset suojaavat meitä virheiltä. Kokeile lisätä main-funktioon koodia, joka käyttää s:tä ja x:ää, nähdäksesi missä voit käyttää niitä ja missä omistajuussäännöt estävät sen.

Paluuarvot ja näkyvyysalue

Paluuarvot voivat myös siirtää omistajuutta. Listaus 4-4 näyttää esimerkin funktiosta, joka palauttaa arvon, samankaltaisilla annotaatioilla kuin Listauksessa 4-3.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-04/src/main.rs}}
}

Muuttujan omistajuus noudattaa samaa kaavaa joka kerta: arvon sijoittaminen toiseen muuttujaan siirtää sen. Kun muuttuja, joka sisältää keon tietoja, poistuu näkyvyysalueelta, drop siivoaa arvon, ellei tietojen omistajuutta ole siirretty toiseen muuttujaan.

Vaikka tämä toimii, omistajuuden ottaminen ja palauttaminen jokaisella funktiolla on hieman työlästä. Entä jos haluamme antaa funktion käyttää arvoa ottamatta omistajuutta? On ärsyttävää, että kaiken mitä välitämme sisään täytyy myös välittää takaisin, jos haluamme käyttää sitä uudelleen, lisäksi mihin tahansa funktion rungosta tulevaan dataan, jonka haluamme ehkä palauttaa.

Rust antaa meidän palauttaa useita arvoja tuplen avulla, kuten Listauksessa 4-5 näytetään.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-05/src/main.rs}}
}

Mutta tämä on liikaa seremoniaa ja työtä käsitteelle, jonka pitäisi olla yleinen. Onneksi Rustissa on ominaisuus arvon käyttämiseen siirtämättä omistajuutta, nimeltä viitteet.

Viitteet ja lainaus

Viittaukset ja lainaaminen

Listauksen 4-5 tuplakoodin ongelma on, että meidän täytyy palauttaa String kutsuvalle funktiolle, jotta voimme edelleen käyttää String-arvoa calculate_length-kutsun jälkeen, koska String siirtyi calculate_length-funktion omistukseen. Sen sijaan voimme tarjota viittauksen String-arvoon. Viittaus on kuin osoitin siinä mielessä, että se on osoite, jota seuraamalla pääsemme kyseiseen osoitteeseen tallennettuun dataan; tämän datan omistaa jokin toinen muuttuja. Toisin kuin osoitin, viittaus on taattu osoittamaan kelvollista tietyn tyyppistä arvoa koko viittauksen eliniän ajan.

Näin määrittelet ja käytät calculate_length-funktiota, joka ottaa viittauksen objektiin parametrinaan omistajuuden siirtämisen sijaan:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-07-reference/src/main.rs:all}}
}

Ensinnäkin huomaa, että kaikki tuplakoodi muuttujan määrityksessä ja funktion paluuarvossa on poissa. Toiseksi huomaa, että välitämme &s1:n calculate_length-funktiolle ja sen määrityksessä otamme &String-tyypin String-tyypin sijaan. Nämä et-merkit edustavat viittauksia, ja niiden avulla voit viitata johonkin arvoon ottamatta sen omistajuutta. Kuva 4-6 havainnollistaa tätä käsitettä.

Kuva 4-6: Kaavio &String-tyypin s:stä, joka osoittaa String-tyypin s1:een

Huom: Viittaamisen vastakohta &-merkillä on dereferointi, joka tehdään dereferointioperaattorilla *. Näemme dereferointioperaattorin käyttöä Luvussa 8 ja käsittelemme dereferoinnin yksityiskohdat Luvussa 15.

Katsotaan funktiokutsua tarkemmin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-07-reference/src/main.rs:here}}
}

&s1-syntaksi antaa meidän luoda viittauksen, joka viittaa s1:n arvoon mutta ei omista sitä. Koska viittaus ei omista sitä, arvoa, johon se osoittaa, ei vapauteta, kun viittaus lakkaa olemasta käytössä.

Samoin funktion signatuuri käyttää &-merkkiä ilmaisemaan, että parametrin s tyyppi on viittaus. Lisätään selittäviä annotaatioita:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-08-reference-with-annotations/src/main.rs:here}}
}

Näkyvyysalue, jolla muuttuja s on kelvollinen, on sama kuin minkä tahansa funktion parametrin näkyvyysalue, mutta viittauksen osoittamaa arvoa ei vapauteta, kun s lakkaa olemasta käytössä, koska s:llä ei ole omistajuutta. Kun funktioilla on viittauksia parametreina todellisten arvojen sijaan, meidän ei tarvitse palauttaa arvoja omistajuuden palauttamiseksi, koska emme koskaan omistaneet niitä.

Kutsumme viittauksen luomista lainaamiseksi. Kuten oikeassa elämässä, jos henkilö omistaa jotain, voit lainata sen häneltä. Kun olet valmis, sinun täytyy palauttaa se. Et omista sitä.

Mitä tapahtuu, jos yritämme muuttaa jotain, mitä lainaamme? Kokeile Listauksen 4-6 koodia. Varoitus: se ei toimi!

{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-06/src/main.rs}}

Tässä on virhe:

{{#include ../listings/ch04-understanding-ownership/listing-04-06/output.txt}}

Aivan kuten muuttujat ovat oletusarvoisesti muuttumattomia, viittauksetkin ovat. Emme saa muuttaa jotain, johon meillä on viittaus.

Muuttuvat viittaukset

Voimme korjata Listauksen 4-6 koodin sallimaan lainatun arvon muuttamisen muutamalla pienellä muutoksella, jotka käyttävät muuttuvaa viittausta:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-09-fixes-listing-04-06/src/main.rs}}
}

Ensin muutamme s:n muotoon mut. Sitten luomme muuttuvan viittauksen &mut s:llä, kun kutsumme change-funktiota, ja päivitämme funktion signatuurin hyväksymään muuttuvan viittauksen some_string: &mut String. Tämä tekee hyvin selväksi, että change-funktio muuttaa lainaamaansa arvoa.

Muuttuvilla viittauksilla on yksi suuri rajoitus: jos sinulla on muuttuva viittaus arvoon, sinulla ei voi olla muita viittauksia kyseiseen arvoon. Tämä koodi, joka yrittää luoda kaksi muuttuvaa viittausta s:ään, epäonnistuu:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-10-multiple-mut-not-allowed/src/main.rs:here}}

Tässä on virhe:

{{#include ../listings/ch04-understanding-ownership/no-listing-10-multiple-mut-not-allowed/output.txt}}

Tämä virheilmoitus sanoo, että koodi on virheellinen, koska emme voi lainata s:ää muuttuvana useammin kuin kerran kerrallaan. Ensimmäinen muuttuva lainaus on r1:ssä ja sen täytyy kestää siihen asti, kunnes sitä käytetään println!:ssä, mutta tuon muuttuvan viittauksen luomisen ja sen käytön välissä yritimme luoda toisen muuttuvan viittauksen r2:ssa, joka lainaa samoja tietoja kuin r1.

Rajoitus, joka estää useita muuttuvia viittauksia samoihin tietoihin samaan aikaan, sallii mutaation, mutta hyvin kontrolloidulla tavalla. Uusien rustilaisien on vaikea tottua siihen, koska useimmat kielet sallivat mutaation milloin tahansa. Tämän rajoituksen hyöty on, että Rust voi estää data race -tilanteet käännösaikana. Data race on samankaltainen kuin kilpailutilanne (race condition), ja se tapahtuu, kun nämä kolme käyttäytymistä esiintyvät:

• Kaksi tai useampi osoitin käyttää samoja tietoja samaan aikaan.
• Vähintään yhtä osoittimista käytetään kirjoittamaan dataan.
• Mitään mekanismia ei käytetä synkronoimaan pääsyä dataan.

Data race -tilanteet aiheuttavat määrittelemätöntä käyttäytymistä, ja niitä voi olla vaikea diagnosoida ja korjata ajonaikana; Rust estää tämän ongelman kieltäytymällä kääntämästä data race -tilanteita sisältävää koodia!

Kuten aina, voimme käyttää aaltosulkeita luodaksemme uuden näkyvyysalueen, mikä sallii useita muuttuvia viittauksia, mutta ei samanaikaisia:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-11-muts-in-separate-scopes/src/main.rs:here}}
}

Rust pakottaa samanlaisen säännön muuttuvien ja muuttumattomien viittausten yhdistämiselle. Tämä koodi johtaa virheeseen:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-12-immutable-and-mutable-not-allowed/src/main.rs:here}}

Tässä on virhe:

{{#include ../listings/ch04-understanding-ownership/no-listing-12-immutable-and-mutable-not-allowed/output.txt}}

Huh! Emme myöskään voi omistaa muuttuvaa viittausta, kun meillä on muuttumaton viittaus samaan arvoon.

Muuttumattoman viittauksen käyttäjät eivät odota arvon muuttuvan yllättäen altaan! Useita muuttumattomia viittauksia sallitaan kuitenkin, koska kukaan, joka vain lukee dataa, ei voi vaikuttaa kenenkään muun datan lukemiseen.

Huomaa, että viittauksen näkyvyysalue alkaa siitä, missä se esitellään, ja jatkuu viimeiseen kertaan, jolloin viittausta käytetään. Esimerkiksi tämä koodi kääntyy, koska muuttumattomien viittausten viimeinen käyttö on println!:ssä, ennen kuin muuttuva viittaus esitellään:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-13-reference-scope-ends/src/main.rs:here}}
}

Muuttumattomien viittausten r1:n ja r2:n näkyvyysalueet päättyvät println!:n jälkeen, missä niitä käytetään viimeisen kerran, eli ennen kuin muuttuva viittaus r3 luodaan. Nämä näkyvyysalueet eivät limitty, joten tämä koodi on sallittu: kääntäjä voi päätellä, ettei viittausta enää käytetä ennen näkyvyysalueen päättymistä.

Vaikka lainausvirheet voivat joskus turhauttaa, muista, että Rust-kääntäjä osoittaa mahdollisen bugin varhain (käännösaikana ajonaikaisen sijaan) ja näyttää tarkalleen, missä ongelma on. Sinun ei sitten tarvitse selvittää, miksi datasi ei ole sitä, mitä luulit sen olevan.

Riippuvat viittaukset

Kielissä, joissa on osoittimia, on helppo luoda virheellisesti riippuvan osoittimen — osoittimen, joka viittaa muistipaikkaan, joka on saatettu antaa jollekulle muulle — vapauttamalla muistia mutta säilyttämällä osoitin kyseiseen muistiin. Rustissa kääntäjä puolestaan takaa, ettei viittauksia koskaan ole riippuvia: jos sinulla on viittaus johonkin dataan, kääntäjä varmistaa, ettei data poistu näkyvyysalueelta ennen kuin viittaus siihen poistuu.

Yritetään luoda riippuva viittaus nähdäksemme, miten Rust estää ne käännösaikaisella virheellä:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-14-dangling-reference/src/main.rs}}

Tässä on virhe:

{{#include ../listings/ch04-understanding-ownership/no-listing-14-dangling-reference/output.txt}}

Tämä virheilmoitus viittaa ominaisuuteen, jota emme ole vielä käsitelleet: elinikäihin. Käsittelemme elinikäitä yksityiskohtaisesti Luvussa 10. Mutta jos sivuutat elinikäisiin liittyvät osat, viesti sisältää avaimen siihen, miksi tämä koodi on ongelma:

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

Katsotaan tarkemmin, mitä tapahtuu dangle-koodimme jokaisessa vaiheessa:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-15-dangling-reference-annotated/src/main.rs:here}}

Koska s luodaan dangle-funktion sisällä, kun dangle-funktion koodi on valmis, s vapautetaan. Mutta yritimme palauttaa viittauksen siihen. Tämä tarkoittaa, että viittaus osoittaisi virheelliseen String-arvoon. Se ei käy! Rust ei anna meidän tehdä tätä.

Ratkaisu on palauttaa String suoraan:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-16-no-dangle/src/main.rs:here}}
}

Tämä toimii ilman ongelmia. Omistajuus siirtyy ulos, eikä mitään vapauteta.

Viittausten säännöt

Kerrataan, mitä olemme käsitelleet viittauksista:

• Milloin tahansa voit omistaa joko yhden muuttuvan viittauksen tai minkä tahansa määrän muuttumattomia viittauksia.
• Viittausten on aina oltava kelvollisia.

Seuraavaksi tarkastelemme erilaista viittaustyyppiä: sliceja.

Viipale-tyyppi

Slice-tyyppi

Slicet antavat sinun viitata kokoelman peräkkäiseen elementtijaksoon koko kokoelman sijaan. Slice on eräänlainen viite, joten sillä ei ole omistajuutta.

Tässä on pieni ohjelmointiongelma: kirjoita funktio, joka ottaa välilyönneillä erotetun merkkijonon sanoja ja palauttaa ensimmäisen sanan, jonka se löytää kyseisestä merkkijonosta. Jos funktio ei löydä välilyöntiä merkkijonosta, koko merkkijonon täytyy olla yksi sana, joten koko merkkijono pitäisi palauttaa.

Käydään läpi, miten kirjoittaisimme tämän funktion signatuurin käyttämättä sliceja, jotta ymmärrämme ongelman, jonka slicet ratkaisevat:

fn first_word(s: &String) -> ?

first_word-funktiolla on parametrina &String. Emme tarvitse omistajuutta, joten tämä on hyvä. (Idiomatiisessa Rustissa funktiot eivät ota omistajuutta argumenteistaan, elleivät sitä tarvitse, ja syyt siihen selviävät selväksi jatkaessamme!) Mutta mitä meidän pitäisi palauttaa? Meillä ei oikeastaan ole tapaa puhua merkkijonon osasta. Voisimme kuitenkin palauttaa sanan lopun indeksin, jonka ilmaisee välilyönti. Kokeillaan sitä, kuten Listauksessa 4-7.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:here}}
}

Koska meidän täytyy käydä String läpi elementti kerrallaan ja tarkistaa, onko arvo välilyönti, muunnamme String-mme tavutaulukoksi käyttämällä as_bytes-metodia.

{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:as_bytes}}

Seuraavaksi luomme iteraattorin tavutaulukon yli käyttämällä iter-metodia:

{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:iter}}

Käsittelemme iteraattoreita yksityiskohtaisemmin Luvussa 13. Toistaiseksi tiedä, että iter on metodi, joka palauttaa jokaisen elementin kokoelmassa ja että enumerate käärii iter-metodin tuloksen ja palauttaa jokaisen elementin osana monikkoa sen sijaan. Monikon ensimmäinen elementti, jonka enumerate palauttaa, on indeksi, ja toinen elementti on viite elementtiin. Tämä on hieman kätevämpää kuin indeksin laskeminen itse.

Koska enumerate-metodi palauttaa monikon, voimme käyttää kuvioita purkamaan tuon monikon. Käsittelemme kuvioita lisää Luvussa 6. for-silmukassa määritämme kuvion, jossa on i monikon indeksille ja &item monikon yksittäiselle tavulle. Koska saamme viitteen elementtiin .iter().enumerate()-ketjusta, käytämme kuviossa &-merkkiä.

for-silmukan sisällä etsimme välilyöntiä edustavaa tavua käyttämällä tavuliteraalisyntaksia. Jos löydämme välilyönnin, palautamme sijainnin. Muuten palautamme merkkijonon pituuden käyttämällä s.len().

{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:inside_for}}

Meillä on nyt tapa selvittää ensimmäisen sanan lopun indeksi merkkijonossa, mutta on ongelma. Palautamme usize-arvon yksinään, mutta se on merkityksellinen luku vain &String-kontekstissa. Toisin sanoen, koska se on erillinen arvo String-arvosta, ei ole mitään takeita siitä, että se olisi edelleen kelvollinen tulevaisuudessa. Harkitse Listauksen 4-8 ohjelmaa, joka käyttää Listauksen 4-7 first_word-funktiota.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-08/src/main.rs:here}}
}

Tämä ohjelma kääntyy ilman virheitä ja tekisi niin myös, jos käyttäisimme word-muuttujaa s.clear()-kutsun jälkeen. Koska word ei ole lainkaan yhteydessä s-muuttujan tilaan, word sisältää edelleen arvon 5. Voisimme käyttää arvoa 5 muuttujan s kanssa yrittääksemme poimia ensimmäisen sanan, mutta tämä olisi bugi, koska s-muuttujan sisältö on muuttunut siitä, kun tallensimme arvon 5 muuttujaan word.

Huolehtiminen siitä, että word-muuttujan indeksi menee epäsynkkaan s-muuttujan datan kanssa, on työlästä ja virhealtista! Näiden indeksien hallinta on vieläkin hauraampaa, jos kirjoitamme second_word-funktion. Sen signatuurin pitäisi näyttää tältä:

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

Nyt seuraamme sekä aloitus- että lopetusindeksiä, ja meillä on vielä enemmän arvoja, jotka laskettiin tietyn tilan datasta mutta eivät ole lainkaan sidottuja siihen tilaan. Meillä on kolme toisiinsa liittymätöntä muuttujaa, jotka täytyy pitää synkassa.

Onneksi Rustilla on ratkaisu tähän ongelmaan: merkkijonoslicet.

Merkkijonoslicet

Merkkijonoslice on viite String-arvon osaan, ja se näyttää tältä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-17-slice/src/main.rs:here}}
}

Sen sijaan, että viittaisimme koko String-arvoon, hello on viite String-arvon osaan, joka määritellään ylimääräisessä [0..5]-osassa. Luomme slicet käyttämällä hakasulkeissa olevaa väliä määrittämällä [aloitusindeksi..lopetusindeksi], missä aloitusindeksi on slicen ensimmäinen sijainti ja lopetusindeksi on yksi enemmän kuin slicen viimeinen sijainti. Sisäisesti slice-tietorakenne tallentaa aloitussijainnin ja slicen pituuden, joka vastaa arvoa lopetusindeksi miinus aloitusindeksi. Eli tapauksessa let world = &s[6..11]; world olisi slice, joka sisältää osoittimen s-arvon indeksin 6 tavuun pituusarvolla 5.

Kuva 4-7 näyttää tämän kaaviona.

Kuva 4-7: Merkkijonoslice viittaa osaan String-arvosta

Rustin ..-välisyntaksilla, jos haluat aloittaa indeksistä 0, voit jättää pois arvon kahden pisteen edestä. Toisin sanoen, nämä ovat yhtä suuret:

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

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

Samoin, jos sliceesi sisältää String-arvon viimeisen tavun, voit jättää pois loppunumeron. Tämä tarkoittaa, että nämä ovat yhtä suuret:

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

let len = s.len();

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

Voit myös jättää pois molemmat arvot ottaaksesi slicen koko merkkijonosta. Eli nämä ovat yhtä suuret:

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

let len = s.len();

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

Huom: Merkkijonoslicen väli-indeksien täytyy olla kelvollisilla UTF-8-merkki rajoilla. Jos yrität luoda merkkijonoslicen monitavuisen merkin keskeltä, ohjelmasi päättyy virheeseen. Merkkijonoslicien esittelyä varten oletamme tässä osiossa vain ASCII-merkkejä; UTF-8-käsittelyn tarkempi käsittely on Luvun 8 osiossa “UTF-8-koodatun tekstin tallentaminen merkkijonoilla”.

Kaiken tämän tiedon valossa kirjoitetaan first_word uudelleen palauttamaan slice. Tyyppi, joka merkitsee “merkkijonoslicea”, kirjoitetaan muodossa &str:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-18-first-word-slice/src/main.rs:here}}
}

Saamme sanan lopun indeksin samalla tavalla kuin Listauksessa 4-7, etsimällä ensimmäisen välilyönnin esiintymän. Kun löydämme välilyönnin, palautamme merkkijonoslicen käyttämällä merkkijonon alkua ja välilyönnin indeksiä aloitus- ja lopetusindekseinä.

Nyt kun kutsumme first_word-funktiota, saamme takaisin yhden arvon, joka on sidottu taustalla olevaan dataan. Arvo koostuu viitteestä slicen aloituspisteeseen ja slicen elementtien määrästä.

Slicen palauttaminen toimisi myös second_word-funktiolle:

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

Meillä on nyt suoraviivainen API, jota on paljon vaikeampi sotkea, koska kääntäjä varmistaa, että String-arvoon tehdyt viitteet pysyvät kelvollisina. Muista bugi Listauksen 4-8 ohjelmassa, kun saimme ensimmäisen sanan lopun indeksin mutta sitten tyhjensimme merkkijonon, jolloin indeksimme oli virheellinen? Tuo koodi oli loogisesti virheellinen, mutta se ei näyttänyt välittömiä virheitä. Ongelmat ilmaantuisivat myöhemmin, jos jatkaisimme ensimmäisen sanan indeksin käyttöä tyhjän merkkijonon kanssa. Slicet tekevät tästä bugista mahdottoman ja kertovat meille ongelmasta koodissamme paljon aikaisemmin. first_word-funktion slice-version käyttö aiheuttaa käännösajan virheen:

{{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-19-slice-error/src/main.rs:here}}

Tässä on kääntäjän virhe:

{{#include ../listings/ch04-understanding-ownership/no-listing-19-slice-error/output.txt}}

Muista lainausperiaatteista, että jos meillä on muuttumaton viite johonkin, emme voi myöskään ottaa muuttuvaa viitettä. Koska clear täytyy katkaista String, sen täytyy saada muuttuva viite. clear-kutsun jälkeinen println! käyttää viitettä muuttujassa word, joten muuttumattoman viitteen täytyy olla edelleen aktiivinen tuossa vaiheessa. Rust estää muuttuvan viitteen clear-funktiossa ja muuttumattoman viitteen muuttujassa word olemasta samaan aikaan, ja käännös epäonnistuu. Rust ei ole ainoastaan tehnyt API:stamme helpomman käyttää, vaan se on myös poistanut kokonaisen virheluokan käännösaikana!

Merkkijonoliteraalit sliceina

Muista, että puhuimme merkkijonoliteraalien tallentumisesta binääritiedostoon. Nyt kun tiedämme sliceista, voimme ymmärtää merkkijonoliteraalit oikein:

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

Tässä s-muuttujan tyyppi on &str: se on slice, joka osoittaa kyseiseen kohtaan binääritiedostossa. Tämän takia merkkijonoliteraalit ovat myös muuttumattomia; &str on muuttumaton viite.

Merkkijonoslicet parametreina

Tieto siitä, että voit ottaa sliceja literaaleista ja String-arvoista, johtaa meidät vielä yhteen parannukseen first_word-funktioon, ja se on sen signatuuri:

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

Kokeneempi rustilainen kirjoittaisi Listauksessa 4-9 näytetyn signatuurin sen sijaan, koska se antaa meille mahdollisuuden käyttää samaa funktiota sekä &String- että &str-arvoilla.

{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-09/src/main.rs:here}}

Jos meillä on merkkijonoslice, voimme välittää sen suoraan. Jos meillä on String, voimme välittää slicen String-arvosta tai viitteen String-arvoon. Tämä joustavuus hyödyntää deref-pakotuksia, ominaisuutta, jota käsittelemme Luvun 15 osiossa “Implisiittiset deref-pakotukset funktioiden ja metodien kanssa”.

Funktion määrittely ottamaan merkkijonoslice String-viitteen sijaan tekee API:stamme yleisemmän ja hyödyllisemmän menettämättä mitään toiminnallisuutta:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-09/src/main.rs:usage}}
}

Muut slicet

Merkkijonoslicet, kuten saatat kuvitella, ovat merkkijonoihin erityisiä. Mutta on olemassa yleisempikin slice-tyyppi. Harkitse tätä taulukkoa:

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

Aivan kuten saatamme haluta viitata osaan merkkijonosta, saatamme haluta viitata osaan taulukosta. Teemme sen näin:

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

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

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

Tällä slicellä on tyyppi &[i32]. Se toimii samalla tavalla kuin merkkijonoslicet, tallentamalla viitteen ensimmäiseen elementtiin ja pituuden. Käytät tämänlaista slicea kaikenlaisissa muissa kokoelmissa. Käsittelemme näitä kokoelmia yksityiskohtaisesti, kun puhumme vektoreista Luvussa 8.

Yhteenveto

Omistajuuden, lainauksen ja slicejen käsitteet varmistavat muistiturvallisuuden Rust- ohjelmissa käännösaikana. Rust-kieli antaa sinulle hallinnan muistin käytöstä samalla tavalla kuin muut järjestelmäohjelmointikielet, mutta se, että datan omistaja siivoaa automaattisesti datan, kun omistaja poistuu näkyvyysalueelta, tarkoittaa, että sinun ei tarvitse kirjoittaa ja debugata ylimääräistä koodia saadaksesi tämän hallinnan.

Omistajuus vaikuttaa siihen, miten monet muut Rustin osat toimivat, joten puhumme näistä käsitteistä lisää koko kirjan ajan. Siirrytään Lukuun 5 ja katsotaan, miten datan osia ryhmitellään yhteen struct-rakenteessa.

Rakenteiden (Structs) käyttö tietojen ryhmittelyyn

Rakenne (struct) on mukautettu tietotyyppi, jonka avulla voit paketoida yhteen ja nimetä useita toisiinsa liittyviä arvoja, jotka muodostavat merkityksellisen kokonaisuuden. Jos olet tuttu oliopohjaisista kielistä, struct vastaa olion tietokenttiä. Tässä luvussa vertailemme tuplia ja rakenteita syventäen aiempaa osaamistasi ja osoitamme, milloin rakenteet ovat parempi tapa ryhmitellä tietoa.

Käymme läpi, miten määritellään ja luodaan rakenteita. Lisäksi käsittelemme, kuinka määritellä rakenteeseen liittyviä funktioita, erityisesti metodeja, joiden avulla voidaan määrittää rakenteeseen liittyvää toimintaa. Rakenteet ja luettelotyypit (enums, käsitellään luvussa 6) ovat keskeisiä rakennuspalikoita, joilla voit luoda uusia tyyppejä ohjelmasi sovellusalueelle ja hyödyntää Rustin käännösaikaista tyyppitarkistusta mahdollisimman tehokkaasti.

Rakenteiden määrittäminen ja instanssien luominen

Rakenteiden määrittely ja instanssien luominen

Rakenteet ovat samankaltaisia kuin tuplat, joita käsiteltiin ”Tuplatyyppi” -osiossa, siinä mielessä, että molemmat pitävät useita toisiinsa liittyviä arvoja. Kuten tuplissa, rakenteen osat voivat olla eri tyyppejä. Toisin kuin tuplissa, rakenteessa nimeät jokaisen datan osan, jotta arvojen merkitys on selvä. Näiden nimien lisääminen tarkoittaa, että rakenteet ovat joustavampia kuin tuplat: sinun ei tarvitse luottaa datan järjestykseen määrittääksesi tai käyttääksesi instanssin arvoja.

Määrittääksesi rakenteen, kirjoitat avainsanan struct ja nimeät koko rakenteen. Rakenteen nimen pitäisi kuvata yhdessä ryhmiteltyjen datan osien merkitystä. Sitten aaltosulkeiden sisällä määrittelemme datan osien nimet ja tyypit, joita kutsumme kentiksi. Esimerkiksi Listausta 5-1 näyttää rakenteen, joka tallentaa tietoja käyttäjätilistä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-01/src/main.rs:here}}
}

Käyttääksemme rakennetta sen määrittelyn jälkeen, luomme kyseisen rakenteen instanssin määrittämällä konkreettiset arvot jokaiselle kentälle. Luomme instanssin ilmoittamalla rakenteen nimen ja lisäämällä aaltosulkeet, jotka sisältävät avain: arvo -pareja, joissa avaimet ovat kenttien nimiä ja arvot ovat dataa, jonka haluamme tallentaa näihin kenttiin. Emme tarvitse määrittää kenttiä samassa järjestyksessä, jossa ilmoitimme ne rakenteessa. Toisin sanoen rakenteen määrittely on kuin yleinen malli tyypille, ja instanssit täyttävät mallin tietyllä datalla luodakseen tyypin arvoja. Esimerkiksi voimme ilmoittaa tietyn käyttäjän kuten Listauksessa 5-2 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-02/src/main.rs:here}}
}

Saadaksemme tietyn arvon rakenteesta, käytämme pistesyntaksia. Esimerkiksi käyttääksemme tämän käyttäjän sähköpostiosoitetta, käytämme user1.email. Jos instanssi on muuttuva, voimme muuttaa arvoa käyttämällä pistesyntaksia ja sijoittamalla tiettyyn kenttään. Listausta 5-3 näyttää, miten muutetaan email-kentän arvoa muuttuvassa User-instanssissa.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-03/src/main.rs:here}}
}

Huomaa, että koko instanssin täytyy olla muuttuva; Rust ei salli meidän merkitä vain tiettyjä kenttiä muuttuviksi. Kuten minkä tahansa lausekkeen kanssa, voimme rakentaa uuden instanssin rakenteesta funktion rungon viimeisenä lausekkeena palauttaaksemme implisiittisesti kyseisen uuden instanssin.

Listausta 5-4 näyttää build_user-funktion, joka palauttaa User-instanssin annetulla sähköpostilla ja käyttäjänimellä. active-kenttä saa arvon true, ja sign_in_count saa arvon 1.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-04/src/main.rs:here}}
}

On järkevää nimetä funktion parametrit samalla nimellä kuin rakenteen kentät, mutta email- ja username-kenttien ja -muuttujien toistaminen on hieman työlästä. Jos rakenteella olisi enemmän kenttiä, jokaisen nimen toistaminen olisi vieläkin ärsyttävämpää. Onneksi on kätevä lyhenne!

Kentän alustuksen lyhenteen käyttö

Koska parametrien nimet ja rakenteen kenttien nimet ovat täsmälleen samat Listauksessa 5-4, voimme käyttää kentän alustuksen lyhenne-syntaksia kirjoittaaksemme build_user-funktion uudelleen niin, että se käyttäytyy täsmälleen samalla tavalla, mutta ilman username- ja email-toistoa, kuten Listauksessa 5-5 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-05/src/main.rs:here}}
}

Tässä luomme uuden User-rakenteen instanssin, jolla on kenttä nimeltä email. Haluamme asettaa email-kentän arvoksi build_user-funktion email-parametrin arvon. Koska email-kentällä ja email-parametrilla on sama nimi, meidän tarvitsee kirjoittaa vain email eikä email: email.

Instanssien luominen toisista instansseista rakenteen päivityssyntaksilla

On usein hyödyllistä luoda uusi instanssi rakenteesta, joka sisältää suurimman osan arvoista toisesta instanssista, mutta muuttaa joitakin. Voit tehdä tämän käyttämällä rakenteen päivityssyntaksia.

Ensin Listauksessa 5-6 näytämme, miten luodaan uusi User-instanssi user2:ssa tavallisesti ilman päivityssyntaksia. Asetamme uuden arvon email-kentälle, mutta käytämme muuten samoja arvoja user1:stä, jonka loimme Listauksessa 5-2.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-06/src/main.rs:here}}
}

Käyttämällä rakenteen päivityssyntaksia voimme saavuttaa saman vaikutuksen vähemmällä koodilla, kuten Listauksessa 5-7 on esitetty. ..-syntaksi määrittää, että jäljellä olevilla kentillä, joita ei ole eksplisiittisesti asetettu, pitäisi olla sama arvo kuin annetun instanssin kentillä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-07/src/main.rs:here}}
}

Listauksen 5-7 koodi luo myös instanssin user2:ssa, jolla on eri arvo email-kentälle, mutta samat arvot username-, active- ja sign_in_count-kentille user1:stä. ..user1 täytyy tulla viimeisenä määrittämään, että jäljellä olevat kentät saavat arvonsa user1:n vastaavista kentistä, mutta voimme valita määrittää arvoja niin monelle kentälle kuin haluamme missä tahansa järjestyksessä riippumatta kenttien järjestyksestä rakenteen määrittelyssä.

Huomaa, että rakenteen päivityssyntaksi käyttää =-merkkiä kuten sijoituslauseke; tämä johtuu siitä, että se siirtää datan, kuten näimme ”Muuttujat ja data vuorovaikutuksessa siirron kanssa” -osiossa. Tässä esimerkissä emme voi enää käyttää user1:tä user2:n luomisen jälkeen, koska user1:n username-kentän String siirrettiin user2:een. Jos olisimme antaneet user2:lle uudet String-arvot sekä email- että username-kentille, ja siten käyttäneet vain active- ja sign_in_count-arvoja user1:stä, user1 olisi edelleen kelvollinen user2:n luomisen jälkeen. Sekä active että sign_in_count ovat tyyppejä, jotka toteuttavat Copy-traitin, joten ”Vain pinossa oleva data: Copy” -osiossa käsittelemämme käyttäytyminen pätee. Voimme edelleen käyttää user1.email tässä esimerkissä, koska sen arvoa ei siirretty pois.

Tuple-rakenteiden käyttö nimeämättömillä kentillä eri tyyppien luomiseksi

Rust tukee myös rakenteita, jotka näyttävät samankaltaisilta kuin tuplat, ja joita kutsutaan tuple-rakenteiksi. Tuple-rakenteilla on rakenteen nimen tuoma lisämerkitys, mutta niillä ei ole nimiä liitettynä kenttiinsä; niillä on vain kenttien tyypit. Tuple-rakenteet ovat hyödyllisiä, kun haluat antaa koko tuplalle nimen ja tehdä tuplasta eri tyypin kuin muista tuplista, ja kun jokaisen kentän nimeäminen kuten tavallisessa rakenteessa olisi puhelias tai tarpeeton.

Määrittääksesi tuple-rakenteen, aloita struct-avainsanalla ja rakenteen nimellä, jota seuraa tuplan tyypit. Esimerkiksi tässä määrittelemme ja käytämme kahta tuple-rakennetta nimeltä Color ja Point:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-01-tuple-structs/src/main.rs}}
}

Huomaa, että black- ja origin-arvot ovat eri tyyppejä, koska ne ovat eri tuple-rakenteiden instansseja. Jokainen määrittelemäsi rakenne on oma tyypinsä, vaikka rakenteen kentät saattaisivat olla samoja tyyppejä. Esimerkiksi funktio, joka ottaa parametrin tyypillä Color, ei voi ottaa Point-argumenttia, vaikka molemmat tyypit koostuvat kolmesta i32-arvosta. Muuten tuple-rakenneinstanssit ovat samankaltaisia kuin tuplat siinä mielessä, että voit purkaa ne yksittäisiin osiinsa, ja voit käyttää .-merkkiä, jota seuraa indeksi, päästäksesi yksittäiseen arvoon. Toisin kuin tuplat, tuple-rakenteet vaativat sinua nimeämään rakenteen tyypin, kun purat ne. Esimerkiksi kirjoittaisimme let Point(x, y, z) = point.

Yksikkömäiset rakenteet ilman kenttiä

Voit myös määritellä rakenteita, joilla ei ole lainkaan kenttiä! Näitä kutsutaan yksikkömäisiksi rakenteiksi, koska ne käyttäytyvät samankaltaisesti kuin (), yksikkötyyppi, josta mainitsimme ”Tuplatyyppi” -osiossa. Yksikkömäiset rakenteet voivat olla hyödyllisiä, kun sinun täytyy toteuttaa trait jollekin tyypille, mutta sinulla ei ole dataa, jonka haluaisit tallentaa itse tyyppiin. Käsittelemme traitteja Luvussa 10. Tässä on esimerkki yksikkörakenteen nimeltä AlwaysEqual ilmoittamisesta ja instanssin luomisesta:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-04-unit-like-structs/src/main.rs}}
}

Määrittääksemme AlwaysEqual:in, käytämme struct-avainsanaa, haluamaamme nimeä ja sitten puolipistettä. Ei tarvetta aaltosulkeille tai sulkeille! Sitten voimme saada AlwaysEqual-instanssin subject-muuttujaan samalla tavalla: käyttämällä määrittelemäämme nimeä ilman aaltosulkeita tai sulkeita. Kuvittele, että myöhemmin toteutamme käyttäytymistä tälle tyypille siten, että jokainen AlwaysEqual-instanssi on aina yhtä suuri kuin minkä tahansa muun tyypin instanssi, ehkä testaustarkoituksiin tunnetun tuloksen saamiseksi. Emme tarvitsisi dataa toteuttaaksemme tuota käyttäytymistä! Näet Luvussa 10, miten määritellä traitteja ja toteuttaa ne mille tahansa tyypille, mukaan lukien yksikkömäiset rakenteet.

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

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

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

Esimerkkiohjelma rakenteiden käytöstä

Esimerkkiohjelma, joka käyttää rakenteita

Ymmärtääksemme, milloin rakenteita kannattaa käyttää, kirjoitamme ohjelman, joka laskee suorakulmion pinta-alan. Aloitamme käyttämällä yksittäisiä muuttujia ja refaktoroimme ohjelman vähitellen niin, että käytämme rakenteita.

Tehdään uusi binääriprojekti Cargo-ohjelmalla nimeltä rectangles, joka ottaa suorakulmion leveyden ja korkeuden pikseleinä ja laskee suorakulmion pinta-alan. Listausta 5-8 näyttää lyhyen ohjelman, joka tekee juuri tämän projektimme src/main.rs-tiedostossa.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-08/src/main.rs:all}}
}

Aja ohjelma komennolla cargo run:

{{#include ../listings/ch05-using-structs-to-structure-related-data/listing-05-08/output.txt}}

Tämä koodi onnistuu laskemaan suorakulmion pinta-alan kutsumalla area-funktiota kummallakin mitalla, mutta voimme tehdä koodista selkeämmän ja luettavamman.

Ongelma tässä koodissa näkyy area-funktion signatuurissa:

{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-08/src/main.rs:here}}

area-funktion pitäisi laskea yhden suorakulmion pinta-ala, mutta kirjoittamassamme funktiossa on kaksi parametria, eikä ohjelmassamme ole missään selvää, että parametrit liittyvät toisiinsa. Olisi luettavampaa ja hallittavampaa ryhmitellä leveys ja korkeus yhteen. Olemme jo käsitelleet yhden tavan tehdä tämä Luvun 3 ”Tuplatyyppi” -osiossa: käyttämällä tuplia.

Refaktorointi tuplilla

Listausta 5-9 näyttää toisen version ohjelmastamme, joka käyttää tuplia.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-09/src/main.rs}}
}

Eräästä näkökulmasta tämä ohjelma on parempi. Tuplat antavat lisätä hieman rakennetta, ja välitämme nyt vain yhden argumentin. Mutta toisesta näkökulmasta tämä versio on epäselvempi: tuplat eivät nimeä elementtejään, joten meidän täytyy indeksoida tuplan osia, mikä tekee laskennastamme vähemmän ilmeistä.

Leveyden ja korkeuden sekoittaminen ei vaikuttaisi pinta-alan laskentaan, mutta jos haluaisimme piirtää suorakulmion ruudulle, se vaikuttaisi! Meidän piti muistaa, että width on tuplan indeksi 0 ja height on tuplan indeksi 1. Tämä olisi vielä vaikeampaa jollekin muulle selvittää ja muistaa, jos hän käyttäisi koodiamme. Koska emme välittäneet datamme merkitystä koodissamme, virheiden tekeminen on nyt helpompaa.

Refaktorointi rakenteilla

Käytämme rakenteita lisätäksemme merkitystä nimeämällä datan. Voimme muuntaa käyttämämme tuplan rakenteeksi, jolla on nimi kokonaisuudelle sekä nimet osille, kuten Listauksessa 5-10 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-10/src/main.rs}}
}

Tässä olemme määritelleet rakenteen ja nimenneet sen Rectangle. Aaltosulkeiden sisällä määritimme kentät width ja height, joilla molemmilla on tyyppi u32. Sitten main-funktiossa loimme tietyn Rectangle-instanssin, jonka leveys on 30 ja korkeus 50.

area-funktiomme on nyt määritelty yhdellä parametrilla, jonka olemme nimenneet rectangle ja jonka tyyppi on Rectangle-rakenteen instanssin muuttumaton lainaus. Kuten mainittiin Luvussa 4, haluamme lainata rakenteen omistajuuden siirtämisen sijaan. Näin main säilyttää omistajuutensa ja voi jatkaa rect1:n käyttöä, minkä vuoksi käytämme &-merkkiä funktion signatuurissa ja funktiokutsussa.

area-funktio käyttää Rectangle-instanssin width- ja height-kenttiä (huomaa, että lainatun rakenteen instanssin kenttien käyttö ei siirrä kenttien arvoja, minkä vuoksi näet usein rakenteiden lainauksia). area-funktion signatuuri sanoo nyt täsmälleen, mitä tarkoitamme: laske Rectangle-rakenteen pinta-ala käyttämällä sen width- ja height-kenttiä. Tämä välittää, että leveys ja korkeus liittyvät toisiinsa, ja antaa kuvaavat nimet arvoille tuplan indeksiarvojen 0 ja 1 sijaan. Tämä on selkeyden voitto.

Toiminnallisuuden lisääminen johdettavilla traitteilla

Olisi hyödyllistä pystyä tulostamaan Rectangle-instanssi debugatessamme ohjelmaamme ja näkemään kaikkien sen kenttien arvot. Listausta 5-11 yrittää käyttää println!-makroa kuten aiemmissa luvuissa. Tämä ei kuitenkaan toimi.

{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-11/src/main.rs}}

Kun käännämme tämän koodin, saamme virheen, jonka ydinviesti on:

{{#include ../listings/ch05-using-structs-to-structure-related-data/listing-05-11/output.txt:3}}

println!-makro voi tehdä monenlaista muotoilua, ja oletusarvoisesti aaltosulkeet kertovat println!:lle käyttämään Display-nimistä muotoilua: tulostusta, joka on tarkoitettu suoraan loppukäyttäjälle. Tähän mennessä näkemämme primitiivityypit toteuttavat Display-traitin oletusarvoisesti, koska on vain yksi tapa näyttää 1 tai mikä tahansa muu primitiivityyppi käyttäjälle. Mutta rakenteiden kohdalla se, miten println!:n pitäisi muotoilla tuloste, on vähemmän selvä, koska näyttömahdollisuuksia on enemmän: haluatko pilkkuja vai et? Haluatko tulostaa aaltosulkeet? Pitäisikö kaikki kentät näyttää? Tämän epäselvyyden vuoksi Rust ei yritä arvata, mitä haluamme, eikä rakenteilla ole valmista Display-toteutusta käytettäväksi println!:n ja {}-paikkamerkin kanssa.

Jos jatkamme virheilmoitusten lukemista, löydämme tämän hyödyllisen huomautuksen:

{{#include ../listings/ch05-using-structs-to-structure-related-data/listing-05-11/output.txt:9:10}}

Kokeillaan! println!-makrokutsu näyttää nyt tältä: println!("rect1 is {rect1:?}");. Määritteen :? laittaminen aaltosulkeiden sisään kertoo println!:lle, että haluamme käyttää Debug-nimistä tulostusmuotoa. Debug-traitin avulla voimme tulostaa rakenteemme tavalla, joka on hyödyllinen kehittäjille, jotta näemme sen arvon debugatessamme koodiamme.

Käännä koodi tällä muutoksella. Pah! Saamme silti virheen:

{{#include ../listings/ch05-using-structs-to-structure-related-data/output-only-01-debug/output.txt:3}}

Mutta kääntäjä antaa taas hyödyllisen huomautuksen:

{{#include ../listings/ch05-using-structs-to-structure-related-data/output-only-01-debug/output.txt:9:10}}

Rust sisältää toiminnallisuuden debug-tietojen tulostamiseen, mutta meidän täytyy erikseen valita se käyttöön rakenteellemme. Teemme sen lisäämällä ulkoisen attribuutin #[derive(Debug)] juuri ennen rakenteen määrittelyä, kuten Listauksessa 5-12 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-12/src/main.rs}}
}

Nyt kun ajamme ohjelman, emme saa virheitä ja näemme seuraavan tulosteen:

{{#include ../listings/ch05-using-structs-to-structure-related-data/listing-05-12/output.txt}}

Hienoa! Tuloste ei ole kaunein mahdollinen, mutta se näyttää kaikkien tämän instanssin kenttien arvot, mikä auttaisi varmasti debuggauksessa. Kun meillä on suurempia rakenteita, on hyödyllistä saada hieman helpommin luettava tuloste; näissä tapauksissa voimme käyttää {:#?} muodon {:?} sijaan println!-merkkijonossa. Tässä esimerkissä {:#?}-tyyli tuottaa seuraavan tulosteen:

{{#include ../listings/ch05-using-structs-to-structure-related-data/output-only-02-pretty-debug/output.txt}}

Toinen tapa tulostaa arvo Debug-muodossa on käyttää dbg!-makroa, joka ottaa omistajuuden lausekkeesta (toisin kuin println!, joka ottaa viittauksen), tulostaa tiedoston ja rivinumeron, jossa dbg!-makrokutsu tapahtuu koodissasi, sekä kyseisen lausekkeen tulosarvon, ja palauttaa lausekkeen omistajuuden.

Huom: dbg!-makrokutsu tulostaa vakiovirhevirtaan (stderr), toisin kuin println!, joka tulostaa vakiotulostusvirtaan (stdout). Puhumme stderr:stä ja stdout:sta lisää Luvun 12 osiossa ”Virheiden ohjaaminen vakiovirheeseen”.

Tässä on esimerkki, jossa olemme kiinnostuneita arvosta, joka sijoitetaan width-kenttään, sekä koko rakenteen arvosta rect1:ssä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-05-dbg-macro/src/main.rs}}
}

Voimme laittaa dbg!:n lausekkeen 30 * scale ympärille, ja koska dbg! palauttaa lausekkeen arvon omistajuuden, width-kenttä saa saman arvon kuin ilman dbg!-kutsua. Emme halua dbg!:n ottavan rect1:n omistajuutta, joten käytämme viittausta rect1:een seuraavassa kutsussa. Tässä on tämän esimerkin tuloste:

{{#include ../listings/ch05-using-structs-to-structure-related-data/no-listing-05-dbg-macro/output.txt}}

Näemme, että ensimmäinen tuloste tuli src/main.rs-tiedoston riviltä 10, jossa debuggaamme lauseketta 30 * scale, ja sen tulosarvo on 60 (Debug-muotoilu kokonaisluvuille tulostaa vain niiden arvon). dbg!-kutsu src/main.rs-tiedoston rivillä 14 tulostaa arvon &rect1, joka on Rectangle-rakenne. Tämä tuloste käyttää Rectangle-tyypin siistiä Debug-muotoilua. dbg!-makro voi olla todella hyödyllinen selvittäessäsi, mitä koodisi tekee!

Debug-traitin lisäksi Rust on tarjonnut joukon traitteja, joita voimme käyttää derive-attribuutin kanssa lisätäksemme hyödyllistä käyttäytymistä mukautetuille tyypeillemme. Nämä traitit ja niiden käyttäytymiset on lueteltu Liitteessä C. Käsittelemme, miten toteutamme nämä traitit mukautetulla käyttäytymisellä sekä miten luomme omia traitteja Luvussa 10. On myös monia muita attribuutteja kuin derive; lisätietoja on Rust-viitteen ”Attribuutit”-osiossa.

area-funktiomme on hyvin spesifinen: se laskee vain suorakulmioiden pinta-alan. Olisi hyödyllistä sitoa tämä käyttäytyminen tiukemmin Rectangle-rakenteeseemme, koska se ei toimi minkään muun tyypin kanssa. Katsotaan, miten voimme jatkaa tämän koodin refaktorointia muuttamalla area-funktion area-metodiksi, joka on määritelty Rectangle-tyypillemme.

Metodisyntaksi

Metodisyntaksi

Metodit ovat samankaltaisia kuin funktiot: ne määritellään fn-avainsanalla ja nimellä, niillä voi olla parametreja ja palautusarvo, ja ne sisältävät koodia, joka suoritetaan, kun metodia kutsutaan jostakin muualta. Toisin kuin funktiot, metodit määritellään rakenteen (tai luettelotyypin tai trait-objektin, joita käsitellään Luvussa 6 ja Luvussa 18, vastaavasti) yhteydessä, ja niiden ensimmäinen parametri on aina self, joka edustaa rakenteen instanssia, jolle metodia kutsutaan.

Metodin määrittely

Muutetaan area-funktio, jolla on Rectangle-instanssi parametrina, ja tehdään sen sijaan area-metodi, joka määritellään Rectangle-rakenteelle, kuten Listauksessa 5-13 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-13/src/main.rs}}
}

Määrittääksemme funktion Rectangle-kontekstissa, aloitamme impl (toteutus) -lohkon Rectangle-rakenteelle. Kaikki tämän impl-lohkon sisällä on liitetty Rectangle-tyyppiin. Siirrämme sitten area-funktion impl-lohkon aaltosulkeiden sisään ja muutamme ensimmäisen (ja tässä tapauksessa ainoan) parametrin signatuurissa ja kaikkialla rungossa muotoon self. main-funktiossa, jossa kutsuimme area-funktiota ja välitimme rect1:n argumenttina, voimme sen sijaan käyttää metodisyntaksia kutsuaksemme area-metodia Rectangle-instanssillamme. Metodisyntaksi tulee instanssin jälkeen: lisäämme pisteen, metodin nimen, sulkeet ja mahdolliset argumentit.

area-metodin signatuurissa käytämme &self:ää rectangle: &Rectangle:n sijaan. &self on itse asiassa lyhenne muodolle self: &Self. impl-lohkon sisällä tyyppi Self on alias tyypille, jolle impl-lohko on tarkoitettu. Metodeilla täytyy olla ensimmäisenä parametrinaan nimeltään self tyyppiä Self, joten Rust antaa sinun lyhentää tämän pelkällä nimellä self ensimmäisessä parametripaikassa. Huomaa, että meidän täytyy silti käyttää &:ää self-lyhenteen edessä osoittaaksemme, että tämä metodi lainaa Self-instanssia, aivan kuten teimme rectangle: &Rectangle:ssa. Metodit voivat ottaa omistajuuden self:stä, lainata self:ää muuttumattomasti, kuten teimme tässä, tai lainata self:ää muuttuvasti, aivan kuten ne voivat tehdä mille tahansa muulle parametrille.

Valitsimme &self:n tässä samasta syystä kuin käytimme &Rectangle:a funktioversiossa: emme halua ottaa omistajuutta, ja haluamme vain lukea rakenteen dataa, emme kirjoittaa siihen. Jos haluaisimme muuttaa instanssia, jolle metodia kutsutaan, osana sitä, mitä metodi tekee, käyttäisimme &mut self:ää ensimmäisenä parametrina. Metodi, joka ottaa omistajuuden instanssista käyttämällä pelkkää self:ää ensimmäisenä parametrina, on harvinainen; tätä tekniikkaa käytetään yleensä silloin, kun metodi muuntaa self:n joksikin muuksi ja haluat estää kutsujaa käyttämästä alkuperäistä instanssia muunnoksen jälkeen.

Pääsyy metodien käyttämiseen funktioiden sijaan, metodisyntaksin tarjoamisen ja sen lisäksi, ettei self:n tyyppiä tarvitse toistaa jokaisen metodin signatuurissa, on organisointi. Olemme sijoittaneet kaikki asiat, joita voimme tehdä tyypin instanssilla, yhteen impl-lohkoon sen sijaan, että pakottaisimme koodimme tulevat käyttäjät etsimään Rectangle:n ominaisuuksia eri paikoista tarjoamassamme kirjastossa.

Huomaa, että voimme halutessamme antaa metodille saman nimen kuin rakenteen kentällä on. Esimerkiksi voimme määritellä Rectangle-rakenteelle metodin, joka on myös nimeltään width:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-06-method-field-interaction/src/main.rs:here}}
}

Tässä valitsemme, että width-metodi palauttaa true, jos instanssin width- kentän arvo on suurempi kuin 0, ja false, jos arvo on 0: voimme käyttää kenttää saman nimisen metodin sisällä mihin tahansa tarkoitukseen. main-funktiossa, kun rect1.width:n jälkeen tulee sulkeet, Rust tietää, että tarkoitamme metodia width. Kun emme käytä sulkeita, Rust tietää, että tarkoitamme kenttää width.

Usein, mutta ei aina, kun annamme metodille saman nimen kuin kentällä on, haluamme sen vain palauttavan kentän arvon eikä tekevän mitään muuta. Tällaisia metodeja kutsutaan gettereiksi, eikä Rust toteuta niitä automaattisesti rakenteen kentille, kuten jotkut muut kielet tekevät. Getterit ovat hyödyllisiä, koska voit tehdä kentästä yksityisen mutta metodista julkisen ja siten mahdollistaa vain-luku-pääsyn kyseiseen kenttään osana tyypin julkista API:a. Käsittelemme, mitä julkinen ja yksityinen ovat ja miten kenttä tai metodi merkitään julkiseksi tai yksityiseksi, Luvussa 7.

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

Metodit, joilla on useita parametreja

Harjoitellaan metodien käyttöä toteuttamalla toinen metodi Rectangle-rakenteelle. Tällä kertaa haluamme, että Rectangle-instanssi ottaa toisen Rectangle- instanssin ja palauttaa true, jos toinen Rectangle mahtuu kokonaan self:n (eli ensimmäisen Rectangle:n) sisään; muuten sen pitäisi palauttaa false. Toisin sanoen, kun olemme määritelleet can_hold-metodin, haluamme pystyä kirjoittamaan Listauksessa 5-14 näytetyn ohjelman.

{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-14/src/main.rs}}

Odotettu tuloste näyttäisi seuraavalta, koska rect2:n molemmat mitat ovat pienempiä kuin rect1:n mitat, mutta rect3 on leveämpi kuin rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Tiedämme, että haluamme määritellä metodin, joten se on impl Rectangle -lohkon sisällä. Metodin nimi on can_hold, ja se ottaa parametrina muuttumattoman lainauksen toisesta Rectangle:sta. Voimme päätellä parametrin tyypin katsomalla koodia, joka kutsuu metodia: rect1.can_hold(&rect2) välittää &rect2:n, joka on muuttumaton lainaus rect2:sta, Rectangle-instanssista. Tämä on järkevää, koska meidän täytyy vain lukea rect2:a (eikä kirjoittaa, mikä tarkoittaisi, että tarvitsisimme muuttuvan lainauksen), ja haluamme main:in säilyttävän omistajuuden rect2:sta, jotta voimme käyttää sitä uudelleen can_hold-metodin kutsumisen jälkeen. can_hold-metodin palautusarvo on totuusarvo, ja toteutus tarkistaa, ovatko self:n leveys ja korkeus suurempia kuin toisen Rectangle:n leveys ja korkeus, vastaavasti. Lisätään uusi can_hold-metodi Listauksen 5-13 impl-lohkoon, kuten Listauksessa 5-15 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-15/src/main.rs:here}}
}

Kun ajamme tämän koodin Listauksen 5-14 main-funktiolla, saamme haluamamme tulosteen. Metodeilla voi olla useita parametreja, jotka lisätään signatuuriin self-parametrin jälkeen, ja nämä parametrit toimivat aivan kuten parametrit funktioissa.

Liittyvät funktiot

Kaikkia impl-lohkon sisällä määriteltyjä funktioita kutsutaan liittyviksi funktioiksi, koska ne liittyvät impl:n jälkeen nimettyyn tyyppiin. Voimme määritellä liittyviä funktioita, joilla ei ole self:ää ensimmäisenä parametrinaan (ja jotka siten eivät ole metodeja), koska niiden ei tarvitse tyypin instanssia työskennelläkseen. Olemme jo käyttäneet tällaista funktiota: String::from-funktiota, joka on määritelty String-tyypille.

Liittyviä funktioita, jotka eivät ole metodeja, käytetään usein konstruktoreina, jotka palauttavat rakenteen uuden instanssin. Näitä kutsutaan usein new:ksi, mutta new ei ole erityinen nimi eikä se ole sisäänrakennettu kieleen. Esimerkiksi voisimme halutessamme tarjota liittyvän funktion nimeltä square, jolla olisi yksi mittaparametri ja joka käyttäisi sitä sekä leveytenä että korkeutena, mikä helpottaisi neliön muotoisen Rectangle:n luomista sen sijaan, että joutuisimme määrittämään saman arvon kahdesti:

Tiedostonimi: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-03-associated-functions/src/main.rs:here}}
}

Self-avainsanat palautustyypissä ja funktion rungossa ovat aliaksia tyypille, joka esiintyy impl-avainsanan jälkeen, joka tässä tapauksessa on Rectangle.

Kutsuaksemme tätä liittyvää funktiota, käytämme ::-syntaksia rakenteen nimen kanssa; let sq = Rectangle::square(3); on esimerkki. Tämä funktio on rakenteen nimiavaruudessa: ::-syntaksia käytetään sekä liittyville funktioille että moduulien luomille nimiavaruuksille. Käsittelemme moduuleja Luvussa 7.

Useita impl-lohkoja

Jokaisella rakenteella saa olla useita impl-lohkoja. Esimerkiksi Listausta 5-15 vastaa Listauksessa 5-16 näytetty koodi, jossa jokainen metodi on omassa impl-lohkossaan.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/listing-05-16/src/main.rs:here}}
}

Ei ole syytä erotella näitä metodeja useisiin impl-lohkoihin tässä, mutta tämä on kelvollista syntaksia. Näemme tapauksen, jossa useat impl-lohkot ovat hyödyllisiä Luvussa 10, jossa käsittelemme geneerisiä tyyppejä ja traitteja.

Yhteenveto

Rakenteet antavat sinun luoda mukautettuja tyyppejä, jotka ovat merkityksellisiä sovellusalueellesi. Rakenteiden avulla voit pitää toisiinsa liittyvät datan osat yhteydessä toisiinsa ja nimetä jokaisen osan, jotta koodisi on selkeää. impl-lohkoissa voit määritellä tyypillesi liittyviä funktioita, ja metodit ovat eräänlaisia liittyviä funktioita, joiden avulla voit määrittää käyttäytymisen, joka rakenteidesi instansseilla on.

Mutta rakenteet eivät ole ainoa tapa luoda mukautettuja tyyppejä: siirrytään Rustin luettelotyyppi-ominaisuuteen lisätäksemme työkalupakkiisi uuden työkalun.

Luettelotyypit (Enums) ja mallintaminen

Tässä luvussa tarkastelemme luettelotyyppejä, joita kutsutaan myös enum-tyypeiksi. Enumit mahdollistavat tyypin määrittelyn luettelemalla sen mahdolliset variantit. Ensin määrittelemme ja käytämme enumia osoittaaksemme, kuinka enum voi tallentaa sekä merkitystä että dataa.

Seuraavaksi tutkimme erityisen hyödyllistä Option-enumia, joka ilmaisee, että arvo voi olla joko jotain tai ei mitään. Sitten perehdymme match-lausekkeeseen, joka tekee erilaisten enum-arvojen käsittelystä helppoa ja selkeää. Lopuksi käsittelemme if let -rakennetta, joka on toinen kätevä tapa käsitellä enum-arvoja yksinkertaisemmin.

Enumin määrittäminen

Enumin määrittely

Siinä missä rakenteet antavat tavan ryhmitellä toisiinsa liittyviä kenttiä ja dataa, kuten Rectangle-rakenteen width- ja height-kentät, enumit antavat tavan sanoa, että arvo on yksi mahdollisista arvoista. Esimerkiksi saatamme haluta sanoa, että Rectangle on yksi mahdollisista muodoista, joihin kuuluvat myös Circle ja Triangle. Tätä varten Rust antaa meidän koodata nämä mahdollisuudet enumina.

Katsotaan tilannetta, jonka haluamme ilmaista koodissa, ja nähdään, miksi enumit ovat hyödyllisiä ja sopivampia kuin rakenteet tässä tapauksessa. Oletetaan, että meidän täytyy työskennellä IP-osoitteiden kanssa. Tällä hetkellä IP-osoitteille käytetään kahta pääasiallista standardia: versio neljä ja versio kuusi. Koska nämä ovat ainoat mahdolliset IP-osoitteet, joita ohjelmamme kohtaa, voimme luetella kaikki mahdolliset variantit, mistä sana enumeration eli luettelotyyppi saa nimensä.

Mikä tahansa IP-osoite voi olla joko version neljä tai version kuusi osoite, mutta ei molempia samaan aikaan. Tämä IP-osoitteiden ominaisuus tekee enum-tietorakenteesta sopivan, koska enum-arvo voi olla vain yksi sen varianteista. Sekä version neljä että version kuusi osoitteet ovat silti pohjimmiltaan IP-osoitteita, joten niitä pitäisi käsitellä samana tyypinä, kun koodi käsittelee tilanteita, jotka koskevat mitä tahansa IP-osoitetyyppiä.

Voimme ilmaista tämän käsitteen koodissa määrittelemällä IpAddrKind-luettelon ja listaamalla mahdolliset IP-osoitteen tyypit, V4 ja V6. Nämä ovat enumin variantit:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-01-defining-enums/src/main.rs:def}}
}

IpAddrKind on nyt mukautettu tietotyyppi, jota voimme käyttää muualla koodissamme.

Enum-arvot

Voimme luoda kummankin IpAddrKind-variantin instanssit näin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-01-defining-enums/src/main.rs:instance}}
}

Huomaa, että enumin variantit ovat nimetty tunnisteen sisällä, ja käytämme kaksoispistettä erottamaan ne toisistaan. Tämä on hyödyllistä, koska nyt molemmat arvot IpAddrKind::V4 ja IpAddrKind::V6 ovat samaa tyyppiä: IpAddrKind. Voimme sitten esimerkiksi määritellä funktion, joka ottaa minkä tahansa IpAddrKind-arvon:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-01-defining-enums/src/main.rs:fn}}
}

Ja voimme kutsua tätä funktiota kummallakin variantilla:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-01-defining-enums/src/main.rs:fn_call}}
}

Enumien käytössä on vielä enemmän etuja. Kun ajattelemme IP-osoitetyyppiämme tarkemmin, tällä hetkellä meillä ei ole tapaa tallentaa varsinaista IP-osoitteen dataa; tiedämme vain sen tyypin. Koska opit juuri rakenteista Luvussa 5, saatat olla taipuvainen ratkaisemaan tämän ongelman rakenteilla, kuten Listauksessa 6-1 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-01/src/main.rs:here}}
}

Tässä olemme määritelleet IpAddr-rakenteen, jolla on kaksi kenttää: kind-kenttä, jonka tyyppi on IpAddrKind (aiemmin määrittelemämme enum), ja address-kenttä, jonka tyyppi on String. Meillä on kaksi tämän rakenteen instanssia. Ensimmäinen on home, ja sen kind-kentän arvo on IpAddrKind::V4 ja siihen liittyvä osoitedata on 127.0.0.1. Toinen instanssi on loopback. Sen kind-kentän arvo on IpAddrKind-enumin toinen variantti, V6, ja siihen liittyvä osoite on ::1. Olemme käyttäneet rakennetta niputtaaksemme kind- ja address-arvot yhteen, joten nyt variantti on yhdistetty arvoon.

Sama käsite voidaan kuitenkin ilmaista tiiviimmin pelkällä enumilla: sen sijaan, että enum olisi rakenteen sisällä, voimme laittaa datan suoraan kuhunkin enum-varianttiin. Tämä uusi IpAddr-enumin määrittely sanoo, että sekä V4- että V6-variantit sisältävät liittyvät String-arvot:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-02-enum-with-data/src/main.rs:here}}
}

Liitämme datan suoraan kuhunkin enum-varianttiin, joten erillistä rakennetta ei tarvita. Tässä on myös helpompi nähdä toinen yksityiskohta siitä, miten enumit toimivat: jokaisen määrittelemämme enum-variantin nimi muuttuu myös funktioksi, joka rakentaa enum-instanssin. Toisin sanoen IpAddr::V4() on funktiokutsu, joka ottaa String-argumentin ja palauttaa IpAddr-tyypin instanssin. Saamme tämän konstruktorifunktion automaattisesti enumin määrittelyn seurauksena.

Enumin käytössä on toinenkin etu rakenteeseen verrattuna: jokaisella variantilla voi olla eri tyyppejä ja eri määrä liittyvää dataa. Version neljä IP-osoitteissa on aina neljä numeerista komponenttia, joiden arvot ovat välillä 0–255. Jos haluaisimme tallentaa V4-osoitteet neljänä u8-arvona mutta ilmaista V6-osoitteet yhtenä String-arvona, emme voisi tehdä sitä rakenteella. Enumit käsittelevät tämän tapauksen vaivatta:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-03-variants-with-different-data/src/main.rs:here}}
}

Olemme näyttäneet useita eri tapoja määritellä tietorakenteita version neljä ja version kuusi IP-osoitteiden tallentamiseen. Kuitenkin, kuten käy ilmi, IP-osoitteiden tallentaminen ja sen koodaaminen, minkä tyyppisiä ne ovat, on niin yleistä, että standardikirjastossa on määrittely, jota voimme käyttää! Katsotaan, miten standardikirjasto määrittelee IpAddr:n: siinä on täsmälleen sama enum ja variantit, jotka olemme määritelleet ja käyttäneet, mutta se upottaa osoitedatan varianttien sisään kahden eri rakenteen muodossa, jotka on määritelty eri tavoin kullekin variantille:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

Tämä koodi havainnollistaa, että enum-variantin sisään voi laittaa minkä tahansa tyyppistä dataa: merkkijonoja, numeerisia tyyppejä tai rakenteita, esimerkiksi. Voit jopa sisällyttää toisen enumin! Lisäksi standardikirjaston tyypit eivät usein ole paljon monimutkaisempia kuin mitä itse keksisit.

Huomaa, että vaikka standardikirjasto sisältää IpAddr-määrittelyn, voimme silti luoda ja käyttää omaa määrittelyämme ilman ristiriitaa, koska emme ole tuoneet standardikirjaston määrittelyä laajuuteemme. Puhumme tyyppejen tuomisesta laajuuteen enemmän Luvussa 7.

Katsotaan toista enum-esimerkkiä Listauksessa 6-2: tässä on laaja kirjo eri tyyppejä upotettuna varianteihin.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-02/src/main.rs:here}}
}

Tässä enumissa on neljä varianttia eri tyypeillä:

• Quit ei sisällä lainkaan dataa.
• Move sisältää nimettyjä kenttiä, kuten rakenne.
• Write sisältää yhden String-arvon.
• ChangeColor sisältää kolme i32-arvoa.

Enumin määrittely varianteilla, kuten Listauksessa 6-2, on samankaltaista kuin erilaisten rakennemäärittelyjen määrittely, paitsi että enum ei käytä struct-avainsanaa ja kaikki variantit on ryhmitelty yhteen Message-tyypin alle. Seuraavat rakenteet voisivat tallentaa saman datan, jonka edellä olevat enum-variantit tallentavat:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-04-structs-similar-to-message-enum/src/main.rs:here}}
}

Mutta jos käyttäisimme eri rakenteita, joilla kullakin on oma tyypinsä, emme voisi yhtä helposti määritellä funktiota, joka ottaa minkä tahansa näistä viestityypeistä, kuin voisimme Listauksessa 6-2 määritellyllä Message-enumilla, joka on yksi tyyppi.

Enumeilla ja rakenteilla on vielä yksi yhteinen piirre: aivan kuten voimme määritellä metodeja rakenteille impl:llä, voimme määritellä metodeja myös enumeille. Tässä on call-niminen metodi, jonka voisimme määritellä Message-enumillemme:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-05-methods-on-enums/src/main.rs:here}}
}

Metodin runko käyttäisi self:ää saadakseen arvon, jolle metodia kutsuttiin. Tässä esimerkissä olemme luoneet muuttujan m, jonka arvo on Message::Write(String::from("hello")), ja se on se, mikä self on call-metodin rungossa, kun m.call() suoritetaan.

Katsotaan vielä toista standardikirjaston enumia, joka on hyvin yleinen ja hyödyllinen: Option.

Option-enum ja sen edut verrattuna null-arvoihin

Tämä osio tutkii Option-tapauskatsausta, joka on toinen standardikirjaston määrittelemä enum. Option-tyyppi koodaa hyvin yleisen tilanteen, jossa arvo voi olla jotain tai ei mitään.

Esimerkiksi, jos pyydät ensimmäistä alkiota ei-tyhjästä listasta, saat arvon. Jos pyydät ensimmäistä alkiota tyhjästä listasta, et saa mitään. Tämän käsitteen ilmaiseminen tyyppijärjestelmän kautta tarkoittaa, että kääntäjä voi tarkistaa, oletko käsitellyt kaikki tapaukset, jotka sinun pitäisi käsitellä; tämä ominaisuus voi estää virheitä, jotka ovat erittäin yleisiä muissa ohjelmointikielissä.

Ohjelmointikielen suunnittelua ajatellaan usein sen pohjalta, mitä ominaisuuksia sisällytetään, mutta pois jätetyt ominaisuudet ovat myös tärkeitä. Rustissa ei ole null-ominaisuutta, joka on monissa muissa kielissä. Null on arvo, joka tarkoittaa, ettei siinä ole arvoa. Kielissä, joissa on null, muuttujat voivat aina olla jommassakummassa tilassa: null tai ei-null.

Vuoden 2009 esityksessään ”Null References: The Billion Dollar Mistake” Tony Hoare, nullin keksijä, sanoo seuraavaa:

Kutsun sitä miljardidollarin virheekseni. Silloin suunnittelin ensimmäistä kattavaa tyyppijärjestelmää viittauksille olio-ohjelmointikielessä. Tavoitteenani oli varmistaa, että kaikki viittausten käyttö olisi täysin turvallista ja kääntäjä tarkistaisi sen automaattisesti. Mutta en voinut vastustaa kiusausta laittaa mukaan null-viittaus, yksinkertaisesti koska se oli niin helppo toteuttaa. Tämä on johtanut lukemattomiin virheisiin, haavoittuvuuksiin ja järjestelmän kaatumisiin, jotka ovat todennäköisesti aiheuttaneet miljardin dollarin edestä kipua ja vahinkoa viimeisten neljänkymmenen vuoden aikana.

Ongelma null-arvojen kanssa on, että jos yrität käyttää null-arvoa ei-null-arvona, saat jonkinlaisen virheen. Koska tämä null- tai ei-null-ominaisuus on kaikkialla, on erittäin helppo tehdä tämänkaltaisia virheitä.

Kuitenkin käsite, jota null yrittää ilmaista, on silti hyödyllinen: null on arvo, joka on tällä hetkellä virheellinen tai poissa jostain syystä.

Ongelma ei ole oikeastaan käsitteessä vaan tietyssä toteutuksessa. Siksi Rustissa ei ole null-arvoja, mutta siinä on enum, joka voi koodata käsitteen, että arvo on läsnä tai poissa. Tämä enum on Option<T>, ja se on standardikirjaston määrittelemä seuraavasti:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Option<T>-enum on niin hyödyllinen, että se on jopa mukana preludessa; sinun ei tarvitse tuoda sitä laajuuteen erikseen. Sen variantit ovat myös mukana preludessa: voit käyttää Some- ja None-variantteja suoraan ilman Option::-etuliitettä. Option<T>-enum on silti tavallinen enum, ja Some(T) ja None ovat edelleen tyyppiä Option<T>.

<T>-syntaksi on Rust-ominaisuus, josta emme ole vielä puhuneet. Se on geneerinen tyyppiparametri, ja käsittelemme geneerisiä tyyppejä tarkemmin Luvussa 10. Toistaiseksi sinun tarvitsee tietää vain, että <T> tarkoittaa, että Option-enumin Some-variantti voi sisältää yhden kappaleen dataa mistä tahansa tyypistä, ja jokainen konkreettinen tyyppi, jota käytetään T:n paikalla, tekee koko Option<T>-tyypistä eri tyypin. Tässä on esimerkkejä Option-arvojen käytöstä numerotyyppejä ja merkkityyppejä tallentaen:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-06-option-examples/src/main.rs:here}}
}

Muuttujan some_number tyyppi on Option<i32>. Muuttujan some_char tyyppi on Option<char>, joka on eri tyyppi. Rust voi päätellä nämä tyypit, koska olemme määrittäneet arvon Some-variantin sisällä. Muuttujan absent_number kohdalla Rust vaatii meitä merkitsemään koko Option-tyypin: kääntäjä ei voi päätellä tyyppiä, jota vastaava Some-variantti sisältäisi, katsomalla pelkkää None-arvoa. Tässä kerromme Rustille, että tarkoitamme absent_number:n olevan tyyppiä Option<i32>.

Kun meillä on Some-arvo, tiedämme, että arvo on läsnä ja se on Some-variantin sisällä. Kun meillä on None-arvo, se tarkoittaa eräässä mielessä samaa kuin null: meillä ei ole kelvollista arvoa. Miksi Option<T> on siis parempi kuin null?

Lyhyesti sanottuna, koska Option<T> ja T (missä T voi olla mikä tahansa tyyppi) ovat eri tyyppejä, kääntäjä ei anna meidän käyttää Option<T>-arvoa ikään kuin se olisi varmasti kelvollinen arvo. Esimerkiksi tämä koodi ei käänny, koska se yrittää lisätä i8:n Option<i8>:aan:

{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/src/main.rs:here}}

Jos ajamme tämän koodin, saamme virheilmoituksen, joka näyttää tältä:

{{#include ../listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/output.txt}}

Voimakasta! Käytännössä tämä virheilmoitus tarkoittaa, että Rust ei ymmärrä, miten i8 ja Option<i8> lisätään yhteen, koska ne ovat eri tyyppejä. Kun meillä on arvo tyypiltään kuten i8 Rustissa, kääntäjä varmistaa, että meillä on aina kelvollinen arvo. Voimme edetä luottavaisin mielin ilman, että meidän täytyy tarkistaa null ennen arvon käyttöä. Vasta kun meillä on Option<i8> (tai mikä tahansa tyyppi, jonka kanssa työskentelemme), meidän täytyy huolehtia siitä, että arvo saattaa puuttua, ja kääntäjä varmistaa, että käsittelemme tämän tapauksen ennen arvon käyttöä.

Toisin sanoen sinun täytyy muuntaa Option<T> arvoksi T, ennen kuin voit suorittaa T:n operaatioita sillä. Yleisesti tämä auttaa havaitsemaan yhden yleisimmistä null-ongelmista: oletus, että jokin ei ole null, vaikka se itse asiassa on.

Virheellisen oletuksen riskin poistaminen auttaa sinua luottamaan koodiisi enemmän. Jotta voisit olla arvo, joka saattaa olla null, sinun täytyy erikseen valita se tekemällä arvon tyypiksi Option<T>. Sitten kun käytät sitä arvoa, sinun täytyy erikseen käsitellä tapaus, jossa arvo on null. Kaikkialla, missä arvolla on tyyppi, joka ei ole Option<T>, voit turvallisesti olettaa, ettei arvo ole null. Tämä oli tarkoituksellinen suunnittelupäätös Rustissa rajoittaakseen nullin yleisyyttä ja lisätäkseen Rust-koodin turvallisuutta.

Miten siis saat T-arvon Some-variantista, kun sinulla on Option<T>-tyyppinen arvo, jotta voit käyttää sitä arvoa? Option<T>-enumilla on suuri määrä metodeja, jotka ovat hyödyllisiä eri tilanteissa; voit tutustua niihin sen dokumentaatiossa. Option<T>-metodien tunteminen on erittäin hyödyllistä Rust-matkallasi.

Yleisesti ottaen, jotta voit käyttää Option<T>-arvoa, haluat koodia, joka käsittelee kunkin variantin. Haluat koodia, joka suoritetaan vain, kun sinulla on Some(T)-arvo, ja tämä koodi saa käyttää sisäistä T:tä. Haluat toisenlaista koodia, joka suoritetaan vain, jos sinulla on None-arvo, eikä tässä koodissa ole T-arvoa käytettävissä. match-lauseke on ohjausrakenne, joka tekee juuri tämän enumien kanssa käytettynä: se suorittaa eri koodia riippuen siitä, mikä enumin variantti sillä on, ja tämä koodi voi käyttää vastaavan arvon sisällä olevaa dataa.

match-ohjausrakenteen konstruktio

match-ohjausrakenne

Rustissa on erittäin tehokas ohjausrakenne nimeltä match, jonka avulla voit verrata arvoa sarjaan kuvioita ja suorittaa sitten koodia sen perusteella, mikä kuvio täsmää. Kuviot voivat koostua kirjaimellisista arvoista, muuttujien nimistä, jokerimerkeistä ja monista muista asioista; Luku 19 käsittelee kaikki erilaiset kuviotyypit ja niiden toiminnan. match-lausekkeen voima tulee kuvioiden ilmaisukyvystä ja siitä, että kääntäjä varmistaa kaikkien mahdollisten tapausten käsitellyn.

Voit ajatella match-lauseketta kolikonlajittelukoneena: kolikot liukuvat radalla, jossa on erikokoisia reikiä, ja jokainen kolikko putoaa ensimmäiseen reikään, johon se mahtuu. Samalla tavalla arvot käyvät läpi match-lausekkeen jokaisen kuvion, ja ensimmäiseen kuvioon, johon arvo ”mahtuu”, arvo putoaa liittyvään koodilohkoon suoritusta varten.

Puhutaanpa kolikoista — käytetään niitä esimerkkinä match-lausekkeen kanssa! Voimme kirjoittaa funktion, joka ottaa tuntemattoman Yhdysvaltain kolikon ja määrittää samankaltaisella tavalla kuin laskuri, mikä kolikko se on, ja palauttaa sen arvon senteissä, kuten Listauksessa 6-3 on esitetty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-03/src/main.rs:here}}
}

Puretaan value_in_cents-funktion match-lauseke. Ensin listaamme match-avainsanan ja sitten lausekkeen, joka tässä tapauksessa on arvo coin. Tämä näyttää hyvin samalta kuin ehtolauseke if:n kanssa, mutta ero on suuri: if:ssä ehdon täytyy evaluoitua totuusarvoksi, mutta tässä se voi olla mikä tahansa tyyppi. Tässä esimerkissä coin-muuttujan tyyppi on ensimmäisellä rivillä määritelty Coin-enum.

Seuraavaksi tulevat match-haarat. Haaralla on kaksi osaa: kuvio ja jokin koodi. Ensimmäisellä haaralla on kuvio, joka on arvo Coin::Penny, ja sitten =>-operaattori, joka erottaa kuvion ja suoritettavan koodin. Tässä tapauksessa koodi on vain arvo 1. Jokainen haara erotetaan seuraavasta pilkulla.

Kun match-lauseke suoritetaan, se vertaa tulosarvoa kunkin haaran kuvioon järjestyksessä. Jos kuvio täsmää arvoon, kyseiseen kuvioon liittyvä koodi suoritetaan. Jos kuvio ei täsmää arvoon, suoritus jatkuu seuraavaan haaraan, aivan kuten kolikonlajittelukoneessa. Meillä voi olla niin monta haaraa kuin tarvitsemme: Listauksessa 6-3 match-lausekkeessamme on neljä haaraa.

Kuhunkin haaraan liittyvä koodi on lauseke, ja vastaavan haaran lausekkeen tulosarvo on koko match-lausekkeen palauttama arvo.

Emme yleensä käytä aaltosulkeita, jos haaran koodi on lyhyt, kuten Listauksessa 6-3, jossa jokainen haara palauttaa vain arvon. Jos haluat suorittaa useita koodirivejä haarassa, sinun täytyy käyttää aaltosulkeita, ja haaraa seuraava pilkku on silloin valinnainen. Esimerkiksi seuraava koodi tulostaa ”Lucky penny!” aina, kun metodia kutsutaan Coin::Penny-arvolla, mutta palauttaa silti lohkon viimeisen arvon, 1:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-08-match-arm-multiple-lines/src/main.rs:here}}
}

Arvoihin sitoutuvat kuviot

Toinen hyödyllinen ominaisuus match-haaroissa on, että ne voivat sitoutua kuvioon täsmäävien arvojen osiin. Näin voimme poimia arvoja enum-varianttien sisältä.

Esimerkkinä muutetaan yksi enum-varianteistamme pitämään dataa sisällään. Vuosina 1999–2008 Yhdysvaltain rahapaja lyö 25 sentin kolikoita, joissa oli eri suunnitelma jokaiselle 50 osavaltiolle toisella puolella. Mikään muu kolikko ei saanut osavaltiosuunnitelmia, joten vain 25 sentin kolikoilla on tämä ylimääräinen arvo. Voimme lisätä tämän tiedon enum-määrittelyymme muuttamalla Quarter-variantin sisältämään UsState-arvon, kuten Listauksessa 6-4 on tehty.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-04/src/main.rs:here}}
}

Kuvitellaan, että ystävä yrittää kerätä kaikki 50 osavaltion 25 sentin kolikkoa. Kun lajittelemme irtonaisia kolikoita tyypin mukaan, mainitsemme myös jokaisen 25 sentin kolikon osavaltion nimen, jotta ystävä voi lisätä sen kokoelmaansa, jos sitä ei vielä ole.

Tämän koodin match-lausekkeessa lisäämme muuttujan nimeltä state kuvioon, joka täsmää Coin::Quarter-variantin arvoihin. Kun Coin::Quarter täsmää, state-muuttuja sitoutuu kyseisen 25 sentin kolikon osavaltion arvoon. Sitten voimme käyttää state:a kyseisen haaran koodissa näin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-09-variable-in-pattern/src/main.rs:here}}
}

Jos kutsuisimme value_in_cents(Coin::Quarter(UsState::Alaska)), coin olisi Coin::Quarter(UsState::Alaska). Kun vertaamme tätä arvoa jokaiseen match-haaraan, mikään ei täsmää ennen kuin pääsemme Coin::Quarter(state)-haaraan. Tällöin state-sidonta on arvo UsState::Alaska. Voimme sitten käyttää tätä sidontaa println!-lausekkeessa ja poimia näin sisäisen osavaltioarvon Coin-enumin Quarter-variantista.

Option<T>-kuvio match-lausekkeessa

Edellisessä osiossa halusimme saada sisäisen T-arvon Some-tapauksesta käytettäessä Option<T>:tä; voimme käsitellä Option<T>:tä myös match-lausekkeella, kuten teimme Coin-enumin kanssa! Sen sijaan, että vertaisimme kolikoita, vertaamme Option<T>:n variantteja, mutta match-lausekkeen toimintatapa pysyy samana.

Oletetaan, että haluamme kirjoittaa funktion, joka ottaa Option<i32>:n ja lisää 1 sisällä olevaan arvoon, jos arvo on olemassa. Jos arvoa ei ole, funktion pitäisi palauttaa None-arvo eikä yrittää suorittaa mitään operaatioita.

Tämä funktio on hyvin helppo kirjoittaa match-lausekkeen ansiosta, ja se näyttää Listaukselta 6-5.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-05/src/main.rs:here}}
}

Tarkastellaan plus_one-funktion ensimmäistä suoritusta tarkemmin. Kun kutsumme plus_one(five), muuttujalla x plus_one-funktion rungossa on arvo Some(5). Vertaamme sitten sitä jokaiseen match-haaraan:

{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-05/src/main.rs:first_arm}}

Some(5)-arvo ei täsmää kuvioon None, joten jatkamme seuraavaan haaraan:

{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-05/src/main.rs:second_arm}}

Täsmääkö Some(5) kuvioon Some(i)? Kyllä! Meillä on sama variantti. i sitoutuu Some:n sisältämään arvoon, joten i saa arvon 5. Haaran koodi suoritetaan sitten, joten lisäämme 1 arvoon i ja luomme uuden Some-arvon, jonka sisällä on yhteensä 6.

Tarkastellaan nyt Listauksen 6-5 toista plus_one-kutsua, jossa x on None. Siirrymme match-lausekkeeseen ja vertaamme ensimmäiseen haaraan:

{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-05/src/main.rs:first_arm}}

Se täsmää! Lisättävää arvoa ei ole, joten ohjelma pysähtyy ja palauttaa None-arvon =>-merkin oikealla puolella. Koska ensimmäinen haara täsmäsi, muita haaroja ei verrata.

match-lausekkeen ja enumien yhdistäminen on hyödyllistä monissa tilanteissa. Näet tämän kuvion paljon Rust-koodissa: match enumia vasten, sitoa muuttuja sisällä olevaan dataan ja suorita sitten koodia sen perusteella. Se on aluksi hieman hankalaa, mutta kun tottuu siihen, toivot sitä kaikissa kielissä. Se on jatkuvasti käyttäjien suosikki.

match-lausekkeet ovat tyhjentäviä

match-lausekkeesta on vielä yksi puoli, josta meidän täytyy puhua: haarojen kuvioiden täytyy kattaa kaikki mahdollisuudet. Harkitse tätä versiota plus_one-funktiostamme, jossa on bugi eikä se käänny:

{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/src/main.rs:here}}

Emme käsitelleet None-tapausta, joten tämä koodi aiheuttaa bugin. Onneksi Rust osaa havaita tämän bugin. Jos yritämme kääntää tämän koodin, saamme tämän virheen:

{{#include ../listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/output.txt}}

Rust tietää, ettemme käsitelleet kaikkia mahdollisia tapauksia, ja tietää jopa, minkä kuvion unohdimme! match-lausekkeet Rustissa ovat tyhjentäviä: meidän täytyy käsitellä jokainen mahdollisuus, jotta koodi on kelvollinen. Erityisesti Option<T>:n tapauksessa, kun Rust estää meitä unohtamasta None-tapauksen käsittelyn eksplisiittisesti, se suojaa meitä olettamasta, että meillä on arvo, vaikka se saattaa olla null, mikä tekee aiemmin käsitellystä miljardin dollarin virheestä mahdottoman.

Yleiskuviot ja _-paikkamerkki

Enumien avulla voimme myös tehdä erityistoimia muutamalle tietylle arvolle, mutta kaikille muille arvoille tehdä yhden oletustoiminnon. Kuvitellaan, että toteutamme pelin, jossa jos heität noppaa ja saat 3, pelaajasi ei liiku vaan saa uuden hienon hatun. Jos heität 7, pelaajasi menettää hienon hatun. Kaikille muille arvoille pelaajasi liikkuu pelilaudalla sen verran tilaa kuin noppa osoittaa. Tässä on match, joka toteuttaa tämän logiikan nopan heittotuloksella kovakoodattuna satunnaisen arvon sijaan, ja kaikki muu logiikka edustettu funktioina ilman runkoa, koska niiden toteuttaminen ei kuulu tämän esimerkin piiriin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-15-binding-catchall/src/main.rs:here}}
}

Ensimmäisillä kahdella haaralla kuviot ovat kirjaimellisia arvoja 3 ja 7. Viimeisellä haaralla, joka kattaa kaikki muut mahdolliset arvot, kuvio on muuttuja, jonka olemme valinneet nimeksi other. other-haaran koodi käyttää muuttujaa välittämällä sen move_player-funktiolle.

Tämä koodi kääntyy, vaikka emme listanneet kaikkia mahdollisia u8-arvoja, koska viimeinen kuvio täsmää kaikkiin arvoihin, joita ei ole erikseen listattu. Tämä yleiskuvio täyttää vaatimuksen, että match on tyhjentävä. Huomaa, että yleiskuvion täytyy olla viimeisenä, koska kuvioita evaluoidaan järjestyksessä. Jos yleiskuvio olisi aiemmin, muut haarat eivät koskaan suorittuisi, joten Rust varoittaa meitä, jos lisäämme haaroja yleiskuvion jälkeen!

Rustissa on myös kuvio, jota voimme käyttää, kun haluamme yleiskuvion mutta emme halua käyttää yleiskuvion arvoa: _ on erityinen kuvio, joka täsmää mihin tahansa arvoon eikä sido sitä arvoon. Tämä kertoo Rustille, ettei meidän tarvitse arvoa, joten Rust ei varoita meitä käyttämättömästä muuttujasta.

Muutetaan pelin sääntöjä: nyt, jos heität mitä tahansa muuta kuin 3 tai 7, sinun täytyy heittää uudelleen. Emme enää tarvitse yleiskuvion arvoa, joten voimme muuttaa koodimme käyttämään _-merkkiä other-nimisen muuttujan sijaan:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-16-underscore-catchall/src/main.rs:here}}
}

Tämä esimerkki täyttää myös tyhjentävyysvaatimuksen, koska sivuutamme eksplisiittisesti kaikki muut arvot viimeisessä haarassa; emme ole unohtaneet mitään.

Lopuksi muutamme pelin sääntöjä vielä kerran niin, ettei vuorollasi tapahdu mitään, jos heität mitä tahansa muuta kuin 3 tai 7. Voimme ilmaista tämän käyttämällä yksikköarvoa (tyhjä tuplatyyppi, josta mainittiin ”Tuplatyyppi” -osiossa) koodina, joka liittyy _-haaraan:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-17-underscore-unit/src/main.rs:here}}
}

Tässä kerromme Rustille eksplisiittisesti, ettei meidän tarvitse käyttää mitään muuta arvoa, joka ei täsmää aiemman haaran kuvioon, emmekä halua suorittaa mitään koodia tässä tapauksessa.

Kuvioista ja täsmäyksestä on lisää, mitä käsittelemme Luvussa 19. Toistaiseksi siirrymme if let-syntaksiin, joka voi olla hyödyllinen tilanteissa, joissa match-lauseke on hieman puhelias.

Ytimekäs ohjausrakenne if let- ja let else-lauseilla

Tiivis ohjausrakenne if let- ja let...else-rakenteilla

if let-syntaksi antaa yhdistää if- ja let-rakenteet vähemmän puhelijaan tapaan käsitellä arvoja, jotka täsmäävät yhteen kuvioon, ja sivuuttaa loput. Harkitse Listauksen 6-6 ohjelmaa, joka täsmää Option<u8>-arvon config_max-muuttujassa, mutta haluaa suorittaa koodia vain, jos arvo on Some-variantti.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-06/src/main.rs:here}}
}

Jos arvo on Some, tulostamme Some-variantin arvon sitomalla arvon muuttujaan max kuviossa. Emme halua tehdä mitään None-arvolla. match-lausekkeen tyydyttämiseksi meidän täytyy lisätä _ => () yhden variantin käsittelyn jälkeen, mikä on ärsyttävää ylimääräistä koodia.

Sen sijaan voisimme kirjoittaa tämän lyhyemmällä tavalla käyttämällä if let-rakennetta. Seuraava koodi käyttäytyy samoin kuin Listauksen 6-6 match:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-12-if-let/src/main.rs:here}}
}

if let-syntaksi ottaa kuvion ja lausekkeen, jotka erotetaan yhtäsuuruusmerkillä. Se toimii samalla tavalla kuin match, jossa lauseke annetaan match:lle ja kuvio on sen ensimmäinen haara. Tässä tapauksessa kuvio on Some(max), ja max sitoutuu Some:n sisällä olevaan arvoon. Voimme sitten käyttää max:ia if let-lohkon rungossa samalla tavalla kuin käytimme max:ia vastaavassa match-haarassa. if let-lohkon koodi suoritetaan vain, jos arvo täsmää kuvioon.

if let tarkoittaa vähemmän kirjoittamista, vähemmän sisennystä ja vähemmän ylimääräistä koodia. Menetät kuitenkin match-lausekkeen pakottaman tyhjentävän tarkistuksen, joka varmistaa, ettei sinun unohda käsitellä mitään tapauksia. Valinta match- ja if let-rakenteiden välillä riippuu siitä, mitä teet tietyssä tilanteessa, ja siitä, onko tiiviys sopiva kompromissi tyhjentävän tarkistuksen menettämisestä.

Toisin sanoen voit ajatella if let:iä syntaksisokerina match-lausekkeelle, joka suorittaa koodia, kun arvo täsmää yhteen kuvioon, ja sitten sivuuttaa kaikki muut arvot.

Voimme liittää else-haaran if let-rakenteeseen. else-haaraan liittyvä koodilohko on sama kuin koodilohko, joka menisi _-tapaukseen match-lausekkeessa, joka vastaa if let- ja else-rakennetta. Muista Listauksen 6-4 Coin-enumin määrittely, jossa Quarter-variantti sisälsi myös UsState-arvon. Jos haluaisimme laskea kaikki ei-25-senttiset kolikot ja samalla ilmoittaa 25 sentin kolikoiden osavaltiot, voisimme tehdä sen match-lausekkeella näin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-13-count-and-announce-match/src/main.rs:here}}
}

Tai voisimme käyttää if let- ja else-lauseketta näin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/no-listing-14-count-and-announce-if-let-else/src/main.rs:here}}
}

Pysyminen ”onnellisella polulla” let...else-rakenteella

Yleinen kuvio on suorittaa laskenta, kun arvo on läsnä, ja palauttaa oletusarvo muuten. Jatkamalla kolikkoesimerkkiämme UsState-arvolla, jos haluaisimme sanoa jotain hauskaa riippuen siitä, kuinka vanha 25 sentin kolikon osavaltio on, voisimme lisätä UsState-rakenteeseen metodin, joka tarkistaa osavaltion iän, näin:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-07/src/main.rs:state}}
}

Sitten voisimme käyttää if let:iä täsmätäksemme kolikon tyyppiin ja esitelläksemme state-muuttujan ehdon rungon sisällä, kuten Listauksessa 6-7.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-07/src/main.rs:describe}}
}

Se hoitaa asian, mutta on siirtänyt työn if let-lausekkeen runkoon, ja jos tehtävä on monimutkaisempi, voi olla vaikea seurata, miten ylätason haarat liittyvät toisiinsa. Voisimme myös hyödyntää sitä, että lausekkeet tuottavat arvon, joko tuottaaksemme state:n if let:stä tai palauttaaksemme aikaisin, kuten Listauksessa 6-8. (Voit tehdä jotain vastaavaa myös match-lausekkeella.)

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-08/src/main.rs:describe}}
}

Tämä on kuitenkin omalla tavallaan hieman ärsyttävää seurata! Yksi if let-haara tuottaa arvon, ja toinen palaa kokonaan funktiosta.

Tämän yleisen kuvion ilmaisemiseksi miellyttävämmällä tavalla Rustissa on let...else. let...else-syntaksi ottaa kuvion vasemmalle puolelle ja lausekkeen oikealle puolelle, hyvin samankaltaisesti kuin if let, mutta siinä ei ole if-haaraa, vain else-haara. Jos kuvio täsmää, se sitoo arvon kuviosta ulompaan näkyvyysalueeseen. Jos kuvio ei täsmää, ohjelma siirtyy else-haaraan, jonka täytyy palata funktiosta.

Listauksessa 6-9 näet, miltä Listaus 6-8 näyttää, kun if let korvataan let...else-rakenteella.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch06-enums-and-pattern-matching/listing-06-09/src/main.rs:describe}}
}

Huomaa, että näin pysytään ”onnellisella polulla” funktion päärungossa ilman merkittävästi erilaista ohjausrakennetta kahdelle haaralle, kuten if let teki.

Jos ohjelmassasi on logiikkaa, joka on liian puheliasta ilmaistavaksi match-lausekkeella, muista, että if let ja let...else ovat myös Rust-työkalupakissasi.

Yhteenveto

Olemme nyt käsitelleet, miten enumien avulla luodaan mukautettuja tyyppejä, jotka voivat olla yksi joukosta lueteltuja arvoja. Olemme näyttäneet, miten standardikirjaston Option<T>-tyyppi auttaa käyttämään tyyppijärjestelmää virheiden estämiseen. Kun enum-arvoilla on dataa sisällään, voit käyttää match- tai if let-rakennetta poimiaksesi ja käyttääksesi näitä arvoja riippuen siitä, kuinka monta tapausta sinun täytyy käsitellä.

Rust-ohjelmasi voivat nyt ilmaista sovellusalueesi käsitteitä rakenteiden ja enumien avulla. Mukautettujen tyyppien luominen API:isi käyttöön varmistaa tyyppiturvallisuuden: kääntäjä varmistaa, että funktiosi saavat vain sellaisia arvoja, joita kukin funktio odottaa.

Jotta voit tarjota käyttäjillesi hyvin organisoidun ja suoraviivaisen API:n, joka paljastaa juuri sen, mitä käyttäjät tarvitsevat, siirrytään nyt Rustin moduuleihin.

Suurten projektien hallinta pakettien, laatikoiden ja moduulien avulla

Kun ohjelmasi kasvaa, sen rakenteen järjestäminen tulee yhä tärkeämmäksi. Ryhmittelemällä toisiinsa liittyvät toiminnallisuudet ja erottamalla erilliset ominaisuudet koodista voit helpottaa koodin hallintaa. Tämä tekee selväksi, mistä tietty ominaisuus löytyy ja missä sitä voi muokata.

Tähän asti kirjoittamamme ohjelmat ovat olleet yhdessä moduulissa ja yhdessä tiedostossa. Kun projekti kasvaa, koodi kannattaa jakaa useisiin moduuleihin ja tiedostoihin. Paketti voi sisältää useita binäärisiä laatikoita (crates) sekä valinnaisesti yhden kirjastolaatikon. Kun paketti kasvaa, voit erottaa osia omiksi laatikoiksi, jolloin ne voivat toimia ulkoisina riippuvuuksina. Tämä luku kattaa nämä tekniikat. Suurille projekteille, joissa on useita toisiinsa liittyviä paketteja, Cargo tarjoaa työtilat (workspaces), joita käsittelemme luvussa 14.

Käsittelemme myös yksityiskohtien kapselointia, joka mahdollistaa koodin uudelleenkäytön korkeammalla tasolla. Kun olet toteuttanut jonkin toiminnon, muu koodi voi kutsua sitä sen julkisen rajapinnan kautta ilman, että tarvitsee tietää toteutuksen yksityiskohtia. Tämä rajaa sitä tietomäärää, joka sinun täytyy pitää mielessäsi.

Aiheeseen liittyy myös näkyvyysalue (scope): koodin kirjoittamisen konteksti määrää, mitkä nimet ovat käytettävissä. Kun ohjelmoija tai kääntäjä käsittelee koodia, sen on tiedettävä, viittaako jokin nimi muuttujaan, funktioon, rakenteeseen, enum-tyyppiin, moduuliin, vakioon tai muuhun. Voit määritellä näkyvyysalueita ja päättää, mitkä nimet ovat käytettävissä missäkin kohdassa. Et voi antaa kahta saman nimistä elementtiä samassa näkyvyysalueessa, mutta Rust tarjoaa työkaluja nimikonfliktien ratkaisemiseen.

Rust tarjoaa useita ominaisuuksia, joilla voit hallita koodisi rakennetta, mukaan lukien sen, mitkä yksityiskohdat ovat julkisia, mitkä yksityisiä ja mitkä nimet ovat käytettävissä missäkin kontekstissa. Näitä ominaisuuksia kutsutaan usein moduulijärjestelmäksi, ja ne sisältävät:

• Paketit (Packages): Cargo-ominaisuus, joka mahdollistaa laatikoiden rakentamisen, testaamisen ja jakamisen.
• Laatikot (Crates): Moduulipuu, joka tuottaa kirjaston tai suoritettavan tiedoston.
• Moduulit ja use: Ohjaavat koodin rakennetta, näkyvyyttä ja polkujen käyttöä.
• Polut (Paths): Määrittävät, miten nimetään elementtejä, kuten rakenteita, funktioita tai moduuleja.

Tässä luvussa käsittelemme näitä ominaisuuksia, niiden yhteistoimintaa ja sitä, miten niitä käytetään näkyvyysalueiden hallintaan. Tavoitteena on, että tämän luvun jälkeen ymmärrät Rustin moduulijärjestelmän ja pystyt hallitsemaan näkyvyysalueita sujuvasti!

Paketit ja cratet

Paketit ja crate:t

Moduulijärjestelmän ensimmäiset osat, joita käsittelemme, ovat paketit ja crate:t.

Crate on pienin määrä koodia, jota Rust-kääntäjä käsittelee kerrallaan. Vaikka käyttäisit rustc-komentoa cargo-komennon sijaan ja antaisit yhden lähdekooditiedoston (kuten teimme jo ”Rust-ohjelman perusteet”-kohdassa luvussa 1), kääntäjä pitää kyseistä tiedostoa crate:na. Crate:t voivat sisältää moduuleja, ja moduulit voidaan määritellä muissa tiedostoissa, jotka käännetään crate:n mukana, kuten tulemme näkemään seuraavissa osioissa.

Crate voi olla jommassakummassa muodossa: binääricrate tai kirjastocrate. Binääricrate:t ovat ohjelmia, jotka voidaan kääntää ajettavaksi suoritettavaksi tiedostoksi, kuten komentoriviohjelma tai palvelin. Jokaisella on oltava main-funktio, joka määrittää, mitä tapahtuu suoritettavan käynnistyessä. Kaikki tähän mennessä luomamme crate:t ovat olleet binääricrate:ja.

Kirjastocrate:illa ei ole main-funktiota, eivätkä ne käänny suoritettaviksi tiedostoiksi. Sen sijaan ne määrittelevät toiminnallisuutta, joka on tarkoitettu jaettavaksi useiden projektien kesken. Esimerkiksi rand-crate, jota käytimme luvussa 2, tarjoaa toiminnallisuutta satunnaisten lukujen generointiin. Useimmiten kun rustilaiset sanovat ”crate”, he tarkoittavat kirjastocrate:a, ja he käyttävät sanaa ”crate” vaihdettavasti yleisen ohjelmointikäsitteen ”kirjasto” kanssa.

Crate-juuri on lähdekooditiedosto, josta Rust-kääntäjä aloittaa ja joka muodostaa crate:si juurimoduulin (käsittelemme moduuleja perusteellisesti kohdassa ”Laajuuden ja yksityisyyden hallinta moduuleilla”).

Paketti on yhden tai useamman crate:n kokoelma, joka tarjoaa tietyn toiminnallisuuden. Paketti sisältää Cargo.toml-tiedoston, joka kuvaa, miten nämä crate:t rakennetaan. Cargo on itse asiassa paketti, joka sisältää binääricrate:n komentorivityökalulle, jota olet käyttänyt koodisi kääntämiseen. Cargo-paketti sisältää myös kirjastocrate:n, josta binääricrate riippuu. Muut projektit voivat riippua Cargo-kirjastocrate:sta käyttääkseen samaa logiikkaa, jota Cargo-komentorivityökalu käyttää.

Paketti voi sisältää niin monta binääricrate:a kuin haluat, mutta enintään yhden kirjastocrate:n. Paketissa on oltava vähintään yksi crate, olipa se kirjasto- tai binääricrate.

Käydään läpi, mitä tapahtuu, kun luomme paketin. Ensin annamme komennon cargo new my-project:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

Kun olemme suorittaneet cargo new my-project, käytämme ls-komentoa nähdäksemme, mitä Cargo luo. my-project-hakemistossa on Cargo.toml-tiedosto, joka muodostaa paketin. Siellä on myös src-hakemisto, joka sisältää main.rs-tiedoston. Avaa Cargo.toml tekstieditorissasi ja huomaa, ettei siinä mainita src/main.rs:ää. Cargo noudattaa käytäntöä, jonka mukaan src/main.rs on binääricrate:n crate-juuri, jolla on sama nimi kuin paketilla. Vastaavasti Cargo tietää, että jos pakettihakemisto sisältää src/lib.rs:n, paketti sisältää kirjastocrate:n, jolla on sama nimi kuin paketilla, ja src/lib.rs on sen crate-juuri. Cargo välittää crate-juuritiedostot rustc-kääntäjälle kirjaston tai binäärin rakentamiseksi.

Tässä meillä on paketti, joka sisältää vain src/main.rs:n, eli se sisältää vain binääricrate:n nimeltä my-project. Jos paketti sisältää sekä src/main.rs:n että src/lib.rs:n, siinä on kaksi crate:a: binääri ja kirjasto, molemmilla sama nimi kuin paketilla. Paketissa voi olla useita binääricrate:ja sijoittamalla tiedostoja src/bin-hakemistoon: jokainen tiedosto on erillinen binääricrate.

Moduulien määrittäminen laajuuden ja yksityisyyden hallitsemiseksi

Laajuuden ja yksityisyyden hallinta moduuleilla

Tässä osiossa käsittelemme moduuleja ja moduulijärjestelmän muita osia, nimittäin polkuja, joiden avulla voit nimetä kohteita; use-avainsanaa, joka tuo polun laajuuteen; ja pub-avainsanaa, jolla kohteet tehdään julkisiksi. Käsittelemme myös as-avainsanaa, ulkoisia paketteja ja glob-operaattoria.

Moduulien pikaopas

Ennen kuin siirrymme moduulien ja polkujen yksityiskohtiin, tässä on nopea viite siitä, miten moduulit, polut, use-avainsana ja pub-avainsana toimivat kääntäjässä ja miten useimmat kehittäjät järjestävät koodinsa. Käymme läpi esimerkkejä jokaisesta näistä säännöistä koko luvun ajan, mutta tämä on hyvä paikka muistuttaa itseään moduulien toiminnasta.

• Aloita crate-juuresta: Kun crate käännetään, kääntäjä etsii ensin crate-juuritiedostosta (yleensä src/lib.rs kirjastocrate:lle ja src/main.rs binääricrate:lle) käännettävää koodia.
• Moduulien määrittely: Crate-juuritiedostossa voit määritellä uusia moduuleja; oletetaan, että määrittelet ”garden”-moduulin komennolla mod garden;. Kääntäjä etsii moduulin koodia näistä paikoista:
  • Inline, aaltosulkeissa, jotka korvaavat mod garden -lauseen lopussa olevan puolipisteen
  • Tiedostosta src/garden.rs
  • Tiedostosta src/garden/mod.rs
• Alimoduulien määrittely: Missä tahansa tiedostossa paitsi crate-juuressa voit määritellä alimoduuuleja. Esimerkiksi voit määritellä mod vegetables; tiedostossa src/garden.rs. Kääntäjä etsii alimoduuulin koodia emomoduulin nimisestä hakemistosta näistä paikoista:
  • Inline, suoraan mod vegetables -lauseen jälkeen aaltosulkeissa puolipisteen sijaan
  • Tiedostosta src/garden/vegetables.rs
  • Tiedostosta src/garden/vegetables/mod.rs
• Polut moduulien koodiin: Kun moduuli on osa crate:asi, voit viitata kyseisen moduulin koodiin mistä tahansa muualta samassa crate:ssa, kunhan yksityisyyssäännöt sen sallivat, käyttämällä polkua koodiin. Esimerkiksi Asparagus-tyyppi garden-moduulin vegetables-alimoduuulissa löytyy polusta crate::garden::vegetables::Asparagus.
• Yksityinen vs. julkinen: Moduulin sisällä oleva koodi on oletuksena yksityistä emomoduuleilleen. Tehdäksesi moduulin julkiseksi, määrittele se komennolla pub mod mod-komennon sijaan. Tehdäksesi julkisen moduulin kohteet myös julkisiksi, käytä pub-avainsanaa niiden määrittelyjen edessä.
• use-avainsana: Laajuudessa use-avainsana luo oikoteitä kohteille vähentääkseen pitkien polkujen toistoa. Missä tahansa laajuudessa, jossa voidaan viitata crate::garden::vegetables::Asparagus-polkuun, voit luoda oikotien komennolla use crate::garden::vegetables::Asparagus;, ja sen jälkeen sinun tarvitsee vain kirjoittaa Asparagus käyttääksesi kyseistä tyyppiä laajuudessa.

Tässä luomme binääricrate:n nimeltä backyard, joka havainnollistaa näitä sääntöjä. Crate:n hakemisto, joka myös on nimeltään backyard, sisältää nämä tiedostot ja hakemistot:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Tässä tapauksessa crate-juuritiedosto on src/main.rs, ja se sisältää:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/quick-reference-example/src/main.rs}}

pub mod garden; -rivi kertoo kääntäjälle sisällyttää koodi, jonka se löytää tiedostosta src/garden.rs, joka on:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/quick-reference-example/src/garden.rs}}

Tässä pub mod vegetables; tarkoittaa, että koodi tiedostosta src/garden/vegetables.rs sisällytetään myös. Kyseinen koodi on:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/quick-reference-example/src/garden/vegetables.rs}}

Siirrytään nyt näiden sääntöjen yksityiskohtiin ja havainnollistetaan niitä käytännössä!

Liittyvän koodin ryhmittely moduuleihin

Moduulit antavat meille mahdollisuuden järjestää koodia crate:n sisällä luettavuuden ja helpon uudelleenkäytön vuoksi. Moduulit antavat myös hallita kohteiden yksityisyyttä, koska moduulin sisällä oleva koodi on oletuksena yksityistä. Yksityiset kohteet ovat sisäisiä toteutustietoja, jotka eivät ole ulkopuolisen käytön saatavilla. Voimme valita tehdä moduulit ja niiden sisällä olevat kohteet julkisiksi, mikä paljastaa ne ulkoisen koodin käytettäväksi ja riippuvuudeksi.

Esimerkkinä kirjoitetaan kirjastocrate, joka tarjoaa ravintolan toiminnallisuuden. Määrittelemme funktioiden signatuurit, mutta jätämme niiden rungot tyhjiksi keskittyäksemme koodin organisointiin ravintolan toteutuksen sijaan.

Ravintola-alalla ravintolan osia kutsutaan etu- ja takaosaksi. Etuosassa asiakkaat ovat; se kattaa paikat, joissa emännät istuttavat asiakkaat, tarjoilijat ottavat tilaukset ja maksut, ja baarimestarit valmistavat juomia. Takaosassa keitit ja kokit työskentelevät keittiössä, tiskinpesijät siivoavat, ja esimiehet tekevät hallinnollista työtä.

Rakentaaksemme crate:amme tällä tavalla voimme järjestää sen funktiot sisäkkäisiin moduuleihin. Luo uusi kirjasto nimeltä restaurant suorittamalla cargo new restaurant --lib. Syötä sitten listauksen 7-1 koodi tiedostoon src/lib.rs määritelläksesi moduuleja ja funktiosignatuureja; tämä koodi on etuosan osio.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-01/src/lib.rs}}

Määrittelemme moduulin mod-avainsanalla, jota seuraa moduulin nimi (tässä tapauksessa front_of_house). Moduulin runko menee sitten aaltosulkeiden sisään. Moduulien sisällä voimme sijoittaa muita moduuleja, kuten tässä tapauksessa moduulit hosting ja serving. Moduulit voivat myös sisältää määrittelyjä muille kohteille, kuten structeille, enumeille, vakioille, trait:eille ja kuten listauksessa 7-1 funktioille.

Moduuleja käyttämällä voimme ryhmitellä liittyvät määrittelyt yhteen ja nimetä, miksi ne liittyvät toisiinsa. Tätä koodia käyttävät ohjelmoijat voivat navigoida koodissa ryhmien perusteella sen sijaan, että heidän pitäisi lukea läpi kaikki määrittelyt, mikä helpottaa heille relevanttien määrittelyjen löytämistä. Tähän koodiin uutta toiminnallisuutta lisäävät ohjelmoijat tietävät, mihin sijoittaa koodin pitääkseen ohjelman järjestyksessä.

Aiemmin mainitsimme, että src/main.rs ja src/lib.rs kutsutaan crate-juuriksi. Niiden nimen syy on se, että kummankin näistä kahdesta tiedostosta sisältö muodostaa moduulin nimeltä crate crate:n moduulirakenteen juuressa, jota kutsutaan moduulipuuksi.

Listaus 7-2 näyttää moduulipuun listauksen 7-1 rakenteelle.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Tämä puu näyttää, miten jotkin moduulit sisäkkäistyvät muihin moduuleihin; esimerkiksi hosting sisäkkäistyy front_of_house-moduuliin. Puu näyttää myös, että jotkin moduulit ovat sisaruksia, eli ne on määritelty samassa moduulissa; hosting ja serving ovat sisaruksia, jotka on määritelty front_of_house-moduulissa. Jos moduuli A on moduulin B sisällä, sanomme, että moduuli A on moduulin B lapsi ja moduuli B on moduulin A vanhempi. Huomaa, että koko moduulipuu on juurrutettu implisiittiseen moduuliin nimeltä crate.

Moduulipuu saattaa muistuttaa tietokoneesi tiedostojärjestelmän hakemistopuuta; tämä on erittäin osuva vertaus! Aivan kuten hakemistot tiedostojärjestelmässä, käytät moduuleja koodisi organisointiin. Ja aivan kuten tiedostot hakemistossa, tarvitsemme tavan löytää moduulimme.

Polut moduulipuun kohteen viittaamiseen

Polut kohteen viittaamiseen moduulipuussa

Näyttääksemme Rustille, mistä kohteen moduulipuussa löytyy, käytämme polkua samalla tavalla kuin käytämme polkua navigoidessamme tiedostojärjestelmässä. Kutsuaksemme funktiota meidän on tiedettävä sen polku.

Polku voi olla kahdessa muodossa:

• Absoluuttinen polku on täydellinen polku, joka alkaa crate-juuresta; ulkoisen crate:n koodille absoluuttinen polku alkaa crate:n nimellä, ja nykyisen crate:n koodille se alkaa literaalilla crate.
• Suhteellinen polku alkaa nykyisestä moduulista ja käyttää self-, super- tai nykyisen moduulin tunnistetta.

Sekä absoluuttisia että suhteellisia polkuja seuraa yksi tai useampi tunniste, jotka on erotettu kaksoispisteillä (::).

Palataan listaukseen 7-1 ja oletetaan, että haluamme kutsua add_to_waitlist-funktiota. Tämä on sama kuin kysyisi: Mikä on add_to_waitlist-funktion polku? Listaus 7-3 sisältää listauksen 7-1, josta on poistettu joitakin moduuleja ja funktioita.

Näytämme kaksi tapaa kutsua add_to_waitlist-funktiota uudesta funktiosta eat_at_restaurant, joka on määritelty crate-juuressa. Nämä polut ovat oikein, mutta on vielä toinen ongelma, joka estää tämän esimerkin kääntymisen sellaisenaan. Selitämme syyn hetken kuluttua.

eat_at_restaurant-funktio on osa kirjastocrate:amme julkista API:a, joten merkitsemme sen pub-avainsanalla. Kohdassa ”Polkujen paljastaminen pub-avainsanalla” käsittelemme pub:ia tarkemmin.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-03/src/lib.rs}}

Ensimmäisellä kerralla kun kutsumme add_to_waitlist-funktiota funktiossa eat_at_restaurant, käytämme absoluuttista polkua. add_to_waitlist-funktio on määritelty samassa crate:ssa kuin eat_at_restaurant, mikä tarkoittaa, että voimme käyttää crate-avainsanaa absoluuttisen polun aloittamiseen. Sisällytämme sitten jokaisen peräkkäisen moduulin, kunnes pääsemme add_to_waitlist-funktioon. Voit kuvitella tiedostojärjestelmän, jolla on sama rakenne: Määrittäisimme polun /front_of_house/hosting/add_to_waitlist suorittaaksemme add_to_waitlist-ohjelman; crate-nimen käyttäminen crate-juuresta aloittamiseen on kuin /-merkin käyttäminen tiedostojärjestelmän juuresta aloittamiseen komentorivilläsi.

Toisella kerralla kun kutsumme add_to_waitlist-funktiota funktiossa eat_at_restaurant, käytämme suhteellista polkua. Polku alkaa front_of_house-moduulin nimellä, joka on määritelty samalla tasolla moduulipuussa kuin eat_at_restaurant. Tässä tiedostojärjestelmän vastine olisi polun front_of_house/hosting/add_to_waitlist käyttäminen. Moduulin nimellä aloittaminen tarkoittaa, että polku on suhteellinen.

Valinta suhteellisen tai absoluuttisen polun käytöstä on päätös, jonka teet projektisi perusteella, ja se riippuu siitä, siirrätkö todennäköisemmin kohteen määrittelykoodia erikseen vai yhdessä koodin kanssa, joka käyttää kohdetta. Esimerkiksi jos siirtäisimme front_of_house-moduulin ja eat_at_restaurant-funktion moduuliin nimeltä customer_experience, meidän pitäisi päivittää absoluuttinen polku add_to_waitlist-funktioon, mutta suhteellinen polku olisi edelleen kelvollinen. Jos kuitenkin siirtäisimme eat_at_restaurant-funktion erikseen moduuliin nimeltä dining, absoluuttinen polku add_to_waitlist-kutsuun pysyisi samana, mutta suhteellinen polku pitäisi päivittää. Yleinen mieltymyksemme on määrittää absoluuttiset polut, koska on todennäköisempää, että haluamme siirtää koodin määrittelyjä ja kohteiden kutsuja toisistaan riippumatta.

Yritetään kääntää listaus 7-3 ja selvitetään, miksi se ei vielä käänny! Virheet, jotka saamme, on näytetty listauksessa 7-4.

{{#include ../listings/ch07-managing-growing-projects/listing-07-03/output.txt}}

Virheilmoitukset sanovat, että moduuli hosting on yksityinen. Toisin sanoen meillä on oikeat polut hosting-moduuliin ja add_to_waitlist-funktioon, mutta Rust ei anna meidän käyttää niitä, koska sillä ei ole pääsyä yksityisiin osiin. Rustissa kaikki kohteet (funktiot, metodit, structit, enumit, moduulit ja vakiot) ovat oletuksena yksityisiä emomoduuleilleen. Jos haluat tehdä kohteen, kuten funktion tai structin, yksityiseksi, laitat sen moduuliin.

Emomoduulin kohteet eivät voi käyttää alimoduuulien yksityisiä kohteita, mutta alimoduuulien kohteet voivat käyttää esi-isämoduuliensa kohteita. Tämä johtuu siitä, että alimoduuulit käärivät ja piilottavat toteutustietonsa, mutta alimoduuulit näkevät kontekstin, jossa ne on määritelty. Jatkaaksemme metaforaamme, ajattele yksityisyyssääntöjä kuin ravintolan takaosaa: Siellä tapahtuva on yksityistä ravintolan asiakkaille, mutta toimistopäälliköt näkevät ja voivat tehdä kaiken ravintolassa, jota he hallinnoivat.

Rust päätti, että moduulijärjestelmä toimii tällä tavalla, jotta sisäisten toteutustietojen piilottaminen on oletus. Näin tiedät, mitä sisäisen koodin osia voit muuttaa rikkomatta ulkoista koodia. Rust antaa kuitenkin mahdollisuuden paljastaa alimoduuulien koodin sisäisiä osia ulommille esi-isämoduuleille käyttämällä pub-avainsanaa kohteen tekemiseksi julkiseksi.

Polkujen paljastaminen pub-avainsanalla

Palataan listauksen 7-4 virheeseen, joka kertoi, että hosting-moduuli on yksityinen. Haluamme, että emomoduulin eat_at_restaurant-funktiolla on pääsy alimoduuulin add_to_waitlist-funktioon, joten merkitsemme hosting-moduulin pub-avainsanalla, kuten listauksessa 7-5.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-05/src/lib.rs:here}}

Valitettavasti listauksen 7-5 koodi tuottaa edelleen kääntäjän virheitä, kuten listauksessa 7-6.

{{#include ../listings/ch07-managing-growing-projects/listing-07-05/output.txt}}

Mitä tapahtui? pub-avainsanan lisääminen mod hosting -lauseen eteen tekee moduulista julkisen. Tämän muutoksen jälkeen, jos pääsemme front_of_house-moduuliin, pääsemme hosting-moduuliin. Mutta hosting-moduulin sisältö on edelleen yksityistä; moduulin tekeminen julkiseksi ei tee sen sisällöstä julkista. pub-avainsana moduulissa sallii vain sen esi-isämoduulien koodin viitata siihen, ei päästä sen sisäiseen koodiin. Koska moduulit ovat säiliöitä, pelkällä moduulin tekemisellä julkiseksi emme voi tehdä paljon; meidän on mentävä pidemmälle ja valittava tehdä yksi tai useampi moduulin sisällä olevista kohteista julkisiksi.

Listauksen 7-6 virheet sanovat, että add_to_waitlist-funktio on yksityinen. Yksityisyyssäännöt koskevat structeja, enumeja, funktioita ja metodeja sekä moduuleja.

Tehdään myös add_to_waitlist-funktiosta julkinen lisäämällä pub-avainsana sen määrittelyn eteen, kuten listauksessa 7-7.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-07/src/lib.rs:here}}

Nyt koodi kääntyy! Nähdäksemme, miksi pub-avainsanan lisääminen sallii näiden polkujen käytön funktiossa eat_at_restaurant yksityisyyssääntöjen suhteen, tarkastellaan absoluuttista ja suhteellista polkua.

Absoluuttisessa polussa aloitamme crate:sta, crate:amme moduulipuun juuresta. front_of_house-moduuli on määritelty crate-juuressa. Vaikka front_of_house ei ole julkinen, koska eat_at_restaurant-funktio on määritelty samassa moduulissa kuin front_of_house (eli eat_at_restaurant ja front_of_house ovat sisaruksia), voimme viitata front_of_house-moduuliin funktiosta eat_at_restaurant. Seuraavaksi on hosting-moduuli, joka on merkitty pub:lla. Pääsemme hosting-moduulin emomoduuliin, joten pääsemme hosting-moduuliin. Lopuksi add_to_waitlist-funktio on merkitty pub:lla, ja pääsemme sen emomoduuliin, joten tämä funktiokutsu toimii!

Suhteellisessa polussa logiikka on sama kuin absoluuttisessa polussa paitsi ensimmäisessä vaiheessa: Sen sijaan, että aloittaisimme crate-juuresta, polku alkaa front_of_house-moduulista. front_of_house-moduuli on määritelty samassa moduulissa kuin eat_at_restaurant, joten suhteellinen polku, joka alkaa moduulista, jossa eat_at_restaurant on määritelty, toimii. Sitten, koska hosting ja add_to_waitlist on merkitty pub:lla, polun loppuosa toimii, ja tämä funktiokutsu on kelvollinen!

Jos aiot jakaa kirjastocrate:asi, jotta muut projektit voivat käyttää koodiasi, julkinen API:si on sopimus crate:si käyttäjien kanssa, joka määrittää, miten he voivat olla vuorovaikutuksessa koodisi kanssa. Julkisen API:n muutosten hallintaan liittyy monia näkökohtia, jotka helpottavat ihmisten riippuvuutta crate:stasi. Nämä näkökohdat ylittävät tämän kirjan laajuuden; jos olet kiinnostunut tästä aiheesta, katso Rust API Guidelines -ohjeet.

Suhteellisten polkujen aloittaminen super:lla

Voimme rakentaa suhteellisia polkuja, jotka alkavat emomoduulista nykyisen moduulin tai crate-juuren sijaan käyttämällä super-avainsanaa polun alussa. Tämä on kuin tiedostojärjestelmän polun aloittaminen ..-syntaksilla, joka tarkoittaa siirtymistä emohakemistoon. super:n käyttäminen sallii meidän viitata kohteeseen, jonka tiedämme olevan emomoduulissa, mikä voi helpottaa moduulipuun uudelleenjärjestelyä, kun moduuli on läheisesti liittynyt emomoduuliin, mutta emomoduuli saatetaan joskus siirtää muualle moduulipuussa.

Harkitse listauksen 7-8 koodia, joka mallintaa tilannetta, jossa keittiömestari korjaa virheellisen tilauksen ja tuo sen henkilökohtaisesti asiakkaalle. back_of_house-moduulissa määritelty fix_incorrect_order-funktio kutsuu emomoduulissa määriteltyä deliver_order-funktiota määrittämällä polun deliver_order-funktioon aloittaen super:lla.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-08/src/lib.rs}}

fix_incorrect_order-funktio on back_of_house-moduulissa, joten voimme käyttää super:a siirtyäksemme back_of_house-moduulin emomoduuliin, joka tässä tapauksessa on crate, juuri. Sieltä etsimme deliver_order-funktiota ja löydämme sen. Onnistui! Uskomme, että back_of_house-moduuli ja deliver_order-funktio pysyvät todennäköisesti samassa suhteessa toisiinsa ja siirtyvät yhdessä, jos päättäisimme järjestää crate:n moduulipuun uudelleen. Siksi käytimme super:a, jotta meillä olisi vähemmän paikkoja päivitettäväksi tulevaisuudessa, jos tämä koodi siirretään eri moduuliin.

Structien ja enumien tekeminen julkisiksi

Voimme myös käyttää pub:ia structien ja enumien merkitsemiseen julkisiksi, mutta pub:n käytössä structien ja enumien kanssa on muutamia lisätietoja. Jos käytämme pub:ia struct-määrittelyn edessä, teemme structista julkisen, mutta structin kentät ovat edelleen yksityisiä. Voimme tehdä jokaisesta kentästä julkisen tai yksityisen tapauskohtaisesti. Listauksessa 7-9 olemme määritelleet julkisen back_of_house::Breakfast-structin, jossa on julkinen toast-kenttä mutta yksityinen seasonal_fruit-kenttä. Tämä mallintaa ravintolatilannetta, jossa asiakas voi valita aterian kanssa tulevan leivän tyypin, mutta keittiömestari päättää, mikä hedelmä seuraa ateriaa sen perusteella, mikä on sesongissa ja varastossa. Saatavilla olevat hedelmät vaihtuvat nopeasti, joten asiakkaat eivät voi valita hedelmää tai edes nähdä, minkä hedelmän he saavat.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-09/src/lib.rs}}

Koska back_of_house::Breakfast-structin toast-kenttä on julkinen, funktiossa eat_at_restaurant voimme kirjoittaa ja lukea toast-kenttää käyttämällä pistesyntaksia. Huomaa, ettemme voi käyttää seasonal_fruit-kenttää funktiossa eat_at_restaurant, koska seasonal_fruit on yksityinen. Kokeile poistaa kommentti riviltä, joka muuttaa seasonal_fruit-kentän arvoa, nähdäksesi minkä virheen saat!

Huomaa myös, että koska back_of_house::Breakfast-structilla on yksityinen kenttä, structin on tarjottava julkinen assosioitu funktio, joka luo Breakfast-instanssin (olemme nimenneet sen tässä summer). Jos Breakfast-structilla ei olisi tällaista funktiota, emme voisi luoda Breakfast-instanssia funktiossa eat_at_restaurant, koska emme voisi asettaa yksityisen seasonal_fruit-kentän arvoa funktiossa eat_at_restaurant.

Sitä vastoin, jos teemme enumista julkisen, kaikista sen varianteista tulee julkisia. Tarvitsemme vain pub-avainsanan enum-avainsanan edessä, kuten listauksessa 7-10.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-10/src/lib.rs}}

Koska teimme Appetizer-enumista julkisen, voimme käyttää Soup- ja Salad-variantteja funktiossa eat_at_restaurant.

Enumit eivät ole kovin hyödyllisiä, elleivät niiden variantit ole julkisia; olisi ärsyttävää joutua merkitsemään kaikki enum-variantit pub:lla joka tapauksessa, joten enum-varianttien oletus on olla julkisia. Structit ovat usein hyödyllisiä ilman, että niiden kentät olisivat julkisia, joten struct-kentät noudattavat yleistä sääntöä, että kaikki on oletuksena yksityistä, ellei niitä ole merkitty pub:lla.

On vielä yksi tilanne, jossa pub:ia käytetään, jota emme ole käsitelleet, ja se on viimeinen moduulijärjestelmämme ominaisuus: use-avainsana. Käsittelemme use:a ensin erikseen, ja sitten näytämme, miten pub ja use yhdistetään.

Polkujen tuominen näkyvyysalueeseen use-avainsanalla

Polkujen tuominen laajuuteen use-avainsanalla

Polkujen kirjoittaminen funktioiden kutsumiseksi voi tuntua hankalalta ja toistavalta. Listauksessa 7-7, valitsimmepa absoluuttisen tai suhteellisen polun add_to_waitlist-funktioon, meidän piti aina määrittää myös front_of_house ja hosting joka kerta kun halusimme kutsua add_to_waitlist-funktiota. Onneksi on olemassa tapa yksinkertaistaa tätä prosessia: Voimme luoda oikotien polkuun use-avainsanalla kerran ja käyttää sitten lyhyempää nimeä kaikkialla muualla laajuudessa.

Listauksessa 7-11 tuomme crate::front_of_house::hosting-moduulin eat_at_restaurant-funktion laajuuteen, jotta meidän tarvitsee vain määrittää hosting::add_to_waitlist kutsuaksemme add_to_waitlist-funktiota funktiossa eat_at_restaurant.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-11/src/lib.rs}}

use-avainsanan ja polun lisääminen laajuuteen on samanlaista kuin symbolisen linkin luominen tiedostojärjestelmässä. Lisäämällä use crate::front_of_house::hosting crate-juureen, hosting on nyt kelvollinen nimi kyseisessä laajuudessa, aivan kuin hosting-moduuli olisi määritelty crate-juuressa. use:lla laajuuteen tuodut polut tarkistavat myös yksityisyyden, kuten kaikki muutkin polut.

Huomaa, että use luo oikotien vain sille laajuudelle, jossa use esiintyy. Listaus 7-12 siirtää eat_at_restaurant-funktion uuteen alimoduuuliin nimeltä customer, joka on sitten eri laajuus kuin use-lause, joten funktion runko ei käänny.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-12/src/lib.rs}}

Kääntäjän virhe näyttää, että oikotie ei enää päde customer-moduulissa:

{{#include ../listings/ch07-managing-growing-projects/listing-07-12/output.txt}}

Huomaa, että on myös varoitus, että use ei ole enää käytössä laajuudessaan! Korjataksesi tämän ongelman, siirrä use myös customer-moduuliin, tai viittaa emomoduulin oikotiehen super::hosting:lla customer-alimoduuulissa.

Idiomatisten use-polkujen luominen

Listauksessa 7-11 saatoit ihmetellä, miksi määritimme use crate::front_of_house::hosting ja kutsuimme sitten hosting::add_to_waitlist funktiossa eat_at_restaurant, sen sijaan että määrittäisimme use-polun aina add_to_waitlist-funktioon saakka saavuttaaksemme saman tuloksen, kuten listauksessa 7-13.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-13/src/lib.rs}}

Vaikka sekä listaus 7-11 että listaus 7-13 saavuttavat saman tehtävän, listaus 7-11 on idiomatinen tapa tuoda funktio laajuuteen use:lla. Funktion emomoduulin tuominen laajuuteen use:lla tarkoittaa, että meidän on määritettävä emomoduuli funktiota kutsuessamme. Emomoduulin määrittäminen funktiota kutsuttaessa tekee selväksi, että funktiota ei ole määritelty paikallisesti, mutta silti minimoidaan täyden polun toisto. Listauksen 7-13 koodi ei ole selvä siitä, missä add_to_waitlist on määritelty.

Toisaalta, kun tuomme structeja, enumeja ja muita kohteita use:lla, on idiomatista määrittää täydellinen polku. Listaus 7-14 näyttää idiomatisen tavan tuoda standardikirjaston HashMap-struct binääricrate:n laajuuteen.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-14/src/main.rs}}
}

Tämän idiomien takana ei ole vahvaa syytä: se on vain käytäntö, joka on kehittynyt, ja ihmiset ovat tottuneet lukemaan ja kirjoittamaan Rust-koodia tällä tavalla.

Poikkeus tähän idiomiaan on, jos tuomme kaksi samannimistä kohdetta laajuuteen use-lauseilla, koska Rust ei salli sitä. Listaus 7-15 näyttää, miten tuoda kaksi samannimistä Result-tyyppiä laajuuteen, joilla on sama nimi mutta eri emomoduulit, ja miten viitata niihin.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-15/src/lib.rs:here}}

Kuten näet, emomoduulien käyttäminen erottaa kaksi Result-tyyppiä. Jos sen sijaan määrittäisimme use std::fmt::Result ja use std::io::Result, meillä olisi kaksi Result-tyyppiä samassa laajuudessa, eikä Rust tietäisi, mitä tarkoitimme käyttäessämme Result:ia.

Uusien nimien antaminen as-avainsanalla

On olemassa toinen ratkaisu ongelmaan, jossa tuodaan kaksi samannimistä tyyppiä samaan laajuuteen use:lla: Polun jälkeen voimme määrittää as ja uuden paikallisen nimen, eli aliaksen, tyypille. Listaus 7-16 näyttää toisen tavan kirjoittaa listauksen 7-15 koodi uudelleennimeämällä yksi kahdesta Result-tyypistä as:lla.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-16/src/lib.rs:here}}

Toisessa use-lauseessa valitsimme uuden nimen IoResult tyypille std::io::Result, joka ei ole ristiriidassa std::fmt:n Result:n kanssa, jonka olemme myös tuoneet laajuuteen. Listaukset 7-15 ja 7-16 katsotaan idiomatiseksi, joten valinta on sinun!

Nimien uudelleenvienti pub use:lla

Kun tuomme nimen laajuuteen use-avainsanalla, nimi on yksityinen laajuudelle, johon sen tuimme. Jotta koodi kyseisen laajuuden ulkopuolelta voisi viitata kyseiseen nimeen ikään kuin se olisi määritelty kyseisessä laajuudessa, voimme yhdistää pub ja use. Tätä tekniikkaa kutsutaan uudelleenvienniksi, koska tuomme kohteen laajuuteen mutta teemme sen myös muiden saataville heidän tuodakseen sen omaan laajuuteensa.

Listaus 7-17 näyttää listauksen 7-11 koodin, jossa juurimoduulin use on muutettu muotoon pub use.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-17/src/lib.rs}}

Ennen tätä muutosta ulkoisen koodin olisi pitänyt kutsua add_to_waitlist-funktiota polulla restaurant::front_of_house::hosting::add_to_waitlist(), mikä olisi myös vaatinut front_of_house-moduulin merkitsemistä pub:ksi. Nyt kun tämä pub use on vienyt uudelleen hosting-moduulin juurimoduulista, ulkoinen koodi voi käyttää polkua restaurant::hosting::add_to_waitlist() sen sijaan.

Uudelleenvienti on hyödyllistä, kun koodisi sisäinen rakenne eroaa siitä, miten koodiasi kutsuvat ohjelmoijat ajattelevat toimialuetta. Esimerkiksi tässä ravintolametaforassa ravintolaa pyörittävät ihmiset ajattelevat ”etuosaa” ja ”takaosaa”. Mutta ravintolaa vierailevat asiakkaat eivät todennäköisesti ajattele ravintolan osia näillä termeillä. pub use:lla voimme kirjoittaa koodimme yhdellä rakenteella mutta paljastaa eri rakenteen. Näin kirjastomme on hyvin organisoitu sekä kirjastoa työstäville ohjelmoijille että kirjastoa kutsuville ohjelmoijille. Tarkastelemme toista esimerkkiä pub use:sta ja sen vaikutuksesta crate:si dokumentaatioon kohdassa ”Kätevän julkisen API:n vienti” luvussa 14.

Ulkoisten pakettien käyttö

Luvussa 2 ohjelmoimme arvauspeli-projektin, joka käytti ulkoista pakettia nimeltä rand satunnaisten lukujen saamiseksi. Käyttääksemme rand:ia projektissamme lisäsimme tämän rivin tiedostoon Cargo.toml:

{{#include ../listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml:9:}}

rand:in lisääminen riippuvuudeksi tiedostoon Cargo.toml kertoo Cargolle ladata rand-paketti ja kaikki sen riippuvuudet osoitteesta crates.io ja tehdä rand saataville projektillemme.

Sitten tuodaksemme rand-määrittelyt pakettimme laajuuteen lisäsimme use-rivin, joka alkaa crate:n nimellä rand, ja listasimme kohteet, jotka halusimme tuoda laajuuteen. Muista, että kohdassa ”Satunnaisen luvun generointi” luvussa 2 toimme rand::prelude-moduulin kohteet laajuuteen ja kutsuimme rand::rng-funktiota:

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-03/src/main.rs:ch07-04}}

Rust-yhteisön jäsenet ovat tehneet monia paketteja saataville osoitteessa crates.io, ja minkä tahansa niistä tuominen pakettiisi sisältää samat vaiheet: niiden listaaminen pakettisi Cargo.toml-tiedostossa ja use:n käyttäminen niiden crate:jen kohteiden tuomiseen laajuuteen.

Huomaa, että standardikirjasto std on myös crate, joka on ulkopuolinen paketillemme. Koska standardikirjasto toimitetaan Rust-kielen mukana, meidän ei tarvitse muuttaa Cargo.toml:ia sisällyttääksemme std:n. Meidän on kuitenkin viitattava siihen use:lla tuodaksemme kohteita sieltä pakettimme laajuuteen. Esimerkiksi HashMap:n kanssa käyttäisimme tätä riviä:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Tämä on absoluuttinen polku, joka alkaa std:llä, standardikirjaston crate:n nimellä.

Sisäkkäisten polkujen käyttö use-listojen siistimiseen

Jos käytämme useita kohteita, jotka on määritelty samassa crate:ssa tai samassa moduulissa, jokaisen kohteen listaaminen omalle rivilleen voi viedä paljon pystysuuntaista tilaa tiedostoissamme. Esimerkiksi nämä kaksi use-lausetta, joita käytimme arvauspelissä listauksessa 2-4, tuovat std:n kohteet laajuuteen:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/src/main.rs:here}}

Sen sijaan voimme käyttää sisäkkäisiä polkuja tuodaksemme samat kohteet laajuuteen yhdellä rivillä. Teemme tämän määrittämällä polun yhteisen osan, jota seuraa kaksoispiste, ja sitten aaltosulkeet luettelon polkujen osista, jotka eroavat, kuten listauksessa 7-18.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-18/src/main.rs:here}}

Suuremmissa ohjelmissa useiden kohteiden tuominen laajuuteen samasta crate:sta tai moduulista sisäkkäisiä polkuja käyttäen voi vähentää tarvittavien erillisten use-lausetten määrää huomattavasti!

Voimme käyttää sisäkkäistä polkua milla tahansa polun tasolla, mikä on hyödyllistä yhdistettäessä kahta use-lausetta, joilla on yhteinen alipolku. Esimerkiksi listaus 7-19 näyttää kaksi use-lausetta: toinen, joka tuo std::io:n laajuuteen, ja toinen, joka tuo std::io::Write:n laajuuteen.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-19/src/lib.rs}}

Näiden kahden polun yhteinen osa on std::io, ja se on ensimmäisen polun kokonaisuus. Yhdistääksemme nämä kaksi polkua yhdeksi use-lauseeksi voimme käyttää self:ä sisäkkäisessä polussa, kuten listauksessa 7-20.

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-20/src/lib.rs}}

Tämä rivi tuo std::io:n ja std::io::Write:n laajuuteen.

Kohteiden tuominen glob-operaattorilla

Jos haluamme tuoda kaikki polussa määritellyt julkiset kohteet laajuuteen, voimme määrittää kyseisen polun, jota seuraa *-glob-operaattori:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Tämä use-lause tuo kaikki std::collections:ssa määritellyt julkiset kohteet nykyiseen laajuuteen. Ole varovainen käyttäessäsi glob-operaattoria! Glob voi vaikeuttaa sen tunnistamista, mitkä nimet ovat laajuudessa ja mistä ohjelmassasi käytetty nimi on määritelty. Lisäksi, jos riippuvuus muuttaa määrittelyjään, tuomasi muuttuvat myös, mikä voi johtaa kääntäjän virheisiin riippuvuutta päivitettäessä, jos riippuvuus lisää määrittelyn samalla nimellä kuin sinun määrittelysi samassa laajuudessa, esimerkiksi.

Glob-operaattoria käytetään usein testauksessa tuomaan kaikki testattava tests-moduuliin; käsittelemme tätä kohdassa ”Testien kirjoittaminen” luvussa 11. Glob-operaattoria käytetään joskus myös osana preludi-mallia: Katso standardikirjaston dokumentaatiosta lisätietoja tästä mallista.

Moduulien erottaminen eri tiedostoihin

Moduulien erottaminen eri tiedostoihin

Tähän asti kaikki esimerkit tässä luvussa ovat määrittäneet useita moduuleja yhdessä tiedostossa. Kun moduulit kasvavat suuriksi, saatat haluta siirtää niiden määritelmät erillisiin tiedostoihin, jotta koodia olisi helpompi selata.

Esimerkiksi voimme aloittaa luvun 7-17 koodista, jossa oli useita ravintolaan liittyviä moduuleja. Siirrämme nämä moduulit erillisiin tiedostoihin sen sijaan, että määrittelisimme ne ohjelmakokonaisuuden juuritiedostossa. Tässä tapauksessa juuritiedosto on src/lib.rs, mutta sama menetelmä toimii myös binäärikokonaisuuksissa, joiden juuritiedosto on src/main.rs.

Ensimmäiseksi siirrämme front_of_house-moduulin omaan tiedostoonsa. Poista sen koodilohkon sisältö ja jätä vain mod front_of_house; -määrittely, jolloin src/lib.rs näyttää seuraavalta:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-21-and-22/src/lib.rs}}

Huomaa, että tämä ei käänny ennen kuin luomme tiedoston src/front_of_house.rs:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-21-and-22/src/front_of_house.rs}}

Rust tietää etsiä tätä tiedostoa, koska se löysi mod front_of_house;-määrittelyn ohjelmakokonaisuuden juurimoduulissa.

Huomioi, että mod-määrittely tarvitaan vain yhden kerran moduulipuussa. Kun kääntäjä tietää, että tiedosto kuuluu projektiin ja missä moduulipuussa se sijaitsee, muiden tiedostojen tulisi viitata siihen samalla tavoin kuin muihin moduuleihin – kuten käsiteltiin luvussa Polut moduulipuussa viittaamiseen. mod ei siis toimi kuten #include joissakin muissa ohjelmointikielissä.

Seuraavaksi siirrämme hosting-moduulin omaan tiedostoonsa. Koska hosting on front_of_house-moduulin lapsimoduuli eikä juurimoduuli, prosessi on hieman erilainen. Luomme hosting-tiedoston src/front_of_house-hakemistoon.

Aloitamme muuttamalla src/front_of_house.rs-tiedostoa niin, että se sisältää vain hosting-moduulin määrittelyn:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/no-listing-02-extracting-hosting/src/front_of_house.rs}}

Seuraavaksi luomme uuden src/front_of_house/hosting.rs-tiedoston ja siirrämme hosting-moduulin koodin sinne:

{{#rustdoc_include ../listings/ch07-managing-growing-projects/no-listing-02-extracting-hosting/src/front_of_house/hosting.rs}}

Jos hosting.rs sijaitsisi suoraan src-hakemistossa, kääntäjä olettaisi sen olevan ohjelmakokonaisuuden juurimoduulin hosting-moduuli eikä front_of_house-moduulin lapsimoduuli. Tämä tarkoittaa, että kääntäjän säännöt tiedostojen sijoittelusta vastaavat moduulipuuta.

Nyt jokainen moduuli on siirretty omaan tiedostoonsa, mutta moduulipuu pysyy muuttumattomana. eat_at_restaurant-funktion kutsut toimivat edelleen ilman muutoksia, vaikka määrittelyt ovat eri tiedostoissa. Tämä menetelmä mahdollistaa moduulien siirtämisen uusiin tiedostoihin niiden kasvaessa ilman, että koodia tarvitsee muuttaa merkittävästi.

Huomaa, että src/lib.rs:ssä oleva pub use crate::front_of_house::hosting-määrittely ei ole muuttunut, eikä use vaikuta siihen, mitkä tiedostot käännetään osana ohjelmakokonaisuutta. mod-avainsana määrittää moduulit, ja Rust etsii moduulin nimeä vastaavasta tiedostosta sen koodin.

Yhteenveto

Rust mahdollistaa paketin jakamisen useisiin ohjelmakokonaisuuksiin (crates) ja ohjelmakokonaisuuden jakamisen moduuleihin, jotta eri moduuleihin määriteltyihin kohteisiin voidaan viitata toisista moduuleista. Tämä voidaan tehdä käyttämällä absoluuttisia tai suhteellisia polkuja. use-avainsanalla polku voidaan tuoda laajuuteen, jolloin sitä voidaan käyttää lyhyemmällä muodolla. Moduulin koodi on oletuksena yksityistä, mutta sen määrittelyt voidaan tehdä julkisiksi lisäämällä pub-avainsana.

Seuraavassa luvussa tutustumme Rustin standardikirjaston kokoelmatietorakenteisiin, joita voit käyttää järjestelmällisessä koodissasi.

Yleiset kokoelmat

Rustin standardikirjasto sisältää joukon erittäin hyödyllisiä tietorakenteita, joita kutsutaan kokoelmiksi (collections). Useimmat muut tietotyypit edustavat yksittäistä arvoa, mutta kokoelmat voivat sisältää useita arvoja. Toisin kuin sisäänrakennetut taulukot (arrays) ja tuplet (tuples), näiden kokoelmien osoittama data tallennetaan kekoon (heap). Tämä tarkoittaa, että tietomäärää ei tarvitse tietää kääntäjän aikana, ja se voi kasvaa tai pienentyä ohjelman suorituksen aikana. Jokaisella kokoelmalla on omat ominaisuutensa ja kustannuksensa, ja sopivan kokoelman valitseminen kuhunkin tilanteeseen on taito, jonka kehität ajan myötä. Tässä luvussa käsittelemme kolmea Rust-ohjelmissa usein käytettyä kokoelmaa:

• Vektori (vector) mahdollistaa muuttuvan määrän arvoja, jotka sijaitsevat vierekkäin muistissa.
• Merkkijono (string) on kokoelma merkkejä. Olemme aiemmin maininneet String-tyypin, mutta tässä luvussa perehdymme siihen tarkemmin.
• Hajautustaulu (hash map) mahdollistaa arvojen yhdistämisen tiettyihin avaimiin. Se on erityinen toteutus yleisemmästä tietorakenteesta, jota kutsutaan mapiksi.

Jos haluat oppia lisää Rustin tarjoamista muista kokoelmista, katso dokumentaatio.

Tässä luvussa käymme läpi, miten luodaan ja päivitetään vektoreita, merkkijonoja ja hajautustauluja sekä mikä tekee kustakin erityisen.

Arvojen listojen tallentaminen vektoreilla

Arvojen listojen tallentaminen vektoreilla

Ensimmäinen kokoelmatyyppi, jota tarkastelemme, on Vec<T>, joka tunnetaan myös vektorina. Vektorit antavat sinun tallentaa useamman kuin yhden arvon yhteen tietorakenteeseen, joka sijoittaa kaikki arvot vierekkäin muistiin. Vektorit voivat tallentaa vain saman tyyppisiä arvoja. Ne ovat hyödyllisiä, kun sinulla on luettelo kohteita, kuten tiedoston tekstirivit tai ostoskorin tuotteiden hinnat.

Uuden vektorin luominen

Luodaksesi uuden tyhjän vektorin kutsumme Vec::new-funktiota, kuten listauksessa 8-1.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-01/src/main.rs:here}}
}

Huomaa, että lisäsimme tähän tyyppimerkinnän. Koska emme lisää mitään arvoja tähän vektoriin, Rust ei tiedä, millaisia elementtejä aiot tallentaa. Tämä on tärkeä kohta. Vektorit on toteutettu geneerisillä tyypeillä; käsittelemme geneeristen tyyppien käyttöä omissa tyypeissäsi luvussa 10. Toistaiseksi tiedä, että standardikirjaston tarjoama Vec<T>-tyyppi voi tallentaa minkä tahansa tyypin. Kun luomme vektorin tietyn tyypin tallentamiseksi, voimme määrittää tyypin kulmasuluissa. Listauksessa 8-1 olemme kertoneet Rustille, että v:n Vec<T> tallentaa i32-tyyppisiä elementtejä.

Useammin luot Vec<T>:n alkuarvoilla, ja Rust päättelee tallennettavan arvon tyypin, joten harvoin tarvitset tehdä tämän tyyppimerkinnän. Rust tarjoaa kätevästi vec!-makron, joka luo uuden vektorin, joka tallentaa antamasi arvot. Listaus 8-2 luo uuden Vec<i32>:n, joka tallentaa arvot 1, 2 ja 3. Kokonaislukutyyppi on i32, koska se on oletuskokonaislukutyyppi, kuten käsittelimme ”Tietotyypit” -kohdassa luvussa 3.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-02/src/main.rs:here}}
}

Koska olemme antaneet alkuperäiset i32-arvot, Rust voi päätellä, että v:n tyyppi on Vec<i32>, eikä tyyppimerkintää tarvita. Seuraavaksi tarkastelemme, miten vektoria muokataan.

Vektorin päivittäminen

Luodaksesi vektorin ja lisätäksesi siihen elementtejä voimme käyttää push-metodia, kuten listauksessa 8-3.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-03/src/main.rs:here}}
}

Kuten minkä tahansa muuttujan kanssa, jos haluamme pystyä muuttamaan sen arvoa, meidän on tehtävä se muuttuvaksi mut-avainsanalla, kuten käsittelimme luvussa 3. Sisällyttämämme luvut ovat kaikki i32-tyyppiä, ja Rust päättelee tämän datasta, joten Vec<i32>-merkintää ei tarvita.

Vektorin elementtien lukeminen

On kaksi tapaa viitata vektoriin tallennettuun arvoon: indeksoinnilla tai get-metodilla. Seuraavissa esimerkeissä olemme merkinneet näiden funktioiden palauttamat arvot selkeyden vuoksi.

Listaus 8-4 näyttää molemmat tavat käyttää arvoa vektorissa, indeksointisyntaksilla ja get-metodilla.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-04/src/main.rs:here}}
}

Huomaa muutamia yksityiskohtia. Käytämme indeksiarvoa 2 saadaksemme kolmannen elementin, koska vektorit indeksoidaan numerolla alkaen nollasta. &- ja []-merkkien käyttö antaa meille viitteen elementtiin indeksiarvolla. Kun käytämme get-metodia indeksin välittämiseksi argumenttina, saamme Option<&T>:n, jota voimme käyttää match:in kanssa.

Rust tarjoaa nämä kaksi tapaa viitata elementtiin, jotta voit valita, miten ohjelma käyttäytyy, kun yrität käyttää indeksiarvoa olemassa olevien elementtien alueen ulkopuolella. Esimerkkinä katsotaan, mitä tapahtuu, kun meillä on viisi elementtiä sisältävä vektori ja yritämme sitten käyttää elementtiä indeksissä 100 kummallakin tekniikalla, kuten listauksessa 8-5.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-05/src/main.rs:here}}
}

Kun suoritamme tämän koodin, ensimmäinen []-metodi aiheuttaa ohjelman paniikin, koska se viittaa olemattomaan elementtiin. Tätä metodia kannattaa käyttää, kun haluat ohjelmasi kaatuvan, jos yritetään käyttää elementtiä vektorin lopun jälkeen.

Kun get-metodille välitetään indeksi, joka on vektorin ulkopuolella, se palauttaa None:n panikoimatta. Käyttäisit tätä metodia, jos elementin käyttäminen vektorin alueen ulkopuolella voi tapahtua satunnaisesti normaaleissa olosuhteissa. Koodissasi on sitten logiikka käsitellä joko Some(&element) tai None, kuten käsittelimme luvussa 6. Esimerkiksi indeksi voi tulla käyttäjältä, joka syöttää numeron. Jos he vahingossa syöttävät liian suuren numeron ja ohjelma saa None-arvon, voisit kertoa käyttäjälle, kuinka monta kohdetta nykyisessä vektorissa on, ja antaa heille uuden mahdollisuuden syöttää kelvollinen arvo. Se olisi käyttäjäystävällisempää kuin ohjelman kaatuminen kirjoitusvirheen vuoksi!

Kun ohjelmalla on kelvollinen viite, lainauskontrolleri valvoo omistus- ja lainaussääntöjä (käsiteltiin luvussa 4) varmistaakseen, että tämä viite ja kaikki muut viitteet vektorin sisältöön pysyvät kelvollisina. Muista sääntö, jonka mukaan et voi olla muuttuvia ja muuttumattomia viitteitä samassa laajuudessa. Tämä sääntö pätee listauksessa 8-6, jossa pidämme muuttumatonta viitettä vektorin ensimmäiseen elementtiin ja yritämme lisätä elementin loppuun. Tämä ohjelma ei toimi, jos yritämme myös viitata kyseiseen elementtiin myöhemmin funktiossa.

{{#rustdoc_include ../listings/ch08-common-collections/listing-08-06/src/main.rs:here}}

Tämän koodin kääntäminen tuottaa tämän virheen:

{{#include ../listings/ch08-common-collections/listing-08-06/output.txt}}

Listauksen 8-6 koodi saattaa näyttää siltä, että sen pitäisi toimia: Miksi viitteen ensimmäiseen elementtiin pitäisi välittää muutoksista vektorin lopussa? Tämä virhe johtuu siitä, miten vektorit toimivat: Koska vektorit sijoittavat arvot vierekkäin muistiin, uuden elementin lisääminen vektorin loppuun saattaa vaatia uuden muistin varaamista ja vanhojen elementtien kopioimista uuteen tilaan, jos ei ole tarpeeksi tilaa sijoittaa kaikki elementit vierekkäin sinne, missä vektori on tällä hetkellä tallennettuna. Siinä tapauksessa viite ensimmäiseen elementtiin osoittaisi vapautettuun muistiin. Lainaussäännöt estävät ohjelmia päätymästä tällaiseen tilanteeseen.

Huom: Lisätietoja Vec<T>-tyypin toteutustiedoista on kohdassa ”Rustonomicon”.

Vektorin arvojen läpikäynti

Käyttääksemme jokaista vektorin elementtiä vuorollaan, käymme läpi kaikki elementit sen sijaan, että käyttäisimme indeksejä yksi kerrallaan. Listaus 8-7 näyttää, miten käyttää for-silmukkaa saadaksesi muuttumattomia viitteitä jokaiseen i32-arvojen vektorin elementtiin ja tulostaaksesi ne.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-07/src/main.rs:here}}
}

Voimme myös käydä läpi muuttuvia viitteitä jokaiseen muuttuvan vektorin elementtiin tehdäksemme muutoksia kaikkiin elementteihin. Listauksen 8-8 for-silmukka lisää 50 jokaiseen elementtiin.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-08/src/main.rs:here}}
}

Muuttaaksemme arvoa, johon muuttuva viite viittaa, meidän on käytettävä *-dereferointioperaattoria päästäksemme i:n arvoon ennen kuin voimme käyttää +=-operaattoria. Käsittelemme dereferointioperaattoria tarkemmin kohdassa ”Viittauksen seuraaminen arvoon” luvussa 15.

Vektorin läpikäynti, olipa muuttumattomasti tai muuttuvasti, on turvallista lainauskontrollerin sääntöjen ansiosta. Jos yrittäisimme lisätä tai poistaa kohteita listauksen 8-7 ja listauksen 8-8 for-silmukoiden rungoissa, saisimme kääntäjän virheen, joka on samanlainen kuin listauksen 8-6 koodilla. for-silmukan pitämä viite vektoriin estää koko vektorin samanaikaisen muokkaamisen.

Enumin käyttö useiden tyyppien tallentamiseen

Vektorit voivat tallentaa vain saman tyyppisiä arvoja. Tämä voi olla hankalaa; on ehdottomasti käyttötapauksia, joissa tarvitaan eri tyyppisten kohteiden luettelon tallentaminen. Onneksi enum-variantit on määritelty saman enum-tyypin alle, joten kun tarvitsemme yhden tyypin edustamaan eri tyyppisiä elementtejä, voimme määritellä ja käyttää enumia!

Esimerkiksi oletetaan, että haluamme saada arvoja taulukkolaskentataulukon riviltä, jossa jotkin rivin sarakkeet sisältävät kokonaislukuja, jotkut liukulukuja ja jotkut merkkijonoja. Voimme määritellä enumin, jonka variantit tallentavat eri arvotyyppejä, ja kaikki enum-variantit katsotaan samaksi tyypiksi: enumin tyypiksi. Sitten voimme luoda vektorin, joka tallentaa kyseisen enumin ja siten lopulta eri tyyppejä. Olemme havainnollistaneet tämän listauksessa 8-9.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-09/src/main.rs:here}}
}

Rustin on tiedettävä käännösaikana, mitä tyyppejä vektorissa on, jotta se tietää tarkalleen, kuinka paljon muistia keossa tarvitaan jokaisen elementin tallentamiseen. Meidän on myös oltava eksplisiittisiä siitä, mitkä tyypit ovat sallittuja tässä vektorissa. Jos Rust sallisi vektorin sisältää mitä tahansa tyyppiä, olisi mahdollista, että yksi tai useampi tyypeistä aiheuttaisi virheitä vektorin elementeille suoritettavissa operaatioissa. Enumin ja match-lausekkeen käyttö tarkoittaa, että Rust varmistaa käännösaikana, että jokainen mahdollinen tapaus käsitellään, kuten käsittelimme luvussa 6.

Jos et tiedä kattavaa joukkoa tyyppejä, joita ohjelma saa ajonaikana tallennettavaksi vektoriin, enum-tekniikka ei toimi. Sen sijaan voit käyttää trait-objektia, jota käsittelemme luvussa 18.

Nyt kun olemme käsitelleet joitakin yleisimpiä tapoja käyttää vektoreita, muista tutustua API-dokumentaatioon kaikista hyödyllisistä metodeista, jotka standardikirjasto on määritellyt Vec<T>:lle. Esimerkiksi push:n lisäksi pop-metodi poistaa ja palauttaa viimeisen elementin.

Vektorin pudottaminen pudottaa sen elementit

Kuten mikä tahansa muu struct, vektori vapautetaan, kun se poistuu laajuudesta, kuten listauksessa 8-10.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-10/src/main.rs:here}}
}

Kun vektori pudotetaan, kaikki sen sisältö pudotetaan myös, eli sen sisältämät kokonaisluvut siivotaan. Lainauskontrolleri varmistaa, että viitteitä vektorin sisältöön käytetään vain niin kauan kuin vektori itse on kelvollinen.

Siirrytään seuraavaan kokoelmatyyppiin: String!

UTF-8-koodattujen tekstien tallentaminen merkkijonoilla

UTF-8-koodatun tekstin tallentaminen merkkijonoilla

Käsittelimme merkkijonoja luvussa 4, mutta tarkastelemme niitä nyt syvällisemmin. Uudet rustilaiset jäävät usein jumiin merkkijonoihin kolmen syyn yhdistelmän vuoksi: Rustin taipumus paljastaa mahdolliset virheet, merkkijonojen oleminen monimutkaisempia tietorakenteita kuin monet ohjelmoijat antavat niille tunnustusta, ja UTF-8. Nämä tekijät yhdistyvät tavalla, joka voi tuntua vaikealta, kun tulet muista ohjelmointikielistä.

Käsittelemme merkkijonoja kokoelmien yhteydessä, koska merkkijonot on toteutettu tavujen kokoelmana plus joitakin metodeja hyödyllisen toiminnallisuuden tarjoamiseksi, kun näitä tavuja tulkitaan tekstinä. Tässä osiossa käsittelemme String-tyypin operaatioita, joita jokaisella kokoelmatyypillä on, kuten luominen, päivittäminen ja lukeminen. Käsittelemme myös tapoja, joilla String eroaa muista kokoelmista, nimittäin sitä, miten String-tyyppiin indeksointi on monimutkaista ihmisten ja tietokoneiden eri tulkintojen vuoksi String-datasta.

Merkkijonojen määrittely

Määrittelemme ensin, mitä tarkoitamme termillä merkkijono. Rustissa on vain yksi merkkijonotyyppi ydinkielessä, joka on merkkijonoviipale str, joka nähdään yleensä lainatussa muodossaan &str. Luvussa 4 käsittelimme merkkijonoviipaleita, jotka ovat viittauksia jossain muualla tallennettuun UTF-8-koodattuun merkkijonodataan. Merkkijonoliteraalit, esimerkiksi, tallennetaan ohjelman binääritiedostoon ja ovat siksi merkkijonoviipaleita.

String-tyyppi, jonka Rustin standardikirjasto tarjoaa eikä ydinkieli koodaa, on kasvava, muuttuva, omistettu, UTF-8-koodattu merkkijonotyyppi. Kun rustilaiset viittaavat Rustissa ”merkkijonoihin”, he saattavat viitata joko String- tai merkkijonoviipaletyyppiin &str, ei vain toiseen näistä tyypeistä. Vaikka tämä osio käsittelee pääasiassa String:ia, molempia tyyppejä käytetään runsaasti Rustin standardikirjastossa, ja sekä String että merkkijonoviipaleet ovat UTF-8-koodattuja.

Uuden merkkijonon luominen

Monet samat operaatiot, jotka ovat saatavilla Vec<T>:n kanssa, ovat saatavilla myös String:in kanssa, koska String on itse asiassa toteutettu tavujen vektorin kääreenä joillakin ylimääräisillä takuilla, rajoituksilla ja ominaisuuksilla. Esimerkki funktiosta, joka toimii samalla tavalla Vec<T>:n ja String:in kanssa, on new-funktio instanssin luomiseen, kuten listauksessa 8-11.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-11/src/main.rs:here}}
}

Tämä rivi luo uuden tyhjän merkkijonon nimeltä s, johon voimme sitten ladata dataa. Usein meillä on joitakin alkudataa, joilla haluamme aloittaa merkkijonon. Tätä varten käytämme to_string-metodia, joka on saatavilla millä tahansa tyypillä, joka toteuttaa Display-traitin, kuten merkkijonoliteraalit. Listaus 8-12 näyttää kaksi esimerkkiä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-12/src/main.rs:here}}
}

Tämä koodi luo merkkijonon, joka sisältää initial contents.

Voimme myös käyttää funktiota String::from luodaksemme String:in merkkijonoliteraalista. Listauksen 8-13 koodi on vastaava listauksen 8-12 koodille, joka käyttää to_string:ia.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-13/src/main.rs:here}}
}

Koska merkkijonoja käytetään niin moniin asioihin, voimme käyttää monia erilaisia geneerisiä API:ja merkkijonoille, mikä tarjoaa meille paljon vaihtoehtoja. Jotkut niistä saattavat vaikuttaa tarpeettomilta, mutta niillä kaikilla on paikkansa! Tässä tapauksessa String::from ja to_string tekevät saman asian, joten kumpi valitset on tyyli- ja luettavuuskysymys.

Muista, että merkkijonot ovat UTF-8-koodattuja, joten voimme sisällyttää niihin mitä tahansa oikein koodattua dataa, kuten listauksessa 8-14.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-14/src/main.rs:here}}
}

Kaikki nämä ovat kelvollisia String-arvoja.

Merkkijonon päivittäminen

String voi kasvaa kooltaan ja sen sisältö voi muuttua, aivan kuten Vec<T>:n sisältö, jos työnnät siihen lisää dataa. Lisäksi voit kätevästi käyttää +-operaattoria tai format!-makroa String-arvojen yhdistämiseen.

Liittäminen push_str:lla tai push:lla

Voimme kasvattaa String:ia käyttämällä push_str-metodia liittääksemme merkkijonoviipaleen, kuten listauksessa 8-15.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-15/src/main.rs:here}}
}

Näiden kahden rivin jälkeen s sisältää foobar. push_str-metodi ottaa merkkijonoviipaleen, koska emme välttämättä halua ottaa parametrin omistusta. Esimerkiksi listauksen 8-16 koodissa haluamme pystyä käyttämään s2:ta sen sisällön liittämisen jälkeen s1:een.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-16/src/main.rs:here}}
}

Jos push_str-metodi ottaisi s2:n omistuksen, emme voisi tulostaa sen arvoa viimeisellä rivillä. Tämä koodi kuitenkin toimii odotetusti!

push-metodi ottaa yhden merkin parametrina ja lisää sen String:iin. Listaus 8-17 lisää kirjaimen l String:iin push-metodilla.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-17/src/main.rs:here}}
}

Tuloksena s sisältää lol.

Yhdistäminen +:lla tai format!:lla

Usein haluat yhdistää kaksi olemassa olevaa merkkijonoa. Yksi tapa tehdä se on käyttää +-operaattoria, kuten listauksessa 8-18.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-18/src/main.rs:here}}
}

Merkkijono s3 sisältää Hello, world!. Syy siihen, miksi s1 ei ole enää kelvollinen lisäyksen jälkeen, ja syy siihen, miksi käytimme viitettä s2:een, liittyy metodin allekirjoitukseen, jota kutsutaan kun käytämme +-operaattoria. +-operaattori käyttää add-metodia, jonka allekirjoitus näyttää suunnilleen tältä:

fn add(self, s: &str) -> String {

Standardikirjastossa näet add:n määriteltynä geneerisillä tyypeillä ja assosioituilla tyypeillä. Tässä olemme korvanneet konkreettisilla tyypeillä, mikä tapahtuu kun kutsumme tätä metodia String-arvoilla. Käsittelemme geneerisiä tyyppejä luvussa 10. Tämä allekirjoitus antaa meille vihjeet, joita tarvitsemme +-operaattorin hankalien osien ymmärtämiseksi.

Ensinnäkin s2:lla on &, mikä tarkoittaa, että lisäämme viitteen toisesta merkkijonosta ensimmäiseen merkkijonoon. Tämä johtuu add-funktion s-parametrista: Voimme lisätä vain merkkijonoviipaleen String:iin; emme voi lisätä kahta String-arvoa yhteen. Mutta odota—&s2:n tyyppi on &String, ei &str, kuten add:n toisessa parametrissa määritellään. Miksi listaus 8-18 sitten kääntyy?

Syy siihen, miksi voimme käyttää &s2:ta add-kutsussa, on se, että kääntäjä voi pakottaa &String-argumentin muotoon &str. Kun kutsumme add-metodia, Rust käyttää dereferointipakkoa, joka tässä muuttaa &s2:n muotoon &s2[..]. Käsittelemme dereferointipakkoa tarkemmin luvussa 15. Koska add ei ota s-parametrin omistusta, s2 on edelleen kelvollinen String tämän operaation jälkeen.

Toiseksi allekirjoituksesta näemme, että add ottaa self:n omistuksen, koska self:llä ei ole &:ia. Tämä tarkoittaa, että s1 listauksessa 8-18 siirretään add-kutsuun eikä ole enää kelvollinen sen jälkeen. Joten vaikka let s3 = s1 + &s2; näyttää siltä, että se kopioisi molemmat merkkijonot ja loisi uuden, tämä lause itse asiassa ottaa s1:n omistuksen, liittää kopion s2:n sisällöstä ja palauttaa tuloksen omistuksen. Toisin sanoen se näyttää tekevän paljon kopioita, mutta ei tee; toteutus on tehokkaampi kuin kopiointi.

Jos meidän on yhdistettävä useita merkkijonoja, +-operaattorin käyttäytyminen muuttuu hankalaksi:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/no-listing-01-concat-multiple-strings/src/main.rs:here}}
}

Tässä vaiheessa s on tic-tac-toe. Kaikkien +- ja "-merkkien kanssa on vaikea nähdä, mitä tapahtuu. Monimutkaisempien merkkijonoyhdistelmien tekemiseen voimme sen sijaan käyttää format!-makroa:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/no-listing-02-format/src/main.rs:here}}
}

Tämä koodi asettaa myös s:n arvoksi tic-tac-toe. format!-makro toimii kuten println!, mutta tulostaa tulosteen näytölle sen sijaan, että se palauttaa String:in sisällöllä. format!-makroa käyttävä versio on paljon helpompi lukea, ja format!-makron generoima koodi käyttää viitteitä, joten tämä kutsu ei ota omistusta mistään parametreistään.

Merkkijonoon indeksointi

Monissa muissa ohjelmointikielissä yksittäisten merkkien käyttäminen merkkijonosta viittaamalla niihin indeksillä on kelvollinen ja yleinen operaatio. Jos kuitenkin yrität käyttää String:in osia indeksointisyntaksilla Rustissa, saat virheen. Harkitse kelvotonta koodia listauksessa 8-19.

{{#rustdoc_include ../listings/ch08-common-collections/listing-08-19/src/main.rs:here}}

Tämä koodi tuottaa seuraavan virheen:

{{#include ../listings/ch08-common-collections/listing-08-19/output.txt}}

Virhe kertoo tarinan: Rust-merkkijonot eivät tue indeksointia. Mutta miksi ei? Vastataksemme tähän kysymykseen meidän on käsiteltävä, miten Rust tallentaa merkkijonot muistiin.

Sisäinen esitys

String on kääre Vec<u8>:n ympärillä. Katsotaan joitakin oikein koodattuja UTF-8-esimerkkimerkkijonojamme listauksesta 8-14. Ensin tämä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-14/src/main.rs:spanish}}
}

Tässä tapauksessa len on 4, mikä tarkoittaa, että merkkijonoa "Hola" tallentava vektori on 4 tavua pitkä. Jokainen näistä kirjaimista vie 1 tavun UTF-8-koodauksessa. Seuraava rivi saattaa kuitenkin yllättää (huomaa, että tämä merkkijono alkaa kyrillisen isolla kirjaimella Ze, ei numerolla 3):

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-14/src/main.rs:russian}}
}

Jos sinulta kysyttäisiin, kuinka pitkä merkkijono on, saatat sanoa 12. Itse asiassa Rustin vastaus on 24: se on tavujen määrä, joita tarvitaan ”Здравствуйте”:n koodaamiseen UTF-8:ssa, koska jokainen Unicode-skaalaarvo kyseisessä merkkijonossa vie 2 tavua tallennustilaa. Siksi indeksi merkkijonon tavuissa ei aina vastaa kelvollista Unicode-skaalaarvoa. Havainnollistaaksemme, harkitse tätä kelvotonta Rust-koodia:

let hello = "Здравствуйте";
let answer = &hello[0];

Tiedät jo, että answer ei ole З, ensimmäinen kirjain. Kun З on koodattu UTF-8:ssa, ensimmäinen tavu on 208 ja toinen on 151, joten näyttäisi siltä, että answer:n pitäisi olla 208, mutta 208 ei ole kelvollinen merkki yksinään. 208:n palauttaminen ei todennäköisesti ole sitä, mitä käyttäjä haluaisi, jos he pyytäisivät tämän merkkijonon ensimmäistä kirjainta; kuitenkin se on ainoa data, joka Rustilla on tavuindeksissä 0. Käyttäjät eivät yleensä halua tavuarvoa palautettavaksi, vaikka merkkijono sisältäisi vain latinalaisia kirjaimia: Jos &"hi"[0] olisi kelvollista koodia, joka palauttaisi tavuarvon, se palauttaisi 104:n, ei h:ta.

Vastaus on siis, että odottamattoman arvon palauttamisen ja virheiden estämiseksi, joita ei ehkä huomata heti, Rust ei käännä tätä koodia lainkaan ja estää väärinkäsitykset varhaisessa kehitysvaiheessa.

Tavut, skaalaarvot ja grafeemiklusterit

Toinen kohta UTF-8:sta on, että Rustin näkökulmasta merkkijonoihin on itse asiassa kolme relevanttia tapaa katsoa: tavuina, skaalaarvoina ja grafeemiklustereina (lähin vastine sille, mitä kutsumme kirjaimiksi).

Jos katsomme hindinkielistä sanaa ”नमस्ते”, joka on kirjoitettu devanagari-kirjaimistolla, se tallennetaan u8-arvojen vektorina, joka näyttää tältä:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Se on 18 tavua ja näin tietokoneet lopulta tallentavat tämän datan. Jos katsomme niitä Unicode-skaalaarvoina, jotka ovat Rustin char-tyyppi, nämä tavut näyttävät tältä:

['न', 'म', 'स', '्', 'त', 'े']

Tässä on kuusi char-arvoa, mutta neljäs ja kuudes eivät ole kirjaimia: ne ovat diakriittisiä merkkejä, jotka eivät ole järkeviä yksinään. Lopuksi, jos katsomme niitä grafeemiklustereina, saisimme sen, mitä ihminen kutsuisi hindinkielisen sanan neljäksi kirjaimiksi:

["न", "म", "स्", "ते"]

Rust tarjoaa erilaisia tapoja tulkita raakaa merkkijonodataa, jota tietokoneet tallentavat, jotta jokainen ohjelma voi valita tarvitsemansa tulkinnan riippumatta siitä, millä ihmiskielellä data on.

Viimeinen syy siihen, miksi Rust ei salli meidän indeksoida String:iin saadaksemme merkin, on se, että indeksointi-operaatioiden odotetaan aina vievän vakiintuneen ajan (O(1)). Mutta tätä suorituskykyä ei ole mahdollista taata String:in kanssa, koska Rustin pitäisi käydä läpi sisältö alusta indeksiin määrittääkseen, kuinka monta kelvollista merkkiä siellä on.

Merkkijonoviipaleiden leikkaaminen

Merkkijonoon indeksointi on usein huono idea, koska ei ole selvää, mikä merkkijonon indeksointi-operaation palautustyypin pitäisi olla: tavu, merkki, grafeemiklusteri vai merkkijonoviipale. Jos todella tarvitset käyttää indeksejä merkkijonoviipaleiden luomiseen, Rust pyytää sinua olemaan tarkempi.

Sen sijaan, että indeksoisit []:lla yhdellä numerolla, voit käyttää []:a alueella luodaksesi merkkijonoviipaleen, joka sisältää tiettyjä tavuja:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Tässä s on &str, joka sisältää merkkijonon ensimmäiset 4 tavua. Aiemmin mainitsimme, että jokainen näistä merkeistä oli 2 tavua, mikä tarkoittaa, että s on Зд.

Jos yrittäisimme leikata vain osan merkin tavuista jollakin kuten &hello[0..1], Rust panikoisi ajonaikana samalla tavalla kuin jos virheellistä indeksiä käytettäisiin vektorissa:

{{#include ../listings/ch08-common-collections/output-only-01-not-char-boundary/output.txt}}

Sinun pitäisi olla varovainen luodessasi merkkijonoviipaleita alueilla, koska se voi kaataa ohjelmasi.

Merkkijonojen läpikäynti

Paras tapa käsitellä merkkijonon osia on olla eksplisiittinen siitä, haluatko merkkejä vai tavuja. Yksittäisille Unicode-skaalaarvoille käytä chars-metodia. chars:in kutsuminen merkkijonolla ”Зд” erottelee ja palauttaa kaksi char-tyyppistä arvoa, ja voit käydä tuloksen läpi käyttääksesi jokaista elementtiä:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Tämä koodi tulostaa seuraavan:

З
д

Vaihtoehtoisesti bytes-metodi palauttaa jokaisen raakatuvun, mikä saattaa olla sopivaa toimialallesi:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Tämä koodi tulostaa 4 tavua, jotka muodostavat tämän merkkijonon:

208
151
208
180

Muista kuitenkin, että kelvolliset Unicode-skaalaarvot voivat koostua useammasta kuin yhdestä tavusta.

Grafeemiklusterien saaminen merkkijonoista, kuten devanagari-kirjaimistolla, on monimutkaista, joten standardikirjasto ei tarjoa tätä toiminnallisuutta. Crate:t ovat saatavilla osoitteessa crates.io, jos tarvitset tätä toiminnallisuutta.

Merkkijonojen monimutkaisuuden käsittely

Yhteenvetona, merkkijonot ovat monimutkaisia. Eri ohjelmointikielet tekevät erilaisia valintoja siitä, miten esittää tämä monimutkaisuus ohjelmoijalle. Rust on valinnut tehdä String-datan oikeasta käsittelystä oletuskäyttäytymisen kaikille Rust-ohjelmille, mikä tarkoittaa, että ohjelmoijien on pohdittava UTF-8-datan käsittelyä etukäteen. Tämä kompromissi paljastaa enemmän merkkijonojen monimutkaisuutta kuin on ilmeistä muissa ohjelmointikielissä, mutta se estää sinua käsittelemästä ei-ASCII-merkkeihin liittyviä virheitä myöhemmin kehityssykliäsi.

Hyvä uutinen on, että standardikirjasto tarjoaa paljon toiminnallisuutta, joka on rakennettu String- ja &str-tyyppien päälle auttamaan käsittelemään näitä monimutkaisia tilanteita oikein. Muista tutustua dokumentaatioon hyödyllisistä metodeista, kuten contains merkkijonon etsimiseen ja replace merkkijonon osien korvaamiseen toisella merkkijonolla.

Siirrytään hieman vähemmän monimutkaiseen asiaan: hajautustaulukot!

Avainten tallentaminen liittyvine arvoineen hajautustaulukoissa

Avaimien tallentaminen liittyvine arvoineen hajautustaulukoissa

Viimeinen yleisistä kokoelmistamme on hajautustaulukko. Tyyppi HashMap<K, V> tallentaa avainten tyyppiä K olevien avainten ja arvojen tyyppiä V olevien arvojen välisen kuvauksen käyttämällä hajautusfunktiota, joka määrittää, miten nämä avaimet ja arvot sijoitetaan muistiin. Monet ohjelmointikielet tukevat tällaista tietorakennetta, mutta ne käyttävät usein eri nimeä, kuten hash, map, object, hash table, dictionary tai associative array, mainitakseni muutamia.

Hajautustaulukot ovat hyödyllisiä, kun haluat hakea dataa ei indeksillä, kuten vektoreilla, vaan avaimella, joka voi olla minkä tahansa tyyppinen. Esimerkiksi pelissä voisit seurata kunkin joukkueen pistemäärää hajautustaulukossa, jossa jokainen avain on joukkueen nimi ja arvot ovat kunkin joukkueen pisteet. Joukkueen nimen perusteella voit hakea sen pistemäärän.

Käymme läpi hajautustaulukoiden perus-API:n tässä osiossa, mutta HashMap<K, V>:lle standardikirjaston määrittelemissä funktioissa piilee paljon muutakin hyödyllistä. Kuten aina, tarkista standardikirjaston dokumentaatio lisätietoja varten.

Uuden hajautustaulukon luominen

Yksi tapa luoda tyhjä hajautustaulukko on käyttää new:ia ja lisätä elementtejä insert:illä. Listauksessa 8-20 seuraamme kahden joukkueen, joiden nimet ovat Blue ja Yellow, pistemääriä. Blue-joukkue aloittaa 10 pisteellä ja Yellow-joukkue 50 pisteellä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-20/src/main.rs:here}}
}

Huomaa, että meidän on ensin use:ttava HashMap standardikirjaston collections-osasta. Kolmesta yleisestä kokoelmastamme tämä on vähiten käytetty, joten sitä ei sisällytetä automaattisesti preludiin tuotuihin ominaisuuksiin. Hajautustaulukoilla on myös vähemmän tukea standardikirjastosta; ei ole esimerkiksi sisäänrakennettua makroa niiden rakentamiseen.

Kuten vektorit, hajautustaulukot tallentavat datansa kekoon. Tällä HashMap:illa on avaimia tyyppiä String ja arvoja tyyppiä i32. Kuten vektorit, hajautustaulukot ovat homogeenisia: kaikkien avainten on oltava samaa tyyppiä, ja kaikkien arvojen on oltava samaa tyyppiä.

Hajautustaulukon arvojen käyttö

Voimme saada arvon hajautustaulukosta antamalla sen avaimen get-metodille, kuten listauksessa 8-21.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-21/src/main.rs:here}}
}

Tässä score:lla on arvo, joka liittyy Blue-joukkueeseen, ja tulos on 10. get-metodi palauttaa Option<&V>:n; jos hajautustaulukossa ei ole arvoa kyseiselle avaimelle, get palauttaa None:n. Tämä ohjelma käsittelee Option:in kutsumalla copied:ia saadakseen Option<i32>:n Option<&i32>:n sijaan, sitten unwrap_or:ia asettaakseen score:n nollaksi, jos scores:issa ei ole merkintää avaimelle.

Voimme käydä läpi jokaisen avain-arvo-parin hajautustaulukossa samalla tavalla kuin vektoreilla käyttämällä for-silmukkaa:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs:here}}
}

Tämä koodi tulostaa jokaisen parin satunnaisessa järjestyksessä:

Yellow: 50
Blue: 10

Omistuksen hallinta hajautustaulukoissa

Copy-traitin toteuttaville tyypeille, kuten i32, arvot kopioidaan hajautustaulukkoon. Omistetuille arvoille, kuten String, arvot siirretään ja hajautustaulukko on niiden omistaja, kuten listauksessa 8-22 havainnollistetaan.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-22/src/main.rs:here}}
}

Emme voi käyttää muuttujia field_name ja field_value sen jälkeen, kun ne on siirretty hajautustaulukkoon insert-kutsulla.

Jos lisäämme viittauksia arvoihin hajautustaulukkoon, arvoja ei siirretä hajautustaulukkoon. Arvojen, joihin viitteet osoittavat, on oltava kelvollisia vähintään niin kauan kuin hajautustaulukko on kelvollinen. Käsittelemme näitä ongelmia tarkemmin kohdassa ”Viittausten validointi elinaikoilla” luvussa 10.

Hajautustaulukon päivittäminen

Vaikka avain-arvo-parien määrä on kasvava, jokaisella yksilöllisellä avaimella voi olla vain yksi siihen liittyvä arvo kerrallaan (mutta ei päinvastoin: esimerkiksi sekä Blue- että Yellow-joukkueella voi olla arvo 10 tallennettuna scores-hajautustaulukkoon).

Kun haluat muuttaa dataa hajautustaulukossa, sinun on päätettävä, miten käsitellä tapaus, jossa avaimella on jo arvo. Voit korvata vanhan arvon uudella arvolla täysin sivuuttaen vanhan arvon. Voit pitää vanhan arvon ja jättää huomiotta uuden arvon, lisäten uuden arvon vain, jos avaimella ei jo ole arvoa. Tai voit yhdistää vanhan arvon ja uuden arvon. Katsotaan, miten tehdä kukin näistä!

Arvon korvaaminen

Jos lisäämme avaimen ja arvon hajautustaulukkoon ja lisäämme sitten saman avaimen eri arvolla, avaimeen liittyvä arvo korvataan. Vaikka listauksen 8-23 koodi kutsuu insert:ia kahdesti, hajautustaulukossa on vain yksi avain-arvo-pari, koska lisäämme Blue-joukkueen avaimen arvon molemmilla kerroilla.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-23/src/main.rs:here}}
}

Tämä koodi tulostaa {"Blue": 25}. Alkuperäinen arvo 10 on korvattu.

Avaimen ja arvon lisääminen vain, jos avaimella ei ole arvoa

On yleistä tarkistaa, onko tietyllä avaimella jo arvo hajautustaulukossa, ja sitten toimia seuraavasti: Jos avain on olemassa hajautustaulukossa, olemassa olevan arvon pitäisi pysyä ennallaan; jos avainta ei ole, lisää se ja sille arvo.

Hajautustaulukoilla on tähän erityinen API nimeltä entry, joka ottaa parametrina avaimen, jonka haluat tarkistaa. entry-metodin palautusarvo on enum nimeltä Entry, joka edustaa arvoa, joka saattaa olla olemassa tai ei. Oletetaan, että haluamme tarkistaa, onko Yellow-joukkueen avaimella arvo. Jos ei ole, haluamme lisätä arvon 50, ja sama Blue-joukkueelle. entry-API:ta käyttäen koodi näyttää listaukselta 8-24.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-24/src/main.rs:here}}
}

Entry:n or_insert-metodi on määritelty palauttamaan muuttuva viite vastaavan Entry-avaimen arvoon, jos kyseinen avain on olemassa, ja jos ei, se lisää parametrin uudeksi arvoksi tälle avaimelle ja palauttaa muuttuvan viitteen uuteen arvoon. Tämä tekniikka on paljon siistimpi kuin logiikan kirjoittaminen itse, ja lisäksi se toimii paremmin lainauskontrollerin kanssa.

Listauksen 8-24 koodin suorittaminen tulostaa {"Yellow": 50, "Blue": 10}. Ensimmäinen entry-kutsu lisää Yellow-joukkueen avaimen arvolla 50, koska Yellow-joukkueella ei ole vielä arvoa. Toinen entry-kutsu ei muuta hajautustaulukkoa, koska Blue-joukkueella on jo arvo 10.

Arvon päivittäminen vanhan arvon perusteella

Toinen yleinen käyttötapaus hajautustaulukoille on avaimen arvon hakeminen ja sen päivittäminen vanhan arvon perusteella. Esimerkiksi listaus 8-25 näyttää koodin, joka laskee, kuinka monta kertaa kukin sana esiintyy tekstissä. Käytämme hajautustaulukkoa, jossa sanat ovat avaimia, ja kasvatamme arvoa seurataksemme, kuinka monta kertaa olemme nähneet kyseisen sanan. Jos näemme sanan ensimmäistä kertaa, lisäämme ensin arvon 0.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-25/src/main.rs:here}}
}

Tämä koodi tulostaa {"world": 2, "hello": 1, "wonderful": 1}. Saatat nähdä samat avain-arvo-parit tulostettuna eri järjestyksessä: Muista kohdasta ”Hajautustaulukon arvojen käyttö”, että hajautustaulukon läpikäynti tapahtuu satunnaisessa järjestyksessä.

split_whitespace-metodi palauttaa iteraattorin aliviipaleista, jotka on erotettu välilyönneillä text:n arvosta. or_insert-metodi palauttaa muuttuvan viitteen (&mut V) määritellyn avaimen arvoon. Tässä tallennamme kyseisen muuttuvan viitteen count-muuttujaan, joten arvon asettamiseksi meidän on ensin dereferoitava count asteriskilla (*). Muuttuva viite poistuu laajuudesta for-silmukan lopussa, joten kaikki nämä muutokset ovat turvallisia ja lainaussääntöjen sallimia.

Hajautusfunktiot

Oletuksena HashMap käyttää hajautusfunktiota nimeltä SipHash, joka voi tarjota vastustuskykyä hajautustaulukoihin liittyviä palvelunestohyökkäyksiä (DoS) vastaan¹. Tämä ei ole nopein saatavilla oleva hajautusalgoritmi, mutta kompromissi paremman turvallisuuden ja suorituskyvyn laskun välillä on sen arvoinen. Jos profiloit koodisi ja huomaat, että oletushajautusfunktio on liian hidas tarkoituksiisi, voit vaihtaa toiseen funktioon määrittämällä eri hasherin. Hasher on tyyppi, joka toteuttaa BuildHasher-traitin. Käsittelemme trait:eja ja niiden toteuttamista luvussa 10. Sinun ei välttämättä tarvitse toteuttaa omaa hasheria alusta; crates.io -sivustolla on muiden Rust-käyttäjien jakamia kirjastoja, jotka tarjoavat hashereita toteuttaen monia yleisiä hajautusalgoritmeja.

Yhteenveto

Vektorit, merkkijonot ja hajautustaulukot tarjoavat paljon toiminnallisuutta, jota tarvitaan ohjelmissa, kun sinun on tallennettava, käytettävä ja muokattava dataa. Tässä on harjoituksia, joihin sinun pitäisi nyt olla valmis:

1. Annetulle kokonaislukulistalle käytä vektoria ja palauta mediaani (lajiteltuna arvo keskimmäisessä sijainnissa) ja moodi (arvo, joka esiintyy useimmin; hajautustaulukko on hyödyllinen tässä) listasta.
2. Muunna merkkijonot siansaksaksi. Jokaisen sanan ensimmäinen konsonantti siirretään sanan loppuun ja lisätään ay, joten first muuttuu muotoon irst-fay. Vokaalilla alkaviin sanoihin lisätään loppuun hay sen sijaan (apple muuttuu muotoon apple-hay). Muista UTF-8-koodauksen yksityiskohdat!
3. Käyttämällä hajautustaulukkoa ja vektoreita luo tekstipohjainen käyttöliittymä, jonka avulla käyttäjä voi lisätä työntekijöiden nimiä osastoon yrityksessä; esimerkiksi ”Add Sally to Engineering” tai ”Add Amir to Sales.” Anna sitten käyttäjän hakea luettelo kaikista osaston henkilöistä tai kaikista yrityksen henkilöistä osastoittain, lajiteltuna aakkosjärjestykseen.

Standardikirjaston API-dokumentaatio kuvaa vektoreiden, merkkijonojen ja hajautustaulukoiden metodeja, jotka ovat hyödyllisiä näissä harjoituksissa!

Siirrymme monimutkaisempiin ohjelmiin, joissa operaatiot voivat epäonnistua, joten on täydellinen hetki käsitellä virheenkäsittelyä. Teemme sen seuraavaksi!

1. https://en.wikipedia.org/wiki/SipHash ↩

Virheidenhallinta

Ohjelmistokehityksessä virheet ovat väistämättömiä, joten Rust tarjoaa useita tapoja käsitellä tilanteita, joissa jokin menee pieleen. Usein Rust vaatii sinua huomioimaan mahdollisen virheen ja käsittelemään sen ennen kuin koodisi voidaan kääntää. Tämä tekee ohjelmastasi vankemman, koska virheet havaitaan ja käsitellään ennen kuin koodi päätyy tuotantoon!

Rust jakaa virheet kahteen pääkategoriaan: palautettaviin (recoverable) ja palauttamattomiin (unrecoverable) virheisiin. Palautettavan virheen, kuten tiedostoa ei löydy -virheen, kohdalla haluamme yleensä ilmoittaa ongelmasta käyttäjälle ja yrittää toimintoa uudelleen. Palauttamattomat virheet ovat ohjelmointivirheiden oireita, kuten taulukon rajojen ylitys, ja näissä tapauksissa ohjelman on lopetettava välittömästi.

Useimmat ohjelmointikielet eivät tee eroa näiden kahden virhetyypin välillä, vaan käsittelevät molemmat samalla tavalla esimerkiksi poikkeusten (exceptions) avulla. Rust ei käytä poikkeuksia. Sen sijaan se tarjoaa Result<T, E>-tyypin palautettaville virheille ja panic!-makron, joka pysäyttää ohjelman palauttamattoman virheen kohdatessa.

Tässä luvussa käsittelemme ensin panic!-makron käyttöä ja sen jälkeen Result<T, E>-tyypin käyttöä virheiden käsittelyyn. Lopuksi pohdimme, milloin on järkevää yrittää palautua virheestä ja milloin ohjelma kannattaa pysäyttää kokonaan.

Palautumattomat virheet panic!-komennolla

Palauttamattomat virheet panic!-makrolla

Joskus koodissa tapahtuu jotain, mille emme voi tehdä mitään. Näissä tapauksissa Rust tarjoaa panic!-makron. panic! voidaan laukaista kahdella tavalla: joko suorittamalla virheellinen toiminto (kuten yrittämällä käyttää taulukon rajojen ulkopuolista indeksiä) tai kutsumalla panic!-makroa suoraan.

Molemmissa tapauksissa ohjelma pysäytetään ja tapahtuu paniikkitila (panic state). Oletusarvoisesti tämä tulostaa virheviestin, purkaa pinoon kertyneet kutsut (stack unwinding) ja lopettaa ohjelman. Ympäristömuuttujan avulla voidaan myös näyttää pinojäljitys (backtrace), mikä auttaa selvittämään, mistä virhe johtuu.

[profile.release]
panic = 'abort'

panic!-makron kutsuminen

Tarkastellaan yksinkertaista ohjelmaa, joka kutsuu panic!-makroa:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/no-listing-01-panic/src/main.rs}}
}

Kun ohjelma ajetaan, tulos näyttää tältä:

{{#include ../listings/ch09-error-handling/no-listing-01-panic/output.txt}}

Viimeiset kaksi riviä sisältävät panic!-viestin ja virheen sijainnin (src/main.rs:2:5 tarkoittaa src/main.rs-tiedoston toista riviä, viidettä merkkiä).

Jos panic! tapahtuu kirjastokoodissa, virheviesti voi näyttää tuntemattomalta. Voimme käyttää pinojäljitystä (backtrace) selvittääksemme, missä virhe tapahtui.

panic! ja pinojäljitys

Katsotaan esimerkkiä, jossa ohjelma yrittää käyttää taulukon rajojen ulkopuolista indeksiä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/listing-09-01/src/main.rs}}
}

Tässä yritämme käyttää 100. alkiota, mutta vektorissa on vain kolme alkiota. Tämä johtaa panic!-tilaan, koska Rust ei voi palauttaa kelvollista arvoa. Toisin kuin C-kielessä, jossa muistialueen ulkopuolinen luku voi aiheuttaa määrittelemätöntä käyttäytymistä (undefined behavior), Rust estää tällaiset tilanteet pysäyttämällä ohjelman.

Jos ajamme ohjelman, virhe näyttää tältä:

{{#include ../listings/ch09-error-handling/listing-09-01/output.txt}}

Virheilmoitus osoittaa virheellisen indeksin käytön ohjelman main.rs-tiedoston rivillä 4.

Rust tarjoaa pinojäljityksen, jonka avulla voi nähdä, mitkä funktiot johtivat panic!-kutsuun. Voit ottaa sen käyttöön asettamalla ympäristömuuttujan RUST_BACKTRACE=1:

$ RUST_BACKTRACE=1 cargo run

Tuloste näyttää jotain tämän kaltaista:

stack backtrace:
   0: rust_begin_unwind
             at /rustc/.../library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/.../library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/.../library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at /rustc/.../library/core/src/slice/index.rs:274:10
   4: panic::main
             at ./src/main.rs:4:6

Pinojäljityksessä tärkein rivi on src/main.rs:4:6, koska se osoittaa virheen sijainnin omassa koodissamme. Tämän tiedon avulla voimme korjata virheen estämällä taulukon rajojen ylityksen.

Rust estää useita muistivirheitä, joita esiintyy muissa kielissä, kuten buffer overread -haavoittuvuuksia. Jos yritämme käyttää olematonta taulukon kohtaa, Rust pysäyttää ohjelman, jotta virhe ei aiheuttaisi tietoturvaongelmia.

Seuraavaksi tarkastelemme, miten palautettavat virheet voidaan käsitellä käyttäen Result<T, E>-tyyppiä.

Palautuvat virheet Result-tyypillä

Palautuvat virheet Result:illa

Useimmat virheet eivät ole tarpeeksi vakavia vaatimaan ohjelman täydellistä pysäyttämistä. Joskus kun funktio epäonnistuu, syy on sellainen, jonka voit helposti tulkita ja vastata siihen. Esimerkiksi jos yrität avata tiedoston ja operaatio epäonnistuu, koska tiedostoa ei ole olemassa, saatat haluta luoda tiedoston sen sijaan, että lopettaisit prosessin.

Muista kohdasta ”Mahdollisen epäonnistumisen käsittely Result:illa” luvussa 2, että Result-enum on määritelty kahdella variantilla, Ok ja Err, seuraavasti:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T ja E ovat geneerisiä tyyppiparametreja: käsittelemme geneerisiä tyyppejä tarkemmin luvussa 10. Mitä sinun tarvitsee tietää nyt on, että T edustaa onnistumistapauksessa Ok-variantin sisällä palautettavan arvon tyyppiä, ja E edustaa epäonnistumistapauksessa Err-variantin sisällä palautettavan virheen tyyppiä. Koska Result:illa on nämä geneeriset tyyppiparametrit, voimme käyttää Result-tyyppiä ja siihen määriteltyjä funktioita monissa eri tilanteissa, joissa haluamme palauttaa erilaisia onnistumis- ja virhearvoja.

Kutsutaan funktiota, joka palauttaa Result-arvon, koska funktio voi epäonnistua. Listauksessa 9-3 yritämme avata tiedoston.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/listing-09-03/src/main.rs}}
}

File::open:n palautustyyppi on Result<T, E>. Geneerinen parametri T on täytetty File::open:n toteutuksessa onnistumisarvon tyypillä, std::fs::File, joka on tiedostokahva. Virhearvossa käytetty E-tyyppi on std::io::Error. Tämä palautustyyppi tarkoittaa, että File::open-kutsu voi onnistua ja palauttaa tiedostokahvan, josta voimme lukea tai kirjoittaa. Funktiokutsu voi myös epäonnistua: esimerkiksi tiedostoa ei ehkä ole olemassa, tai meillä ei ehkä ole oikeutta käyttää tiedostoa. File::open-funktiolla on oltava tapa kertoa meille, onnistuiko se vai epäonnistuiko, ja antaa meille joko tiedostokahva tai virhetiedot. Tämä tieto on juuri se, mitä Result-enum välittää.

Tapauksessa, jossa File::open onnistuu, muuttujan greeting_file_result arvo on Ok-instanssi, joka sisältää tiedostokahvan. Tapauksessa, jossa se epäonnistuu, muuttujan greeting_file_result arvo on Err-instanssi, joka sisältää lisätietoja tapahtuneesta virhetyypistä.

Meidän on lisättävä listauksen 9-3 koodiin toimia, jotka riippuvat File::open:n palauttamasta arvosta. Listaus 9-4 näyttää yhden tavan käsitellä Result:ia perustyökalulla, match-lausekkeella, jota käsittelimme luvussa 6.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/listing-09-04/src/main.rs}}
}

Huomaa, että kuten Option-enum, Result-enum ja sen variantit on tuotu laajuuteen preludin kautta, joten meidän ei tarvitse määrittää Result:: ennen Ok- ja Err-variantteja match-haaroissa.

Kun tulos on Ok, tämä koodi palauttaa sisäisen file-arvon Ok-variantista, ja sitten määritämme kyseisen tiedostokahvan arvon muuttujalle greeting_file. match:in jälkeen voimme käyttää tiedostokahvaa lukemiseen tai kirjoittamiseen.

match:in toinen haara käsittelee tapauksen, jossa saamme Err-arvon File::open:sta. Tässä esimerkissä olemme valinneet kutsua panic!-makroa. Jos nykyisessä hakemistossamme ei ole tiedostoa nimeltä hello.txt ja suoritamme tämän koodin, näemme seuraavan tulosteen panic!-makrosta:

{{#include ../listings/ch09-error-handling/listing-09-04/output.txt}}

Kuten tavallisesti, tämä tuloste kertoo meille tarkalleen, mikä meni pieleen.

Eri virheiden täsmäyttäminen

Listauksen 9-4 koodi kutsuu panic!:ia riippumatta siitä, miksi File::open epäonnistui. Haluamme kuitenkin toimia eri tavoin eri epäonnistumissyistä. Jos File::open epäonnistui, koska tiedostoa ei ole olemassa, haluamme luoda tiedoston ja palauttaa kahvan uudelle tiedostolle. Jos File::open epäonnistui jostain muusta syystä—esimerkiksi koska meillä ei ollut oikeutta avata tiedostoa—haluamme silti, että koodi kutsuu panic!:ia samalla tavalla kuin listauksessa 9-4. Tätä varten lisäämme sisäisen match-lausekkeen, kuten listauksessa 9-5.

{{#rustdoc_include ../listings/ch09-error-handling/listing-09-05/src/main.rs}}

File::open:n Err-variantin sisällä palauttaman arvon tyyppi on io::Error, joka on standardikirjaston tarjoama struct. Tällä structilla on metodi kind, jota voimme kutsua saadaksemme io::ErrorKind-arvon. Enum io::ErrorKind on standardikirjaston tarjoama ja sillä on variantteja, jotka edustavat erilaisia virhetyyppejä, jotka voivat johtua io-operaatiosta. Variantti, jota haluamme käyttää, on ErrorKind::NotFound, joka ilmaisee, että tiedostoa, jota yritämme avata, ei ole vielä olemassa. Joten täsmäytämme greeting_file_result:in, mutta meillä on myös sisäinen match error.kind():n päällä.

Ehto, jonka haluamme tarkistaa sisäisessä match:issa, on se, onko error.kind():n palauttama arvo ErrorKind-enumin NotFound-variantti. Jos on, yritämme luoda tiedoston File::create:lla. Koska File::create voi myös epäonnistua, tarvitsemme toisen haaran sisäiseen match-lausekkeeseen. Kun tiedostoa ei voida luoda, tulostetaan eri virheilmoitus. Ulomman match:in toinen haara pysyy samana, joten ohjelma panikoi kaikissa virheissä paitsi puuttuvan tiedoston virheessä.

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

Oikotiet paniikkiin virheessä

match:in käyttö toimii tarpeeksi hyvin, mutta se voi olla hieman sanallista eikä aina välitä aikomusta hyvin. Result<T, E>-tyypillä on monia apumetodeja, jotka on määritelty erilaisiin, tarkempiin tehtäviin. unwrap-metodi on oikotiemetodi, joka on toteutettu juuri kuten listauksessa 9-4 kirjoittamamme match-lauseke. Jos Result-arvo on Ok-variantti, unwrap palauttaa Ok:n sisällä olevan arvon. Jos Result on Err-variantti, unwrap kutsuu panic!-makroa puolestamme. Tässä on esimerkki unwrap:in toiminnasta:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/no-listing-04-unwrap/src/main.rs}}
}

Jos suoritamme tämän koodin ilman hello.txt-tiedostoa, näemme virheilmoituksen unwrap-metodin tekemästä panic!-kutsusta:

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Vastaavasti expect-metodi antaa meille myös valita panic!-virheilmoituksen. expect:in käyttäminen unwrap:in sijaan ja hyvien virheilmoitusten antaminen voi välittää aikomuksesi ja helpottaa paniikin lähteen jäljittämistä. expect:in syntaksi näyttää tältä:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/no-listing-05-expect/src/main.rs}}
}

Käytämme expect:ia samalla tavalla kuin unwrap:ia: palauttaaksemme tiedostokahvan tai kutsuaksemme panic!-makroa. expect:in panic!-kutsussa käytetty virheilmoitus on parametri, jonka välitämme expect:ille, unwrap:in käyttämän oletusarvoisen panic!-viestin sijaan. Se näyttää tältä:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Tuotantolaatuisessa koodissa useimmat rustilaiset valitsevat expect:in unwrap:in sijaan ja antavat enemmän kontekstia siitä, miksi operaation odotetaan aina onnistuvan. Näin, jos oletuksesi koskaan osoittautuvat vääriksi, sinulla on enemmän tietoa virheenkorjaukseen.

Virheiden propagointi

Kun funktion toteutus kutsuu jotain, mikä voi epäonnistua, sen sijaan että käsittelisit virheen funktion sisällä, voit palauttaa virheen kutsuvalle koodille, jotta se voi päättää, mitä tehdä. Tätä kutsutaan virheen propagoinniksi, ja se antaa enemmän hallintaa kutsuvalle koodille, jossa saattaa olla enemmän tietoa tai logiikkaa, joka sanelee, miten virhe pitäisi käsitellä, kuin mitä sinulla on käytettävissäsi koodisi kontekstissa.

Esimerkiksi listaus 9-6 näyttää funktion, joka lukee käyttäjänimen tiedostosta. Jos tiedostoa ei ole olemassa tai sitä ei voida lukea, tämä funktio palauttaa nämä virheet koodille, joka kutsui funktiota.

#![allow(unused)]
fn main() {
{{#include ../listings/ch09-error-handling/listing-09-06/src/main.rs:here}}
}

Tämä funktio voidaan kirjoittaa paljon lyhyemmällä tavalla, mutta aloitamme tekemällä suuren osan manuaalisesti tutkiaksemme virheenkäsittelyä; lopussa näytämme lyhyemmän tavan. Katsotaan ensin funktion palautustyyppiä: Result<String, io::Error>. Tämä tarkoittaa, että funktio palauttaa arvon tyyppiä Result<T, E>, jossa geneerinen parametri T on täytetty konkreettisella tyypillä String ja geneerinen tyyppi E on täytetty konkreettisella tyypillä io::Error.

Jos tämä funktio onnistuu ilman ongelmia, tätä funktiota kutsuva koodi saa Ok-arvon, joka sisältää String:in—tiedostosta luetun username:n. Jos tämä funktio kohtaa ongelmia, kutsuva koodi saa Err-arvon, joka sisältää io::Error-instanssin, jossa on lisätietoja ongelmista. Valitsimme io::Error:in tämän funktion palautustyypiksi, koska se sattuu olemaan virhearvon tyyppi, jonka molemmat tämän funktion rungossa kutsumamme operaatiot voivat palauttaa: File::open-funktio ja read_to_string-metodi.

Funktion runko alkaa kutsumalla File::open-funktiota. Sitten käsittelemme Result-arvon match:illa, joka on samanlainen kuin listauksen 9-4 match. Jos File::open onnistuu, tiedostokahva kuviomuuttujassa file tulee muuttuvan muuttujan username_file arvoksi ja funktio jatkuu. Err-tapauksessa panic!:in kutsumisen sijaan käytämme return-avainsanaa palataksemme aikaisin kokonaan funktiosta ja välittääksemme File::open:n virhearvon, nyt kuviomuuttujassa e, takaisin kutsuvalle koodille tämän funktion virhearvona.

Joten, jos meillä on tiedostokahva username_file:ssa, funktio luo sitten uuden String:in muuttujaan username ja kutsuu read_to_string-metodia tiedostokahvassa username_file lukeakseen tiedoston sisällön username:iin. read_to_string-metodi palauttaa myös Result:in, koska se voi epäonnistua, vaikka File::open onnistui. Joten tarvitsemme toisen match:in käsitelläksemme kyseisen Result:in: Jos read_to_string onnistuu, funktiomme on onnistunut, ja palautamme tiedostosta nyt username:ssa olevan käyttäjänimen Ok:ssa käärittynä. Jos read_to_string epäonnistuu, palautamme virhearvon samalla tavalla kuin palautimme virhearvon match:issa, joka käsitteli File::open:n palautusarvon. Meidän ei kuitenkaan tarvitse eksplisiittisesti sanoa return, koska tämä on funktion viimeinen lauseke.

Tätä koodia kutsuva koodi käsittelee sitten joko Ok-arvon, joka sisältää käyttäjänimen, tai Err-arvon, joka sisältää io::Error:in. Kutsuvalle koodille jää päätettäväksi, mitä näille arvoille tehdään. Jos kutsuva koodi saa Err-arvon, se voisi kutsua panic!:ia ja kaataa ohjelman, käyttää oletuskäyttäjänimeä tai hakea käyttäjänimen jostain muualta kuin tiedostosta, esimerkiksi. Meillä ei ole tarpeeksi tietoa siitä, mitä kutsuva koodi todella yrittää tehdä, joten propagoidamme kaiken onnistumis- tai virhetiedon ylöspäin sen käsiteltäväksi asianmukaisesti.

Tämä virheiden propagoinnin malli on niin yleinen Rustissa, että Rust tarjoaa kysymysmerkkioperaattorin ? helpottamaan tätä.

?-operaattorin oikotie

Listaus 9-7 näyttää read_username_from_file:n toteutuksen, jolla on sama toiminnallisuus kuin listauksessa 9-6, mutta tässä toteutuksessa käytetään ?-operaattoria.

#![allow(unused)]
fn main() {
{{#include ../listings/ch09-error-handling/listing-09-07/src/main.rs:here}}
}

Result-arvon jälkeen sijoitettu ? on määritelty toimimaan lähes samalla tavalla kuin match-lausekkeet, jotka määrittelimme käsittelemään Result-arvoja listauksessa 9-6. Jos Result-arvon arvo on Ok, Ok:n sisällä oleva arvo palautetaan tästä lausekkeesta ja ohjelma jatkuu. Jos arvo on Err, Err palautetaan koko funktiosta ikään kuin olisimme käyttäneet return-avainsanaa, jotta virhearvo propagoidaan kutsuvalle koodille.

On ero listauksen 9-6 match-lausekkeen ja ?-operaattorin välillä: Virhearvot, joille ?-operaattoria kutsutaan, käyvät läpi from-funktion, joka on määritelty standardikirjaston From-traitissa ja jota käytetään arvojen muuntamiseen tyypistä toiseen. Kun ?-operaattori kutsuu from-funktiota, vastaanotettu virhetyyppi muunnetaan nykyisen funktion palautustyypissä määriteltyyn virhetyyppiin. Tämä on hyödyllistä, kun funktio palauttaa yhden virhetyypin edustaen kaikkia tapoja, joilla funktio voi epäonnistua, vaikka osat voivat epäonnistua monista eri syistä.

Esimerkiksi voisimme muuttaa listauksen 9-7 read_username_from_file-funktion palauttamaan mukautetun virhetyypin nimeltä OurError, jonka määrittelemme. Jos määrittelemme myös impl From<io::Error> for OurError rakentaaksemme OurError-instanssin io::Error:sta, read_username_from_file-funktion rungon ?-operaattorikutsut kutsuvat from:ia ja muuntavat virhetyypit lisäämättä enempää koodia funktioon.

Listauksen 9-7 kontekstissa File::open-kutsun lopussa oleva ? palauttaa Ok:n sisällä olevan arvon muuttujaan username_file. Jos virhe tapahtuu, ?-operaattori palaa aikaisin koko funktiosta ja antaa minkä tahansa Err-arvon kutsuvalle kodelle. Sama pätee read_to_string-kutsun lopussa olevaan ?:ään.

?-operaattori poistaa paljon toistuvaa koodia ja yksinkertaistaa tämän funktion toteutusta. Voimme jopa lyhentää tätä koodia edelleen ketjuttamalla metodikutsuja heti ?:n jälkeen, kuten listauksessa 9-8.

#![allow(unused)]
fn main() {
{{#include ../listings/ch09-error-handling/listing-09-08/src/main.rs:here}}
}

Olemme siirtäneet uuden String:in luomisen username:ssa funktion alkuun; tämä osa ei ole muuttunut. Sen sijaan, että loisimme muuttujan username_file, olemme ketjuttaneet read_to_string-kutsun suoraan File::open("hello.txt")?:n tulokseen. Meillä on edelleen ? read_to_string-kutsun lopussa, ja palautamme edelleen Ok-arvon, joka sisältää username:n, kun sekä File::open että read_to_string onnistuvat virheiden palauttamisen sijaan. Toiminnallisuus on taas sama kuin listauksissa 9-6 ja 9-7; tämä on vain eri, ergonomisempi tapa kirjoittaa se.

Listaus 9-9 näyttää tavan tehdä tämä vielä lyhyemmäksi käyttämällä fs::read_to_string:ia.

#![allow(unused)]
fn main() {
{{#include ../listings/ch09-error-handling/listing-09-09/src/main.rs:here}}
}

Tiedoston lukeminen merkkijonoon on melko yleinen operaatio, joten standardikirjasto tarjoaa kätevän fs::read_to_string-funktion, joka avaa tiedoston, luo uuden String:in, lukee tiedoston sisällön, laittaa sisällön kyseiseen String:iin ja palauttaa sen. Tietysti fs::read_to_string:in käyttö ei anna meille mahdollisuutta selittää kaikkea virheenkäsittelyä, joten teimme sen ensin pidemmällä tavalla.

Missä ?-operaattoria voi käyttää

?-operaattoria voi käyttää vain funktioissa, joiden palautustyyppi on yhteensopiva arvon kanssa, jolle ? käytetään. Tämä johtuu siitä, että ?-operaattori on määritelty suorittamaan aikainen paluu arvosta funktiosta samalla tavalla kuin listauksessa 9-6 määrittelemämme match-lauseke. Listauksessa 9-6 match käytti Result-arvoa, ja aikaisen paluun haara palautti Err(e)-arvon. Funktion palautustyypin on oltava Result, jotta se on yhteensopiva tämän return:in kanssa.

Listauksessa 9-10 katsotaan virhettä, jonka saamme, jos käytämme ?-operaattoria main-funktiossa, jonka palautustyyppi ei ole yhteensopiva arvon tyypin kanssa, jolle käytämme ?:ää.

{{#rustdoc_include ../listings/ch09-error-handling/listing-09-10/src/main.rs}}

Tämä koodi avaa tiedoston, mikä voi epäonnistua. ?-operaattori seuraa File::open:n palauttamaa Result-arvoa, mutta tällä main-funktiolla on palautustyyppi (), ei Result. Kun käännetään tämä koodi, saamme seuraavan virheilmoituksen:

{{#include ../listings/ch09-error-handling/listing-09-10/output.txt}}

Tämä virhe osoittaa, että ?-operaattoria saa käyttää vain funktiossa, joka palauttaa Result:in, Option:in tai muun tyypin, joka toteuttaa FromResidual:in.

Virheen korjaamiseksi sinulla on kaksi vaihtoehtoa. Yksi vaihtoehto on muuttaa funktiosi palautustyyppi yhteensopivaksi arvon kanssa, jolle käytät ?-operaattoria, kunhan sinulla ei ole rajoituksia, jotka estävät sen. Toinen vaihtoehto on käyttää match:ia tai jotakin Result<T, E>:n metodeista käsitelläksesi Result<T, E>:n sopivalla tavalla.

Virheilmoitus mainitsi myös, että ?:ää voi käyttää myös Option<T>-arvojen kanssa. Kuten Result:in kanssa, voit käyttää ?:ää Option:issa vain funktiossa, joka palauttaa Option:in. ?-operaattorin käyttäytyminen, kun sitä kutsutaan Option<T>:llä, on samanlainen kuin kun sitä kutsutaan Result<T, E>:llä: Jos arvo on None, None palautetaan aikaisin funktiosta kyseisessä kohdassa. Jos arvo on Some, Some:n sisällä oleva arvo on lausekkeen tulosarvo, ja funktio jatkuu. Listaus 9-11 on esimerkki funktiosta, joka löytää annetun tekstin ensimmäisen rivin viimeisen merkin.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/listing-09-11/src/main.rs:here}}
}

Tämä funktio palauttaa Option<char>:in, koska siellä saattaa olla merkki, mutta se on myös mahdollista, ettei siellä ole. Tämä koodi ottaa text-merkkijonoviipaleargumentin ja kutsuu sen lines-metodia, joka palauttaa iteraattorin merkkijonon riveistä. Koska tämä funktio haluaa tarkastella ensimmäistä riviä, se kutsuu next:ia iteraattorilla saadakseen ensimmäisen arvon iteraattorista. Jos text on tyhjä merkkijono, tämä next-kutsu palauttaa None:n, jolloin käytämme ?:a pysähtyäksemme ja palauttaaksemme None:n funktiosta last_char_of_first_line. Jos text ei ole tyhjä merkkijono, next palauttaa Some-arvon, joka sisältää merkkijonoviipaleen ensimmäisestä rivistä text:issä.

? erottaa merkkijonoviipaleen, ja voimme kutsua chars:ia kyseisellä merkkijonoviipaleella saadaksemme iteraattorin sen merkeistä. Olemme kiinnostuneita viimeisestä merkistä tällä ensimmäisellä rivillä, joten kutsumme last:ia palauttaaksemme viimeisen kohteen iteraattorista. Tämä on Option, koska on mahdollista, että ensimmäinen rivi on tyhjä merkkijono; esimerkiksi jos text alkaa tyhjällä rivillä mutta sisältää merkkejä muilla riveillä, kuten "\nhi". Jos kuitenkin ensimmäisellä rivillä on viimeinen merkki, se palautetaan Some-variantissa. Keskellä oleva ?-operaattori antaa meille tiiviin tavan ilmaista tämä logiikka, jolloin voimme toteuttaa funktion yhdellä rivillä. Jos emme voisi käyttää ?-operaattoria Option:issa, meidän pitäisi toteuttaa tämä logiikka useammilla metodikutsuilla tai match-lausekkeella.

Huomaa, että voit käyttää ?-operaattoria Result:issa funktiossa, joka palauttaa Result:in, ja voit käyttää ?-operaattoria Option:issa funktiossa, joka palauttaa Option:in, mutta et voi sekoittaa niitä. ?-operaattori ei automaattisesti muunna Result:ia Option:iksi tai päinvastoin; näissä tapauksissa voit käyttää metodeja, kuten ok-metodia Result:issa tai ok_or-metodia Option:issa, tehdäksesi muunnoksen eksplisiittisesti.

Tähän mennessä kaikki käyttämämme main-funktiot ovat palauttaneet (). main-funktio on erityinen, koska se on suoritettavan ohjelman sisään- ja uloskäyntipiste, ja sen palautustyypillä on rajoituksia, jotta ohjelma käyttäytyy odotetusti.

Onneksi main voi myös palauttaa Result<(), E>. Listaus 9-12 sisältää listauksen 9-10 koodin, mutta olemme muuttaneet main:in palautustyypiksi Result<(), Box<dyn Error>> ja lisänneet paluuarvon Ok(()) loppuun. Tämä koodi kääntyy nyt.

{{#rustdoc_include ../listings/ch09-error-handling/listing-09-12/src/main.rs}}

Box<dyn Error>-tyyppi on trait-objekti, jota käsittelemme kohdassa ”Trait-objektien käyttö jaetun käyttäytymisen abstrahointiin” luvussa 18. Toistaiseksi voit lukea Box<dyn Error>:in tarkoittavan ”mitä tahansa virhetyyppiä”. ?:n käyttö Result-arvolla main-funktiossa virhetyypillä Box<dyn Error> on sallittua, koska se sallii minkä tahansa Err-arvon palauttamisen aikaisin. Vaikka tämän main-funktion runko palauttaisi vain std::io::Error-tyyppisiä virheitä, määrittämällä Box<dyn Error> tämä allekirjoitus pysyy oikeana, vaikka main:in runkoon lisättäisiin enemmän koodia, joka palauttaa muita virheitä.

Kun main-funktio palauttaa Result<(), E>, suoritettava lopettaa arvolla 0, jos main palauttaa Ok(()), ja lopettaa nollasta poikkeavalla arvolla, jos main palauttaa Err-arvon. C-kielellä kirjoitetut suoritettavat palauttavat kokonaislukuja lopettaessaan: onnistuneesti lopettavat ohjelmat palauttavat kokonaisluvun 0, ja virheelliset ohjelmat palauttavat jonkin muun kokonaisluvun kuin 0. Rust palauttaa myös kokonaislukuja suoritettavista ollakseen yhteensopiva tämän käytännön kanssa.

main-funktio voi palauttaa mitä tahansa tyyppejä, jotka toteuttavat traitin std::process::Termination, joka sisältää funktion report, joka palauttaa ExitCode:n. Katso standardikirjaston dokumentaatiosta lisätietoja Termination-traitin toteuttamisesta omille tyypeillesi.

Nyt kun olemme käsitelleet panic!:in kutsumisen tai Result:in palauttamisen yksityiskohdat, palataan aiheeseen, miten päättää, kumpaa on sopivaa käyttää missäkin tilanteessa.

panic! vai ei panic!?

panic! vai ei?

Miten siis päätät, milloin sinun pitäisi kutsua panic!:ia ja milloin palauttaa Result? Kun koodi panikoi, palautumista ei ole mahdollista. Voit kutsua panic!:ia mihin tahansa virhetilanteeseen, onko mahdollinen tapa palautua vai ei, mutta silloin teet päätöksen, että tilanne on palautumaton kutsuvalle koodille. Kun valitset palauttaa Result-arvon, annat kutsuvalle koodille vaihtoehtoja. Kutsuva koodi voi valita yrittää palautua tavalla, joka sopii sen tilanteeseen, tai se voi päättää, että Err-arvo tässä tapauksessa on palautumaton, jolloin se voi kutsua panic!:ia ja muuttaa palautuvan virheesi palautumattomaksi. Siksi Result:in palauttaminen on hyvä oletusvalinta, kun määrittelet funktion, joka voi epäonnistua.

Tilanteissa kuten esimerkeissä, prototyyppikoodissa ja testeissä on sopivampaa kirjoittaa koodia, joka panikoi Result:in palauttamisen sijaan. Tutkitaan miksi, ja sitten käsitellään tilanteita, joissa kääntäjä ei voi kertoa, että epäonnistuminen on mahdotonta, mutta sinä ihmisenä voit. Luku päättyy yleisiin ohjeisiin siitä, milloin panikoida kirjastokoodissa.

Esimerkit, prototyyppikoodi ja testit

Kun kirjoitat esimerkkiä havainnollistamaan jotain käsitettä, vankan virheenkäsittelykoodin sisällyttäminen voi tehdä esimerkistä epäselvemmän. Esimerkeissä ymmärretään, että metodin, kuten unwrap:in, kutsuminen, joka voi panikoida, on tarkoitettu paikanpitäjäksi sille tavalle, jolla haluat sovelluksesi käsittelevän virheet, mikä voi vaihdella sen mukaan, mitä muu koodisi tekee.

Vastaavasti unwrap- ja expect-metodit ovat erittäin käteviä prototyyppauksessa, kun et ole vielä valmis päättämään, miten käsitellä virheitä. Ne jättävät selkeät merkit koodiisi siihen asti, kun olet valmis tekemään ohjelmastasi vankemman.

Jos metodikutsu epäonnistuu testissä, haluat koko testin epäonnistuvan, vaikka kyseinen metodi ei olisikaan testattava toiminnallisuus. Koska panic! on tapa, jolla testi merkitään epäonnistuneeksi, unwrap:in tai expect:in kutsuminen on juuri sitä, mitä pitäisi tapahtua.

Kun sinulla on enemmän tietoa kuin kääntäjällä

Olisi myös sopivaa kutsua expect:ia, kun sinulla on muuta logiikkaa, joka varmistaa, että Result:illa on Ok-arvo, mutta logiikka ei ole sellaista, mitä kääntäjä ymmärtää. Sinulla on silti Result-arvo, joka on käsiteltävä: mikä tahansa kutsumasi operaatio voi silti epäonnistua yleisesti, vaikka se olisi loogisesti mahdotonta juuri sinun tilanteessasi. Jos voit varmistaa tarkastamalla koodin manuaalisesti, ettet koskaan saa Err-varianttia, on täysin hyväksyttävää kutsua expect:ia ja dokumentoida syy, miksi uskot, ettei koskaan saa Err-varianttia, argumenttitekstissä. Tässä on esimerkki:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/no-listing-08-unwrap-that-cant-fail/src/main.rs:here}}
}

Luomme IpAddr-instanssin jäsentämällä kovakoodatun merkkijonon. Näemme, että 127.0.0.1 on kelvollinen IP-osoite, joten expect:in käyttö on tässä hyväksyttävää. Kovakoodatun kelvollisen merkkijonon olemassaolo ei kuitenkaan muuta parse-metodin palautustyyppiä: saamme silti Result-arvon, ja kääntäjä pakottaa meidät käsittelemään Result:ia ikään kuin Err-variantti olisi mahdollisuus, koska kääntäjä ei ole tarpeeksi älykäs nähdäkseen, että tämä merkkijono on aina kelvollinen IP-osoite. Jos IP-osoitemerkkijono tulisi käyttäjältä sen sijaan, että se olisi kovakoodattu ohjelmaan ja siksi voisi epäonnistua, käsittelisimme ehdottomasti Result:ia vankemmalla tavalla. Oletuksen mainitseminen, että tämä IP-osoite on kovakoodattu, kehottaa meitä muuttamaan expect:in paremmaksi virheenkäsittelykoodiksi, jos tulevaisuudessa tarvitsemme hakea IP-osoitteen jostain muusta lähteestä.

Ohjeita virheenkäsittelyyn

On suositeltavaa, että koodisi panikoi, kun on mahdollista, että koodisi päätyy huonoon tilaan. Tässä kontekstissa huono tila tarkoittaa tilannetta, jossa jokin oletus, takuu, sopimus tai invariantti on rikottu, kuten kun virheellisiä arvoja, ristiriitaisia arvoja tai puuttuvia arvoja välitetään koodillesi—plus yksi tai useampi seuraavista:

• Huono tila on jotain odottamatonta, toisin kuin jotain, mikä todennäköisesti tapahtuu satunnaisesti, kuten käyttäjä syöttää dataa väärässä muodossa.
• Koodisi tästä eteenpäin on luotettava siihen, ettei ole tässä huonossa tilassa, sen sijaan että tarkistaisi ongelman jokaisessa vaiheessa.
• Ei ole hyvää tapaa koodata tätä tietoa käyttämiisi tyyppeihin. Käymme läpi esimerkin siitä, mitä tarkoitamme kohdassa ”Tilojen ja käyttäytymisen koodaus tyypeillä” luvussa 18.

Jos joku kutsuu koodiasi ja välittää arvoja, jotka eivät ole järkeviä, on parasta palauttaa virhe, jos voit, jotta kirjastosi käyttäjä voi päättää, mitä tehdä kyseisessä tapauksessa. Jos kuitenkin jatkaminen voisi olla epäturvallista tai haitallista, paras valinta saattaa olla kutsua panic!:ia ja hälyttää kirjastosi käyttäjä heidän koodinsa bugista, jotta he voivat korjata sen kehityksen aikana. Vastaavasti panic! on usein sopivaa, jos kutsut ulkoista koodia, joka on hallintasi ulkopuolella ja palauttaa virheellisen tilan, jota et voi korjata.

Kun epäonnistuminen on odotettavissa, on sopivampaa palauttaa Result kuin kutsua panic!:ia. Esimerkkejä ovat jäsentäjälle annettu virheellinen data tai HTTP-pyyntö, joka palauttaa tilan, joka ilmaisee, että olet osunut nopeusrajoitukseen. Näissä tapauksissa Result:in palauttaminen ilmaisee, että epäonnistuminen on odotettu mahdollisuus, jonka kutsuvan koodin on päätettävä, miten käsitellä.

Kun koodisi suorittaa operaation, joka voi asettaa käyttäjän riskiin, jos sitä kutsutaan virheellisillä arvoilla, koodisi pitäisi ensin varmistaa, että arvot ovat kelvollisia, ja panikoida, jos arvot eivät ole kelvollisia. Tämä on pääasiassa turvallisuussyistä: Yritys käsitellä virheellistä dataa voi altistaa koodisi haavoittuvuuksille. Tämä on pääsyy, miksi standardikirjasto kutsuu panic!:ia, jos yrität muistin käyttöä alueen ulkopuolelta: Yritys käyttää muistia, joka ei kuulu nykyiseen tietorakenteeseen, on yleinen turvallisuusongelma. Funktioilla on usein sopimuksia: Niiden käyttäytymistä taataan vain, jos syötteet täyttävät tietyt vaatimukset. Panikointi, kun sopimus rikotaan, on järkevää, koska sopimusrikkomus osoittaa aina kutsupuolen bugia, eikä se ole sellainen virhe, jonka haluat kutsuvan koodin käsittelevän eksplisiittisesti. Itse asiassa ei ole järkevää tapaa kutsuvalle koodille palautua; kutsupuolen ohjelmoijien on korjattava koodi. Funktion sopimukset, erityisesti kun rikkomus aiheuttaa paniikin, tulisi selittää funktion API-dokumentaatiossa.

Paljon virhetarkistuksia kaikissa funktioissasi olisi kuitenkin sanallista ja ärsyttävää. Onneksi voit käyttää Rustin tyyppijärjestelmää (ja siten kääntäjän tekemää tyyppitarkistusta) tekemään monia tarkistuksista puolestasi. Jos funktiollasi on tietty tyyppi parametrina, voit jatkaa koodisi logiikkaa tietäen, että kääntäjä on jo varmistanut, että sinulla on kelvollinen arvo. Esimerkiksi jos sinulla on tyyppi Option:in sijaan, ohjelmasi odottaa jotain eikä ei mitään. Koodisi ei sitten tarvitse käsitellä kahta tapausta Some- ja None-varianteille: sillä on vain yksi tapaus, jossa arvo on varmasti olemassa. Koodi, joka yrittää välittää ei mitään funktiollesi, ei edes käänny, joten funktiosi ei tarvitse tarkistaa kyseistä tapausta ajonaikana. Toinen esimerkki on etumerkittömän kokonaislukutyypin, kuten u32:n, käyttö, joka varmistaa, että parametri ei ole koskaan negatiivinen.

Mukautetut tyypit validointiin

Viedään ajatus Rustin tyyppijärjestelmän käytöstä kelvollisen arvon varmistamiseksi askeleen pidemmälle ja katsotaan mukautetun tyypin luomista validointiin. Muista arvauspeli luvusta 2, jossa koodimme pyysi käyttäjää arvaamaan luvun välillä 1 ja 100. Emme koskaan validoineet, että käyttäjän arvaus oli näiden lukujen välillä ennen kuin tarkistimme sen salaisen lukuamme vastaan; validoimme vain, että arvaus oli positiivinen. Tässä tapauksessa seuraukset eivät olleet kovin vakavat: Tulosteemme ”Liian korkea” tai ”Liian matala” olisi silti oikein. Mutta olisi hyödyllinen parannus ohjata käyttäjää kohti kelvollisia arvauksia ja saada eri käyttäytyminen, kun käyttäjä arvaa luvun, joka on alueen ulkopuolella, verrattuna tilanteeseen, jossa käyttäjä kirjoittaa esimerkiksi kirjaimia numeroiden sijaan.

Yksi tapa tehdä tämä olisi jäsentää arvaus i32:ksi pelkän u32:n sijaan salliakseen mahdollisesti negatiiviset luvut, ja sitten lisätä tarkistus, että luku on alueella, näin:

{{#rustdoc_include ../listings/ch09-error-handling/no-listing-09-guess-out-of-range/src/main.rs:here}}

if-lauseke tarkistaa, onko arvomme alueen ulkopuolella, kertoo käyttäjälle ongelmasta ja kutsuu continue:a aloittaakseen silmukan seuraavan iteraation ja pyytääkseen uuden arvauksen. if-lausekkeen jälkeen voimme jatkaa guess:n ja salaisen luvun vertailuja tietäen, että guess on välillä 1 ja 100.

Tämä ei kuitenkaan ole ihanteellinen ratkaisu: Jos olisi ehdottoman kriittistä, että ohjelma toimisi vain arvoilla välillä 1 ja 100, ja sillä olisi monia funktioita tällä vaatimuksella, tällaisen tarkistuksen tekeminen jokaisessa funktiossa olisi työlästä (ja saattaisi vaikuttaa suorituskykyyn).

Sen sijaan voimme luoda uuden tyypin erilliseen moduuliin ja sijoittaa validoinnit funktioon, joka luo tyypin instanssin, sen sijaan että toistaisimme validoinnit kaikkialla. Näin on turvallista funktioiden käyttää uutta tyyppiä signatuureissaan ja luottaa saamiinsa arvoihin. Listaus 9-13 näyttää yhden tavan määritellä Guess-tyyppi, joka luo Guess-instanssin vain, jos new-funktio saa arvon välillä 1 ja 100.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch09-error-handling/listing-09-13/src/guessing_game.rs}}
}

Huomaa, että tämä koodi tiedostossa src/guessing_game.rs riippuu moduulimäärittelyn mod guessing_game; lisäämisestä tiedostoon src/lib.rs, jota emme ole näyttäneet tässä. Tämän uuden moduulin tiedostossa määrittelemme structin nimeltä Guess, jolla on kenttä nimeltä value, joka tallentaa i32:n. Tähän tallennetaan luku.

Sitten toteutamme assosioitun funktion nimeltä new tyypille Guess, joka luo Guess-arvojen instansseja. new-funktio on määritelty ottamaan yksi parametri nimeltä value tyyppiä i32 ja palauttamaan Guess:in. new-funktion rungon koodi testaa value:n varmistaakseen, että se on välillä 1 ja 100. Jos value ei läpäise tätä testiä, kutsumme panic!:ia, mikä hälyttää kutsupuolen ohjelmoijan, että heillä on bugi korjattavana, koska Guess:in luominen value:lla tämän alueen ulkopuolella rikkoisi sopimuksen, johon Guess::new luottaa. Olosuhteet, joissa Guess::new saattaa panikoida, tulisi käsitellä sen julkisessa API-dokumentaatiossa; käsittelemme dokumentointikäytäntöjä, jotka ilmaisevat panic!:in mahdollisuuden luomassasi API-dokumentaatiossa luvussa 14. Jos value läpäisee testin, luomme uuden Guess:in, jonka value-kenttä on asetettu value-parametriin, ja palautamme Guess:in.

Seuraavaksi toteutamme metodin nimeltä value, joka lainaa self:ää, ei ota muita parametreja ja palauttaa i32:n. Tällaisia metodeja kutsutaan joskus gettereiksi, koska niiden tarkoitus on saada dataa kentistään ja palauttaa se. Tämä julkinen metodi on tarpeen, koska Guess-structin value-kenttä on yksityinen. On tärkeää, että value-kenttä on yksityinen, jotta Guess-structia käyttävä koodi ei saa asettaa value:a suoraan: guessing_game-moduulin ulkopuolinen koodi täytyy käyttää Guess::new-funktiota luodakseen Guess-instanssin, varmistaen näin, ettei Guess:illä voi olla value:a, jota Guess::new-funktion ehtoja ei ole tarkistettu.

Funktio, jolla on parametri tai joka palauttaa vain lukuja välillä 1 ja 100, voi sitten ilmoittaa signatuurissaan, että se ottaa tai palauttaa Guess:in i32:n sijaan, eikä sen tarvitse tehdä lisätarkistuksia rungossaan.

Yhteenveto

Rustin virheenkäsittelyominaisuudet on suunniteltu auttamaan sinua kirjoittamaan vankempaa koodia. panic!-makro ilmaisee, että ohjelmasi on tilassa, jota se ei voi käsitellä, ja antaa sinun kertoa prosessille pysähtyä sen sijaan, että yrittäisit jatkaa virheellisillä tai vääriä arvoilla. Result-enum käyttää Rustin tyyppijärjestelmää ilmaisemaan, että operaatiot voivat epäonnistua tavalla, josta koodisi voi palautua. Voit käyttää Result:ia kertomaan koodille, joka kutsuu koodiasi, että sen on käsiteltävä mahdollinen onnistuminen tai epäonnistuminen. panic!:in ja Result:in käyttö sopivissa tilanteissa tekee koodistasi luotettavamman väistämättömien ongelmien edessä.

Nyt kun olet nähnyt hyödyllisiä tapoja, joilla standardikirjasto käyttää geneerisiä tyyppejä Option- ja Result-enumien kanssa, puhumme siitä, miten geneeriset tyypit toimivat ja miten voit käyttää niitä koodissasi.

Geneeriset tyypit, traitit ja eliniät

Jokaisella ohjelmointikielellä on työkaluja, joilla voidaan tehokkaasti vähentää toistuvuutta koodissa. Rustissa yksi tällainen työkalu on geneerisyys (generics): abstraktit paikkamerkit konkreettisille tyypeille tai muille ominaisuuksille. Voimme määrittää geneeristen tyyppien käyttäytymisen tai niiden suhteen toisiin geneerisiin tyyppeihin, tietämättä tarkalleen, mitä niiden tilalla tulee olemaan kääntö- ja suoritusaikana.

Funktiot voivat ottaa parametreja, joiden tyyppi on geneerinen, samalla tavalla kuin ne ottavat parametreja, joiden arvoja ei tunneta etukäteen. Olemme jo käyttäneet geneerisiä tyyppejä aiemmin, esimerkiksi:

• Luvussa 6 Option<T>
• Luvussa 8 Vec<T> ja HashMap<K, V>
• Luvussa 9 Result<T, E>

Tässä luvussa opit määrittelemään omia tyyppejä, funktioita ja metodeja geneerisillä tyypeillä!

Ensin tarkastelemme, miten voimme vähentää koodin toistuvuutta siirtämällä toistuvaa koodia erilliseen funktioon. Tämän jälkeen käytämme samaa tekniikkaa muuntaaksemme kaksi erillistä funktiota geneeriseksi funktioksi. Opimme myös, miten geneerisiä tyyppejä voidaan käyttää rakenteissa (structs) ja luetteloissa (enums).

Seuraavaksi käsittelemme traitteja, joilla voidaan määritellä geneeristä käyttäytymistä. Traitteja voi yhdistää geneeristen tyyppien kanssa, jolloin voidaan rajoittaa, millaiset tyypit ovat kelvollisia.

Lopuksi tarkastelemme elinikiä (lifetimes), jotka ovat geneeristen tyyppien erityismuoto. Ne antavat kääntäjälle tietoa siitä, miten viittaukset liittyvät toisiinsa, varmistaen, että viittaukset pysyvät kelvollisina useammissa tilanteissa.

Toiston poistaminen siirtämällä koodi funktioon

Geneerisyys mahdollistaa tiettyjen tyyppien korvaamisen paikkamerkillä, joka voi edustaa useita eri tyyppejä. Ennen kuin syvennymme geneeriseen syntaksiin, tarkastelemme, kuinka voimme poistaa toistuvaa koodia ilman geneerisiä tyyppejä – siirtämällä se funktioon. Sen jälkeen käytämme samaa menetelmää muuttaaksemme funktiosta geneerisen.

Aloitetaan lyhyellä ohjelmalla, joka etsii suurimman luvun listasta.

Esimerkki: Suurimman luvun etsiminen listasta

Alla oleva ohjelma (Listing 10-1) tallentaa listan kokonaislukuja muuttujaan number_list. Se asettaa ensimmäisen luvun suurimmaksi ja käy sitten kaikki listan luvut läpi. Jos nykyinen luku on suurempi kuin jo löydetty suurin luku, se päivitetään. Lopuksi largest-muuttujaan jää suurin luku, tässä tapauksessa 100.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-01/src/main.rs:here}}
}

Olemme nyt saaneet tehtäväksi löytää suurimman luvun kahdesta eri listasta. Voimme ratkaista tämän kopioimalla saman koodin kahteen eri paikkaan, kuten alla:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-02/src/main.rs}}
}

Vaikka tämä toimii, koodin kopiointi on huono käytäntö, koska se tekee ohjelmasta vaikeammin ylläpidettävän ja virhealttiimman. Jos haluamme muuttaa logiikkaa myöhemmin, meidän on päivitettävä molemmat kopiot.

Parempi ratkaisu on luoda erillinen funktio, joka toimii minkä tahansa listan kanssa. Tämä tekee koodista selkeämmän ja abstraktimman.

Abstraktin funktion määrittely

Alla olevassa esimerkissä (Listing 10-3) siirrämme suurimman luvun etsintälogiikan largest-nimiseen funktioon. Tämän jälkeen kutsumme sitä kahdella eri listalla.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-03/src/main.rs:here}}
}

Tässä largest-funktiolla on parametri list, joka voi edustaa mitä tahansa i32-kokonaislukujen viipaletta. Kun funktiota kutsutaan, se käyttää annettua listaa.

Muutos prosessissa:

1. Tunnista toistuva koodi.
2. Siirrä toistuva koodi erilliseen funktioon ja määritä sen parametrit ja palautusarvo.
3. Kutsu funktiota niissä kohdissa, joissa aiemmin oli toistuvaa koodia.

Seuraavaksi sovellamme samaa lähestymistapaa geneerisiin tyyppeihin, jotta voimme vähentää koodin toistoa entisestään. Samalla tavalla kuin funktiot voivat toimia abstraktilla list-parametrilla, ne voivat myös toimia abstrakteilla tyypeillä.

Esimerkiksi, jos meillä olisi kaksi funktiota:

• Yksi, joka löytää suurimman arvon i32-listasta.
• Toinen, joka löytää suurimman arvon char-listasta.

Kuinka voisimme yhdistää nämä funktiot geneerisen tyypin avulla? Siitä jatkamme seuraavaksi!

Geneeriset tietotyypit

Geneeriset tietotyypit

Käytämme geneerisiä tyyppejä luodaksemme määritelmiä esimerkiksi funktioiden allekirjoituksille tai structeille, joita voimme sitten käyttää monilla eri konkreettisilla tietotyypeillä. Aloitetaan katsomalla, miten funktioita, structeja, enum-arvoja ja metodeja määritellään geneeristen tyyppien avulla. Sen jälkeen käsittelemme, miten geneeriset tyypit vaikuttavat koodin suorituskykyyn.

Funktiomäärittelyissä

Kun määrittelemme funktion, joka käyttää geneerisiä tyyppejä, sijoitamme geneeriset tyypit funktion allekirjoitukseen sinne, missä yleensä määrittelemme parametrien ja palautusarvon tietotyypit. Näin koodistamme tulee joustavampaa ja se tarjoaa kutsujille enemmän toiminnallisuutta samalla kun vältämme koodin toistamista.

Jatkamme largest-funktion parissa. Listaus 10-4 näyttää kaksi funktiota, jotka molemmat etsivät suurimman arvon viipaleesta. Yhdistämme ne sitten yhdeksi funktioksi, joka käyttää geneerisiä tyyppejä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-04/src/main.rs:here}}
}

Funktio largest_i32 on se, jonka erotimme listauksessa 10-3 ja joka etsii suurimman i32-arvon viipaleesta. Funktio largest_char etsii suurimman char-arvon viipaleesta. Funktioiden rungot ovat samanlaiset, joten poistamme toiston ottamalla käyttöön geneerisen tyyppiparametrin yhdessä funktiossa.

Parametroidaksemme tyypit uudessa yhdessä funktiossa meidän täytyy nimetä tyyppiparametri, aivan kuten teemme arvoparametreille funktiossa. Voit käyttää mitä tahansa tunnistetta tyyppiparametrin nimenä. Käytämme kuitenkin T:tä, koska Rustin käytännön mukaan tyyppiparametrien nimet ovat lyhyitä, usein vain yksi kirjain, ja Rustin tyyppien nimeämiskäytäntö on UpperCamelCase. Lyhenne sanasta type, T on useimpien Rust-ohjelmoijien oletusvalinta.

Kun käytämme parametria funktion rungossa, meidän täytyy ilmoittaa parametrin nimi allekirjoituksessa, jotta kääntäjä tietää, mitä nimi tarkoittaa. Vastaavasti, kun käytämme tyyppiparametrin nimeä funktion allekirjoituksessa, meidän täytyy ilmoittaa tyyppiparametrin nimi ennen kuin käytämme sitä. Määritelläksemme geneerisen largest-funktion sijoitamme tyyppinimien ilmoitukset kulmasulkeisiin <> funktion nimen ja parametrilistan väliin, näin:

fn largest<T>(list: &[T]) -> &T {

Luemme tämän määrittelyn näin: ”Funktio largest on geneerinen jonkin tyypin T suhteen.” Tällä funktiolla on yksi parametri nimeltä list, joka on tyypin T arvojen viipale. Funktio largest palauttaa viittauksen arvoon, jonka tyyppi on sama T.

Listaus 10-5 näyttää yhdistetyn largest-funktion määrittelyn, joka käyttää geneeristä tietotyyppiä allekirjoituksessaan. Listaus näyttää myös, miten funktiota voidaan kutsua joko i32-arvojen tai char-arvojen viipaleella. Huomaa, että tämä koodi ei vielä käänny.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-05/src/main.rs}}

Jos käännämme tämän koodin nyt, saamme seuraavan virheen:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-05/output.txt}}

Ohjeteksti mainitsee std::cmp::PartialOrd, joka on trait, ja käsittelemme traitteja seuraavassa osiossa. Toistaiseksi tiedä, että tämä virhe kertoo, että largest-funktion runko ei toimi kaikille mahdollisille tyypeille, joita T voisi olla. Koska haluamme vertailla tyypin T arvoja rungossa, voimme käyttää vain tyyppejä, joiden arvoja voidaan järjestää. Vertailujen mahdollistamiseksi standardikirjasto tarjoaa std::cmp::PartialOrd-traitin, jonka voit toteuttaa tyypeille (katso lisätietoja liitteestä C). Korjataksemme listauksen 10-5 voimme seurata ohjetekstin ehdotusta ja rajoittaa tyypit, jotka kelpaavat T:lle, vain niihin, jotka toteuttavat PartialOrd-traitin. Listaus kääntyy silloin, koska standardikirjasto toteuttaa PartialOrd-traitin sekä i32- että char-tyypeille.

Struct-määrittelyissä

Voimme myös määritellä structeja käyttämään geneeristä tyyppiparametria yhdessä tai useammassa kentässä <>-syntaksilla. Listaus 10-6 määrittelee Point<T>-structin, joka säilyttää x- ja y-koordinaattiarvot minkä tyyppisinä tahansa.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-06/src/main.rs}}
}

Syntaksi geneeristen tyyppien käyttöön struct-määrittelyissä on samanlainen kuin funktiomäärittelyissä. Ensin ilmoitamme tyyppiparametrin nimen kulmasulkeissa heti structin nimen jälkeen. Sitten käytämme geneeristä tyyppiä struct-määrittelyssä siinä kohdassa, missä muuten määrittelisimme konkreettiset tietotyypit.

Huomaa, että koska olemme käyttäneet vain yhtä geneeristä tyyppiä määritellessämme Point<T>:n, tämä määrittely sanoo, että Point<T>-struct on geneerinen jonkin tyypin T suhteen ja kentät x ja y ovat molemmat samaa tyyppiä, mikä se tyyppi sitten onkaan. Jos luomme Point<T>-instanssin, jonka arvot ovat eri tyyppejä, kuten listauksessa 10-7, koodimme ei käänny.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-07/src/main.rs}}

Tässä esimerkissä, kun annamme kokonaislukuarvon 5 muuttujalle x, kerromme kääntäjälle, että geneerinen tyyppi T on kokonaisluku tässä Point<T>- instanssissa. Kun määrittelemme 4.0 muuttujalle y, jonka olemme määritelleet samaan tyyppiin kuin x, saamme tyyppivirheen, joka näyttää tältä:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-07/output.txt}}

Määritelläksemme Point-structin, jossa x ja y ovat molemmat geneerisiä mutta voivat olla eri tyyppejä, voimme käyttää useita geneerisiä tyyppiparametreja. Esimerkiksi listauksessa 10-8 muutamme Point-structin määrittelyn geneeriseksi tyypeille T ja U, jossa x on tyyppiä T ja y on tyyppiä U.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-08/src/main.rs}}
}

Nyt kaikki näytetyt Point-instanssit ovat sallittuja! Voit käyttää määrittelyssä niin monta geneeristä tyyppiparametria kuin haluat, mutta useamman kuin muutaman käyttö tekee koodista vaikealukuista. Jos huomaat tarvitsevasi paljon geneerisiä tyyppejä koodissasi, se voi viitata siihen, että koodisi kaipaa uudelleenjärjestelyä pienempiin osiin.

Enum-määrittelyissä

Kuten structeissa, voimme määritellä enum-arvoja säilyttämään geneerisiä tietotyyppejä variantteihinsa. Katsotaan vielä kerran Option<T>-enum-arvoa, jonka standardikirjasto tarjoaa ja jota käytimme luvussa 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Tämän määrittelyn pitäisi nyt olla selkeämpi. Kuten näet, Option<T>-enum on geneerinen tyypin T suhteen ja sillä on kaksi varianttia: Some, joka säilyttää yhden arvon tyypistä T, ja variantti None, joka ei säilytä mitään arvoa. Käyttämällä Option<T>-enum-arvoa voimme ilmaista abstraktin käsitteen valinnaisesta arvosta, ja koska Option<T> on geneerinen, voimme käyttää tätä abstraktiota riippumatta valinnaisen arvon tyypistä.

Enum-arvot voivat käyttää myös useita geneerisiä tyyppejä. Result-enum-arvon määrittely, jota käytimme luvussa 9, on yksi esimerkki:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Result-enum on geneerinen kahden tyypin, T ja E, suhteen ja sillä on kaksi varianttia: Ok, joka säilyttää arvon tyypistä T, ja Err, joka säilyttää arvon tyypistä E. Tämä määrittely tekee Result-enum-arvon käytöstä kätevää missä tahansa, missä operaatio voi onnistua (palauttaa arvon jonkin tyypin T) tai epäonnistua (palauttaa virheen jonkin tyypin E). Tätä käytimme avatessamme tiedoston listauksessa 9-3, jossa T täytettiin tyypillä std::fs::File, kun tiedosto avattiin onnistuneesti, ja E täytettiin tyypillä std::io::Error, kun tiedoston avaamisessa oli ongelmia.

Kun tunnistat koodissasi tilanteita, joissa on useita struct- tai enum- määrittelyjä, jotka eroavat vain säilyttämiensä arvojen tyypeistä, voit välttää toiston käyttämällä geneerisiä tyyppejä.

Metodimäärittelyissä

Voimme toteuttaa metodeja structeille ja enum-arvoille (kuten teimme luvussa 5) ja käyttää geneerisiä tyyppejä niiden määrittelyissäkin. Listaus 10-9 näyttää Point<T>-structin, jonka määrittelimme listauksessa 10-6, ja siihen toteutetun x-nimisen metodin.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-09/src/main.rs}}
}

Tässä olemme määritelleet Point<T>-structille metodin nimeltä x, joka palauttaa viittauksen kentän x dataan.

Huomaa, että meidän täytyy ilmoittaa T heti impl-avainsanan jälkeen, jotta voimme käyttää T:tä määrittääksemme, että toteutamme metodeja tyypille Point<T>. Ilmoittamalla T:n geneeriseksi tyypiksi impl-avainsanan jälkeen Rust tunnistaa, että kulmasulkeissa Point-tyypin jälkeen oleva tyyppi on geneerinen tyyppi eikä konkreettinen tyyppi. Olisimme voineet valita erilaisen nimen tälle geneeriselle parametrille kuin struct-määrittelyssä ilmoitettu geneerinen parametri, mutta saman nimen käyttö on käytäntö. Jos kirjoitat metodin impl-lohkon sisällä, joka ilmoittaa geneerisen tyypin, se metodi määritellään minkä tahansa tyypin instanssille, riippumatta siitä, mikä konkreettinen tyyppi korvaa geneerisen tyypin.

Voimme myös määrittää rajoituksia geneerisille tyypeille määritellessämme metodeja tyypille. Voisimme esimerkiksi toteuttaa metodeja vain Point<f32>- instansseille eikä Point<T>-instansseille millä tahansa geneerisellä tyypillä. Listauksessa 10-10 käytämme konkreettista tyyppiä f32, mikä tarkoittaa, että emme ilmoita mitään tyyppejä impl-avainsanan jälkeen.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-10/src/main.rs:here}}
}

Tämä koodi tarkoittaa, että tyypillä Point<f32> on distance_from_origin- metodi; muilla Point<T>-instansseilla, joissa T ei ole tyyppiä f32, ei ole tätä metodia määriteltynä. Metodi mittaa, kuinka kaukana pisteemme on pisteestä koordinaateissa (0.0, 0.0), ja käyttää matemaattisia operaatioita, jotka ovat käytettävissä vain liukulukutyypeille.

Struct-määrittelyssä olevat geneeriset tyyppiparametrit eivät aina ole samoja kuin saman structin metodien allekirjoituksissa käytetyt. Listaus 10-11 käyttää geneerisiä tyyppejä X1 ja Y1 Point-structille ja X2 ja Y2 mixup-metodin allekirjoituksessa selkeyttääkseen esimerkkiä. Metodi luo uuden Point-instanssin, jossa x-arvo tulee self-Point-instanssista (tyyppiä X1) ja y-arvo annetusta Point-instanssista (tyyppiä Y2).

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-11/src/main.rs}}
}

Funktiossa main olemme määritelleet Point-instanssin, jossa x on i32 (arvolla 5) ja y on f64 (arvolla 10.4). Muuttuja p2 on Point- struct, jossa x on merkkijonoviipale (arvolla "Hello") ja y on char (arvolla c). Kutsumalla mixup-metodia p1:llä argumenttina p2 saamme p3:n, jossa x on i32, koska x tuli p1:stä. Muuttujassa p3 y on char, koska y tuli p2:sta. println!-makrokutsu tulostaa p3.x = 5, p3.y = c.

Tämän esimerkin tarkoitus on demonstroida tilanne, jossa jotkut geneeriset parametrit ilmoitetaan impl-avainsanalla ja jotkut metodin määrittelyssä. Tässä geneeriset parametrit X1 ja Y1 ilmoitetaan impl-avainsanan jälkeen, koska ne liittyvät struct-määrittelyyn. Geneeriset parametrit X2 ja Y2 ilmoitetaan fn mixup-kohdan jälkeen, koska ne ovat merkityksellisiä vain metodille.

Geneerisiä tyyppejä käyttävän koodin suorituskyky

Saatat miettiä, aiheutuuko geneeristen tyyppiparametrien käytöstä ajonaikainen kustannus. Hyvä uutinen on, että geneeristen tyyppien käyttö ei hidasta ohjelmaasi verrattuna konkreettisiin tyyppeihin.

Rust saavuttaa tämän suorittamalla monomorfisoinnin (monomorphization) geneeristä koodista käännösaikana. Monomorfisointi on prosessi, jossa geneerinen koodi muutetaan tiettyyn koodiin täyttämällä konkreettiset tyypit, joita käytetään käännöksen yhteydessä. Tässä prosessissa kääntäjä tekee vastakkaisen kuin vaiheet, joilla loimme geneerisen funktion listauksessa 10-5: Kääntäjä tarkastaa kaikki kohdat, joissa geneeristä koodia kutsutaan, ja generoi koodin konkreettisille tyypeille, joilla geneeristä koodia kutsutaan.

Katsotaan, miten tämä toimii käyttämällä standardikirjaston geneeristä Option<T>-enum-arvoa:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Kun Rust kääntää tämän koodin, se suorittaa monomorfisoinnin. Tämän prosessin aikana kääntäjä lukee arvot, joita on käytetty Option<T>-instansseissa, ja tunnistaa kaksi Option<T>-tyyppiä: toinen on i32 ja toinen f64. Näin se laajentaa Option<T>:n geneerisen määrittelyn kahteen i32- ja f64- erikoistuneeseen määrittelyyn korvaten geneerisen määrittelyn tiettyillä määrittelyillä.

Monomorfisoidun version koodi näyttää suunnilleen seuraavalta (kääntäjä käyttää eri nimiä kuin mitä käytämme tässä havainnollistukseen):

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

Geneerinen Option<T> korvataan kääntäjän luomilla tiettyillä määrittelyillä. Koska Rust kääntää geneerisen koodin koodiksi, joka määrittää tyypin jokaisessa instanssissa, emme maksa ajonaikaista kustannusta geneeristen tyyppien käytöstä. Kun koodi suoritetaan, se toimii aivan kuten jos olisimme monistaneet jokaisen määrittelyn käsin. Monomorfisointiprosessi tekee Rustin geneerisistä tyypeistä erittäin tehokkaita ajonaikana.

Traitit: jaetun käyttäytymisen määrittäminen

Jaetun käyttäytymisen määrittely traittejen avulla

Trait määrittelee toiminnallisuuden, joka tietyllä tyypillä on ja jonka se voi jakaa muiden tyyppien kanssa. Voimme käyttää traitteja määrittelemään jaettua käyttäytymistä abstraktisti. Voimme käyttää trait-rajoja (trait bounds) määrittääksemme, että geneerinen tyyppi voi olla mikä tahansa tyyppi, jolla on tiettyä käyttäytymistä.

Huom: Traitit muistuttavat ominaisuutta, jota muissa kielissä usein kutsutaan rajapinnoiksi (interfaces), vaikka niissä on eroja.

Traitin määrittely

Tyypin käyttäytyminen koostuu metodeista, joita voimme kutsua kyseiselle tyypille. Eri tyypit jakavat saman käyttäytymisen, jos voimme kutsua samoja metodeja kaikille näille tyypeille. Trait-määrittelyt ovat tapa ryhmittää metodien allekirjoituksia yhteen määrittelemään joukko käyttäytymisiä, joita tarvitaan jonkin tarkoituksen saavuttamiseksi.

Esimerkiksi sanotaan, että meillä on useita structeja, jotka säilyttävät erilaisia tekstejä ja määriä: NewsArticle-struct, joka säilyttää uutisjutun tietyssä paikassa, ja SocialPost, jossa voi olla enintään 280 merkkiä sekä metatietoa siitä, oliko kyseessä uusi julkaisu, uudelleenjulkaisu vai vastaus toiseen julkaisuun.

Haluamme tehdä aggregator-nimisen mediakoostajakirjaston, joka voi näyttää yhteenvetoja tiedoista, jotka voivat olla NewsArticle- tai SocialPost- instanssissa. Tarvitsemme yhteenvedon kustakin tyypistä ja pyydämme sitä kutsumalla summarize-metodia instanssilla. Listaus 10-12 näyttää julkisen Summary-traitin määrittelyn, joka ilmaisee tämän käyttäytymisen.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-12/src/lib.rs}}

Tässä ilmoitamme traitin trait-avainsanalla ja sitten traitin nimen, joka tässä tapauksessa on Summary. Ilmoitamme traitin myös pub-määritteellä, jotta tästä cratesta riippuvat cratet voivat käyttää tätä traitia myös, kuten näemme muutamassa esimerkissä. Aaltosulkeiden sisällä ilmoitamme metodien allekirjoitukset, jotka kuvaavat tämän traitin toteuttavien tyyppien käyttäytymistä, joka tässä tapauksessa on fn summarize(&self) -> String.

Metodin allekirjoituksen jälkeen käytämme puolipistettä aaltosulkeiden sijaan. Jokaisen tämän traitin toteuttavan tyypin täytyy tarjota oma mukautettu käyttäytymänsä metodin rungolle. Kääntäjä varmistaa, että jokaisella tyypillä, jolla on Summary-trait, on metodi summarize määriteltynä täsmälleen tällä allekirjoituksella.

Traitilla voi olla useita metodeja rungossaan: Metodien allekirjoitukset luetellaan yksi per rivi, ja jokainen rivi päättyy puolipisteeseen.

Traitin toteuttaminen tyypille

Nyt kun olemme määritelleet Summary-traitin metodien halutut allekirjoitukset, voimme toteuttaa sen mediakoostajamme tyypeille. Listaus 10-13 näyttää Summary-traitin toteutuksen NewsArticle-structille, joka käyttää otsikkoa, kirjoittajaa ja sijaintia luodakseen summarize-metodin palautusarvon. SocialPost-structille määrittelemme summarize-metodin käyttäjänimen jälkeen koko julkaisun tekstin olettaen, että julkaisun sisältö on jo rajoitettu 280 merkkiin.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-13/src/lib.rs:here}}

Traitin toteuttaminen tyypille on samanlaista kuin tavallisten metodien toteuttaminen. Ero on siinä, että impl-avainsanan jälkeen laitamme toteutettavan traitin nimen, sitten for-avainsanan ja sitten tyypin nimen, jolle haluamme toteuttaa traitin. impl-lohkon sisällä laitamme metodien allekirjoitukset, jotka trait-määrittely on määritellyt. Sen sijaan, että lisäisimme puolipisteen jokaisen allekirjoituksen jälkeen, käytämme aaltosulkeita ja täytämme metodin rungon traitin metodien haluamalla käyttäytymisellä kyseiselle tyypille.

Nyt kun kirjasto on toteuttanut Summary-traitin NewsArticle- ja SocialPost-tyypeille, craten käyttäjät voivat kutsua trait-metodeja NewsArticle- ja SocialPost-instansseilla samalla tavalla kuin kutsumme tavallisia metodeja. Ainoa ero on, että käyttäjän täytyy tuoda trait näkyviin tyyppejen ohella. Tässä on esimerkki siitä, miten binääricrate voisi käyttää aggregator-kirjastocrateamme:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-01-calling-trait-method/src/main.rs}}

Tämä koodi tulostaa 1 new post: horse_ebooks: of course, as you probably already know, people.

Muut aggregator-cratesta riippuvat cratet voivat myös tuoda Summary- traitin näkyviin toteuttaakseen Summary-traitin omille tyypeilleen. Yksi rajoitus on huomionarvoista: voimme toteuttaa traitin tyypille vain, jos joko trait tai tyyppi, tai molemmat, ovat paikallisia crateamme. Esimerkiksi voimme toteuttaa standardikirjaston traitteja kuten Display mukautetulle tyypille kuten SocialPost osana aggregator-cratemme toiminnallisuutta, koska tyyppi SocialPost on paikallinen aggregator-cratemme. Voimme myös toteuttaa Summary-traitin Vec<T>:lle aggregator-cratemme, koska trait Summary on paikallinen aggregator-cratemme.

Emme voi kuitenkaan toteuttaa ulkoisia traitteja ulkoisille tyypeille. Esimerkiksi emme voi toteuttaa Display-traitia Vec<T>:lle aggregator-cratemme sisällä, koska Display ja Vec<T> on molemmat määritelty standardikirjastossa eivätkä ole paikallisia aggregator-cratemme. Tämä rajoitus on osa ominaisuutta nimeltä koherenssi (coherence), ja tarkemmin orvokkosääntöä (orphan rule), joka on nimetty niin, koska ylätyyppi ei ole läsnä. Tämä sääntö varmistaa, etteivät muiden ihmisten koodit voi rikkoa sinun koodiasi ja päinvastoin. Ilman sääntöä kaksi cratea voisi toteuttaa saman traitin samalle tyypille, eikä Rust tietäisi, mitä toteutusta käyttää.

Oletustoteutusten käyttö

Joskus on hyödyllistä, että traitin joillakin tai kaikilla metodeilla on oletuskäyttäytymistä sen sijaan, että vaadittaisiin toteutuksia kaikille metodeille jokaiselle tyypille. Sitten, kun toteutamme traitin tietylle tyypille, voimme säilyttää tai ohittaa kunkin metodin oletuskäyttäytymisen.

Listauksessa 10-14 määrittelemme oletusmerkkijonon Summary-traitin summarize-metodille sen sijaan, että määrittelisimme vain metodin allekirjoituksen, kuten teimme listauksessa 10-12.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-14/src/lib.rs:here}}

Käyttääksemme oletustoteutusta NewsArticle-instanssien yhteenvetoon määrittelemme tyhjän impl-lohkon impl Summary for NewsArticle {}.

Vaikka emme enää määrittele summarize-metodia suoraan NewsArticle-tyypille, olemme tarjonneet oletustoteutuksen ja määritelleet, että NewsArticle toteuttaa Summary-traitin. Näin voimme silti kutsua summarize-metodia NewsArticle-instanssilla, näin:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-02-calling-default-impl/src/main.rs:here}}

Tämä koodi tulostaa New article available! (Read more...).

Oletustoteutuksen luominen ei vaadi meitä muuttamaan mitään Summary-traitin toteutuksesta SocialPost-tyypille listauksessa 10-13. Syy on, että syntaksi oletustoteutuksen ohittamiseen on sama kuin trait-metodin toteuttamiseen, jolla ei ole oletustoteutusta.

Oletustoteutukset voivat kutsua muita metodeja samassa traitissa, vaikka näillä muilla metodeilla ei olisikaan oletustoteutusta. Näin trait voi tarjota paljon hyödyllistä toiminnallisuutta ja vaatia toteuttajilta vain pienen osan määrittelyä. Esimerkiksi voisimme määritellä Summary-traitille summarize_author-metodin, jonka toteutus on pakollinen, ja sitten määritellä summarize-metodin, jolla on oletustoteutus, joka kutsuu summarize_author- metodia:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-03-default-impl-calls-other-methods/src/lib.rs:here}}

Käyttääksemme tätä Summary-traitin versiota meidän täytyy määritellä vain summarize_author, kun toteutamme traitin tyypille:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-03-default-impl-calls-other-methods/src/lib.rs:impl}}

Kun olemme määritelleet summarize_author-metodin, voimme kutsua summarize- metodia SocialPost-structin instansseilla, ja summarize-metodin oletustoteutus kutsuu tarjoamaamme summarize_author-määrittelyä. Koska olemme toteuttaneet summarize_author-metodin, Summary-trait on antanut meille summarize-metodin käyttäytymisen ilman, että meidän tarvitsee kirjoittaa enempää koodia. Tältä se näyttää:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-03-default-impl-calls-other-methods/src/main.rs:here}}

Tämä koodi tulostaa 1 new post: (Read more from @horse_ebooks...).

Huomaa, ettei ole mahdollista kutsua oletustoteutusta saman metodin ohittavasta toteutuksesta.

Traittien käyttö parametreina

Nyt kun tiedät, miten traitteja määritellään ja toteutetaan, voimme tutkia, miten traitteja käytetään määrittelemään funktioita, jotka hyväksyvät monia eri tyyppejä. Käytämme Summary-traitia, jonka toteutimme NewsArticle- ja SocialPost-tyypeille listauksessa 10-13, määritelläksemme notify-funktion, joka kutsuu summarize-metodia item-parametrillaan, joka on jokin tyyppi, joka toteuttaa Summary-traitin. Teemme tämän käyttämällä impl Trait- syntaksia, näin:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-04-traits-as-parameters/src/lib.rs:here}}

Sen sijaan, että item-parametrilla olisi konkreettinen tyyppi, määrittelemme impl-avainsanan ja traitin nimen. Tämä parametri hyväksyy minkä tahansa tyypin, joka toteuttaa määritellyn traitin. notify-funktion rungossa voimme kutsua mitä tahansa item-metodeja, jotka tulevat Summary-traitista, kuten summarize. Voimme kutsua notify-funktiota ja antaa sille minkä tahansa NewsArticle- tai SocialPost-instanssin. Koodi, joka kutsuu funktiota millä tahansa muulla tyypillä, kuten String tai i32, ei käänny, koska nämä tyypit eivät toteuta Summary-traitia.

Trait-rajasyntaksi

impl Trait -syntaksi toimii suoraviivaisissa tapauksissa, mutta se on itse asiassa syntaktista sokeria pidemmälle muodolle, joka tunnetaan nimellä trait-raja (trait bound); se näyttää tältä:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

Tämä pidempi muoto on vastaava kuin edellisen osion esimerkki, mutta sanallisempi. Sijoitamme trait-rajat geneerisen tyyppiparametrin ilmoituksen jälkeen kaksoispisteen jälkeen kulmasulkeisiin.

impl Trait -syntaksi on kätevä ja tekee koodista tiiviimpää yksinkertaisissa tapauksissa, kun taas täydellisempi trait-rajasyntaksi voi ilmaista monimutkaisempaa muissa tapauksissa. Esimerkiksi voimme olla kaksi parametria, jotka toteuttavat Summary-traitin. Tämä impl Trait -syntaksilla näyttää tältä:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

impl Trait -syntaksin käyttö on sopivaa, jos haluamme tämän funktion sallivan item1:n ja item2:n olevan eri tyyppejä (kunhan molemmat tyypit toteuttavat Summary-traitin). Jos haluamme kuitenkin pakottaa molemmat parametrit olemaan samaa tyyppiä, meidän täytyy käyttää trait-rajaa, näin:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

Geneerinen tyyppi T, joka on määritelty item1- ja item2-parametrien tyypiksi, rajoittaa funktion siten, että argumenttina annetun arvon konkreettisen tyypin täytyy olla sama item1:lle ja item2:lle.

Useat trait-rajat +-syntaksilla

Voimme myös määrittää useamman kuin yhden trait-rajan. Sanotaan, että haluamme notify-funktion käyttävän näyttömuotoilua sekä summarize-metodia item-parametrilla: Määrittelemme notify-määrittelyssä, että item täytyy toteuttaa sekä Display että Summary. Voimme tehdä näin käyttämällä +- syntaksia:

pub fn notify(item: &(impl Summary + Display)) {

+-syntaksi on kelvollinen myös geneeristen tyyppien trait-rajoissa:

pub fn notify<T: Summary + Display>(item: &T) {

Kun kaksi trait-rajaa on määritelty, notify-funktion runko voi kutsua summarize-metodia ja käyttää {}-muotoilua item-parametrille.

Selkeämmät trait-rajat where-lausekkeilla

Liian monien trait-rajojen käytöllä on haittapuolensa. Jokaisella geneerisellä tyypillä on omat trait-rajansa, joten funktioilla, joilla on useita geneerisiä tyyppiparametreja, voi olla paljon trait-rajatietoa funktion nimen ja parametrilistan välissä, mikä tekee funktion allekirjoituksesta vaikealukuisen. Tästä syystä Rustissa on vaihtoehtoinen syntaksi trait-rajojen määrittelyyn where-lausekkeessa funktion allekirjoituksen jälkeen. Sen sijaan, että kirjoittaisimme tämän:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

voimme käyttää where-lauseketta, näin:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-07-where-clause/src/lib.rs:here}}

Tämän funktion allekirjoitus on vähemmän sekava: Funktion nimi, parametrilista ja palautustyyppi ovat lähellä toisiaan, samoin kuin funktiossa, jossa ei ole paljon trait-rajoja.

Traitin toteuttavien tyyppien palauttaminen

Voimme myös käyttää impl Trait -syntaksia palautuspaikassa palauttaaksemme jonkin traitin toteuttavan tyypin arvon, kuten tässä:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-05-returning-impl-trait/src/lib.rs:here}}

Käyttämällä impl Summary palautustyypinä määrittelemme, että returns_summarizable-funktio palauttaa jonkin Summary-traitin toteuttavan tyypin nimeämättä konkreettista tyyppiä. Tässä tapauksessa returns_summarizable palauttaa SocialPost-instanssin, mutta tätä funktiota kutsuvan koodin ei tarvitse tietää sitä.

Mahdollisuus määrittää palautustyyppi vain sen toteuttaman traitin perusteella on erityisen hyödyllinen sulkujen ja iteraattorien yhteydessä, joita käsittelemme luvussa 13. Sulut ja iteraattorit luovat tyyppejä, jotka vain kääntäjä tuntee, tai tyyppejä, joiden määrittely on hyvin pitkä. impl Trait -syntaksi antaa sinun määrittää tiiviisti, että funktio palauttaa jonkin Iterator-traitin toteuttavan tyypin ilman, että sinun tarvitsee kirjoittaa hyvin pitkää tyyppiä.

Voit kuitenkin käyttää impl Trait -syntaksia vain, jos palautat yhden tyypin. Esimerkiksi tämä koodi, joka palauttaa joko NewsArticle- tai SocialPost- instanssin palautustyypin ollessa impl Summary, ei toimisi:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-06-impl-trait-returns-one-type/src/lib.rs:here}}

Joko NewsArticle- tai SocialPost-instanssin palauttaminen ei ole sallittua impl Trait -syntaksin kääntäjässä toteutettujen rajoitusten vuoksi. Käsittelemme, miten kirjoitamme funktion tällä käyttäytymisellä luvun 18 osiossa ”Trait- olioiden käyttö jaetun käyttäytymisen abstrahointiin”.

Metodien ehdollinen toteuttaminen trait-rajojen avulla

Käyttämällä trait-rajaa impl-lohkossa, joka käyttää geneerisiä tyyppiparametreja, voimme toteuttaa metodeja ehdollisesti tyypeille, jotka toteuttavat määritellyt traitit. Esimerkiksi tyyppi Pair<T> listauksessa 10-15 toteuttaa aina new-funktion palauttaakseen uuden Pair<T>-instanssin (muista luvun 5 ”Metodisyntaksi” -osiosta, että Self on tyyppialias impl-lohkon tyypille, joka tässä tapauksessa on Pair<T>). Mutta seuraavassa impl-lohkossa Pair<T> toteuttaa cmp_display- metodin vain, jos sen sisäinen tyyppi T toteuttaa PartialOrd-traitin, joka mahdollistaa vertailun, ja Display-traitin, joka mahdollistaa tulostamisen.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-15/src/lib.rs}}

Voimme myös toteuttaa traitin ehdollisesti mille tahansa tyypille, joka toteuttaa toisen traitin. Traitin toteutukset mille tahansa tyypille, joka täyttää trait-rajat, kutsutaan peittoimplementaatioiksi (blanket implementations), ja niitä käytetään laajasti Rustin standardikirjastossa. Esimerkiksi standardikirjasto toteuttaa ToString-traitin mille tahansa tyypille, joka toteuttaa Display-traitin. Standardikirjaston impl-lohko näyttää suunnilleen tältä:

impl<T: Display> ToString for T {
    // --snip--
}

Koska standardikirjastossa on tämä peittoimplementaatio, voimme kutsua ToString-traitin määrittelemää to_string-metodia millä tahansa tyypillä, joka toteuttaa Display-traitin. Esimerkiksi voimme muuttaa kokonaisluvut vastaaviksi String-arvoiksi näin, koska kokonaisluvut toteuttavat Display-traitin:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

Peittoimplementaatiot näkyvät traitin dokumentaatiossa ”Implementors”-osiossa.

Traitit ja trait-rajat antavat meille mahdollisuuden kirjoittaa koodia, joka käyttää geneerisiä tyyppiparametreja vähentääkseen toistoa, mutta myös määrittää kääntäjälle, että haluamme geneerisen tyypin omaavan tiettyä käyttäytymistä. Kääntäjä voi sitten käyttää trait-rajatietoa tarkistaakseen, että kaikki koodissamme käytetyt konkreettiset tyypit tarjoavat oikean käyttäytymisen. Dynaamisesti tyypitetyissä kielissä saisimme virheen ajonaikana, jos kutsuisimme metodia tyypille, joka ei määrittele metodia. Mutta Rust siirtää nämä virheet käännösaikaan, joten meidän täytyy korjata ongelmat ennen kuin koodimme edes pystyy suorittumaan. Lisäksi emme tarvitse kirjoittaa koodia, joka tarkistaa käyttäytymistä ajonaikana, koska olemme jo tarkistaneet käännösaikana. Näin parannamme suorituskykyä luopumatta geneeristen tyyppien joustavuudesta.

Viitteiden vahvistaminen eliniillä

Viittausten validointi elinikien avulla

Eliniät (lifetimes) ovat toinen geneeristen tyyppien laji, jota olemme jo käyttäneet. Sen sijaan, että varmistaisimme tyypin käyttäytyvän haluamallamme tavalla, eliniät varmistavat, että viittaukset ovat kelvollisia niin kauan kuin tarvitsemme niitä.

Yksi yksityiskohta, jota emme käsitelleet luvun 4 osiossa ”Viittaukset ja lainaaminen”, on se, että jokaisella Rustin viittauksella on elinikä, joka on alue, jolla viittaus on kelvollinen. Useimmiten eliniät ovat implisiittisiä ja pääteltyjä, aivan kuten useimmiten tyypit ovat pääteltyjä. Meidän täytyy ilmoittaa tyypit vain, kun useita tyyppejä on mahdollista. Vastaavasti meidän täytyy merkitä eliniät, kun viittausten eliniöillä voi olla useita eri suhteita. Rust vaatii meitä merkitsemään suhteet geneeristen elinikäparametrien avulla varmistaakseen, että ajonaikana käytetyt viittaukset ovat varmasti kelvollisia.

Elinikien merkitseminen ei ole edes käsite, jota useimmissa muissa ohjelmointikielissä on, joten tämä tuntuu tutustumattomalta. Vaikka emme käsittele eliniä kokonaisuudessaan tässä luvussa, käsittelemme yleisiä tapoja, joilla voit kohdata elinikäsyntaksia, jotta voit tottua käsitteeseen.

Riippuvat viittaukset

Elinikien pääasiallinen tarkoitus on estää riippuvia viittauksia (dangling references), jotka, jos niiden olemassaolo sallittaisiin, saisivat ohjelman viittaamaan muihin tietoihin kuin niihin, joihin sen on tarkoitus viitata. Harkitse listauksen 10-16 ohjelmaa, jossa on ulompi ja sisempi näkyvyysalue.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-16/src/main.rs}}

Huom: Listausten 10-16, 10-17 ja 10-23 esimerkit ilmoittavat muuttujia antamatta niille alkuarvoa, joten muuttujan nimi on olemassa ulommalla näkyvyysalueella. Ensi silmäyksellä tämä saattaa vaikuttaa ristiriitaiselta Rustin null-arvojen puuttumisen kanssa. Jos kuitenkin yritämme käyttää muuttujaa ennen arvon antamista, saamme käännösvirheen, mikä osoittaa, että Rust todellakaan ei salli null-arvoja.

Ulompi näkyvyysalue ilmoittaa muuttujan nimeltä r ilman alkuarvoa, ja sisempi näkyvyysalue ilmoittaa muuttujan nimeltä x alkuarvolla 5. Sisemmällä näkyvyysalueella yritämme asettaa r:n arvoksi viittauksen x:ään. Sitten sisempi näkyvyysalue päättyy, ja yritämme tulostaa r:n arvon. Tämä koodi ei käänny, koska arvo, johon r viittaa, on poistunut näkyvyysalueelta ennen kuin yritämme käyttää sitä. Tässä on virheilmoitus:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-16/output.txt}}

Virheilmoitus sanoo, että muuttuja x ”does not live long enough”. Syy on, että x on näkyvyysalueen ulkopuolella, kun sisempi näkyvyysalue päättyy rivillä 7. Mutta r on silti kelvollinen ulommalla näkyvyysalueella; koska sen näkyvyysalue on suurempi, sanomme, että se ”elää pidempään”. Jos Rust sallisi tämän koodin toimia, r viittaisi muistiin, joka vapautettiin, kun x poistui näkyvyysalueelta, eikä mikään, mitä yrittäisimme tehdä r:llä, toimisi oikein. Miten Rust määrittää, että tämä koodi on virheellinen? Se käyttää lainauskontrolleria.

Lainauskontrolleri

Rustin kääntäjällä on lainauskontrolleri (borrow checker), joka vertaa näkyvyysalueita määrittääkseen, ovatko kaikki lainaukset kelvollisia. Listaus 10-17 näyttää saman koodin kuin listaus 10-16, mutta merkinnöillä, jotka näyttävät muuttujien eliniät.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-17/src/main.rs}}

Tässä olemme merkinneet r:n eliniän 'a:lla ja x:n eliniän 'b:llä. Kuten näet, sisempi 'b-lohko on paljon pienempi kuin ulompi 'a-elinikälohko. Käännösaikana Rust vertaa kahden eliniän kokoa ja näkee, että r:llä on elinikä 'a, mutta se viittaa muistiin, jonka elinikä on 'b. Ohjelma hylätään, koska 'b on lyhyempi kuin 'a: Viittauksen kohteella ei ole yhtä pitkää elinikää kuin viittauksella.

Listaus 10-18 korjaa koodin niin, ettei siinä ole riippuvaa viittausta, ja se kääntyy ilman virheitä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-18/src/main.rs}}
}

Tässä x:llä on elinikä 'b, joka tässä tapauksessa on suurempi kuin 'a. Tämä tarkoittaa, että r voi viitata x:ään, koska Rust tietää, että r:n viittaus on aina kelvollinen niin kauan kuin x on kelvollinen.

Nyt kun tiedät, missä viittausten eliniät ovat ja miten Rust analysoi eliniitä varmistaakseen, että viittaukset ovat aina kelvollisia, tutkitaan geneerisiä eliniä funktioiden parametreissa ja palautusarvoissa.

Geneeriset eliniät funktioissa

Kirjoitamme funktion, joka palauttaa pidemmän kahdesta merkkijonoviipaleesta. Tämä funktio ottaa kaksi merkkijonoviipaletta ja palauttaa yhden merkkijonoviipaleen. Kun olemme toteuttaneet longest-funktion, listauksen 10-19 koodin pitäisi tulostaa The longest string is abcd.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-19/src/main.rs}}

Huomaa, että haluamme funktion ottavan merkkijonoviipaleita, jotka ovat viittauksia, eivät merkkijonoja, koska emme halua longest-funktion ottavan parametriensa omistajuutta. Katso lisätietoja siitä, miksi listauksen 10-19 parametrit ovat haluamiamme, luvun 4 osiosta ”Merkkijonoviipaleet parametreina”.

Jos yritämme toteuttaa longest-funktion kuten listauksessa 10-20, se ei käänny.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-20/src/main.rs:here}}

Sen sijaan saamme seuraavan virheen, joka käsittelee eliniitä:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-20/output.txt}}

Ohjeteksti paljastaa, että palautustyypillä täytyy olla geneerinen elinikäparametri, koska Rust ei voi kertoa, viittaako palautettava viittaus x:ään vai y:ään. Itse asiassa emme tiedä sitäkään, koska funktion rungon if-lohko palauttaa viittauksen x:ään ja else-lohko viittauksen y:ään!

Kun määrittelemme tämän funktion, emme tiedä konkreettisia arvoja, jotka annetaan tälle funktiolle, joten emme tiedä, suoritetaanko if- vai else- tapaus. Emme myöskään tiedä viittausten konkreettisia eliniä, joten emme voi tarkastella näkyvyysalueita kuten listauksissa 10-17 ja 10-18 määrittääksemme, onko palauttamamme viittaus aina kelvollinen. Lainauskontrolleri ei voi määrittää tätäkään, koska se ei tiedä, miten x:n ja y:n eliniät liittyvät palautusarvon elinikään. Korjataksemme tämän virheen lisäämme geneerisiä elinikäparametreja, jotka määrittelevät viittausten välisen suhteen, jotta lainauskontrolleri voi suorittaa analyysinsä.

Elinikämerkintöjen syntaksi

Elinikämerkinnät eivät muuta sitä, kuinka kauan mikään viittauksista elää. Pikemminkin ne kuvaavat useiden viittausten eliniöiden välisiä suhteita vaikuttamatta eliniöihin. Aivan kuten funktiot voivat hyväksyä minkä tahansa tyypin, kun allekirjoitus määrittää geneerisen tyyppiparametrin, funktiot voivat hyväksyä viittauksia millä tahansa eliniällä määrittämällä geneerisen elinikäparametrin.

Elinikämerkinnöillä on hieman epätavallinen syntaksi: Elinikäparametrien nimien täytyy alkaa heittomerkillä (') ja ne ovat yleensä pieniä kirjaimia ja hyvin lyhyitä, kuten geneeriset tyypit. Useimmat ihmiset käyttävät nimeä 'a ensimmäiselle elinikämerkinnälle. Sijoitamme elinikäparametrien merkinnät &-merkin jälkeen viittauksessa käyttäen välilyöntiä erottamaan merkinnän viittauksen tyypistä.

Tässä on joitakin esimerkkejä — viittaus i32:een ilman elinikäparametria, viittaus i32:een, jolla on elinikäparametri nimeltä 'a, ja muuttuva viittaus i32:een, jolla on myös elinikä 'a:

&i32        // a reference
&'a i32     // a reference with an explicit lifetime
&'a mut i32 // a mutable reference with an explicit lifetime

Yksi elinikämerkintä itsessään ei merkitse paljon, koska merkinnät on tarkoitettu kertomaan Rustille, miten useiden viittausten geneeriset elinikäparametrit liittyvät toisiinsa. Tarkastellaan, miten elinikämerkinnät liittyvät toisiinsa longest-funktion yhteydessä.

Funktioiden allekirjoituksissa

Käyttääksemme elinikämerkintöjä funktioiden allekirjoituksissa meidän täytyy ilmoittaa geneeriset elinikäparametrit kulmasulkeissa funktion nimen ja parametrilistan välissä, aivan kuten teimme geneeristen tyyppiparametrien kanssa.

Haluamme allekirjoituksen ilmaisevan seuraavan rajoituksen: Palautettu viittaus on kelvollinen niin kauan kuin molemmat parametrit ovat kelvollisia. Tämä on parametrien ja palautusarvon eliniöiden välinen suhde. Nimeämme eliniän 'a:ksi ja lisäämme sen jokaiseen viittaukseen, kuten listauksessa 10-21.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-21/src/main.rs:here}}
}

Tämän koodin pitäisi kääntyä ja tuottaa haluamamme tuloksen, kun käytämme sitä listauksen 10-19 main-funktion kanssa.

Funktion allekirjoitus kertoo nyt Rustille, että jollekin eliniälle 'a funktio ottaa kaksi parametria, jotka molemmat ovat merkkijonoviipaleita, jotka elävät vähintään yhtä kauan kuin elinikä 'a. Funktion allekirjoitus kertoo myös Rustille, että funktiosta palautettu merkkijonoviipale elää vähintään yhtä kauan kuin elinikä 'a. Käytännössä tämä tarkoittaa, että longest-funktion palauttaman viittauksen elinikä on sama kuin funktioargumenttien viittaamien arvojen eliniöistä lyhyempi. Nämä suhteet ovat ne, joita haluamme Rustin käyttävän analysoidessaan tätä koodia.

Muista, että kun määrittelemme elinikäparametrit tässä funktion allekirjoituksessa, emme muuta annettujen tai palautettujen arvojen eliniöitä. Pikemminkin määrittelemme, että lainauskontrollerin täytyy hylätä kaikki arvot, jotka eivät noudata näitä rajoituksia. Huomaa, että longest-funktion ei tarvitse tietää tarkalleen, kuinka kauan x ja y elävät, vain että jokin näkyvyysalue voidaan korvata 'a:lla, joka tyydyttää tämän allekirjoituksen.

Kun merkitsemme eliniöitä funktioissa, merkinnät menevät funktion allekirjoitukseen, ei funktion runkoon. Elinikämerkinnät tulevat osaksi funktion sopimusta, aivan kuten allekirjoituksen tyypit. Funktioallekirjoitusten sisältäminen elinikäsopimus tarkoittaa, että Rust-kääntäjän suorittama analyysi voi olla yksinkertaisempaa. Jos on ongelma funktion merkinnöissä tai sen kutsumisessa, kääntäjän virheet voivat osoittaa koodimme osan ja rajoitukset tarkemmin. Jos sen sijaan Rust- kääntäjä tekisi enemmän päätelmiä siitä, mitä aioimme eliniöiden suhteilla, kääntäjä saattaisi pystyä osoittamaan vain koodimme käytön monia askelia ongelman syystä.

Kun annamme konkreettisia viittauksia longest-funktiolle, konkreettinen elinikä, joka korvaa 'a:n, on osa x:n näkyvyysalueesta, joka leikkaa y:n näkyvyysalueen kanssa. Toisin sanoen geneerinen elinikä 'a saa konkreettisen eliniän, joka on yhtä suuri kuin x:n ja y:n eliniöistä lyhyempi. Koska olemme merkinneet palautetun viittauksen samalla elinikäparametrilla 'a, palautettu viittaus on myös kelvollinen x:n ja y:n eliniöistä lyhyemmän pituuden ajan.

Katsotaan, miten elinikämerkinnät rajoittavat longest-funktiota antamalla viittauksia, joilla on eri konkreettiset eliniät. Listaus 10-22 on suoraviivainen esimerkki.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-22/src/main.rs:here}}
}

Tässä esimerkissä string1 on kelvollinen ulomman näkyvyysalueen loppuun asti, string2 on kelvollinen sisemmän näkyvyysalueen loppuun asti, ja result viittaa johonkin, joka on kelvollinen sisemmän näkyvyysalueen loppuun asti. Aja tämä koodi ja näet, että lainauskontrolleri hyväksyy sen; se kääntyy ja tulostaa The longest string is long string is long.

Seuraavaksi kokeillaan esimerkkiä, joka näyttää, että result-viittauksen elinikän täytyy olla kahden argumentin lyhyempi elinikä. Siirrämme result- muuttujan ilmoituksen sisemmän näkyvyysalueen ulkopuolelle, mutta jätämme arvon result-muuttujalle antamisen sisemmän näkyvyysalueen sisälle string2:n kanssa. Sitten siirrämme result:ia käyttävän println!:n sisemmän näkyvyysalueen ulkopuolelle, sen päättymisen jälkeen. Listauksen 10-23 koodi ei käänny.

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-23/src/main.rs:here}}

Kun yritämme kääntää tämän koodin, saamme tämän virheen:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-23/output.txt}}

Virhe näyttää, että jotta result olisi kelvollinen println!-lauseelle, string2:n täytyisi olla kelvollinen ulomman näkyvyysalueen loppuun asti. Rust tietää tämän, koska olemme merkinneet funktioiden parametrien ja palautusarvojen eliniät käyttämällä samaa elinikäparametria 'a.

Ihmisinä voimme katsoa tätä koodia ja nähdä, että string1 on pidempi kuin string2, ja siksi result sisältää viittauksen string1:een. Koska string1 ei ole vielä poistunut näkyvyysalueelta, viittaus string1:een on silti kelvollinen println!-lauseelle. Kääntäjä ei kuitenkaan näe, että viittaus on kelvollinen tässä tapauksessa. Olemme kertoneet Rustille, että longest- funktion palauttaman viittauksen elinikä on sama kuin annettujen viittausten eliniöistä lyhyempi. Siksi lainauskontrolleri kieltää listauksen 10-23 koodin, koska siinä voi olla virheellinen viittaus.

Kokeile suunnitella lisää kokeita, joissa vaihtelet longest-funktiolle annettujen viittausten arvoja ja eliniöitä sekä sitä, miten palautettua viittausta käytetään. Tee hypoteeseja siitä, läpäisevätkö kokeesi lainauskontrollerin ennen kääntämistä; tarkista sitten, olitko oikeassa!

Suhteet

Tapa, jolla sinun täytyy määrittää elinikäparametrit, riippuu siitä, mitä funktiosi tekee. Esimerkiksi, jos muuttaisimme longest-funktion toteutusta palauttamaan aina ensimmäisen parametrin pidemmän merkkijonoviipaleen sijaan, emme tarvitsisi määrittää elinikää y-parametrille. Seuraava koodi kääntyy:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-08-only-one-reference-with-lifetime/src/main.rs:here}}
}

Olemme määrittäneet elinikäparametrin 'a parametrille x ja palautustyypille, mutta emme parametrille y, koska y:n eliniällä ei ole mitään suhdetta x:n tai palautusarvon elinikään.

Kun palautamme viittauksen funktiosta, palautustyypin elinikäparametrin täytyy vastata jonkin parametrin elinikäparametria. Jos palautettu viittaus ei viittaa mihinkään parametreista, sen täytyy viitata tässä funktiossa luotuun arvoon. Tämä olisi kuitenkin riippuva viittaus, koska arvo poistuu näkyvyysalueelta funktion lopussa. Harkitse tätä yritystä toteuttaa longest- funktio, joka ei käänny:

{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-09-unrelated-lifetime/src/main.rs:here}}

Tässä, vaikka olemme määrittäneet elinikäparametrin 'a palautustyypille, tämä toteutus ei käänny, koska palautusarvon elinikä ei liity parametrien eliniöihin ollenkaan. Tässä on virheilmoitus, jonka saamme:

{{#include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-09-unrelated-lifetime/output.txt}}

Ongelma on, että result poistuu näkyvyysalueelta ja siivotaan longest- funktion lopussa. Yritämme myös palauttaa viittauksen result:iin funktiosta. Emme voi määrittää elinikäparametreja, jotka muuttaisivat riippuvaa viittausta, eikä Rust anna meidän luoda riippuvaa viittausta. Tässä tapauksessa paras korjaus olisi palauttaa omistettu tietotyyppi viittauksen sijaan, jolloin kutsuva funktio on vastuussa arvon siivoamisesta.

Lopulta elinikäsyntaksi koskee eri parametrien ja funktioiden palautusarvojen eliniöiden yhdistämistä. Kun ne on yhdistetty, Rustilla on tarpeeksi tietoa salliakseen muistiturvalliset operaatiot ja kieltääkseen operaatiot, jotka luoisivat riippuvia osoittimia tai muuten rikkoisivat muistiturvallisuutta.

Struct-määrittelyissä

Tähän asti määrittelemämme structit säilyttävät kaikki omistettuja tyyppejä. Voimme määritellä structeja säilyttämään viittauksia, mutta siinä tapauksessa meidän täytyy lisätä elinikämerkintä jokaiseen viittaukseen structin määrittelyssä. Listauksessa 10-24 on struct nimeltä ImportantExcerpt, joka säilyttää merkkijonoviipaleen.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-24/src/main.rs}}
}

Tällä structilla on yksi kenttä part, joka säilyttää merkkijonoviipaleen, joka on viittaus. Kuten geneeristen tietotyyppien kanssa, ilmoitamme geneerisen elinikäparametrin nimen kulmasulkeissa structin nimen jälkeen, jotta voimme käyttää elinikäparametria struct-määrittelyn rungossa. Tämä merkintä tarkoittaa, että ImportantExcerpt-instanssi ei voi elää pidempään kuin viittaus, jonka se säilyttää part-kentässään.

Tässä main-funktio luo ImportantExcerpt-structin instanssin, joka säilyttää viittauksen muuttujan novel omistaman String-arvon ensimmäiseen lauseeseen. novel-datan on olemassa ennen ImportantExcerpt-instanssin luomista. Lisäksi novel ei poistu näkyvyysalueelta ennen kuin ImportantExcerpt poistuu näkyvyysalueelta, joten ImportantExcerpt-instanssin viittaus on kelvollinen.

Elinikien poisjättäminen

Olet oppinut, että jokaisella viittauksella on elinikä ja että sinun täytyy määrittää elinikäparametrit funktioille tai structeille, jotka käyttävät viittauksia. Meillä oli kuitenkin funktio listauksessa 4-9, joka näytetään uudelleen listauksessa 10-25, ja se kääntyi ilman elinikämerkintöjä.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/listing-10-25/src/main.rs:here}}
}

Syy, miksi tämä funktio kääntyy ilman elinikämerkintöjä, on historiallinen: Rustin varhaisissa versioissa (ennen 1.0) tämä koodi ei olisi kääntynyt, koska jokainen viittaus tarvitsi eksplisiittisen eliniän. Silloin funktion allekirjoitus olisi kirjoitettu näin:

fn first_word<'a>(s: &'a str) -> &'a str {

Kun Rust-tiimi oli kirjoittanut paljon Rust-koodia, he huomasivat, että Rust- ohjelmoijat kirjoittivat samoja elinikämerkintöjä yhä uudelleen tietyissä tilanteissa. Nämä tilanteet olivat ennustettavia ja noudattivat muutamia deterministisiä kuvioita. Kehittäjät ohjelmoivat nämä kuviot kääntäjän koodiin, jotta lainauskontrolleri voisi päätellä eliniät näissä tilanteissa eikä eksplisiittisiä merkintöjä tarvittaisi.

Tämä Rustin historia on merkityksellinen, koska on mahdollista, että lisää deterministisiä kuvioita ilmestyy ja lisätään kääntäjään. Tulevaisuudessa vähemmän elinikämerkintöjä saattaa olla tarpeen.

Kuviot, jotka on ohjelmoitu Rustin viittausten analyysiin, kutsutaan elinikien poisjättämissäännöiksi (lifetime elision rules). Nämä eivät ole sääntöjä ohjelmoijille noudatettavaksi; ne ovat joukko erityisiä tapauksia, joita kääntäjä harkitsee, ja jos koodisi sopii näihin tapauksiin, sinun ei tarvitse kirjoittaa eliniöitä eksplisiittisesti.

Poisjättämissäännöt eivät tarjoa täyttä päätelmää. Jos viittausten eliniöistä on vielä epäselvyyttä Rustin sovellettua sääntöjä, kääntäjä ei arvaa, mikä jäljellä olevien viittausten elinikä pitäisi olla. Arvaamisen sijaan kääntäjä antaa virheen, jonka voit ratkaista lisäämällä elinikämerkinnät.

Funktio- tai metodiparametrien eliniöitä kutsutaan syöttöeliniöiksi (input lifetimes), ja palautusarvojen eliniöitä tuottoeliniöiksi (output lifetimes).

Kääntäjä käyttää kolmea sääntöä selvittääkseen viittausten eliniöitä, kun eksplisiittisiä merkintöjä ei ole. Ensimmäinen sääntö koskee syöttöeliniöitä, ja toinen ja kolmas sääntö koskevat tuottoeliniöitä. Jos kääntäjä pääsee kolmen säännön loppuun ja viittauksia on vielä, joiden eliniöitä se ei voi selvittää, kääntäjä pysähtyy virheeseen. Nämä säännöt koskevat fn-määrittelyjä sekä impl-lohkoja.

Ensimmäinen sääntö on, että kääntäjä määrittää elinikäparametrin jokaiselle parametrille, joka on viittaus. Toisin sanoen funktio, jolla on yksi parametri, saa yhden elinikäparametrin: fn foo<'a>(x: &'a i32); funktio, jolla on kaksi parametria, saa kaksi erillistä elinikäparametria: fn foo<'a, 'b>(x: &'a i32, y: &'b i32); ja niin edelleen.

Toinen sääntö on, että jos on täsmälleen yksi syöttöelinikäparametri, se elinikä määritetään kaikille tuottoelinikäparametreille: fn foo<'a>(x: &'a i32) -> &'a i32.

Kolmas sääntö on, että jos on useita syöttöelinikäparametreja, mutta yksi niistä on &self tai &mut self, koska tämä on metodi, self:n elinikä määritetään kaikille tuottoelinikäparametreille. Tämä kolmas sääntö tekee metodeista paljon miellyttävämpiä lukea ja kirjoittaa, koska vähemmän symboleja on tarpeen.

Olkoon me olemme kääntäjä. Sovelletaan näitä sääntöjä selvittääksemme viittausten eliniöt first_word-funktion allekirjoituksessa listauksessa 10-25. Allekirjoitus alkaa ilman eliniöitä, jotka liittyvät viittauksiin:

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

Sitten kääntäjä soveltaa ensimmäistä sääntöä, joka määrittää, että jokainen parametri saa oman eliniänsä. Kutsumme sitä 'a:ksi kuten tavallisesti, joten nyt allekirjoitus on tämä:

fn first_word<'a>(s: &'a str) -> &str {

Toinen sääntö pätee, koska on täsmälleen yksi syöttöelinikä. Toinen sääntö määrittää, että yhden syöttöparametrin elinikä määritetään tuottoelinikään, joten allekirjoitus on nyt tämä:

fn first_word<'a>(s: &'a str) -> &'a str {

Nyt kaikilla viittauksilla tässä funktioallekirjoituksessa on eliniät, ja kääntäjä voi jatkaa analyysiään ilman, että ohjelmoijan tarvitsee merkitä eliniöitä tässä funktioallekirjoituksessa.

Katsotaan toista esimerkkiä käyttäen longest-funktiota, jolla ei ollut elinikäparametreja, kun aloimme työskennellä sen kanssa listauksessa 10-20:

fn longest(x: &str, y: &str) -> &str {

Sovelletaan ensimmäistä sääntöä: Jokainen parametri saa oman eliniänsä. Tällä kertaa meillä on kaksi parametria yhden sijaan, joten meillä on kaksi elinikää:

fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &str {

Näet, että toinen sääntö ei päde, koska on useampi kuin yksi syöttöelinikä. Kolmas sääntö ei myöskään päde, koska longest on funktio eikä metodi, joten mikään parametreista ei ole self. Kun olemme käyneet läpi kaikki kolme sääntöä, emme ole vieläkään selvittäneet palautustyypin elinikää. Tämän vuoksi saimme virheen yrittäessämme kääntää listauksen 10-20 koodia: Kääntäjä kävi läpi elinikien poisjättämissäännöt, mutta ei silti voinut selvittää kaikkia viittausten eliniöitä allekirjoituksessa.

Koska kolmas sääntö pätee todella vain metodien allekirjoituksissa, katsomme eliniöitä tässä yhteydessä seuraavaksi nähdäksemme, miksi kolmas sääntö tarkoittaa, ettei meidän tarvitse merkitä eliniöitä metodien allekirjoituksissa usein.

Metodimäärittelyissä

Kun toteutamme metodeja structille, jolla on eliniöitä, käytämme samaa syntaksia kuin geneeristen tyyppiparametrien kanssa, kuten listauksessa 10-11. Missä ilmoitamme ja käytämme elinikäparametreja riippuu siitä, liittyvätkö ne structin kenttiin vai metodin parametreihin ja palautusarvoihin.

Structin kenttien elinikien nimet täytyy aina ilmoittaa impl-avainsanan jälkeen ja sitten käyttää structin nimen jälkeen, koska nämä eliniät ovat osa structin tyyppiä.

impl-lohkon sisällä olevissa metodien allekirjoituksissa viittaukset voivat liittyä structin kenttien viittausten elinikään tai olla riippumattomia. Lisäksi elinikien poisjättämissäännöt usein tekevät niin, ettei elinikämerkintöjä tarvita metodien allekirjoituksissa. Katsotaan joitakin esimerkkejä käyttäen structia nimeltä ImportantExcerpt, jonka määrittelimme listauksessa 10-24.

Ensin käytämme level-nimistä metodia, jonka ainoa parametri on viittaus self:ään ja jonka palautusarvo on i32, joka ei ole viittaus mihinkään:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-10-lifetimes-on-methods/src/main.rs:1st}}
}

Elinikäparametrin ilmoitus impl-avainsanan jälkeen ja sen käyttö tyypin nimen jälkeen ovat pakollisia, mutta ensimmäisen poisjättämissäännön ansiosta emme tarvitse merkitä viittauksen self:n elinikää.

Tässä on esimerkki, jossa kolmas elinikien poisjättämissääntö pätee:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-10-lifetimes-on-methods/src/main.rs:3rd}}
}

On kaksi syöttöelinikää, joten Rust soveltaa ensimmäistä elinikien poisjättämissääntöä ja antaa sekä &self:lle että announcement:ille omat eliniänsä. Sitten, koska yksi parametreista on &self, palautustyyppi saa &self:n eliniän, ja kaikki eliniät on huomioitu.

Staattinen elinikä

Yksi erityinen elinikä, josta meidän täytyy keskustella, on 'static, joka merkitsee, että kyseinen viittaus voi elää koko ohjelman keston. Kaikilla merkkijonoliteraaleilla on 'static-elinikä, jonka voimme merkitä näin:

#![allow(unused)]
fn main() {
let s: &'static str = "I have a static lifetime.";
}

Tämän merkkijonon teksti on tallennettu suoraan ohjelman binääritiedostoon, joka on aina käytettävissä. Siksi kaikkien merkkijonoliteraalien elinikä on 'static.

Saatat nähdä virheilmoituksissa ehdotuksia käyttää 'static-elinikää. Mutta ennen kuin määrittelet 'static-elinikää viittaukselle, mieti, elääkö viittauksesi todella koko ohjelmasi eliniän ja haluatko sen elävän. Useimmiten virheilmoitus, joka ehdottaa 'static-elinikää, johtuu yrityksestä luoda riippuva viittaus tai eliniöjen epäsuhtasta. Tällaisissa tapauksissa ratkaisu on korjata nämä ongelmat, ei määrittää 'static-elinikää.

Geneeriset tyyppiparametrit, trait-rajat ja eliniät yhdessä

Katsotaan lyhyesti syntaksia geneeristen tyyppiparametrien, trait-rajojen ja eliniöiden määrittelyyn yhdessä yhdessä funktiossa!

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch10-generic-types-traits-and-lifetimes/no-listing-11-generics-traits-and-lifetimes/src/main.rs:here}}
}

Tämä on longest-funktio listauksesta 10-21, joka palauttaa pidemmän kahdesta merkkijonoviipaleesta. Mutta nyt siinä on ylimääräinen parametri nimeltä ann geneerisestä tyypistä T, joka voidaan täyttää millä tahansa tyypillä, joka toteuttaa Display-traitin where-lausekkeen määrittämällä tavalla. Tämä ylimääräinen parametri tulostetaan {}-merkinnällä, minkä vuoksi Display- trait-raja on tarpeen. Koska eliniät ovat eräänlaisia geneerisiä tyyppejä, elinikäparametrin 'a ja geneerisen tyyppiparametrin T ilmoitukset menevät samaan listaan kulmasulkeissa funktion nimen jälkeen.

Yhteenveto

Käsittelimme paljon tässä luvussa! Nyt kun tiedät geneerisistä tyyppiparametreista, traitteista ja trait-rajoista sekä geneerisistä elinikäparametreista, olet valmis kirjoittamaan koodia ilman toistoa, joka toimii monissa eri tilanteissa. Geneeriset tyyppiparametrit antavat sinun soveltaa koodia eri tyyppeihin. Traitit ja trait-rajat varmistavat, että vaikka tyypit ovat geneerisiä, niillä on koodin tarvitsema käyttäytyminen. Opit käyttämään elinikämerkintöjä varmistaaksesi, ettei tämä joustava koodi sisällä riippuvia viittauksia. Ja kaikki tämä analyysi tapahtuu käännösaikana, mikä ei vaikuta ajonaikaiseen suorituskykyyn!

Usko tai älä, näistä luvussa käsittelemistämme aiheista on vielä paljon opittavaa: Luku 18 käsittelee trait-olioita, jotka ovat toinen tapa käyttää traitteja. On myös monimutkaisempia skenaarioita, joissa tarvitset elinikämerkintöjä vain hyvin edistyneissä tilanteissa; niitä varten sinun kannattaa lukea Rust Reference. Mutta seuraavaksi opit kirjoittamaan testejä Rustissa, jotta voit varmistaa, että koodisi toimii odotetulla tavalla.

Automaattisten testien kirjoittaminen

Edsger W. Dijkstra kirjoitti vuonna 1972 esseessään The Humble Programmer:
“Ohjelmatestaus voi olla erittäin tehokas tapa osoittaa virheiden olemassaolo, mutta se on täysin riittämätön osoittamaan niiden puuttumista.”
Tämä ei kuitenkaan tarkoita, ettemme voisi yrittää testata niin paljon kuin mahdollista!

Ohjelmamme oikeellisuus tarkoittaa sitä, kuinka hyvin koodi toteuttaa haluamamme toiminnallisuuden. Rust on suunniteltu huomioimaan ohjelmien oikeellisuus tarkasti, mutta sen varmistaminen on monimutkaista eikä helppoa todistaa. Rustin tyyppijärjestelmä kantaa suuren osan tästä vastuusta, mutta sekään ei voi estää kaikkia virheitä. Siksi Rust sisältää kattavan tuen automaattisten testien kirjoittamiseen.

Oletetaan, että kirjoitamme funktion add_two, joka lisää annetulle luvulle kaksi. Funktion allekirjoitus määrittää, että se ottaa kokonaisluvun parametrina ja palauttaa kokonaisluvun tuloksena. Kun toteutamme ja käännämme tämän funktion, Rust suorittaa tyyppitarkistuksen ja lainantarkistuksen varmistaakseen, että emme esimerkiksi yritä antaa sille String-tyyppistä arvoa tai kelpaamatonta viittausta.

Mutta Rust ei voi tarkistaa, tekeekö funktio juuri sitä, mitä tarkoitimme – eli palauttaako se parametrin plus 2 eikä esimerkiksi plus 10 tai miinus 50! Tällaisissa tilanteissa testit ovat ratkaisevia.

Voimme kirjoittaa testejä varmistaaksemme, että kun annamme funktiolle add_two arvon 3, se palauttaa arvon 5. Voimme ajaa nämä testit aina, kun teemme muutoksia koodiin, varmistaaksemme, että aiemmin toiminut käyttäytyminen ei ole muuttunut.

Testaaminen on monimutkainen taito. Emme voi kattaa yhden luvun aikana kaikkea, mitä hyvien testien kirjoittamiseen liittyy, mutta tässä luvussa käsittelemme Rustin testausjärjestelmän mekaniikkaa. Käymme läpi annotaatiot ja makrot, joita voit käyttää testien kirjoittamiseen, testien ajamisen oletuskäyttäytymisen ja asetukset, sekä testien organisoinnin yksikkötesteihin ja integraatiotesteihin.

Miten testejä kirjoitetaan

Testien kirjoittaminen

Testit ovat Rust-funktioita, jotka varmistavat, että ei-testikoodi toimii odotetulla tavalla. Testifunktioiden rungot suorittavat tyypillisesti nämä kolme toimintoa:

• Valmistele tarvittavat tiedot tai tila.
• Suorita testattava koodi.
• Varmista, että tulokset ovat odotetut.

Katsotaan Rustin tarjoamia ominaisuuksia erityisesti testien kirjoittamiseen, jotka sisältävät nämä toiminnot: test-attribuutti, muutamia makroja ja should_panic-attribuutin.

Testifunktioiden rakenne

Yksinkertaisimmillaan Rustin testi on funktio, joka on merkitty test- attribuutilla. Attribuutit ovat metatietoa Rust-koodin osista; yksi esimerkki on derive-attribuutti, jota käytimme structeissa luvussa 5. Muuttaaksesi funktion testifunktioksi, lisää #[test] riville ennen fn:ää. Kun ajat testisi cargo test -komennolla, Rust rakentaa testiajaminen binääritiedoston, joka ajaa merkityt funktiot ja raportoi, läpäiseekö kukin testifunktio vai epäonnistuuko se.

Aina kun luomme uuden kirjastoprojektin Cargolla, testimoduuli testifunktiolla luodaan automaattisesti meille. Tämä moduuli antaa mallin testien kirjoittamiseen, jotta sinun ei tarvitse etsiä tarkkaa rakennetta ja syntaksia joka kerta, kun aloitat uuden projektin. Voit lisätä niin monta lisätestifunktiota ja testimoduulia kuin haluat!

Tutkimme testien toiminnan eri puolia kokeilemalla mallitestiä ennen kuin testaamme varsinaista koodia. Sitten kirjoitamme joitakin tosielämän testejä, jotka kutsuvat kirjoittamaamme koodia ja varmistavat, että sen käyttäytyminen on oikea.

Luodaan uusi kirjastoprojekti nimeltä adder, joka laskee yhteen kaksi lukua:

$ cargo new adder --lib
     Created library `adder` project
$ cd adder

adder-kirjastosi src/lib.rs-tiedoston sisällön pitäisi näyttää listaukselta 11-1.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-01/src/lib.rs}}

Tiedosto alkaa esimerkki-add-funktiolla, jotta meillä on jotain testattavaa.

Toistaiseksi keskitytään pelkästään it_works-funktioon. Huomaa #[test]- merkintä: Tämä attribuutti ilmaisee, että tämä on testifunktio, joten testiajaminen tietää käsitellä tätä funktiota testinä. Meillä voi myös olla ei-testifunktioita tests-moduulissa yhteisten skenaarioiden valmisteluun tai yleisten operaatioiden suorittamiseen, joten meidän täytyy aina ilmaista, mitkä funktiot ovat testejä.

Esimerkkifunktion runko käyttää assert_eq!-makroa varmistaakseen, että result, joka sisältää add-funktion kutsun tuloksen arvoilla 2 ja 2, on yhtä suuri kuin 4. Tämä varmistus toimii esimerkkinä tyypillisestä testin muodosta. Ajetaan se nähdäksemme, että testi läpäisee.

cargo test -komento ajaa kaikki projektimme testit, kuten listauksessa 11-2.

{{#include ../listings/ch11-writing-automated-tests/listing-11-01/output.txt}}

Cargo käänsi ja ajoi testin. Näemme rivin running 1 test. Seuraava rivi näyttää luodun testifunktion nimen, nimeltä tests::it_works, ja että testin ajamisen tulos on ok. Yhteenveto test result: ok. tarkoittaa, että kaikki testit läpäisivät, ja osa 1 passed; 0 failed laskee läpäisseiden tai epäonnistuneiden testien määrän.

Testin voi merkitä ohitetuksi, jotta se ei aja tietyssä tilanteessa; käsittelemme tämän luvun myöhemmässä osiossa ”Testien ohittaminen, ellei niitä erikseen pyydetä”. Koska emme ole tehneet sitä tässä, yhteenveto näyttää 0 ignored. Voimme myös antaa cargo test -komennolle argumentin ajaa vain testit, joiden nimi vastaa merkkijonoa; tätä kutsutaan suodatukseksi (filtering), ja käsittelemme sen osiossa ”Testien osajoukon ajaminen nimen perusteella”. Tässä emme ole suodattaneet ajettavia testejä, joten yhteenvedon loppu näyttää 0 filtered out.

0 measured -tilasto koskee suorituskykytestejä (benchmark tests). Tällä hetkellä suorituskykytestit ovat saatavilla vain yönightly-Rustissa. Katso dokumentaatio suorituskykytesteistä saadaksesi lisätietoja.

Testitulosteen seuraava osa alkaen Doc-tests adder koskee dokumentaatiotestien tuloksia. Meillä ei ole vielä dokumentaatiotestejä, mutta Rust voi kääntää API-dokumentaatiossamme esiintyvät koodiesimerkit. Tämä ominaisuus auttaa pitämään dokumentaation ja koodin synkassa! Käsittelemme dokumentaatiotestien kirjoittamista luvun 14 osiossa ”Dokumentaatiokommentit testeinä”. Toistaiseksi ohitamme Doc-tests- tulosteen.

Aloitetaan testin mukauttaminen omiin tarpeisiimme. Ensin vaihdetaan it_works- funktion nimi eri nimeksi, kuten exploration, näin:

Filename: src/lib.rs

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-01-changing-test-name/src/lib.rs}}

Sitten ajetaan cargo test uudelleen. Tuloste näyttää nyt exploration it_works- kohdan sijaan:

{{#include ../listings/ch11-writing-automated-tests/no-listing-01-changing-test-name/output.txt}}

Nyt lisätään toinen testi, mutta tällä kertaa tehdään testi, joka epäonnistuu! Testit epäonnistuvat, kun jokin testifunktiossa paniikkiutuu. Jokainen testi ajetaan uudessa säikeessä, ja kun pääsäie näkee testisäikeen kuolleen, testi merkitään epäonnistuneeksi. Luvussa 9 puhuimme, että yksinkertaisin tapa paniikkiutua on kutsua panic!-makroa. Syötä uusi testi funktiona nimeltä another, jolloin src/lib.rs-tiedostosi näyttää listaukselta 11-3.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-03/src/lib.rs}}

Aja testit uudelleen cargo test -komennolla. Tulosteen pitäisi näyttää listaukselta 11-4, joka näyttää, että exploration-testimme läpäisi ja another epäonnistui.

{{#include ../listings/ch11-writing-automated-tests/listing-11-03/output.txt}}

ok-kohdan sijaan rivi test tests::another näyttää FAILED. Kaksi uutta osiota ilmestyy yksittäisten tulosten ja yhteenvedon väliin: Ensimmäinen näyttää yksityiskohtaisen syyn kunkin testin epäonnistumiselle. Tässä tapauksessa saamme tiedot, että tests::another epäonnistui, koska se paniikkiutui viestillä Make this test fail rivillä 17 src/lib.rs-tiedostossa. Seuraava osio listaa vain kaikkien epäonnistuneiden testien nimet, mikä on hyödyllistä, kun testejä ja paljon yksityiskohtaista epäonnistuneen testin tulostetta on paljon. Voimme käyttää epäonnistuneen testin nimeä ajamaan vain kyseisen testin debugataksemme sitä helpommin; puhumme lisää testien ajamisen tavoista osiossa ”Testien ajamisen hallinta”.

Yhteenvetorivi näkyy lopussa: Kaiken kaikkiaan testituloksemme on FAILED. Yksi testi läpäisi ja yksi epäonnistui.

Nyt kun olet nähnyt, miltä testitulokset näyttävät eri skenaarioissa, katsotaan joitakin muita makroja kuin panic!, jotka ovat hyödyllisiä testeissä.

Tulosten tarkistaminen assert!-makrolla

assert!-makro, jonka standardikirjasto tarjoaa, on hyödyllinen, kun haluat varmistaa, että jokin ehto testissä evaluoituu arvoksi true. Annetaan assert!-makrolle argumentti, joka evaluoituu totuusarvoksi. Jos arvo on true, mitään ei tapahdu ja testi läpäisee. Jos arvo on false, assert!- makro kutsuu panic!:a saadakseen testin epäonnistumaan. assert!-makron käyttö auttaa meitä tarkistamaan, että koodimme toimii tarkoittamallamme tavalla.

Luvussa 5, listauksessa 5-15, käytimme Rectangle-structia ja can_hold- metodia, jotka toistetaan tässä listauksessa 11-5. Laitetaan tämä koodi src/lib.rs-tiedostoon ja kirjoitetaan sille testejä assert!-makron avulla.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-05/src/lib.rs}}

can_hold-metodi palauttaa totuusarvon, mikä tekee siitä täydellisen käyttötapauksen assert!-makrolle. Listauksessa 11-6 kirjoitamme testin, joka testaa can_hold-metodia luomalla Rectangle-instanssin, jonka leveys on 8 ja korkeus 7, ja varmistamalla, että se voi sisältää toisen Rectangle-instanssin, jonka leveys on 5 ja korkeus 1.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-06/src/lib.rs:here}}

Huomaa use super::*; -rivi tests-moduulin sisällä. tests-moduuli on tavallinen moduuli, joka noudattaa tavallisia näkyvyyssääntöjä, joita käsittelimme luvussa 7 osiossa ”Polut moduulipuun kohteeseen viittaamiseen”. Koska tests-moduuli on sisämoduuli, meidän täytyy tuoda testattava koodi ulommassa moduulissa sisämoduulin näkyvyysalueelle. Käytämme tässä globia, joten kaikki ulommassa moduulissa määrittelemämme on käytettävissä tässä tests-moduulissa.

Olemme nimenneet testimme larger_can_hold_smaller, ja olemme luoneet kaksi tarvitsemaamme Rectangle-instanssia. Sitten kutsuimme assert!-makroa ja annoimme sille lausekkeen larger.can_hold(&smaller). Tämän lausekkeen pitäisi palauttaa true, joten testimme pitäisi läpäistä. Katsotaan!

{{#include ../listings/ch11-writing-automated-tests/listing-11-06/output.txt}}

Se läpäisee! Lisätään toinen testi, joka tällä kertaa varmistaa, ettei pienempi suorakulmio voi sisältää suurempaa suorakulmiota:

Filename: src/lib.rs

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-02-adding-another-rectangle-test/src/lib.rs:here}}

Koska can_hold-funktion oikea tulos tässä tapauksessa on false, meidän täytyy kääntää tämä tulos ennen kuin annamme sen assert!-makrolle. Näin testimme läpäisee, jos can_hold palauttaa false:

{{#include ../listings/ch11-writing-automated-tests/no-listing-02-adding-another-rectangle-test/output.txt}}

Kaksi testiä läpäisee! Katsotaan nyt, mitä testituloksille tapahtuu, kun tuomme virheen koodiimme. Muutamme can_hold-metodin toteutusta korvaamalla suurempi-kuin-merkin (>) pienempi-kuin-merkillä (<) leveyksiä vertailtaessa:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/src/lib.rs:here}}

Testien ajaminen nyt tuottaa seuraavan:

{{#include ../listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/output.txt}}

Testimme löysivät virheen! Koska larger.width on 8 ja smaller.width on 5, leveyksien vertailu can_hold-metodissa palauttaa nyt false: 8 ei ole pienempi kuin 5.

Yhtäsuuruuden testaaminen assert_eq!- ja assert_ne!-makroilla

Yleinen tapa varmistaa toiminnallisuus on testata yhtäsuuruutta testattavan koodin tuloksen ja odottamasi arvon välillä. Voit tehdä tämän assert!-makrolla ja antamalla sille lausekkeen, joka käyttää ==-operaattoria. Tämä on kuitenkin niin yleinen testi, että standardikirjasto tarjoaa makroparin — assert_eq! ja assert_ne! — suorittaakseen tämän testin kätevämmin. Nämä makrot vertaavat kahta argumenttia yhtäsuuruuden tai erisuuruuden osalta. Ne myös tulostavat kaksi arvoa, jos varmistus epäonnistuu, mikä helpottaa miksi testi epäonnistui; päinvastoin assert!-makro ilmaisee vain, että se sai false-arvon ==- lausekkeelle tulostamatta arvoja, jotka johtivat false-arvoon.

Listauksessa 11-7 kirjoitamme funktion nimeltä add_two, joka lisää 2 parametriinsa, ja testaamme sitten tämän funktion assert_eq!-makrolla.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-07/src/lib.rs}}

Tarkistetaan, että se läpäisee!

{{#include ../listings/ch11-writing-automated-tests/listing-11-07/output.txt}}

Luomme muuttujan nimeltä result, joka sisältää add_two(2)-kutsun tuloksen. Sitten annamme result- ja 4-arvot assert_eq!-makrolle. Tulostusrivi tälle testille on test tests::it_adds_two ... ok, ja ok-teksti ilmaisee, että testimme läpäisi!

Tuodaan virhe koodiimme nähdäksemme, miltä assert_eq! näyttää epäonnistuessaan. Muutetaan add_two-funktion toteutus lisäämään 3 2:n sijaan:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/src/lib.rs:here}}

Aja testit uudelleen:

{{#include ../listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/output.txt}}

Testimme löysi virheen! tests::it_adds_two -testi epäonnistui, ja viesti kertoo, että epäonnistunut varmistus oli left == right ja mitkä left- ja right-arvot ovat. Tämä viesti auttaa aloittamaan debuggauksen: left- argumentti, jossa meillä oli add_two(2)-kutsun tulos, oli 5, mutta right- argumentti oli 4. Voit kuvitella, että tästä olisi erityisen hyötyä, kun testejä on paljon.

Huomaa, että joissakin kielissä ja testikehyksissä yhtäsuuruusvarmistusten funktioiden parametreja kutsutaan expected- ja actual-arvoiksi, ja argumenttien järjestys on merkityksellinen. Rustissa niitä kutsutaan kuitenkin left- ja right-arvoiksi, eikä sillä ole väliä, missä järjestyksessä määrittelemme odottamamme arvon ja koodin tuottaman arvon. Voisimme kirjoittaa testin varmistuksen muodossa assert_eq!(4, result), mikä johtaisi samaan epäonnistumisviestiin, joka näyttää assertion `left == right` failed.

assert_ne!-makro läpäisee, jos kaksi antamaamme arvoa eivät ole yhtä suuret, ja epäonnistuu, jos ne ovat. Tämä makro on hyödyllisin tapauksissa, joissa emme ole varmoja, mikä arvo tulee olemaan, mutta tiedämme, mikä arvo ei todellakaan saa olla. Esimerkiksi jos testaamme funktiota, joka muuttaa syötteensä jollakin tavalla, mutta tapa, jolla syöte muuttuu, riippuu viikonpäivästä, jolloin ajamme testejämme, paras asia varmistaa saattaa olla, ettei funktion tuloste ole yhtä suuri kuin syöte.

Pinnan alla assert_eq!- ja assert_ne!-makrot käyttävät operaattoreita == ja !=. Kun varmistukset epäonnistuvat, nämä makrot tulostavat argumenttinsa debug-muotoilulla, mikä tarkoittaa, että verrattavien arvojen täytyy toteuttaa PartialEq- ja Debug-traitit. Kaikki primitiivityypit ja useimmat standardikirjaston tyypit toteuttavat nämä traitit. Itse määrittelemillesi structeille ja enum-arvoille sinun täytyy toteuttaa PartialEq varmistaaksesi näiden tyyppien yhtäsuuruuden. Sinun täytyy myös toteuttaa Debug tulostaaksesi arvot, kun varmistus epäonnistuu. Koska molemmat traitit ovat johdettavia traitteja, kuten mainittiin listauksessa 5-12 luvussa 5, tämä on yleensä yhtä suoraviivaista kuin #[derive(PartialEq, Debug)]-merkinnän lisääminen struct- tai enum-määrittelyysi. Katso liite C, ”Johdettavat traitit” näistä ja muista johdettavista traiteista.

Mukautettujen virheviestien lisääminen

Voit myös lisätä mukautetun viestin, joka tulostetaan epäonnistumisviestin kanssa, valinnaisina argumentteina assert!-, assert_eq!- ja assert_ne!- makroille. Pakollisten argumenttien jälkeen määritellyt argumentit välitetään format!-makrolle (käsiteltiin luvussa 8 osiossa ”Yhdistäminen +- tai format!-operaattorilla”), joten voit antaa muotoilumerkkijonon, joka sisältää {}-paikkamerkit ja arvot näihin paikkamerkkeihin. Mukautetut viestit ovat hyödyllisiä dokumentoimaan, mitä varmistus tarkoittaa; kun testi epäonnistuu, sinulla on parempi käsitys siitä, mikä koodissa on vikana verrattuna siihen, mitä odotimme tapahtuvan.

Esimerkiksi sanotaan, että meillä on funktio, joka tervehtii ihmisiä nimellä, ja haluamme testata, että funktiolle antamamme nimi näkyy tulosteessa:

Filename: src/lib.rs

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-05-greeter/src/lib.rs}}

Tämän ohjelman vaatimuksista ei ole vielä sovittu, ja olemme melko varmoja, että tervehdyksen alussa oleva Hello-teksti muuttuu. Päätimme, ettei meidän haluta päivittää testiä, kun vaatimukset muuttuvat, joten tarkistamme tarkan yhtäsuuruuden greeting-funktion palauttamaan arvoon sen sijaan, että varmistaisimme vain, että tuloste sisältää syöteparametrin tekstin.

Tuodaan nyt virhe tähän koodiin muuttamalla greeting jättämään name pois nähdäksemme, miltä oletusarvoinen testin epäonnistuminen näyttää:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/src/lib.rs:here}}

Tämän testin ajaminen tuottaa seuraavan:

{{#include ../listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/output.txt}}

Tämä tulos ilmaisee vain, että varmistus epäonnistui ja millä rivillä varmistus on. Hyödyllisempi epäonnistumisviesti tulostaisi greeting-funktion arvon. Lisätään mukautettu epäonnistumisviesti, joka koostuu muotoilumerkkijonosta paikkamerkillä, joka täytetään todellisella arvolla, jonka saimme greeting- funktiosta:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/src/lib.rs:here}}

Nyt kun ajamme testin, saamme informatiivisemman virheviestin:

{{#include ../listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/output.txt}}

Näemme testitulosteessa todellisen arvon, jonka saimme, mikä auttaisi debuggaamaan, mitä tapahtui sen sijaan, mitä odotimme tapahtuvan.

Paniikin tarkistaminen should_panic-attribuutilla

Palautusarvojen tarkistamisen lisäksi on tärkeää tarkistaa, että koodimme käsittelee virhetilanteet odottamallamme tavalla. Esimerkiksi harkitse Guess-tyyppiä, jonka loimme luvussa 9, listauksessa 9-13. Muu koodi, joka käyttää Guess-tyyppiä, luottaa takuuseen, että Guess-instanssit sisältävät vain arvoja välillä 1–100. Voimme kirjoittaa testin, joka varmistaa, että Guess-instanssin luominen arvolla tämän alueen ulkopuolelta paniikkiutuu.

Teemme tämän lisäämällä should_panic-attribuutin testifunktiollemme. Testi läpäisee, jos funktion sisällä oleva koodi paniikkiutuu; testi epäonnistuu, jos funktion sisällä oleva koodi ei paniikkiudu.

Listaus 11-8 näyttää testin, joka tarkistaa, että Guess::new-funktion virhetilanteet tapahtuvat, kun odotamme niitä.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-08/src/lib.rs}}

Sijoitamme #[should_panic]-attribuutin #[test]-attribuutin jälkeen ja ennen testifunktiota, johon se kohdistuu. Katsotaan tulos, kun tämä testi läpäisee:

{{#include ../listings/ch11-writing-automated-tests/listing-11-08/output.txt}}

Näyttää hyvältä! Tuodaan nyt virhe koodiimme poistamalla ehto, jonka perusteella new-funktio paniikkiutuu, jos arvo on suurempi kuin 100:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-08-guess-with-bug/src/lib.rs:here}}

Kun ajamme listauksen 11-8 testin, se epäonnistuu:

{{#include ../listings/ch11-writing-automated-tests/no-listing-08-guess-with-bug/output.txt}}

Emme saa tässä tapauksessa kovin hyödyllistä viestiä, mutta kun katsomme testifunktiota, näemme, että se on merkitty #[should_panic]-attribuutilla. Saamamme epäonnistuminen tarkoittaa, että testifunktion koodi ei aiheuttanut paniikkia.

should_panic-attribuuttia käyttävät testit voivat olla epätarkkoja. should_panic-testi läpäisisi, vaikka testi paniikkiutuisi eri syystä kuin odotimme. Tehdäksemme should_panic-testeistä tarkempia voimme lisätä valinnaisen expected-parametrin should_panic-attribuuttiin. Testiajaminen varmistaa, että epäonnistumisviesti sisältää annetun tekstin. Esimerkiksi harkitse muokattua Guess-koodia listauksessa 11-9, jossa new-funktio paniikkiutuu eri viesteillä riippuen siitä, onko arvo liian pieni vai liian suuri.

{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-09/src/lib.rs:here}}

Tämä testi läpäisee, koska arvo, jonka laitamme should_panic-attribuutin expected-parametriin, on osamerkkijono viestistä, jolla Guess::new-funktio paniikkiutuu. Olisimme voineet määrittää koko odottamamme paniikkiviestin, joka tässä tapauksessa olisi Guess value must be less than or equal to 100, got 200. Mitä määrität riippuu siitä, kuinka uniikki tai dynaaminen paniikkiviesti on ja kuinka tarkka haluat testisi olevan. Tässä tapauksessa paniikkiviestin osamerkkijono riittää varmistamaan, että testifunktion koodi suorittaa else if value > 100 -tapauksen.

Nähdäksemme, mitä tapahtuu, kun should_panic-testi expected-viestillä epäonnistuu, tuodaan taas virhe koodiimme vaihtamalla if value < 1- ja else if value > 100 -lohkojen rungot:

{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-09-guess-with-panic-msg-bug/src/lib.rs:here}}

Tällä kertaa kun ajamme should_panic-testin, se epäonnistuu: