Ръждьо в примери

Ръждьо1 е модерен системен език за програмиране, целящ безопасност, скорост и едновременност2. Той постига тези цели чрез безопасен достъп до паметта и без да използва събирач на отпадъците3.

Ръждьо в примери (РП) е набор от изпълними примери, които представят различни понятия в Ръждьо и стандартните му библиотеки. За да ги разберете напълно, трябва да инсталирате Ръждьо на вашето сметало и да преглеждате своевремменно представителната документация. По-любопитните могат да прегледат и изходния код на този сайт.

Сега да започваме!

Б. пр.

1

Ръждьо – Rust. Обикновено имена не се превеждат, но според преводача, това име трябва да се преведе, за да се внуши усещането, че това е просто едно послушно куче, което ще прави каквото му се каже. Освен това звучи по-нашенски.

2

едновременност – concurency. Едновременност на изпълнението на задачи в една програма. Ръждьо постига едновременност на изпълнението чрез нишки. Те са обяснени в Разни в std/Нишки.

3

събирач на отпадъците – garbage collector. Обособена част от езиците за програмиране, грижеща се за освобождаване на паметта от неизползваните вече данни.

Здравей, Свят

Ето изходния код на обичайната програма „Здравей, Свят“.

// Това е коментар. Компилаторът го подминава.
// Можете да пробвате кода, като натиснете бутона "Run" ей тук ->
// или, ако предпочитате да ползвате клавиатура, като използвате клавишното
// съчетание "Ctrl + Enter"

// Кодът може да бъде променян. Променете го.
// Винаги можете да го върнете в началния му вид, като натиснете бутона "Reset" ->

// Това е главната функция.
fn main() {
    // Изявленията тук се изпълняват,
    // когато се пусне компилираният двоичен файл.

    // Извежда текст в конзолата (терминала).
    println!("Здравей, Свят!");
}

println! е макрос, който отпечатва (print!) текст в конзолата.

От изходния код може да бъде създаден изпълним файл чрез компилатора на Ръждьо: rustc.

$ rustc hello.rs

rustc ще произведе двоичен изпълним файл hello, който може да бъде пуснат.

$ ./hello
Здравей, Свят!

Упражнение

Натиснете по-горе, за да видите очаквания изход. След това добавете нов ред с макроса println!, така че изходът да бъде:

Здравей, Свят!
Аз съм Ръждар!

Коментари

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

  • Обикновени коментари – компилаторът ги пренебрегва:
    • // Едноредови коментари – продължават до края на реда.
    • /* Блокови коментари – продължават до затварящия ограничител. */
  • Документни коментари – биват превърнати в HTML документация на библиотеки:
    • /// Създава библиотечна документация за единицата, следваща коментара.
    • //! Създава библиотечна документация за единицата, съдържаща коментара.
fn main() {
    // Това е пример за едноредов коментар.
    // В началото на реда има две наклонени черти.
    // Всичко след тях до края на реда няма да се прочете от компилатора.

    // println!("Здравей, свят!");

    // Изпълнете примера. Виждате ли горното изявление? Сега изтрийте
    // наклонените черти и изпълнете примера отново.

    /*
     * Това е друг вид коментар – блоков коментар. Като цяло едноредовите
     * коментари се препоръчват повече. Но блоковите коментари са 
     * изключително полезни за временно „изключване“ на части от
     * програмния код.
     * /* Блоковите коментари могат да /* се вгнездяват */ */ един в друг.
     * Така лесно можете да коментирате всичко в main().
     * /*/*/* Проверете сами! */*/*/
     */

    /*
    Забележете: Колонката със звездички `*` по-горе е само за прегледност.
    Не е задължителна.
    */

    // По-лесно е да променяте изразите чрез блокови коментари. 
    // Махнете коментара на следващия ред, за да промените резултата.
    let x = 5 + /* 90 + */ 5;
    println!("Is `x` 10 or 100? x = {}", x);
}

Вижте също:

документация на библиотеки

Форматиран изход

Отпечатването на текст в конзолата се управлява от набор макроси1, описани в пакета std::fmt. Някои от тях са:

  • format!: пише форматиран текст в String
  • print!: също като format!, но текстът бива изведен на конзолата (io::stdout).
  • println!: като print!, но накрая се добавя и нов ред.
  • eprint!: също като print!, но текстът се отпечатва в стандартния поток за грешки (io::stderr).
  • eprintln!: също като eprint!, но накрая се добавя и нов ред.

Всички макроси обработват текста по един и същи начин. Освен това Ръждьо проверява правилността на форматирането по време на компилиране.

fn main() {
    // Означенията `{}` ще бъдат автоматично заменени с каквито и да са подадени
    // аргументи. А самите аргументи ще бъдат превърнати в низове.
    println!("{} days", 31);

    // Може да се използват местата на аргументите. Указвайки число между
    // `{}`, определяте кой по ред аргумент да бъде сложен там
    // Броенето на аргументите започва от 0 непосредствено след 
    // форматирания низ.
    println!("{0}, това е {1}. {1}, това е {0}", "Alice", "Bob");

    // Както и именувани аргументи.
    println!("{subject} {verb} {object}",
             object="мързеливото куче",
             subject="бързата кафява котка",
             verb="скача върху");

    // Може да се приложи различно форматиране чрез знак за формат
    // след двуеточие `:`.
    println!("Основа 10:                   {}",   69420); // 69420
    println!("Основа  2 (двоично):         {:b}", 69420); // 10000111100101100
    println!("Основа  8 (осмично):         {:o}", 69420); // 207454
    println!("Основа 16 (шестнадесетично): {:x}", 69420); // 10f2c
    println!("Основа 16 (шестнадесетично): {:X}", 69420); // 10F2C

    // Можете да равнявате текст надясно, като укажете ширината. Следното ще
    // изведе "    1". (Четири празноти и "1" с обща ширина 5.)
    println!("{число:>5}", число=1);

    // Можете да указвате отстъпи с нули
    println!("{number:0>5}", number=1); // 00001
    // и да подравнявате вляво, като обърнете знака. Следното ще изведе "10000".
    println!("{number:0<5}", number=1); // 10000

    // Можете да използвате именувани аргументи за формат,
    // като долепите знака $ отзад.
    println!("{number:0>width$}", number=1, width=5);   

    // Ръждьо дори проверява дали са подадени нужният брой аргументи.
    println!("Казвам се {0}, {1} {0}", "Бонд");
    // ПОПРАВИ ^ Добавете липсващия аргумент: "Джеймс"

    // Само типове, осъществяващи fmt::Display, могат да бъдат форматирани с `{}`.
    // Потребителските типове не осъществятват fmt::Display по подразбиране.

    #[allow(dead_code)] // Изключва предупрежденията за `dead_code` (мъртъв код).
    // Обявена, но неизползвана по-късно единица.
    struct Structure(i32);

    // Следното няма да се компилира, защото `Structure` не осъществява
    // fmt::Display.
    // println!("Тази структура `{}` няма да се отпечати…", Structure(3));
    // ЗАДАЧА ^ Разкоментирайте горния ред.

    // От Ръждьо 1.58 нагоре можете да ползвате вече обявена променлива.
    // Както и по-горе, следното ще изведе
    // "    1", 4 празноти и "1",
    let число: f64 = 1.0; // и името на променливата може да е с български букви!
    let width: usize = 5;
    println!("{число:>width$}");
}

Пакетът std::fmt съдържа много отличители (ключова дума trait)2, управляващи показването на текст. Ето два от важните.

  • fmt::Debug: Използва обозначението3 {:?}. Форматира текст с цел разбор на грешки.
  • fmt::Display: Използва обозначението {}. Форматира текст по-разбираемо и удобно за потребителя.

Тук използвахме fmt::Display, понеже стандартната библиотека (std) осъществява4 тези типове. За да представите като текст потребителски типове, са нужни повече стъпки.

Като осъществите отличителя fmt::Display, автоматично осъществявате отличителя ToString, който ни позволява да превърнем типа в низ (String).

#[allow(dead_code)] на ред 47 е атрибут, който важи само за модула след него.

Упражнения

  • Поправете кода по-горе (вижте ПОПРАВИ), така че да работи без грешка.
  • Разкоментирайте реда, където се опитваме да форматираме структурата Structure (вижте ЗАДАЧА).
  • Добавете извикване на макроса println!, който да изпечатва: Числото Пи е 3.142, като определите видимия брой знаци след десетичната запетая. За целта на това упражнение използвайте let pi = 3.141592 като приближение за Пи. (Съвет: Потърсете в документацията на std::fmt как се настройва показваният брой цифри след десетичната запетая).

Б. пр.

1

макрос – macro. Дума, навлязла в компютърните науки през 1959 г. Съkращение от macroinstructions. Представлява указания, които се изпълняват по време на компилация. Макросите се използват за автоматично създаване на поредица от изявления и изрази, които изпълняват определено действие.

2

отличител – trait. Отличителят (буквално отличителна черта) (trait) е набор от методи, описани за непознат тип Self, където Self е прякор за типа на извикващия обект. Методите могат да достъпват други методи, обявени в същия отличител. В Ръждьо отличителят описва поведение чрез методи. Всеки тип може да бъде производен на няколко отличителя и същевременно да осъществява други отличители. Отличителите могат да бъдат осъществявани за всеки тип данни.

3

обозначение, означение – marker

4

осъществявам, въплъщавам – implement. Осъществяване, осъществление, въплъщение – implementation

Вижте също:

std::fmt, macro_rules!, Структури, Отличители и dead_code

Debug

Всички типове, които искат да ползват отличители за форматиране от std::fmt, трябва да осъществят съответния отличител, за да бъдат печатаеми. Само типовете от стандартната библиотека std осъществяват тези отличители. Всички останали типове трябва някак да ги осъществят.

С помощта на отличителя fmt::Debug лесно се създават негови производни (derive). Всички типове могат да осъществят автоматично fmt::Debug (да станат призводни на fmt::Debug – бел. прев.). За разлика от него, fmt::Display трябва да бъде осъществен на ръка.

#![allow(unused)]
fn main() {
// Тази структура не може да бъде отпечатана нито с `fmt::Display`
// нито с `fmt::Debug`.
struct UnPrintable(i32);

// Атрибутът `derive` автоматично създава необходимото осъществяване
// (необходимия изписан код), за да направи тази структура (`struct`) печатаема с
// `fmt::Debug`.
#[derive(Debug)]
struct DebugPrintable(i32);
}

Всички типове от библиотеката std са печатаеми чрез означението {:?}:

// `Structure` става производна  на `fmt::Debug`. `Structure` е структура,
// която съдържа единица данни от типа `i32`.
#[derive(Debug)]
struct Structure(i32);

// Поставяме `Structure` в структурата `Deep`, която също правим печатаема.
#[derive(Debug)]
struct Deep(Structure);

fn main() {
    // Печатането чрез `{:?}` е подобно на печатането чрез `{}`.
    println!("В една година има {:?} месеца.", 12);
    println!("{1:?} {0:?} is the {actor:?} name.",
             "Slater",
             "Christian",
             actor="actor's");

    // `Structure` е печатаема!
    println!("Сега {:?} ще се отпечати!", Structure(3));

    // Проблемът с `derive` е, че не можем да да управляваме външния вид
    // на отпечатаното. Ами ако искаме да покажем просто `7`?
    println!("Now {:?} will print!", Deep(Structure(7)));
}

fmt::Debug определено прави типовете печатаеми, но грубо. Ръждьо предоставя и „красиво отпечатване” с помощта на {:#?}.

#[derive(Debug)]
struct Person<'a> {
    name: &'a str,
    age: u8
}

fn main() {
    let name = "Peter";
    let age = 27;
    let peter = Person { name, age };

    // Красиво отпечатване
    println!("{:#?}", peter);
}

Можем ръчно да осъществим fmt::Display, ако искаме да управляваме показването.

Вижте също:

Атрибути, Производни, std::fmt, Структури и Отличители

Display

Изходът от fmt::Debug рядко изглежда сбит и чист. Често е по-добре сами да нагодим начина на показване. Това се постига като сами осъществим отличителя fmt::Display. Той използва означението {} при извеждане на низ на екрана. Осъществяването изглежда така:

#![allow(unused)]
fn main() {
// Внасяме модула `fmt`, за да можем да го ползваме (`use`).
use std::fmt;

// Описваме структура, за която ще осъществим `fmt::Display`
// Това е разнородна поредица, именувана `Structure`,
// която съдържа един член от тип `i32`.
struct Structure(i32);

// За да използваме означението `{}`, трябва ръчно да осъществим `impl fmt::Display`
// за типa `for Structure`.
impl fmt::Display for Structure {
    // Този отличител изисква да се осъществи метода `fmt` с точно това описание⁴.
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // Пишем първия член в подадения изходен поток `f`.
        // write! връща данни от тип `fmt::Result`,
        // който показва дали действието (писане) е успяло или не.
        // Обърнете внимание, че правописът⁵  на `write!`
        // е много подобен на `println!`.
        write!(f, "{}", self.0)
    }
}
}

fmt::Display може да е по-изчистен от fmt::Debug, но се появяват някои затруднения за библиотеката std. Как би трябвало да се показват неопределени типове? Например ако std осъществеше един единствен начин за показване за всички Vec<T>, какъв щеше да е той? Би ли бил някой от тези двата?

  • Vec<path>: /:/etc:/home/username:/bin (разделяме с :)
  • Vec<number>: 1,2,3 (разделяме със ,)

Не, защото няма съвършен начин за показване на всички типове и библиотеката std не налага никакъв. fmt::Display не е осъществен за Vec<T> и за никакви обобщени съдържащи типове1. В тези случаи (показване на обобщени съдържащи типове) се налага да ползваме fmt::Debug.

Това не е пречка все пак, защото за всеки съдържащ тип, който не е обобщен, можем да осъществим fmt::Display.

use std::fmt; // Внасяме `fmt`.

// Структура, съдържаща две числа. Ще я направим производна на `Debug`,
// за да сравним изгледа с осъществения от нас `Display`.
#[derive(Debug)]
struct MinMax(i64, i64);

// Осъществяваме `Display` за `MinMax`.
impl fmt::Display for MinMax {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // Използваме `self.пореден_номер`, за да достъпим всяко парче данни.
        write!(f, "({}, {})", self.0, self.1)
    }
}

// Описваме структура с именувани полета, за да я сравним.
#[derive(Debug)]
struct Point2D {
    x: f64,
    y: f64,
}

// По подобен начин осъществяваме `Display` за `Point2D`.
impl fmt::Display for Point2D {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // Показваме само `x` и `y`.
        write!(f, "x: {}, y: {}", self.x, self.y)
    }
}

fn main() {
    let minmax = MinMax(0, 14);

    println!("Сравняваме показването на структури:");
    println!("Display: {}", minmax);
    println!("Debug: {:?}", minmax);

    let big_range =   MinMax(-300, 300);
    let small_range = MinMax(-3, 3);

    println!("Големият порядък е {big}, а малкият е {small}",
             small = small_range,
             big = big_range);

    let point = Point2D { x: 3.3, y: 7.2 };

    println!("Сравняваме показването на точки:");
    println!("Display: {}", point);
    println!("Debug: {:?}", point);

    // Грешка. `Debug` и `Display` са осъществени, но `{:b}`
    // изисква осъществяване на `fmt::Binary`. Следното няма да работи.
    // println!("Как изглежда Point2D, представен двоично: {:b}?", point);
}

Осъществихме fmt::Display, но не и fmt::Binary, и затова не можем да го ползваме. std::fmtпредоставя много такива отличители и всеки трябва да бъде осъществен поотделно. Това е описано подробно в std::fmt.

Упражнение

След като проверите изхода от горния пример, използвайте структурата Point2D като ръководство, за да добавите нова структура – Complex към примера. При отпечатване изходът трябва да изглежда така:

Display: 3.3 + 7.2i
Debug: Complex { real: 3.3, imag: 7.2 }

Б. пр.

1

обобщени съдържащи типове – generic containers

2

разнородна поредица – tuple, вижте разнородни поредици

3

член – element

4

описание (на функция/метод) – signature

5

правопис – syntax

Вижте също:

Производни, std::fmt, macro_rules!, Структури, Отличители и Обявлението use

Проверка: List

Осъществяването на fmt::Display за структура, на която трябва да обработим всички членове, е по-сложно. Проблемът е, че всеки write! връща fmt::Result. Правилната обработка изисква да се погрижим за всички връщани стойности. Ръждьо ни предоставя оператора ? точно с тази цел.

Използването на ? за write! изглежда така:

// Пробваме дали `write!` връща грешка. Ако да, връщаме грешката,
// иначе продължаваме.
write!(f, "{}", value)?;

Като имаме ?, осъществяването на fmt::Display за данни от тип Vec е ясно:

use std::fmt; // Import the `fmt` module.

// Описваме структура с име `List`, която съдържа `Vec`.
struct List(Vec<i32>);

impl fmt::Display for List {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // Извличаме стойността, като я достъпваме по индекс,
        // и създаваме препратка¹ към `vec`.
        let vec = &self.0;

        write!(f, "[")?;

        // Обхождаме `vec`, като присвояваме текущата стойност на `v`,
        // и записваме поредния номер в `count`.
        for (count, v) in vec.iter().enumerate() {
            // Пред всеки член, освен първия, добавяме запетая.
            // Използваме ?, за да върнем грешка, ако има.
            if count != 0 { write!(f, ", ")?; }
            write!(f, "{}", v)?;
        }

        // Затваряме отворената скоба и връщаме стойност от тип fmt::Result.
        write!(f, "]")
    }
}

fn main() {
    let v = List(vec![1, 2, 3]);
    println!("{}", v);
}

Упражнение

Променете програмата така, че да се отпечатва и поредният номер на всеки член в поредицата (вектора). Новият изход трябва да изглежда така:

[0: 1, 1: 2, 2: 3]

Вижте също:

for, ref, Result, struct, ? и vec!

1

препратка – reference

Форматиране

Видяхме, че форматирането се указва чрез низ за формат:

  • format!("{}", foo) -> "3735928559"
  • format!("0x{:X}", foo) -> "0xDEADBEEF"
  • format!("0o{:o}", foo) -> "0o33653337357"

Една и съща променлива (foo) може да бъде форматирана по различен начин в зависимост от това, какъв тип аргумент се използва: X, o или неустановен.

Тази функционалност за форматиране се осъществява чрез отличители и за всеки тип аргумент се осъществява различен отличител. Най-често използваният отличител за форматиране е Display. Display обработва случаите, когато типът на аргумента не е указан, например {}.

use std::fmt::{self, Formatter, Display};

struct City {
    name: &'static str,
    // Географска ширина
    lat: f32,
    // Географска дължина
    lon: f32,
}

impl Display for City {
    // `f` е склад¹ и този метод трябва да пише форматирания низ в него.
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        let lat_c = if self.lat >= 0.0 { 'N' } else { 'S' };
        let lon_c = if self.lon >= 0.0 { 'E' } else { 'W' };

        // макросът `write!` е като `format!`, но той пише форматирания низ
        // в склад (първия аргумент – `f`).
        write!(f, "{}: {:.3}°{} {:.3}°{}",
               self.name, self.lat.abs(), lat_c, self.lon.abs(), lon_c)
    }
}

#[derive(Debug)]
struct Color {
    red: u8,
    green: u8,
    blue: u8,
}

fn main() {
    for city in [
        City { name: "Dublin", lat: 53.347778, lon: -6.259722 },
        City { name: "Oslo", lat: 59.95, lon: 10.75 },
        City { name: "Vancouver", lat: 49.25, lon: -123.1 },
    ] {
        println!("{}", city);
    }
    for color in [
        Color { red: 128, green: 255, blue: 90 },
        Color { red: 0, green: 3, blue: 254 },
        Color { red: 0, green: 0, blue: 0 },
    ] {
        // Променете кода да използва {},
        // след като осъществите fmt::Display за Color.
        println!("{:?}", color);
    }
}

Можете да видите пълния списък отличители за форматиране и техните типове аргументи в документацията за std::fmt.

Упражнение

Осъществете fmt::Display за структурата Color, така че изходът да изглежда така:

RGB (128, 255, 90) 0x80FF5A
RGB (0, 3, 254) 0x0003FE
RGB (0, 0, 0) 0x000000

Три съвета в случай на затруднения:

Вижте също:

std::fmt

1

склад (за временно съхранение) – buffer

Първични типове

Ръждьо предоставя голямо разнообразие от първични (основни) типове1. Ето някои:

Прости Типове2

  • Цели числа със знак: i8, i16, i32, i64, i128 и isize (размер за указател)
  • Цели числа без знак: u8, u16, u32, u64, u128 и usize (размер за указател)
  • Числа с плаваща запетая: f32, f64
  • char Единични стойности от Уникод като 'ѫ', 'a', 'α' и '∞' (всяка заема 4 байта)
  • bool С възможни стойности true или false
  • Единичният тип3 (), чиято единствена възможна стойност е празна разнородна поредица: ()

Въпреки че стойността на единичния тип е разнородна поредица, той не се смята за съставен тип4, тъй като не съдържа множество стойности.

Съставни Типове

  • Еднородни поредици – [1, 2, 3]
  • Разнородни поредици – (1, true)

Променливите винаги може да се отбелязват с тип. Числата могат да се отбелязват с наставка или по подразбиране. Целите числа по подразбиране са с тип i32, а тези с плаваща запетая – f64. Обърнете внимание, че Ръждьо може да отгатва типа в зависимост от текущата употреба5.

fn main() {
    // Типът на променливите може да се отбелязва.
    let logical: bool = true;

    let a_float: f64 = 1.0;  // Обичайно отбелязване
    let an_integer   = 5i32; // Отбелязване чрез наставка

    // Или се ползва тип по подразбиране.
    let default_float   = 3.0; // `f64`
    let default_integer = 7;   // `i32`

    // Типът може да бъде отгатнат в зависимост от употребата на променливата.
    let mut inferred_type = 12; // Типът i64 е отгатнат от друг ред.
    inferred_type = 4294967296i64;

    // Стойността на менѝмите променливи може да бъде променяна.
    let mut mutable = 12; // Mutable `i32`
    mutable = 21;

    // Грешка! Типът на променливата не може да се променя.
    mutable = true;

    // Променливите могат да се презаписват чрез засенчване.
    let mutable = true;
}

Б. пр.

1

първични типове, основни типове – primitives

2

прости (единични, скаларни) типове – scalar types

3

Единичен тип – unit type

4

съставен тип – compound type

5

текущата употреба, контекст – context

Вижте също:

std library, mut, inference, и shadowing

Буквални стойности и оператори

Целите числа 1, числата с плаваща запетая 1.2, знаците "a", низовете "abc", логическите стойности true и единичният тип () могат да бъдат изразени чрез буквални стойности.

Целите числа могат да бъдат представени и като шестнадесетични, осмични или двоични, като се използват следните представки: 0x, 0o или 0b.

В числовите буквални стойности могат да се ползват подчертавки за по-добра четимост, например: 1_000 е същото като 1000, а 0.000_001 е 0.000001.

Ръждьо поддържа и експоненциално записване: 1e6, 7.6e-4. Използваният тип е f64.

Трябва да кажем на компилатора типа на буквалната стойност, който желаем да ползваме за нея. Засега ще ползваме наставката u32, за да укажем, че числото е цяло, 32-битово и без знак. С наставката i32 ще указваме 32-битово цяло число със знак.

Операторите и предимството, с което се изпълняват в Ръждьо, са подобни на тези в другите C-подобни езици.

fn main() {
    // Сбор на цели числа
    println!("1 + 2 = {}", 1u32 + 2);

    // Разлика от цели числа
    println!("1 - 2 = {}", 1i32 - 2);
    // ЗАДАЧА ^ Променете `1i32` на `1u32`, за да видите защо е важен типът.

    // Научно записване
    println!("1e4 is {}, -2.5e-3 is {}", 1e4, -2.5e-3);

    // Съкратено логическо записване
    println!("true AND false е {}", true && false);
    println!("true OR false е {}", true || false);
    println!("NOT true е {}", !true);

    // Побитови действия
    println!("0011 AND 0101 е {:04b}", 0b0011u32 & 0b0101);
    println!("0011 OR 0101 е {:04b}", 0b0011u32 | 0b0101);
    println!("0011 XOR 0101 е {:04b}", 0b0011u32 ^ 0b0101);
    println!("1 << 5 е {}", 1u32 << 5);
    println!("0x80 >> 2 е 0x{:x}", 0x80u32 >> 2);

    // Използвайте подчертавки за по-добра четимост!
    println!("Един милион се пише така: {}", 1_000_000u32);
}

Разнородни поредици

Разнородната поредица е сбирка от стойности с различни типове. Разнородните поредици се създават с помощта на кръгли скоби () и всяка поредица е стойност с описание на типа (T1, T2, ...), където T1, T2 са типовете на нейните членове. Функциите могат да използват такива поредици, за да връщат множество стойности, тъй като разнородните поредици могат да съдържат всякакъв брой стойности.

// Разнородните поредици могат да бъдат ползвани като аргументи за функции
// и като стойност за връщане.
fn reverse(pair: (i32, bool)) -> (bool, i32) {
    // С помощта на `let` можем да присвоим отделните членове на променливи.
    let (int_param, bool_param) = pair;

    (bool_param, int_param)
}

// Следната структура е за упражнението.
#[derive(Debug)]
struct Matrix(f32, f32, f32, f32);

fn main() {
    // Поредица с повече разнородни стойности.
    let long_tuple = (1u8, 2u16, 3u32, 4u64,
                      -1i8, -2i16, -3i32, -4i64,
                      0.1f32, 0.2f64,
                      'a', true);

    // Стойностите се извличат чрез указване на поредния номер (индексиране).
    println!("Long tuple first value: {}", long_tuple.0);
    println!("Long tuple second value: {}", long_tuple.1);

    // Разнородни могат да бъдат членове на други разнородни.
    let tuple_of_tuples = ((1u8, 2u16, 2u32), (4u64, -1i8), -2i16);

    // Разнородните са печатаеми.
    println!("tuple of tuples: {:?}", tuple_of_tuples);

    // Но дълги разнородни (по-големи от 12 члена) не са печатаеми.
    //let too_long_tuple = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13);
    //println!("Too long tuple: {:?}", too_long_tuple);
    // ЗАДАЧА ^ Разкоментирайте горните два реда,
    // за да видите грешката при компилация.

    let pair = (1, true);
    println!("Чифтът е {:?}", pair);

    println!("Обърнатият чифт е {:?}", reverse(pair));

    // За да създадете разнородна поредица с единична буквална стойност, трябва
    // да поставите запетая след единствената стойност и да оградите цялото с
    // кръгли скоби. Така компилаторът може да я отличи от обикновена буквална
    // стойност, оградена със скоби.
    println!("Едночленна разнородна поредица: {:?}", (5u32,));
    println!("Просто едно цяло число: {:?}", (5u32));

    // Разнородните поредици могат да бъдат разлагани на отделни променливи.
    let tuple = (1, "hello", 4.5, true);
    let (a, b, c, d) = tuple;
    println!("{:?}, {:?}, {:?}, {:?}", a, b, c, d);

    let matrix = Matrix(1.1, 1.2, 2.1, 2.2);
    println!("{:?}", matrix);
}

Упражнения

  1. Преговор: Добавете fmt::Display към структурата Matrix в примера горе, така че, ако използвате формата {}, да видите следния изход:

    ( 1.1 1.2 )
    ( 2.1 2.2 )
    

    За да си припомните, може да се върнете на примера с отпечатване чрез fmt::Display.

  2. Добавете функция transpose1, която приема matrix като аргумент и връща матрица, на която средните два елемента са разместени. Използвайте reverse за образец2. Пример:

    println!("Matrix:\n{}", matrix);
    println!("Transpose:\n{}", transpose(matrix));

    Изход:

    Matrix:
    ( 1.1 1.2 )
    ( 2.1 2.2 )
    Transpose:
    ( 1.1 2.1 )
    ( 1.2 2.2 )
    

Б. пр.

1

размествам, премествам от другата страна, сменям местата на две неща – transpose

2

образец, шаблон – template

Поредици и отрязъци

Поредицата1 е сбирка от обекти2 с един и същи тип T, съхранявани в съседни клетки от паметта. Поредиците се създават с помощта на квадратни скоби []. Дължината им се знае още по време на компилиране и е част от описанието на типа [T; дължина].

Отрязъците3 са подобни на поредиците, но тяхната дължина е неизвестна по време на компилация. Отрязъкът е двусловен обект – първата дума е указател към данните, а втората показва размера (дължината) на отрязъка. Типът на размера е същият като usize, сиреч 64 бита при архитектура x86-64. Отрязъците могат да бъдат използвани за заемане4 на дял (отрязък) от поредица и имат описание5 на типа &[T].

use std::mem;

// Тази функция заема (взема на заем) отрязък от поредица.
fn analyze_slice(slice: &[i32]) {
    println!("Първи член на отрязъка: {}", slice[0]);
    println!("Отрязъкът има {} члена", slice.len());
}

fn main() {
    // Поредица с непроменим размер (описанието на типа ([i32; 5]) е излишно).
    let xs: [i32; 5] = [1, 2, 3, 4, 5];

    //  Всички членове може да се зададат предварително с определена еднаква за
    // всички стойност.
    let ys: [i32; 500] = [0; 500];

    // Преброяването (индексирането) започва от 0.
    println!("Първи член на поредицата: {}", xs[0]);
    println!("Втори член на поредицата: {}", xs[1]);

    // `len` връща броя на членовете в поредицата.
    println!("Брой на членовете в поредицата: {}", xs.len());

    // Поредиците се слагат на стълпа.
    println!("Поредицата заема {} байта от паметта", mem::size_of_val(&xs));

    // Поредиците могат да бъдат заемани автоматично, като отрязъците.
    println!("Заемаме цялата поредица като отрязък.");
    analyze_slice(&xs);

    // Отрязъците могат да сочат към дял (част) от поредица.
    // Те изглеждат така: [начално_място..крайно_място].
    // `начално_място` е мястото в поредицата, което ще бъде първо в отрязъка.
    // `крайно_място` е с едно по-голямо от последното място в отрязъка.
    println!("Заемаме дял от поредицата като отрязък.");
    analyze_slice(&ys[1 .. 4]);

    // Пример за празен отрязък: `&[]`:
    let празна_поредица: [u32; 0] = [];
    assert_eq!(&празна_поредица, &[]);
    assert_eq!(&празна_поредица, &[][..]); // Същото, но по-подробно

    // Членовете на поредиците могат да бъдат достъпвани безопасно като
    // използваме метода `.get`, който връща `Option`. Това може да се ползва при
    // намиране на съвпадения или да се ползва с `.expect()`, ако искате
    // програмата ви да излиза с хубаво съобщение, вместо просто да продължава.
    for i in 0..xs.len() + 1 { // Опаа, с един член повече!
        match xs.get(i) {
            Some(xval) => println!("{}: {}", i, xval),
            None => println!("По-полека, забави, забави! {} е в повече!", i),
        }
    }

    // Достъп до член извън границите на поредица предизвиква грешка по време
    // на компилация.
    //println!("{}", xs[5]);
    // Достъп до член извън границите на отрязък предизвиква грешка по време
    // на изпълнение.
    //println!("{}", xs[..][5]);
}

Б. пр.

Бележките по-долу описват избраните български думи. Ще се стремим да ги ползваме с предимство. Целта е да поизчистим нашия език от заливащите ни американизми. В края на османското владичество езикът ни е приличал на езика на програмистите и по-младите днес, само че с турски думи. По това явление можем да съдим под чие владичество се намираме.

1

поредица, масив – array. От простонароден латински (през френски) *ar-redare – слагам в ред, подреждам.

2

предмети, обекти – objects

3

отрязъци, рѐзени – slices

4

заемане, заемка, заемам, вземам на заем – borrowwing, borrow

5

описание, обявление – signature

Потребителски типове

Потребителските типове в Ръждьо се създават главно чрез две ключови думи:

  • struct: Описваме структура
  • enum: Описваме броител

Константи могат да се създават също така с const и static.

Структури

Има три вида структури (structs), които могат да бъдат създавани с ключовата дума struct:

  • Подредени структури, които са просто именувани разнородни поредици;
  • Класически – същите като в C;
  • Единични (Unit) структури, които нямат полета и са полезни за обобщения.
// Атрибут за скриване на предупрежденията за неизползван код.
#![allow(dead_code)]
// Спираме предупрежденията за необичайни знаци.
#![allow(uncommon_codepoints)]

#[derive(Debug)]
struct Person {
    name: String,
    age: u8,
}

// Единична структура
struct Unit;

// Подредена структура
struct Pair(i32, f32);

// Структура с две полета
struct Point {
    x: f32,
    y: f32,
}

// Структурите могат да бъдат използвани и като стойности на полета в други
// структури.
struct Правоѫгълник {
    // Правоѫгълникът може да се опише, като се укаже къде се намират горният ляв
    // и долният десен ъгъл в пространството.
    горе_ляво: Point,
    долу_дясно: Point,
}

fn main() {
    // Могат да се създават структури, като за стойности на полетата се подадат
    // променливи със същите имена като имената на полетата.
    let name = String::from("Peter");
    let age = 27;
    let peter = Person { name, age };

    // Отпечатваме структурата 
    println!("{:?}", peter);

    // Създаваме нова структура с тип `Point`
    let point: Point = Point { x: 10.3, y: 0.4 };

    // Достъп до полетата на point
    println!("Координати на точката: ({}, {})", point.x, point.y);

    // Създаваме нова "точка", като използваме правописа за обновяване чрез
    // използване на полетата на старата.
    let долу_дясно = Point { x: 5.2, ..point };

    // `долу_дясно.y` ще има същата стойност като `point.y` защото
    // използвахме това поле от `point`
    println!("Втора точка: ({}, {})", долу_дясно.x, долу_дясно.y);

    // Разлагаме точката в променливи left_edge и top_edge, като използваме
    // *обвързване* чрез `let`
    let Point { x: left_edge, y: top_edge } = point;

    let _rectangle = Правоѫгълник {
        // създаването на структура също е израз (връща стойност)
        горе_ляво: Point { x: left_edge, y: top_edge },
        // ползваме променлива с името на полето, за да му дадем стойност
        долу_дясно,
    };

    // Създаваме нов обект на единичната структура Unit.
    let _unit = Unit;

    // Създаваме нов Pair - разнородна поредица
    let pair = Pair(1, 0.1);

    // Достъп до стойностите на полетата на обекта на разнородната структура
    println!("pair contains {:?} and {:?}", pair.0, pair.1);

    // Разлагаме чрез подредена структура
    let Pair(integer, decimal) = pair;

    println!("pair contains {:?} and {:?}", integer, decimal);
}

Бележки на преводача

Обвързването (binding) в Ръждьо е същото като присвояване на стойност на променлива в другите езици. Тук обвързваме дадена стойност с име.

Виждаме, че можем да ползваме всяка азбука дори в имената на структурите и функциите, не само на променливите.

Упражнения

  1. Добавете функция rect_area, която изчислява площта на един Четирѭгълник ( опитайте да ползвате вложено разлагане).
  2. Добавете функция square, която приема променлива от тип Point и променлива от тип f32 като аргументи и връща тип Четирѭгълник, чийто горен ляв ъгъл е същият като точката, а ширината и дължината съответстват на подадената променлива от тип f32.

Вижте също

attributes и destructuring

Броители

Ключовата дума enum1 позволява създаването на тип, който може да представлява един от няколко различни варианта. Всеки вариант, който може да бъде действителна2 структура, може да бъде действителен и в броител (enum).

// Създаваме `enum`, за да определим някакво събитие в уеб.
// Забележете как името и типът на данните заедно определят варианта:
// `PageLoad != PageUnload` и `KeyPress(char) != Paste(String)`.
// Всеки вариант е различен и независим.
enum WebEvent {
    // Всеки вариант на `enum` може да бъде:
    // празна единица `unit`;
    PageLoad,
    PageUnload,
    // разнородна поредица `tuple`;
    KeyPress(char),
    Paste(String),
    // или C-образна стурктура (като тези в езика C).
    Click { x: i64, y: i64 },
}

// Функция, която приема броител `WebEvent` като аргумент
// и не връща нищо.
fn inspect(event: WebEvent) {
    match event {
        WebEvent::PageLoad => println!("заредихте страницата"),
        WebEvent::PageUnload => println!("напуснахте страницата"),
        // Разлагаме (изваждаме) `c` от варианта на `enum`.
        WebEvent::KeyPress(c) => println!("натиснахте '{}'.", c),
        WebEvent::Paste(s) => println!("поставихте \"{}\".", s),
        // Разлагаме `Click` на `x` и `y`.
        WebEvent::Click { x, y } => {
            println!("натиснахте място с координати x={}, y={}.", x, y);
        },
    }
}

fn main() {
    let pressed = WebEvent::KeyPress('x');
    // `to_owned()` създава *притежаван* `String` от низов отрязък.
    let pasted  = WebEvent::Paste("my text".to_owned());
    let click   = WebEvent::Click { x: 20, y: 80 };
    let load    = WebEvent::PageLoad;
    let unload  = WebEvent::PageUnload;

    inspect(pressed);
    inspect(pasted);
    inspect(click);
    inspect(load);
    inspect(unload);
}

Прякори на типове

Ако ползвате прякор3 на тип, можете да се обръщате към всеки вариант на броителя чрез неговия прякор. Това може да се окаже полезно, ако името на броителя е твърде дълго или твърде общо и искате да го промените.

enum VeryVerboseEnumOfThingsToDoWithNumbers {
    Add,
    Subtract,
}

// Създаваме прякор на типа
type Operations = VeryVerboseEnumOfThingsToDoWithNumbers;

fn main() {
    // Можем да достигаме до всеки вариант на броителя чрез прякора му.
    // По-кратко и удобно е.
    let x = Operations::Add;
}

Най-често ще виждате използването на прякори в блоковете за осъществяване impl, където се ползва прякорът Self.

enum VeryVerboseEnumOfThingsToDoWithNumbers {
    Add,
    Subtract,
}

impl VeryVerboseEnumOfThingsToDoWithNumbers {
    fn run(&self, x: i32, y: i32) -> i32 {
        match self {
            Self::Add => x + y,
            Self::Subtract => x - y,
        }
    }
}

За да научите повече за броителите и типовите прякори, може да прочетете отчета за стабилизация. Оттогава е стабилна тази способност4 на Ръждьо.

Вижте също:

match, fn и String, "Type alias enum variants" RFC

Б. пр.

1

броител – enum. От enumerator – буквално „изброител”

2

действителен – valid

4

способност, възможност – feature

use

С обявлението use (ползвам) избягваме ръчното указване на обхвата1:

// Скриваме предупрежденията за неизползван код.
#![allow(dead_code)]

enum Status {
    Rich,
    Poor,
}

enum Work {
    Civilian,
    Soldier,
}

fn main() {
    // Изрично `use` (указваме, че ще ползваме) всяко име.
    // Така избягваме изписването на пълния път до него (т.е. обхвата му).
    use crate::Status::{Poor, Rich};
    // Автоматично `use` (използваме) всяко име от `Work`.
    use crate::Work::*;

    // Същото като `Status::Poor`.
    let status = Poor;
    // Същото като `Work::Civilian`.
    let work = Civilian;

    match status {
        // Забележете, че вариантите са достъпни без пълно изписване,
        // понеже изрично ползвахме `use` горе.
        Rich => println!("Богатият има много пари"),
        Poor => println!("Бедният няма пари..."),
    }

    match work {
        // Отново не указваме пълния път до вариантите.
        Civilian => println!("Цивилните работят!"),
        Soldier  => println!("Войниците се бият!"),
    }
}

Б. пр.

1

указване на обхвата („взор” от гр.) на променливите – scoping; обхват (взор), между кои две фигурни скоби (блок от код) е видима променливата (в какъв обхват) – scope. Това е различно от видимост – visibility, където се има предвид общодостъпност (pub) и частност на единиците (променливи, типове, функции).

Вижте също:

match и use

Като в C

Броителите (enum) може да се ползват както в C.

// Скриваме предупрежденията за неизползван код.
#![allow(dead_code)]

// `enum` с премълчан различител (започва от 0)
enum Number {
    Zero,
    One,
    Two,
}

// `enum` с изричен различител
enum Color {
    Red = 0xff0000,
    Green = 0x00ff00,
    Blue = 0x0000ff,
}

fn main() {
    // `enums` могат да бъдат приведени (cast) до цели числа.
    println!("zero is {}", Number::Zero as i32);
    println!("one is {}", Number::One as i32);

    println!("roses are #{:06x}", Color::Red as i32);
    println!("violets are #{:06x}", Color::Blue as i32);
}

Вижте също:

Привеждане към тип (casting)

Проверка: свързан списък

Често свързаните списъци се осъществяват чрез enum:

use crate::List::*;

enum List {
    // Cons: разнородна поредица, съдържаща един член от списъка и указател към
    // следващия възел
    Cons(u32, Box<List>),
    // Nil: Възел, обозначаващ края на свързания списък
    Nil,
}

// Към броителя могат да се прикачват методи
impl List {
    // Създава празен списък
    fn new() -> List {
        // Типът на `Nil` е `List`
        Nil
    }

    // Приема списък и връща същия списък с нов член в началото му
    fn prepend(self, elem: u32) -> List {
        // Типът на `Cons` също е List
        Cons(elem, Box::new(self))
    }

    // Връща дължината на списъка
    fn len(&self) -> u32 {
        // Трябва да проверим за съответствие със `self`, защото
        // поведението на този метод зависи от варианта на `self`
        // Типът на`self` е `&List`, а типът на `*self` е `List`.
        // За предпочитане е да се търси съответствие с дадения тип `T`,
        // вместо с препратката `&T`.
        // След Ръждьо 2018 можем да ползваме `self` тук, както и tail
        // (без препратка) по-долу. `&s` и `ref tail` ще бъдат отгатнати. 
        // Вижте https://doc.rust-lang.org/edition-guide/rust-2018/ownership-and-lifetimes/default-match-bindings.html
        match *self {
            // Не можем да овладеем (take ownership of) `tail`, защото `self`
            // е взет на заем; вместо това вземаме препратка към `tail`
            Cons(_, ref tail) => 1 + tail.len(),
            // Основен случай: Празният списък е с нулева дължина
            Nil => 0
        }
    }

    // Връща представяне на списъка като низ (от динамичната памет)
    fn stringify(&self) -> String {
        match *self {
            Cons(head, ref tail) => {
                // `format!` е подобен на `print!`, но връща низ
                // от динамичната памет, вместо да печати в конзолата.
                format!("{}, {}", head, tail.stringify())
            },
            Nil => {
                format!("Nil")
            },
        }
    }
}

fn main() {
    // Създаваме празен свързан списък 
    let mut list = List::new();

    // Добавяме няколко члена в началото на списъка
    list = list.prepend(1);
    list = list.prepend(2);
    list = list.prepend(3);

    // Показваме окончателното състояние на списъка
    println!("свързаният списък е с дължина {}.", list.len());
    println!("{}", list.stringify());
}

Вижте също:

Box и methods

Константи

Ръждьо има два вида константи1, които могат да бъдат обявени във всеки обхват на видимост, включително глобален. И двата вида изискват изрично отбелязване на типа.

  • const: Неменѝма стойност (общият случай).
  • static: Възможно менѝма (mut) променлива със статичен живот – 'static. Статичният живот е отгатнат2 и не е нужно да се указва изрично. Достъпът до или промяната на менѝма статична променлива е опасно3 (unsafe) действие.
// Глобалните се обявяват извън всички други обхвати на видимост.
static LANGUAGE: &str = "Ръждьо";
const THRESHOLD: i32 = 10;

fn is_big(n: i32) -> bool {
    // Достъп до стойността на константа в някоя функция
    n > THRESHOLD
}

fn main() {
    let n = 16;

    // Достъп до константа в главната нишка
    println!("Това е {}", LANGUAGE);
    println!("Прагът е {}", THRESHOLD);
    println!("{} е {}", n, if is_big(n) { "голям" } else { "малък" });

    // Грешка! Не може да се изменя `const`.
    THRESHOLD = 5;
    // ПОПРАВИ ^ Да се коментира този ред
}

Вижте също:

RFC за const/static, 'static lifetime

Б. пр.

1

константи, непроменливи – constants

2

отгатнат – inferred

3

опасно – unsafe

Обвързване на променливи

Ръждьо предоставя безопасност чрез статично типизиране. Когато обвързваме променлива със стойност1, типът може да бъде указан при обявяването на променливата. В повечето случаи обаче компилаторът ще успее да отгатне типа на променливата от употребата ѝ, като с това силно намалява нуждата от изрично отбелязване на типа.

Стойностите (включително и буквалните) могат да бъдат обвързани с променливи с помощта на оператора let.

fn main() {
    let an_integer = 1u32;
    let a_boolean = true;
    let unit = ();

    // копираме `an_integer` в `copied_integer`
    let copied_integer = an_integer;

    println!("Цяло число: {:?}", copied_integer);
    println!("Булева променлива: {:?}", a_boolean);
    println!("Запознайте се с единичната (празна) стойност `unit`: {:?}", unit);

    // Компилаторът предупреждава за неизползвани обвързвания.
    // Тези предупреждения могат да бъдат заглушени, като започнем името
    // на променливата с подчертавка.
    let _unused_variable = 3u32;

    let noisy_unused_variable = 2u32;
    // ПОПРАВИ ^ Поставете подчертавка в началото на името,
    // за да подтиснете предупреждението.
    // Забележете, че предупрежеденията може да не се покажат,
    // ако пуснете програмата направо от уеб-четеца.
}
1

обвързване на променлива (със стойност) – variable binding

Менѝмост

Обвързването на променлива е неменѝмо1 по подразбиране. Но с помощта на променителя2 mut, промяната на стойността може да бъде разрешена.

fn main() {
    let _immutable_binding = 1;
    let mut mutable_binding = 1;

    println!("Преди промяната: {}", mutable_binding);

    // Ok
    mutable_binding += 1;

    println!("След промяната: {}", mutable_binding);

    // Грешка! Не може да се присвои нова стойност на неменѝма променлива
    _immutable_binding += 1;
}

Компилаторът ще изведе подробни описания на грешките, свързани с менимостта на променливите.

Б. пр.

1

неменѝмо, непроменимо – (im)mutable. неменѝмост – immutability; непроменяемост – immutability

2

изменител, модификатор – modifier

Обхват и засенчване

Обвързването на дадена променлива е с определен обхват. Обхватът (в какво пространство е видима (достъпна) една променлива) е ограничен от обгръщащия я блок. Блокът е набор от изявления1, ограден с фигурни скоби {}.

fn main() {
    // Това обвързване живее (е в обхват) във функцията `main`.
    let long_lived_binding = 1;

    // Това е блок и има по-малък обхват от функцията `main`.
    {
        // Това обвързване съществува само в този блок.
        let short_lived_binding = 2;

        println!("вътрешно краткосрочно: {}", short_lived_binding);
    }
    // Край на блока

    // Грешка! `short_lived_binding` не съществува в този обхват.
    println!("външно краткосрочно обвързване: {}", short_lived_binding);
    // ПОПРАВИ ^ Да се коментира този ред.

    println!("външно дългосрочно: {}", long_lived_binding);
}

Засенчване на променливи също е разрешено.

fn main() {
    let shadowed_binding = 1;

    {
        println!("Преди засенчване: {}", shadowed_binding);

        // Тази променлива *засенчва* външната.
        let shadowed_binding = "abc";

        println!("засенчена във вътрешния блок: {}", shadowed_binding);
    }
    println!("във външния блок: {}", shadowed_binding);

    // Това обвързване *засенчва* предишното обвързване.
    let shadowed_binding = 2;
    println!("засенчена във външния блок: {}", shadowed_binding);
 
}

Б. пр.

1

изявление – statement

Предварително обявление

Възможно е първо само да се обяви обвързване на променлива, а по-късно да се даде начална стойност. Това обаче рядко се прави, тъй като някои променливи може да останат без начална стойност.

fn main() {
    // Обявяваме обвързване с променлива
    let a_binding;

    {
        let x = 2;

        // Даваме начална стойност
        a_binding = x * x;
    }

    println!("обвързване: {}", a_binding);

    let another_binding;

    // Грешка! Употреба на неинициализирано обвързване
    println!("друго обвързване: {}", another_binding);
    // ПОПРАВИ ^ Да се коментира този ред

    another_binding = 1;

    println!("друго обвързване: {}", another_binding);
}

Компилаторът забранява използването на променливи без стойност, защото това би довело до неопределено поведение.

Замразяване

Когато данни са обвързани с променлива неизменяемо, това ги замразява. Замразени данни не могат да бъдат изменяни дотогава, докато неменимото обвързване не излезе извън обхват.

fn main() {
    let mut _mutable_integer = 7i32;

    {
        // Засенчване чрез неменимо обвързване `_mutable_integer`
        let _mutable_integer = _mutable_integer;

        // Грешка! `_mutable_integer` is frozen in this scope
        _mutable_integer = 50;
        // ПОПРАВИ ^ Да се коментира този ред

        // `_mutable_integer` излиза от обхват
    }

    // Ok! `_mutable_integer` не е замразено тук
    _mutable_integer = 3;
}

Типове

Ръждьо предоставя няколко начина за промяна или задаване типа на първични и потребителски типове. Следните раздели покриват:

Привеждане към тип

Ръждьо не прави неявно (принудително) привеждане1 между първичните типове. Но изрично привеждане2 може да се прави с помощта на ключовата дума as (като).

Правилата за преобразуване между целочислените стойности следват тези в езика C като цяло, освен в случаите, където в C поведенеието е неопределено. Поведението при преобразуване между всички целочислени типове е строго определено в Ръждьо.

// Подтискаме всички предупреждения за преливащи привеждания между типовете.
#![allow(overflowing_literals)]

fn main() {
    let decimal = 65.4321_f32;

    // Грешка! Няма неявно привеждане (coercion)
    let integer: u8 = decimal;
    // ПОПРАВИ ^ Да се коментира този ред

    // Изрично привеждане (casting)
    let integer = decimal as u8;
    let character = integer as char;

    // Грешка! Има някои ограничения при привеждане.
    // Десетична дроб не може да се приведе
    // направо към писмен знак `char`.
    let character = decimal as char;
    // ПОПРАВИ ^ Да се коментира този ред

    println!("Привеждане: {} -> {} -> {}", decimal, integer, character);

    // Когато се привежда каквато и да е стойност към беззнаков тип, T,
    // T::MAX + 1 се добавя или изважда,
    // докато стойността не се побере в новия тип.

    // 1000 се побира в u16
    println!("1000 като u16 е: {}", 1000 as u16);

    // 1000 - 256 - 256 - 256 = 232
    // Подробности: първите 8 най-малко значими (младши) битове (LSB) се
    // запазват, а старшите (MSB) се орязват.
    println!("1000 като u8 е : {}", 1000 as u8);
    // -1 + 256 = 255
    println!("  -1 като u8 е : {}", (-1i8) as u8);

    // За положителни числа това е същото като получаване на остатък
    println!("Остатꙑкът от 1000, делено на 256, е: {}", 1000 % 256);

    // Когато привеждаме към знаков тип, побитовият резултат е същият като
    // първото привеждане към съответстващия беззнаков тип. Ако най-значимият
    // бит на стойността е 1, то стойността е отрицателна.

    // Освен, разбира се, когато стойността се побира в типа.
    println!(" 128 като i16 е: {}", 128 as i16);

    // В граничния случай стойността на 128, 
    // представена в 8-бита с допълнение до две, е -128
    println!(" 128 as a i8 is : {}", 128 as i8);

    // повтаряме примера от горе
    // 1000 като u8 -> 232
    println!("1000 като u8 е : {}", 1000 as u8);
    // и стойността на 232, 
    //представена в 8-бита с допълнение до две, е -24
    println!(" 232 as a i8 is : {}", 232 as i8);

    // От Ръждьо 1.45, ключовата дума `as` работи като *наситено привеждане*,
    // когато привеждаме от тип с плаваща запетая към целочислен тип. Ако
    // дробната стойност надвишава горната граница или е по-малка от долната
    // граница, върнатата стойност ще бъде равна на прескочената граница.

    // 300.0 като u8 е 255
    println!(" 300.0 като u8 е: {}", 300.0_f32 as u8);
    // -100.0 като u8 е 0
    println!("-100.0 като u8 е: {}", -100.0_f32 as u8);
    // NAN като u8 е 0
     println!(" NAN     като u8 е: {}", f32::NAN as u8);

    // Това поведение разходва малко от времето на изпълнение и може да бъде
    // избегнато чрез опасни методи. Обаче резултатът може да прелее
    // и да върне **ненадеждни стойности**. Използвайте тези методи разумно.
    unsafe {
        // 300.0 като u8 е 44
        println!(" 300.0 като u8 е : {}", 300.0_f32.to_int_unchecked::<u8>());
        // -100.0 като u8 е 156
        println!("-100.0 като u8 е : {}", (-100.0_f32).to_int_unchecked::<u8>());
        //  NAN като u8 е 0
        println!("   NAN като u8 е : {}", f32::NAN.to_int_unchecked::<u8>());
    }
}

Бележки на преводача

Привеждането (casting) (на един тип към друг) е различно от превръщането (conversion). За привеждане се ползва ключовата дума as. Извършва се просто вместване на стойността в друг тип. Когато целевият числов тип е по-малък, при това действие стойността може да „прелее” и да загубим данни.

Превръщането (conversion) се прави при съставни и потребителски типове и се осъществява чрез отличители. Разглежда се в следващата глава – Превръщане.

преливащи привеждания между типовете – casts which overflow

1

мълчаливо привеждане насила (от един тип към друг) – coercion

2

изрично привеждане (към друг тип) – casting

Буквални стойности

Типът на числовите буквални стойнсти може да бъде указан като наставка. Например, за да укажете, че буквалната стойност 42 ще бъде от тип i32, напишете 42i32.

Типът на буквалните без наставка ще зависи от начина им на използване. Ако няма някакви ограничения, компилаторът ще използва i32 за цели числа и f64 за десетични дроби.

fn main() {
    // Буквални с наставки. Типовете им се знаят отначало.
    let x = 1u8;
    let y = 2u32;
    let z = 3f32;

    // Буквални без наставка. Типовете им ще зависят от по-нататъшната употреба.
    let i = 1;
    let f = 1.0;

    // `size_of_val` връща размера на дадена променлива в байтове.
    println!("размерът на `x` в байтове: {}", std::mem::size_of_val(&x));
    println!("размерът на `y` в байтове: {}", std::mem::size_of_val(&y));
    println!("размерът на `z` в байтове: {}", std::mem::size_of_val(&z));
    println!("размерът на ` i` в байтове: {}", std::mem::size_of_val(&i));
    println!("размерът на `f` в байтове: {}", std::mem::size_of_val(&f));
}

Някои понятия в горния код все още не са обяснени. Ето кратко обяснение за нетърпеливите читатели:

  • std::mem::size_of_val е функция, но извикана с пълния ѝ път. Програмният код може да бъде разпределен в логически единици, наречени модули. В този случай функцията size_of_val е описана в модула mem, а модулът mem е описан в коша std. За подробности вижте Модули и Кошове.

Отгатване

Двигателят за отгатване на типа е доста умен. Не просто гледа типа на връщаната стойност от израза при задаване на първоначална стойност. Гледа и начина, по който се използва променливата след това, за да отгатне типа ѝ. Ето един по-сложен пример за отгатване на типа.

fn main() {
    // Благодарение на отбелязването с наставка, компилаторът знае, че
    // типът на `elem` е u8.
    let elem = 5u8;

    // Създаване на празен вектор (поредица с нарастваща дължина).
    let mut vec = Vec::new();
    // Тук компилаторът все още не знае типа на `vec`. Знае само, че това е
    // вектор, съдържащ някакъв тип данни (`Vec<_>`).

    // Добавяме `elem` към вектора.
    vec.push(elem);
    // Аха! Сега компилаторът знае, че това е вектор от членове с тип `u8` (`Vec<u8>`).
    // ЗАДАЧА ^ Коментирайте реда с `vec.push(elem)`.

    println!("{:?}", vec);
}

Не бе нужно да отбелязваме типа на променливата. Компилаторът е щастлив, както и програмистът!

Прякори

Изявлениeто type може да се използва за задаване на ново име на съществуващ вече тип. Типовете трябва да имат имена от вида UpperCamelCase. Ако не спазите това правило, компилаторът ще ви покаже предупреждение. Изключение от него са първичните типове.

// `NanoSecond`, `Inch`, и `U64` са нови имена за `u64`.
type NanoSecond = u64;
type Inch = u64;
type U64 = u64;

fn main() {
    // `NanoSecond` = `Inch` = `U64` = `u64`.
    let nanoseconds: NanoSecond = 5 as U64;
    let inches: Inch = 2 as U64;

    // Забележете, че прякорите *не* предоставят повече безопасност по
    // отношение на типизирането, понеже те *не* са нови типове.
    println!("{} наносекунди + {} инчове = {} мерна единица?",

             nanoseconds,
             inches,
             nanoseconds + inches);
}

Прякорите се използват най-вече за намаляване на писането. Например типът io::Result<T> е прякор на Result<T, io::Error>.

Вижте също:

Атрибути

Превръщане

Първичните типове могат да бъдат превръщани от един в друг чрез привеждане.

Ръждьо се справя с превръщането между потребителски типове (да речем struct и enum) чрез отличители. Обобщените превръщания ще ползват отличителите From и Into. Но има и обособени за най-честите случаи – когато се превръща от и към низове (String).

From и Into

Отличителите From и Into са същностно свързани и тази връзка е част от начина, по който са осъществени. Ако можете да превърнете тип А в тип Б, то би трябвало лесно да превърнете и тип Б в А.

From (От)

Отличителят From дава възможност даден тип да опише как да създаде себе си от друг тип. Така имаме прост начин за превръщане между няколко различни типа. Има множество осъществявания на този отличител в стандартната библиотека за превръщане от един към друг на първични и често използвани типове.

Ето как лесно да превърнем str в String

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

Можем да опишем наше собствено превръщане за наш си тип.

use std::convert::From;

#[derive(Debug)]
struct Number {
    value: i32,
}

impl From<i32> for Number {
    fn from(item: i32) -> Self {
        Number { value: item }
    }
}

fn main() {
    let num = Number::from(30);
    println!("My number is {:?}", num);
}

Into (Къмто/Във)

Отличителят Into е просто обратното на отличителя From. Това означава, че ако сте осъществили From за вашия тип, Into ще извика вашето осъществяване, когато е нужно.

Когато използваме отличителя Into, обикновено се налага да указваме типа, към който превръщаме, тъй като компилаторът често не може да го определи. Но това е нищо, имайки предвидвид какво получаваме безплатно.

use std::convert::Into;

#[derive(Debug)]
struct Number {
    value: i32,
}

impl Into<Number> for i32 {
    fn into(self) -> Number {
        Number { value: self }
    }
}

fn main() {
    let int = 5;
    // Try removing the type annotation
    let num: Number = int.into();
    println!("My number is {:?}", num);
}

TryFrom и TryInto

Подобно на From и Into, TryFrom и TryInto са обобщени отличители за превръщане между типове. За разлика от From и Into, TryFrom и TryInto се ползват за превръщания, които може да не успеят. Затова те връщат Result.

use std::convert::TryFrom;
use std::convert::TryInto;

#[derive(Debug, PartialEq)]
struct EvenNumber(i32);

impl TryFrom<i32> for EvenNumber {
    type Error = ();

    fn try_from(value: i32) -> Result<Self, Self::Error> {
        if value % 2 == 0 {
            Ok(EvenNumber(value))
        } else {
            Err(())
        }
    }
}

fn main() {
    // TryFrom

    assert_eq!(EvenNumber::try_from(8), Ok(EvenNumber(8)));
    assert_eq!(EvenNumber::try_from(5), Err(()));

    // TryInto

    let result: Result<EvenNumber, ()> = 8i32.try_into();
    assert_eq!(result, Ok(EvenNumber(8)));
    let result: Result<EvenNumber, ()> = 5i32.try_into();
    assert_eq!(result, Err(()));
}

Към и от низове

Превръщане към String

За да превърнем от всякакъв тип към низ (String), трябва просто да осъществим отличителя ToString за дадения тип. Вместо да го правим наистина, по-добре да осъществим fmt::Display, който автоматично предоставя ToString и позволява отпечатване на типа, както обсъдихме вече в раздела за print!.

use std::fmt;

struct Circle {
    radius: i32
}

impl fmt::Display for Circle {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Circle of radius {}", self.radius)
    }
}

fn main() {
    let circle = Circle { radius: 6 };
    println!("{}", circle.to_string());
}

Разбор на String

Един от най-често срещаните случаи на превръщане е този на низ към число. Обичайният1 за Ръждьо подход тук е да ползвате функцията parse и или да улесните отгатването на типа, или да укажете типа за извличане посредством правописа „турбориба”2. И двата начина са показани в следващия пример.

Това ще превърне низа в указания тип, доколкото е осъществен отличителят FromStr за този тип. Много типове в стандартната библиотека осъществяват този отличител. За да имаме това действие за потребителски тип, просто осъществяваме FromStr за типа.

fn main() {
    let parsed: i32 = "5".parse().unwrap();
    let turbo_parsed = "10".parse::<i32>().unwrap();

    let sum = parsed + turbo_parsed;
    println!("Sum: {:?}", sum);
}

Б. пр.

разбор – parsing

правя разбор на нещо – parse

1

обичаен, собствено присъщ, идиоматичен – idiomatic. Свойствен (в случая – свойствен на Ръждьо)

2

турбориба – turbofish. Изписване име_на_метод::<Тип>(); ::<Тип> (напомня на риба).

Изрази

Програмите в Ръждьо се състоят (най-вече) от изявления:

fn main() {
    // изявлениe
    // изявлениe
    // изявлениe
}

Има няколко вида изявления в Ръждьо. Двете най-често срещани са обявяване на обвързване на променлива и използване на точка и запетая (;) с израз:

fn main() {
    // обвързваме променливата x със стойността 5
    let x = 5;

    // израз;
    x;
    x + 1;
    15;
}

Блоковете също са изрази, така че те могат да бъдат използвани като стойност за присвояване на променлива. Всеки блок може да се ползва като израз (бел. прев.). Стойността, върната от последния израз в блока, ще бъде присвоена на вероятно очакващата я променлива.1 Но! Ако последният израз в блока завършва с точка и запетая, върнатата стойност ще бъде ().2

fn main() {
    let x = 5u32;

    let y = {
        let x_squared = x * x;
        let x_cube = x_squared * x;

        // Този израз ще бъде присвоен на `y`
        x_cube + x_squared + x
    };

    let z = {
        // Точката и запетаята подтискат този израз. Като следствие на `z` е
        // присвоена стойността `()`
        2 * x;
    };

    println!("x is {:?}", x);
    println!("y is {:?}", y);
    println!("z is {:?}", z);
}

Б. пр.

1

стойност за присвояване, дясна стойност – rvalue. Не е обяснено какво всъщност е израз (изявление, което връща присвоима стойност). Да се разясни: https://en.wikipedia.org/wiki/Value_(computer_science)#lrvalue

2

празна единична стойност – (), като void в едни , а null,Null,nil в други езици. Вижте Unit_type в Wikipedia

Управление на програмния поток

Неразделна част от всеки език за програмиране са начините за управление на програмния поток: if/else, for и други. Да поговорим за тях в Ръждьо.

if/else

Разклоняването чрез if-else е подобно на другите езици. За разлика от много от тях, условието не е нужно да бъде оградено със скоби и всяко условно разклонение е задължително следвано от блок. Условията if-else са изрази1 и всички разклонения трябва да връщат данни с един и същи тип.

fn main() {
    let n = 5;

    if n < 0 {
        print!("{} е отрицателно", n);
    } else if n > 0 {
        print!("{} е положително", n);
    } else {
        print!("{} е нула", n);
    }

    let big_n =
        if n < 10 && n > -10 {
            println!(", и е малко число, да го увеличим  десет пъти…");

            // Този израз връща данни от тип `i32`.
            10 * n
        } else {
            println!(", и е голямо число, да го намалим наполовина…");

            // Този израз трябва също да върне `i32`.
            n / 2
            // ЗАДАЧА ^ Опитайте да подтиснете този израз с точка и запетая.
        };
    //   ^ Не забравяйте да поставите ; тук!
    // Всички обвързвания на променливи го изискват.

    println!("{} -> {}", n, big_n);
}

Вижте също

Изрази

Б. пр.

1

ако-то – if-else са изрази. Това означава, че връщат стойност.

loop

Ръждьо предоставя ключовата дума loop1 за описване на безкраен цикъл.

С изявлениeто break можем да излезем от цикъла по всяко време, а с изявлениeто continue можем да пропуснем останалите изявления в повторението и да започнем ново.

fn main() {
    let mut count = 0u32;

    println!("Нека броим до безкрайност!");

    // Безкраен цикъл
    loop {
        count += 1;

        if count == 3 {
            println!("три");

            // Пропускаме остатъка от повторението
            continue;
        }

        println!("{}", count);

        if count == 5 {
            println!("Добре, стига толкова");

            // Излизаме от този цикъл
            break;
        }
    }
}

Б. пр.

1

безкраен цикъл – loop – клуп, примка, гайка; правя затворена верига, зациклям. Безкрайно повтарящ се набор от изявления.

Влагане и отметки

Възможно е да прекъснем (break) или продължим (continue) външни цикли, когато имаме вложени цикли. В тези случаи циклите трябва да се отбележат с някакъв белег ('label) и белегът трябва да се подаде на изявлението break или continue.

#![allow(unreachable_code, unused_labels)]

fn main() {
    'външен: loop {
        println!("Влязохме във външния цикъл…");

        'вътрешен: loop {
            println!("Влязохме във вътрешния цикъл…");

            // Това ще прекъсне само вътрешния цикъл
            //break;

            // Това прекъсва външния цикъл
            break 'външен;
        }

        println!("Никога няма да стигнем тук.");
    }

    println!("Излязохме от външния цикъл.");
}

Връщане на стойност

Един от начините за използване на loop е да се опитва някакво действие, докато успее. Ако действието върне някаква стойност, може да искаме да я подадем на останалия код. Поставете стойността след break и тя ще бъде върната от израза за цикъл.

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

    assert_eq!(result, 20);
}

while

Ключовата дума while (докато) може да се използва за изпълнение на цикъл, докато някакво условие е истина.

Да напишем досадната програма FizzBuzz, като изпозлваме цикълwhile.

fn main() {
    // Промелива за броене
    let mut n = 1;

    // Въртим, докато `n` е по-малко от 101
    while n < 101 {
        if n % 15 == 0 {
            println!("fizzbuzz");
        } else if n % 3 == 0 {
            println!("fizz");
        } else if n % 5 == 0 {
            println!("buzz");
        } else {
            println!("{}", n);
        }

        // Увеличаваме стойността на броителя
        n += 1;
    }
}

for

for и range

Действието for in може да се използва за повторение чрез Iterator (повторител1). Един от най-лесните начини да се създаде повторител е като се използва означението за редица2 a..b. Така произвеждаме стойности от a (включително) до b(без b), където стъпката е една стойност.

Да напишем FizzBuzz, като използваме for вместо while.

fn main() {
    // `n` ще приеме стойност: 1, 2, ..., 100 при всяко повторение
    for n in 1..101 {
        if n % 15 == 0 {
            println!("fizzbuzz");
        } else if n % 3 == 0 {
            println!("fizz");
        } else if n % 5 == 0 {
            println!("buzz");
        } else {
            println!("{}", n);
        }
    }
}

Ако искаме редицата да включва и първата, и последната стойност, трябва да ползваме означението a..=b. Горното може да бъде написано така:

fn main() {
    // `n` ще приеме стойност: 1, 2, ..., 101 при всяко повторение
    for n in 1..=101 {
        if n % 15 == 0 {
            println!("fizzbuzz");
        } else if n % 3 == 0 {
            println!("fizz");
        } else if n % 5 == 0 {
            println!("buzz");
        } else {
            println!("{}", n);
        }
    }
}

for и повторителите

Действието for in може да си взаимодейства с даден Iterator по няколко начина. Както се посочва в раздела за отличителя Iterator, по подразбиране цикълът for ще приложи метода into_iter върху сбирка3 от единици, които има за обхождане. Това обаче не е единственият начин за превръщане на сбирки в повторители.

Методите into_iter, iter и iter_mut превръщат някаква сбирка от единици в повторител по различни начини, като предоставят различен поглед (и възможност за действие) върху данните в сбирката.

  • iter заема4 всеки член от сбирката при всяко повторение. Така сбирката остава непроменена и може да се ползва след приключване на повторенията.
fn main() {
    let names = vec!["Bob", "Frank", "Ferris"];

    for name in names.iter() {
        match name {
            &"Ferris" => println!("Има ръждар помежду ни!"),
            // ЗАДАЧА ^ Изтрийте  знака & и сравнете само с "Ferris"
            _ => println!("Здрасти {}", name),
        }
    }
    
    println!("names: {:?}", names);
}
  • into_iter поглъща5 сбирката, така че на всяка стъпка имаме на разположение самата стойност. След поглъщането сбирката повече не може да се ползва, понеже бива преместена6 вътре в цикъла.
fn main() {
    let names = vec!["Bob", "Frank", "Ferris"];

    for name in names.into_iter() {
        match name {
            "Ferris" => println!("Има ръждар помежду ни!"),
            _ => println!("Здрасти {}", name),
        }
    }
    
    println!("names: {:?}", names);
    // ПОПРАВИ ^ Коментирайте този ред
}
  • iter_mut заема всеки член като менѝм и така позволява сбирката да бъде променяна на място.
fn main() {
    let mut names = vec!["Bob", "Frank", "Ferris"];

    for name in names.iter_mut() {
        *name = match name {
            &mut "Ferris" => "There is a rustacean among us!",
            _ => "Hello",
        }
    }
    // Забележете, че всички стойности в `names` са променени според сравненията.
    println!("names: {:?}", names);
}

Обърнете внимание на начините, по които сравняваме стойностите в откъсите по-горе – разклонението в match. Това е ключовата разлика между трите различни начина за сравнение. Различният вид сравнение предполага възможност за извършване на различни действия върху данните.

Б. пр.

1

повторител, итератор – iterator

2

редица (от .. до) – range; означението за редица – range notation. https://bg.wikipedia.org/wiki/Редица

3

сбирка – collection. Колекция, набор.

4

заема, взема на заем – borrows

5

поглъща – consumes. Поглъща (параметри, поредица, сбирка и т.н.) – consumes (parameters, array, collection etc.). Сиреч, стойността от променливата бива изядена (буквално), така че първоначалната променлива не може повече да бъде използвана. След поглъщането на преместените в новата променлива данни, при излизане на променливата от обхват паметта бива освободена.

6

преместен – moved. Виж Собственост и премествания

Вижте също:

Iterator

match

Ръждьо предоставя възможност зa сравнение на стойности чрез ключовата дума match, която може да се ползва както switch в езика C. Изпълнява се първото съвпадащо разклонение, а всички възможни стойности (за съвпадение) трябва да са покрити (описани).

fn main() {
    let number = 13;
    // ЗАДАЧА ^ Пробвайте различни стойности за `number`

    println!("Кажи нещо за {}", number);
    match number {
        // Съвпадение по единична стойност
        1 => println!("Едно!"),
        // Съвпадение по няколко стойности
        2 | 3 | 5 | 7 | 11 => println!("Това е просто число"),
        // ЗАДАЧА ^ Добавете 13 към поредицата от прости числа
        // Съвпадение в редица от стойности (включително)
        13..=19 => println!("Юноша"),
        // Обработка на останалите случаи
        _ => println!("Нищо особено"),
        // ЗАДАЧА ^ Коментирайте това разклонение, покриващо всички случаи.
    }

    let boolean = true;
    // `match` е също и израз.
    let binary = match boolean {
        // Разклоненията трябва да покриват всички възможни стойности.
        false => 0,
        true => 1,
        // ЗАДАЧА ^ Коментирайте едно от разклоненията
    };

    println!("{} -> {}", boolean, binary);
}

Разлагане

Блокът match може да разлага1 единици2 по различни начини.

Б. пр.

3

разлагам – destructure, разлагане (на обекти в отделни променливи) – destructuring

2

единици – items. Ето определението за единици от „The Rust Reference”: Единицата е съставна част от коша. Единиците са подредени в коша от вложен набор от модули. Всеки кош има един „най-външен” безименен модул; всички единици в коша имат свои пътища в модулното дърво на коша. Единиците са напълно определени по време на компилиране, обикновено не се променят по време на изпълнение и може да се намират в памет само за четене. Примери за единици са: модули, обявления за външни (extern) кошове, обявления use, описания на: функции, типове, структури, броители, обединения; константни единици, статични единици, описания на отличители, осъществявания, външни блокове (extern)

Разнородни

Разнородните поредици могат да бъдат разложени в match както следва:

fn main() {
    let triple = (0, -2, 3);
    // ЗАДАЧА ^ Пробвайте различни стойности за `triple`

    println!("Кажи ми нещо за {:?}", triple);
    // `match` може да се използва за разлагане на разнородна поредица
    match triple {
        // Изваждаме втория и третия член
        (0, y, z) => println!("Първият е `0`, `y` е {:?} и `z` е {:?}", y, z),
        (1, ..)  => println!("Първият е  `1`, а останалите нямат значение"),
        (.., 2)  => println!("Последният е`2`, а останалите нямат значение"),
        (3, .., 4)  => println!("Първият е `3`, последният е `4`,
        а останалите нямат значение"),
        // `..` може да се използва за пренебрегване на останалите членове
        _      => println!("Няма значение какви са"),
        // `_` означва „Не обвързвай стойността с променлива!”
    }
}

Вижте също:

Разнородни поредици

Поредици и отрязъци

Подобно на разнородните поредици, еднородните поредици и отрязъците могат да бъдат разложени по следния начин:

fn main() {
    // Променете стойностите в поредицата или я превърнете в отрязък!
    let array = [1, -2, 6];

    match array {
        // Обвързва втория и третия член със съответните променливи
        [0, second, third] =>
            println!("array[0] = 0, array[1] = {}, array[2] = {}", second, third),

        // Отделни стойности могат да бъдат пренебрегнати с _
        [1, _, third] => println!(
            "array[0] = 1, array[2] = {} and array[1] was ignored",
            third
        ),

        // Също можете да обвържете някои и да пренебрегнете останалите
        [-1, second, ..] => println!(
            "array[0] = -1, array[1] = {}, а всички останали биват пренебрегнати",
            second
        ),
        // Това долу няма да се компилира
        // [-1, second] => ...

        // Или да ги съхраните в поредица или отрязък (типът зависи от
        // стойността на това, с което се сравнява)
        [3, second, tail @ ..] => println!(
            "array[0] = 3, array[1] = {}, а останалите членове са {:?}",
            second, tail
        ),

        // Съчетавайки тези подходи, можем например да обвържем първата и
        // последната стойност, а остатъка да съхраним в отделна поредица.
        [first, middle @ .., last] => println!(
            "array[0] = {}, middle = {:?}, array[2] = {}",
            first, middle, last
        ),
    }
}

Вижте също:

Поредици и отрязъци и Програмен поток/match/Обвързване за знака @

Броители

enum се разлага по подобен начин:

// `allow` се изисква за заглушаване на предупрежденията,
//тъй като е използван само един вариант.
#[allow(dead_code)]
enum Color {
    // Тези три са определени само по име.
    Red,
    Blue,
    Green,
    // Тези обвързват разнордни поредици от стойности `u32` към различни имена:
    // цветови пространства.
    RGB(u32, u32, u32),
    HSV(u32, u32, u32),
    HSL(u32, u32, u32),
    CMY(u32, u32, u32),
    CMYK(u32, u32, u32, u32),
}

fn main() {
    let color = Color::RGB(122, 17, 40);
    // ЗАДАЧА ^ Пробвайте различни значения за `color`

    println!("Какъв е този цвят?");
    // `enum` може да бъде разложен с помощта на `match`.
    match color {
        Color::Red   => println!("Цветът е червен!"),
        Color::Blue  => println!("Цветът е син!"),
        Color::Green => println!("Цветът е зелен!"),
        Color::RGB(r, g, b) =>
            println!("Червен: {}, зелен: {} и син: {}!", r, g, b),
        Color::HSV(h, s, v) =>
            println!("Hue: {}, saturation: {}, value: {}!", h, s, v),
        Color::HSL(h, s, l) =>
            println!("Hue: {}, saturation: {}, lightness: {}!", h, s, l),
        Color::CMY(c, m, y) =>
            println!("Cyan: {}, magenta: {}, yellow: {}!", c, m, y),
        Color::CMYK(c, m, y, k) =>
            println!("Cyan: {}, magenta: {}, yellow: {}, key (black): {}!",
                c, m, y, k),
        // Няма нужда от други разклонения,
        // защото всички случаи вече са разгледани.
    }
}

Вижте също:

#[allow(...)], Цветови модел и enum

Указатели и ref

За указателите трябва да се прави разлика между разлагане и пряк достъп1, тъй като те са различни понятия, които се ползват по различен начин от езици като C/C++.

  • При дереферирането ползваме знака *
  • При разлагане ползваме &, ref и ref mut
fn main() {
    // Обвързваме препратка към данни от тип `i32`. `&` означава, че
    // присвояваме препратка.
    let reference = &4;

    match reference {
        // Ако `reference` се сравни с `&val`, сравнението е:
        // `&i32`
        // `&val`
        // ^ Виждаме, че ако махнем `&`, то тогава стойност от тип `i32`
        // би трябвало да се присвои на `val`.
        &val => println!("Получих стойност чрез разлагане: {:?}", val),
    }

    // За да се избегне ползването на `&`, трябва да достъпим пряко, преди да сравним.
    match *reference {
        val => println!("Получих стойност чрез дерефериране: {:?}", val),
    }

    // Какво, ако нямаме препратка към данни? Препратка към данните имахме в
    // горния пример (`&4`), защото дясната страна вече беше препратка. Това тук
    // не е препратка, защото дясната част на присвояването (`3`) не е препратка.
    let _not_a_reference = 3;

    // Ръждьо предоставя ключовата дума `ref` точно с тази цел. Присвояването се
    // променя така, че се създава препратка към стойността от дясната страна и
    // тази препратка бива обвързана с променливата.
    let ref _is_a_reference = 3;

    // Съответно, ако опишем две стойности без препратки, можем да получим
    // препратки към тези стойности чрез `ref` и `ref mut`.
    let value = 5;
    let mut mut_value = 6;

    // Използвайте ключовата дума `ref`, за да създадете препратка.
    match value {
        ref r => println!("Получих препратка към стойност: {:?}", r),
    }

    // По подобен начин използвайте `ref mut`.
    match mut_value {
        ref mut m => {
            // Получихме препратка. Трябваше да достъпим стойността пряко,
            // преди да можем да добавим нещо към нея.
            *m += 10;
            println!("Добавихме 10. `mut_value`: {:?}", m);
        },
    }
}

Б. пр.

1

достъпвам пряко, дереферирам – dereference. Пряк достъп (до данните от препратката) – dereferencing. Достъпвам пряко (без препратка) – dereference

ЗАДАЧА за преводача!: да се прегледа и ако трябва да се преработи!!!

https://ciksiti.com/bg/chapters/10350-dereference-pointer-in-c--in-ubuntu-20-04

https://learn.fmi.uni-sofia.bg/pluginfile.php/50356/mod_resource/content/0/pointref.pdf

Вижте също:

Образецът ref

Структури

Подобно, една struct може да бъде разложена така:

fn main() {
    struct Foo {
        x: (u32, u32),
        y: u32,
    }

    // Променяйте стойностите в структурата, за да видите какво става
    let foo = Foo { x: (1, 2), y: 3 };

    match foo {
        Foo { x: (1, b), y } => println!("First of x is 1, b = {},  y = {} ", b, y),

        // Можете да разлагате структури и да преименувате променливи. Редът не е важен
        Foo { y: 2, x: i } => println!("y is 2, i = {:?}", i),

        // Също може да пропускате някои променливи:
        Foo { y, .. } => println!("y = {}, we don't care about x", y),
        // Това ще даде грешка: написаното не споменава полето `x`
        //Foo { y } => println!("y = {}", y),
    }

    let faa = Foo { x: (1, 2), y: 3 };

    //  Структура може да бъде разлагана и без `match` блок:
    let Foo { x : x0, y: y0 } = faa;
    println!("Outside: x0 = {x0:?}, y0 = {y0}");
}

Вижте също:

Structs

Стражи

В match може да се добавят стражи за допълнителни проверки в разклоненията за сравнение.

#[allow(dead_code)]
enum Temperature {
    Celsius(i32),
    Fahrenheit(i32),
}

fn main() {
    let temperature = Temperature::Celsius(35);
    // ^ ЗАДАЧА Пробвайте различни стойности за `temperature`

    match temperature {
        Temperature::Celsius(t) if t > 30 => println!("{}°C е над 30 по Целзий", t),
        // Частта с условието `if` ^ е страж
        Temperature::Celsius(t) => println!("{}°C е под 30 по Целзий", t),

        Temperature::Fahrenheit(t) if t > 86 => println!("{}°F е над 86 по Фаренхайт", t),
        Temperature::Fahrenheit(t) => println!("{}°F е под 86 по Фаренхайт", t),
    }
}

Забележете, че компилаторът не отчита стражите при проверка за изчерпателност на сравненията.

fn main() {
    let number: u8 = 4;

    match number {
        i if i == 0 => println!("Нула"),
        i if i > 0 => println!("По-голямо от нула"),
        // _ => unreachable!("Никога не трябва да се случва."),
        // ЗАДАЧА ^ разкоментирайте, за да се компилира.
    }
}

Вижте също:

Разнородни поредици, Броители

Обвързване

При косвения достъп до променливи (съответно сравнение чрез буквални стойности) е невъзможно в разклонението да се използва тази променлива (или стойност) без обвързване наново. match предоставя знака @ за обвързване на определени стойности с имена на променливи:

// Функция `age`, връщаща стойност от тип `u32`.
fn age() -> u32 {
    15
}

fn main() {
    println!("Кажете на каква възраст сте.");

    match age() {
        0 => println!("Все още не съм отпразнувало първия си рожден ден"),
        // можехме направо да сравним 1 ..= 12, но тогава на каква възраст би
        // било едно новородено? Затова обвързваме `n` с последователността
        // 1 ..= 12. Сега можем да кажем каква е възрастта.
        n @ 1  ..= 12 => println!("Аз съм дете на {:?} години", n),
        n @ 13 ..= 19 => println!("Аз съм младеж на {:?} години", n),
        // Нищо не е обвързано (изрично). Връщаме стойността.
        n => println!("Аз съм възрастен на {:?} години", n),
    }
}

Можете да ползвате обвързване за разлагане на варианти на броители, например Option:

fn some_number() -> Option<u32> {
    Some(42)
}

fn main() {
    match some_number() {
        // Даденият вариант `Some` съвпада, ако стойността му, обвързана с `n`,
        // е равна на 42.
        Some(n @ 42) => println!("Отговор: {}!", n),
        // Съвпадение с някое друго число.
        Some(n)      => println!("Безинтересно... {}", n),
        // Съвпадение с нещо друго (вариант `None`).
        _            => (),
    }
}

Вижте също:

функции, броители и Option

if let

В някои случаи, когато сравняваме броители, match е неудобен. Например:

#![allow(unused)]
fn main() {
// Създаваме променлива `optional` от тип `Option<i32>`
let optional = Some(7);

match optional {
    Some(i) => {
        println!("Това е наистина дълъг ред и `{:?}`", i);
        // ^ Трябват ни два отстъпа само за да извадим `i` от броителя за избор.
    },
    _ => {},
    // ^ Нали `match` е изчерпателен. Изглежда само пилеем код.
};

}

if let е по-чист в този случай и също позволява различни възможности за обработка на грешки:

fn main() {
    // Всички са от тип `Option<i32>`
    let number = Some(7);
    let letter: Option<i32> = None;
    let emoticon: Option<i32> = None;

    // Конструкцията `if let` се чете така:
    // Ако `let` разложи `number` в `Some(i)`, изпълни този блок (`{}`).
    if let Some(i) = number {
        println!("Matched {:?}!", i);
    }

    // Ако трябва да укажете какво се случва иначе, използвайте `else`:
    if let Some(i) = letter {
        println!("Matched {:?}!", i);
    } else {
        // Разлагането не успя. Влизаме в случая за обработка на грешката.
        println!("Не уцелихме число. Да пробваме с буква!");
    }

    // Предоставяме друг вид неуспех.
    let i_like_letters = false;

    if let Some(i) = emoticon {
        println!("Matched {:?}!", i);
    // Разлагането не успя. Оценяваме условието `else if`, за да видим дали
    // влизаме в другото условие:
    } else if i_like_letters {
        println!("Не уцелихме число. Да пробваме с буква!");
    } else {
    // Условието бе оценено като false. Това е разклонението по
    // подразбиране:
        println!(" Не харесвам букви. Да ползваме емотикон :)!");
    }
}

По същия начин if let може да се ползва за сравнение на всяка стойност на броител:

// Примерен броител
enum Foo {
    Bar,
    Baz,
    Qux(u32)
}

fn main() {
    // Създаваме примерни променливи
    let a = Foo::Bar;
    let b = Foo::Baz;
    let c = Foo::Qux(100);
    
    // Променливата a съвпада с Foo::Bar
    if let Foo::Bar = a {
        println!("a = foobar");
    }
    
    // Променливата b не съвпада с Foo::Bar
    // Така че на екрана не се извжда нищо
    if let Foo::Bar = b {
        println!("b = foobar");
    }
    
    // Променливата 'c' съвпада с Foo::Qux, който има стойност, подобна на Some()
    // от предишния пример
    if let Foo::Qux(value) = c {
        println!("c = {}", value);
    }

    // Обвързването чрез @ също работи с `if let`
    if let Foo::Qux(value @ 100) = c {
        println!("c = 100");
    }
}

Допълнителна полза е, че if let ни позволява да сравняваме непараметризирани варианти на броители. Това е вярно дори в случаите, когато броителят не осъществява или не е производен на1 PartialEq. В тези случаи дори ако if Foo::Bar == a не се компилира, тъй като вариантите на броителя не могат да бъдат сравнявани, if let ще си работи.

Искате ли предизвикателство? Поправете следния пример, като използвате if let:

// Този броител нарочно нито осъществява, нито извежда PartialEq.
// Ето защо сравнението Foo::Bar == a дава грешка.
enum Foo {Bar}

fn main() {
    let a = Foo::Bar;

    // Променливата a съвпада с Foo::Bar
    if Foo::Bar == a {
    // ^-- това причинява грешка по време на компилация. Използвайте `if let`.
        println!("a = foobar");
    }
}

Б. пр.

1

про-извежда, съм прозводен на – derive

Вижте също:

enum, Option и RFC

let-else

🛈 за постоянно от: rust 1.65

🛈 Можете да изберете определено издание, като компилирате по следния начин rustc --edition=2021 main.rs

С let-else дадено опровержимо сравнение1 може да успее и по този начин да обвърже променливи от обкръжаващия блока код като обикновено изявление let, или да се разклони (напр. чрез break, return, panic!), когато сравнението не успее.

use std::str::FromStr;

fn get_count_item(s: &str) -> (u64, &str) {
    let mut it = s.split(' ');
    let (Some(count_str), Some(item)) = (it.next(), it.next()) else {
        panic!("Не може да се извлече двойката 'брой-единици' от '{s}'");
    };
    let Ok(count) = u64::from_str(count_str) else {
        panic!("Не може да се извлече цялото число от '{count_str}'");
    };
    (count, item)
}

fn main() {
    assert_eq!(get_count_item("3 chairs"), (3, "chairs"));
}

Обхватът на обвързаните променливи е главното, по което let-else се различава от изразите match или if let-else. Преди въвеждането на let-else можеше да се постигне нещо подобно с повече повторения и външно let:

#![allow(unused)]
fn main() {
use std::str::FromStr;

fn get_count_item(s: &str) -> (u64, &str) {
    let mut it = s.split(' ');
    let (count_str, item) = match (it.next(), it.next()) {
        (Some(count_str), Some(item)) => (count_str, item),
        _ => panic!("Не може да се извлече двойката 'брой-единици' от '{s}'"),
    };
    let count = if let Ok(count) = u64::from_str(count_str) {
        count
    } else {
        panic!("Не може да се извлече цялото число от '{count_str}'");
    };
    (count, item)
}

assert_eq!(get_count_item("3 chairs"), (3, "chairs"));
}

Б. пр.

1

опровержимо сравнение/съвпадение – a refutable pattern. Това е сравнение, което може да не успее, например '0' ..= '9' няма да съвпадне с 'А'.

Вижте също:

option, match, if let и let-else RFC.

while let

Подобно на if let, while let може да направи неудобните последователни изявления match по-поносими. Да разгледаме следната последователност от действия, увеличаваща i:

#![allow(unused)]
fn main() {
// Правим променлива `optional` от тип `Option<i32>`
let mut optional = Some(0);

// пробваме няколко пъти.
loop {
    match optional {
        // Ако `optional` е разложимо, влизаме в блока.
        Some(i) => {
            if i > 9 {
                println!("По-голямо от 9, напускаме!");
                optional = None;
            } else {
                println!("`i` е `{:?}`. Опитай отново.", i);
                optional = Some(i + 1);
            }
            // ^ Изисква 3 отстъпа!
        },
        // Напускаме повторенията, ако разлагането не успее:
        _ => { break; }
        // ^ Защо това да е задължително? Трябва да има по-добър начин!
    }
}
}

Ако използваме while let, нещата изглеждат по-добре:

fn main() {
    // Правим променлива `optional` от тип `Option<i32>`
    let mut optional = Some(0);

    // Това се чете: "докато `let` разлага `optional` в
    // `Some(i)`, изпълняваме блока (`{…}`). Иначе прекъсваме (`{ break; }`).
    while let Some(i) = optional {
        if i > 9 {
            println!("По-голямо от 9, напускаме!");
            optional = None;
        } else {
            println!("`i` е `{:?}`. Опитай отново.", i);
            optional = Some(i + 1);
        }
        // ^ По-малко отместване вдясно и няма изрично изискване
        // за обработка на неуспешен случай.
    }
    // ^ `if let` – имаше допълнителни условия `else`/`else if`
    // `while let` – няма такива.
}

Вижте също:

enum, Option и RFC

Функции

Функциите се обявяват с ключовата дума fn. Типовете на аргументите им се отбелязват като при променливите и ако функцията връща стойност, типът на връщаната стойност се указва след стрелка ->.

Последният израз във функцията ще бъде използван като стойност за връщане. Той не трябва да завършва с ;, за да бъде ползван като върната стойност (б. пр.). Но изявлението return може да се ползва по-рано в тялото на функцията, дори насред цикли или в изявлениe if. Да пренапишем FizzBuzz като използваме функции!

// За разлика от C/C++, тук няма ограничения в реда на обявяване на функциите
fn main() {
    // Можем да използваме функцията тук, а да я опишем някъде по-късно
    fizzbuzz_to(100);
}

// Функция, връщаща булева стойност
// Както при променливите, можем да ползваме всяка азбука (б. пр.)
fn е_делимо_на(lhs: u32, rhs: u32) -> bool {
    // Краен случай, по-ранно връщане
    if rhs == 0 {
        return false;
    }

    // Това е израз, няма нужда от `return`
    // И не трябва да завършва с `;`
    lhs % rhs == 0
}

// Функции, които не връщат стойност, всъщност връщат типа unit `()`
fn fizzbuzz(n: u32) -> () {
    if е_делимо_на(n, 15) {
        println!("fizzbuzz");
    } else if е_делимо_на(n, 3) {
        println!("fizz");
    } else if е_делимо_на(n, 5) {
        println!("buzz");
    } else {
        println!("{}", n);
    }
}

// Когато функция връща `()`, връщаният тип може да не се указва в обявлението
fn fizzbuzz_to(n: u32) {
    for n in 1..=n {
        fizzbuzz(n);
    }
}

Придадени функции и методи

Някои функции се отнасят до определен тип. Те биват два вида: придадени функции и методи. Придадените функции са такива, които са обявени изобщо за типа, докато методите са функции, които се извикват с отделен обект, създаден от този тип.

struct Point {
    x: f64,
    y: f64,
}

// Блок за осъществяване. Всички придадени към структурата `Point` функции и
// методите ѝ влизат тук
impl Point {
    // Това е „придадена функция“, защото се отнася до Point.
    //
    // Придадените функции не се извикват задължително с обекти.
    // Тези функции се използват обичайно като конструктори.
    fn origin() -> Point {
        Point { x: 0.0, y: 0.0 }
    }

    // Друга придадена функция, приемаща два аргумента:
    fn new(x: f64, y: f64) -> Point {
        Point { x: x, y: y }
    }
}

struct Rectangle {
    p1: Point,
    p2: Point,
}

impl Rectangle {
    // Това е метод
    // `&self` е краткопис за `self: &Self`, където `Self` е прякор за типа на
    // извикващия обект. В този случай `Self` = `Rectangle`
    fn area(&self) -> f64 {
        // `self` предоставя достъп до полетата на структурата
        // чрез оператора точка (.).
        let Point { x: x1, y: y1 } = self.p1;
        let Point { x: x2, y: y2 } = self.p2;

        // `abs` е метод на типа `f64`, връщащ абсолютната стойност на
        // извикващия
        ((x1 - x2) * (y1 - y2)).abs()
    }

    fn perimeter(&self) -> f64 {
        // Разлагаме self.p1 и self.p2 в Point
        let Point { x: x1, y: y1 } = self.p1;
        let Point { x: x2, y: y2 } = self.p2;

        2.0 * ((x1 - x2).abs() + (y1 - y2).abs())
    }

    // Този метод изисква извикващият обект да бъде менѝм
    // Дългото изписване на `&mut self` е `self: &mut Self`
    fn translate(&mut self, x: f64, y: f64) {
        self.p1.x += x;
        self.p2.x += x;

        self.p1.y += y;
        self.p2.y += y;
    }
}

// `Pair` владее данни: две цели числа, намиращи се в динамичната памет
struct Pair(Box<i32>, Box<i32>);

impl Pair {
    // Този метод *поглъща* данните на извикващия обект
    // Дългото изписване на `self` е `self: Self`
    fn destroy(self) {
        // Разлагаме `self`
        let Pair(first, second) = self;

        println!("Pair({}, {}) бива разрушен…", first, second);

        // `first` и `second` излизат от обхват и паметта, която са заемали,
        // бива освободена.
    }
}

fn main() {
    let rectangle = Rectangle {
        // Придадените функции се извикват с двойно двоеточие
        p1: Point::origin(),
        p2: Point::new(3.0, 4.0),
    };

    // Методите се извикват с оператора точка
    // Забележете, че първият аргумент `&self` се подава неявно, сиреч
    // `rectangle.perimeter()` === `Rectangle::perimeter(&rectangle)`
    println!("Rectangle perimeter: {}", rectangle.perimeter());
    println!("Rectangle area: {}", rectangle.area());

    let mut square = Rectangle {
        p1: Point::origin(),
        p2: Point::new(1.0, 1.0),
    };

    // Грешка! `rectangle` е неменѝм, но този метод изисква менѝм обект
    //rectangle.translate(1.0, 0.0);
    // ЗАДАЧА ^ Разкоментирайте този ред

    // Добре! Меними обекти могат да извикват меними методи
    square.translate(1.0, 1.0);

    let pair = Pair(Box::new(1), Box::new(2));

    pair.destroy();

    // Грешка! Предишното извикване на `destroy` *погълна* `pair`
    //pair.destroy();
    // ЗАДАЧА ^ Разкоментирайте този ред
}

Затваряния

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

|val| val + x

Правописът и способностите на затварянията ги правят много удобни за ползване „в движение”. Извикването на затваряне е точно като извикването на функция. Само дето входните и връщаните типове могат да бъдат отгатнати, а имената на входните променливи трябва да се указват.

Други отличителни белези на затварянията са:

  • ползват се || вместо () около входните променливи.
  • незадължително ограждане на тялото с{}, когато тялото е само един израз (иначе е задължително).
  • възможността да се прихващат променливи от обкръжаващия обхват.
fn main() {
    let outer_var = 42;
    
    // Обикновена функция не може да се обръща към променливи от обкръжаващата
    // среда
    //fn function(i: i32) -> i32 { i + outer_var }
    // ЗАДАЧА: разкоментирайте горния ред и вижте грешката при компилиране.
    // Компилаторът предлага да напишете затваряне вместо функция.

    // Затварянията са безименни, тук ги обвързваме към препратки. Отбелязването
    // на входни и изходни типове е еднакво с това на функциите, но е
    // по желание. По желание е и обгръщането на тялото с `{}`, когато се
    // състои само от един израз. Тези безименни функции могат да се присвояват
    // на подходящо именувани променливи.
    let closure_annotated = |i: i32| -> i32 { i + outer_var };
    let closure_inferred  = |i     |          i + outer_var  ;

    // Извикваме затварянията.
    println!("closure_annotated: {}", closure_annotated(1));
    println!("closure_inferred: {}", closure_inferred(1));
    // След като веднъж е бил отгатнат типа на входноизходните данни на
    // затварянето, той не може да бъде отгатнат отново като друг тип.
    //println!("не може да се преизползва closure_inferred с друг тип:
    //{}", closure_inferred(42i64));
    // ЗАДАЧА: разкоментирайте двата горни реда
    //и вижте грешката при компилиране.

    // Затваряне без аргументи, връщащо стойност от тип `i32`.
    // Връщаният тип е отгатнат.
    let one = || 1;
    println!("closure returning one: {}", one());

}

Прихващане

Затварянията са много гъвкави и правят всичко възможно да си вършат работата без допълнителни указания. Това позволява прихващането на променливи да бъде нагаждано според както е необходимо – чрез преместване или чрез заемане. Затварянията могат да прихващат променливи като:

  • препратки: &T
  • меними препратки: &mut T
  • стойност: T

Променливите биват прихващани най-вече като препратки, а другояче – само по необходимост.

fn main() {
    use std::mem;
    
    let color = String::from("green");

    // Затваряне, отпечатващо `color`, което незабавно заема (`&`) `color`.
    // Заетото и затварянето се съхраняват в променливата `print`.
    // Променливата остава заета до последното извикване на `print`. 
    //
    // `println!` изисква аргументи само като неменими препратки, така че
    // не налага допълнителни ограничения.
    let print = || println!("`color`: {}", color);

    // Извикваме затварянето, използвайки заетата променлива.
    print();

    // `color` може да бъде заета отново, защото `print` държи само неменима
    // препратка към `color`. 
    let _reborrow = &color;
    print();

    // пресместване или заемане на `color` отново е разрешено след последното
    // ползване на `print`
    let _color_moved = color;


    let mut count = 0;
    // Затваряне, което да увеличи стойността на `count`, може да заеме `&mut
    // count` или `count`, но `&mut count` е по-малко ограничаващо, така че прави
    // това. Незабавно заема `count`.
    //
    // Задължително е `inc` да е `mut`, защото съхраняваме в него менима
    // препратка (`&mut`). Като извикваме затварянето, ние го променяме и
    // затова трябва да го опишем като менимо – `mut`.
    let mut inc = || {
        count += 1;
        println!("`count`: {}", count);
    };

    // Извикваме затварянето, използвайки менима заемка.
    inc();

    // Затварянето `inc` все още заема `count` като менима променлива, защото
    // се извиква отново по-късно.
    // Ако се опитаме да я заемем пак, това ще доведе до грешка.
    // let _reborrow = &count; 
    // ^ ЗАДАЧА: разкоментирайте този ред.
    inc();

    // `inc` вече не заема `&mut count`. Затова можем да я заемем без грешка.
    let _count_reborrowed = &mut count; 

    
    // Некопируем тип
    let movable = Box::new(3);

    // `mem::drop` изисква `T`, така че следващият код ще прихване `movable`
    // по стойност (ще го премести вътре в затварянето). Ако типът беше
    // копируем, щеше да се копира в затварянето, а първоизточникът да си
    // остане недокоснат.
    // Некопируем тип задължително бива преместен и затова `movable` незабавно
    // се мести в затварянето.
    let consume = || {
        println!("`movable`: {:?}", movable);
        mem::drop(movable);
    };

    // `consume` *поглъща* променливата, затова може да бъде извикана само веднъж.
    consume();
    // consume();
    // ^ ЗАДАЧА: разкоментирайте този ред.
}

Ако напишем move преди отвесните чертички, караме затварянето да овладее прихванатите променливи:

fn main() {
    // `Vec` е некопируем.
    let haystack = vec![1, 2, 3];

    let contains = move |needle| haystack.contains(needle);

    println!("{}", contains(&1));
    println!("{}", contains(&4));

    // println!("There're {} elements in vec", haystack.len());
    // ^ Ако разкоментирате горния ред, ще получите грешка при компилацията,
    // защото проверителят на заемите не позволява повторното използване на
    // променливи, след като са преместени.
    
    // Ако премахнете `move` от обявлението на затварянето, то ще заеме
    // haystack като неменима препратка, така че haystack ще може да се ползва.
    // Тогава, ако разкоментирате реда с println! по-горе, няма да има грешка.
}

Вижте също:

Box и std::mem::drop

Като входни параметри

Ръждьо избира как да прихваща променливи в движение и почти без да е нужно отбелязване на типа. Тази неопределеност не се позволява, когато пишем функции. Когато се приема затваряне като входен параметър, трябва да се укаже пълният тип на затварянето, като се използва някой от наличните вече отличители. Отличителят се определя от това, какво прави затварянето с прихванатите стойности.

Ето кои са те, по ред на намаляване на ограниченията.

  • Fn: прихванатите стойности се използват като препратки (&T)
  • FnMut: прихванатите стойности се използват като меними препратки (&mut T)
  • FnOnce: прихванатите стойности се използват като стойности (T)

Компилаторът ще прихване променливите по възможно най-малко ограничаващия начин. Това се прави променлива по променлива.

Нека разгледаме един параметър, отбелязан като FnOnce. Това указва, че затварянето би могло да прихване околните променливи като &T, &mut T, или T, но компилаторът в крайна сметка ще избере в зависимост от начина на използване на променливите в затварянето.

Това е така, защото е възможно да се случи преместване на стойността, тогава също ще е възможно заемането на всеки тип. Забележете, че обратното не е вярно. Ако параметърът е отбелязан като Fn, тогава прихващане на променливи като &mut T или T е невъзможно. Само прихващане като &T е позволено.

В следващия пример заменете използвания отличител с Fn, FnMut и FnOnce, за да видите какво се случва:

// Функция, която приема затваряне като аргумент и го извиква.
// <F> означава, че F е „параметър с обобщен тип”
fn apply<F>(f: F) where
    // Зтварянето не приема нищо и не връща нищо.
    F: FnOnce() {
    // ^ ЗАДАЧА: Променете това на `Fn` или `FnMut`.

    f();
}

// Функция, която приема затваряне и връща `i32`.
fn apply_to_3<F>(f: F) -> i32 where
    // Затварянето приема `i32` и връща `i32`.
    F: Fn(i32) -> i32 {

    f(3)
}

fn main() {
    use std::mem;

    let greeting = "здравей";
    // Некопируем тип.
    // `to_owned` създава собствени данни от заети данни
    let mut farewell = "довиждане".to_owned();

    // Прихващаме 2 променливи: `greeting` като препратка и `farewell` като
    // стойност.
    let diary = || {
        // `greeting` е препратка: изисква `Fn`.
        println!("Аз казах {}.", greeting);

        // Промяната прави `farewell` да бъде прихваната като менима препратка
        // Сега е нужен `FnMut`.
        farewell.push_str("!!!");
        println!("После изкрещях {}.", farewell);
        println!("Сега мога да поспя. zzzzz");

        // Ако извикаме `drop` ръчно, `farewell` ще бъде прихваната като
        // стойност. Сега ни трябва `FnOnce`.
        mem::drop(farewell);
    };

    // Извикваме функцията, която прилага затварянето.
    apply(diary);

    // `double` удовлетворява ограниченията на отличителя за `apply_to_3`
    let double = |x| 2 * x;

    println!("Удвоено 3: {}", apply_to_3(double));
}

Вижте също:

std::mem::drop, Fn, FnMut, Generics, where и FnOnce

Безименен тип

Затварянията прихващат променливи от околния код. Какви са последствията от това? Обърнете внимание, че когато използваме затваряне като параметър на функция, е нужно да използваме обобщения. Това е необходимо заради начина, по който се описват затварянията:

#![allow(unused)]
fn main() {
// `F` must be generic.
fn apply<F>(f: F) where
    F: FnOnce() {
    f();
}
}

Когато описваме затваряне, компилаторът неявно създава нова безименна структура, в която да съхранява прихванатите променливи, като същевременно осъществява нужната функционалност за този нов безименен тип чрез един от отличителите Fn, FnMut или FnOnce. Този тип бива присвоен на променлива, която се пази до извикване на затварянето.

Понеже този нов тип е непознат, всяко използване във функция ще изисква обобщен тип. Обаче един неограничен по тип параметър <T> ще си е все така нееднозначен и затова забранен. Така че ограничаването до един от отличителите Fn, FnMut или FnOnce (които затварянето осъществява) е достатъчно за указване на типа му.

// `F` трябва да осъществява `Fn` за затваряне, което не приема входни
// параметри и не връща нищо – точно каквото е нужно за `print`.
fn apply<F>(f: F) where
    F: Fn() {
    f();
}

fn main() {
    let x = 7;

    // Прихващаме `x` в безименен тип и осъществяваме `Fn` за него. 
    // Съхраняваме го в `print`.
    let print = || println!("{}", x);

    apply(print);
}

Вижте също:

Подробен разбор, Fn, FnMut и FnOnce

Входни функции

Понеже затварянията могат да бъдат използвани като аргументи, може би се чудите дали същото важи и за функциите. И наистина – да! Ако обявите функция, приемаща затваряне като параметър, тогава всяка функция, удовлетворяваща пределите1 на отличителя за това затваряне, може да бъде подадена като параметър.

// Описваме функция, която приема обобщен аргумент `F`, о-пределен от `Fn`,
// и го извиква като функция
fn call_me<F: Fn()>(f: F) {
    f();
}

// Описваме функция-обвивка, удовлетворяваща пределите на `Fn`
fn function() {
    println!("Аз съм функция!");
}

fn main() {
    // Описваме затваряне, удовлетворяващо пределите на `Fn`
    let closure = || println!("Аз съм затваряне!");

    call_me(closure);
    call_me(function);
}

В допълнение, отличителите (traits) Fn, FnMut и FnOnce нареждат как едно затваряне прихваща променливите от околния видим обхват.

1

предели, граници – bounds

Вижте също:

Fn, FnMut и FnOnce

Като изходни параметри

Възможно е да се приемат затваряния като входни параметри, значи би трябвало да е възможно и да връщаме затваряния. Но по определение типовете на безименните затваряния са незвестни, така че трябва да опишем типа за връщане impl ИмеНаОтличител, за да върнем затваряне.

Възможните отличители за връщане на затваряне:

  • Fn
  • FnMut
  • FnOnce

Освен това трябва да се ползва ключовата дума move, което подсказва, че всички прихващания са по стойност. Това се налага, понеже прихващанията като препратки ще бъдат изхвърлени (паметта ще бъде освободена (б. пр.)), когато функцията върне, и така биха останали недействителни препратки във върнатото затваряне.

fn create_fn() -> impl Fn() {
    let text = "Fn".to_owned();

    move || println!("Това е: {}", text)
}

fn create_fnmut() -> impl FnMut() {
    let text = "FnMut".to_owned();

    move || println!("Това е: {}", text)
}

fn create_fnonce() -> impl FnOnce() {
    let text = "FnOnce".to_owned();

    move || println!("Това е: {}", text)
}

fn main() {
    let fn_plain = create_fn();
    let mut fn_mut = create_fnmut();
    let fn_once = create_fnonce();

    fn_plain();
    fn_mut();
    fn_once();
}

Вижте също:

Fn, FnMut, Обобщения и impl ИмеНаОтличител.

Примери в std

Този раздел съдържа няколко примера от стандартната библиотека за използване на затваряния.

Iterator::any

Iterator::any е функция, на която като подадем повторител1, ще върне true, ако някой от членовете му удовлетворява твърдението2. Иначе – false. Ето неговото обявление:

pub trait Iterator {
    // Типът, върху който се извършва повторението.
    type Item;

    // `any` приема `&mut self`, значи извикващият може да бъде
    // заеман и променян, но не и поглъщан
    fn any<F>(&mut self, f: F) -> bool where
        // `FnMut` означава, че всяка прихваната променлива може най-много
        // да бъде променяна, но не и поглъщана. `Self::Item` означава, че
        // аргументите към затварянето се приемат по стойност.
        F: FnMut(Self::Item) -> bool;
}
fn main() {
    let vec1 = vec![1, 2, 3];
    let vec2 = vec![4, 5, 6];

    // `iter()` за вектори дава `&i32`.   Разлагаме към `i32`.
    println!("2 във vec1: {}", vec1.iter().any(|&x| x == 2));
    // `into_iter()` за вектори дава `i32`.    Няма нужда от разлагане.
    println!("2 във vec2: {}", vec2.into_iter().any(|x| x == 2));

    // `iter()` само заема `vec1` и членовете му, така че могат да бъдат
    // ползвани пак
    println!("vec1 len: {}", vec1.len());
    println!("Първият член от vec1 е: {}", vec1[0]);
    // `into_iter()` премества `vec2` и членовете му, та не може да се ползват
    // вече.
    // println!("Първият член от vec2 е: {}", vec2[0]);
    // println!("дължина на vec2: {}", vec2.len());
    // ЗАДАЧА: разкоментирайте двата реда горе и вижте грешките при компилиране

    let array1 = [1, 2, 3];
    let array2 = [4, 5, 6];

    // `iter()` за поредици дава `&i32`.
    println!("2 in array1: {}", array1.iter()     .any(|&x| x == 2));
    // `into_iter()` за поредици дава `i32`.
    println!("2 in array2: {}", array2.into_iter().any(|x| x == 2));
    // ^ ПОПРАВИ: да се промени кода, така че да работи за издание 2021
}

Б. пр.

1

подаване на повторител като аргумент – passing an iterator to a function. Повторителят се подава като първи аргумент, а твърдението, което е затваряне, като втори.

2

твърдение – predicate

3

давам, предавам (се), произвеждам, нося – yield. https://eurodict.com/dictionary/yield-82257

Вижте също:

std::iter::Iterator::any

Търсене чрез повторители

Iterator::find е функция , която търси чрез обхождане първата стойност, удовлетворяваща някакво условие. Ако никоя от стойностите в повторителя не удовлетворява условието, връща None. Ето обявлението ѝ:

pub trait Iterator {
    // Типът, върху който се извършва повторението.
    type Item;

    // `find` приема `&mut self`, значи извикващият може да бъде
    // заеман и променян, но не и поглъщан
    fn find<P>(&mut self, predicate: P) -> Option<Self::Item> where
        // `FnMut` означава, че всяка прихваната променлива може най-много
        // да бъде променяна, но не и поглъщана. `&Self::Item` показва, че
        // аргументите към затварянето се приемат като препратки.
        P: FnMut(&Self::Item) -> bool;
}
fn main() {
    let vec1 = vec![1, 2, 3];
    let vec2 = vec![4, 5, 6];

    //`iter()` за вектори дава `&i32`. 
    let mut iter = vec1.iter();
    // `into_iter()` за вектори дава `i32`.
    let mut into_iter = vec2.into_iter();

    // `iter()` за вектори дава `&i32`, а ние искаме да достъпим някой от
    // членовете. Значи трябва да разложим `&&i32` до `i32`
    println!("Find 2 in vec1: {:?}", iter     .find(|&&x| x == 2));
    // `into_iter()` за вектори дава `i32`, а ние искаме да достъпим някой от
    // членовете. Значи трябва да разложим `&i32` до `i32`
    println!("Find 2 in vec2: {:?}", into_iter.find(| &x| x == 2));

    let array1 = [1, 2, 3];
    let array2 = [4, 5, 6];

    // `iter()` за поредици дава `&&i32`
    println!("Find 2 in array1: {:?}", array1.iter()     .find(|&&x| x == 2));
    // `into_iter()` за поредици дава `&i32`
    println!("Find 2 in array2: {:?}", array2.into_iter().find(|&x| x == 2));
    // ПОПРАВИ: да се промени кода, така че да работи за издание 2021
}

Iterator::find ви дава препратка към члена. Но ако искате да получите мястото му, използвайте Iterator::position.

fn main() {
    let vec = vec![1, 9, 3, 3, 13, 2];

    // `iter()` за вектори дава `&i32`, а `position()` не приема препратка.
    // Значи трябва да разложим `&i32` до `i32``
    let index_of_first_even_number = vec.iter().position(|&x| x % 2 == 0);
    assert_eq!(index_of_first_even_number, Some(5));
    
    // `into_iter()` за вектори дава `i32`, а `position()`не приема препратка. 
    // Така че не трябва да разлагаме
    let index_of_first_negative_number = vec.into_iter().position(|x| x < 0);
    assert_eq!(index_of_first_negative_number, None);
}

Вижте също:

std::iter::Iterator::find

std::iter::Iterator::find_map

std::iter::Iterator::position

std::iter::Iterator::rposition

Функции от по-висок порядък

Ръждьо предоставя Функции от по-Висок Порядък (ФВП). Това са функции, които приемат една или повече функции и произвеждат нова, по-полезна функция. ФВП и ленивите повторители придават на Ръждьо по-функционалния му оттенък.

fn is_odd(n: u32) -> bool {
    n % 2 == 1
}

fn main() {
    println!("Намираме сбора от нечетните квадрати, по-малки от 1000, \
      на всички числа"
    );
    let upper = 1000;

    // Императивен (със заповеди) подход
    // Обявяваме променлива за съхраняване на сбора
    let mut acc = 0;
    // Изброяваме: 0, 1, 2, ... до безкрайност
    for n in 0.. {
        // Повдигаме числото на квадрат
        let n_squared = n * n;

        if n_squared >= upper {
            // Прекъсваме изброяването, ако сме достигнали горната граница
            break;
        } else if is_odd(n_squared) {
            // Добавяме стойност, ако числото е нечетно
            acc += n_squared;
        }
    }
    println!("Императивен подход: {}", acc);

    // Функционален подход
    let sum_of_squared_odd_numbers: u32 =
        (0..).map(|n| n * n)              // Всички естествени числа на квадрат
             .take_while(|&n_squared| n_squared < upper) // Под горната граница
             .filter(|&n_squared| is_odd(n_squared))     // Които са нечетни
             .sum();                                     // Събираме ги
    println!("Функционален подход: {}", sum_of_squared_odd_numbers);
}

Option и Iterator осъществяват немалка част от ФВП.

Разклоняващи функции1

Разклоняващите функции никога не връщат. Техният тип за връщане се отбелязва с !, което означава празен тип.

#![allow(unused)]
fn main() {
fn foo() -> ! {
    panic!("Това извикване няма да върне управлението.");
}
}

Обратно на всички други типове, от този тип не може да бъде създаден обект, защото множеството от всичките му възможни стойности е празно. Забележете, че той е различен от типа (), който има точно една празна стойност.2

Ето например следната функция връща както обикновено, макар да няма никакви данни във върнатата стойност.

fn some_fn() {
    ()
}

fn main() {
    let _a: () = some_fn();
    println!("Функцията 'some_fn()' връща и затова виждате този ред.");
}

А тази няма никога да върне управлението обратно към извикващата.

#![feature(never_type)]

fn main() {
    let x: ! = panic!("Това извикване никога не връща.");
    println!("Никога няма да видите този ред!");
}

Макар това свойство да изглежда като отвлечено понятие, в действителност е много полезно и често удобно. Главното предимство на този тип е, че може да бъде приведен към всеки друг и така да бъде ползван на места, където е нужен точно определен тип, например в разклонения на match. Това ни позволява да пишем код като следния:

fn main() {
    fn sum_odd_numbers(up_to: u32) -> u32 {
        let mut acc = 0;
        for i in 0..up_to {
            // Забележете, че типът за връщане на този израз за сравнение
            // трябва да бъде u32 заради типа на променливата "addition".
            let addition: u32 = match i%2 == 1 {
                // Променливата "i" е от тип u32, което си е съвсем наред.
                true => i,
                // От друга страна, изразът "continue" не връща u32, но отново е
                // наред, защото той никога не връща и затова не нарушава
                // изискванията за типа на израза за сравнение `match`.
                false => continue,
            };
            acc += addition;
        }
        acc
    }
    println!("Сбор на нечетните числа до 9 (не включено): {}", sum_odd_numbers(9));
}

Това е също връщаният тип на функциите, които въртят безкрайно (напр. loop {}) – като мрежовите сървъри; или функциите, които прекъсват текущия процес – например exit().

Б. пр.

1

Разклоняващи функции – diverging, защото разклоняват програмния поток, а и често се използват в изрази за сравнение match, които се разклоняват именно благодарение на типа „Никога”.

2

никога, типът, наречен Никога – the "Never" type. В книгата „Езикът за програмиране Ръст” този тип е наречен „типът Никога”, тъй като, когато се използва като тип за връщане от функция, тя никога не връща контрола на програмата към обкръжаващия я програмен код. Вижте „The Never Type that Never Returns”.

Модули

Ръждьо предоставя мощна модулна уредба1, която може да се използва за разпределяне на кода в иерархия от логически обособени единици (модули) и управление на видимостта (частна/обща)2 между тях.

Модулът е съвкупност от единици: функции, структури, отличители, блокове за осъществяване (impl) и дори други модули.

Б. пр.

1

уредба – system

2

частна/обща видимост – visibility (private/public)

Видимост

По подразбиране единиците в един модул имат частна видмост, но това може да се промени чрез използване на променителя1 pub. Само общите единици2 (обозначени с pub) могат да се достъпят отвън – от код, който е извън обхвата на модула.

// Модул с име `my_mod`
mod my_mod {
    // Единиците в модулите имат частна видимост по подразбиране
    // (не са видими отвън).
    fn private_function() {
        println!("извикахме `my_mod::private_function()`");
    }

    // Използваме променителя `pub` да отменим подразбираната видимост.
    pub fn function() {
        println!("извикахме `my_mod::function()`");
    }

    // Единиците могат да достъпват други единици в същия модул, дори частни.
    pub fn indirect_access() {
        print!("извикахме `my_mod::indirect_access()`, която извиква\n> ");
        private_function();
    }

    // Модулите могат също да бъдат вложени
    pub mod nested {
        pub fn function() {
            println!("извикахме `my_mod::nested::function()`");
        }

        #[allow(dead_code)]
        fn private_function() {
            println!("извикахме `my_mod::nested::private_function()`");
        }

        // Функции, обявени чрез изписването `pub(in път)`, са видими само в
        // подадения път. `път` трябва да бъде родителски или прародителски модул
        pub(in crate::my_mod) fn public_function_in_my_mod() {
            print!("извикахме `my_mod::nested::public_function_in_my_mod()`, \
            която извика\n> ");
            public_function_in_nested();
        }

        // Функции, обявени чрез изписването `pub(self)`, са видими само
        // в текущия модул, което е същото като да ги оставим частни.
        pub(self) fn public_function_in_nested() {
            println!("извикахме `my_mod::nested::public_function_in_nested()`");
        }

        // Функции, обявени чрез изписването `pub(super)`,
        // са видими само в родителския модул.
        pub(super) fn public_function_in_super_mod() {
            println!("извикахме \
                        `my_mod::nested::public_function_in_super_mod()`");
        }
    }

    pub fn call_public_function_in_my_mod() {
        print!("извикахме `my_mod::call_public_function_in_my_mod()`, \
                която извиква\n> ");
        nested::public_function_in_my_mod();
        print!("> ");
        nested::public_function_in_super_mod();
    }

    // pub(crate) прави функциите видими само в текущия кош.
    pub(crate) fn public_function_in_crate() {
        println!("извикахме `my_mod::public_function_in_crate()`");
    }

    // Вложените модули следват същите правила за видимост.
    mod private_nested {
        #[allow(dead_code)]
        pub fn function() {
            println!("извикахме `my_mod::private_nested::function()`");
        }

        // Частните родителски единици продължават да ограничават видимостта на
        // дъщерните единици, дори да са обявени като видими в по-широк обхват.
        #[allow(dead_code)]
        pub(crate) fn restricted_function() {
            println!("извикахме \
            `my_mod::private_nested::restricted_function()`");
        }
    }
}

fn function() {
    println!("извикахме `function()`");
}

fn main() {
    // Модулите ни позволяват да различаваме единици с еднакви имена.
    function();
    my_mod::function();

    // Общите единици, включително тези от вложените модули, могат да се
    // достъпят извън родителския модул.
    my_mod::indirect_access();
    my_mod::nested::function();
    my_mod::call_public_function_in_my_mod();

    // Единиците, обявени чрез `pub(crate)`, могат да се извикат отвсякъде
    // в същия кош.
    my_mod::public_function_in_crate();

    // Единиците, обявени чрез `pub(in path)`, могат да се извикват
    // само в указания модул
    // Грешка! Функцията `public_function_in_my_mod` е частна
    //my_mod::nested::public_function_in_my_mod();
    // ЗАДАЧА ^ Разкоментирйте този ред

    // Частните единици за даден модул не могат да се достъпят пряко,
    // дори да са вложени в общ модул:
    // Грешка! `private_function` е частна
    //my_mod::private_function();
    // ЗАДАЧА ^ Разкоментирйте този ред

    // Грешка! `private_function` е частна
    //my_mod::nested::private_function();
    // ЗАДАЧА ^ Разкоментирйте този ред

    // Грешка! `private_nested` е частен модул
    //my_mod::private_nested::function();
    // ЗАДАЧА ^ Разкоментирйте този ред

    // Грешка! `private_nested` е частен модул
    //my_mod::private_nested::restricted_function();
    // ЗАДАЧА ^ Разкоментирйте този ред
}

Б. пр.

1

променител (на видимостта) – (visibility) modifier

2

общи, общодостъпни единици (с обща видимост) – public items

Видимост на структури

Със своите полета структурите имат допълнително ниво на видимост. Видимостта по подразбиране е частна и може да бъде променена чрез pub. Тази видимост има значение само когато структурата бива достъпена извън модула, в който е описана, и е предназначена за скриване на данни (капсулиране).

mod my {
    // Обща (общодостъпна) структура с общо поле и обобщен тип `T`
    pub struct OpenBox<T> {
        pub contents: T,
    }

    // Обща (общодостъпна) структура с частно поле и обобщен тип `T`
    pub struct ClosedBox<T> {
        contents: T,
    }

    impl<T> ClosedBox<T> {
        // Общодостъпен конструктор
        pub fn new(contents: T) -> ClosedBox<T> {
            ClosedBox {
                contents: contents,
            }
        }
    }
}

fn main() {
    // Общите структури с общи полета могат да се създават както обикновено
    let open_box = my::OpenBox { contents: "public information" };

    // и техните полета могат да се достъпват.
    println!("Отворената кутия съдържа: {}", open_box.contents);

    // Общите структури с частни полета не могат да се създават
    // с използване на имена на полета.
    // Грешка! `ClosedBox` има частни полета
    //let closed_box = my::ClosedBox { contents: "тайни данни" };
    // ЗАДАЧА ^ Разкоментирйте този ред

    // Все пак структури с частни полета може да се създават с помощта на
    // общодостъпни конструктори,
    let _closed_box = my::ClosedBox::new("classified information");

    // а частните полета на обща структура не може да се достъпват.
    // Грешка! Полето `contents` е частно
    //println!("Затворената кутия съдържа: {}", _closed_box.contents);
    // ЗАДАЧА ^ Разкоментирйте този ред
}

Вижте също:

Обобщения и методи

Обявлението use

Обявлението use може да бъде използвано за обвързване на пълен път с ново име за по-лесен достъп. Често се използва така:

use crate::deeply::nested::{
    my_first_function,
    my_second_function,
    AndATraitType
};

fn main() {
    my_first_function();
}

Може да използвате ключовата дума as, за да обвържете внасяния1 с нови имена:

// Обвързваме пътя `deeply::nested::function` с `other_function`.
use deeply::nested::function as other_function;

fn function() {
    println!("извикахме `function()`");
}

mod deeply {
    pub mod nested {
        pub fn function() {
            println!("извикахме `deeply::nested::function()`");
        }
    }
}

fn main() {
    // Улеснен достъп до `deeply::nested::function`
    other_function();

    println!("Влизане в блока");
    {
        // Това е същото като `use deeply::nested::function as function`.
        // Тази `function()` ще засенчи другата.
        use crate::deeply::nested::function;

        // Обвързвянията от вида `use` имат местен обхват. В този случай
        // засенчаването на `function()` е само в този блок.
        function();

        println!("Напускане на блока");
    }

    function();
}

Б. пр.

1

внасяне – import. Внасяне (на имена (модули и функции)) в текущия обхват (код или файл).

super и self

Ключовите думи super и self могат да се ползват в пътя, за да се премахнат неясноти при достъпа до единици от даден модул и да се предотврати ненужно точно изписване на пътища.

fn function() {
    println!("извикахме `function()`");
}

mod cool {
    pub fn function() {
        println!("извикахме `cool::function()`");
    }
}

mod my {
    fn function() {
        println!("извикахме `my::function()`");
    }
    
    mod cool {
        pub fn function() {
            println!("извикахме `my::cool::function()`");
        }
    }
    
    pub fn indirect_call() {
        // Да достъпим всички функции от този обхват с име `function`!
        print!("извикахме `my::indirect_call()`, that\n> ");
        
        // Ключовата дума `self` се отнася до текущия модул – в този случай `my`.
        // Извикването `self::function()` и извикването `function()` са едно и
        // също, защото се отнасят до една и съща функция.
        self::function();
        function();
        
        // Можем да ползваме `self` и за да достъпим друг модул в `my`:
        self::cool::function();
        
        // Ключовата дума `super` се отнася до родителския обхват
        // (извън модула `my`).
        super::function();
        
        // Това ще създаде прякор root_function за `cool::function` в обхвата
        // на целия *кош*. В този случай обхватът на коша е най-външният обхват.
        {
            use crate::cool::function as root_function;
            root_function();
        }
    }
}

fn main() {
    my::indirect_call();
}

Иерархия на файловете

Модулите могат да бъдат организирани във файлова иерархия. Да разбием примера от раздел Видимост във файлове:

$ tree .
.
├── my
│   ├── inaccessible.rs
│   └── nested.rs
├── my.rs
└── split.rs

В split.rs:

// Това обявление ще търси файл с име `my.rs` и ще вмъкне неговото съдържание в
// модул с име `my` в този обхват
mod my;

fn function() {
    println!("извикахме `function()`");
}

fn main() {
    my::function();

    function();

    my::indirect_access();

    my::nested::function();
}

В my.rs:

// По подобен начин `mod inaccessible` и `mod nested` ще намерят файловете
// `nested.rs` и `inaccessible.rs` и ще ги вмъкнат тук в съответните им модули
mod inaccessible;
pub mod nested;

pub fn function() {
    println!("извикахме `my::function()`");
}

fn private_function() {
    println!("извикахме `my::private_function()`");
}

pub fn indirect_access() {
    print!("извикахме `my::indirect_access()`, that\n> ");

    private_function();
}

В my/nested.rs:

pub fn function() {
    println!("извикахме `my::nested::function()`");
}

#[allow(dead_code)]
fn private_function() {
    println!("извикахме `my::nested::private_function()`");
}

В my/inaccessible.rs:

#[allow(dead_code)]
pub fn public_function() {
    println!("извикахме `my::inaccessible::public_function()`");
}

Да проверим дали всичко работи както преди:

$ rustc split.rs && ./split
called `my::function()`
called `function()`
called `my::indirect_access()`, that
> called `my::private_function()`
called `my::nested::function()`

Кошове

Кошът1 е компилационна единица в Ръждьо. Когато изпълните на командния ред rustc some_file.rs, some_file.rs се смята за главния файл в коша. Ако some_file.rs има в себе си обявление mod, съдържанието на файловете в модула ще бъдат вмъкнати на местата, където са обявленията mod, преди компилаторът да започне работа. Иначе казано, модулите не се компилират поотделно. Само кошове биват компилирани.

Кошът може да бъде компилиран като изпълним файл или като библиотека. По подразбиране rustc ще произведе изпълним файл от коша. Това поведение може да бъде променено, като се подаде флага --crate-type със стойност lib.

Б. пр.

1

кошове – crates

Създаване на библиотека

Да създадем библиотека и после да видим как да я свържем с друг кош.

В rary.rs:

pub fn public_function() {
    println!("called rary's `public_function()`");
}

fn private_function() {
    println!("called rary's `private_function()`");
}

pub fn indirect_access() {
    print!("called rary's `indirect_access()`, that\n> ");

    private_function();
}
$ rustc --crate-type=lib rary.rs
$ ls lib*
library.rlib

Библиотеките получават представка "lib" пред името и по подразбиране се именуват на главния файл за коша. Това име може да бъде променено, като се подаде на rustc флага --crate-name или като се използва атрибута crate_name.

Използване на библиотека

За да свържете кош с тази нова библиотека, може да ползвате флага за rustc --extern. Всичко от библиотеката ще бъде внесено с име на модул, съответстващо с името на библиотеката. Този модул се държи като всеки друг модул.

// extern crate rary; 
// Може да се изисква за издания на Ръждьо 2015 или по-ранни

fn main() {
    rary::public_function();

    // Грешка! `private_function` е частна
    //rary::private_function();

    rary::indirect_access();
}
# library.rlib е пътят до компилираната библиотека. Тук предполагаме,
# че се намира в същата директория:
$ rustc executable.rs --extern rary=library.rlib && ./executable 
called rary's `public_function()`
called rary's `indirect_access()`, that
> called rary's `private_function()`

Cargo

cargo1 е представителното2 средство на Ръждьо за управление на пакети. Има множество наистина полезни качества за подобряване на кода и улеснява работата на разработчика. Ето някои от възможностите му:

  • Управление на зависмости и свързаност с crates.io (представителният регистър за пакети на Ръждьо)
  • Поддръжка на тестове
  • Поддръжка на проверки за бързодействие3

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

Б. пр.

1

товар, карго – cargo

2

представителното – official

3

проверки за бързодействие – benchmarks

Зависимости

Повечето програми зависят от някакви библиотеки. Ако някога сте управлявали зависимости на ръка, знаете каква мъка е. За щастие Ръждьо идва стандартно с cargo! cargo може да управлява зависимостите в проекта.

За да създадете нов проект на Ръждьо, изпълнете на командния ред:

# Изпълним
cargo new foo

# Библиотека
cargo new --lib bar

До края на раздела ще приемем, че правим изпълним файл, но знайте, че е същото като за библиотека.

След изпълнението на горните команди файловото дърво на проекта изглежда така:

.
├── bar
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
└── foo
    ├── Cargo.toml
    └── src
        └── main.rs

main.rs е главният файл с изходен код за новия ви проект foo – нищо особено дотук. Cargo.toml е файлът с настройки за cargo за този проект. Ако погледнете в него, ще видите нещо такова:

[package]
name = "foo"
version = "0.1.0"
authors = ["mark"]

[dependencies]

Полето name под [package] определя името на проекта. То се ползва от crates.io, ако обнародвате коша (повече по-късно). Това е и името на двоичния изпълним файл след компилация.

Полето version е версията на коша. Използват се Значещи версии1.

Полето authorsе списък с автори и се ползва, когато кошът се обнародва.

Разделът [dependencies] е за добавяне на зависимости към проекта.

Нека предположим, че искаме програмата ни да има отлична външност за командния ред2. Можете да намерите много чудесни пакети на crates.io (представителния3 регистър за пакети на Ръждьо). Чест избор е clap. По време на това писание последната версия на clap е 2.27.1. За да добавим зависимост към нашата програма, просто добавяме следното в Cargo.toml под [dependencies]: clap = "2.27.1". И това е! Можете да използвате clap.

cargo поддържа и други типове зависимости. Ето малък пример:

[package]
name = "foo"
version = "0.1.0"
authors = ["mark"]

[dependencies]
clap = "2.27.1" # от crates.io
rand = { git = "https://github.com/rust-lang-nursery/rand" } # от хранилището
bar = { path = "../bar" } # от файлов път на сметалото ви

cargo е повече от управление на зависимости. Всички възможни настройки са изброени в спецификацията на формата на Cargo.toml.

За да построим нашия проект, можем да изпълним cargo build където и да е в папката на проекта (включително и подпапките). Може също да изпълним cargo run, за да построим и изпълним произведения двоичен файл. Забележете, че тези команди ще разрешат зависимостите, ще изтеглят кошовете, ако е необходимо, и ще построят всичко, включително и вашия кош. Ще се построи отново само каквото е нужно, подобно на make.

Voila! Това е всичко!

Б. пр.

1

Значещи версии – semantic versions

2

външност, интерфейс – interface. външност за командния ред (ВКР) – command line interface (CLI). Външността е присъщо свойство на единиците да си взаимодействат с други единици код. В други езици (Java до версия 8) външностите не осъществяват никакво действие. Те са само „дрешки“, който даден клас трябва да си „ушие“ сам, за да може да общува с обекти на други класове. В Ръждьо пък типовете стават производни на отличителите и така могат просто да „облекат” някои готови „дрешки” (Debug), а други да си „ушият”, като ги осъществят (Display). Отличителите в Ръждьо са по-скоро като абстрактните класове в Java. Но в Ръждьо, можете да извеждате (derive) повече от един отличител.

3

представителен (официален) – official

Уговорки1

В предишния раздел видяхме следната иерархия от папки:

foo
├── Cargo.toml
└── src
    └── main.rs

Да предположим, че искаме да имаме два изпълними файла в проекта. Тогава какво?

Оказва се, че cargo поддържа това. Името по подразбиране за главния файл е main.rs, както видяхме по-рано, но можем да сложим допълнителни изпълними файлове в папка bin/

foo
├── Cargo.toml
└── src
    ├── main.rs
    └── bin
        └── my_other_bin.rs

За да кажем на cargo да компилира или изпълни само този двоичен файл, просто му подаваме флага --bin my_other_bin, където my_other_bin е името на файла, с който искаме да работим.

Освен да изпълнява двоични файлове, cargo може да изпълнява също примери, тестове и проверки за бързодействие.

В следващия раздел ще разгледаме по-отблизо тестовете.

Б. пр.

1

уговорки, конвенции – conventions

Тестове

Както знаем, тестването е неразделна част от всеки софтуер. Ръждьо има първокласна поддръжка за единични (unit) и интеграционни тестове. Вижте глава 11 от „The Rust Programming Language”.

Там е описано как се пишат тестове. Можем да сложим единичните тестове в модулите, които те тестват, а интеграционните в отделна директория tests/:

foo
├── Cargo.toml
├── src
│   └── main.rs
│   └── lib.rs
└── tests
    ├── my_test.rs
    └── my_other_test.rs

Всеки файл в tests е отделен интеграционен тест, сиреч тест, който проверява библиотеката така, сякаш тя е извикана от зависим от нея кош.

Глава Тестване разглежда трите вида тестване: Единично, Документално и Интеграционно.

cargo предоставя лесен начин за изпълняване на всички тестове!

$ cargo test

Ще видите да се извежда следното на екрана:

$ cargo test
   Compiling blah v0.1.0 (file:///nobackup/blah)
    Finished dev [unoptimized + debuginfo] target(s) in 0.89 secs
     Running target/debug/deps/blah-d3b32b97275ec472

running 3 tests
test test_bar ... ok
test test_baz ... ok
test test_foo_bar ... ok
test test_foo ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Можете също така да пускате тестове, чието име съвпада с даден образец:

$ cargo test test_foo
$ cargo test test_foo
   Compiling blah v0.1.0 (file:///nobackup/blah)
    Finished dev [unoptimized + debuginfo] target(s) in 0.35 secs
     Running target/debug/deps/blah-d3b32b97275ec472

running 2 tests
test test_foo ... ok
test test_foo_bar ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out

Имайте предвид следното: Cargo може да изпълнява няколко теста едновременно, така че се уверете, че те не си съперничат по някакъв начин.

Един пример как едновременността създава проблеми е когато два теста пишат в един и същи файл, както по-долу:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    // Внасяме нужните модули
    use std::fs::OpenOptions;
    use std::io::Write;

    // Този тест пише във файл
    #[test]
    fn test_file() {
        // Отваря файла ferris.txt или създава нов, ако не съществува.
        let mut file = OpenOptions::new()
            .append(true)
            .create(true)
            .open("ferris.txt")
            .expect("Failed to open ferris.txt");

        // Print "Ferris" 5 times.
        for _ in 0..5 {
            file.write_all("Ferris\n".as_bytes())
                .expect("Could not write to ferris.txt");
        }
    }

    // Този тест се опитва да пише в същия файл
    #[test]
    fn test_file_also() {
        // Отваря файла ferris.txt или създава нов, ако не съществува.
        let mut file = OpenOptions::new()
            .append(true)
            .create(true)
            .open("ferris.txt")
            .expect("Failed to open ferris.txt");

        // Print "Corro" 5 times.
        for _ in 0..5 {
            file.write_all("Corro\n".as_bytes())
                .expect("Could not write to ferris.txt");
        }
    }
}
}

Макар че намерението ни е да получим следното:

$ cat ferris.txt
Ferris
Ferris
Ferris
Ferris
Ferris
Corro
Corro
Corro
Corro
Corro

Това, което всъщност се въвежда във ferris.txt, е:

$ cargo test test_file
Corro
Ferris
Corro
Ferris
Corro
Ferris
Corro
Ferris
Corro
Ferris

Скриптове за построяване

Понякога обикновеното построяване с cargo не стига. Може би е нужна някаква предварителна подготовка, преди cargo да може да компилира всичко успешно. Например създаване на обособен програмен код или нещо трябва да се компилира отделно. За справяне с такива случаи Cargo може да изпълни написани от вас скриптове за построяване.

За да добавите такъв скрипт към вашия пакет, можете да го укажете в Cargo.toml както следва:

[package]
...
build = "build.rs"

Иначе Cargo по подразбиране ще търси скрипт с име build.rs в директорията на проекта.

Как се ползва скрипт за построяване

Скриптът е просто файл с код на Ръждьо, който ще бъде компилиран и извикан преди всичко друго в пакета. Сиреч, може да бъде използван за създаване на нужните предпоставки за успешно построяване на вашия кош.

Cargo предоставя входни данни на скрипта чрез променливи на обкръжението. Те са описани в „The Cargo Book” (Environment variables Cargo sets for crates).

Скриптът предоставя изходни данни чрез стандартния изход (stdout). Всички отпечатани редове биват записани в target/debug/build/<pkg>/output. Редовете, започващи с cargo:, ще бъдат ползвани пряко от Cargo и така можете да задавате параметри за компилирането на пакета.

За повече подробности и примери прегледайте Cargo specification.

Атрибути

Атрибутът представлява метаданни, приложени към някой модул, кош или друга единица. Тези метаданни могат да бъдат ползвани за:

Когато атрибутите са приложими за целия кош, те се пишат така: #![crate_attribute], а когато се прилагат към модул или друга единица, се пишат така: #[item_attribute] (забележете, че няма удивителна !).

Атрибутите могат да приемат аргументи по различни начини:

  • #[attribute = "value"]
  • #[attribute(key = "value")]
  • #[attribute(value)]

Атрибутите могат да имат множество стойности и могат да бъдат на няколко реда:

#[attribute(value, value2)]


#[attribute(value, value2, value3,
            value4, value5)]

dead_code

Кокмпилаторът предоставя статични проверки за „мъртъв код” – dead_code (lint), които ни предупреждават за неизползвани функции. Можем да използваме атрибут, за да изключим предупреждението.

fn used_function() {}

// `#[allow(dead_code)]` е атрибут, който изключва проверката за мъртъв код
#[allow(dead_code)]
fn unused_function() {}

fn noisy_unused_function() {}
// ПОПРАВИ ^ Добавете атрибут, за да спрете предупреждението

fn main() {
    used_function();
}

Забележете, че в истински програми неизползваният код би трябвало да се премахва. В тези примери ние разрешаваме такъв код на места поради естеството на примерите.

Crates

Атрибутът crate_type казва на компилатора дали един кош е изпълним файл или библиотека, и дори какъв тип библиотека. А атрибутът crate_name задава името на коша.

Важно е да отбележим обаче, че и двата атрибута не влияят на компилирането, когато използваме Cargo. И понеже Cargo се ползва в повечето проекти на Ръждьо, това означава, че тези атрибути рядко се срещат в истински проекти.

В lib.rs

// Този кош е библиотека
#![crate_type = "lib"]
// Библиотеката се казва "rary"
#![crate_name = "rary"]

pub fn public_function() {
    println!("извикахме rary's `public_function()`");
}

fn private_function() {
    println!("извикахме rary's `private_function()`");
}

pub fn indirect_access() {
    print!("извикахме rary's `indirect_access()`, that\n> ");
    private_function();
}

Когато ползваме атрибута crate_type, вече няма нужда да подаваме флага --crate-type на rustc.

$ rustc lib.rs
$ ls lib*
library.rlib

cfg

Условни проверки на настройките на компилиране са възможни чрез два оператора:

  • атрибутът cfg: #[cfg(...)]
  • макросът cfg!: cfg!(...) при условни изрази

Докато първият включва условна компилация, вторият условно се оценява като буквалите1 „да” (true) или „не” (false), което позволява да се правят проверки по време на изпълнение. И двете единици код ползват един и същ правопис за приемане на аргументи.

За разлика от #[cfg], cfg! не премахва код, а само се оценява като „да” или „не”. Вички блокове в един израз if/else трябва да работят, когато се ползва cfg!, независимо как ще бъде оценен cfg!.

// Тази функция се компилира само ако целевата ОУ е Линукс
#[cfg(target_os = "linux")]
fn are_you_on_linux() {
    println!("Работите в Линукс!");
}

// А тази функция се компилира само ако целевата ОУ *не е* Линукс
#[cfg(not(target_os = "linux"))]
fn are_you_on_linux() {
    println!("*Не* работите в Линукс!");
}

fn main() {
    are_you_on_linux();

    println!("Сигурни ли сте?");
    if cfg!(target_os = "linux") {
        println!("Да. Определено е Линукс!");
    } else {
        println!("Да. Определено *не е* Линукс!");
    }
}

Б. пр.

1

буквал (буквална стойност) – literal (literal value)

Вижте също:

Справочника, документацията за cfg! и macro_rules!.

Собствени условия

Някои условия като target_os се предоставят от rustc, но вашите собствени условия задължително се подават на rustc чрез флага `--cfg.

#[cfg(some_condition)]
fn conditional_function() {
    println!("condition met!");
}

fn main() {
    conditional_function();
}

Изпълнете долната команда и вижте какво се случва, ако не подадете флага със съответната стойност.

С потрбителски флаг cfg:

$ rustc --cfg some_condition custom.rs && ./custom
condition met!

Обобщения

Обобщенията1 са начин за обобщаване на типове и функционалност за по-широк кръг от случаи. Това е особено полезно за намаляване на повторенията в програмния код, но може да доведе до много усложнен правопис. За да се направи част от кода обобщена, е необходимо грижливо да се укаже за кои типове се отнася обобщеният код. Най-простата и най-често срещана употреба е за обобщение на параметри за типове2.

Описваме даден параметър за тип като обобщен, като ограждаме с ъглови скоби типовете, за които е в сила обобщеният тип. Типовете обикновено започват с главна буква и ако се състоят от повече от една дума, думите са слети, а всяка следваща започва с главна буква. Такова именоване е познато като КамилскиВид: <Aaa, Bbb, ДругТип...>. Обобщените типове за параметри обикновено се представят така: <T>. В Ръждьо „обобщена” е също всяка единица, приемаща един или повече обобщени типа <T>. Всеки тип, указан като обобщен, е обобщен параметър за тип, а всеки друг е точен3 (необобщен).

Например описваме обобщена функция, именувана foo, която приема аргумент T от всякакъв тип:

fn foo<T>(arg: T) { ... }

Понеже T е указан като обобщен параметър за тип чрез <T>, той се смята обобщен, когато се ползва така (arg: T). Това важи дори T да е бил описан преди това като struct.

Този пример показва част от правописа в действие:

// Точен тип `A`.
struct A;

// При описване на типа `Single` първото използване на `A` не се предхожда от `<A>`.
// Това означава, че `Single` е точен тип, а `A` е описан по-горе.
struct Single(A);
//            ^ Тук е първото използване от `Single на типа `A`.

// Тук `<T>` предхожда първата употреба на `T`, значи `SingleGen` е обобщен тип.
// Понеже типовият параметър `T` е обобщен, то би могъл да бъде всичко,
// включително точния тип `A`, описан горе.
struct SingleGen<T>(T);

fn main() {
    // `Single` е точен и изрично приема `A`.
    let _s = Single(A);
    
    // Създаваме променлива `_char` от тип `SingleGen<char>`
    // и ѝ даваме стойност `SingleGen('a')`.
    // Тук `SingleGen` има изрично указан типов параметър.
    let _char: SingleGen<char> = SingleGen('a');

    // `SingleGen` може също да има неявно указан типов параметър:
    let _t    = SingleGen(A); // Uses `A` defined at the top.
    let _i32  = SingleGen(6); // Uses `i32`.
    let _char = SingleGen('a'); // Uses `char`.
}

Б. пр.

1

обобщения – generics

2

параметър за тип, типов параметър – <ИмеНаТип> – type parameter

3

точен, даден, определен; конкретен – concrete

Вижте също:

structs

Функции

Същият набор от правила може да бъде приложен за функции: типът T става обобщен, ако е предшестван от <T>.

Използването на обобщени функции понякога изисква да се указват типови параметри. Такъв може да е случаят, ако функцията е извикана, когато връщаният тип е обобщен, или ако компилаторът няма достатъчно сведения, за да отгатне нужните типови параметри.

Извикване на функция с изрично указани параметри за тип изглежда така: fun::<A, B, ...>().

struct A;          // Точен тип `A`.
struct S(A);       // Точен тип `S`.
struct SGen<T>(T); // Обобщен тип `SGen`.

// Всички следващи функции *овладяват* подадената им променлива.
// След това променливата незабавно излиза от областта на видимост и бива освободена.

// Описваме функция `reg_fn`, приемаща аргумент `_s` от тип `S`.
// Тук никъде няма `<T>`, значи това не е обобщена функция.
fn reg_fn(_s: S) {}

// Описваме функция `gen_spec_t`, приемаща аргумент `_s` от тип `SGen<T>`.
// Тя има изрично даден праметър за тип `A`, но понеже `A` не е бил указан като
// обобщен параметър за тип за `gen_spec_t`, тя не е обобщена.
fn gen_spec_t(_s: SGen<A>) {}

// Описваме функция `gen_spec_i32`, приемаща аргумент `_s` от тип `SGen<i32>`.
// Тя има изрично даден праметър за тип `i32`, който е точен тип.
// Понеже `i32` не е обобщен тип, тази функция също не е обобщена.
fn gen_spec_i32(_s: SGen<i32>) {}

// Описваме функция `generic`, приемаща аргумент `_s` от тип `SGen<T>`.
// Понеже `SGen<T>` се предхожда от `<T>`, тази функция е обобщена чрез `T`.
fn generic<T>(_s: SGen<T>) {}

fn main() {
    // Използваме необобщените функции
    reg_fn(S(A));          // Точно определен тип.
    gen_spec_t(SGen(A));   // Неявно указан типов параметър `A`.
    gen_spec_i32(SGen(6)); // Неявно указан типов параметър `i32`.

    // Изрично указан типов параметър `char` за `generic()`.
    generic::<char>(SGen('a'));

    // Неявно указан типов параметър `char` за `generic()`.
    generic(SGen('c'));
}

Б. пр.

овладявам – take ownership

Вижте също:

functions и structs

Осъществяване

Подобно на функциите осъществяванията изискват внимание, за да останат обобщени.

#![allow(unused)]
fn main() {
struct S; // Точен тип`S`
struct GenericVal<T>(T); // Обобщен тип `GenericVal`

// Осъществяваме GenericVal, където изрично указваме типовите параметри:
impl GenericVal<f32> {} // Указваме `f32`
impl GenericVal<S> {} // Указваме `S`, описан по-горе

// `<T>` Трябва да предхожда типа, за да остане обобщен GenericVal
impl<T> GenericVal<T> {}
}
struct Val {
    val: f64,
}

struct GenVal<T> {
    gen_val: T,
}

// Осъществяваме Val
impl Val {
    fn value(&self) -> &f64 {
        &self.val
    }
}

// Осъществяваме GenVal за обобщен тип `T`
impl<T> GenVal<T> {
    fn value(&self) -> &T {
        &self.gen_val
    }
}

fn main() {
    let x = Val { val: 3.0 };
    let y = GenVal { gen_val: 3i32 };

    println!("{}, {}", x.value(), y.value());
}

Вижте също:

функции, връщащи препратки, impl и struct

Отличители

Разбира се, отличителите също могат да бъдат обобщени. Тук описваме един, който осъществява наново отличителя Drop като обобщен метод на метода drop и като входен параметър.

// Некопируеми типове.
struct Empty;
struct Null;

// Обобщен отличител за `T`.
trait DoubleDrop<T> {
    // Обявяваме метод за извикващия тип, който приема допълнителен единичен
    // параметър `T` и не прави нищо с него.
    fn double_drop(self, _: T);
}

// Осъществяваме `DoubleDrop<T>` за всеки обобщен параметър `T` и извикващ `U`.
impl<T, U> DoubleDrop<T> for U {
    // Този метод овладява и двата подадени аргумента, като така освобождава
    // паметта и за двата.
    fn double_drop(self, _: T) {}
}

fn main() {
    let empty = Empty;
    let null  = Null;

    // Освобождаваме `empty` и `null`.
    empty.double_drop(null);

    //empty;
    //null;
    // ^ ЗАДАЧА: Разкоментирйте двата реда.
}

Вижте също:

Drop, struct и Отличители

Предели

Когато работим с обобщения, често се налага параметрите за типове да ползват предели (bounds), за да о-пределят каква функционалност осъществява даденият тип. Следващият пример използва отличителя Display за извеждане на стойност на екрана и е задължително T да бъде ограничен (о-пределен) от Display; сиреч, T трябва да осъществи Display.

// Обявяваме функция `printer`, която приема обобщен тип `T`, който трябва да е
// осъществил отличителя `Display`.
fn printer<T: Display>(t: T) {
    println!("{}", t);
}

Пределите ограничават обобщението до типове, които отговарят на ограниченията, иначе казано, които са в пределите на нужната функционалност. Ето:

struct S<T: Display>(T);

// Грешка! `Vec<T>` не осъществява `Display`. Това уточнение ще се провали.
let s = S(vec![1]);

Друго последствие от о-пределянето е, че обобщените обекти могат да извикват методите на отличителите, упоменати в пределите. Например:

// Отличител, който осъществява означението: `{:?}`.
use std::fmt::Debug;

trait HasArea {
    fn area(&self) -> f64;
}

impl HasArea for Rectangle {
    fn area(&self) -> f64 { self.length * self.height }
}

#[derive(Debug)]
struct Rectangle { length: f64, height: f64 }
#[allow(dead_code)]
struct Triangle  { length: f64, height: f64 }

// Обобщеният тип `T` трябва да осъществява `Debug`. Независимо какъв е типът,
// следният код ще работи.
fn print_debug<T: Debug>(t: &T) {
    println!("{:?}", t);
}

// `T` трябва да осъществява `HasArea`. Всеки тип, който е в пределите, може да
// извика функцията на `HasArea` `area`.
fn area<T: HasArea>(t: &T) -> f64 { t.area() }

fn main() {
    let rectangle = Rectangle { length: 3.0, height: 4.0 };
    let _triangle = Triangle  { length: 3.0, height: 4.0 };

    print_debug(&rectangle);
    println!("Area: {}", area(&rectangle));

    //print_debug(&_triangle);
    //println!("Area: {}", area(&_triangle));
    // ^ ЗАДАЧА: Разкоментирайте горните редове.
    // | Грешка: Не осъществява ни `Debug`, ни `HasArea`. 
}

Забележете, че в някои случаи за по-голяма изразителност или четимост могат да се изполват условия where за налагане на предели.

Вижте също:

std::fmt, structs и отличители

Проверка: празни предели

Следствие от начина на работа на пределите е, че дори даден отличител да не включва никаква функционалност, пак може да бъде използван като предел.Eq и Copy са такива примери от стандартната библиотека.

Така отличителят (trait) е просто отличителна черта (trait), по която отличаваме два иначе нямащи нищо общо типа, и тази черта се явява о-предел-ител за тези два типа (б.пр.).

struct Cardinal;
struct BlueJay;
struct Turkey;

trait Red {}
trait Blue {}

impl Red for Cardinal {}
impl Blue for BlueJay {}

// Тези функции работят само за типове, осъществяващи тези отличители. Това,
// че отличителите са празни, няма никакво значение. 
fn red<T: Red>(_: &T)   -> &'static str { "red" }
fn blue<T: Blue>(_: &T) -> &'static str { "blue" }

fn main() {
    let cardinal = Cardinal;
    let blue_jay = BlueJay;
    let _turkey   = Turkey;

    // `red()` няма да работи за обект BlueJay заради пределите
    println!("A cardinal is {}", red(&cardinal));
    println!("A blue jay is {}", blue(&blue_jay));
    //println!("A turkey is {}", red(&_turkey));
    // ^ ЗАДАЧА: Разкоментирйте този ред.
}

Вижте също:

std::cmp::Eq, std::marker::Copy и Отличители

Множество предели

Повече предели за отделен тип може да се приложат чрез знака +. Обикновено различните типове се отделят със ,.

use std::fmt::{Debug, Display};

fn compare_prints<T: Debug + Display>(t: &T) {
    println!("Debug: `{:?}`", t);
    println!("Display: `{}`", t);
}

fn compare_types<T: Debug, U: Debug>(t: &T, u: &U) {
    println!("t: `{:?}`", t);
    println!("u: `{:?}`", u);
}

fn main() {
    let string = "words";
    let array = [1, 2, 3];
    let vec = vec![1, 2, 3];

    compare_prints(&string);
    //compare_prints(&array);
    // ^ ЗАДАЧА: Разкоментирайте горния ред.

    compare_types(&array, &vec);
}

Вижте също:

std::fmt и отличители

Условия „където” (where)

Предел може да бъде описан също и чрез условие where1 непосредствено преди отварящата фигурна скоба {, а не само при първото споменаване на типа. Освен това условията where могат да налагат предели на произволни типове, а не само на параметри за типове.

Ето някои случаи, при които условието where е полезно:

  • Когато обобщени типове и предели се указват поотделно, така кодът е по-ясен:
impl <A: TraitB + TraitC, D: TraitE + TraitF> MyTrait<A, D> for YourType {}

// Изразяване на предели чрез условие `where`
impl <A, D> MyTrait<A, D> for YourType where
    A: TraitB + TraitC,
    D: TraitE + TraitF {}
  • Условието where е по-изразително, сравнено с обичайния правопис. В този пример блокът за осъществяване (impl) не може да бъде изразен направо без условие where:
use std::fmt::Debug;

trait PrintInOption {
    fn print_in_option(self);
}

// Тъй като в противен случай би трябвало да изразим това като `T: Debug`
// или да използваме друг непряк подход, това изисква условие `where`: 
impl<T> PrintInOption for T where
    Option<T>: Debug {
    // Искаме `Option<T>: Debug` да бъде нашият предел, защото това отпечатваме
    // Иначе ще се окаже, че ползваме грешен предел.
    fn print_in_option(self) {
        println!("{:?}", Some(self));
    }
}

fn main() {
    let vec = vec![1, 2, 3];

    vec.print_in_option();
}

1 условие „където” – where clause (б.пр.)

Вижте също:

RFC, Структури и Отличители

Изразът за нов тип

Изразът за нов тип1 дава гаранция по време на компилация, че на програмата е подаден правилният тип за стойност.

Да речем, че имаме функция за проверка на възраст, която проверява възрастта в години. На нея трябва да ѝ се подаде стойност от тип Years.

struct Years(i64);

struct Days(i64);

impl Years {
    pub fn to_days(&self) -> Days {
        Days(self.0 * 365)
    }
}


impl Days {
    /// изрязва непълни години
    pub fn to_years(&self) -> Years {
        Years(self.0 / 365)
    }
}

fn old_enough(age: &Years) -> bool {
    age.0 >= 18
}

fn main() {
    let age = Years(5);
    let age_days = age.to_days();
    println!("Old enough {}", old_enough(&age));
    println!("Old enough {}", old_enough(&age_days.to_years()));
    // println!("Old enough {}", old_enough(&age_days));
}

Разкоментирайте последното изявлениe println!, за да видите, че предоставеният тип трябва да бъде Years.

За да получите стойността на „новия тип” като основен тип, може да ползвате разнородна поредица или разлагане по следния начин:

struct Years(i64);

fn main() {
    let years = Years(42);
    let years_as_primitive_1: i64 = years.0; // Разнородно
    let Years(years_as_primitive_2) = years; // Разлагане
}

Б. пр.

1

Изразът за нов тип – New Type Idiom/Pattern

Вижте също:

structs, "…a Generic Array using Newtype Pattern"

Придадени единици

Понятието Придадени единици1 се отнася до единици от различeн вид. Това е разширение на обобщенията за отличители и позволява отличителите вътрешно да описват нови единици.

Една такава единица се нарича придаден тип и позволява опростено използване, когато отличителят е обобщен през своя съдържащ тип.

Б. пр.

1

придадени единици (типове, функции, методи) – такива, които се прикрепят/добавят/придават към други типове – associated items (types, functions, methods)

Вижте също:

RFC, Разлагане (бележки)

Проблемът

Отличител, който е обобщен през своя съдържащ тип, изисква указване на типа – потребителите на отличителя трябва да уточнят всичките му обобщени типове.

В примера долу отличителят Contains позволява да се използват обобщените типове A и B. След това отличителят бива осъществен за типа Container, като се указва i32 за A и B, така че да може да се ползва с fn difference().

Понеже Contains е обобщен, ни се налага изрично да посочим всичките обобщени типове за fn difference(). Всъщност ни е нужен някакъв начин да кажем, че A и B са предопределени от входния тип C. Както ще видите в следващия раздел, придадените типове предоставят точно тази възможност.

struct Container(i32, i32);

// Отличител, който проверява дали две единици се съхранвяват в друг съдържащ
// тип. Също извлича първата и последната стойност.
trait Contains<A, B> {
    fn contains(&self, _: &A, _: &B) -> bool; // Изисква изрично `A` и `B`.
    fn first(&self) -> i32; // Не изисква изрично `A` или `B`.
    fn last(&self) -> i32;  // Не изисква изрично `A` или `B`.
}

impl Contains<i32, i32> for Container {
    // Истина, ако съхрняваните числа са равни на подадените.
    fn contains(&self, number_1: &i32, number_2: &i32) -> bool {
        (&self.0 == number_1) && (&self.1 == number_2)
    }

    // Взима и връща първото число.
    fn first(&self) -> i32 {
        self.0
    }

    // Взима и връща последното число.
    fn last(&self) -> i32 {
        self.1
    }
}

// `C` съдържа `A` и `B`. В този смисъл е досадно да трябва да изразяваме `A` и
// `B` отново.
fn difference<A, B, C>(container: &C) -> i32
where
    C: Contains<A, B>,
{
    container.last() - container.first()
}

fn main() {
    let number_1 = 3;
    let number_2 = 10;

    let container = Container(number_1, number_2);

    println!(
        "Съдържа ли контейнерът {} и {}: {}",
        &number_1,
        &number_2,
        container.contains(&number_1, &number_2)
    );
    println!("Първо число: {}", container.first());
    println!("Последно: {}", container.last());

    println!("Разликата е: {}", difference(&container));
}

Вижте също:

Структури и Отличители

Придадени типове

Употребата на придадени типове подобрява цялостната четимост на кода, като премества вътрешните типове в отделен отличител като изходни типове. Правописът за описанието на отличителя е следният:

#![allow(unused)]
fn main() {
// `A` и `B` се описват в отличителя с помощта на ключовата дума `type`.
// (Важно: Този `type` тук не е същият като когато се ползва `type` за
// указване на прякор)
trait Contains {
    type A;
    type B;

    // Обновен правопис за достъп до тези типове като обобщения.
    fn contains(&self, _: &Self::A, _: &Self::B) -> bool;
}
}

Забележете, че функциите, използващи отличителя Contains, вече не трябва да упоменават A или B изобщо:

// Без използване на придадени типове
fn difference<A, B, C>(container: &C) -> i32 where
    C: Contains<A, B> { ... }

// С използване на придадени типове
fn difference<C: Contains>(container: &C) -> i32 { ... }

Да пренапишем примера от предния раздел, като ползваме придадени типове:

struct Container(i32, i32);

// Отличител, който проверява дали две единици се съхранвяват в друг съдържащ
// тип. Също извлича първата и последната стойност.
trait Contains {
    // Тук обявяваме обобщени типове, които методите ще могат да ползват.
    type A;
    type B;

    fn contains(&self, _: &Self::A, _: &Self::B) -> bool;
    fn first(&self) -> i32;
    fn last(&self) -> i32;
}

impl Contains for Container {
    // Определяме какви типове са `A` и `B`. Ако входният тип е
    // `Container(i32, i32)`, изходните типове са определени като
    // `i32` и `i32`.
    type A = i32;
    type B = i32;

    // `&Self::A` и `&Self::B` също може да се ползват тук.
    fn contains(&self, number_1: &i32, number_2: &i32) -> bool {
        (&self.0 == number_1) && (&self.1 == number_2)
    }
    // Взима и връща първото число.
    fn first(&self) -> i32 { self.0 }

    // Взима и връща последното число.
    fn last(&self) -> i32 { self.1 }
}

fn difference<C: Contains>(container: &C) -> i32 {
    container.last() - container.first()
}

fn main() {
    let number_1 = 3;
    let number_2 = 10;

    let container = Container(number_1, number_2);

    println!(
        "Съдържа ли контейнерът {} и {}: {}",
        &number_1,
        &number_2,
        container.contains(&number_1, &number_2)
    );
    println!("Първо число: {}", container.first());
    println!("Последно: {}", container.last());

    println!("Разликата е: {}", difference(&container));
}

Параметри от призрачен тип

Параметър от призрачен тип1 е такъв, който не се появява по време на изпълнение, а се проверява статично (и само) по време на компилиране.

Типовете данни могат да използват допълнителни обобщени типови параметри, които да действат като означения или да извършват проверки на типове по време на компилиране. Тези допълнителни параметри не съдържат съхранени стойности и не правят нищо по време на изпълнение.

В следващия пример съвместяваме std::marker::PhantomData с идеята за параметър от призрачен тип, за да създадем разнородни поредици, съдържащи различни типове данни.

use std::marker::PhantomData;

// Разнородна структура от призрачен тип, обобщена през `A` със скрит
// параметър `B`.
#[derive(PartialEq)] // Разрешаваме проверка за еднаквост за този тип.
struct РазноПриз<A, B>(A, PhantomData<B>);

// Структура от призрачен тип, обобщена през `A` със скрит параметър `B`.
#[derive(PartialEq)] // Разрешаваме проверка за еднаквост за този тип.
struct ПризроСтрой<A, B> {
    first: A,
    phantom: PhantomData<B>,
}

// Важно: Заделено е място в паметта за обобщения тип `A`, но не и за `B`.
//        Затова `B` не може да се използва в изчисления.

fn main() {
    // Тук `f32` и `f64` са скритите параметри.
    // Типът за РазноПриз е уточнен като `<char, f32>`.
    let _tuple1: РазноПриз<char, f32> = РазноПриз('Q', PhantomData);
    // Типът за РазноПриз е уточнен като  `<char, f64>`.
    let _tuple2: РазноПриз<char, f64> = РазноПриз('Q', PhantomData);

    // Типът е уточнен като `<char, f32>`.
    let _struct1: ПризроСтрой<char, f32> = ПризроСтрой {
        first: 'Q',
        phantom: PhantomData,
    };
    // Типът е уточнен като `<char, f64>`.
    let _struct2: ПризроСтрой<char, f64> = ПризроСтрой {
        first: 'Q',
        phantom: PhantomData,
    };

    // Грешка по време на компилация за _tuple2! Разминаване в типовете –
    // променливите не могат да бъдат сравнени:
    // expected `РазноПриз<char, f32>`, found `РазноПриз<char, f64>`
    println!("_tuple1 == _tuple2 yields: {}", _tuple1 == _tuple2);

    // Грешка по време на компилация за _struct2! Разминаване в типовете –
    // променливите не могат да бъдат сравнени:
    // expected `ПризроСтрой<char, f32>`, found `ПризроСтрой<char, f64>`
    println!("_struct1 == _struct2 yields: {}", _struct1 == _struct2);
}

Б. пр.

1

параметър от призрачен тип – phantom type parameter. В примера отново използваме азбука, за да покажем поддръжката на Ръждьо за уникод и по-ясно да различм внесения PhantomData от нашите потребителски типове, които можем да наречем всякак.

Вижте също:

Derive, struct и Подредени структури

Проверка: разясняване на единичния тип

Можем да разгледаме един полезен начин за превръщане на мерни единици1, като осъществим Add с помощта на параметър от призрачен тип. Отличителят Add е разгледан по-долу:

// Този строеж предполага: `Self + RHS = Изход`, където RHS (ДС - Дясна
// страна) е по подразбиране Self, ако не е уточнена в осъществяването.
pub trait Add<RHS = Self> {
    type Изход;

    fn add(self, rhs: RHS) -> Self::Изход;
}

// `Изход` трябва да бъде `T<U>` така че `T<U> + T<U> = T<U>`.
impl<U> Add for T<U> {
    type Изход = T<U>;
    ...
}

Цялото – осъществено:

use std::marker::PhantomData;
use std::ops::Add;

/// Създаваме празни броители, като единични типове.
#[derive(Debug, Clone, Copy)]
enum Инч {}
#[derive(Debug, Clone, Copy)]
enum Мм {}

/// `Дължина` е тип с параметър от призрачен тип `Единица`,
/// и не е обобщен през типа `Дължина` (сиреч `f64`).
///
/// `f64` вече осъществява отличителите `Clone` и `Copy`.
#[derive(Debug, Clone, Copy)]
struct Дължина<Единица>(f64, PhantomData<Единица>);

/// Отличителят `Add` описва поведението на оператора `+`.
impl<Единица> Add for Дължина<Единица> {
    type Output = Дължина<Единица>;

    // add() връща нова структура `Дължина`, съдържаща сбора.
    fn add(self, rhs: Дължина<Единица>) -> Дължина<Единица> {
        // `+` извиква осъществяването на отличителя `Add` за `f64`.
        Дължина(self.0 + rhs.0, PhantomData)
    }
}

fn main() {
    // Описва `one_foot` с призрачен тип `Инч`.
    let one_foot: Дължина<Инч> = Дължина(12.0, PhantomData);
    // `one_meter` има параметър от призрачен тип `Мм`.
    let one_meter: Дължина<Мм> = Дължина(1000.0, PhantomData);

    // `+` извиква метода `add()`, който осъществихме за `Дължина<Единица>`.
    //
    // Понеже `Дължина` осъществява `Copy`, `add()` не поглъща
    // `one_foot` и `one_meter`, а ги копира в `self` и `rhs`.
    let two_feet = one_foot + one_foot;
    let two_meters = one_meter + one_meter;

    // Събирането работи.
    println!("една стъпка + one_foot = {:?} ин", two_feet.0);
    println!("един метър + one_meter = {:?} мм", two_meters.0);

    // Безсмислените действия не минават, както и трябва:
    // Грешка по време на компилиране: несъответствие в типовете.
    // expected `Дължина<Инч>`, found `Дължина<Мм>`
    //let one_feter = one_foot + one_meter;
}

Б. пр.

1 Игра на думи: мерна единица, единичен тип – unit. Вижте Unit_type в Wikipedia

Вижте също:

Borrowing (&), Bounds (X: Y), enum, impl & self, Overloading, ref, Traits (X for Y) и TupleStructs.

Правила за обхват

Обхватът (на видимост) има голямо значение за владението1, заемането2 и живота3 на променливите. Той показва на компилатора докога са в сила заеманията, кога може да се освободи паметта и кога променливите биват създадени и унищожени.

Б. пр.

1

владение, собственост – ownership, овладяване – to take ownership

2

заемка, заемане (вземане на заем) – borrowing

3

живот (на променлива) – lifetime

ПДИ

Променливите в Ръждьо не са просто имена за данни, подредени на стълп1: Те също така владеят части от паметта, например Box<T> владее памет в купа2. Ръждьо спазва принципа ПДИ (Придобиването на Данни3 е Инициализация) – RAII (Resource Acquisition Is Initialization). Това означава, че винаги, когато някой обект излезе от обхват, неговият метод за унищожаване се извиква и владените от него данни се освобождават.

Това поведение предпазва от бъгове, причинени от утечки на данни4. Повече никога няма да ви се наложи да освобождавате памет на ръка или да се притеснявате за утечки в паметта. Ето показно̀:

// raii.rs
fn create_box() {
    // Заделяме място за цяло число на купа.
    let _box1 = Box::new(3i32);

    // `_box1` се унищожава тук и паметта се освобождава
}

fn main() {
    // Заделяме място за цяло число на купа.
    let _box2 = Box::new(5i32);

    // Вложен блок (и обхват):
    {
        // Заделяме място за цяло число на купа.
        let _box3 = Box::new(4i32);

        // `_box3` се унищожава тук и паметта се освобождава 
    }

    // Създаване много кутии за забавление
    // Не се налага да освобождаваме памет на ръка!
    for _ in 0u32..1_000 {
        create_box();
    }

    // `_box2` се унищожава тук и паметта се освобождава 
}

Разбира се, винаги можем да проверим за грешки с помощта на valgrind:

$ rustc raii.rs && valgrind ./raii
==26873== Memcheck, a memory error detector
==26873== Copyright (C) 2002-2013, and GNU GPL'd, by Julian Seward et al.
==26873== Using Valgrind-3.9.0 and LibVEX; rerun with -h for copyright info
==26873== Command: ./raii
==26873==
==26873==
==26873== HEAP SUMMARY:
==26873==     in use at exit: 0 bytes in 0 blocks
==26873==   total heap usage: 1,013 allocs, 1,013 frees, 8,696 bytes allocated
==26873==
==26873== All heap blocks were freed -- no leaks are possible
==26873==
==26873== For counts of detected and suppressed errors, rerun with: -v
==26873== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 2 from 2)

Няма утечки!

Унищожител

Идеята за унищожител5 в Ръждьо е осъществена от отличителя Drop. Унищожителят се извиква, когато парчето данни излезе от обхват. Не е задължително този отличител да бъде осъществен за всеки тип, а само когато вашият тип изисква да се направи нещо при унщожаване на обекта.

Изпълнете следващия пример, за да видите как работи Drop. Когато променливата във функцията main излезе от обхват, потребителският унищожител ще бъде извикан.

struct ToDrop;

impl Drop for ToDrop {
    fn drop(&mut self) {
        println!("ToDrop is being dropped");
    }
}

fn main() {
    let x = ToDrop;
    println!("Made a ToDrop!");
}

Б. пр.

1

стълп, стек – stack. Остаряла форма на „стълб”, кула. Подредена памет в програмата за временно съхранение. Там съхраняваните единици са подредени условно казано отдолу нагоре и може да се вземат само отгоре – последната влязла стойност излиза първа. Източник: БТР, 935 – София 1996, Наука и Изкуство. Вижте Стек в Уикипедия..

2

куп – heap. Другият вид памет на програмата – не подреден, различен от стълпа, който е подреден.

3

данни, източник – resource

4

утечки на данни (в паметта) – resource (memory) leaks

5

унищожител – destructor.

Вижте също:

Box

Владение и премествания

Понеже променливите сами се грижат за освобождаване на заетата от тях част от паметта, данните могат да имат само един владелец (собственик). Това също предотвратява възможността дадено парче данни да бъде освободено повече от веднъж. Обърнете внимание, че не всички променливи владеят данни (препратките са такива променливи).

Когато присвояваме стойност на променлива (let x = y) или подаваме аргументи като стойност (не като препратка) (foo(x)), владението на данните бива предадено на функцията. Казано по ръждьовски, това е преместване1.

След преместването предишният владелец (променлива) повече не може да бъде ползван. Това предотвратява създаването на висящи указатели2.

// Тази функция овладява заделената памет от купа
fn destroy_box(c: Box<i32>) {
    println!("Унищожаваме кутия, която съдържа {}", c);

    // `c` е унищожена и паметта е освободена
}

fn main() {
    // Паметта за това число е заделена в стълпа.
    let x = 5u32;

    // *Копираме* `x` в `y` – няма преместване на данни.
    let y = x;

    // И двете стойности могат да се ползват независимо една от друга.
    println!("x е {}, а y е {}", x, y);

    // `a` е указател към цяло число от купа̀.
    let a = Box::new(5i32);

    println!("a съдържа: {}", a);

    // *Местим* `a` в `b`
    let b = a;
    // Адресът на указателя на `a` е копиран (не самите данни) в `b`.
    // И двете променливи сега са указатели към едни и същи данни, заделени в
    // купа, но сега `b` *владее* данните.
    
    // Грешка! `a` повече няма достъп до данните, понеже вече не владее тези
    // данни от купа.
    //println!("a съдържа: {}", a);
    // ЗАДАЧА ^ Разкоментирайте този ред

    // Тази функция овладява заделената в купа памет, преди владяна от `b`
    destroy_box(b);

    // Понеже паметта от купа е освободена вече, следващото действие би
    // осъществило пряк достъп до вече освободена памет. Това е забранено от
    // компилатора.
    // Грешка! Поради същата причина като предишната грешка.
    //println!("b contains: {}", b);
    // ЗАДАЧА ^ Разкоментирайте този ред
}

Б. пр.

1

местене, преместване на данни (от една променлива в друга) – move

2

висящ указател – dangling pointer

Менѝмост

Менѝмостта на данните може да бъде променена, когато собствеността бива прехвърлена на друга променлива.

fn main() {
    let неменѝма_кутийка = Box::new(5u32);

    println!("неменѝма_кутийка съдържа {}", неменѝма_кутийка);

    // Грешка поради неменимост
    //*неменѝма_кутийка = 4;

    // *Преместваме* кутийката, сменяйки владелеца (и менимостта)
    let mut mutable_box = неменѝма_кутийка;

    println!("mutable_box contains {}", mutable_box);

    // Променяме съдържанието на кутйката.
    *mutable_box = 4;

    println!("mutable_box сега съдържа {}", mutable_box);
}

Частични премествания

Обвързване (на променливи) по образец1 може да се ползва за разлагане в отделни променливи2 чрез преместване на части от съставната променлива. Едновременно с това части от променливата могат да се разложат в други променливи чрез създаване на препратки към тези части. Това може да доведе до частично преместване на данните от променливата, което означава, че част от данните в променливата са преместени, а други части не са. В този случай изходната променлива вече не може да бъде използвана като едно цяло. Само частите, които са присвоени на нови променливи като препратки, могат да бъдат използвани повторно.

fn main() {
    #[derive(Debug)]
    struct Person {
        name: String,
        age: Box<u8>,
    }

    let person = Person {
        name: String::from("Alice"),
        age: Box::new(20),
    };

    // Стойността, присвоена на променливата `name`, е преместена извън person,
    // но `age` е само препратка.
    let Person { name, ref age } = person;

    println!("The person's age is {}", age);

    println!("The person's name is {}", name);

    // Грешка! заемка на частично преместена стойност: `person`. Случило се е
    // частично преместване.
    //println!("The person struct is {:?}", person);

    // `person` не може да се ползва като цяло, но частта `person.age` може,
    // понеже нейната стойност не е преместена.
    println!("The person's age from person struct is {}", person.age);
}

(В този пример съхраняваме стойността на променливата age в купа̀, за да онагледим частичното преместване. Ако изтрием ref от кода по-горе, компилаторът ще върне грешка, тъй като владението на person.age ще бъде прехвърлено на променливата age. Ако Person.age беше записано в стълпа (т.е. не беше в кутийка), нямаше да е нужно да пишем ref, понеже според описанието си age щеше да е копирало данните от person.age, без да ги мести.)

Б. пр.

2

разлагане – destructuring. Съставните променливи могат да бъдат разложени на съставните им части, като всяка част отиде в отделна променлива.

1

обвързване по образец (при разлагане на структура) – pattern binding

Вижте също:

Разлагане

Заемане

През повечето време искаме достъп до данните, без да ги овладяваме. За да постигне това, Ръждьо ползва заемане. Вместо да подаваме обекти като стойности (T), можем да подаваме обекти като препратки (&T).

Компилаторът прави статична проверка и гарантира (чрез своя проверител на заемките), че препратките винаги сочат към действителни обекти. Сиреч, ако към някой обект има препратки, обектът не може да бъде унищожен.

// Тази функция овладява една кутия и я унищожава
fn ям_кутия_i32(boxed_i32: Box<i32>) {
    println!("Унищожавам кутия, съдържаща {}", boxed_i32);
}

// Тази функция заема стойност от тип i32
fn заемам_i32(borrowed_i32: &i32) {
    println!("Това цяло число е: {}", borrowed_i32);
}

fn main() {
    // Създаваме променливи – i32 в кутия (съхранявана на купа̀) и i32 на стълпа
    let boxed_i32 = Box::new(5_i32);
    let stacked_i32 = 6_i32;

    // Заемаме съдържанието на кутията. Владението не е прехвърлено, така че
    // съдържанието може да бъде заемано отново.
    заемам_кутия_i32(&boxed_i32);
    заемам_от_стълп_i32(&stacked_i32);

    {
        // Вземаме препратка към данните, съдържащи се в кутията
        let _ref_to_i32: &i32 = &boxed_i32;

        // Грешка!
        // Невъзможно е да бъде унищожена `boxed_i32`, докато вътрешната ѝ
        // стойност е заета по-късно в обхвата.
        ям_кутия_i32(boxed_i32);
        // ПОПРАВИ ^ Коментирайте този ред

        // Опит за заемане на `_ref_to_i32`, след като вътрешната стойност е
        // унищожена
        заемам_i32(_ref_to_i32);
        // `_ref_to_i32` излиза от обхват и вече не се заема.
    }

    // `boxed_i32` вече може да предаде владението на `ям_кутия_i32` и да бъде
    // унищожена
    ям_кутия_i32(boxed_i32);
}

Менѝмост

Менѝмите данни могат да бъдат заемани менѝмо като напишем &mut T. Това се нарича менѝма препратка1 и дава на заемащата променлива достъп до стойността за писане и четене. И обратното – като напишем &T, заемаме данните като неменѝма препратка2. Заемащата променлива може само да чете данните, но не и да ги променя.

#[allow(dead_code)]
#[derive(Clone, Copy)]
struct Book {
    // `&'static str` е препратка към низ, заделен в паметта само за четене
    author: &'static str,
    title: &'static str,
    year: u32,
}

// Тази функция взема препратка към променлива от тип Book
fn borrow_book(book: &Book) {
    println!(
        "Аз взех на заем неменѝмо {} - {} edition",
        book.title, book.year
    );
}

// Тази функция взема менима препратка към менима `book` и променя полето
// `year` на 2014
fn new_edition(book: &mut Book) {
    book.year = 2014;
    println!("Аз заех менѝмо {} - издание {}", book.title, book.year);
}

fn main() {
    // Създаваме неменѝма Book, наречена `immutabook`
    let immutabook = Book {
        // буквалните низове са от тип `&'static str`
        author: "Douglas Hofstadter",
        title: "Gödel, Escher, Bach",
        year: 1979,
    };

    // Създаваме менѝмо копие на `immutabook` и го наричаме `mutabook`
    let mut mutabook = immutabook;

    // Заемаме неменимо неменим обект
    borrow_book(&immutabook);

    // Заемаме неменимо меним обект
    borrow_book(&mutabook);

    // Заемаме менимо меним обект
    new_edition(&mut mutabook);

    // Error! Не може да се заеме неменим обект като менѝм
    new_edition(&mut immutabook);
    // ПОПРАВИ ^ Коментирайте този ред
}

Б. пр.

1

менѝма препратка – mutable reference

2

неменѝма препратка – immutable reference

Вижте също:

static

Единосъщност

Чрез обвързване с имена (каквото са променливите) данните могат да бъдат заемани неменимо многократно, но докато са заети неменимо, първоначалните данни не могат да бъдат заемани менимо. От друга страна, разрешена е само една менима заемка едновременно. Първоначалните данни може да се заемат отново само след като менимата препратка е била използвана за последен път.

struct Point {
    x: i32,
    y: i32,
    z: i32,
}

fn main() {
    let mut point = Point { x: 0, y: 0, z: 0 };

    let borrowed_point = &point;
    let another_borrow = &point;
    // Данните могат да бъдат достъпени чрез препратки и чрез първоначалния
    // владелец
    println!(
        "Point has coordinates: ({}, {}, {})",
        borrowed_point.x, another_borrow.y, point.z
    );

    // Грешка! Не може да се заеме `point` като менима, защото сега е заета
    // като неменѝма
    // let mutable_borrow = &mut point;
    // ЗАДАЧА^ Разкоментирайте този ред

    // Заетите стойности биват ползвани отново тук
    println!(
        "Point has coordinates: ({}, {}, {})",
        borrowed_point.x, another_borrow.y, point.z
    );

    // Неменимите препратки не се ползват по-нататък в кода, следователно може
    // да бъдат заемани отново чрез менима препратка.
    let mutable_borrow = &mut point;

    // Променяме данните чрез менима препратка
    mutable_borrow.x = 5;
    mutable_borrow.y = 2;
    mutable_borrow.z = 1;

    // Грешка! Не може да се заеме `point` като неменѝма, защото сега е заета
    // като менѝма.
    // let y = &point.y;
    // ЗАДАЧА^ Разкоментирайте този ред

    // Грешка! Не може да се печати, защото `println!` взема неменѝма препратка,
    // а по-долу в кода се ползва `mutable_borrow` – менима препратка.
    // println!("Point Z coordinate is {}", point.z);
    // ЗАДАЧА^ Разкоментирайте този ред

    // Може! Менѝми препратки може да се подават като неменѝми на `println!`
    println!(
        "Point has coordinates: ({}, {}, {})",
        mutable_borrow.x, mutable_borrow.y, mutable_borrow.z
    );

    // Менимата препратка вече не се използва до края на кода, значи може
    // данните да бъдат заемани отново.
    let new_borrowed_point = &point;
    println!(
        "Point now has coordinates: ({}, {}, {})",
        new_borrowed_point.x, new_borrowed_point.y, new_borrowed_point.z
    );
}

Б. пр.

В Ръждьо за единосъщни1 се смятат две променливи, които сочат към едни и същи данни в паметта. В следването на собствените си правила за безопасност, Ръждьо не позволява едновременно писане в две променливи, които сочат към едни и същи данни, макар да са с различни имена. Тогава едната променлива се счита за друго име (прякор, псевдоним) на другата. От „The Rustonomicon”: „…variables and pointers alias if they refer to overlapping regions of memory.” – „…променливите и указателите с две различни имена са единосъщни, ако препращат към припокриващи се области от паметта.“

1

единосъщност, разноименност – aliasing

Образецът ref

Когато намираме съвпадения по образец или разлагаме съставни променливи, като обвързваме имена на променливи с данни чрез let, можем да ползваме ключовата дума ref, за да вземем препратки към полетата на структура или разнородна поредица. Следващият пример ни показва няколко случая, в които това може да бъде полезно.

#[derive(Clone, Copy)]
struct Point { x: i32, y: i32 }

fn main() {
    let c = 'Q';

    // Заемане чрез използване на `ref` от лявата страна на `=` е
    // същото като заемане чрез използване на `&` от дясната страна.
    let ref ref_c1 = c;
    let ref_c2 = &c;

    println!("ref_c1 equals ref_c2: {}", *ref_c1 == *ref_c2);

    let point = Point { x: 0, y: 0 };

    // `ref` действа също при разлагане на структура.
    let _copy_of_x = {
        // `ref_to_x` е препратка към полето `x` в `point`.
        let Point { x: ref ref_to_x, y: _ } = point;

        // Връщаме копие на полето `x` от `point`.
        *ref_to_x
    };

    // Менимо копие от `point`
    let mut mutable_point = point;

    {
        // `ref` може да се ползва с `mut` за взимане на меними препратки.
        let Point { x: _, y: ref mut mut_ref_to_y } = mutable_point;

        // Променяме стойността на полето `y` от `mutable_point` чрез менима препратка.
        *mut_ref_to_y = 1;
    }

    println!("point is ({}, {})", point.x, point.y);
    println!("mutable_point is ({}, {})", mutable_point.x, mutable_point.y);

    // Менима разнородна поредица, която съдържа указател
    let mut mutable_tuple = (Box::new(5u32), 3u32);
    
    {
        // Разлагаме `mutable_tuple`, за да променим стойността на `last`.
        let (_, ref mut last) = mutable_tuple;
        *last = 2u32;
    }
    
    println!("tuple is {:?}", mutable_tuple);
}

Живот

Продължителността на живота [на променливите] е конструкция1 на компилаторa (или по-точно на неговия проверител на заемките2), който проверява дали всички заемания са действителни. В частност, животът на една променлива започва, когато бива създадена, и приключва с нейното унищожаване. Макар обхватът и животът на променливите често да се споменават заедно, те не са едно и също нещо.

Да вземем например случая, където заемаме променлива чрез &. Заемката има живот, предопределен от това, къде е обявена. Последствието е, че заемката е в сила до преди заемодателят да бъде унищожен. А обхватът се определя от това, къде се ползва препратката.

В следващия пример и до края на този раздел ще видим как се отнася животът към обхвата и по какво се различават.

// Животът на променливите е обозначен с линии, показващи създаването и
// унищожаването на всяка променлива.
// `i` е с най-дълъг живот, защото нейният обхват изцяло включва `borrow1` и
// `borrow2`. Продължителността на `borrow1` няма значение за `borrow2`, тъй като
// те са отделени.
fn main() {
    let i = 3; // Животът на `i` започва.  ────────────────┐
    //                                                     │
    { //                                                   │
        let borrow1 = &i; // Животът на `borrow1` начева. ┐│
        //                                                ││
        println!("borrow1: {}", borrow1); //              ││
    } // `borrow1` свършва. ──────────────────────────────┘│
    //                                                     │
    //                                                     │
    { //                                                   │
        let borrow2 = &i; //Животът на `borrow2` начева. ─┐│
        //                                                ││
        println!("borrow2: {}", borrow2); //              ││
    } // `borrow2` свършва. ──────────────────────────────┘│
    //                                                     │
}   // Животът на `i` свършва.  ───────────────────────────┘

Забележете, че не се присвояват никакви имена или типове за обозначване на животите. Това създава ограничения при използването на животите, както ще видим.

Б. пр.

Когато говорим за живот, винаги става въпрос за заети данни и препратки.

1

конструкция – construct

2

проверител на заемките – borrow checker

Изрично отбелязване

Проверителят за заемки използва изричното отбелязване на живота, за да определи колко дълго са в сила препратките. В случаите, когато животите са изрично указани (не са пропуснати1|2), Ръждьо изисква изрично отбелязване, за да определи какъв би трябвало да е животът на дадена препратка. Правописът за указване на живот е с апостроф. Ето така:

foo<'a>
// `foo` има параметър за живот `'a`

Подобно на затварянията, използването на животи изисква обобщения. В допълнение, този правопис за живот означава, че животът на foo не може да надвишава този на 'a. Изричното обозначаване на тип има вида &'a T, като 'a вече е било въведено в употреба.

Когато имаме множество животи, правописът е подобен:

foo<'a, 'b>
// `foo` има параметри за живот за `'a` и `'b`

В този случай животът на foo не може да надвишава този на 'a или 'b.

Да разгледаме следния пример за изрично обозначаване на живот:

// `print_refs` приема две препратки към данни от тип `i32`, които имат
// различни животи `'a` и `'b`. Тези два живота трябва да са с продължителност
// поне колкото на функцията `print_refs`.
fn print_refs<'a, 'b>(x: &'a i32, y: &'b i32) {
    println!("x is {} and y is {}", x, y);
}

// Функция, която не приема аргументи, но има праметър за живот `'a`.
fn failed_borrow<'a>() {
    let _x = 12;

    // Грешка!: `_x` не живее достатъчно продължително
    let _y: &'a i32 = &_x;
    // Опитът да се ползва живот `'a` като изрично отбелязване за тип вътре във
    // функцията дава грешка, защото животът на `&_x` е по-кратък от този на `y`. Кратък
    // живот не може насила да бъде приведен към по-продължителен.
}

fn main() {
    // Създаваме променливи, за да бъдат заети по-долу.
    let (four, nine) = (4, 9);
    
    // Заети препратки (`&`) и на двете променливи са подадени във функцията.
    print_refs(&four, &nine);
    // Всяка заета входна променлива трябва да надживее заемащия. Иначе
    // казано, животът на `four` и `nine` трябва да е по-продължителен от този
    // на `print_refs`.
    
    failed_borrow();
    // `failed_borrow` не съдържа препратки, които да насилят `'a` да бъде по-продължителен
    // от живота на функцията, обаче `'a` е по-продължителен. Понеже животът не е ограничаван
    // никога, той по подразбиране е `'static`.
}

Б. пр.

1

неявно указан, пропуснат – elided (elision)

2

неявно указване, пропускане – elision. Пропускането отбелязва животите неявно, така че е нещо различно.

Вижте също:

Обобщения и Затваряния

Функции

Без оглед на пропускането, обявите на функции с живот имат някои ограничения:

  • всяка препратка задължително трябва да е с отбелязан живот.
  • всяка върната препратка задължително трябва да има същия живот като на входните данни (параметъра), или животът ѝ да бъде static.

В допълнние, обърнете внимание, че връщането на препратки е забранено, ако това ще доведе до връщане на недействителни данни. Следващият пример показва няколко работещи разновидности на функции с указана продължителност на живота.

// Една входна препратка с живот `'a`, която трябва да живее поне колкото
// функцията.
fn print_one<'a>(x: &'a i32) {
    println!("`print_one`: x is {}", x);
}

// Също може да се приемат меними препратки с указан живот.
fn add_one<'a>(x: &'a mut i32) {
    *x += 1;
}

// Повече аргументи с различен живот. В този случай и двата аргумента биха
// могли да имат един и същи живот `'a`, но при по-сложни случаи може да се наложи
// да са с различни животи.
fn print_multi<'a, 'b>(x: &'a i32, y: &'b i32) {
    println!("`print_multi`: x is {}, y is {}", x, y);
}

// Да се връщат приети като аргументи препратки е приемливо.
// Но трябва да бъде върнат правилният живот.
fn pass_x<'a, 'b>(x: &'a i32, _: &'b i32) -> &'a i32 { x }

//fn invalid_output<'a>() -> &'a String { &String::from("foo") }
// Горното не работи: `'a` трябва да живее по-продължително от функцията.
// Тук `&String::from("foo")` ще създаде обект `String`, следван от препратка.
// След което данните се изхвърлят при излизане от обхват, като така за връщане
// остава препратка към недействителни данни.

fn main() {
    let x = 7;
    let y = 9;
    
    print_one(&x);
    print_multi(&x, &y);
    
    let z = pass_x(&x, &y);
    print_one(z);

    let mut t = 3;
    add_one(&mut t);
    print_one(&t);
}

Вижте също:

Функции

Методи

Методите се обозначават подобно на функциите:

struct Owner(i32);

impl Owner {
    // Отбелязваме живота на аргументите като при самостоятелна функция.
    fn add_one<'a>(&'a mut self) { self.0 += 1; }
    fn print<'a>(&'a self) {
        println!("`print`: {}", self.0);
    }
}

fn main() {
    let mut owner = Owner(18);

    owner.add_one();
    owner.print();
}

Вижте също:

Методи

Структури

Отбелязването на живот в структури е също подобно на функциите:

// Тип `Borrowed`, който съдържа препратка към число от тип `i32`. Препратката
// към `i32` трябва да надживее `Borrowed`.
#[derive(Debug)]
struct Borrowed<'a>(&'a i32);

// И тук двете препратки трябва да надживеят тази структура.
#[derive(Debug)]
struct NamedBorrowed<'a> {
    x: &'a i32,
    y: &'a i32,
}

// Броител, който е или `i32`, или препратка към такива данни.
#[derive(Debug)]
enum Either<'a> {
    Num(i32),
    Ref(&'a i32),
}

fn main() {
    let x = 18;
    let y = 15;

    let single = Borrowed(&x);
    let double = NamedBorrowed { x: &x, y: &y };
    let reference = Either::Ref(&x);
    let number    = Either::Num(y);

    println!("x is borrowed in {:?}", single);
    println!("x and y are borrowed in {:?}", double);
    println!("x is borrowed in {:?}", reference);
    println!("y is *not* borrowed in {:?}", number);
}

Вижте също:

Структури

Отличители

Отбелязването на живот в методи на отличители е като при функциите. Забележете, че за impl също може да се указва живот.

// Структура с отбелязан живот за нея и неин член.
#[derive(Debug)]
struct Borrowed<'a> {
    x: &'a i32,
}

// Отбелязваме живот за `impl`.
impl<'a> Default for Borrowed<'a> {
    fn default() -> Self {
        Self {
            x: &10,
        }
    }
}

fn main() {
    let b: Borrowed = Default::default();
    println!("b is {:?}", b);
}

Вижте също:

Отличители

Предели

Както обобщените типове могат да имат предели, животите (сами по себе си обобщения) също ползват предели. Знакът : тук има малко по различно значение, но пък знакът + е със същото значение като при обобщенията. Тук следното се чете така:

  1. T: 'a: Всички препратки в T трябва да имат продължителност на живота по-голяма от 'a.
  2. T: Trait + 'a: Типът T трябва да осъществява отличителя Trait и всички препратки в T трябва да живеят по-продължително от 'a.

Примерът показва използването на горния правопис след ключовата дума where:

use std::fmt::Debug; // Trait to bound with.

#[derive(Debug)]
struct Ref<'a, T: 'a>(&'a T);
// `Ref` съдържа препратка към обобщен тип `T`, който има някакъв живот `'a`.
//`T` е о-пределен (ограничен) така, че всякакви *препратки* в `T` трябва да
// надживеят `'a`. Освен това животът на `Ref` не може да надвишава `'a`.

// Обобщена функция, която печати с помощта на отличителя `Debug`.
fn print<T>(t: T) where
    T: Debug {
    println!("`print`: t is {:?}", t);
}

// Тук функцията приема препратка към `T`, където `T` осъществява `Debug` и
// всички препратки в `T` живеят повече от `'a`. Освен това `'a` трябва да
// надживее функцията.
fn print_ref<'a, T>(t: &'a T) where
    T: Debug + 'a {
    println!("`print_ref`: t is {:?}", t);
}

fn main() {
    let x = 7;
    let ref_x = Ref(&x);

    print_ref(&ref_x);
    print(ref_x);
}

Вижте също:

„Обобщения”, „Предели” в „Обобщения” и „Множество предели” в „Обобщения”

Принуждение

По-дълъг живот може да бъде принудително сведен към по-кратък, така че да работи в обхват, в който иначе не би работил. Това се постига от компилатора на Ръждьо чрез отгатнато принуждение към по-краткия живот, а също и чрез обявяване на разлика в животите:

// Тук Ръждьо отгатва възможно най-кратката продължителност на живота. След
// това двете препратки биват сведени принудително към тази продължителност.
fn multiply<'a>(first: &'a i32, second: &'a i32) -> i32 {
    first * second
}

// `<'a: 'b, 'b>` се чете така: живот `'a` е дълъг поне колкото `'b`.
// Тук приемаме като вход `&'a i32` и връщаме `&'b i32` като резултат от
// принуждението.
fn choose_first<'a: 'b, 'b>(first: &'a i32, _: &'b i32) -> &'b i32 {
    first
}

fn main() {
    let first = 2; // По-дълъг живот
    
    {
        let second = 3; // По-кратък живот
        
        println!("Произведението е {}", multiply(&first, &second));
        println!("{} is the first", choose_first(&first, &second));
    };
}

#ЗАДАЧА–ПРЕВОД ДА се прегледа и сравни с източника, защото има много промени напоследък, особено commit 11e137369be Да се допреведе новодобавеното.

Статичeн

Ръждьо има няколко запазени имена за животи. Едно от тях е 'static. Може да се натъкнете на тях в два случая:

// Препратка със 'static – статична продължителност на живота:
let s: &'static str = "hello world";

// 'static като част от предел за отличител:
fn generic<T>(x: T) where T: 'static {}

Двата случая са свързани, но има тънка разлика и това често води до объркване при изучаването на Ръждьо. Ето някои примери за всеки от случаите:

Като живот на препратка

Препратка с живот, обозначен като 'static, указва, че данните, към които сочи препратката, живеят през цялото време, докато работи програмата. Този живот може принудително да бъде съкратен.

Има два начина за създаване на променлива със статичен ('static) живот. И в двата случая данните се съхраняват в статичната (само за четене) памет на изпълнимия файл.

  • Създаване на константа с ключовата дума static.
  • Създаване на низова буквална стойност от тип &'static str.

В следващия пример са онагледени и двата начина:

// Създаваме константа с продължителност на живота `'static`.
static NUM: i32 = 18;

// Връща препратка към  `NUM`, като нейният `'static` живот е принудително сведен
// до този на входния аргумент.
fn coerce_static<'a>(_: &'a i32) -> &'a i32 {
    &NUM
}

fn main() {
    {
        // Създаваме низова буквална стойност и я отпечатваме:
        let static_string = "Аз съм в паметта само за четене.";
        println!("static_string: {}", static_string);

        // Когато `static_string` излезе от обхват, препратката не може да бъде
        // ползвана повече, но данните си остават в двоичния файл.
    }

    {
        // Създаваме цяло число, за да го подадем на `coerce_static`:
        let lifetime_num = 9;

        // Свеждаме живота на `NUM` до този на `lifetime_num`:
        let coerced_static = coerce_static(&lifetime_num);

        println!("coerced_static: {}", coerced_static);
    }

    println!("NUM: {} остава достъпно!", NUM);
}

Като предел на отличител

Като предел на отличител 'static означава, че типът не съдържа никакви нестатични препратки. Сиреч получателят може да държи типа колкото му е необходимо и да знае, че данните в този тип винаги ще са действителни, докато не ги изхвърли.

Неясен смисъл на английски. Д го погледна пак§!: It's important to understand this means that any owned data always passes a 'static lifetime bound, but a reference to that owned data generally does not:

Важно е да се знае, че това означава, че всички притежавани данни винаги минават проверка за статичен ('static) предел на живота, но препратките към тези притежавани данни обикновено не преминават:

use std::fmt::Debug;

fn print_it( input: impl Debug + 'static ) {
    println!( "подадената 'static стойност е: {:?}", input );
}

fn main() {
    // i е собствена и не съдържа препратки, значи е 'static:
    let i = 5;
    print_it(i);

    // Опааа, &i има живот само колкото е обхватът на main(),
    // значи не е 'static:
    print_it(&i);
}

Компилаторът ще ви каже:

error[E0597]: `i` does not live long enough
  --> src/lib.rs:15:15
   |
15 |     print_it(&i);
   |     ---------^^--
   |     |         |
   |     |         borrowed value does not live long enough
   |     argument requires that `i` is borrowed for `'static`
16 | }
   | - `i` dropped here while still borrowed

Вижте също:

константи 'static

Пропускане

Някои образци за прилагане на идеята за живот на препратките са толкова често срещани, че проверителят на заемките разрешава да бъдат пропуснати, за да се спести писане и да се подобри четимостта на кода. Това е известно като пропускане1 (елизия). Пропускането е разрешено само за често срещани образци.

Следният код показва примери на пропускане. За по-изчерпателно описание на пропускането вижте „Lifetime Elision” в книгата.

// `elided_input` и `annotated_input` всъщност имат едно и също обявление, защото
// животът на `elided_input` е отгатнат от компилатора:
fn elided_input(x: &i32) {
    println!("`elided_input`: {}", x);
}

fn annotated_input<'a>(x: &'a i32) {
    println!("`annotated_input`: {}", x);
}

// По същия начин и `elided_pass` и `annotated_pass` имат еднакви обяви, защото
// животът на `elided_pass` бива добавен неявно:
fn elided_pass(x: &i32) -> &i32 { x }

fn annotated_pass<'б>(x: &'б i32) -> &'б i32 { x }

fn main() {
    let x = 3;

    elided_input(&x);
    annotated_input(&x);

    println!("`elided_pass`: {}", elided_pass(&x));
    println!("`annotated_pass`: {}", annotated_pass(&x));
}

Б. пр.

1

пропускане, изпускане, скриване (елизия) – elision

Вижте също:

elision

Отличители

Отличителят (буквално отличителна черта – б. пр.) (trait) е набор от методи, описани за непознат тип: Self. Методите могат да достъпват други методи, обявени в същия отличител.

Отличителите могат да бъдат осъществявани за всеки тип данни. В този пример описваме Animal като множество от методи. След това отличителят Animal бива осъществен за типа Sheep. Така можем да ползваме методи от Animal със Sheep.

struct Sheep { naked: bool, name: &'static str }

trait Animal {
    // Обявяваме придадена функция; `Self` се отнася до осъществяващия тип
    fn new(name: &'static str) -> Self;

    // Обяви на методи; ще върнат низ.
    fn name(&self) -> &'static str;
    fn noise(&self) -> &'static str;

    // Отличителите могат да предоставят осъществени методи по подразбиране.
    fn talk(&self) {
        println!("{} says {}", self.name(), self.noise());
    }
}

impl Sheep {
    fn is_naked(&self) -> bool {
        self.naked
    }

    fn shear(&mut self) {
        if self.is_naked() {
            // Методите на осъществителя (структура, друг отличител) могат да
            // извикват методите, осъществени в отличителя.
            println!("{} is already naked...", self.name());
        } else {
            println!("{} gets a haircut!", self.name);

            self.naked = true;
        }
    }
}

// Осъществяваме отличителя `Animal` за `Sheep`.
impl Animal for Sheep {
    // `Self` е типът на осъществителя: `Sheep`.
    fn new(name: &'static str) -> Sheep {
        Sheep { name: name, naked: false }
    }

    fn name(&self) -> &'static str {
        self.name
    }

    fn noise(&self) -> &'static str {
        if self.is_naked() {
            "беееее?"
        } else {
            "бееееее!"
        }
    }
    
    // Методите по подразбиране, осъществени в отличителя, могат да бъдат
    // променени.
    fn talk(&self) {
        // Например, можем да добавим малко тихо съзерцание.
        println!("{} pauses briefly... {}", self.name, self.noise());
    }
}

fn main() {
    // В този случай е нужно да се укаже типът.
    let mut dolly: Sheep = Animal::new("Dolly");
    // ЗАДАЧА ^ Премахнете необходимостта от указване на типа на променливата.

    dolly.talk();
    dolly.shear();
    dolly.talk();
}

Производни

Компилаторът може да предоставя основно осъществяване за някои отличители чрез атрибута #[derive]. Тези отличители могат да бъдат осъществени и ръчно, ако е необходимо по-сложно поведение.

Ето списък с отличители, от които можем да създаваме производни1:

  • Отличители за сравнение: Eq, PartialEq, Ord, PartialOrd.
  • Clone, за създаване на T от &T чрез копиране.
  • Copy, да се направи даден тип „копируем“ вместо „преместваем“.
  • Hash, за изчисляване на хеш-сума от &T.
  • Default, за създаване на празен обект от даден тип данни.
  • Debug, за форматиране на стойност чрез обозначението {:?}.
// `Centimeters` – разнородна поредица, която може да бъде сравнявана с друга
#[derive(PartialEq, PartialOrd)]
struct Centimeters(f64);

// `Inches` – разнородна поредица, която може да бъде отпечатвана
#[derive(Debug)]
struct Inches(i32);

impl Inches {
    fn to_centimeters(&self) -> Centimeters {
        let &Inches(inches) = self;

        Centimeters(inches as f64 * 2.54)
    }
}

// `Seconds` – разнородна поредица без допълнителни атрибути
struct Seconds(i32);

fn main() {
    let _one_second = Seconds(1);

    // Грешка: `Seconds` не може да се печати; не осъществява отличителя `Debug`
    //println!("One second looks like: {:?}", _one_second);
    // ЗАДАЧА ^ Разкоментирайте този ред

    // Грешка: `Seconds` не може да бъде сравнявана;
    // Не осъществява отличителя `PartialEq`
    //let _this_is_true = (_one_second == _one_second);
    // ЗАДАЧА ^ Разкоментирайте този ред

    let foot = Inches(12);

    println!("One foot equals {:?}", foot);

    let meter = Centimeters(100.0);

    let cmp =
        if foot.to_centimeters() < meter {
            "smaller"
        } else {
            "bigger"
        };

    println!("One foot is {} than one meter.", cmp);
}

Б. пр.

1

производни – типове, които наследяват способности от отличители, използвайки атрибута #[derive]. глаг.: съм прозводен на – derive

Вижте също:

derive

Връщане на отличители със dyn

Компилаторът на Ръждьо трябва да знае колко място в паметта изисква всеки тип за връщане от функция. Това означава, че всичките ви функции трябва да връщат определен тип. За разлика от други езици, ако имате отличител Animal, тук не можете да напишете функция, която връща Animal, защото различните ѝ въплъщения ще изискват различно количество памет.

Все пак това ограничение може лесно да се заобиколи. Вместо да връщат направо обект от отличител, функциите могат да връщат Box (кутия), която съдържа някакво въплъщение на Animal. Кутията е просто препратка към някакво място от паметта в купа1. Понеже размерът на препратката се знае и компилаторът може да гарантира, че тя сочи към Animal, за който е заделено място в купа, то нашата функция може да върне отличител.

Ръждьо гледа да бъде колкото се може по-изричен, когато заделя памет на купа. Така че, ако функцията ви връща препратка-към-отличител-на-купа, трябва да напишете пред връщания тип ключовата дума dyn.

struct Sheep {}
struct Cow {}

trait Animal {
    // Обявление на метод
    fn noise(&self) -> &'static str;
}

// Осъществяваме отличителя `Animal` за `Sheep`.
impl Animal for Sheep {
    fn noise(&self) -> &'static str {
        "беееее!"
    }
}

// Осъществяваме отличителя `Animal` за `Cow`.
impl Animal for Cow {
    fn noise(&self) -> &'static str {
        "мууууу!"
    }
}

// Връща някаква структура, която осъществява някакво животно (Animal), но не
// знаем кое точно по време на компилация.
fn random_animal(random_number: f64) -> Box<dyn Animal> {
    if random_number < 0.5 {
        Box::new(Sheep {})
    } else {
        Box::new(Cow {})
    }
}

fn main() {
    let random_number = 0.234;
    let animal = random_animal(random_number);
    println!("Избрахте случайно животно и то казва {}", animal.noise());
}

Б. пр.

1

куп – същ. м. р. ед. ч. – the heap memory

Промяна на оператори

В Ръждьо много от операторите могат да бъдат променяни чрез отличители. Някои оператори може да се ползват за извършване на различни задачи в зависимост от подадените им аргументи. Това е възможно, защото операторите са просто краснопис за извикване на методи. Например + в израза a + b извиква метода add (ей така a.add(b)). Този метод add е част от отличителя Add. Така операторът + може да се ползва от всеки осъществител на отличтеля Add.

Списък с отличители като Add, които променят оператори, може да бъде намерен в core::ops.

use std::ops;

struct Foo;
struct Bar;

#[derive(Debug)]
struct FooBar;

#[derive(Debug)]
struct BarFoo;

// Отличителят `std::ops::Add` се използва за указване на функционалността на `+`.
// Тук създаваме `Add<Bar>` – отличител за добавяне с RHS от тип `Bar`.
// Следващият блок осъществява операцията: Foo + Bar = FooBar
impl ops::Add<Bar> for Foo {
    type Output = FooBar;

    fn add(self, _rhs: Bar) -> FooBar {
        println!("> Извикахме Foo.add(Bar)");

        FooBar
    }
}

// Като разменим типовете, в крайна сметка осъществяваме некомутативно добавяне.
// Тук създаваме `Add<Foo>` – отличител за добавяне с RHS от тип `Foo`.
// Този блок осъществява операцията: Bar + Foo = BarFoo
impl ops::Add<Foo> for Bar {
    type Output = BarFoo;

    fn add(self, _rhs: Foo) -> BarFoo {
        println!("> Извикахме Bar.add(Foo)");

        BarFoo
    }
}

fn main() {
    println!("Foo + Bar = {:?}", Foo + Bar);
    println!("Bar + Foo = {:?}", Bar + Foo);
}

See Also

Add, Syntax Index

Drop

Отличителят Drop има само един метод – drop, който се извиква автоматично, когато даден обект излезе от обхват. Главната полза от Drop е освобождаването на памет, която производният обект владее.

Box, Vec, String, File и Process са примерни въплъщения на Drop за освобождаване на данни. Отличителят Drop може да бъде осъществен и на ръка за всеки потребителски тип.

Следващият пример извежда съобщение в конзолата и така показва кога е извикана функцията drop.

struct Droppable {
    name: &'static str,
}

// Това простичко въплъщение на `drop` отпечатва в конзолата.
impl Drop for Droppable {
    fn drop(&mut self) {
        println!("> Dropping {}", self.name);
    }
}

fn main() {
    let _a = Droppable { name: "a" };

    // блок А
    {
        let _b = Droppable { name: "b" };

        // блок Б
        {
            let _c = Droppable { name: "c" };
            let _d = Droppable { name: "d" };

            println!("Излизаме от блок Б");
        }
        println!("Тъкмо излязохме от блок Б");

        println!("Излизаме от блок А");
    }
    println!("Тъкмо излязохме от блок А");

    // Променливата може да бъде освободена чрез извикване ръчно на `drop`
    drop(_a);
    // ЗАДАЧА ^ Коментирайте този ред

    println!("край на главната функция");

    // `_a` няма да бъде освободена отново тук, понеже вече е освободена ръчно
}

Повторители

Отличителят Iterator се ползва за осъществяване на повторители върху сбирки от данни, каквито са поредиците.

Отличителят изисква само един метод за следващия (next) член. Той може да се опише на ръка в блок за осъществяване (impl) или да се ползва автоматично (както е в поредиците и редиците).

За удобство в общия случай конструкцията for превръща някои сбирки в повторители с помощта на метода .into_iter().

struct Fibonacci {
    curr: u32,
    next: u32,
}

// Осъществяваме `Iterator` за `Fibonacci`.
// Отличителят `Iterator` изисква осъществяване само на един метод за следващия
// (`next`) член.
impl Iterator for Fibonacci {
    // Можем да ползваме този тип чрез Self::Item
    type Item = u32;

    // Тук описваме последователност с `.curr` и `.next`.
    // Типът за връщане е `Option<T>`:
    //     * Когато `Iterator` свърши, ще бъде върнато `None`.
    //     * Иначе – следващата стойност бива обгърната в `Some` и върната.
    // Ползваме Self::Item като тип за връщане, така че можем да сменим типа и
    // да не променяме обявленията на функциите.
    fn next(&mut self) -> Option<Self::Item> {
        let current = self.curr;

        self.curr = self.next;
        self.next = current + self.next;

        // Тъй като редицата на Фибоначи няма край, то `Iterator` никога няма да върне
        // `None`, а винаги ще връща `Some`.
        Some(current)
    }
}

// Връща производител на последователност на Фибоначи.
fn fibonacci() -> Fibonacci {
    Fibonacci { curr: 0, next: 1 }
}

fn main() {
    // `0..3` е `Iterator`, който създава 0, 1, and 2.
    let mut sequence = 0..3;

    println!("Четири последователни извиквания на `next` върху редицата 0..3");
    println!("> {:?}", sequence.next());
    println!("> {:?}", sequence.next());
    println!("> {:?}", sequence.next());
    println!("> {:?}", sequence.next());

    // `for` работи върху обект, създаден от `Iterator`, докато той не върне `None`.
    // Всяка стойност `Some` е разгърната и обвързана с променлива (тук – `i`).
    println!("Iterate through 0..3 using `for`");
    for i in 0..3 {
        println!("> {}", i);
    }

    // Методът `take(n)` смалява обекта от тип `Iterator` до първите му `n` члена.
    println!("Първите четири члена от последователността на Фибоначи са: ");
    for i in fibonacci().take(4) {
        println!("> {}", i);
    }

    // Методът `skip(n)` скъсява обекта от тип `Iterator`, като освобождава първите му `n` члена.
    println!("Следващите четири члена от последователността на Фибоначи са: ");
    for i in fibonacci().skip(4).take(4) {
        println!("> {}", i);
    }

    let array = [1u32, 3, 3, 7];

    // Методът `iter` произвежда обект от тип `Iterator` от поредица или отрязък.
    println!("Iterate the following array {:?}", &array);
    for i in array.iter() {
        println!("> {}", i);
    }
}

impl Черта

impl Черта може да се ползва на две места:

  1. като тип за аргумент
  2. като тип за връщане

Като тип за аргумент

Ако функцията ви е обобщена чрез някакакъв отличител, но нямате нищо против уточняването на типа, може да опростите обявлението на функцията, като използвате правописа impl Черта за тип на аргумента.

За пример да разгледаме следния код:

fn parse_csv_document<R: std::io::BufRead>(src: R)
    -> std::io::Result<Vec<Vec<String>>> {
    src.lines()
        .map(|line| {
            // За всеки ред в източника
            line.map(|line| {
                // Ако редът е прочетен успешно, се обработва,
                // ако ли не – връща грешка
                line.split(',') // Цепи реда по запетайки
                    .map(|entry| String::from(entry.trim()))
                    // Маха водещи и следващи празноти
                    .collect() // Събира всички низове в реда във Vec<String>
            })
        })
        .collect() // Събира всички редове във Vec<Vec<String>>
}

parse_csv_document е обобщена и това ѝ позволява да приема всякакъв тип, осъществяващ BufRead. Такива са BufReader<File> и [u8]. Не е важно какво точно е типът R. R се ползва само за да бъде обявен типът на src, така че функцията може да бъде написана и така:

fn parse_csv_document(src: impl std::io::BufRead)
    -> std::io::Result<Vec<Vec<String>>> {
    src.lines()
        .map(|line| {
            // За всеки ред в източника
            line.map(|line| {
                // Ако редът е прочетен успешно, се обработва,
                // ако ли не – връща грешка
                line.split(',') // Цепи реда по запетайки
                    .map(|entry| String::from(entry.trim()))
                    // Маха водещи и следваши празноти
                    .collect() // Събира всички низове в реда във Vec<String>
            })
        })
        .collect() // Събира всички редове във Vec<Vec<String>>
}

Забележете, че използвайки impl Черта като тип за аргумент, не можете изрично да кажете каква форма на функцията използвате. По-точно, parse_csv_document::<std::io::Empty>(std::io::empty()) няма да работи с втория пример.

Като тип за връщане

Ако вашата функция връща тип, който осъществява MyTrait, можете да опишете типа за връщане така: -> impl MyTrait. Това може доста да опрости обявленията на функциите ви.

use std::iter;
use std::vec::IntoIter;

// Тази функция съчетава два вектора `Vec<i32>` и връща повторител за
// съчетанието. Вижте колко е сложен типът за връщане!
fn combine_vecs_explicit_return_type(
    v: Vec<i32>,
    u: Vec<i32>,
) -> iter::Cycle<iter::Chain<IntoIter<i32>, IntoIter<i32>>> {
    v.into_iter().chain(u.into_iter()).cycle()
}

// Това е същата функция, но типът ѝ за връщане ползва `impl Черта`.
// Вижте колко по-проста е!
fn combine_vecs(
    v: Vec<i32>,
    u: Vec<i32>,
) -> impl Iterator<Item=i32> {
    v.into_iter().chain(u.into_iter()).cycle()
}

fn main() {
    let v1 = vec![1, 2, 3];
    let v2 = vec![4, 5];
    let mut v3 = combine_vecs(v1, v2);
    assert_eq!(Some(1), v3.next());
    assert_eq!(Some(2), v3.next());
    assert_eq!(Some(3), v3.next());
    assert_eq!(Some(4), v3.next());
    assert_eq!(Some(5), v3.next());
    println!("all done");
}

Още повече, че някои типове в Ръждьо не могат да бъдат написани изрично. Например, всяко затваряне има свой собствен безименен тип. Преди появата на правописа impl Черта трябваше да се задели място на купа̀, за да се върне затваряне. Но сега е възможно да се направи статично, ето така:

// Връща функция, която добавя `y` към входа си
fn make_adder_function(y: i32) -> impl Fn(i32) -> i32 {
    let closure = move |x: i32| { x + y };
    closure
}

fn main() {
    let plus_one = make_adder_function(1);
    assert_eq!(plus_one(2), 3);
}

Можете също да пишете impl Черта, за да върнете повторител, който ползва затварянията map или filter. Това прави употребата на map и filter по-лесна. Понеже типовете на затварянията нямат имена, не можете да напишете изрично името на типа за връщане, ако функцията ви връща повторител със затваряне. Но с помощта на impl Черта това е лесно:

fn double_positives<'a>(numbers: &'a Vec<i32>) -> impl Iterator<Item = i32> + 'a {
    numbers
        .iter()
        .filter(|x| x > &&0)
        .map(|x| x * 2)
}

fn main() {
    let singles = vec![-3, -2, 2, 3];
    let doubles = double_positives(&singles);
    assert_eq!(doubles.collect::<Vec<i32>>(), vec![4, 6]);
}

Clone

Когато се обработват данни, поведението по подразбиране е да бъдат прехвърлени (move) при присвояване или извикване на функции. Все пак понякога искаме да копираме дaнните.

Отличителят Clone ни помага точно за това. Обикновено ползваме метода .clone(), описан в отличителя Clone.

// Единична структура без данни
#[derive(Debug, Clone, Copy)]
struct Unit;

// Подредена структура, осъществяваща отличителя `Clone`
#[derive(Clone, Debug)]
struct Pair(Box<i32>, Box<i32>);

fn main() {
    // Създаваме обект от тип `Unit`
    let unit = Unit;
    // Копираме `unit`, няма данни за местене.
    let copied_unit = unit;

    // И двата обекта `Unit` могат да се ползват независимо един от друг
    println!("original: {:?}", unit);
    println!("copy: {:?}", copied_unit);

    // Създаваме данни от тип `Pair`
    let pair = Pair(Box::new(1), Box::new(2));
    println!("original: {:?}", pair);

    // Местим `pair` в `moved_pair`, има преместване на данни.
    let moved_pair = pair;
    println!("moved: {:?}", moved_pair);

    // Грешка! `pair` е загубил данните си.
    //println!("original: {:?}", pair);
    // ЗАДАЧА ^ Разкоментирайте този ред.

    // Клонираме `moved_pair` в `cloned_pair` (включително с данните).
    let cloned_pair = moved_pair.clone();
    // Освобождаваме първоначалния чифт с помощта на `std::mem::drop`.
    drop(moved_pair);

    // Грешка! `moved_pair` вече е освободен.
    //println!("copy: {:?}", moved_pair);
    // ЗАДАЧА ^ Разкоментирайте този ред.

    // Резултатът от .clone() все още може да се ползва!
    println!("clone: {:?}", cloned_pair);
}

Надотличители

В Ръждьо няма „наследяване“, но можете да опишете отличител, който да е надмножество1 на друг отличител. Например:

trait Person {
    fn name(&self) -> String;
}

// Person  е надотличител на Student.
// Осъществяването на Student изисква да осъществите също и методите в Person.
trait Student: Person {
    fn university(&self) -> String;
}

trait Programmer {
    fn fav_language(&self) -> String;
}

// CompSciStudent (студент по компютърни науки) е подотличител едновременно на
// Programmer и Student. Осъществяването на CompSciStudent изисква да осъществите
// и двата надотличителя.
trait CompSciStudent: Programmer + Student {
    fn git_username(&self) -> String;
}

fn comp_sci_student_greeting(student: &dyn CompSciStudent) -> String {
    format!(
        "My name is {} and I attend {}.
        My favorite language is {}. My Git username is {}",
        student.name(),
        student.university(),
        student.fav_language(),
        student.git_username()
    )
}

fn main() {}

Б. пр.

1

надотличител – supertrait. Подобно на „надклас” в други езици, „надотличител”-ят е надмножество на друг отличител. А всяка структура може да осъществява или да бъде производна на повече от един отличител.

Вижте също:

The Ръждьо Programming Language chapter on supertraits

Уточняване на застъпващи се отличители

Всеки тип може да осъществява много различни отличители. Но какво да правим, ако два отличителя изискват осъществяване на метод с едно и също име? Например много отличители може да имат метод с име get(). А тези методи може би връщат и различен тип данни!

Имаме добри новини. Понеже всяко осъществяване на отличител става в отделен блок impl, винаги е ясно чий метод get осъществяваме.

Но пък как ще извикаме тези методи? За да ги различим, се нуждаем от Пълнокачествен Правопис1.

trait UsernameWidget {
    // Връща избраното потребителско име от тази джаджа
    fn get(&self) -> String;
}

trait AgeWidget {
    // Връща избраната възраст от тази джаджа
    fn get(&self) -> u8;
}

// Форма за попълване и с двете полета – и UsernameWidget, и AgeWidget
struct Form {
    username: String,
    age: u8,
}

impl UsernameWidget for Form {
    fn get(&self) -> String {
        self.username.clone()
    }
}

impl AgeWidget for Form {
    fn get(&self) -> u8 {
        self.age
    }
}

fn main() {
    let form = Form {
        username: "rustacean".to_owned(),
        age: 28,
    };

    // Ако разкоментирате този ред, ще получите грешка, която казва
    // "намерени са множество `get`", защото това наистина са
    // множество методи с името `get`.
    // println!("{}", form.get());

    let username = <Form as UsernameWidget>::get(&form);
    assert_eq!("rustacean".to_owned(), username);
    let age = <Form as AgeWidget>::get(&form);
    assert_eq!(28, age);
}

Б. пр.

1

пълнокачествен правопис – fully qualified syntax. Такова описание на нещата, което не оставя неясноти.

Вижте също:

The Ръждьо Programming Language chapter on Fully Qualified syntax

macro_rules!

Ръждьо предоставя мощна уредба за макроси, която позволява метапрограмиране1. Както видяхме в предишните глави, макросите изглеждат като функции, само че завършват накрая с удивителен знак !. Но вместо да създават извикване на функция, макросите биват разгърнати2 в изходен код, който се компилира с другия код в програмата. За разлика, обаче, от макросите в C и други езици, ръждьовите макроси биват разгърнати в абстрактни3 правописни дървета, а не просто като предварително обработени низове (състоящи се от програмен код). Така не ви се случват неочаквани бъгове, например заради предимството на операторите при извикване.

Макроси се създават с помощта на макроса macro_rules!

// Това е простичък макрос, наречен `say_hello`.
macro_rules! say_hello {
    // `()` означава, че макросът не приема аргументи.
    () => {
        // Макросът ще се разгърне както е съдържанието на този блок.
        println!("Hello!")
    };
}

fn main() {
    // Това извикване се разгръща като `println!("Hello")`
    say_hello!()
}

И така. Защо са полезни макросите?

  1. Избягване на повторения (не се повтаряй). Има много случаи, където може да ви трябва подобна функционалност на различни места, но с различни типове. Често написването на макрос е полезен начин за избягване на повторения в кода. (Повече по-късно)

  2. Езици с особено предназначение.4 Макросите позволяват да се описва определен правопис за точно определена цел. (Повече по-късно)

  3. Външности с променлив брой аргументи.5 Понякога искате да опишете външност6, която приема различен брой аргументи. Един пример е макросът println!, който приема различен брой аргументи в зависимост от означенията в низа за форматиране. (Повече по-късно)

Б. пр.

1

метапрограмиране – metaprogramming. Програмиране на програмирането – създаване на изходен програмен код, чрез програмиране.

2

разгърнат (програмен код) – expanded

3

отвлечен (за понятие), абстрактен – abstract

4

Езици с особено предназначение – Domain-Specific Languages (DSL). Обратното на Езици с общо предназначение – General Purpose Programming Languages, какъвто е Ръждьо.

5

Външности с променлив брой аргументи – Variadic interfaces

6

външност (интерфейс) – interface

Правопис

В следващите подраздели ще покажем как се описват макроси в Ръждьо. Има три основни понятия:

Б. пр.

1

образци и обозначители – patterns and designators

2

презаписване – overloading

Обозначители

Пред аргументите на макроса се поставя знакът за долар $ и се отбелязват като тип чрез обозначител1:

macro_rules! create_function {
    // Този макрос приема един аргумент с обозначител `ident` и създава функция,
    // наречена `$func_name`. Обозначителят `ident` се използва за имена на
    // променливи и функции.
    ($func_name:ident) => {
        fn $func_name() {
            // Макросът `stringify!` превръща `ident` в низ.
            println!("Вие извикахте {:?}()",
                     stringify!($func_name));
        }
    };
}

// Създаваме функции, именувани `foo` и `bar`, чрез горния макрос.
create_function!(foo);
create_function!(bar);

macro_rules! print_result {
    // Този макрос приема израз от тип `expr` и го отпечатва
    // като низ заедно с изхода от него.
    // Обозначителят `expr` се използва за изрази.
    ($expression:expr) => {
        // `stringify!` ще преобразува израза *както си е* в низ.
        println!("{:?} = {:?}",
                 stringify!($expression),
                 $expression);
    };
}

fn main() {
    foo();
    bar();

    print_result!(1u32 + 1);

    // Да не забравяме, че блоковете също са изрази!
    print_result!({
        let x = 1u32;

        x * x + 2 * x - 1
    });
}

Ето някои от наличните [типове] обозначители:

  • block
  • expr се използва за указване на изрази
  • ident се използва за задаване имена на променливи и функции
  • item
  • literalсе използва за обозначаване на буквални константи
  • pat (образец)
  • path
  • stmt (изявлениe)
  • tt (дърво от признаци2)
  • ty (тип)
  • vis (окачествител на видимостта)

За да видите пълния списък, погледнете в Справочника на Ръждьо.

Б. пр.

1

обозначител – designator

2

знак, признак, белег; опознавателен знак; – token

Презареждане

Макросите могат да бъдат презареждани1 да приемат различни съчетания от аргументи. В този смисъл macro_rules! може да работи подобно на блок за сравнение на стойности по съвпадение (match).

// `test!` ще сравни `$left` и `$right`
// по различни начини в зависимост от това, как го извикате:
macro_rules! test {
    // Не е нужно аргументите да бъдат разделени със запетаи.
    // Може да се използва всякакъв образец!
    ($left:expr; и $right:expr) => {
        println!("{:?} и {:?} е {:?}",
                 stringify!($left),
                 stringify!($right),
                 $left && $right)
    };
    // ^ всяко разклонение трябва да завършва с точка и запетая.
    ($left:expr; или $right:expr) => {
        println!("{:?} или {:?} е {:?}",
                 stringify!($left),
                 stringify!($right),
                 $left || $right)
    };
}

fn main() {
    test!(1i32 + 1 == 2i32; и 2i32 * 2 == 4i32);
    test!(true; или false);
}

Б. пр.

1

Презареждане (Презаписване) – Overloading

Повторение

В макросите може да се използва знакът + в списъка с аргументи, за да се обозначи, че даден аргумент може да се повтаря1 поне веднъж; или знакът *, за да се обозначи, че аргументът може да се повтаря нула или повече пъти.

В следващия пример, ако оградим израза за съвпадението с $(...),+, това ще съвпадне с един или повече изрази (expr), разделени със запетая. Забележете също, че знакът ; не е задължителен за последния израз.

// `find_min!` ще намери най-малкото число от незнаен брой аргументи.
macro_rules! find_min {
    // Основен случай:
    ($x:expr) => ($x);
    // `$x` последвано от поне едно `$y,`
    ($x:expr, $($y:expr),+) => (
        // Извикваме `find_min!` върху последното `$y`
        std::cmp::min($x, find_min!($($y),+))
    )
}

fn main() {
    println!("{}", find_min!(1));
    println!("{}", find_min!(1 + 2, 2));
    println!("{}", find_min!(5, 2 * 3, 4));
}

Б. пр.

1

повторение – repeat

НСП (Не Се Повтаряй!)

Можем да постигнем НСП1, като изнесем във макроси общи части от функции и набори от тестове. Ето един пример, осъществяващ и тестващ съставните оператори +=, *= и -= за Vec<T>:

use std::ops::{Add, Mul, Sub};

macro_rules! assert_equal_len {
    // Обозначителят `tt` (дърво с признаци) се използва за оператори и
    // признаци(опознавателни).
    ($a:expr, $b:expr, $func:ident, $op:tt) => {
        assert!($a.len() == $b.len(),
                "{:?}: несъответсвие в размерите: {:?} {:?} {:?}",
                stringify!($func),
                ($a.len(),),
                stringify!($op),
                ($b.len(),));
    };
}

macro_rules! op {
    ($func:ident, $bound:ident, $op:tt, $method:ident) => {
        fn $func<T: $bound<T, Output=T> + Copy>(xs: &mut Vec<T>, ys: &Vec<T>) {
            assert_equal_len!(xs, ys, $func, $op);

            for (x, y) in xs.iter_mut().zip(ys.iter()) {
                *x = $bound::$method(*x, *y);
                // *x = x.$method(*y);
            }
        }
    };
}

// Осъществяваме функциите `add_assign`, `mul_assign` и `sub_assign`.
op!(add_assign, Add, +=, add);
op!(mul_assign, Mul, *=, mul);
op!(sub_assign, Sub, -=, sub);

mod test {
    use std::iter;
    macro_rules! test {
        ($func:ident, $x:expr, $y:expr, $z:expr) => {
            #[test]
            fn $func() {
                for size in 0usize..10 {
                    let mut x: Vec<_> = iter::repeat($x).take(size).collect();
                    let y: Vec<_> = iter::repeat($y).take(size).collect();
                    let z: Vec<_> = iter::repeat($z).take(size).collect();

                    super::$func(&mut x, &y);

                    assert_eq!(x, z);
                }
            }
        };
    }

    // Тестваме `add_assign`, `mul_assign` и `sub_assign`.
    test!(add_assign, 1u32, 2u32, 3u32);
    test!(mul_assign, 2u32, 3u32, 6u32);
    test!(sub_assign, 3u32, 2u32, 1u32);
}
$ rustc --test dry.rs && ./dry
running 3 tests
test test::mul_assign ... ok
test test::add_assign ... ok
test test::sub_assign ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured

Б. пр.

1

НСП (Не Се Повтаряй!) – DRY (Don't Repeat Yourself)

Езици с особено предназначение (ЕОП)

Един ЕОП е малък език, внедрен в макроси на Ръждьо. Това си е напълно действащ Ръждьо, защото уредбата за макроси го разгръща в обикновени изявления и изрази на Ръждьо, но изглежда като малък език. Това ви позволява да опишете сбит или самовиден1 правопис за някакви особени (ограничени) дейности.

Да предположим, че искам да опиша ВП (Външност за Приложение)2 за калкулатор. Бих искал да мога, като напиша математически израз, изходът да се изведе на конзолата.

macro_rules! calculate {
    (eval $e:expr) => {
        {
            let val: usize = $e; // Насилваме типовете да са цели числа
            println!("{} = {}", stringify!{$e}, val);
        }
    };
}

fn main() {
    calculate! {
        eval 1 + 2 // Хи-хи, `eval` _не е_ ключова дума в Ръждьо!
    }

    calculate! {
        eval (1 + 2) * (3 / 4)
    }
}

Изход:

1 + 2 = 3
(1 + 2) * (3 / 4) = 0

Това беше простичък израз, но има разработени много по-сложни външности, като например lazy_static или clap.

Обърнете внимание и на двете двойки фигурни скоби в макроса. Външните са част от правописа на macro_rules!, в допълнение към () или [].

Б. пр.

1

самовиден (очевиден, саморазбиращ се) – intuitive (self-evident).

2

ВП (Външност за Приложение) – API (Application Programmming Interface)

Променлив брой аргументи

Една външност с променлив брой аргументи1 приема произволен брой аргументи. Например println! може да приеме произволен брой аргументи в зависимост от означенията в низа за форматиране.

Можем да разширим нашия макрос calculate! от предния раздел да приема променлив брой податки:

macro_rules! calculate {
    // Образецът за единичен `eval`
    (eval $e:expr) => {
        {
            let val: usize = $e; // Насилваме типовете да са цели числа 
            println!("{} = {}", stringify!{$e}, val);
        }
    };

    // Рекурсивно разграждаме множество `eval`и
    (eval $e:expr, $(eval $es:expr),+) => {{
        calculate! { eval $e }
        calculate! { $(eval $es),+ }
    }};
}

fn main() {
    calculate! { // Мамууу! Произволен `calculate!`!
        eval 1 + 2,
        eval 3 + 4,
        eval (2 * 3) + 1
    }
}

Изход:

1 + 2 = 3
3 + 4 = 7
(2 * 3) + 1 = 7

Б. пр.

1

Външности с променлив брой аргументи – Variadic interfaces

Обработка на грешки

Обработка на грешки1 е действието, което се предприема в случай на провал. Например, ако продължим изпълнението на програмата въпреки неуспешно прочитане на файл, определено ще имаме затруднения с използването на входните данни. Отчитането и изричното управление на тези грешки спасява програмата от по-нататъшни провали.

В Ръждьо има различни начини за справяне с грешки. Те са описани в следващите раздели на тази глава. Всички те имат едва доловими разлики помежду си и се ползват в различни случаи. Ето някои общи правила:

Изрична паника, panic, върши работа най-вече за писане на тестове и за справяне с непоправими грешки. Тя може да бъде полезна, например при работа с все още недописани функции, но в тези случаи по-описателното съобщение, извеждано от макроса unimplemented! е къде по-добро. В тестовете panic е разумен начин за изрично посочване на неуспех.

Типът Option се ползва, когато дадена стойност е незадължителна, или когато липсата на стойност не е недопустимо състояние. Например липсата на наддиректория – / и C: си нямат такава. Няма страшно да ползваме метода unwrap от броителя Option, докато скицираме програмата си, или когато сме напълно сигурни, че ще върне стойност. Обаче expect върши по-добра работа, защото ни дава възможност да зададем съобщение в случай на грешка.

Когато има вероятност нещо да се обърка и извикващият блок трябва да се оправя с грешката, ползвайте Result. Може да разгънете (unwrap), а и да очаквате (expect) грешките. Но моля, по-добре е да ползвате тези методи само при бързи тестове и докато скицирате програмата си.

По-обстойно раглеждане на обработката на грешки ще намерите в съответната глава от Книгата.

Б. пр.

1

Обработка на грешки – Error handling

2

Книгата – the book "The Rust Programming Language". https://doc.rust-lang.org/book/ch09-00-error-handling.html

panic

Най-простата обработка на грешки е panic. Този макрос извежда съобщение за грешка, започва да размотава стълпа и обикновено прекратява програмата. Тук изрично извикваме panic при нашето условие за грешка:

fn drink(beverage: &str) {
    // Не бива да пиете твърде много сладки напитки.
    if beverage == "lemonade" { panic!("AAAaaaaa!!!!"); }

    println!("Просто ми трябва нещо освежаващо като {}.", beverage);
}

fn main() {
    drink("water");
    drink("lemonade");
    drink("still water");
}

Първото извикване на drink работи, а второто се паникьосва, така че до третото не достигаме никога.

abort и unwind

Предният раздел показа механизма за обработка на грешки panic. Различните пътища, по които поема кодът, могат да бъдат компилирани условно в зависимост от настройката за panic. Текущите налични стойности са „размотаване“ (unwind) и „преждевременно прекратяване” (abort).

Ако разработим предния пример с лимонадата, можем изрично да ползваме стратегията за паникьосване, за да насочим програмата по различен път.


fn drink(beverage: &str) {
   // Не бива да пиете твърде много сладки напитки.
    if beverage == "lemonade" {
        if cfg!(panic="abort"){ println!("Това не е вашият купон. Беж!!!!");}
        else{ println!("Изплюйте!!!!");}
    }
    else{ println!("Просто ми трябва нещо освежаващо като {}.", beverage); }
}

fn main() {
    drink("water");
    drink("lemonade");
}

Ето друг пример, който пренаписва drink() и използва изрично ключовата дума unwind.


#[cfg(panic = "unwind")]
fn ah(){ println!("Изплюйте!!!!");}

#[cfg(not(panic="unwind"))]
fn ah(){ println!("Това не е вашият купон. Беж!!!!");}

fn drink(beverage: &str){
    if beverage == "lemonade"{ ah();}
    else{println!("Просто ми трябва нещо освежаващо като {}.", beverage);}
}

fn main() {
    drink("water");
    drink("lemonade");
}

Стратегията за паникьосване може да бъде зададена на командния ред, като ползваме abort или unwind.

rustc  lemonade.rs -C panic=abort

Option и unwrap

В последния пример показахме, че можем да предизвикаме срив по желание. Казахме на програмата да се паникьоса (panic), ако пием лимонада с много захар. Но какво да правим, ако очакваме някакво (some), а не получим никакво питие? Такава развръзка също е лоша и трябва да се справим и с нея.

Бихме могли да пробваме какво ще стане, ако ни се подаде празен низ ("") – никакво питие. Понеже пишем на Ръждьо, нека накараме компилатора да ни покаже случаите, в които няма питие.

В стандартната библиотека има един броител (enum), наречен Option<T> – Избор<Т>. Той се ползва, когато има вероятност да липсва някаква стойност, която очакваме. Проявява се в две възможности за избор:

  • Some(T) – Някакво(T): Намерена е някаква стойност от типT;
  • None – Нищо: Няма никаква стойност.

Тези две възможности могат да бъдат обработени или изрично с помощта на match, или мълчаливо чрез unwrap. Мълчаливата обработка или ще върне вътрешната стойност (ще я разгърне), или ще паникьоса (panic) програмата ни.

Забележете, че е възможно да управляваме паниката с помощта на expect, а от друга страна, unwrap ни дава по-несмислен изход, отколкото изричната обработка. В следния пример изричната обработка на грешката произвежда по-управляем изход, като оставя възможността за паникьосване, ако желаем.

// Възрастният е видял всичко и може да обработи всяко питие добре.
// Всички питиета се обработват изрично с `match`.
fn give_adult(drink: Option<&str>) {
    // Указваме поведение за всеки от случаите.
    match drink {
        Some("лимонада") => println!("Ъъъ! Много сладко."),
        Some(inner) => println!("{}? Колко любезно.", inner),
        None => println!("Няма питие? Е, добре."),
    }
}

// Други ще се `panic`ьосат при вида на сладки питиета.
// Всички питиета са обработени чрез разгъване – `unwrap`.
fn drink(drink: Option<&str>) {
    // `unwrap` връща `panic`, когато получи `None`.
    let вътре = drink.unwrap();
    if вътре == "лимонада" {
        panic!("AAAaaaaa!!!!");
    }

    println!("Обичам {}!!!!", вътре);
}

fn main() {
    let water = Some("вода");
    let lemonade = Some("лимонада");
    let void = None;

    give_adult(water);
    give_adult(lemonade);
    give_adult(void);

    let coffee = Some("кафе");
    let nothing = None;

    drink(coffee);
    drink(nothing);
}

Разопаковане на избори със ?

Може да разопаковате Option с изявления match, но често е по-лесно да се ползва операторът ?. Ако x е Option, то тогава, като изпълните x?, то ще върне вътрешната стойност, ако x е Some. Иначе ще прекъсне функцията, в която се намира, и ще върне None.

fn next_birthday(current_age: Option<u8>) -> Option<String> {
	// Ако `current_age` е `None`, това връща `None`.
	// Ако `current_age` е `Some`, вътрешната стойност от тип `u8` + 1
    // бива присвоена на `next_age`
    let next_age: u8 = current_age? + 1;
    Some(format!("Следващата година ще съм на {} години.", next_age))
}

Може да навържете много ? един след друг, за да направите кода си по-четим.

#![allow(dead_code)]
#[derive(Debug)]
struct Person {
    job: Option<Job>,
}

#[derive(Clone, Copy, Debug)]
struct Job {
    phone_number: Option<PhoneNumber>,
}

#[derive(Clone, Copy, Debug)]
struct PhoneNumber {
    area_code: Option<u8>,
    number: u32,
}

impl Person {
    // Взима областния код от служебния телефонен номер на лицето, ако го има.
    fn work_phone_area_code(&self) -> Option<u8> {
        // Без оператора `?` тук щеше да има много вгнездени едно в друго
        // изявления `match`.
        // Кодът щеше да е много повече. Опитайте да го напишете сами и
        // вижте кое е по-лесно.
        self.job?.phone_number?.area_code
    }
}

fn main() {
    let p = Person {
        job: Some(Job {
            phone_number: Some(PhoneNumber {
                area_code: Some(61),
                number: 439222222,
            }),
        }),
    };

    println!("{p:#?}");
    assert_eq!(p.work_phone_area_code(), Some(61));
}

Съчетатели: map

match върши работа за обработка на избори (Option). Ако обаче го ползвате много, може да ви се види досадно, особено за действия, които работят само с определени входни данни. В тези случаи можем да ползваме съчетатели1 за управление на програмния поток като отделни части.

Option има вграден метод, наречен map() (съпоставяне, сравнение), който е съчетател за простите сравнения Some -> Some и None -> None. Повече извиквания на map() може да се наредят верижно, така че изходът от първия да извиква следващия, за постигане на повече гъвкавост.

В следния пример функцията process() в много сбит вид замества всички функции, използвани преди това.

#![allow(dead_code)]

#[derive(Debug)] enum Food { Apple, Carrot, Potato }

#[derive(Debug)] struct Peeled(Food);
#[derive(Debug)] struct Chopped(Food);
#[derive(Debug)] struct Cooked(Food);

// Белим нещо за ядене. Ако няма нищо за белене, връщаме `None`.
// Иначе връщаме обеленото.
fn peel(food: Option<Food>) -> Option<Peeled> {
    match food {
        Some(food) => Some(Peeled(food)),
        None       => None,
    }
}

// Нарязваме. Ако няма какво, връщаме `None`.
// Иначе връщаме нарязаното.
fn chop(peeled: Option<Peeled>) -> Option<Chopped> {
    match peeled {
        Some(Peeled(food)) => Some(Chopped(food)),
        None               => None,
    }
}

// Готвим. Тук показваме как вместо `match` за обработка на
// различните случаи се ползва `map()`.
fn cook(chopped: Option<Chopped>) -> Option<Cooked> {
    chopped.map(|Chopped(food)| Cooked(food))
}

// Една функция за белене, рязане и готвене – всичко това последователно.
// Навръзваме няколко извиквания на `map()`, за да опростим кода.
fn process(food: Option<Food>) -> Option<Cooked> {
    food.map(|f| Peeled(f))
        .map(|Peeled(f)| Chopped(f))
        .map(|Chopped(f)| Cooked(f))
}

// Проверяваме има ли храна, преди да се опитаме да ядем!
fn eat(food: Option<Cooked>) {
    match food {
        Some(food) => println!("Мммм… Обичам {:?}!", food),
        None       => println!("О, не! Не става за ядене."),
    }
}

fn main() {
    let apple = Some(Food::Apple);
    let carrot = Some(Food::Carrot);
    let potato = None;

    let cooked_apple = cook(chop(peel(apple)));
    let cooked_carrot = cook(chop(peel(carrot)));
    // Сега да опитаме по-простичко изглеждащата `process()`.
    let cooked_potato = process(potato);

    eat(cooked_apple);
    eat(cooked_carrot);
    eat(cooked_potato);
}

Б. пр.

1

съчетатели, съединители – combinators. Съчетателите са функции от по-високо ниво, които прилагат функции и по-рано описани съчетатели, за да произведат някакъв изход от подадените им данни. Те може да се ползват за управление на програмния поток като отделни части.

Вижте също:

затваряния, Option, Option::map()

Съчетатели: and_then

Описахме map() като начин за верижно изпълнение и опростяване на изявления match. Но ако използваме map() с функция, която връща Option<T>, получаваме вгнезден избор Option<Option<T>>. В такива случаи, ако имаме верижно изпълнение, може да стане объркващо. Тук идва редът на друг съчетател, познат в някои езици като плоскосъпоставяне (flatmap). Този съчетател се нарича and_then() – и_после().

and_then() извиква подадената ѝ функция с обгърната стойност и връща резултата. Ако изборът (Option) е None, тогава връща None.

В следващия пример cookable_v3() връща Option<Food>. Ако ползвахме map() вместо and_then(), щяхме да получим Option<Option<Food>>, което е неподходящ тип за eat().

#![allow(dead_code)]

#[derive(Debug)] enum Food { CordonBleu, Steak, Sushi }
#[derive(Debug)] enum Day { Monday, Tuesday, Wednesday }

// Нямаме съставки, за да направим Суши.
fn have_ingredients(food: Food) -> Option<Food> {
    match food {
        Food::Sushi => None,
        _           => Some(food),
    }
}

// Имаме рецепти за всичко освен за Кордон Бльо.
fn have_recipe(food: Food) -> Option<Food> {
    match food {
        Food::CordonBleu => None,
        _                => Some(food),
    }
}

// За да направим ястие, ни трябват и рецептата, и съставките.
// Можем да представим логиката като верига от съвпадения `match`:
fn cookable_v1(food: Food) -> Option<Food> {
    match have_recipe(food) {
        None       => None,
        Some(food) => have_ingredients(food),
    }
}

// Това може да се пренапише много по-сбито с `and_then()`:
fn cookable_v3(food: Food) -> Option<Food> {
    have_recipe(food).and_then(have_ingredients)
}

// Иначе ще трябва да сплескаме (`flatten()`) една `Option<Option<Food>>`,
// за да получим `Option<Food>`:
fn cookable_v2(food: Food) -> Option<Food> {
    have_recipe(food).map(have_ingredients).flatten()
}

fn eat(food: Food, day: Day) {
    match cookable_v3(food) {
        Some(food) => println!("Еха! В {:?} ще ядем {:?}.", day, food),
        None       => println!("О, не. Няма да ядем в {:?}?", day),
    }
}

fn main() {
    let (cordon_bleu, steak, sushi) = (Food::CordonBleu, Food::Steak, Food::Sushi);

    eat(cordon_bleu, Day::Monday);
    eat(steak, Day::Tuesday);
    eat(sushi, Day::Wednesday);
}

Вижте също:

затваряния, Option, Option::and_then() и Option::flatten()

Разопаковане на избори и стойности по подразбиране

Има няколко начина за разгъване на Option и връщане на стойност по подразбиране, ако проверяваната стойност е None. За да изберем най-подходящия начин, трябва да преценим следното:

  • дали ни е нужно алчно или лениво изчисление на подадения запасен аргумент?
  • дали трябва да запазим първоначалната празна стойност, или да я променим на място?

методът or – верижен, алчен, не пипа празната стойност

pub fn or(self, optb: Option<T>) -> Option<T> може да се изпълнява верижно (няколко пъти последователно), а запасният му аргумент се изчислява алчно, както се вижда от следващия пример. Забележете, че понеже аргументът бива оценен алчно, стойността на подадената на or променлива бива преместена.

#[derive(Debug)] 
enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }

fn main() {
    let apple = Some(Fruit::Apple);
    let orange = Some(Fruit::Orange);
    let no_fruit: Option<Fruit> = None;

    let first_available_fruit = no_fruit.or(orange).or(apple);
    println!("first_available_fruit: {:?}", first_available_fruit);
    // first_available_fruit: Some(Orange)

    // `or` премества аргумента си.
    // В горния пример `or(orange)` връща `Some`, така че `or(apple)` не се
    // извиква. Но въпреки това стойността на променливата `apple` бива
    // преместена и не може да се ползва повече.
    // println!("Променливата apple е преместена, така че този ред
    // няма да се компилира: {:?}", apple);
    // ЗАДАЧА: Разкоментирайте горния ред, за да видите грешката при компилиране.
 }

методът or_else – верижен, ленив, не пипа празната стойност

Друга възможност е да ползвате pub fn or_else<F>(self, f: F) -> Option<T> where F: FnOnce() -> Option<T>,. Той също може да бъде извикан верижно, а подаденият му като запасен аргумент, който е функция или затваряне, бива изчислен лениво. Вижте следния пример.

#[derive(Debug)] 
enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }

fn main() {
    let apple = Some(Fruit::Apple);
    let no_fruit: Option<Fruit> = None;
    let get_kiwi_as_fallback = || {
        println!("Предоставяме киви в запас");
        Some(Fruit::Kiwi)
    };
    let get_lemon_as_fallback = || {
        println!("Предоставяме лимон в запас");
        Some(Fruit::Lemon)
    };

    let first_available_fruit = no_fruit
        .or_else(get_kiwi_as_fallback)
        .or_else(get_lemon_as_fallback);
    println!("first_available_fruit: {:?}", first_available_fruit);
    // Предоставяме киви в запас
    // first_available_fruit: Some(Kiwi)
}

методът get_or_insert – алчен, променя празната стойност на място

За да се подсигурим, че даден Избор съдържа стойност, можем да ползваме pub fn get_or_insert(&mut self, value: T) -> &mut T, за да го променим на място, като му дадем стойност по подразбиране. Забележете, че get_or_insert изчислява запасния аргумент алчно, така че стойността на променливата apple бива преместена:

#[derive(Debug)]
enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }

fn main() {
    let mut моят_плод: Option<Fruit> = None;
    let apple = Fruit::Apple;
    let първият_наличен_плод = моят_плод.get_or_insert(apple);
    println!("първият_наличен_плод е: {:?}", първият_наличен_плод);
    println!("моят_плод е: {:?}", моят_плод);
    // първият_наличен_плод е: Apple
    // my_fruit е: Some(Apple)
    //println!("Стойността на `apple` е преместена: {:?}", apple);
    // ЗАДАЧА: разкоментирайте горния ред, за да видите грешката при
    // компилиране
}

методът get_or_insert_with – ленив, променя празната стойност на място

Вместо изрично да подаваме стойност за връщане, можем да подадем затваряне на pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut T where F: FnOnce() -> T,, както следва:

#[derive(Debug)] 
enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }

fn main() {
    let mut my_fruit: Option<Fruit> = None;
    let get_lemon_as_fallback = || {
        println!("Предоставяме лимон в запас");
        Fruit::Lemon
    };
    let first_available_fruit = my_fruit
        .get_or_insert_with(get_lemon_as_fallback);
    println!("first_available_fruit е: {:?}", first_available_fruit);
    println!("my_fruit е: {:?}", my_fruit);
    // Предоставяме лимон в запас
    // first_available_fruit is: Lemon
    // my_fruit is: Some(Lemon)

    // Ако Option има стойност, тя не се променя и затварянето не се извиква
    let mut my_apple = Some(Fruit::Apple);
    let ше_да_е_ябълка = my_apple.get_or_insert_with(get_lemon_as_fallback);
    println!("ше_да_е_ябълка е: {:?}", ше_да_е_ябълка);
    println!("my_apple не е променена: {:?}", my_apple);
    // Изходът е, както следва. Забележете, че затварянето
    // `get_lemon_as_fallback` не е извикано.
    // ше_да_е_ябълка is: Apple
    // my_apple не е променена: Some(Apple)
}

Вижте също:

Затваряния, get_or_insert, get_or_insert_with, moved variables, or, or_else

Result

Result е по-богата разновидност на типа Option, която описва възможна грешка вместо възможна липса на стойност.

Сиреч, Result<T, E> може да има една от следните стойности:

  • Ok(T): Намерен е член от тип T
  • Err(E): Открита е грешка, чиято стойност е от тип E

Обичайно очакваният изход е Ok, а неочакваният изход е Err.

Както и Option, Result има много придадени методи. unwrap() например или произвежда член от тип T, или завършва програмата с panic. За обработка на различни случаи Result има много припокриващи се с Option съчетатели.

Докато работите с Ръждьо, вероятно ще се натъквате на методи, които връщат типа Result. Такъв е методът parse(). Не винаги е възможно да се извлече1 целевият тип при разбора на низ. Затова parse() връща Result, показващ възможност за неуспех.

Нека видим какво се случва, когато успешно и неуспешно правим разбор на низ (parse()):

fn multiply(first_number_str: &str, second_number_str: &str) -> i32 {
    // Нека пробваме да извлечем числото с `unwrap()`. Дали ще ни ухапе?
    let first_number = first_number_str.parse::<i32>().unwrap();
    let second_number: i32 = second_number_str.parse().unwrap();
    first_number * second_number
}

fn main() {
    let twenty = multiply("10", "2");
    println!("double is {}", twenty);

    let tt = multiply("t", "2");
    println!("double is {}", tt);
}

При неуспешния случай parse() връща грешка, така че unwrap() да се паникьоса. Освен това panic прекратява нашата програма и подава неприятно съобщение за грешка.

За да подобрим качеството на нашето съобщение за грешка, трябва да уточним какъв тип ще връщаме и да помислим как ще обработваме грешката.

Използване на Result в main

Типът Result може също да бъде връщан тип и на функцията main, ако укажем това изрично. Обичайно main има следния вид:

fn main() {
    println!("Hello World!");
}

Обаче main може да връща и Result. Ако се случи грешка във функцията main, тя ще върне код за грешка и ще отпечати подсказващо представяне на грешката (с помощта на отличителя Debug). Следният пример ни показва такъв развой и загатва за неща, които са разгледани в следващия раздел.

use std::num::ParseIntError;

fn main() -> Result<(), ParseIntError> {
    let number_str = "10";
    let number = match number_str.parse::<i32>() {
        Ok(number)  => number,
        Err(e) => return Err(e),
    };
    println!("{}", number);
    Ok(())
}

Б. пр.

1

раз-бир-ам, извличам, разбивам на парче-та – parse

map за Result

Ако просто се паникьосваме в предния пример с multiply, то кодът ни е немощен. Обикновено връщаме грешката към извикващия блок, за да може той да реши как правилно да я обработи.

Първо трябва да знаем с какъв вид грешка си имаме работа. За да определим типа вътре в Err, гледаме parse(), който е осъществен с отличителя FromStr за типа i32. Виждаме, че типът Err е указан като ParseIntError.

В примера по-долу иначе ясното изявление match води като цяло до по-труден за четене код.

use std::num::ParseIntError;

// Сега сме променили типа за връщане. Получаваме го чрез съпоставяне по
// образец (`match`), без да ползваме `unwrap()`.
fn multiply(first_number_str: &str, second_number_str: &str)
   -> Result<i32, ParseIntError> {
    match first_number_str.parse::<i32>() {
        Ok(first_number)  => {
            match second_number_str.parse::<i32>() {
                Ok(second_number)  => {
                    Ok(first_number * second_number)
                },
                Err(e) => Err(e),
            }
        },
        Err(e) => Err(e),
    }
}

fn print(result: Result<i32, ParseIntError>) {
    match result {
        Ok(n)  => println!("n е {}", n),
        Err(e) => println!("Грешка: {}", e),
    }
}

fn main() {
    // Това е по-смислен отговор.
    let twenty = multiply("10", "2");
    print(twenty);

    // Следното съобщение за грешка помага много повече.
    let tt = multiply("t", "2");
    print(tt);
}

За щастие, map, and_then и много други съчетатели от Option са осъществени също и за Result. Страницата с документацията на Result съдържа пълния списък.

use std::num::ParseIntError;

// Както с `Option`, и тук можем да ползваме съчетатели като `map()`.
// Тази функция, иначе същата като горе, се чете така:
// Умножаваме, ако и двете стойности могат да се извлекат от низа, иначе
// предаваме грешката нагоре.
fn multiply(first_number_str: &str, second_number_str: &str)
   -> Result<i32, ParseIntError> {
    first_number_str.parse::<i32>().and_then(|first_number| {
        second_number_str.parse::<i32>().map(|second_number|
            first_number * second_number)
    })
}

fn print(result: Result<i32, ParseIntError>) {
    match result {
        Ok(число)  => println!("числото е {}", число),
        Err(e) => println!("Грешка: {}", e),
    }
}

fn main() {
    // Това е по-смислен отговор.
    let twenty = multiply("10", "2");
    print(twenty);

    // Следното съобщение за грешка помага много повече.
    let tt = multiply("t", "2");
    print(tt);
}

Прякори за Result

Какво да правим, когато искаме да използваме определен тип Result многократно? Да си припомним, че Ръждьо ни позволява да създаваме прякори. За наше удобство можем да опишем прякор за точно определен Result.

Може да се окаже особено полезно да си създадем прякори за грешки само за един модул. Грешките в даден модул често имат един и същи тип Err. Така че с един прякор можем сбито да опишем всички подобни типове Result. Това е толкова полезно, че стандартната библиотека std дори предоставя такъв тип: io::Result!

Ето бърз пример, за да покажем как се пише:

use std::num::ParseIntError;

// Описваме обобщен прякор за `Result` с тип за грешка `ParseIntError`.
type AliasedResult<T> = Result<T, ParseIntError>;

// Използваме горния прякор за обръщение към нашия особен тип `Result`.
fn multiply(first_number_str: &str, second_number_str: &str)
   -> AliasedResult<i32> {
    first_number_str.parse::<i32>().and_then(|first_number| {
        second_number_str.parse::<i32>().map(|second_number|
            first_number * second_number)
    })
}

// Тук прякорът отново ни позволява да спестим малко място.
fn print(result: AliasedResult<i32>) {
    match result {
        Ok(n)  => println!("n is {}", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    print(multiply("10", "2"));
    print(multiply("t", "2"));
}

Вижте също:

io::Result

Ранни връщания

В предишния пример обработвахме грешките изрично с помощта на съчетатели. Друг начин да се справяме с подобни случаи е да ползваме съчетание от изявления match и ранни връщания.

Сиреч, можем просто да спрем изпълнението на функцията и да върнем грешката, ако има такава. За някои от нас този начин на писане може да се окаже по-лесен както за писане, така и за четене. Да разгледаме тази разновидност на предния пример, пренаписан с ранни връщания.

use std::num::ParseIntError;

fn multiply(first_number_str: &str, second_number_str: &str) -> Result<i32, ParseIntError> {
    let first_number = match first_number_str.parse::<i32>() {
        Ok(first_number)  => first_number,
        Err(e) => return Err(e),
    };

    let second_number = match second_number_str.parse::<i32>() {
        Ok(second_number)  => second_number,
        Err(e) => return Err(e),
    };

    Ok(first_number * second_number)
}

fn print(result: Result<i32, ParseIntError>) {
    match result {
        Ok(n)  => println!("n is {}", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    print(multiply("10", "2"));
    print(multiply("t", "2"));
}

Дотук се научихме да обработваме грешките изрично с помощта на съчетатели и ранни връщания. Въпреки че обикновено искаме да избегнем паникьосване, изричната обработка на грешки си е трудоемка.

В следващия раздел ще се запознаем със ? за случаите, в които просто искаме да разгърнем стойността (unwrap), но без да предизвикаме panic.

Запознаване със ?

Понякога ни се иска да имаме простотата на unwrap без вероятна panic-а. Досега unwrap ни принуждаваше да влизаме все по-надълбоко, а на нас просто ни трябваше стойността. Точно това е предназначението на ?.

При откриването на грешка (Err) има две възможни действия:

  1. panic!, което вече решихме, че е добре да се избягва по възможност;
  2. return, защото Err означава, че не можем да обработим това състояние.

? е почти1 точно съответствиe на unwrap, което при неуспех връща Err, вместо да извиква panic. Да видим как можем да опростим предния случай, където ползвахме съчетатели:

use std::num::ParseIntError;

fn multiply(first_number_str: &str, second_number_str: &str)
   -> Result<i32, ParseIntError> {
    let first_number = first_number_str.parse::<i32>()?;
    let second_number = second_number_str.parse::<i32>()?;

    Ok(first_number * second_number)
}

fn print(result: Result<i32, ParseIntError>) {
    match result {
        Ok(n)  => println!("n is {}", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    print(multiply("10", "2"));
    print(multiply("t", "2"));
}

Макросът try!

Допреди да имаше ?, същото постигахме с макроса try!. Сега се препоръчва операторът ?, но все още може да се натъкнете на try!, ако гледате по-стар код. Същата функция за умножение, multiply от предния пример, ще изглежда така с try!:

// За да компилирате и пуснете примера без грешки, докато ползвате Cargo,
// променете стойността на полето издание (`edition`) в раздела `[package]`
// на файла `Cargo.toml` да бъде "2015".
// За да компилиратe направо с rustc:
// rustc ./src/bin/error_result_try.rs  --edition 2015\
//  -o target/debug/error_result_try
// За да изпълните:
// target/debug/error_result_try


use std::num::ParseIntError;

fn multiply(first_number_str: &str, second_number_str: &str)
   -> Result<i32, ParseIntError> {
    let first_number = try!(first_number_str.parse::<i32>());
    let second_number = try!(second_number_str.parse::<i32>());

    Ok(first_number * second_number)
}

fn print(result: Result<i32, ParseIntError>) {
    match result {
        Ok(n)  => println!("n is {}", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    print(multiply("10", "2"));
    print(multiply("t", "2"));
}
1

въпросителен знак (?) – почти като unwrap. Вижте re-enter ? за още подробности.

Множество типове грешки

Предишните примери бяха все много удобни. Типовете Result си взаимодействаха с други Result, а типовете Option – с други Option.

Понякога се налага Option да взаимодейства с Result или Result<T, Error1> да взаимодейства с Result<T, Error2>. В тези случаи искаме да управляваме различните типове грешки така, че да са съставими и лесни за взаимодействие.

В следващия код две извиквания на unwrap създават различни типове грешки. Vec::first връща Option, докато parse::<i32> връща стойност от тип Result<i32, ParseIntError>:

fn double_first(vec: Vec<&str>) -> i32 {
    let first = vec.first().unwrap(); // Generate error 1
    2 * first.parse::<i32>().unwrap() // Generate error 2
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    println!("Първото удвоено е {}", double_first(numbers));

    println!("Първото удвоено е {}", double_first(empty));
    // Грешка 1: входният вектор е празен

    println!("Първото удвоено е {}", double_first(strings));
    // Грешка 2: първата стойност не може да бъде сведена до число
}

В следващите раздели ще видим няколко стратегии за справяне с този род проблеми.

Извличане на Result от Option

Най-лесният начин за справяне със смесени типове за грешки е като просто ги вгнездим един в друг.

use std::num::ParseIntError;

fn double_first(vec: Vec<&str>) -> Option<Result<i32, ParseIntError>> {
    vec.first().map(|first| {
        first.parse::<i32>().map(|n| 2 * n)
    })
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    println!("Първото удвоено е {:?}", double_first(numbers));

    println!("Първото удвоено е {:?}", double_first(empty));
    // Грешка 1: входният вектор е празен

    println!("Първото удвоено е {:?}", double_first(strings));
    // Грешка 2: първата стойност не може да бъде сведена до число
}

В някои случаи ще искаме да спрем изпълнението при грешка (като при ?), но да продължим, когато изборът Option е None. Няколко съчетателя може да ни дойдат отръки, ако искаме да сменим местата на Result и Option.

use std::num::ParseIntError;

fn double_first(vec: Vec<&str>) -> Result<Option<i32>, ParseIntError> {
    let opt = vec.first().map(|first| {
        first.parse::<i32>().map(|n| 2 * n)
    });

    opt.map_or(Ok(None), |r| r.map(Some))
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    println!("Първото удвоено е {:?}", double_first(numbers));
    println!("Първото удвоено е {:?}", double_first(empty));
    println!("Първото удвоено е {:?}", double_first(strings));
}

Описване на тип за грешка

Понякога кодът може да бъде опростен, като се маскират всички различни грешки с единен тип за грешка. Щем показа това с потребителска грешка.

Ръждьо ни позволява да описваме собствени типове за грешки. Ето общите изисквания за „добър” тип грешка:

  • Представя различни грешки чрез еднакъв тип;
  • Показва приятни на вид съобщения за грешка;
  • Лесен е за сравняване с други типове:
    • Добре: Err(EmptyVec);
    • Зле: Err("Please use a vector with at least one element".to_owned()).
  • Може да съдържа сведения за грешката:
    • Добре: Err(BadChar(c, position));
    • Зле: Err("+ cannot be used here".to_owned()).
  • Подхожда си с другите грешки.
use std::fmt;

type Result<T> = std::result::Result<T, DoubleError>;

// Описваме наши типове за грешки. Можем да ги нагодим за начина, по който
// обработваме грешките. Сега ще можем да пишем наши си грешки, да отпращаме към
// някакво вътрешно въплъщение на грешка, или пък нещо между двете.
#[derive(Debug, Clone)]
struct DoubleError;

// Хвърлянето на грешка е напълно отделно от това, как тя бива показвана.
// Не се притеснявайте, ако имате сложна логика в начина на показване.
//
// Забележете, че не съхраняваме никакви допълнителни данни за грешките.
// Това означава, че не можем да потвърдим точно кой низ не може да бъде разбран,
// без да променим нашите типове така, че те да носят тези данни със себе си.
impl fmt::Display for DoubleError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Първият член не може да бъде удвоен.")
    }
}

fn double_first(vec: Vec<&str>) -> Result<i32> {
    vec.first()
        // Променяме грешката да бъде от нашия нов тип.
        .ok_or(DoubleError)
        .and_then(|s| {
            s.parse::<i32>()
                // Тук също ползваме новия тип.
                .map_err(|_| DoubleError)
                .map(|i| 2 * i)
        })
}

fn print(result: Result<i32>) {
    match result {
        Ok(n) => println!("Първото удвоено е {}", n),
        Err(e) => println!("Грешка: {}", e),
    }
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    print(double_first(numbers));
    print(double_first(empty));
    print(double_first(strings));
}

Грешки в Кутии

Един начин за писане на прост код, запазвайки първоначалните грешки, е да ползваме Кутии. За съжаление, в този случай истинската грешка става известна едва по време на изпълнение и не е определена статично.

С помощта на стандартната библиотека можем да слагаме нашите грешки в кутии. Box може да превръща от всеки тип, осъществяващ отличителя Error, в обект от тип Box<Error> посредством From.

use std::error;
use std::fmt;

// Променяме прякора да ползва `Box<dyn error::Error>`.
type Result<T> = std::result::Result<T, Box<dyn error::Error>>;

#[derive(Debug, Clone)]
struct EmptyVec;

impl fmt::Display for EmptyVec {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Първият член не може да бъде удвоен.")
    }
}

impl error::Error for EmptyVec {}

fn double_first(vec: Vec<&str>) -> Result<i32> {
    vec.first()
        .ok_or_else(|| EmptyVec.into()) // Превръща в Box
        .and_then(|s| {
            s.parse::<i32>()
                .map_err(|e| e.into()) // Превръща в Box
                .map(|i| 2 * i)
        })
}

fn print(result: Result<i32>) {
    match result {
        Ok(n) => println!("Първият удвоен член е {}.", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    print(double_first(numbers));
    print(double_first(empty));
    print(double_first(strings));
}

Вижте също:

Dynamic dispatch и Error trait

Други ползвания на ?

Забележете, че в предния пример след разбора гледаме незабавно да сложим грешката от библиотеката в кутия:

.and_then(|s| s.parse::<i32>())
    .map_err(|e| e.into())

Тъй като това е просто действие, може да се окаже удобно да можем да го пропускаме. За съжаление, понеже and_then не е достатъчно гъвкав, това е невъзможно. Вместо това можем да ползваме ?.

Оперторът ? вече бе описан като „unwrap или return Err(err)”. Това не е съвсем вярно. ? всъщност означава „unwrap или return Err(From::from(err))”. Понеже From::from е средство за превръщане между различни типове, това означава, че ако извикаме оператора ?, където грешката може да бъде превърната в типа за връщане, той ще я превърне автоматично.

Тук пренаписваме предния пример да ползва ?. От това следва, че map_err вече не ни е нужна, щом From::from е осъществена за нашия тип за грешка:

use std::error;
use std::fmt;

// Променяме прякора за типа грешка да ползва `Box<dyn error::Error>`.
type Result<T> = std::result::Result<T, Box<dyn error::Error>>;

#[derive(Debug)]
struct EmptyVec;

impl fmt::Display for EmptyVec {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "invalid first item to double")
    }
}

impl error::Error for EmptyVec {}

// Същото построение като преди, но вместо да направим всички `Result` и
// `Option` верижни, ползваме оператора `?`, за да вземем и върнем вътрешната
// стойност незабавано.
fn double_first(vec: Vec<&str>) -> Result<i32> {
    let first = vec.first().ok_or(EmptyVec)?;
    let parsed = first.parse::<i32>()?;
    Ok(2 * parsed)
}

fn print(result: Result<i32>) {
    match result {
        Ok(n)  => println!("Удвоеният първи член е {}.", n),
        Err(e) => println!("Error: {}", e),
    }
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    print(double_first(numbers));
    print(double_first(empty));
    print(double_first(strings));
}

Сега е доста по-чистичко. В сравнение с първоначалната panic-а, това много наподобява на заместване на извикванията на unwrap със ?, само дето типът за връщане е Result. И сега само трябва да бъдат разложени при получване от извикващия.

Вижте също:

From::from и ?

Обгръщане на грешки

Вместо да слагаме грешките в кутии, можем да ги обгръщаме в наш собствен тип за грешка.

use std::error;
use std::error::Error;
use std::num::ParseIntError;
use std::fmt;

type Result<T> = std::result::Result<T, DoubleError>;

#[derive(Debug)]
enum DoubleError {
    EmptyVec,
    // Ще оставим грешката за извличане на цяло число да си се обработва от
    // първоначалния отличител. Допълнителните сведения за грешката изискват да
    // добавим повече данни към типа.
    Parse(ParseIntError),
}

impl fmt::Display for DoubleError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match *self {
            DoubleError::EmptyVec =>
                write!(f, "Моля, ползвайте вектор с поне един член."),
            // Обгърнатата грешка съдържа допълнителни сведения, а те са
            // достъпни чрез метода source().
            DoubleError::Parse(..) =>
                write!(f,
                    "Предоставеният низ не може да се обработи като цяло число."),
        }
    }
}

impl error::Error for DoubleError {
    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
        match *self {
            DoubleError::EmptyVec => None,
            // Причината е начинът, по който е осъществен типът за грешка. Грешката
            // е сведена тихомълком до обекта на отличителя `&error::Error`.
            // Това работи, защото същинският тип вече осъществява отличителя `Error`.
            DoubleError::Parse(ref e) => Some(e),
        }
    }
}


// Осъществяваме превръщането от `ParseIntError` в `DoubleError`.
// Това въплъщение ще бъде извикано автоматично от `?`, ако някоя грешка от тип 
// `ParseIntError` трябва да бъде превърната в `DoubleError`.
impl From<ParseIntError> for DoubleError {
    fn from(err: ParseIntError) -> DoubleError {
        DoubleError::Parse(err)
    }
}

fn double_first(vec: Vec<&str>) -> Result<i32> {
    let first = vec.first().ok_or(DoubleError::EmptyVec)?;
    // Тук ползваме въплъщението на `ParseIntError` от `From` (което описахме
    // горе), за да създадем `DoubleError`.
    let parsed = first.parse::<i32>()?;

    Ok(2 * parsed)
}

fn print(result: Result<i32>) {
    match result {
        Ok(n)  => println!("Първият удвоен член е {}.", n),
        Err(e) => {
            println!("Грешка: {}", e);
            if let Some(source) = e.source() {
                println!("  Причинена от : {}", source);
            }
        },
    }
}

fn main() {
    let numbers = vec!["42", "93", "18"];
    let empty = vec![];
    let strings = vec!["tofu", "93", "18"];

    print(double_first(numbers));
    print(double_first(empty));
    print(double_first(strings));
}

Този подход изисква повечко писане за обработка на грешките и не винаги е нужен. Има библиотеки, които могат да спестят осъществяването на обгръщането.

Вижте също:

From::from и Броители

Обхождане на Result-ати

Действието Iter::map може да не успее. Например:

fn main() {
    let strings = vec!["tofu", "93", "18"];
    let numbers: Vec<_> = strings
        .into_iter()
        .map(|s| s.parse::<i32>())
        .collect();
    println!("Резултати: {:?}", numbers);
}

Да видим как може да се подходи.

Да пропускаме неуспешно обработените единици с помощта на filter_map()

filter_map извиква функция и филтрира резултатите, които са None.

fn main() {
    let strings = vec!["tofu", "93", "18"];
    let numbers: Vec<_> = strings
        .into_iter()
        .filter_map(|s| s.parse::<i32>().ok())
        .collect();
    println!("Резултати: {:?}", numbers);
}

Да съберем провалите с помощта на map_err() и filter_map()

map_err извиква функция , като ѝ подава грешката. Ако добавим това към предното решение с filter_map, можем да съберем грешките, докато обхождаме.

fn main() {
    let strings = vec!["42", "tofu", "93", "999", "18"];
    let mut errors = vec![];
    let numbers: Vec<_> = strings
        .into_iter()
        .map(|s| s.parse::<u8>())
        .filter_map(|r| r.map_err(|e| errors.push(e)).ok())
        .collect();
    println!("Числа: {:?}", numbers);
    println!("Грешки: {:?}", errors);
}

Да предизвикаме неуспех на цялото действие чрез collect()

Result въплъщава FromIterator, така че един вектор, съдържащ резултати (Vec<Result<T, E>>), може да бъде превърнат в резултат, съдържащ вектор (Result<Vec<T>, E>). Щом се натъкнем на Result::Err, обхождането се прекратява.

fn main() {
    let strings = vec!["tofu", "93", "18"];
    let numbers: Result<Vec<_>, _> = strings
        .into_iter()
        .map(|s| s.parse::<i32>())
        .collect();
    println!("Резултати: {:?}", numbers);
}

Същата техника може да бъде приложена с Option.

Събираме всички действителни стойности и грешки с помощта на partition()

fn main() {
    let strings = vec!["tofu", "93", "18"];
    let (numbers, errors): (Vec<_>, Vec<_>) = strings
        .into_iter()
        .map(|s| s.parse::<i32>())
        .partition(Result::is_ok);
    println!("Числа: {:?}", numbers);
    println!("Грешки: {:?}", errors);
}

Ако погледнем резултатите, ще забележим, че всичко е все още обгърнато с Result. За да разгърнем стойностите, трябва да напишем още малко код.

fn main() {
    let strings = vec!["tofu", "93", "18"];
    let (numbers, errors): (Vec<_>, Vec<_>) = strings
        .into_iter()
        .map(|s| s.parse::<i32>())
        .partition(Result::is_ok);
    let numbers: Vec<_> = numbers.into_iter().map(Result::unwrap).collect();
    let errors: Vec<_> = errors.into_iter().map(Result::unwrap_err).collect();
    println!("Числа: {:?}", numbers);
    println!("Грешки: {:?}", errors);
}

Стандартни типове

Библиотеката std предоставя много потребителски типове, изградени на основата на първичните типове. Ето някои от тях:

  • низове с променлива дължина –String: "здравей, свят"
  • вектори с променлива дължина: [1, 2, 3]
  • типове за избор: Option<i32>
  • типове за обработка на грешки: Result<i32, i32>
  • указатели със заделено място на купа̀ (heap) в динамичната памет: Box<i32>

Вижте също:

първични типове и стандартна библиотека

Box, стълп и куп

По подразбиране Ръждьо слага всички стойности на стълп в паметта. Стойностите може да се сложат в кутии (Box<T>) и така да се сложат в купа̀. Кутията (Box<T>) е умен указател към стойност от тип T, за която е заделено място в купа̀. Когато кутия излезе от обхват, се извиква нейният унищожител, вътрешният обект се унищожава, а паметта на купа се освобождава.

Стойностите в кутии може да се достъпят пряко с помощта на оператора звезда – *. Така прескачаме един слой опосредстване1.

use std::mem;

#[allow(dead_code)]
#[derive(Debug, Clone, Copy)]
struct Point {
    x: f64,
    y: f64,
}

// Може да определим един правоъгълник по това къде в пространството се намират
// неговите горен ляв и долен десен ъгъл.
#[allow(dead_code)]
struct Rectangle {
    top_left: Point,
    bottom_right: Point,
}

fn origin() -> Point {
    Point { x: 0.0, y: 0.0 }
}

fn boxed_origin() -> Box<Point> {
    // Заделяме място за точката на купа и връщаме указател към нея.
    Box::new(Point { x: 0.0, y: 0.0 })
}

fn main() {
    // (всички отбелязвания за тип са излишни)
    // Променлива, сложена на стълпа
    let point: Point = origin();
    let rectangle: Rectangle = Rectangle {
        top_left: origin(),
        bottom_right: Point { x: 3.0, y: -4.0 }
    };

    // Променлива, сложена на купа̀
    let boxed_rectangle: Box<Rectangle> = Box::new(Rectangle {
        top_left: origin(),
        bottom_right: Point { x: 3.0, y: -4.0 },
    });

    // Изходът от функции може да се сложи в кутии
    let boxed_point: Box<Point> = Box::new(origin());

    // Двойно опосредстване
    let box_in_a_box: Box<Box<Point>> = Box::new(boxed_origin());

    println!("Точката заема {} байта на стълпа",
             mem::size_of_val(&point));
    println!("Правоъгълникът заема {} байта на стълпа",
             mem::size_of_val(&rectangle));

    // box size == pointer size
    println!("Точката в кутия заема {} байта на стълпа",
             mem::size_of_val(&boxed_point));
    println!("Правоъгълникът в кутия заема {} байта на стълпа",
             mem::size_of_val(&boxed_rectangle));
    println!("Кутията в кутия заема {} байта на стълпа",
             mem::size_of_val(&box_in_a_box));

    // Копираме данните, съдържащи се в `boxed_point` в `unboxed_point`
    let unboxed_point: Point = *boxed_point;
    println!("Точката без кутия заема {} байта на стълпа",
             mem::size_of_val(&unboxed_point));
}

Б. пр.

1

опосредстване – indirection

Вижте също

ПДИ

Вектори

Векторите са поредици с променлива дължина. Както при отрязъците, техният размер е неизвестен по време на компилиране, но могат да се уголемяват и смаляват по всяко време. Векторът се представя чрез три параметъра:

  • указател към данните1;
  • дължина2;
  • вместимост.

Вместимостта показва колко памет (в брой членове) е запазена за вектора. Векторът може да расте, доколкото дължината е по-малка от вместимостта. Когато този праг трябва да се премине, за вектора се заделя ново място в паметта с по-голяма вместимост (и данните биват преместени там).

fn main() {
    // Данните на повторителите могат да бъдат събрани във вектори
    let collected_iterator: Vec<i32> = (0..10).collect();
    println!("събрани (от 0 до 10) – (0..10) into: {:?}", collected_iterator);

    // Макросът `vec!` може да се ползва за създаване на вектор
    let mut xs = vec![1i32, 2, 3];
    println!("Първоначален вектор: {:?}", xs);

    // Добавяме нови членове към вектора
    println!("Бутаме 4 във вектора");
    xs.push(4);
    println!("Вектор: {:?}", xs);

    // Грешка! Неменим вектор не може да расте
    collected_iterator.push(0);
    // ПОПРАВКА ^ Коментирайте този ред

    // Методът `len` дава броя на членовете, съхранени във вектора
    println!("Vector length: {}", xs.len());

    // Посочването се прави с помощта на квадратни скоби
    // (посочването започва от 0)
    println!("Втори член: {}", xs[1]);

    // `pop` премахва последния член от вектора и го връща
    println!("Премахваме (pop) последния член: {:?}", xs.pop());

    // Посочване на член извън пределите на вектора предизвиква паника
    println!("Четвърти член: {}", xs[3]);
    // ПОПРАВКА ^ Коментирайте този ред

    // Векторите могат лесно да бъдат обхождани
    println!("Съдържание на:");
    for x in xs.iter() {
        println!("> {}", x);
    }

    // Векторите могат да бъдат обхождани и като поредният номер на стъпката се
    // слага в отделна променлива (`i`).
    for (i, x) in xs.iter().enumerate() {
        println!("На място {} имаме стойност {}", i, x);
    }

    // Благодарение на `iter_mut`, менимите `Vector`-и могат също да бъдат
    // обхождани така, че да може да се променя всяка стойност.
    for x in xs.iter_mut() {
        *x *= 3;
    }
    println!("Обновен вектор: {:?}", xs);
}

Още методи на Vec може да видите в модула std::vec.

Б. пр.

1

указател към данни – pointer to data

2

дължина – length

Низове

В Ръждьо има два типа низове: String и &str.

Типът String се съхранява като вектор от байтове (Vec<u8>), но е гарантирано, че това винаги ще бъде действителна UTF-8 последователност. Низовете се съхраняват в купа, могат да растат и не завършват с празен байт (\0).

Типът &str е отрязък (&[u8]), който винаги сочи към действителна UTF-8 последователност и може да се ползва за „поглеждане (четене)” в стойност от тип String, точно както &[T] е изглед1 във Vec<T>.

fn main() {
    // (всички отбелязвания на типове са излишни)
    // Препратка към низ, поместен в статичната памет (само за четене)
    let pangram: &'static str = "Хм, чужд щит, бърз гьон плюс яйце в шкаф.";
    println!("Панграм: {}", pangram);

    // Обхождаме думите наобратно, не се създава нов низ в паметта
    println!("Думите наобратно");
    for word in pangram.split_whitespace().rev() {
        println!("> {}", word);
    }

    // Копираме знаци във вектор, подреждаме по азбучен ред и премахваме
    // повтарящите се
    let mut chars: Vec<char> = pangram.chars().collect();
    chars.sort();
    chars.dedup();

    // Създаваме празен низ с променлива дължина
    let mut string = String::new();
    for c in chars {
        // Добавяме знак в края на низа
        string.push(c);
        // Добавяме низ в края на низа
        string.push_str(", ");
    }

    // Окастреният низ е отрязък от първоначалния низ, сиреч няма ново
    // поместване в паметта.
    let chars_to_trim: &[char] = &[' ', ','];
    let trimmed_str: &str = string.trim_matches(chars_to_trim);
    println!("Използвани знаци: {}", trimmed_str);

    // Поместване на низ в купа
    let alice = String::from("Харесвам кучета");
    // Заделяме нова памет и съхраняваме променения низ там
    let bob: String = alice.replace("кучета", "котки");

    println!("Алис казва: {}", alice);
    println!("Боб казва: {}", bob);
}

Още методи на str/String могат да се видят в модулите std::str и std::string.

Буквални стойности и избягване2

Има няколко начина да се пишат низови буквални стойности с особени знаци3 в тях. Всички биват създадени като &str, така че може да се въвеждат както ви е най-удобно. Също така има няколко начина да се пишат байтови низови буквални стойности, който се създават като &[u8; N].

Обичайно особените знаци се избягват с обратно наклонена черта: \. Така можем да добавим всякакъв знак към низ, дори непечатаеми и такива, които не знаем как да въведем. Ако искаме да въведем обратно наклонена черта, я избягваме с още една пред нея: \\.

Низовите или знакови разделители в буквална стойност трябва да се избягват с обратно наклонена черта: "\"", '\''.

fn main() {
    // Можем да ползваме избягване, за да пишем байтове чрез
    // шестнадесетичните им стойности…
    let byte_escape = "I'm writing \x52\x75\x73\x74!";
    println!("What are you doing\x3F (\\x3F means ?) {}", byte_escape);

    // …или кодовите им точки от Уникод.
    let unicode_codepoint = "\u{211D}";
    let character_name = "\"DOUBLE-STRUCK CAPITAL R\"";

    println!("Знакът от Уникод таблицата {} (U+211D) се нарича {}",
                unicode_codepoint, character_name );


    let long_string = "Низовите буквали
                        могат да се пишат на повече редове.
                        Краят на реда и отстъпът тук ->\
                        <- могат също да бъдат избегнати!";
    println!("{}", long_string);
}

Понякога има твърде много знаци за избягване или е много по-удобно да напишем низа така, както си е. Тук е мястото да се ползват сурови низови буkвални стойности4.

fn main() {
    let raw_str = r"Тук избягванията не работят: \x3F \u{211D}";
    println!("{}", raw_str);

    // Ако искаме кавички в суров низ, трябва да го оградим със # около
    // ограждащите кавички.
    let quotes = r#"И тогава си казах: "Няма спасение!""#;
    println!("{}", quotes);

    // Ако ни трябва "#, просто ползваме повече диези (#) за ограждане.
    // Диезите могат да бъдат до 65535.
    let longer_delimiter = r###"Низ със "# в него. И после даже "##!"###;
    println!("{}", longer_delimiter);
}

Искаме низ, който не е кодиран като UTF-8? (Да не забравяме, str и String трябва да са действителни UTF-8.) Или може би искаме поредица от байтове, която е почти само текст? Байтовите низове са нашето спасение!

use std::str;

fn main() {
    // Забележете, че това всъщност не е `&str`
    let bytestring: &[u8; 21] = b"this is a byte string";

    // Байтовите поредици не осъществяват отличителя `Display`, затова
    // печатането им е малко ограничено
    println!("Низ от байтове: {:?}", bytestring);

    // В байтовите низове може да има избягвания на байтове…
    let escaped = b"\x52\x75\x73\x74 as bytes";
    // …но не и на знаци от уникод
    // let escaped = b"\u{211D} не е позволен";
    println!("Някои избегнати байтове: {:?}", escaped);


    // Суровите байтови низове работят точно като суровите низове
    let raw_bytestring = br"\u{211D} тук не е избегнат";
    println!("{:?}", raw_bytestring);

    // Превръщането на байтова поредица в `str` може да се провали
    if let Ok(my_str) = str::from_utf8(raw_bytestring) {
        println!("И същото като текст: '{}'", my_str);
    }

    let _quotes = br#"Можете да използвате също и „причудливо“ форматиране, \
                    както при обичайните сурови низове"#;

    // Суровите низове не трябва задължително да са UTF-8
    // "ようこそ" в кодова таблица SHIFT-JIS
    let shift_jis = b"\x82\xe6\x82\xa8\x82\xb1\x82\xbb";

    // Но тогава не винаги могат да бъдат превърнати в `str`
    match str::from_utf8(shift_jis) {
        Ok(my_str) => println!("Превръщането е успешно: '{}'", my_str),
        Err(e) => println!("Превръщането не успя: {:?}", e),
    };
}

За превръщане между знакови кодирания прегледайте коша encoding.

По-подробен списък с описания на начините за писане на буквални низови стойности и за избягване на знаци е даден в главата „Признаци”5 на „Справочника на Ръждьо”.

Б. пр.

1

изглед – view

3

особени знаци – special characters

2

избягване – escape. Избягва се знак, който искаме да се покаже по различен начин от начина, по който би бил показан иначе, без да е поставена \ пред него.

4

сурови низови буkвални стойности – raw string literals

поместване в паметта, заделяне на памет – allocation

6

панграм – Панграмата ((ж. грамат. р.), наричана още панграм (pangram) (м. грамат. р.), от гръцки: παν γράμμα, pan gramma, „всяка буква“) е изречение, включващо всички букви (глифи/глифове) от дадена азбука (например българската, английската латиница или гръцката).

5

признак – token

Option

Понякога е желателно да прихванем срива на някои части от програмата, вместо да предизвикваме panic!; това може да се постигне с помощта на броителя Option1.

Броителят Option<T> има две разновидности:

  • None – указва неуспех или липса на стойност, и
  • Some(стойност) – разнородна структура, която обгръща дадената стойност от тип T.
// Целочислено деление, което не предизвиква `panic!`
fn checked_division(dividend: i32, divisor: i32) -> Option<i32> {
    if divisor == 0 {
        // Неуспехът е представен като разновидността `None`
        None
    } else {
        // Резултатът е обгърнат в разновидността `Some`
        Some(dividend / divisor)
    }
}

// Тази функция обработва деление, което може да не успее
fn try_division(dividend: i32, divisor: i32) {
    //Стойностите в `Option` може да се проверят чрез израз за намиране на
    // съответствия, като при всеки друг броител
    match checked_division(dividend, divisor) {
        None => println!("{} / {} failed!", dividend, divisor),
        Some(quotient) => {
            println!("{} / {} = {}", dividend, divisor, quotient)
        },
    }
}

fn main() {
    try_division(4, 2);
    try_division(1, 0);

    // Когато обвързваме `None` с променлива, трябва да отбележим типа
    let none: Option<i32> = None;
    let _equivalent_none = None::<i32>;

    let optional_float = Some(0f32);

    // Трябва да извадим стойността от `Some` чрез разгръщане – `unwrap()`.
    println!("{:?} се разгъва до {:?}", optional_float, optional_float.unwrap());

    // Ако се опитаме да разгърнем разновидност `None`, ще предизвикаме `panic!`.
    println!("{:?} unwraps to {:?}", none, none.unwrap());
}

Б. пр.

1

Избор – Option

Result

Видяхме, че броителят Option може да се ползва като стойност за връщане от функции, които може да не успеят, като можем да върнем None при неуспех. Понякога обаче е важно да кажем защо действието не е успяло. За тази цел разполагаме с броителя Result – Изход|Резултат.

Result<T, E> има две разновидности:

  • Ok(стойност), което означава, че действието е успешно и обгръща стойност-та, върната от действието. (стойност е от тип T);
  • Err(защо), което означава, че действието е неуспешно и обгръща защо, което (надяваме се) обяснява причината за неуспеха. (защо е от тип E).
mod checked {
    // Математически „грешки”, който искаме да прихванем
    #[derive(Debug)]
    pub enum MathError {
        DivisionByZero,
        NonPositiveLogarithm,
        NegativeSquareRoot,
    }

    pub type MathResult = Result<f64, MathError>;

    pub fn div(x: f64, y: f64) -> MathResult {
        if y == 0.0 {
            // Това действие може да не успее. Нека върнем причината, обгърната
            // в `Err`
            Err(MathError::DivisionByZero)
        } else {
            // Това действие е правилно – връщаме изхода от него, загърнат в
            // `Ok`.
            Ok(x / y)
        }
    }

    pub fn sqrt(x: f64) -> MathResult {
        if x < 0.0 {
            Err(MathError::NegativeSquareRoot)
        } else {
            Ok(x.sqrt())
        }
    }

    pub fn ln(x: f64) -> MathResult {
        if x <= 0.0 {
            Err(MathError::NonPositiveLogarithm)
        } else {
            Ok(x.ln())
        }
    }
}

// `op(x, y)` === `sqrt(ln(x / y))`
fn op(x: f64, y: f64) -> f64 {
    // Това е пирмида за намиране на съвпадения на три нива!
    match checked::div(x, y) {
        Err(why) => panic!("{:?}", why),
        Ok(ratio) => match checked::ln(ratio) {
            Err(why) => panic!("{:?}", why),
            Ok(ln) => match checked::sqrt(ln) {
                Err(why) => panic!("{:?}", why),
                Ok(sqrt) => sqrt,
            },
        },
    }
}

fn main() {
    // Дали това ще се провали?
    println!("{}", op(1.0, 10.0));
}

?

Навръзването на резултати с match може да се окаже трудночетимо. За щастие операторът ? може да подобри четимостта. ? се ползва в края на изрази, които връщат стойност, обгърната в Result, и е същото като в израза match, като разклонението за обработка на резултата Err(err) се изпълнява като ранно връщане – return Err(From::from(err)), а разклонението Ok(ok) връща израз ok.

mod checked {
    #[derive(Debug)]
    enum MathError {
        DivisionByZero,
        NonPositiveLogarithm,
        NegativeSquareRoot,
    }

    type MathResult = Result<f64, MathError>;

    fn div(x: f64, y: f64) -> MathResult {
        if y == 0.0 {
            Err(MathError::DivisionByZero)
        } else {
            Ok(x / y)
        }
    }

    fn sqrt(x: f64) -> MathResult {
        if x < 0.0 {
            Err(MathError::NegativeSquareRoot)
        } else {
            Ok(x.sqrt())
        }
    }

    fn ln(x: f64) -> MathResult {
        if x <= 0.0 {
            Err(MathError::NonPositiveLogarithm)
        } else {
            Ok(x.ln())
        }
    }

    // Междинна функция 
    fn op_(x: f64, y: f64) -> MathResult {
        // Ако `div` не мине, ще бъде върнато `DivisionByZero`.
        let ratio = div(x, y)?;

        // Ако `ln` не мине, ще бъде върнато `NonPositiveLogarithm`
        let ln = ln(ratio)?;

        sqrt(ln)
    }

    pub fn op(x: f64, y: f64) {
        match op_(x, y) {
            Err(why) => panic!("{}", match why {
                MathError::NonPositiveLogarithm
                    => "Логаритъм от отрицателно число!",
                MathError::DivisionByZero
                    => "Деление на нула!",
                MathError::NegativeSquareRoot
                    => "Корен квадратен от отрицателно число!",
            }),
            Ok(value) => println!("{}", value),
        }
    }
}

fn main() {
    checked::op(1.0, 10.0);
}

Не забравяйте да погледнете документацията, тъй като там има много методи за обвързване и създаване на Result.

panic!

Макросът panic! може да се ползва за създаване на паника и да започне да размотава стълпа си. Докато се размотава стълпът, средата за изпълнение1 се грижи да освободи всички данни, които са във владение на нишката, като извиква унищожителите на всичките ѝ обекти.

Понеже работим само с еднонишкови програми, panic! предизвиква програмата да покаже паническото съобщение и да приключи.

// Ново осъществяване на целочислено деление – (/)
fn division(dividend: i32, divisor: i32) -> i32 {
    if divisor == 0 {
        // Деление на нула предизвиква паника
        panic!("деление на нула");
    } else {
        dividend / divisor
    }
}

// The `main` task
fn main() {
    // Цяло число, поместено в купа̀
    let _x = Box::new(0i32);

    // Това действие ще доведе до провал на задачата.
    division(3, 0);

    println!("Няма да стигнем дотук!");

    // `_x` би трябвало да се унищожи тук.
}

Нека видим, че panic! не създава утечки в паметта.

$ rustc panic.rs && valgrind ./panic
==4401== Memcheck, a memory error detector
==4401== Copyright (C) 2002-2013, and GNU GPL'd, by Julian Seward et al.
==4401== Using Valgrind-3.10.0.SVN and LibVEX; rerun with -h for copyright info
==4401== Command: ./panic
==4401== 
thread '<main>' panicked at 'division by zero', panic.rs:5
==4401== 
==4401== HEAP SUMMARY:
==4401==     in use at exit: 0 bytes in 0 blocks
==4401==   total heap usage: 18 allocs, 18 frees, 1,648 bytes allocated
==4401== 
==4401== All heap blocks were freed -- no leaks are possible
==4401== 
==4401== For counts of detected and suppressed errors, rerun with: -v
==4401== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)

Б. пр.

1

средата за изпълнение – the runtime

HashMap

Докато векторите съхраняват стойностите си в поредица, в която всяка стойност се достъпва чрез показалец – поредното ѝ число, то безредиците1 (HashMap) съхраняват стойностите си с показалци-ключове. Безредните ключове могат да бъдат булеви стойности, цели числа, низове или всеки друг тип, осъществяващ отличителите Eq и Hash. Повече за това ще научим в следващия радел.

Както векторите, и безредиците могат да растат, но могат и сами да се свиват, ако част от заеманата от тях памет не се използва. Можем да създадем безредица с някаква начална вместимост2 с помощта на HashMap::with_capacity(uint) или пък HashMap::new() с някаква вместимост по подразбиране (препоръчва се).

use std::collections::HashMap;

fn call(number: &str) -> &str {
    match number {
        "798-1364" => "Съжаляваме, обаждането не може да се осъществи.
            Молим, затворете и опитайте по-късно.",
        "645-7689" => "Здравейте, свързахте се със Страхотен Пицов. Аз съм Фред.
            Какво ще поръчате днес?",
        _ => "Здравейте! Кой е пак?"
    }
}

fn main() { 
    let mut contacts = HashMap::new();

    contacts.insert("Daniel", "798-1364");
    contacts.insert("Ashley", "645-7689");
    contacts.insert("Katie", "435-8291");
    contacts.insert("Robert", "956-1745");

    // Приема препратка и връща Option<&V>
    match contacts.get(&"Daniel") {
        Some(&number) => println!("Обаждаме се на Даниел: {}", call(number)),
        _ => println!("Нямаме номера на Даниел."),
    }

    // `HashMap::insert()` връща `None`,
    // ако въведеният номер е нов, иначе `Some(value)`
    contacts.insert("Daniel", "164-6743");

    match contacts.get(&"Ashley") {
        Some(&number) => println!("Обаждаме се на Ashley: {}", call(number)),
        _ => println!("Нямаме номер на Ashley."),
    }

    contacts.remove(&"Ashley"); 

    // `HashMap::iter()` връща повторител, който дава
    // (&'a ключ, &'a стойност) двойки в произволен ред.
    for (contact, &number) in contacts.iter() {
        println!("Обаждаме се на {}: {}", contact, call(number)); 
    }
}

За повече сведения, свързани с хеширането и хеш-съответствията (понякога наричани хеш-таблици), погледнете Хеш таблица в Уикипедия

Б. пр.

1

безрѐдица – hash-map, hash-table. Kаша, безредни двойки съответствия, таблицa със съответствия ключ-стойност.

2

вместимост – capacity

Други (потребителски) типове за ключ

Всеки тип, въплъщаващ отличителите Eq и Hash, може да бъде ключ в HashMap. Такива са:

  • bool (макар и не много полезен, защото има само два възможни ключа);
  • int, uint и всичките им разновидности;
  • String и &str (за напреднали: можете да имате HashMap с ключове от тип String и да извиквате .get(), като му подавате &str).

Забележете, че f32 и f64 не осъществяват Hash, най-вероятно заради грешките, свързани с определяне на точността след десетичната запетая, които биха направили използването им като ключове ужасно ненадеждно.

Всички видове сбирки1 осъществяват Eq и Hash, ако съдържаните от тях типове въплъщават Eq и Hash. Например Vec<T> ще въплъщава Hash, ако T въплъщава Hash.

Можем лесно да въплътим Eq и Hash за потрбителски тип с един ред само: #[derive(PartialEq, Eq, Hash)]

Компилаторът ще свърши останалото. Ако искате да управлявате подробностите, можете да осъществите Eq и/или Hash сами. Това ръководство не покрива особеностите по осъществяване на Hash.

За да си поиграем с използване на структура като ключ в HashMap, нека направим простичка уредба за удостоверяване на потребител:

use std::collections::HashMap;

// Eq изисква вашият тип да е производен на PartialEq.
#[derive(PartialEq, Eq, Hash)]
struct Account<'a>{
    username: &'a str,
    password: &'a str,
}

struct AccountInfo<'a>{
    name: &'a str,
    email: &'a str,
}

type Accounts<'a> = HashMap<Account<'a>, AccountInfo<'a>>;

fn try_logon<'a>(accounts: &Accounts<'a>,
        username: &'a str, password: &'a str){
    println!("Username: {}", username);
    println!("Password: {}", password);
    println!("Attempting logon...");

    let logon = Account {
        username,
        password,
    };

    match accounts.get(&logon) {
        Some(account_info) => {
            println!("Успешно влизане!");
            println!("Име: {}", account_info.name);
            println!("Е-поща: {}", account_info.email);
        },
        _ => println!("Не успяхте да влезете!"),
    }
}

fn main(){
    let mut accounts: Accounts = HashMap::new();

    let account = Account {
        username: "j.everyman",
        password: "password123",
    };

    let account_info = AccountInfo {
        name: "John Everyman",
        email: "j.everyman@email.com",
    };

    accounts.insert(account, account_info);

    try_logon(&accounts, "j.everyman", "psasword123");

    try_logon(&accounts, "j.everyman", "password123");
}

Б. пр.

1

сбирка, набор, колекция – collection

HashSet

Можем да гледаме на HashSet (безредно множество1) като на безредица (HashMap), в която ни занимават само ключовете (HashSet<T> е всъщност просто обвивка около HashMap<T, ()>).

„Какъв е смисълът?“, ще попитате. „Мога просто да запиша ключовете във Vec.“

Неповторима способност на HashSet е, че обезпечава неповторимост2 на членовете си. Това е договорът, който всяко неподредено множество спазва. HashSet е просто само едно от въплъщенията. (Вижте също: BTreeSet)

Ако въведем вече същесвуваща в множеството стойност (нововъведената стойност е равна на някоя съществуваща вече в множеството и хешовете им са еднакви), то новата стойност ще замести старата.

Това е велико, ако не искате повтарящи се стойности или ако искате да знаете дали дадена стойност вече я има.

Но множествата могат и повече.

Те имат четири главни действия (всяко от тях връща повторител):

  • union: (обединение) взема всички неповторими членове и от двете множества;

  • difference: (разлика) взема всички членове от първото множество, които не са във второто;

  • intersection: (сечение) взема само тези членове, които са и в двете множества;

  • symmetric_difference: (съразмерна разлика) взема всички членове, които са или в едното, или в другото множество, но не и в двете.

Да пробваме всичките действия в следващия пример:

use std::collections::HashSet;

fn main() {
    let mut a: HashSet<i32> = vec![1i32, 2, 3].into_iter().collect();
    let mut b: HashSet<i32> = vec![2i32, 3, 4].into_iter().collect();

    assert!(a.insert(4));
    assert!(a.contains(&4));

    // `HashSet::insert()` връща false, ако въвежданата стойност вече присъства.
    assert!(b.insert(4), "Стойността 4 вече присъства в множество B!");
    // ПОПРАВКА ^ Коментирайте този ред.

    b.insert(5);

    // Ako типът на членовете на дадена сбирка осъществява `Debug`, то и самата
    // сбирка осъществява `Debug`.
    // Обикновено отпечатва членовете си във вида `[elem1, elem2, ...]`
    println!("A: {:?}", a);
    println!("B: {:?}", b);

    // Отпечатваме [1, 2, 3, 4, 5] в произволен ред.
    println!("Обединение: {:?}", a.union(&b).collect::<Vec<&i32>>());

    // Това би трябвало да отпечати [1]
    println!("Разлика: {:?}", a.difference(&b).collect::<Vec<&i32>>());

    // Отпечатва [2, 3, 4] в произволен ред.
    println!("Intersection: {:?}", a.intersection(&b).collect::<Vec<&i32>>());

    // Опечатва [1, 5]
    println!("Съразмерна разлика: {:?}",
             a.symmetric_difference(&b).collect::<Vec<&i32>>());
}

(Примерите са приспособени от документацията.)

Б. пр.

1

безредно множество (мат.) – set

2

неповторимост – uniqueness; неповторим – unique

Rc

Когато ни е нужно повече променливи да владеят едно и също парченце данни, можем да ползваме Rc(Reference Counting – Броене на Препратки – б. пр.). Rc следи броя на препратките, което е броят на владелците на данните, обгърнати в стойност от тип Rc.

Броят на препратките се увеличава с единица (1) всеки път, когато една стойност от тип Rc бива клонирана, и намалява с единица, когато клонирана стойност от тип Rc излезе от обхват. Когато борят на препратките в Rc стане нула (което означава, че не са останали владелци), стойността на Rc и стойността, която тя обгръща, биват освободени.

Клонирането на стойност Rc никога не прави дълбоко копиране. Клонирането просто създава още един указател към обгърнатата стойност и увеличава бройката на указателите към стойността.

use std::rc::Rc;

fn main() {
    let rc_examples = "Rc examples".to_string();
    {
        println!("--- създаде се rc_a ---");
        
        let rc_a: Rc<String> = Rc::new(rc_examples);
        println!("Брой Препратки към rc_a: {}", Rc::strong_count(&rc_a));
        
        {
            println!("--- rc_a се клонира в rc_b ---");
            
            let rc_b: Rc<String> = Rc::clone(&rc_a);
            println!("Брой Препратки към rc_b: {}", Rc::strong_count(&rc_b));
            println!("Брой Препратки към rc_a: {}", Rc::strong_count(&rc_a));
            
            // Две стойности `Rc` са еднакви, ако техните вътрешни стойности са
            // еднакви
            println!("rc_a и rc_b са еднакви: {}", rc_a.eq(&rc_b));
            
            // Можем да ползваме методите на стойността непосредствено
            println!("Дължината на стойността в rc_a: {}", rc_a.len());
            println!("Стойността на rc_b: {}", rc_b);
            
            println!("--- rc_b е извън обхват (освободена е) ---");
        }
        
        println!("Брой Препратки към rc_a: {}", Rc::strong_count(&rc_a));
        
        println!("--- rc_a е извън обхват (освободена е) ---");
    }
    
    // Грешка! `rc_examples`  вече е преместена в `rc_a`
    // А когато `rc_a` бива освободена, `rc_examples` бива освободена с нея
    // println!("rc_examples: {}", rc_examples);
    // ЗАДАЧА^ Разкоментирайте този ред
}

Вижте също:

std::rc и std::sync::arc.

Arc

Когато се нуждаем от споделено владение на данните между нишките на нашата програма, можем да ползваме Arc(Atomically Reference Counted – Неделимо Броене на Препратките, б.пр.). Чрез своето въплъщение на Clone тази структура може да създава указател към данните от купа̀, като увеличава броя на препратките към данните, към които сочи указателят. Тъй като Arc поддържа споделено между нишките владение, когато последната препратка към дадено парче данни излезе от обхват, променливата (и съответната стойност) се освобождават.

use std::time::Duration;
use std::sync::Arc;
use std::thread;

fn main() {
    // Чрез тази обява на променлива указваме и стойността.
    let apple = Arc::new("the same apple");

    for нишка in 0..10 {
        // Тук не указваме нова стойност. Новата променлива е указател към
        // препратка от купа̀ памет.
        let apple = Arc::clone(&apple);

        thread::spawn(move || {
            // Понеже ползваме Arc, можем да създаваме нови нишки със заделено
            // място за новия указател.
            println!("{:?} от нишка {нишка}", apple);
        });
    }

    // Изчакваме да се отпечатат всички обекти от тип Arc от всички нишки.
    thread::sleep(Duration::from_secs(1));
}

Разни в std

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

  • Нишки
  • Канали1
  • Вход и изход от файлове2

Те дават много повече възможности от първичните типове.

Б. пр.

1

канали – channels

2

В/И (вход и изход) – (input and output) I/O

Вижте също:

първични типове и стандартната библиотека

Нишки

Ръждьо дава възможност за разделяне1 на програмите в самородни2 за работната уредба3 нишки4 чрез функцията spawn. Аргументът към тази функция е преместващо [данните] затваряне.

use std::thread;

const NTHREADS: u32 = 10;

// Това е главната (`main`) нишка.
fn main() {
    // Създаваме вектор, в който да слагаме създадените дъщерни нишки.
    let mut children = vec![];

    for i in 0..NTHREADS {
        // Създаваме друга нишка.
        children.push(thread::spawn(move || {
            println!("това е нишка номер {}", i);
        }));
    }

    for child in children {
        // Чакаме нишката да приключи. Връща стойност, обгърната в Resul.
        let _ = child.join();
    }
}

Тези нишки биват насрочени5 за изпълнение от РУ.

Б. пр.

1

разделям в, пораждам, размножавам, създавам (нишка) – spawn

2

самороден, туземец, местен жител – native

3

работна уредба (РУ) – operating system (OS)

4

нишки – threads

5

биват насрочени – being scheduled

Проверка: map-reduce1

С Ръждьо много лесно се прави успоредна обработка на данни без обичайните затруднения, с които сме свикнали при такива начинания.

Стандартната библиотека предоставя наготово чудесни първични типове за многонишковост2. Тези типове, съчетани с правилата за единосъщност и владеене на променливите, автоматично предотвратяват гонките за данни3.

Правилата за единосъщност на данните4 – само една менима (за писане) препратка или (XOR – изключващо или) много неменими (за четене) препратки – автоматично предотвратяват вероятността да се промени състояние на данните, което е видимо и за други нишки. Когато е нужна синхронизация при промяна на данните, стандартната библиотека предоставя първични типове за синхронизация като Mutex и Channel.

В този пример ще изчислим сумата от всички цифри в блок от числа. Ще направим това, като разпределим парчетата от блока в различни нишки. Всяка нишка ще изчисли сумата на нейния си подблок от цифри. После ще съберем получените междинни суми, изчислени от всяка нишка.

Забележете, че макар да подаваме препратки отвъд границите на нишките, Ръждьо разбира, че подаваме препратки само за четене и така няма опасност от гонки за данните. Освен това, тъй като подаваните препратки имат 'static живот, Ръждьо разбира, че данните няма да бъдат унищожени, докато работят тези нишки. (Когато искаме да споделяме данни с не-'static живот между нишките, можем да ползваме умен указател като Arc, за да държим данните живи и така да избегнем употребата на не-static животи.)

use std::thread;

// Това е главната нишка.
fn main() {

    // Това са нашите данни за обработка.
    // Ще изчислим сбора от всички цифри чрез многонишков алгоритъм, наречен
    // "map-reduce". Всяко парче, отделено от другите с празнота, ще бъде
    // обработено в отделна нишка.
    //
    // ЗАДАЧА: Вижте какво се случва с изхода, ако въведете празноти между
    // някои цифри!
    let data = "86967897737416471853297327050364959
11861322575564723963297542624962850
70856234701860851907960690014725639
38397966707106094172783238747669219
52380795257888236525459303330302837
58495327135744041048897885734297812
69920216438980873548808413720956532
16278424637452589860345374828574668";

    // Създаваме вектор да държи новосъздадените дъщерни нишки.
    let mut children = vec![];

    /*************************************************************************
     * Стъпка "Map"
     *
     * Разделяме данните на парчета и прилагаме предварителна обработка
     ************************************************************************/

    // Разделяме данните на дялове за самостоятелно изчисляване. Всяко парче ще
    // бъде препратка (&str) към истинските данни.
    let chunked_data = data.split_whitespace();

    // Обхождаме парче по парче данните.
    // .enumerate() добавя текущия показалец от повторението към каквото се
    // обхожда. Произведената разнородна поредица "(място, член)" бива
    // незабавно разложена в две променливи – "i" и "data_segment" чрез
    // присвояване.
    for (i, data_segment) in chunked_data.enumerate() {
        println!("Парчето данни  {} е \"{}\"", i, data_segment);

        // Обработваме всяко парче в отделна нишка.
        //
        // spawn() връща ръкохватка за новата нишка, която ТРЯБВА да запазим,
        // за да достъпим върнатата стойност.
        //
        // 'move || -> u32' е правопис за затваряне, който:
        // * не приема аргументи ('||'),
        // * овладява прихванатите стойности ('move') и
        // * връща 32-битово цяло число без знак ('-> u32')
        //
        // Ръждьо е достатъчно умен да отгатне '-> u32' от затварянето,
        // така че можеше даже да не го указваме изрично.
        //
        // ЗАДАЧА: Махнете 'move' и вижте какво се случва.
        children.push(thread::spawn(move || -> u32 {
            // Изчисляваме междинната сума от този участък:
            let result = data_segment
                        // Обхождаме знаците от текущия участък…
                        .chars()
                        // …преобразуваме текстовите знаци в числови стойности…
                        .map(|c| c.to_digit(10).expect("трябва да е число"))
                        // …и сумираме произведения повторител на числа
                        .sum();

            // println! заключва стандартния изход и така няма смесен изход от
            // различни нишки.
            println!("обработихме участък {}, сума={}", i, result);

            // Не ни е нужен израз "return", защото Ръждьо е "ѝзразен език",
            // последно изчисленият израз във всеки блок става автоматично
            // стойност за връщане.
            result

        }));
    }


    /*************************************************************************
     * Стъпка "Reduce"
     *
     * Събираме междинните суми и ги сумираме като краен резултат.
     ************************************************************************/

    // Използваме „турбофиш” (::<>), за да подскажем типа за окончателната сума.
    //
    // ЗАДАЧА: Опитайте без „турбофиш”, като вместо това укажете типа за
    // final_result изрично.
    let final_result = children.into_iter().map(|c| c.join().unwrap())
        .sum::<u32>();

    println!("Окончателна сума: {}", final_result);
}

Упражнения

Не е мъдро броят на нишките да зависи от входните данни. Какво, ако потребителят реши да въведе празноти5 между много числа? Наистина ли искаме да създадем 2000 нишки? Променете програмата, така че данните да се разделят в ограничен брой парчета, определящи се от статична константа в началото на програмата.

Б. пр.

1

съответствие-намаляване – map-reduce? ЗАДАЧА: да се преведе и обясни на български: https://en.wikipedia.org/wiki/MapReduce https://ru.wikipedia.org/wiki/MapReduce

2

нишковост – threading; многонишковост – multi-threading

3

гонки за данни – data races

4

единосъщност, многоименност – aliasing. Когато различни променливи сочат към едни и същи данни. Ръждьо автоматично (по подразбиране) не позволява това да се случи.

5

празнота, празно пространство – space, white-space

Вижте също:

Канали

Ръждьо предоставя неедновременни1 канали (channels) за общуване2 между нишките. Каналите предоставят еднопосочен поток данни между две крайни точки: Подател (Sender) и Получател (Receiver).

use std::sync::mpsc::{Sender, Receiver};
use std::sync::mpsc;
use std::thread;

static NTHREADS: i32 = 3;

fn main() {
    // Каналите имат две крайни точки: `Sender<T>` и `Receiver<T>`,
    // където `T` е типа съобщение, което се пренася
    // (означаването на типа е излишно).
    let (tx, rx): (Sender<i32>, Receiver<i32>) = mpsc::channel();
    let mut children = Vec::new();

    for id in 0..NTHREADS {
        // Точката подател може да се копира.
        let thread_tx = tx.clone();

        // Всяка нишка ще подаде своето 'id' през канала.
        let child = thread::spawn(move || {
            // Нишката овладява `thread_tx`
            // Всяка нишка слага на опашка съобщение в канала.
            thread_tx.send(id).unwrap();

            // Подаването е неблокиращо действие. Нишката ще продължи незабавно
            // след подаването на своето съобщение.
            println!("Нишка {} приключи.", id);
        });

        children.push(child);
    }

    // Тук се събират всички съобщения.
    let mut ids = Vec::with_capacity(NTHREADS as usize);
    for _ in 0..NTHREADS {
        // Методът `recv` взима съобщение от канала.
        // `recv` блокира текущата нишка, ако няма пристигнали съобщения.
        ids.push(rx.recv());
    }
    
    // Чакаме нишките да довършат каквото има.
    for child in children {
        child.join().expect("Опаа! Дъщерната нишка се паникьоса.");
    }

    // Показваме съобщенията в реда на изпращане.
    println!("{:?}", ids);
}

Б. пр.

1

неедновременни – asynchronous; https://www.etymonline.com/word/synchronous https://www.etymonline.com/word/asynchronous

2

общуване, съобщаване – communication

Path

Структурата Path (пѫть)1 представлява осъществление на работа с файлови пътища за съответната файлова уредба2. Има две разновидности на Path: posix::Path – за UNIX-подобни уредби, и windows::Path – за Windows. Встъплението^prelude изнася (внася в обхвата на програмата – бел.прев.) подходящата за текущата уредба разновидност на Path.

Path може да бъде създаден от OsStr и предоставя няколко метода за извличане на данни от файла/директорията, към които сочи пътят.

Променливите от тип Path са неменими. Овладимата разновидност на Path е PathBuf. Отношението между Path и PathBuf е подобно на това между str и String. Променливите от тип PathBuf могат да бъдат променяни на място и могат да бъдат достъпвани пряко, сякаш са от тип Path.

Обърнете внимание, че Path вътрешно не е представена като низ UTF-8, а се съхранява като OsString. Затова превръщането на Path в &str не е безплатно и може да не успее (връща се Option). Все пак Path може свободно да се превърне в OsString или &OsStr, като се използват съответно into_os_string и as_os_str.

use std::path::Path;

fn main() {
    // Създаваме `Path` от `&'static str`
    let path = Path::new(".");

    // Методът `display` връща показваема структура (виж `Display`).
    let _display = path.display();

    // `join` слива път, като ползва съответния разделител
    // за текущата РУ, и връща променлива от тип `PathBuf`.
    let mut new_path = path.join("a").join("b");

    // `push` удължава `PathBuf` с един `&Path`
    new_path.push("c");
    new_path.push("myfile.tar.gz");

    // `set_file_name` обновява името на файла в променливата `PathBuf`
    new_path.set_file_name("package.tgz");

    // Превръща `PathBuf` в отрязък от низ.
    match new_path.to_str() {
        None => panic!("Новият пѫть е недействителна UTF-8 последователност"),
        Some(s) => println!("Новият пѫть е {}", s),
    }
}

Разгледайте и другите методи на Path (posix::Path или windows::Path) и структурата Metadata.

Б. пр.

1

пѫть – path. „пѫть” е старият (до 1945 г.) правопис на думата път. Буквата Ѫ (голям юс – Онсъ, носово О) отразява различните произношения в различните говори на българския език. С голяма вероятност на езика на Светите Братя е звучала като „Он” (Н се поизнася носово като във френски). В съвременните български говори все още можете да чуете разлики в произношението на думи като път, зъб, мъж, рѫка. Ѫ =~ /(ОА|А|Ъ|О|У)(М|Н)?/

2

файлова уредба – filesystem

3

встъпление, предисловие – prelude. именовано::пространство::prelude::*

Вижте също:

OsStr и Metadata.

File I/O

Структурата File представлява отворен файл (обгръща файлово описание1) и дава достъп за четене и/или писане към самия файл.

Тъй като много неща могат да се объркат, докато работим с вход и изход от файлове, методите от File връщат стойности от тип io::Result<T>, който е прякор за Result<T, io::Error>.

Това прави вероятния неуспех при всички входноизходни действия изричен2. Благодарение на това програмистът може да види всички неуспешни опити и бива насърчен да ги обработва чрез изпреварващи действия.

Б. пр.

1

файлово описание – file descriptor

2

изричен – explicit

open

Функцията open може да се ползва за отваряне на файл само за четене.

Един File владее източник – файловото описание, и се грижи да затвори файла, когато той бъде освободен (drop).

use std::fs::File;
use std::io::prelude::*;
use std::path::Path;

fn main() {
    // Създаваме път към желания файл.
    let path = Path::new("hello.txt");
    let display = path.display();

    // Отваряме пътя само за четене. Това връща `io::Result<File>`.
    let mut file = match File::open(&path) {
        Err(why) => panic!("Неуспех при отваряне на {}: {}", display, why),
        Ok(file) => file,
    };

    // Прочитаме съдържанието на файла в низ, връща `io::Result<usize>`.
    let mut s = String::new();
    match file.read_to_string(&mut s) {
        Err(why) => panic!("Неуспех при четене на {}: {}", display, why),
        Ok(_) => print!("{} съдържа:\n{}", display, s),
    }

    // `file` излиза от обхват и "hello.txt" бива затворен
}

Ето очаквания успешен изход:

$ echo "Hello World!" > hello.txt
$ rustc open.rs && ./open
hello.txt contains:
Hello World!

(Пробвайте горния пример при различни условия за неуспех: hello.txt не съществува или hello.txt е нечетим и т.н.)

create

Функцията create отваря файл само за писане. Ако файлът вече съществува, старото му съдържание бива унищожено. Иначе се създава нов файл.

static LOREM_IPSUM: &str =
    "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
";

use std::fs::File;
use std::io::prelude::*;
use std::path::Path;

fn main() {
    let path = Path::new("lorem_ipsum.txt");
    let display = path.display();

    // Отваряме файл само за писане. Връща `io::Result<File>`.
    let mut file = match File::create(&path) {
        Err(why) => panic!("Неуспех при създаване на {}: {}", display, why),
        Ok(file) => file,
    };

    // Пишем низа от `LOREM_IPSUM` във `file`. Връща `io::Result<()>`.
    match file.write_all(LOREM_IPSUM.as_bytes()) {
        Err(why) => panic!("Неуспех при писане във {}: {}", display, why),
        Ok(_) => println!("Успешно записахме в {}", display),
    }
}

Ето очаквания успешен изход:

$ rustc create.rs && ./create
successfully wrote to lorem_ipsum.txt
$ cat lorem_ipsum.txt
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

(Както и в предния пример, пробвайте различни условия за неуспех.)

Може да ползваме структурата OpenOptions, за да настроим как да се отваря файл.

read_lines

Наивен подход

Това може да бъде приличен първи опит на начинаещ за четене на редове от файл.

#![allow(unused)]
fn main() {
use std::fs::read_to_string;

fn read_lines(filename: &str) -> Vec<String> {
    let mut result = Vec::new();

    for line in read_to_string(filename).unwrap().lines() {
        result.push(line.to_string())
    }

    result
}
}

Тъй като методът lines() връща повторител върху редовете във файла, можем също да направим съответствия чрез map и да съберем резултатите (collect), като така представим нещата в по-сбит и ясен израз.

#![allow(unused)]
fn main() {
use std::fs::read_to_string;

fn read_lines(filename: &str) -> Vec<String> {
    read_to_string(filename) 
        .unwrap() // Паника в случай на грешки при четене от файл.
        .lines() // Разделяме низа на низови отрязъци и ги слагаме в повторител.
        .map(String::from) // От всеки отрязък правим низ.
        .collect() // Събираме ги заедно във вектор.
}
}

Забележете, че и в двата примера се налага да превърнем препратката &str, върната от lines(), във владимия тип String с помощта съответно на .to_string() и String::from.

По-сполучлив подход

Тук предаваме владението на отворения File на структура от тип BufReader. BufReader използва вътрешен склад. Така се намалява междинното1 заделяне на памет2.

Също така обновяваме3 read_lines да връща повторител, вместо да заделя памет за нови обекти от тип String за всеки ред.

use std::fs::File;
use std::io::{self, BufRead};
use std::path::Path;

fn main() {
    // Файлът hosts.txt трябва да съществува в текущия път.
    if let Ok(lines) = read_lines("./hosts.txt") {
        // Поглъща повторителя. Връща Option<String>.
        for line in lines {
            if let Ok(ip) = line {
                println!("{}", ip);
            }
        }
    }
}

// Изходът е обгърнат в `Result`, за да разреши намиране на съвпадения при грешки.
// Връща повторител (`Iterator`) от `BufReader` за поредово четене във файла.
fn read_lines<P>(filename: P) -> io::Result<io::Lines<io::BufReader<File>>>
where P: AsRef<Path>, {
    let file = File::open(filename)?;
    Ok(io::BufReader::new(file).lines())
}

Тази програма просто отпечатва редовете един по един.

$ echo -e "127.0.0.1\n192.168.0.1\n" > hosts.txt
$ rustc read_lines.rs && ./read_lines
127.0.0.1
192.168.0.1

(Забележете, че понеже File::open очаква обобщен AsRef<Path> като аргумент, описваме read_lines() като обобщена функция със същото ограничение, като използваме ключовата дума where.)

Този подход е по-сполучлив, отколкото да се създава в паметта обект от тип String с цялото съдържание на файла. При големи файлове четенето им наведнъж в паметта може да създаде особено големи затруднения с производителността.

Б. пр.

1

междинно – intermediate

2

заделяне на памет – memory allocation

3

обновявам – update

Дъщерни процеси

Структурата process::Output представлява изходът от завършил дъщерен процес, а структурата process::Command е строител на процеси.

use std::process::Command;

fn main() {
    let output = Command::new("rustc")
        .arg("--version")
        .output().unwrap_or_else(|e| {
            panic!("Неуспех при изпълнение на процес: {}", e)
    });

    if output.status.success() {
        let s = String::from_utf8_lossy(&output.stdout);

        print!("rustc успя, а стандартният изход беше:\n{}", s);
    } else {
        let s = String::from_utf8_lossy(&output.stderr);

        print!("rustc не успя, а стандартната грешка беше:\n{}", s);
    }
}

(Пробвайте горния пример, като подадете неправилен флаг на rustc)

Тръби

Структурата std::Child представлява работещ дъщерен процес и предоставя ръкохватките1 stdin, stdout и stderr за взаимодействие със същинския процес през тръби2.

use std::io::prelude::*;
use std::process::{Command, Stdio};

static PANGRAM: &'static str =
"the quick brown fox jumped over the lazy dog\n";

fn main() {
    // Изпълняваме командата `wc`
    let process = match Command::new("wc")
                                .stdin(Stdio::piped())
                                .stdout(Stdio::piped())
                                .spawn() {
        Err(why) => panic!("Неуспех при изпълнение на `wc`: {}", why),
        Ok(process) => process,
    };

    // Пишем низ в стандартния входен поток (`stdin`) на `wc`.
    //
    // `stdin` е от тип `Option<ChildStdin>`, но понеже знаем, че това пускане
    // трябва да има такъв, можем направо да го разгърнем (`unwrap`).
    match process.stdin.unwrap().write_all(PANGRAM.as_bytes()) {
        Err(why) => panic!("Неуспех при писане в \
            стандартния входен поток на `wc`: {}", why),
        Ok(_) => println!("Изпратихме всички-букви към `wc`"),
    }

    // `stdin` не живее след горните извиквания и затова бива освободен, а
    // тръбата е затворена.
    //
    // Това е много важно. Иначе `wc` няма да започне да обработва входа, който
    // току-що ѝ изпратихме.

    // Полето `stdout` също е от тип `Option<ChildStdout>` и трябва да бъде разгърнато.
    let mut s = String::new();
    match process.stdout.unwrap().read_to_string(&mut s) {
        Err(why) => panic!("Неуспех при четенето \
            на стандартния изход от `wc`: {}", why),
        Ok(_) => print!("`wc` отговори с:\n{}", s),
    }
}

Б. пр.

1

ръкохватка – handle

2 тръба – pipe; тръбопровод – pipeline (Виж https://en.wikipedia.org/wiki/Pipeline_(Unix))

Изчакване

Ако искате да изчакате някой process::Child да приключи, трябва да извикате Child::wait. Той ще върне обект от тип process::ExitStatus.

use std::process::Command;

fn main() {
    let mut child = Command::new("sleep").arg("5").spawn().unwrap();
    let _result = child.wait().unwrap();

    println!("Достигнахме края на функцията main.");
}
$ rustc wait.rs && ./wait
# `wait` кара програмата ни да работи пет секунди, докато командата `sleep 5`
# не приключи
Достигнахме края на функцията main.

Действия с файловата уредба

Модулът std::fs съдържа няколко функции за работа с файловата уредба.

use std::fs;
use std::fs::{File, OpenOptions};
use std::io;
use std::io::prelude::*;
use std::os::unix;
use std::path::Path;

// Просто осъществяване на `% cat пѫть`
fn cat(path: &Path) -> io::Result<String> {
    let mut f = File::open(path)?;
    let mut s = String::new();
    match f.read_to_string(&mut s) {
        Ok(_) => Ok(s),
        Err(e) => Err(e),
    }
}

// Просто осъществяване на `% echo s > пѫть`
fn echo(s: &str, path: &Path) -> io::Result<()> {
    let mut f = File::create(path)?;

    f.write_all(s.as_bytes())
}

// Просто осъществяване на`% touch пѫть` (пренебрегва съществуващи файлове)
fn touch(path: &Path) -> io::Result<()> {
    match OpenOptions::new().create(true).write(true).open(path) {
        Ok(_) => Ok(()),
        Err(e) => Err(e),
    }
}

fn main() {
    println!("`mkdir a`");
    // Създаваме директория. Връща `io::Result<()>`.
    match fs::create_dir("a") {
        Err(why) => println!("! {:?}", why.kind()),
        Ok(_) => {},
    }

    println!("`echo hello > a/b.txt`");
    // Предишният израз `match` може да се опрости, като ползваме метода
    // `unwrap_or_else`.
    echo("hello", &Path::new("a/b.txt")).unwrap_or_else(|why| {
        println!("! {:?}", why.kind());
    });

    println!("`mkdir -p a/c/d`");
    // Рекурсивно (възвратно) създаваме директория. Връща `io::Result<()>`.
    fs::create_dir_all("a/c/d").unwrap_or_else(|why| {
        println!("! {:?}", why.kind());
    });

    println!("`touch a/c/e.txt`");
    touch(&Path::new("a/c/e.txt")).unwrap_or_else(|why| {
        println!("! {:?}", why.kind());
    });

    println!("`ln -s ../b.txt a/c/b.txt`");
    // Създаваме символна връзка. Връща `io::Result<()>`.
    if cfg!(target_family = "unix") {
        unix::fs::symlink("../b.txt", "a/c/b.txt").unwrap_or_else(|why| {
            println!("! {:?}", why.kind());
        });
    }

    println!("`cat a/c/b.txt`");
    match cat(&Path::new("a/c/b.txt")) {
        Err(why) => println!("! {:?}", why.kind()),
        Ok(s) => println!("> {}", s),
    }

    println!("`ls a`");
    // Четем съдържанието на директория. Връща `io::Result<Vec<Path>>`.
    match fs::read_dir("a") {
        Err(why) => println!("! {:?}", why.kind()),
        Ok(paths) => for path in paths {
            println!("> {:?}", path.unwrap().path());
        },
    }

    println!("`rm a/c/e.txt`");
    // Премахваме файл. Връща `io::Result<()>`.
    fs::remove_file("a/c/e.txt").unwrap_or_else(|why| {
        println!("! {:?}", why.kind());
    });

    println!("`rmdir a/c/d`");
    // Премахваме празна директория. Връща `io::Result<()>`.
    fs::remove_dir("a/c/d").unwrap_or_else(|why| {
        println!("! {:?}", why.kind());
    });
}

Ето очаквания успешен изход:

$ rustc fs.rs && ./fs
`mkdir a`
`echo hello > a/b.txt`
`mkdir -p a/c/d`
`touch a/c/e.txt`
`ln -s ../b.txt a/c/b.txt`
`cat a/c/b.txt`
> hello
`ls a`
> "a/b.txt"
> "a/c"
`rm a/c/e.txt`
`rmdir a/c/d`

И окончателното състояние на директорията a е:

$ tree a
a
|-- b.txt
`-- c
    `-- b.txt -> ../b.txt

1 directory, 2 files

Друг начин да опишем функцията cat е като ползваме ?:

fn cat(path: &Path) -> io::Result<String> {
    let mut f = File::open(path)?;
    let mut s = String::new();
    f.read_to_string(&mut s)?;
    Ok(s)
}

Вижте също:

cfg!

Аргументи на програмата

Стандартната библиотека

Аргументите на командния ред са достъпни чрез функцията std::env::args, която връща повторител, даващ ни стойност от тип String за всеки аргумент:

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();

    // Първият аргумент е пътят, използван за извикване на програмата.
    println!("Моят пѫть е {}.", args[0]);

    // Останалите аргументи са подадените параметри на командния ред.
    // Извикайте програмата така:
    //   $ ./args arg1 arg2
    println!("Получих {:?} аргумента: {:?}.", args.len() - 1, &args[1..]);
}
$ ./args 1 2 3
My path is ./args.
I got 3 arguments: ["1", "2", "3"].

Кошове

Има и много кошове, предоставящи допълнителни възможности при създаване на приложения за командния ред. Готварската книга на Ръждьо излага редица отлични примери за това, как да се ползва един от най-известните кошове за аргументи на командния ред – clap.

Разбор на аргументи

Намиране на съвпадения може да бъде използвано за разбор на прости аргументи:

use std::env;

fn increase(number: i32) {
    println!("{}", number + 1);
}

fn decrease(number: i32) {
    println!("{}", number - 1);
}

fn help() {
    println!("Използване:
match_args <string>
    Проверка дали подаденият низ е отговорът.
match_args {{увеличи|намали}} <цяло число>
    Увеличаване или намаляване на подаденото цяло число с единица.");
}

fn main() {
    let args: Vec<String> = env::args().collect();

    match args.len() {
        // Няма подадени аргументи.
        1 => {
            println!("Името ми е 'match_args'. Подайте някакви аргументи!");
        },
        // Подаден е един аргумент.
        2 => {
            match args[1].parse() {
                Ok(42) => println!("Това е отговорът!"),
                _ => println!("Това не е отговорът."),
            }
        },
        // Подадени са една команда и един аргумент.
        3 => {
            let cmd = &args[1];
            let num = &args[2];
            // Разбираме числото.
            let number: i32 = match num.parse() {
                Ok(n) => {
                    n
                },
                Err(_) => {
                    eprintln!("Грешка: Вторият аргумент не е цяло число.");
                    help();
                    return;
                },
            };
            // Разбираме командата.
            match &cmd[..] {
                "увеличи" => increase(number),
                "намали" => decrease(number),
                _ => {
                    eprintln!("Грешка: Нередовна команда!");
                    help();
                },
            }
        },
        // Всички останали случаи.
        _ => {
            // Показваме помощно съобщение.
            help();
        }
    }
}

Ако сте нарекли програмата си match_args.rs и я компилирате с командата rustc ./match_args.rs, можете да я изпълните както следва:

$ ./match_args Ръждьо
Това не е отговорът.
$ ./match_args 42
Това е отговорът!
$ ./match_args do something
Грешка: Вторият аргумент не е цяло число.
Използване:
match_args <string>
    Проверка дали подаденият низ е отговорът.
match_args {увеличи|намали} <цяло число>
    Увеличаване или намаляване на подаденото цяло число с единица.
$ ./match_args do 42
Грешка: Нередовна команда!
Използване:
match_args <string>
    Проверка дали подаденият низ е отговорът.
match_args {увеличи|намали} <цяло число>
    Увеличаване или намаляване на подаденото цяло число с единица.
$ ./match_args увеличи 42
43

Б. Пр.

1

разбирам === правя разбор – parse

Външности за чужди функции

Ръждьо предоставя възможност за описване на Външности за чужди функции (ВЧФ)1 за библиотеки, написани на езика C. Чуждите функции трябва да се обявят в именуван външен блок extern2, означен с атрибут #[link], който съдържа името на чуждата библиотека.

use std::fmt;

// Този външен блок се свързва с библиотеката libm.
#[link(name = "m")]
extern {
    // Това е чужда функция, която изчислява корен квадратен от комплексно
    // число с единична точност.
    fn csqrtf(z: Complex) -> Complex;

    fn ccosf(z: Complex) -> Complex;
}

// Тъй като извикването на чужди функции се смята за опасно, обичайно се пишат
// обгръщащи функции, които извикват чуждите.
fn cos(z: Complex) -> Complex {
    unsafe { ccosf(z) }
}

fn main() {
    // z = -1 + 0i
    let z = Complex { re: -1., im: 0. };

    // Извикването на чужда функция е опасно действие.
    let z_sqrt = unsafe { csqrtf(z) };

    println!("Корен квадратен от {:?} е {:?}", z, z_sqrt);

    // Извикваме безопасно ППВ, обгръщащо опасно действие.
    println!("cos({:?}) = {:?}", z, cos(z));
}

// Най-малко въплъщение на комплексни числа с единична точност.
#[repr(C)]
#[derive(Clone, Copy)]
struct Complex {
    re: f32,
    im: f32,
}

impl fmt::Debug for Complex {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        if self.im < 0. {
            write!(f, "{}-{}i", self.re, -self.im)
        } else {
            write!(f, "{}+{}i", self.re, self.im)
        }
    }
}

Б. пр.

1

Външност за чужди функции (ВЧФ) – Foreign function interface (FFI). Приложна програмна външност (ППВ) – Application programming interface (API)

2

външен – extern

Тестване

Ръждьо е език за програмиране, който много държи на точността, а това включва поддръжка за писане на софтуерни тестове в самия език.

Тестването се проявява в три разновидности:

Освен това Ръждьо поддържа указване на зависимости по време на разработка3 – за тестване:

Б. пр.

1

поединично тестване – unit testing

2

внедряване – integration

3

зависимости по време на разработка – dev-dependencies

See Also

Поединично тестване

Тестовете в Ръждьо са функции, които проверяват дали друг – нетестов код, действа по очаквания начин. Телата на тестовите функции обикновено извършват някакви първоначални настройки, пускат кода, който искаме да тестваме, и след това установяват дали изходът от изпълнението на кода е каквото очакваме.

Повечето единични тестове се пишат в отделен модул с име tests и атрибут #[cfg(test)]. Тестовите функции се обозначават с атрибута #[test].

Тестовете се провалят, когато нещо в тестова функция се паникьоса (извика panic!). Има някои помощни макроси:

  • assert!(израз)1 – паникьосва се, ако изразът се оцени като false.
  • assert_eq!(ляво, дясно) и assert_ne!(ляво, дясно) – проверяват се левият и десният израз за еднаквост и нееднаквост съответно.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

// Това е наистина калпава функция за събиране. Нейното предназначение в този
// пример е да се провали.
#[allow(dead_code)]
fn bad_add(a: i32, b: i32) -> i32 {
    a - b
}

#[cfg(test)]
mod tests {
    // Забележете този полезен устойчив израз. Така внасяме имена отвън в обхвата на
    // `mod tests`.
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(1, 2), 3);
    }

    #[test]
    fn test_bad_add() {
        // Когато това потвърждение се изпълни, тестът ще се провали.
        // Забележете, че частните функции също могат да бъдат тествани!
        assert_eq!(bad_add(1, 2), 3);
    }
}

Тестовете могат да бъдат пускани с cargo test.

$ cargo test

running 2 tests
test tests::test_bad_add ... FAILED
test tests::test_add ... ok

failures:

---- tests::test_bad_add stdout ----
        thread 'tests::test_bad_add' panicked at 'assertion failed: `(left == right)`
  left: `-1`,
 right: `3`', src/lib.rs:21:8
note: Run with `RUST_BACKTRACE=1` for a backtrace.


failures:
    tests::test_bad_add

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

Тестове и ?

Нито един от предишните единични тестове нямаше тип за връщане. Но в Ръждьо 2018 тестовете могат да връщат Result<()>, което ви позволява да ползвате ? в тях! Това може да ги направи много по-кратки.

fn sqrt(number: f64) -> Result<f64, String> {
    if number >= 0.0 {
        Ok(number.powf(0.5))
    } else {
        Err("отрицателни числа с плаваща запетая нямат квадратен корен".to_owned())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_sqrt() -> Result<(), String> {
        let x = 4.0;
        assert_eq!(sqrt(x)?.powf(2.0), x);
        Ok(())
    }
}

Вижте „Ръководството за изданията” за повече подробности.

Тестване на паника

За да тествате функции, които може да се паникьосат, използвайте атрибута#[should_panic]. Този атрибут приема избираем параметър expected = с текста на съобщението при паника. Ако вашата функция се паникьосва по различни начини, трябва да се уверите, че тествате правилната паника.

pub fn divide_non_zero_result(a: u32, b: u32) -> u32 {
    if b == 0 {
        panic!("Divide-by-zero error");
    } else if a < b {
        panic!("Divide result is zero");
    }
    a / b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_divide() {
        assert_eq!(divide_non_zero_result(10, 2), 5);
    }

    #[test]
    #[should_panic]
    fn test_any_panic() {
        divide_non_zero_result(1, 0);
    }

    #[test]
    #[should_panic(expected = "Divide result is zero")]
    fn test_specific_panic() {
        divide_non_zero_result(1, 10);
    }
}

Пускането на тези тестове ни дава:

$ cargo test

running 3 tests
test tests::test_any_panic ... ok
test tests::test_divide ... ok
test tests::test_specific_panic ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests tmp-test-should-panic

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Пускане на отделни тестове

За да пуснете точно определени тестове, можете да укажете името на теста при изпълнение на командата cargo test.

$ cargo test test_any_panic
running 1 test
test tests::test_any_panic ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out

   Doc-tests tmp-test-should-panic

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

За да пуснете множество тестове, можете да укажете част от име на тест, което съответства на всички тестове, които искате да пуснете.

$ cargo test panic
running 2 tests
test tests::test_any_panic ... ok
test tests::test_specific_panic ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out

   Doc-tests tmp-test-should-panic

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Пропускане2 на тестове

Тестовете могат да бъдат отбелязани с атрибута #[ignore], за да ги изключите. Или пък да ги пуснете с командата cargo test -- --ignored.

#![allow(unused)]
fn main() {
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 2), 4);
    }

    #[test]
    fn test_add_hundred() {
        assert_eq!(add(100, 2), 102);
        assert_eq!(add(2, 100), 102);
    }

    #[test]
    #[ignore]
    fn ignored_test() {
        assert_eq!(add(0, 0), 0);
    }
}
}
$ cargo test
running 3 tests
test tests::ignored_test ... ignored
test tests::test_add ... ok
test tests::test_add_hundred ... ok

test result: ok. 2 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out

   Doc-tests tmp-ignore

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

$ cargo test -- --ignored
running 1 test
test tests::ignored_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests tmp-ignore

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Б. пр.

1

потвърждавам – assert

2

пренебрегвам – ignore. В случая – „пропускам”

3

устойчив израз, идиом – idiom

Тестове в документацията

Главният начин да се документира проект в Ръждьо е чрез добавяне на бележки в изходния код. Документните коментари се пишат според Спецификацията на CommonMark Markdown и поддържат блокове от код в тях. Ръждьо се грижи за правилността, така че тези блокове от код се компилират и се ползват като тестове от документацията.

/// Първият ред е кратко общо описание на функцията.
///
/// Следващите редове представляват подробна документация. Блоковете код
/// започват с тройни обратни кавички и имат в себе си `fn main()` и `extern crate
/// <cratename>`. Да си представим, че тестваме коша `doccomments`:
///
/// ```
/// let result = doccomments::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// Обикновено документните коментари може да включват раздели „Examples”,
/// „Panics” и „Failures”.
///
/// Следващата функция дели едно число на друго.
///
/// # Examples
///
/// ```
/// let result = doccomments::div(10, 2);
/// assert_eq!(result, 5);
/// ```
///
/// # Panics
///
/// Функцията се паникьосва, ако вторият аргумент е нула.
///
/// ```rust,should_panic
/// // паникьосва се при делене на нула.
/// doccomments::div(10, 0);
/// ```
pub fn div(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("Divide-by-zero error");
    }

    a / b
}

Блоковете код в документацията биват тествани автоматично, щом пуснете командата cargo test:

$ cargo test
running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests doccomments

running 3 tests
test src/lib.rs - add (line 7) ... ok
test src/lib.rs - div (line 21) ... ok
test src/lib.rs - div (line 31) ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Основания за тестове в документацията

Главната цел на документните тестове е да служат като примери, които ползват предоставяната функционалност, а това са най-важните насоки. Те ни позволяват да ползваме примерите от документацията като пълноценни парчета код. Но ползването на ? прави така, че компилацията се проваля, понеже main връща unit. В този случай можем да скрием няколко реда код от документацията: можем да напишем fn try_main() -> Result<(), ErrorType>, да я скрием и разгърнем (unwrap) в скритата main. Сложно ли звучи? Ето пример:

/// Използване на скрита `try_main` в документни тестове.
///
/// ```
/// # // Скритите редове започват със знака `#`, но са също компилируеми!
/// # // Ред, който обгръща тялото, показано в документацията.
/// # fn try_main() -> Result<(), String> {
/// let res = doccomments::try_div(10, 2)?;
/// # Ok(()) // Връщаме от try_main.
/// # }
/// # fn main() { // Започва `main`, която извиква `unwrap()`.
/// #    try_main().unwrap(); // Извикваме try_main и разгръщаме,
/// #                         // така че тестът ще се паникьоса в случай на
/// #                         // грешка.
/// # }
/// ```
pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err(String::from("Divide-by-zero"))
    } else {
        Ok(a / b)
    }
}

See Also

  • RFC505 за стила на документацията;
  • API Guidelines за насоки при документиране.

Тестове при внедряване

Поединичните тестове тестват всеки модул поотделно. Те са малки и могат да тестват частен код. Тестовете при внедряване са външни за коша ви и ползват само общодостъпната му външност по същия начин, както и всеки друг код. Тяхното предназначение е да проверят дали различните части на библиотеката ви работят правилно заедно.

Cargo гледа за тестове при внедряване в директорията tests до src.

Файл src/lib.rs:

// Опишете това в кош с име `adder`.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Файл с тест: tests/integration_test.rs:

#[test]
fn test_add() {
    assert_eq!(adder::add(3, 2), 5);
}

Пускаме тестовете с командата cargo test:

$ cargo test
running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/integration_test-bcd60824f5fbfe19

running 1 test
test test_add ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Всеки файл с изходен код на Ръждьо в директорията tests бива компилиран като отделен кош. За да ползваме общ код в различните тестове, можем да направим модул с общодостъпни функции, да го внесем и ползваме в тестовете.

Файл tests/common/mod.rs:

pub fn setup() {
    // Някакъв подготвителен код за създаване на файлове, директории, пускане на
    // сървъри и т.н.
}

Файл с тест: tests/integration_test.rs

// Внасяме общия модул.
mod common;

#[test]
fn test_add() {
    // Ползваме общия код.
    common::setup();
    assert_eq!(adder::add(3, 2), 5);
}

Също ще работи и ако създадем модула като tests/common.rs, но не се препоръчва, защото пускът на тестове смята файла за тестов кош и ще се опита да пусне тестове в него.

Зависимости при разработка

Понякога ни трябват зависимости само за тестове или примери, или за проверка на бързодействието. Такива зависимости се добавят в Cargo.toml в раздел [dev-dependencies]. Тези зависимости не биват предадени на други пакети, които зависят от този пакет.

Един такъв пример е pretty_assertions, който разширява стандартните макроси assert_eq! и assert_ne!, за да предостави разноцветни разлики.

Файл Cargo.toml:

# Стандартните данни за коша не са показани.
[dev-dependencies]
pretty_assertions = "1"

Файл src/lib.rs:

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;
    use pretty_assertions::assert_eq; // Кош за ползване само в тестове. Не
    // може да се ползва в нетестов код.

    #[test]
    fn test_add() {
        assert_eq!(add(2, 3), 5);
    }
}

See Also

Документацията на Карго за указване на зависимости.

Опасни действия

Да започнем този раздел със заемка от представителната документация, „…добре е да избягваме опасен код1.”. Като имаме това предвид, можем да започнем. Отбелязването на опасност в Ръждьо се ползва за заобикаляне на мерките за безопасност, наложени от компилатора. Има четири основни неща, за които се ползват „опасни блокове”:

  • Пряк достъп до сурови указатели;
  • извикване на функции, които са опасни (unsafe) (включително извикване на функция чрез ВЧФ, вижте съответната глава от книгата);
  • достъп до или промяна на статични меними променливи;
  • осъществяване на опасни отличители.

Сурови указатели

Суровите указатели * и препратките &T работят по подобен начин, но препратките са винаги безопасни, понеже винаги сочат към действителни данни, благодарение на проверителя за заемки. Прекият достъп до суров указател може да се направи само чрез опасен блок.

fn main() {
    let raw_p: *const u32 = &10;

    unsafe {
        assert!(*raw_p == 10);
    }
}

Извикване на опасни функции

Някои функции може да бъдат обявени като unsafe. Това означава, че програмистът поема отговорност за безопасността вместо компилатора. Един пример за такъв код е std::slice::from_raw_parts, който ще създаде отрязък от подаден първи член и дължина.

use std::slice;

fn main() {
    let some_vector = vec![1, 2, 3, 4];

    let pointer = some_vector.as_ptr();
    let length = some_vector.len();

    unsafe {
        let my_slice: &[u32] = slice::from_raw_parts(pointer, length);

        assert_eq!(some_vector.as_slice(), my_slice);
    }
}

При използване на slice::from_raw_parts едно от предположенията, които трябва да са потвърдени, е, че подаденият указател сочи към действително място от паметта и че това място съдържа правилния тип данни. Ако тези задължителни условия не са спазени, поведението на програмата е неопределено2 и не се знае какво ще се случи.

Б. пр.

1

опасен код – unsafe code

2

неопределено (поведение) – undefined behaviour

Вписан асемблер

Ръждьо предоставя поддръжка за вписване на код на асемблер1 чрез макроса asm!. Може да се ползва за внедряване на написан на ръка код на асемблер – на същия асемблер като този, създаден от компилатора. Обикновено това не е необходимо, но може да се случи, когато нужната производителност не може да се постигне по друг начин. Пряк достъп до хардуера, например код за ядрото на уредбата, може също да изисква такава функционалност.

Важно: Примерите тук са написани на асемблер за архитектура x86/x86-64, но се поддържат и други архитектури.

Вписан асемблер се поддържа за следните архитектури:

  • x86 and x86-64
  • ARM
  • AArch64
  • RISC-V

Основи

Да започнем с възможно най-простия пример:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

unsafe {
    asm!("nop");
}
}
}

Това ще вмъкне нареждане2 „NOP“ (no operation) в асемблерния код, създаден от компилатора. Забележете, че всички извиквания на asm! трябва да са в блок unsafe, тъй като те могат да вмъкнат произволни нареждания към машината и да счупят иначе непроменлив за програмиста код. Нарежданията за вмъкване се поставят последователно в първия аргумент на макроса asm! като низова буквална стойност.

Вход и изход

Въвеждането на нареждане, което не прави нищо, е отегчително. Да направим нещо, което работи с данни:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64;
unsafe {
    asm!("mov {}, 5", out(reg) x);
}
assert_eq!(x, 5);
}
}

Това ще запише стойността 5 в променливата x от тип u64. Вижда се, че низът, който ползваме за нарежданията, всъщност е низов образец3. Подчинява се на същите правила като низовете за форматиране. Аргументите, които се вмъкват в образеца обаче изглеждат малко по-различно. Първо трябва да укажем дали променливата е вход или изход за вписания асемблер. В този случай е изход. Обявихме това, като написахме out. Също трябва да укажем в какъв вид регистър асемблерът очаква променливата. В нашия случай ние я поставяме в произволен регистър за общо ползване, като указваме reg. Компилаторът ще избере подходящия регистър за вмъкване в образеца и ще прочете променливата оттам, след като вписаният асемблер приключи изпълнението си.

Да видим друг пример, който ползва и вход:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let i: u64 = 3;
let o: u64;
unsafe {
    asm!(
        "mov {0}, {1}",
        "add {0}, 5",
        out(reg) o,
        in(reg) i,
    );
}
assert_eq!(o, 8);
}
}

Това ще добави 5 към входа в променливата i и ще запише резултата в промеливата o. Точният начин, по който се прави това, е първо да се копира стойността от i в изхода, а след това да добави 5 към него.

Примерът показва няколко неща:

Първо виждаме, че asm! позволява да се подадат няколко аргумента като низов образец. Всеки от тях се разглежда като отделен ред асемблерен код, сякаш всички са съединени със знак за нов ред помежду им. Това улеснява форматирането на кода.

Второ, виждаме че входните данни се обявяват, като се пише in вместо out.

Трето, можем да указваме пореден номер на аргумента за заместване в образеца или име, както във всеки низ за форматиране. Това е особено полезно за образците за вписан асемблер, тъй като аргументите често се ползват повече от веднъж. За по-сложен код на асемблер това даже се препоръчва, понеже подобрява четимостта и позволява преподреждане на нарежданията, без да се променя редът на аргументите.

Можем да усъвършенстваме горния пример, като избегнем нареждането mov:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut x: u64 = 3;
unsafe {
    asm!("add {0}, 5", inout(reg) x);
}
assert_eq!(x, 8);
}
}

Виждаме, че се ползва inout, за да се укаже, че даден аргумент е входноизходен. Това е различно от указване на вход и изход поотделно, защото гарантира, че ще присвои и двата на един и същи регистър.

Възможно е също да се укажат различни променливи за входната и изходната части на операнда inout:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64 = 3;
let y: u64;
unsafe {
    asm!("add {0}, 5", inout(reg) x => y);
}
assert_eq!(y, 8);
}
}

Late output operands

The Ръждьо compiler is conservative with its allocation of operands. It is assumed that an out can be written at any time, and can therefore not share its location with any other argument. However, to guarantee optimal performance it is important to use as few registers as possible, so they won't have to be saved and reloaded around the inline assembly block. To achieve this Ръждьо provides a lateout specifier. This can be used on any output that is written only after all inputs have been consumed. There is also a inlateout variant of this specifier.

Here is an example where inlateout cannot be used in release mode or other optimized cases:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
let c: u64 = 4;
unsafe {
    asm!(
        "add {0}, {1}",
        "add {0}, {2}",
        inout(reg) a,
        in(reg) b,
        in(reg) c,
    );
}
assert_eq!(a, 12);
}
}

Горното би могло да работи добре за неоптимизирани случаи (режим Debug), но ако искате оптимизирана производителност (режим release или други случаи на оптимизация), може и да не работи.

That is because in optimized cases, the compiler is free to allocate the same register for inputs b and c since it knows they have the same value. However it must allocate a separate register for a since it uses inout and not inlateout. If inlateout was used, then a and c could be allocated to the same register, in which case the first instruction to overwrite the value of c and cause the assembly code to produce the wrong result.

However the following example can use inlateout since the output is only modified after all input registers have been read:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
    asm!("add {0}, {1}", inlateout(reg) a, in(reg) b);
}
assert_eq!(a, 8);
}
}

Както се вижда, това парче ассемблер ще работи правилно, ако a и b са присвоени на един и същи регистър.

Explicit register operands

Some instructions require that the operands be in a specific register. Therefore, Ръждьо inline assembly provides some more specific constraint specifiers. While reg is generally available on any architecture, explicit registers are highly architecture specific. E.g. for x86 the general purpose registers eax, ebx, ecx, edx, ebp, esi, and edi among others can be addressed by their name.

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let cmd = 0xd1;
unsafe {
    asm!("out 0x64, eax", in("eax") cmd);
}
}
}

In this example we call the out instruction to output the content of the cmd variable to port 0x64. Since the out instruction only accepts eax (and its sub registers) as operand we had to use the eax constraint specifier.

Note: unlike other operand types, explicit register operands cannot be used in the template string: you can't use {} and should write the register name directly instead. Also, they must appear at the end of the operand list after all other operand types.

Consider this example which uses the x86 mul instruction:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

fn mul(a: u64, b: u64) -> u128 {
    let lo: u64;
    let hi: u64;

    unsafe {
        asm!(
            // The x86 mul instruction takes rax as an implicit input and writes
            // the 128-bit result of the multiplication to rax:rdx.
            "mul {}",
            in(reg) a,
            inlateout("rax") b => lo,
            lateout("rdx") hi
        );
    }

    ((hi as u128) << 64) + lo as u128
}
}
}

This uses the mul instruction to multiply two 64-bit inputs with a 128-bit result. The only explicit operand is a register, that we fill from the variable a. The second operand is implicit, and must be the rax register, which we fill from the variable b. The lower 64 bits of the result are stored in rax from which we fill the variable lo. The higher 64 bits are stored in rdx from which we fill the variable hi.

Clobbered registers

In many cases inline assembly will modify state that is not needed as an output. Usually this is either because we have to use a scratch register in the assembly or because instructions modify state that we don't need to further examine. This state is generally referred to as being "clobbered". We need to tell the compiler about this since it may need to save and restore this state around the inline assembly block.

use std::arch::asm;

#[cfg(target_arch = "x86_64")]
fn main() {
    // three entries of four bytes each
    let mut name_buf = [0_u8; 12];
    // String is stored as ascii in ebx, edx, ecx in order
    // Because ebx is reserved, the asm needs to preserve the value of it.
    // So we push and pop it around the main asm.
    // 64 bit mode on 64 bit processors does not allow pushing/popping of
    // 32 bit registers (like ebx), so we have to use the extended rbx register instead.

    unsafe {
        asm!(
            "push rbx",
            "cpuid",
            "mov [rdi], ebx",
            "mov [rdi + 4], edx",
            "mov [rdi + 8], ecx",
            "pop rbx",
            // We use a pointer to an array for storing the values to simplify
            // the Ръждьо code at the cost of a couple more asm instructions
            // This is more explicit with how the asm works however, as opposed
            // to explicit register outputs such as `out("ecx") val`
            // The *pointer itself* is only an input even though it's written behind
            in("rdi") name_buf.as_mut_ptr(),
            // select cpuid 0, also specify eax as clobbered
            inout("eax") 0 => _,
            // cpuid clobbers these registers too
            out("ecx") _,
            out("edx") _,
        );
    }

    let name = core::str::from_utf8(&name_buf).unwrap();
    println!("CPU Manufacturer ID: {}", name);
}

#[cfg(not(target_arch = "x86_64"))]
fn main() {}

In the example above we use the cpuid instruction to read the CPU manufacturer ID. This instruction writes to eax with the maximum supported cpuid argument and ebx, edx, and ecx with the CPU manufacturer ID as ASCII bytes in that order.

Even though eax is never read we still need to tell the compiler that the register has been modified so that the compiler can save any values that were in these registers before the asm. This is done by declaring it as an output but with _ instead of a variable name, which indicates that the output value is to be discarded.

This code also works around the limitation that ebx is a reserved register by LLVM. That means that LLVM assumes that it has full control over the register and it must be restored to its original state before exiting the asm block, so it cannot be used as an input or output except if the compiler uses it to fulfill a general register class (e.g. in(reg)). This makes reg operands dangerous when using reserved registers as we could unknowingly corrupt our input or output because they share the same register.

To work around this we use rdi to store the pointer to the output array, save ebx via push, read from ebx inside the asm block into the array and then restore ebx to its original state via pop. The push and pop use the full 64-bit rbx version of the register to ensure that the entire register is saved. On 32 bit targets the code would instead use ebx in the push/pop.

This can also be used with a general register class to obtain a scratch register for use inside the asm code:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

// Multiply x by 6 using shifts and adds
let mut x: u64 = 4;
unsafe {
    asm!(
        "mov {tmp}, {x}",
        "shl {tmp}, 1",
        "shl {x}, 2",
        "add {x}, {tmp}",
        x = inout(reg) x,
        tmp = out(reg) _,
    );
}
assert_eq!(x, 4 * 6);
}
}

Symbol operands and ABI clobbers

By default, asm! assumes that any register not specified as an output will have its contents preserved by the assembly code. The clobber_abi argument to asm! tells the compiler to automatically insert the necessary clobber operands according to the given calling convention ABI: any register which is not fully preserved in that ABI will be treated as clobbered. Multiple clobber_abi arguments may be provided and all clobbers from all specified ABIs will be inserted.

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

extern "C" fn foo(arg: i32) -> i32 {
    println!("arg = {}", arg);
    arg * 2
}

fn call_foo(arg: i32) -> i32 {
    unsafe {
        let result;
        asm!(
            "call {}",
            // Function pointer to call
            in(reg) foo,
            // 1st argument in rdi
            in("rdi") arg,
            // Return value in rax
            out("rax") result,
            // Mark all registers which are not preserved by the "C" calling
            // convention as clobbered.
            clobber_abi("C"),
        );
        result
    }
}
}
}

Register template modifiers

In some cases, fine control is needed over the way a register name is formatted when inserted into the template string. This is needed when an architecture's assembly language has several names for the same register, each typically being a "view" over a subset of the register (e.g. the low 32 bits of a 64-bit register).

By default the compiler will always choose the name that refers to the full register size (e.g. rax on x86-64, eax on x86, etc).

This default can be overridden by using modifiers on the template string operands, just like you would with format strings:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut x: u16 = 0xab;

unsafe {
    asm!("mov {0:h}, {0:l}", inout(reg_abcd) x);
}

assert_eq!(x, 0xabab);
}
}

In this example, we use the reg_abcd register class to restrict the register allocator to the 4 legacy x86 registers (ax, bx, cx, dx) of which the first two bytes can be addressed independently.

Let us assume that the register allocator has chosen to allocate x in the ax register. The h modifier will emit the register name for the high byte of that register and the l modifier will emit the register name for the low byte. The asm code will therefore be expanded as mov ah, al which copies the low byte of the value into the high byte.

If you use a smaller data type (e.g. u16) with an operand and forget to use template modifiers, the compiler will emit a warning and suggest the correct modifier to use.

Memory address operands

Sometimes assembly instructions require operands passed via memory addresses/memory locations. You have to manually use the memory address syntax specified by the target architecture. For example, on x86/x86_64 using Intel assembly syntax, you should wrap inputs/outputs in [] to indicate they are memory operands:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

fn load_fpu_control_word(control: u16) {
    unsafe {
        asm!("fldcw [{}]", in(reg) &control, options(nostack));
    }
}
}
}

Labels

Any reuse of a named label, local or otherwise, can result in an assembler or linker error or may cause other strange behavior. Reuse of a named label can happen in a variety of ways including:

  • explicitly: using a label more than once in one asm! block, or multiple times across blocks.
  • implicitly via inlining: the compiler is allowed to instantiate multiple copies of an asm! block, for example when the function containing it is inlined in multiple places.
  • implicitly via LTO: LTO can cause code from other crates to be placed in the same codegen unit, and so could bring in arbitrary labels.

As a consequence, you should only use GNU assembler numeric local labels inside inline assembly code. Defining symbols in assembly code may lead to assembler and/or linker errors due to duplicate symbol definitions.

Moreover, on x86 when using the default Intel syntax, due to an LLVM bug, you shouldn't use labels exclusively made of 0 and 1 digits, e.g. 0, 11 or 101010, as they may end up being interpreted as binary values. Using options(att_syntax) will avoid any ambiguity, but that affects the syntax of the entire asm! block. (See Options, below, for more on options.)

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a = 0;
unsafe {
    asm!(
        "mov {0}, 10",
        "2:",
        "sub {0}, 1",
        "cmp {0}, 3",
        "jle 2f",
        "jmp 2b",
        "2:",
        "add {0}, 2",
        out(reg) a
    );
}
assert_eq!(a, 5);
}
}

This will decrement the {0} register value from 10 to 3, then add 2 and store it in a.

This example shows a few things:

  • First, that the same number can be used as a label multiple times in the same inline block.
  • Second, that when a numeric label is used as a reference (as an instruction operand, for example), the suffixes “b” (“backward”) or ”f” (“forward”) should be added to the numeric label. It will then refer to the nearest label defined by this number in this direction.

Options

By default, an inline assembly block is treated the same way as an external FFI function call with a custom calling convention: it may read/write memory, have observable side effects, etc. However, in many cases it is desirable to give the compiler more information about what the assembly code is actually doing so that it can optimize better.

Let's take our previous example of an add instruction:

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
    asm!(
        "add {0}, {1}",
        inlateout(reg) a, in(reg) b,
        options(pure, nomem, nostack),
    );
}
assert_eq!(a, 8);
}
}

Options can be provided as an optional final argument to the asm! macro. We specified three options here:

  • pure means that the asm code has no observable side effects and that its output depends only on its inputs. This allows the compiler optimizer to call the inline asm fewer times or even eliminate it entirely.
  • nomem means that the asm code does not read or write to memory. By default the compiler will assume that inline assembly can read or write any memory address that is accessible to it (e.g. through a pointer passed as an operand, or a global).
  • nostack means that the asm code does not push any data onto the stack. This allows the compiler to use optimizations such as the stack red zone on x86-64 to avoid stack pointer adjustments.

These allow the compiler to better optimize code using asm!, for example by eliminating pure asm! blocks whose outputs are not needed.

See the reference for the full list of available options and their effects.

Б. пр.

1

вписан асемблер – inline assembly

2

нареждане – instruction

3

низов образец – template string

Съвместимост

Езикът Ръждьо се развива бързо, поради което могат да се появят някои затруднения със съвместимостта въпреки полаганите усилия за осигуряване на колкото се може повече бъдеща съвместитмост.

Сурови наименования

Както много други езици Ръждьо има понятието „ключови думи”. Тези думи означават нещо в езика и затова не можем да ги ползваме за имена на променливи, функции и на други места. Суровите наименования1 позволяват да се ползват ключови думи на места, където не биха били разрешени. Това е особено полезно, когато в Ръждьо биват въведени нови ключови думи, а някоя библиотека, използваща по-старо издание на Ръждьо, има променлива или функция със същото име като въведената в някое по-ново издание.

Например кошът foo, компилиран с изданието от 2015 г., изнася функция с име try. Тази дума е запазена за нова способност в изданието от 2018-та. Без да ползваме сурови наименования, няма начин да извикаме функцията.

extern crate foo;

fn main() {
    foo::try();
}

Ще видим тази грешка:

error: expected identifier, found keyword `try`
 --> src/main.rs:4:4
  |
4 | foo::try();
  |      ^^^ expected identifier, found keyword

Можем да я извикаме с помощта на сурово наименование:

extern crate foo;

fn main() {
    foo::r#try();
}

Б. пр.

1

наименование – identifier

Между другото1

Някои теми нямат пряко отношение към това как програмираме, но предоставят средства или инфраструктура, които просто помагат на всички. Такива теми са:

  • Документация: Създаване на документация за потребителите чрез включената програма rustdoc.
  • Игрална площадка2: Внедрява „Площадката за игра на Ръждьо” в нашата документация.

Б. пр.

1

отвъд, след, мета – meta. Заглавието на английски е „Meta”. Ако се опитаме да разтълкуваме значението на тази дума, като потърсим назад в миналото, ще открием, че тази дума може да означава много неща. Най-подходящият превод в случая е като опишем за какво става въпрос. Значенията могат да бъдат: след, зад, между, сред, над, отвъд. Вижте meta.

2

игрална площадка, пясъчник – playground, sandbox

Документация

Ползвайте cargo doc, за да изградите документация в target/doc.

Ползвайте cargo test, за да пуснете всички тестове (включително тези от документацията), а cargo test --doc – само за документните тестове.

Тези команди ще извикат съответно rustdoc (и rustc) според необходимостта.

Документни коментари

Документните коментари са много полезни за големи проекти. Когато пуснем rustdoc, тези коментари се компилират като документация. Те се означават с /// и биват разбрани като Markdown.

#![crate_name = "doc"]

/// Тук се представя човешко същество.
pub struct Person {
    /// Личността трябва да има име, колкото и да го мрази Жулиета.
    name: String,
}

impl Person {
    /// Връща личност с даденото ѝ име.
    ///
    /// # Аргументи
    ///
    /// * `name` – Отрязък от низ, съдържащ името на лицето.
    ///
    /// # Примери
    ///
    /// ```
    /// // Може да имаме ограден код на Ръждьо вътре в коментарите
    /// // Ако подадем  --test на `rustdoc`, тя ще изпълни и тестовете!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// Дава приятелски поздрав!
    ///
    /// Казва "Hello, [name](Person::name)" на лицето, с което е извикана.
    pub fn hello(& self) {
        println!("Hello, {}!", self.name);
    }
}

fn main() {
    let john = Person::new("John");

    john.hello();
}

За да пуснете тестовете, първо изградете кода като библиотека, после кажете на rustdoc къде да намери библиотеката, така че да може да я свърже с всеки документен тест:

$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs

Документни атрибути

Следват няколко примера с най-използваните аргументи за атрибута #[doc].

inline

Използва се за вместване на документацията, вместо да се прави връзка към отделна страница.

#[doc(inline)]
pub use bar::Bar;

/// документация за bar
mod bar {
    /// документацията за Bar
    pub struct Bar;
}

no_inline

Използва се, за да предотврати свързване към отделна страница или където и да е.

// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;

hidden

С това казваме на rustdoc да не включва това в документацията:

// Example from the futures-rs library
#[doc(hidden)]
pub use self::async_await::*;

rustdoc се използва широко от общността. С тази програма е създадена документацията за стандартната библиотека.

Вижте също:

Игрална площадка

Игралната площадка на Ръждьо е място за опити с код на Ръждьо през уеб четец.

Ползване с mdbook

В mdbook можем да направим примерите да могат да се изпълняват и редактират.

fn main() {
    println!("Hello World!");
}

Това позволява читателят не само да чете примерите с код , но и да ги променя. Същественото тук е да добавим думата editable към оградения ни блок код, разделен от предната дума със запетая.

```rust,editable
//...place your code here
```

В допълнение можем да добавим ignore, ако искаме mdbook да пропусне този код, докато изгражда и тества документацията като книга.

```rust,editable,ignore
//...place your code here
```

Ползване с документация

Може би сте забелязали някъде в представителната документация на Ръждьо бутона „Run”, който отваря примера с код в нов раздел в Игралната площадка на Ръждьо. Тази способност се включва, ако ползваме атрибута #[doc], наречен html_playground_url.

Вижте също: