Введение

Эта книга является основным справочником по языку программирования Rust.

Релизы Rust

Новые версии языка Rust выпускаются каждые шесть недель. Первый стабильный релиз языка — Rust 1.0.0, за ним последовали Rust 1.1.0 и так далее. Инструменты (rustc, cargo и др.) и документация (GitHub issues, эта книга и др.) выпускаются вместе с релизом языка.

Последнюю версию этой книги, соответствующую последней версии Rust, всегда можно найти по адресу https://doc.rust-lang.org/reference/. Предыдущие версии можно найти, добавив версию Rust перед каталогом “reference”. Например, Справочник для Rust 1.49.0 находится по адресу https://doc.rust-lang.org/1.49.0/reference/.

Чем Справочник не является

Эта книга не служит введением в язык. Предполагается, что читатель уже знаком с основами языка. Для получения таких базовых знаний доступна book.

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

Аналогично, эта книга обычно не описывает специфику rustc как инструмента или Cargo. У rustc есть rustc book. У Cargo есть cargo book, которая содержит cargo reference. Есть несколько страниц, таких как linkage, которые всё же описывают, как работает rustc.

Эта книга также служит справочником только по тому, что доступно в стабильной версии Rust. Для получения информации о нестабильных функциях, находящихся в разработке, см. Unstable Book.

Компиляторы Rust, включая rustc, выполняют оптимизации. Справочник не определяет, какие оптимизации разрешены или запрещены. Вместо этого рассматривайте скомпилированную программу как “чёрный ящик”. Её можно исследовать только путём запуска, подачи на вход данных и наблюдения за её выводом. Всё, что происходит таким образом, должно соответствовать тому, что указано в справочнике.

Как пользоваться этой книгой

Эта книга не предполагает, что вы читаете её последовательно. Каждая глава, как правило, может быть прочитана самостоятельно, но будет содержать перекрёстные ссылки на другие главы для аспектов языка, на которые она ссылается, но не обсуждает.

Есть два основных способа чтения этого документа.

Первый — найти ответ на конкретный вопрос. Если вы знаете, какая глава отвечает на этот вопрос, вы можете перейти к этой главе через оглавление. В противном случае вы можете нажать s или щёлкнуть значок лупы на верхней панели, чтобы найти ключевые слова, связанные с вашим вопросом. Например, предположим, вы хотите узнать, когда удаляется временное значение, созданное в операторе let. Если вы ещё не знаете, что lifetime of temporaries определено в главе о выражениях, вы можете выполнить поиск по запросу “temporary let”, и первый результат поиска приведёт вас к этому разделу.

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

Тем не менее, не существует неправильного способа читать эту книгу. Читайте её так, как, по вашему мнению, вам лучше всего подходит.

Соглашения

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

• Утверждения, определяющие термин, содержат этот термин курсивом. Всякий раз, когда этот термин используется вне данной главы, он обычно представляет собой ссылку на раздел, содержащий это определение.

  Пример термина — это пример определяемого термина.

• Основной текст описывает последнюю стабильную редакцию (edition). Различия с предыдущими редакциями выделены в специальных блоках:

  2018 Edition differences

  До редакции 2018 года поведение было таким. Начиная с редакции 2018 года, поведение стало таким.

• Примечания, содержащие полезную информацию о состоянии книги или указывающие на полезную, но в основном выходящую за рамки книги информацию, помещаются в блоки-примечания.

  Note

  Это пример примечания.

• Блоки-примеры показывают пример, демонстрирующий какое-либо правило или отмечающий интересный аспект. Некоторые примеры могут содержать скрытые строки, которые можно просмотреть, нажав на значок глаза, который появляется при наведении курсора или нажатии на пример.

  Example

  Это пример кода.

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

• Предупреждения, показывающие некорректное (unsound) поведение в языке или, возможно, запутанные взаимодействия языковых возможностей, помещаются в специальные блоки-предупреждения.

  Warning

  Это пример предупреждения.

• Фрагменты кода в тексте выделены <code> тегами.

  Более длинные примеры кода помещаются в блок с подсветкой синтаксиса, который имеет элементы управления для копирования, выполнения и показа скрытых строк в правом верхнем углу.

  // Это скрытая строка.
  fn main() {
      println!("Это пример кода");
  }

  Все примеры написаны для последней редакции, если не указано иное.

• Грамматика и лексические конструкции описаны в Нотация.

• Идентификаторы правил появляются перед каждым языковым правилом в квадратных скобках. Эти идентификаторы предоставляют способ ссылаться на конкретное правило в языке и ссылаться на него (например). Идентификатор правила использует точки для разделения секций от наиболее общих к наиболее конкретным (например, destructors.scope.nesting.function-body). На узких экранах имя правила сворачивается и отображается как [*].

  На имя правила можно щёлкнуть, чтобы перейти по ссылке на это правило.

  Warning

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

• Правила, для которых существуют связанные тесты, будут содержать ссылку Tests под собой (на узких экранах ссылка выглядит как [T]). Нажатие на ссылку вызовет список тестов, на которые можно щёлкнуть для просмотра теста. Например, см. input.encoding.utf8.

  Связывание правил с тестами — это непрерывный процесс. Обзор см. в главе Сводка тестов.

Участие в разработке

Мы приветствуем любой вклад.

Вы можете внести свой вклад в эту книгу, открыв вопрос (issue) или отправив запрос на принятие изменений (pull request) в the Rust Reference repository. Если эта книга не отвечает на ваш вопрос, и вы считаете, что ответ на него должен быть в ней, пожалуйста, не стесняйтесь создать вопрос или спросить об этом в потоке t-lang/doc на Zulip. Знание того, для чего люди чаще всего используют эту книгу, помогает нам направить внимание на то, чтобы сделать эти разделы как можно лучше. И, конечно, если вы видите что-то неправильное или не нормативное, но не указанное явно как таковое, также, пожалуйста, создайте вопрос.

Нотация

Грамматика

В грамматических фрагментах Лексера и Синтаксиса используются следующие обозначения:

Последовательности имеют более высокий приоритет, чем альтернатива |.

Продукции таблицы строк

Некоторые правила в грамматике — в частности, унарные операторы, бинарные операторы и ключевые слова — представлены в упрощённой форме: в виде перечня печатаемых строк. Эти случаи образуют подмножество правил, касающихся Токены, и предполагается, что они являются результатом фазы лексического анализа, которая передаёт данные парсеру, управляемая ДКА, работающим над дизъюнкцией всех таких записей таблицы строк.

Когда такая строка в шрифте monospace встречается внутри грамматики, это неявная ссылка на отдельный элемент такой продукции таблицы строк. Более подробную информацию см. в разделе Токены.

Визуализация грамматики

Под каждым блоком грамматики находится кнопка для переключения отображения синтаксической диаграммы. Квадратный элемент представляет собой нетерминальное правило, а скруглённый прямоугольник — терминал.

Лексические структуры

Формат входных данных

Эта глава описывает, как исходный файл интерпретируется как последовательность токенов.

Описание того, как программы организованы в файлы, см. в разделе Крейты и исходные файлы

Кодировка исходного кода

Каждый исходный файл интерпретируется как последовательность символов Юникода, закодированных в UTF-8.

Ошибкой является случай, если файл не является корректным UTF-8.

Удаление метки порядка байт (BOM)

Если первый символ в последовательности — U+FEFF (МЕТКА ПОРЯДКА БАЙТ), он удаляется.

Нормализация CRLF

Каждая пара символов U+000D (CR), сразу за которой следует U+000A (LF), заменяется на один символ U+000A (LF). Это происходит однократно, а не повторно, поэтому после нормализации в входных данных всё ещё могут существовать U+000D (CR), сразу за которыми следует U+000A (LF) (например, если исходные данные содержали “CR CR LF LF”).

Остальные вхождения символа U+000D (CR) остаются на месте (они рассматриваются как пробельные символы).

Удаление шебанга (shebang)

Если оставшаяся последовательность начинается с символов #!, символы до первого U+000A (LF) включительно удаляются из последовательности.

Например, первая строка следующего файла будет проигнорирована:

#!/usr/bin/env rustx

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

В качестве исключения, если за символами #! (игнорируя находящиеся между ними комментарии или пробельные символы) следует токен [, ничего не удаляется. Это предотвращает удаление внутреннего атрибута в начале исходного файла.

Токенизация

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

Ключевые слова

Rust делит ключевые слова на три категории:

• Строгие
• Зарезервированные
• Слабые

Строгие ключевые слова

Эти ключевые слова можно использовать только в соответствующих контекстах. Они не могут быть использованы в качестве имён:

• Элементов items
• [Переменных (Variables)]и параметров функций
• Полей и вариантов (variants)
• Параметров типов (Type parameters)
• Параметров времени жизни или меток циклов (loop labels)
• Макросов (Macros) или атрибутов (attributes)
• Заполнителей макросов (Macro placeholders)
• Крейтов (Crates)

Следующие ключевые слова присутствуют во всех редакциях (editions):

• _
• as
• async
• await
• break
• const
• continue
• crate
• dyn
• else
• enum
• extern
• false
• fn
• for
• if
• impl
• in
• let
• loop
• match
• mod
• move
• mut
• pub
• ref
• return
• self
• Self
• static
• struct
• super
• trait
• true
• type
• unsafe
• use
• where
• while

Зарезервированные ключевые слова

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

• abstract
• become
• box
• do
• final
• gen
• macro
• override
• priv
• try
• typeof
• unsized
• virtual
• yield

Слабые ключевые слова

Эти ключевые слова имеют особое значение только в определённых контекстах. Например, можно объявить переменную или метод с именем union.

• 'static
• macro_rules
• raw
• safe
• union

• macro_rules используется для создания пользовательских Macros.

• union используется для объявления union и является ключевым словом только при использовании в объявлении объединения.

• 'static используется для статического времени жизни и не может быть использован в качестве обобщённого параметра времени жизни (generic lifetime parameter) или loop label

  // error[E0262]: invalid lifetime parameter name: `'static`
  fn invalid_lifetime_parameter<'static>(s: &'static str) -> &'static str { s }
  

• safe используется для функций и статических переменных и имеет значение внутри внешних блоков (external blocks).

• raw используется для операторов сырого заимствования (raw borrow operators) и является ключевым словом только при сопоставлении с формой оператора сырого заимствования (например, &raw const expr или &raw mut expr).

Идентификаторы

Идентификаторы соответствуют спецификации UAX31 для версии Unicode 16.0, с добавлениями, описанными ниже. Некоторые примеры идентификаторов:

• foo
• _identifier
• r#true
• Москва
• 東京

Используемый профиль из UAX #31:

• Start := XID_Start, плюс символ подчёркивания (U+005F)
• Continue := XID_Continue
• Medial := пусто

Идентификаторы не могут быть строгими или зарезервированными ключевыми словами без префикса r#, описанного ниже в разделе Сырые идентификаторы.

Символы неразрывного нулевой ширины (ZWNJ U+200C) и соединения нулевой ширины (ZWJ U+200D) не допускаются в идентификаторах.

Идентификаторы ограничены ASCII-подмножеством XID_Start и XID_Continue в следующих ситуациях:

• Объявления extern crate (за исключением идентификатора в AsClause)
• Имена внешних крейтов, на которые ссылается path
• Имена module, загружаемые из файловой системы без атрибута path
• Элементы с атрибутом no_mangle
• Имена элементов во внешних блоках

Нормализация

Идентификаторы нормализуются с использованием Формы нормализации C (NFC), как определено в UAX15. Два идентификатора считаются равными, если равны их формы NFC.

Процедурные (proc-macro) и декларативные (mbe) макросы получают нормализованные идентификаторы на входе.

Raw идентификаторы

Сырой идентификатор похож на обычный идентификатор, но с префиксом r#. (Обратите внимание, что префикс r# не является частью самого идентификатора).

В отличие от обычного идентификатора, сырым идентификатором может быть любое строгое или зарезервированное ключевое слово, кроме перечисленных выше для RESERVED_RAW_IDENTIFIER.

Использование токена RESERVED_RAW_IDENTIFIER является ошибкой.

Комментарии

Обычные комментарии (не документационные)

