Введение путей в область видимости с помощью ключевого слова use

Необходимость выписывать пути для вызова функций может ощущаться неудобной и повторяющейся. В листинге 7-7, независимо от того, выбрали ли мы абсолютный или относительный путь к функции add_to_waitlist, каждый раз, когда мы хотели вызвать add_to_waitlist, нам приходилось указывать также front_of_house и hosting. К счастью, есть способ упростить этот процесс: мы можем создать сокращение для пути с помощью ключевого слова use один раз, а затем использовать более короткое имя везде в этой области видимости.

В листинге 7-11 мы вводим crate::front_of_house::hosting в область видимости функции eat_at_restaurant, так что нам нужно указывать только hosting::add_to_waitlist, чтобы вызвать функцию add_to_waitlist в eat_at_restaurant.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}
Листинг 7-11: Введение модуля в область видимости с помощью use

Добавление use и пути в область видимости аналогично созданию символической ссылки в файловой системе. Добавив use crate::front_of_house::hosting в корень крейта, hosting теперь является допустимым именем в этой области видимости, как если бы модуль hosting был определён в корне крейта. Пути, введённые в область видимости с помощью use, также проверяются на приватность, как и любые другие пути.

Обратите внимание, что use создаёт сокращение только для той конкретной области видимости, в которой встречается use. Листинг 7-12 перемещает функцию eat_at_restaurant в новый дочерний модуль с именем customer, который затем является другой областью видимости, чем оператор use, поэтому тело функции не скомпилируется.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}
Листинг 7-12: Оператор use применяется только в той области видимости, в которой он находится.

Ошибка компилятора показывает, что сокращение больше не действует внутри модуля customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: cannot find module or crate `hosting` in this scope
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   |
   = help: if you wanted to use a crate named `hosting`, use `cargo add hosting` to add it to your `Cargo.toml`
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

Обратите внимание, что также есть предупреждение о том, что use больше не используется в своей области видимости! Чтобы исправить эту проблему, переместите use также внутрь модуля customer или обратитесь к сокращению в родительском модуле через super::hosting внутри дочернего модуля customer.

Создание идиоматичных путей use

В листинге 7-11 вы могли задаться вопросом, почему мы указали use crate::front_of_house::hosting, а затем вызвали hosting::add_to_waitlist в eat_at_restaurant, вместо того чтобы указать путь use вплоть до функции add_to_waitlist, чтобы достичь того же результата, как в листинге 7-13.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}
Листинг 7-13: Введение функции add_to_waitlist в область видимости с помощью use, что неидиоматично

Хотя листинг 7-11 и листинг 7-13 выполняют одну и ту же задачу, листинг 7-11 является идиоматичным способом введения функции в область видимости с помощью use. Введение родительского модуля функции в область видимости с помощью use означает, что нам нужно указывать родительский модуль при вызове функции. Указание родительского модуля при вызове функции делает ясным, что функция не определена локально, при этом минимизируя повторение полного пути. Код в листинге 7-13 неясен относительно того, где определена add_to_waitlist.

С другой стороны, при введении структур, перечислений и других элементов с помощью use идиоматично указывать полный путь. Листинг 7-14 показывает идиоматичный способ введения структуры HashMap из стандартной библиотеки в область видимости бинарного крейта.

Имя файла: src/main.rs
use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}
Листинг 7-14: Введение HashMap в область видимости идиоматичным способом

За этой идиомой нет веской причины: это просто соглашение, которое возникло, и люди привыкли читать и писать код на Rust таким образом.

Исключение из этой идиомы — если мы вводим два элемента с одинаковым именем в область видимости с помощью операторов use, потому что Rust этого не позволяет. Листинг 7-15 показывает, как ввести два типа Result в область видимости, которые имеют одинаковое имя, но разные родительские модули, и как ссылаться на них.

Имя файла: src/lib.rs
use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}
Листинг 7-15: Введение двух типов с одинаковым именем в одну и ту же область видимости требует использования их родительских модулей.

Как видите, использование родительских модулей различает два типа Result. Если бы вместо этого мы указали use std::fmt::Result и use std::io::Result, у нас было бы два типа Result в одной области видимости, и Rust не знал бы, какой из них мы имели в виду, когда использовали Result.

Предоставление новых имён с помощью ключевого слова as

Есть ещё одно решение проблемы введения двух типов с одинаковым именем в одну и ту же область видимости с помощью use: после пути мы можем указать as и новое локальное имя, или псевдоним, для типа. Листинг 7-16 показывает другой способ написать код из листинга 7-15, переименовав один из двух типов Result с помощью as.

Имя файла: src/lib.rs
use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}
Листинг 7-16: Переименование типа при его введении в область видимости с помощью ключевого слова as

Во втором операторе use мы выбрали новое имя IoResult для типа std::io::Result, которое не будет конфликтовать с Result из std::fmt, который мы также ввели в область видимости. Листинг 7-15 и листинг 7-16 считаются идиоматичными, так что выбор за вами!

Реэкспорт имён с помощью pub use

Когда мы вводим имя в область видимости с помощью ключевого слова use, имя является приватным для той области видимости, в которую мы его импортировали. Чтобы позволить коду за пределами этой области видимости ссылаться на это имя, как если бы оно было определено в этой области видимости, мы можем объединить pub и use. Этот приём называется реэкспортом, потому что мы вводим элемент в область видимости, но также делаем этот элемент доступным для других, чтобы они могли ввести его в свою область видимости.

