Немного о том, как "готовить" Rust

Содержание

Для кого эта книга
Как читать эту книгу
Как использовать рецепты
Несколько слов об обработке ошибок
Несколько слов о выборе крейтов

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

Как читать эту книгу

Книга содержит указатель всех рецептов, организованных в разделы: "основы", "кодирование данных", "конкурентность" и так далее. Сами по себе разделы более или менее упорядочены по сложности, более поздние разделы обычно требуют подготовки, и иногда требуют понимания материала, встречающегося в предыдущих разделах.

В указателе каждый раздел содержит список рецептов. Рецепты представляют собой постановку задачи, например "сгенерировать случайные числа из диапазона"; и каждый рецепт помечен "шильдиками", показывающими какие крейты они используют (крейты (crates) - так называются библиотеки в экосистеме Rust), например , а также к каким категориям в crates.io эти крейты принадлежат, например .

Новичкам скорее всего будет комфортно читать последовательно с первого раздела до последнего и такое чтение даст хорошее представление об экосистеме. Нажимайте на заголовок раздела в указателе или на боковой панели, чтобы перейти прямо к нужному разделу в книге.

Если вы просто ищете решение для какой-то простой задачи, эта книга на данный момент более трудна для такого поиска. Самый простой путь чтобы найти нужный рецепт - это просмотреть указатель на предмет нужных крейтов и категорий, которые вас интересуют. И там уже нажимайте на название рецепта, чтобы посмотреть его полностью. Эту неэффективность мы исправим в будущем.

Как использовать рецепты

Рецепты построены так, чтобы дать вам мгновенный доступ к работающему коду наряду с полным объяснением, как он работает и дать вам пути, для получения дальнейшей информации по этой теме.

Все рецепты в этом сборнике являются полными, самодостаточными программами и могут быть скопированы прямо в ваш проект для дальнейших экспериментов с ними. Чтобы сделать это следуйте инструкциям ниже.

Рассмотрим пример "сгенерировать случайные числа из диапазона":

extern crate rand;
use rand::Rng;
fn main() {
    let mut rng = rand::thread_rng();
    println!("Random f64: {}", rng.gen::<f64>());
}

Чтобы "поиграться" с ним локально, вам нужно запустить следующие команды для создания нового cargo-проекта (cargo - это пакетный менеджер для Rust) и перейти внутрь только что созданного проекта:

cargo new my-example --bin
cd my-example

Теперь вам также нужно добавить все необходимые крейты в файл Cargo.toml, как показано в "шильдиках", в данном случае просто rand. Чтобы это сделать, используйте команду cargo add, которая реализована в крейте cargo-edit и вам его нужно сначала установить:

cargo install cargo-edit
cargo add rand

Теперь вы можете заменить содержимое файла src/main.rs на полностью скопированное из рецепта и запустить этот код:

cargo run

Шильдики крейтов, которые сопровождают примеры кода также содержат ссылки на документацию по соответствующим крестам на сайте docs.rs, и часто на дополнительную документацию по тем крестам, которые могут быть вам полезны и возможно подходят вам для решения вашей задачи.

Несколько слов об обработке ошибок

Обработка ошибок в Rust надёжна, если её использовать правильно, но в настоящее время требует некоторого количества повторяющегося кода. Из-за такого повторяющегося кода (boilerplate) можно встретить примеры программ на Rust, которые содержат вызовы unwrap вместо правильной обработки ошибок.

Поскольку эти рецепты предназначены для использования в реальных проектах и должны внедрить наилучшие практики, они также сделаны таким образом, чтобы обеспечить правильную обработку ошибок в случаях, когда появляются типы Option и Result.

Основной шаблон - это использовать главную функцию fn main() -> Result.

Обычно структура примеров выглядит как-то так:

#[macro_use]
extern crate error_chain;
use std::net::IpAddr;
use std::str;
error_chain! {
    foreign_links {
        Utf8(std::str::Utf8Error);
        AddrParse(std::net::AddrParseError);
    }
}
fn main() -> Result<()> {
    let bytes = b"2001:db8::1";
    // Bytes to string.
    let s = str::from_utf8(bytes)?;
    // String to IP address.
    let addr: IpAddr = s.parse()?;
    println!("{:?}", addr);
    Ok(())
}

Этот пример использует макрос error_chain! чтобы определить пользовательские типы Error и Result, наряду с автоматическими преобразованиями для типов ошибок из стандартной библиотеки. Такие автоматические преобразования позволят работать оператору ?.

Для целей повышения читаемости механический код связанный с обработкой ошибок по умолчанию скрыт. Чтобы посмотреть полное содержимое примера, нажмите на кнопку "expand" (

#[macro_use]
extern crate error_chain;
extern crate url;
use url::{Url, Position};

error_chain! {
    foreign_links {
        UrlParse(url::ParseError);
    }
}
fn main() -> Result<()> {
    let parsed = Url::parse("https://httpbin.org/cookies/set?k2=v2&k1=v1")?;
    let cleaned: &str = &parsed[..Position::AfterPath];
    println!("cleaned: {}", cleaned);
    Ok(())
}

Для более глубокого изучения обработки ошибок в Rust, читайте эту главу в Rust book, этот блог пост, (и документацию по крейту https://docs.rs/snafu/0.1.4/snafu/ - прим. перев.)

Несколько слов о выборе крейтов

Эта книга предназначена в конечном итоге дать полноценное покрытие экосистемы вокруг Rust, но на сегодняшний день книга ограничена в охвате, пока мы работаем над инструментами и способом подачи материала книги. Надеемся, начав с малого охвата и постепенно расширяясь книга скоро станет источником высокого качества и будет поддерживать высокий стандарт качества по мере наполнения.

В настоящий момент книга Rust. Сборник рецептов в-основном сосредоточена на стандартной библиотеке, и на "центральных" или "основных" крейтах - эти крейты обеспечивают выполнение самых распространённых программистских задач, и остальная часть экосистемы выстроена на этой основе.

Эта книга очень близко связана с Rust Libz Blitz, проектом, чтобы собрать информацию о библиотеках и улучшить их качество и книга оставляет "привилегию" выбора за этим проектом. Любой крейт, упомянутый в книге уже прошёл проверку в рамках этого проекта, но также есть и крейты ожидающие такой проверки.

Rust Cookbook