Комментарии следуют общему стилю C++: строчные (//) и блочные (/* ... */) формы комментариев. Поддерживаются вложенные блочные комментарии.

Обычные комментарии интерпретируются как форма пробельных символов.

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

Строчные комментарии документации, начинающиеся ровно с трёх слешей (///), и блочные комментарии документации (/** ... */), оба являющиеся внешними комментариями документации, интерпретируются как специальный синтаксис для doc attributes.

То есть они эквивалентны написанию #[doc="..."] вокруг тела комментария, т.е. /// Foo превращается в #[doc="Foo"], а /** Bar */ превращается в #[doc="Bar"]. Следовательно, они должны появляться перед тем, что принимает внешний атрибут.

Строчные комментарии, начинающиеся с //!, и блочные комментарии /*! ... */ — это комментарии документации, которые применяются к родительскому элементу комментария, а не к элементу, который следует за ним.

То есть они эквивалентны написанию #![doc="..."] вокруг тела комментария. Комментарии //! обычно используются для документирования модулей, занимающих исходный файл.

Символ U+000D (CR) не допускается в комментариях документации.

Примеры

#![allow(unused)]
fn main() {
//! Комментарий документации, применяемый к неявному анонимному модулю этого крейта

pub mod outer_module {

    //!  - Внутренний строчный комментарий документации
    //!! - Все ещё внутренний строчный комментарий документации (но с восклицательным знаком в начале)

    /*!  - Внутренний блочный комментарий документации */
    /*!! - Все ещё внутренний блочный комментарий документации (но с восклицательным знаком в начале) */

    //   - Просто комментарий
    ///  - Внешний строчный комментарий документации (ровно 3 слеша)
    //// - Просто комментарий

    /*   - Просто комментарий */
    /**  - Внешний блочный комментарий документации (ровно 2 звёздочки) */
    /*** - Просто комментарий */

    pub mod inner_module {}

    pub mod nested_comments {
        /* В Rust /* мы можем /* вкладывать комментарии */ */ */

        // Все три типа блочных комментариев могут содержать или быть вложенными в
        // любой другой тип:

        /*   /* */  /** */  /*! */  */
        /*!  /* */  /** */  /*! */  */
        /**  /* */  /** */  /*! */  */
        pub mod dummy_item {}
    }

    pub mod degenerate_cases {
        // пустой внутренний строчный комментарий документации
        //!

        // пустой внутренний блочный комментарий документации
        /*!*/

        // пустой строчный комментарий
        //

        // пустой внешний строчный комментарий документации
        ///

        // пустой блочный комментарий
        /**/

        pub mod dummy_item {}

        // пустой блок с 2 звёздочками не является блоком документации, это блочный комментарий
        /***/

    }

    /* Следующий пример не разрешён, потому что внешние комментарии документации
       требуют элемент, который получит документацию */

    /// Где мой элемент?
  mod boo {}
}
}

Пробельные символы

Пробельный символ — это любая непустая строка, содержащая только символы, которые имеют свойство Юникода Pattern_White_Space.

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

Программа на Rust имеет идентичное значение, если каждый пробельный элемент заменён на любой другой допустимый пробельный элемент, такой как одиночный символ пробела.

Токены

Токены — это примитивные конструкции в грамматике, определяемые регулярными (нерекурсивными) языками. Исходный код Rust может быть разбит на следующие виды токенов:

• Ключевые словаKeywords
• Идентификаторыidentifier
• Литералы
• Времена жизни
• Знаки пунктуации
• Разделители

В грамматике этой документации “простые” токены представлены в форме продукций таблицы строк и отображаются шрифтом monospace.

Литералы

Литералы — это токены, используемые в литеральных выражениях.

Примеры

Символы и строки

Экранирования ASCII

Байтовые экранирования

Экранирования Unicode

Экранирования кавычек

Числа

Суффиксы

Суффикс — это последовательность символов, следующая за основной частью литерала (без пробелов между ними), имеющая ту же форму, что и несырой идентификатор или ключевое слово.

Любой вид литерала (строковый, целочисленный и т.д.) с любым суффиксом является допустимым токеном.

Токен литерала с любым суффиксом может быть передан в макрос без возникновения ошибки. Сам макрос решит, как интерпретировать такой токен и следует ли выдавать ошибку. В частности, спецификатор фрагмента literal для макросов по примеру сопоставляет токены литералов с произвольными суффиксами.

#![allow(unused)]
fn main() {
macro_rules! blackhole { ($tt:tt) => () }
macro_rules! blackhole_lit { ($l:literal) => () }

blackhole!("string"suffix); // OK
blackhole_lit!(1suffix); // OK
}

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

Символьные и строковые литералы

Символьные литералы

Символьный литерал — это одиночный символ Unicode, заключённый между двумя символами U+0027 (одинарная кавычка), за исключением самого U+0027, который должен быть экранирован предшествующим символом U+005C (\).

Строковые литералы

Строковый литерал — это последовательность любых символов Unicode, заключённая между двумя символами U+0022 (двойная кавычка), за исключением самого U+0022, который должен быть экранирован предшествующим символом U+005C (\).

Разрывы строк, представленные символом U+000A (LF), допускаются в строковых литералах. Символ U+000D (CR) не может появляться в строковом литерале. Когда неэкранированный символ U+005C (\) встречается непосредственно перед разрывом строки, разрыв строки не появляется в строке, представленной токеном. Подробнее см. Экранирования продолжения строки.

Символьные экранирования

Некоторые дополнительные экранирования доступны либо в символьных, либо в несырых строковых литералах. Экранирование начинается с U+005C (\) и продолжается одной из следующих форм:

• 7-битное экранирование кодовой точки начинается с U+0078 (x) и следует ровно две шестнадцатеричные цифры со значением до 0x7F. Оно обозначает символ ASCII со значением, равным предоставленному шестнадцатеричному значению. Более высокие значения не допускаются, поскольку неясно, означают ли они кодовые точки Unicode или байтовые значения.

• 24-битное экранирование кодовой точки начинается с U+0075 (u) и следует до шести шестнадцатеричных цифр, окружённых фигурными скобками U+007B ({) и U+007D (}). Оно обозначает кодовую точку Unicode, равную предоставленному шестнадцатеричному значению.

• Экранирование пробельного символа — это один из символов U+006E (n), U+0072 (r) или U+0074 (t), обозначающих значения Unicode U+000A (LF), U+000D (CR) или U+0009 (HT) соответственно.

• Нулевое экранирование — это символ U+0030 (0) и обозначает значение Unicode U+0000 (NUL).

• Экранирование обратной косой черты — это символ U+005C (\), который должен быть экранирован, чтобы обозначить сам себя.

Сырые строковые литералы

Сырые строковые литералы не обрабатывают никакие экранирования. Они начинаются с символа U+0072 (r), за которым следует менее 256 символов U+0023 (#) и символ U+0022 (двойная кавычка).

Тело сырой строки может содержать любую последовательность символов Unicode, кроме U+000D (CR). Оно завершается только другим символом U+0022 (двойная кавычка), за которым следует то же количество символов U+0023 (#), которое предшествовало открывающему символу U+0022 (двойная кавычка).

Все символы Unicode, содержащиеся в теле сырой строки, представляют самих себя, символы U+0022 (двойная кавычка) (кроме случая, когда за ними следует по крайней мере столько же символов U+0023 (#), сколько было использовано для начала сырого строкового литерала) или U+005C (\) не имеют никакого специального значения.

Примеры строковых литералов:

#![allow(unused)]
fn main() {
"foo"; r"foo";                     // foo
"\"foo\""; r#""foo""#;             // "foo"

"foo #\"# bar";
r##"foo #"# bar"##;                // foo #"# bar

"\x52"; "R"; r"R";                 // R
"\\x52"; r"\x52";                  // \x52
}

Байтовые и байтовые строковые литералы

Байтовые литералы

Байтовый литерал — это одиночный символ ASCII (в диапазоне U+0000 до U+007F) или одиночное экранирование, перед которым стоят символы U+0062 (b) и U+0027 (одинарная кавычка), и после которого следует символ U+0027. Если символ U+0027 присутствует внутри литерала, он должен быть экранирован предшествующим символом U+005C (\). Он эквивалентен числовому литералу беззнакового 8-битного целого числа u8.

Байтовые строковые литералы

Несырой байтовый строковый литерал — это последовательность символов ASCII и экранирований, перед которой стоят символы U+0062 (b) и U+0022 (двойная кавычка), и после которой следует символ U+0022. Если символ U+0022 присутствует внутри литерала, он должен быть экранирован предшествующим символом U+005C (\). Альтернативно, байтовый строковый литерал может быть сырым байтовым строковым литералом, определённым ниже.

Разрывы строк, представленные символом U+000A (LF), допускаются в байтовых строковых литералах. Символ U+000D (CR) не может появляться в байтовом строковом литерале. Когда неэкранированный символ U+005C (\) встречается непосредственно перед разрывом строки, разрыв строки не появляется в строке, представленной токеном. Подробнее см. Экранирования продолжения строки.

Некоторые дополнительные экранирования доступны либо в байтовых, либо в несырых байтовых строковых литералах. Экранирование начинается с U+005C (\) и продолжается одной из следующих форм:

• Байтовое экранирование начинается с U+0078 (x) и следует ровно две шестнадцатеричные цифры. Оно обозначает байт, равный предоставленному шестнадцатеричному значению.

• Экранирование пробельного символа — это один из символов U+006E (n), U+0072 (r) или U+0074 (t), обозначающих байтовые значения 0x0A (ASCII LF), 0x0D (ASCII CR) или 0x09 (ASCII HT) соответственно.

• Нулевое экранирование — это символ U+0030 (0) и обозначает байтовое значение 0x00 (ASCII NUL).

• Экранирование обратной косой черты — это символ U+005C (\), который должен быть экранирован, чтобы обозначить своё ASCII-представление 0x5C.

Сырые байтовые строковые литералы

Сырые байтовые строковые литералы не обрабатывают никакие экранирования. Они начинаются с символа U+0062 (b), за которым следует U+0072 (r), за которым следует менее 256 символов U+0023 (#) и символ U+0022 (двойная кавычка).

Тело сырой строки может содержать любую последовательность символов ASCII, кроме U+000D (CR). Оно завершается только другим символом U+0022 (двойная кавычка), за которым следует то же количество символов U+0023 (#), которое предшествовало открывающему символу U+0022 (двойная кавычка). Сырой байтовый строковый литерал не может содержать никаких не-ASCII байтов.

Все символы, содержащиеся в теле сырой строки, представляют своё ASCII-представление, символы U+0022 (двойная кавычка) (кроме случая, когда за ними следует по крайней мере столько же символов U+0023 (#), сколько было использовано для начала сырого строкового литерала) или U+005C (\) не имеют никакого специального значения.

Примеры байтовых строковых литералов:

#![allow(unused)]
fn main() {
b"foo"; br"foo";                     // foo
b"\"foo\""; br#""foo""#;             // "foo"

b"foo #\"# bar";
br##"foo #"# bar"##;                 // foo #"# bar

b"\x52"; b"R"; br"R";                // R
b"\\x52"; br"\x52";                  // \x52
}

C-строковые и сырые C-строковые литералы

C-строковые литералы

C-строковый литерал — это последовательность символов Unicode и экранирований, перед которой стоят символы U+0063 (c) и U+0022 (двойная кавычка), и после которой следует символ U+0022. Если символ U+0022 присутствует внутри литерала, он должен быть экранирован предшествующим символом U+005C (\). Альтернативно, C-строковый литерал может быть сырым C-строковым литералом, определённым ниже.

C-строки неявно завершаются байтом 0x00, поэтому C-строковый литерал c"" эквивалентен ручному созданию &CStr из байтового строкового литерала b"\x00". Кроме неявного терминатора, байт 0x00 не допускается внутри C-строки.

Разрывы строк, представленные символом U+000A (LF), допускаются в C-строковых литералах. Символ U+000D (CR) не может появляться в C-строковом литерале. Когда неэкранированный символ U+005C (\) встречается непосредственно перед разрывом строки, разрыв строки не появляется в строке, представленной токеном. Подробнее см. Экранирования продолжения строки.

Некоторые дополнительные экранирования доступны в несырых C-строковых литералах. Экранирование начинается с U+005C (\) и продолжается одной из следующих форм:

• Байтовое экранирование начинается с U+0078 (x) и следует ровно две шестнадцатеричные цифры. Оно обозначает байт, равный предоставленному шестнадцатеричному значению.

• 24-битное экранирование кодовой точки начинается с U+0075 (u) и следует до шести шестнадцатеричных цифр, окружённых фигурными скобками U+007B ({) и U+007D (}). Оно обозначает кодовую точку Unicode, равную предоставленному шестнадцатеричному значению, закодированную как UTF-8.

• Экранирование пробельного символа — это один из символов U+006E (n), U+0072 (r) или U+0074 (t), обозначающих байтовые значения 0x0A (ASCII LF), 0x0D (ASCII CR) или 0x09 (ASCII HT) соответственно.

• Экранирование обратной косой черты — это символ U+005C (\), который должен быть экранирован, чтобы обозначить своё ASCII-представление 0x5C.

C-строка представляет байты без определённой кодировки, но C-строковый литерал может содержать символы Unicode выше U+007F. Такие символы будут заменены байтами UTF-8 представления этого символа.

Следующие C-строковые литералы эквивалентны:

#![allow(unused)]
fn main() {
c"æ";        // LATIN SMALL LETTER AE (U+00E6)
c"\u{00E6}";
c"\xC3\xA6";
}

Сырые C-строковые литералы

Сырые C-строковые литералы не обрабатывают никакие экранирования. Они начинаются с символа U+0063 (c), за которым следует U+0072 (r), за которым следует менее 256 символов U+0023 (#) и символ U+0022 (двойная кавычка).

Тело сырой C-строки может содержать любую последовательность символов Unicode, кроме U+0000 (NUL) и U+000D (CR). Оно завершается только другим символом U+0022 (двойная кавычка), за которым следует то же количество символов U+0023 (#), которое предшествовало открывающему символу U+0022 (двойная кавычка).

Все символы, содержащиеся в теле сырой C-строки, представляют самих себя в кодировке UTF-8. Символы U+0022 (двойная кавычка) (кроме случая, когда за ними следует по крайней мере столько же символов U+0023 (#), сколько было использовано для начала сырого C-строкового литерала) или U+005C (\) не имеют никакого специального значения.

Примеры C-строковых и сырых C-строковых литералов

#![allow(unused)]
fn main() {
c"foo"; cr"foo";                     // foo
c"\"foo\""; cr#""foo""#;             // "foo"

c"foo #\"# bar";
cr##"foo #"# bar"##;                 // foo #"# bar

c"\x52"; c"R"; cr"R";                // R
c"\\x52"; cr"\x52";                  // \x52
}

Целочисленные литералы

Целочисленный литерал имеет одну из четырёх форм:

• Десятичный литерал начинается с десятичной цифры и продолжается любым сочетанием десятичных цифр и знаков подчёркивания.

• Шестнадцатеричный литерал начинается с последовательности символов U+0030 U+0078 (0x) и продолжается любым сочетанием (с как минимум одной цифрой) шестнадцатеричных цифр и знаков подчёркивания.

• Восьмеричный литерал начинается с последовательности символов U+0030 U+006F (0o) и продолжается любым сочетанием (с как минимум одной цифрой) восьмеричных цифр и знаков подчёркивания.

• Двоичный литерал начинается с последовательности символов U+0030 U+0062 (0b) и продолжается любым сочетанием (с как минимум одной цифрой) двоичных цифр и знаков подчёркивания.

Как и любой литерал, целочисленный литерал может следовать (непосредственно, без пробелов) за суффиксом, как описано выше. Суффикс не может начинаться с e или E, так как это будет интерпретировано как экспонента литерала с плавающей точкой. См. Целочисленные литеральные выражения для получения информации о влиянии этих суффиксов.

Примеры целочисленных литералов, которые принимаются как литеральные выражения:

#![allow(unused)]
fn main() {
#![allow(overflowing_literals)]
123;
123i32;
123u32;
123_u32;

0xff;
0xff_u8;
0x01_f32; // целое число 7986, не число с плавающей точкой 1.0
0x01_e3;  // целое число 483, не число с плавающей точкой 1000.0

0o70;
0o70_i16;

0b1111_1111_1001_0000;
0b1111_1111_1001_0000i64;
0b________1;

0usize;

// Эти числа слишком велики для своего типа, но принимаются как литеральные выражения.
128_i8;
256_u8;

// Это целочисленный литерал, принимаемый как литеральное выражение с плавающей точкой.
5f32;
}

Обратите внимание, что -1i8, например, анализируется как два токена: - followed by 1i8.

Примеры целочисленных литералов, которые не принимаются как литеральные выражения:

#![allow(unused)]
fn main() {
#[cfg(false)] {
0invalidSuffix;
123AFB43;
0b010a;
0xAB_CD_EF_GH;
0b1111_f32;
}
}

Индекс кортежа

Индекс кортежа используется для обращения к полям кортежей, кортежных структур и кортежных вариантов перечислений.

Индексы кортежа сравниваются с токеном литерала напрямую. Индексы кортежа начинаются с 0, и каждый последующий индекс увеличивает значение на 1 как десятичное значение. Таким образом, совпадут только десятичные значения, и значение не должно иметь никаких лишних префиксных символов 0.

Индексы кортежа не могут включать никакие суффиксы (такие как usize).

#![allow(unused)]
fn main() {
let example = ("dog", "cat", "horse");
let dog = example.0;
let cat = example.1;
// Следующие примеры недопустимы.
let cat = example.01;  // ОШИБКА: нет поля с именем `01`
let horse = example.0b10;  // ОШИБКА: нет поля с именем `0b10`
let unicorn = example.0usize; // ОШИБКА: суффиксы в индексе кортежа недопустимы
let underscore = example.0_0; // ОШИБКА: нет поля `0_0` в типе `(&str, &str, &str)`
}

Литералы с плавающей точкой

Литерал с плавающей точкой имеет одну из двух форм:

• Десятичный литерал, за которым следует символ точки U+002E (.). За этим может следовать другой десятичный литерал, с необязательной экспонентой.
• Одиночный десятичный литерал, за которым следует экспонента.

Как и целочисленные литералы, литерал с плавающей точкой может следовать за суффиксом, при условии, что часть до суффикса не заканчивается на U+002E (.). Суффикс не может начинаться с e или E, если литерал не включает экспоненту. См. Выражения литералов с плавающей точкой для получения информации о влиянии этих суффиксов.

Примеры литералов с плавающей точкой, которые принимаются как литеральные выражения:

#![allow(unused)]
fn main() {
123.0f64;
0.1f64;
0.1f32;
12E+99_f64;
let x: f64 = 2.;
}

Последний пример отличается, потому что невозможно использовать синтаксис суффикса с литералом с плавающей точкой, заканчивающимся на точку. 2.f64 попытается вызвать метод с именем f64 на 2.

Обратите внимание, что -1.0, например, анализируется как два токена: - followed by 1.0.

Примеры литералов с плавающей точкой, которые не принимаются как литеральные выражения:

#![allow(unused)]
fn main() {
#[cfg(false)] {
2.0f80;
2e5f80;
2e5e6;
2.0e5e6;
1.3e10u64;
}
}

Зарезервированные формы, похожие на числовые литералы

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

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

• Несуффиксированный двоичный, восьмеричный или шестнадцатеричный литерал, за которым, без пробелов, следует символ точки (с теми же ограничениями на то, что следует за точкой, как для литералов с плавающей точкой).

• Несуффиксированный двоичный или восьмеричный литерал, за которым, без пробелов, следует символ e или E.

• Ввод, который начинается с одного из префиксов системы счисления, но не является допустимым двоичным, восьмеричным или шестнадцатеричным литералом (потому что не содержит цифр).

• Ввод, который имеет форму литерала с плавающей точкой без цифр в экспоненте.

Примеры зарезервированных форм:

#![allow(unused)]
fn main() {
0b0102;  // это не `0b010` followed by `2`
0o1279;  // это не `0o127` followed by `9`
0x80.0;  // это не `0x80` followed by `.` и `0`
0b101e;  // это не суффиксированный литерал, или `0b101` followed by `e`
0b;      // это не целочисленный литерал, или `0` followed by `b`
0b_;     // это не целочисленный литерал, или `0` followed by `b_`
2e;      // это не литерал с плавающей точкой, или `2` followed by `e`
2.0e;    // это не литерал с плавающей точкой, или `2.0` followed by `e`
2em;     // это не суффиксированный литерал, или `2` followed by `em`
2.0em;   // это не суффиксированный литерал, или `2.0` followed by `em`
}

Времена жизни и метки циклов

Параметры времени жизни и метки циклов используют токены LIFETIME_OR_LABEL. Любой токен LIFETIME_TOKEN будет принят лексером и, например, может быть использован в макросах.

Сырое время жизни похоже на обычное время жизни, но его идентификатор имеет префикс r#. (Обратите внимание, что префикс r# не включается в состав самого времени жизни.)

В отличие от обычного времени жизни, сырым временем жизни может быть любое строгое или зарезервированное ключевое слово, кроме перечисленных выше для RESERVED_RAW_LIFETIME.

Ошибкой является использование токена RESERVED_RAW_LIFETIME.

Знаки пунктуации

Токены пунктуации используются как операторы, разделители и другие части грамматики.

Разделители

Скобочные знаки пунктуации используются в различных частях грамматики. Открывающая скобка всегда должна быть парной с закрывающей скобкой. Скобки и токены внутри них называются “деревьями токенов” в macros. Три типа скобок:

Зарезервированные токены

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

Зарезервированные префиксы

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

Исходный ввод, который в противном случае лексически интерпретировался бы как несырой идентификатор (или ключевое слово), за которым непосредственно следует символ #, ' или " (без пробелов между ними), идентифицируется как зарезервированный префикс.

Обратите внимание, что сырые идентификаторы, сырые строковые литералы и сырые байтовые строковые литералы могут содержать символ #, но не интерпретируются как содержащие зарезервированный префикс.

Аналогично, префиксы r, b, br, c и cr, используемые в сырых строковых литералах, байтовых литералах, байтовых строковых литералах, сырых байтовых строковых литералах, C-строковых литералах и сырых C-строковых литералах, не интерпретируются как зарезервированные префиксы.

Исходный ввод, который в противном случае лексически интерпретировался бы как несырое время жизни (или ключевое слово), за которым непосредственно следует символ # (без пробелов между ними), идентифицируется как зарезервированный префикс времени жизни.

Зарезервированные ограничители

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

Зарезервированный ограниченный строковый литерал — это токен из одного или более U+0023 (#), за которым непосредственно следует STRING_LITERAL.

Зарезервированные решётки — это токен из двух или более U+0023 (#).

1. Количество символов # с каждой стороны одного и того же литерала должно быть одинаковым. ↩

2. Все числовые литералы допускают _ как визуальный разделитель: 1_234.0E+18f64 ↩

Макросы

Функциональность и синтаксис Rust могут быть расширены с помощью пользовательских определений, называемых макросами. Им даются имена, и они вызываются через единообразный синтаксис: some_extension!(...).

Существует два способа определения новых макросов:

• Макросы по примеру определяют новый синтаксис на более высоком, декларативном уровне.
• Процедурные макросы определяют функциональноподобные макросы, пользовательские наследования (derives) и пользовательские атрибуты с помощью функций, работающих с входными токенами.

Вызов макроса

Вызов макроса раскрывает макрос во время компиляции и заменяет вызов результатом работы макроса. Макросы могут быть вызваны в следующих ситуациях:

• Выражения и инструкции

• Шаблоны

• Типы

• Элементы, включая ассоциированные элементы

• Транскрайберы macro_rules

• Внешние блоки

При использовании в качестве элемента или инструкции используется форма MacroInvocationSemi, где точка с запятой требуется в конце, если не используются фигурные скобки. Квалификаторы видимости никогда не разрешаются перед вызовом макроса или определением macro_rules.

#![allow(unused)]
fn main() {
// Используется как выражение.
let x = vec![1,2,3];

// Используется как инструкция.
println!("Hello!");

// Используется в шаблоне.
macro_rules! pat {
    ($i:ident) => (Some($i))
}

if let pat!(x) = Some(1) {
    assert_eq!(x, 1);
}

// Используется в типе.
macro_rules! Tuple {
    { $A:ty, $B:ty } => { ($A, $B) };
}

type N2 = Tuple!(i32, i32);

// Используется как элемент.
use std::cell::RefCell;
thread_local!(static FOO: RefCell<u32> = RefCell::new(1));

// Используется как ассоциированный элемент.
macro_rules! const_maker {
    ($t:ty, $v:tt) => { const CONST: $t = $v; };
}
trait T {
    const_maker!{i32, 7}
}

// Вызовы макросов внутри макросов.
macro_rules! example {
    () => { println!("Макрос внутри макроса!") };
}
// Сначала раскрывается внешний макрос `example`, затем внутренний макрос `println`.
example!();
}

Макросы по примеру

macro_rules позволяет пользователям определять расширения синтаксиса декларативным способом. Мы называем такие расширения “макросами по примеру” или просто “макросами”.

Каждый макрос по примеру имеет имя и одно или несколько правил. Каждое правило состоит из двух частей: сопоставителя (matcher), описывающего синтаксис, который он сопоставляет, и транскрайбера (transcriber), описывающего синтаксис, который заменит успешно сопоставленный вызов. Как сопоставитель, так и транскрайбер должны быть окружены разделителями. Макросы могут раскрываться в выражения, инструкции, элементы (включая трейты, реализации и внешние элементы), типы или шаблоны.

Транскрибирование

При вызове макроса, раскрыватель макросов ищет вызовы макросов по имени и пробует каждое правило макроса по очереди. Он транскрибирует первое успешное совпадение; если это приводит к ошибке, то последующие совпадения не проверяются.

При сопоставлении не выполняется упреждающий просмотр (lookahead); если компилятор не может однозначно определить, как разбирать вызов макроса по одному токену за раз, то это ошибка. В следующем примере компилятор не заглядывает вперед после идентификатора, чтобы увидеть, является ли следующий токен ), даже если это позволило бы ему однозначно разобрать вызов:

#![allow(unused)]
fn main() {
macro_rules! ambiguity {
    ($($i:ident)* $j:ident) => { };
}

ambiguity!(error); // Ошибка: локальная неоднозначность
}

Как в сопоставителе, так и в транскрайбере, токен $ используется для вызова специального поведения механизма макросов (описано ниже в Метапеременные и Повторы). Токены, не являющиеся частью такого вызова, сопоставляются и транскрибируются буквально, за одним исключением. Исключение состоит в том, что внешние разделители для сопоставителя будут соответствовать любой паре разделителей. Таким образом, например, сопоставитель (()) будет соответствовать {()} но не {{}}. Символ $ не может быть сопоставлен или транскрибирован буквально.

Передача сопоставленного фрагмента

При передаче сопоставленного фрагмента в другой макрос по примеру, сопоставители во втором макросе увидят непрозрачное AST типа фрагмента. Второй макрос не может использовать литеральные токены для сопоставления фрагментов в сопоставителе, только спецификатор фрагмента того же типа. Типы фрагментов ident, lifetime и tt являются исключением и могут быть сопоставлены литеральными токенами. Следующий пример иллюстрирует это ограничение:

#![allow(unused)]
fn main() {
macro_rules! foo {
    ($l:expr) => { bar!($l); }
// ОШИБКА:               ^^ никакие правила не ожидают этот токен в вызове макроса
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

Следующий пример иллюстрирует, как токены могут быть непосредственно сопоставлены после сопоставления фрагмента tt:

#![allow(unused)]
fn main() {
// компилируется OK
macro_rules! foo {
    ($l:tt) => { bar!($l); }
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

Метапеременные

В сопоставителе $ имя : спецификатор-фрагмента сопоставляет фрагмент синтаксиса Rust указанного вида и связывает его с метапеременной $имя.

Допустимые спецификаторы фрагментов:

• block: Блочное выражение
• expr: Выражение
• expr_2021: Выражение кроме Выражения с подчеркиванием и Выражения-константного блока (см. macro.decl.meta.edition2024)
• ident: IDENTIFIER_OR_KEYWORD кроме _, RAW_IDENTIFIER или $crate
• item: Элемент
• lifetime: LIFETIME_TOKEN
• literal: сопоставляет -^?Литеральное выражение
• meta: Атрибут, содержимое атрибута
• pat: Шаблон (см. macro.decl.meta.edition2021)
• pat_param: PatternNoTopAlt
• path: путь в стиле TypePath
• stmt: Инструкция без завершающей точки с запятой (кроме инструкций элементов, которые требуют точку с запятой)
• tt: TokenTree (одиночный токен или токены в соответствующих разделителях (), [] или {})
• ty: Тип
• vis: возможно пустой квалификатор видимости