Листинг 7-17 показывает код из листинга 7-11 с use в корневом модуле, изменённым на pub use.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}
Листинг 7-17: Делаем имя доступным для любого кода из новой области видимости с помощью pub use

До этого изменения внешнему коду пришлось бы вызывать функцию add_to_waitlist, используя путь restaurant::front_of_house::hosting::add_to_waitlist(), что также потребовало бы пометить модуль front_of_house как pub. Теперь, когда этот pub use реэкспортировал модуль hosting из корневого модуля, внешний код может использовать путь restaurant::hosting::add_to_waitlist() вместо этого.

Реэкспорт полезен, когда внутренняя структура вашего кода отличается от того, как программисты, вызывающие ваш код, думали бы о предметной области. Например, в этой метафоре ресторана люди, управляющие рестораном, думают о «входной зоне» и «задней зоне». Но посетители ресторана, вероятно, не будут думать о частях ресторана в этих терминах. С помощью pub use мы можем написать наш код с одной структурой, но предоставить другую структуру. Это делает нашу библиотеку хорошо организованной как для программистов, работающих над библиотекой, так и для программистов, вызывающих библиотеку. Мы рассмотрим другой пример pub use и то, как он влияет на документацию вашего крейта, в «Экспорт удобного публичного API» в главе 14.

Использование внешних пакетов

В главе 2 мы программировали проект игры в угадайку, который использовал внешний пакет под названием rand для получения случайных чисел. Чтобы использовать rand в нашем проекте, мы добавили эту строку в Cargo.toml:

Имя файла: Cargo.toml
rand = "0.10.1"

Добавление rand в качестве зависимости в Cargo.toml говорит Cargo загрузить пакет rand и любые зависимости с crates.io и сделать rand доступным для нашего проекта.

Затем, чтобы ввести определения rand в область видимости нашего пакета, мы добавили строку use, начинающуюся с имени крейта rand, и перечислили элементы, которые хотели ввести в область видимости. Вспомните, что в «Генерация случайного числа» в главе 2 мы ввели элементы из модуля rand::prelude в область видимости и вызвали функцию rand::rng:

use std::io;

use rand::prelude::*;

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

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

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

    println!("You guessed: {guess}");
}

Члены сообщества Rust сделали множество пакетов доступными на crates.io, и включение любого из них в ваш пакет включает те же шаги: перечислить их в файле Cargo.toml вашего пакета и использовать use для введения элементов из их крейтов в область видимости.

Обратите внимание, что стандартная библиотека std также является крейтом, внешним по отношению к нашему пакету. Поскольку стандартная библиотека поставляется вместе с языком Rust, нам не нужно изменять Cargo.toml, чтобы включить std. Но нам нужно ссылаться на неё с помощью use, чтобы ввести элементы оттуда в область видимости нашего пакета. Например, с HashMap мы бы использовали эту строку:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Это абсолютный путь, начинающийся с std, имени крейта стандартной библиотеки.

Использование вложенных путей для очистки списков use

Если мы используем несколько элементов, определённых в одном и том же крейте или одном и том же модуле, перечисление каждого элемента на отдельной строке может занимать много вертикального пространства в наших файлах. Например, эти два оператора use, которые у нас были в игре в угадайку в листинге 2-4, вводят элементы из std в область видимости:

Имя файла: src/main.rs
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

use rand::prelude::*;

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

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

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

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Вместо этого мы можем использовать вложенные пути, чтобы ввести те же элементы в область видимости в одной строке. Мы делаем это, указывая общую часть пути, за которой следуют два двоеточия, а затем фигурные скобки вокруг списка различающихся частей путей, как показано в листинге 7-18.

Имя файла: src/main.rs
use rand::prelude::*;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

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

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

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

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

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}
Листинг 7-18: Указание вложенного пути для введения нескольких элементов с одинаковым префиксом в область видимости

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

Мы можем использовать вложенный путь на любом уровне пути, что полезно при объединении двух операторов use, которые имеют общий подпуть. Например, листинг 7-19 показывает два оператора use: один вводит std::io в область видимости, а другой вводит std::io::Write в область видимости.

Имя файла: src/lib.rs
use std::io;
use std::io::Write;
Листинг 7-19: Два оператора use, где один является подпутём другого

Общая часть этих двух путей — std::io, и это полный первый путь. Чтобы объединить эти два пути в один оператор use, мы можем использовать self в вложенном пути, как показано в листинге 7-20.

Имя файла: src/lib.rs
use std::io::{self, Write};
Листинг 7-20: Объединение путей из листинга 7-19 в один оператор use

Эта строка вводит std::io и std::io::Write в область видимости.

Импорт элементов с помощью оператора глоб

Если мы хотим ввести все публичные элементы, определённые в пути, в область видимости, мы можем указать этот путь, за которым следует оператор глоб *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Этот оператор use вводит все публичные элементы, определённые в std::collections, в текущую область видимости. Будьте осторожны при использовании оператора глоб! Глоб может затруднить определение того, какие имена находятся в области видимости и где используется имя в вашей программе было определено. Кроме того, если зависимость изменяет свои определения, то, что вы импортировали, также изменится, что может привести к ошибкам компилятора при обновлении зависимости, если зависимость добавляет определение с тем же именем, что и ваше определение в той же области видимости, например.

Оператор глоб часто используется при тестировании для введения всего тестируемого в модуль tests; мы поговорим об этом в «Как писать тесты» в главе 11. Оператор глоб также иногда используется как часть шаблона prelude: см. документацию стандартной библиотеки для получения дополнительной информации об этом шаблоне.