Введение путей в область видимости с помощью ключевого слова 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.
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();
}
useДобавление use и пути в область видимости аналогично созданию символической ссылки в
файловой системе. Добавив use crate::front_of_house::hosting в корень крейта,
hosting теперь является допустимым именем в этой области видимости, как если бы модуль hosting
был определён в корне крейта. Пути, введённые в область видимости с помощью use,
также проверяются на приватность, как и любые другие пути.
Обратите внимание, что use создаёт сокращение только для той конкретной области видимости, в которой
встречается use. Листинг 7-12 перемещает функцию eat_at_restaurant в новый
дочерний модуль с именем customer, который затем является другой областью видимости, чем
оператор use, поэтому тело функции не скомпилируется.
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();
}
}
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.
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();
}
add_to_waitlist в область видимости с помощью use, что неидиоматичноХотя листинг 7-11 и листинг 7-13 выполняют одну и ту же задачу, листинг
7-11 является идиоматичным способом введения функции в область видимости с помощью use. Введение
родительского модуля функции в область видимости с помощью use означает, что нам нужно указывать
родительский модуль при вызове функции. Указание родительского модуля при
вызове функции делает ясным, что функция не определена локально,
при этом минимизируя повторение полного пути. Код в листинге 7-13
неясен относительно того, где определена add_to_waitlist.
С другой стороны, при введении структур, перечислений и других элементов с помощью use
идиоматично указывать полный путь. Листинг 7-14 показывает идиоматичный способ
введения структуры HashMap из стандартной библиотеки в область видимости бинарного
крейта.
use std::collections::HashMap;
fn main() {
let mut map = HashMap::new();
map.insert(1, 2);
}
HashMap в область видимости идиоматичным способомЗа этой идиомой нет веской причины: это просто соглашение, которое возникло, и люди привыкли читать и писать код на Rust таким образом.
Исключение из этой идиомы — если мы вводим два элемента с одинаковым именем
в область видимости с помощью операторов use, потому что Rust этого не позволяет. Листинг 7-15
показывает, как ввести два типа Result в область видимости, которые имеют одинаковое имя, но
разные родительские модули, и как ссылаться на них.
use std::fmt;
use std::io;
fn function1() -> fmt::Result {
// --snip--
Ok(())
}
fn function2() -> io::Result<()> {
// --snip--
Ok(())
}
Как видите, использование родительских модулей различает два типа Result.
Если бы вместо этого мы указали use std::fmt::Result и use std::io::Result, у нас
было бы два типа Result в одной области видимости, и Rust не знал бы, какой из них мы
имели в виду, когда использовали Result.
Предоставление новых имён с помощью ключевого слова as
Есть ещё одно решение проблемы введения двух типов с одинаковым именем
в одну и ту же область видимости с помощью use: после пути мы можем указать as и новое
локальное имя, или псевдоним, для типа. Листинг 7-16 показывает другой способ написать
код из листинга 7-15, переименовав один из двух типов Result с помощью as.
use std::fmt::Result;
use std::io::Result as IoResult;
fn function1() -> Result {
// --snip--
Ok(())
}
fn function2() -> IoResult<()> {
// --snip--
Ok(())
}
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.
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();
}
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:
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 в область видимости:
// --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.
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!"),
}
}
В больших программах введение множества элементов в область видимости из одного и того же крейта или
модуля с использованием вложенных путей может значительно сократить количество отдельных операторов use,
необходимых!
Мы можем использовать вложенный путь на любом уровне пути, что полезно при объединении
двух операторов use, которые имеют общий подпуть. Например, листинг 7-19 показывает два
оператора use: один вводит std::io в область видимости, а другой вводит
std::io::Write в область видимости.
use std::io;
use std::io::Write;
use, где один является подпутём другогоОбщая часть этих двух путей — std::io, и это полный первый
путь. Чтобы объединить эти два пути в один оператор use, мы можем использовать self в
вложенном пути, как показано в листинге 7-20.
use std::io::{self, Write};
useЭта строка вводит std::io и std::io::Write в область видимости.
Импорт элементов с помощью оператора глоб
Если мы хотим ввести все публичные элементы, определённые в пути, в область видимости, мы можем
указать этот путь, за которым следует оператор глоб *:
#![allow(unused)]
fn main() {
use std::collections::*;
}
Этот оператор use вводит все публичные элементы, определённые в std::collections, в
текущую область видимости. Будьте осторожны при использовании оператора глоб! Глоб может
затруднить определение того, какие имена находятся в области видимости и где используется имя в вашей программе
было определено. Кроме того, если зависимость изменяет свои определения, то, что
вы импортировали, также изменится, что может привести к ошибкам компилятора при обновлении зависимости, если зависимость добавляет определение с тем же именем,
что и ваше определение в той же области видимости, например.
Оператор глоб часто используется при тестировании для введения всего тестируемого
в модуль tests; мы поговорим об этом в «Как писать
тесты» в главе 11. Оператор глоб также
иногда используется как часть шаблона prelude: см. документацию
стандартной библиотеки для получения дополнительной
информации об этом шаблоне.