30 search results for 'used':
  • Items » Use declarations » Use declarations[items.use] [items.use.syntax] Syntax: UseDeclaration : use UseTree ; UseTree : ( SimplePath ? ::)? * | ( SimplePath ? ::)? { ( UseTree ( , UseTree )* ,?)? } |
  • Items » Use declarations » use PathsUses `Foo` from the value namespace. let x: Foo = ctor(123); // Uses `Foo` From the type namespace. } [items.use.path.edition2015] Edition differences : In the 2015 edition, use paths are relative
  • Items » Use declarations » use VisibilityAlso like items, a use declaration can be public, if qualified by the pub keyword. Such a use declaration serves to re-export a name. A public use declaration can therefore
  • Names » Namespaces » Use declarations[names.namespaces.without.use] A use declaration has named aliases that it imports into scope, but the use item itself does not belong to a specific namespace. Instead, it can introduce aliases into
  • Application Binary Interface » The used attributeThe used attribute can only be applied to static items . This attribute forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries)
  • Type system » Trait and lifetime bounds » Use boundsCertain bounds lists may include a use<..> bound to control which generic parameters are captured by the impl Trait abstract return type . See precise capturing for more details.
  • Introduction » How to use this bookThis book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they
  • Attributes » Debugger » Using debugger_visualizer with GDBAdd the following line to that file: add-auto-load-safe-path path/to/binary. [attributes.debugger.debugger_visualizer.gdb.path] These scripts are embedded using the gdb_script_file key, which is a path relative to the crate source file. #![debugger_visualizer(gdb_script_file =
  • Items » Static items » Using Statics or ConstsIt can be confusing whether or not you should use a constant item or a static item. Constants should, in general, be preferred over statics unless one of the following
  • Attributes » Debugger » Using debugger_visualizer with Natvisuses declarative rules to customize the display of types. For detailed information on the Natvis format, refer to Microsoft's Natvis documentation . [attributes.debugger.debugger_visualizer.natvis.msvc] This attribute only supports embedding Natvis files on
  • Items » Generic parameters » Const genericsprintln!("{}", N * 2); } // Used as a field of a struct. struct Foo<const N: usize>([i32; N]); impl<const N: usize> Foo<N> { // Used as an associated constant. const CONST: usize
  • Linkage » Linkageused (e.g. --gc-sections or -dead_strip for macOS). [link.cdylib] --crate-type=cdylib, #![crate_type = "cdylib"] - A dynamic system library will be produced. This is used when compiling a dynamic library to be
  • Attributes » Diagnostics » The must_use attributeusing the MetaNameValueStr syntax such as #[must_use = "example message"]. The message will be given alongside the warning. [attributes.diagnostics.must_use.type] When used on user-defined composite types, if the expression of an
  • Inline assembly » OptionsThis is primarily useful when including raw assembly code from an external file using include_str!. [asm.options.checks] The compiler performs some additional checks on options: [asm.options.checks.mutually-exclusive] The nomem and readonly options
  • Macros » Macro Invocationusing curly braces. Visibility qualifiers are never allowed before a macro invocation or macro_rules definition. // Used as an expression. let x = vec![1,2,3]; // Used as a statement. println!("Hello!"); // Used
  • Items » Use declarations » RestrictionsThe following are restrictions for valid use declarations: [items.use.restrictions.crate] use crate; must use as to define the name to which to bind the crate root. [items.use.restrictions.self] use {self}; is an
  • Macros » Macros By Example » Hygieneusers of a macro-exporting crate. Crates written for earlier versions of Rust that use helper macros need to be modified to use $crate or local_inner_macros to work well with path-based
  • Type system » Trait and lifetime bounds » Trait and lifetime boundsUseBound : use UseBoundGenericArgs UseBoundGenericArgs : < > | < ( UseBoundGenericArg ,)* UseBoundGenericArg ,? > UseBoundGenericArg : Lifetime | IDENTIFIER | Self [bound.intro] Trait and lifetime bounds provide a
  • Items » Use declarations » Glob importsused as the first or intermediate segments. [items.use.glob.self-import] * cannot be used to import a module's contents into itself (such as use self::*;). [items.use.glob.edition2015] Edition differences : In the 2015
  • Items » Use declarations » Ambiguitiesused. For example: mod foo { pub struct Qux; } mod bar { pub struct Qux; } use foo::*; use bar::*; //~ OK, no name conflict. fn main() { // This would be
  • Inline assembly » Register namesLLVM will allocate one of these reserved registers for reg operands. Assembly code making use of reserved registers should be careful since reg operands may use the same registers. [asm.template-modifiers]
  • Linkage » Prohibited linkage and unwindingOtherwise, unwinding can cause undefined behavior. Note If you are using rustc to link, these rules are enforced automatically. If you are not using rustc to link, you must take
  • Names » Visibility and privacy » Visibility and Privacyused across modules, Rust checks each use of an item to see whether it should be allowed or not. This is where privacy warnings are generated, or otherwise "you used
  • Introduction » ConventionsThese conventions are documented here. Statements that define a term contain that term in italics . Whenever that term is used outside of that chapter, it is usually a link to
  • Inline assembly » Register operandseax vs rax) as equivalent to the base register. [asm.register-operands.error-two-operands] It is a compile-time error to use the same explicit register for two input operands or two output operands. #
  • Items » Enumerations » Enumerationsuse declarations . [items.enum.constructor-namespace] Each variant defines its type in the type namespace , though that type cannot be used as a type specifier. Tuple-like and unit-like variants also define a
  • Items » Implementations » Generic Implementations*/ } // Usage of T inside the implementation does not constrain the impl. impl<T> Struct { fn uses_t(t: &T) { /* ... */ } } // T is used as an
  • Lexical structure » Keywords » Weak keywordsused to create custom macros . [lex.keywords.weak.union] union is used to declare a union and is only a keyword when used in a union declaration. [lex.keywords.weak.lifetime-static] 'static is used for the
  • Names » Names[names.path] Paths are used to refer to an entity, possibly in another module or type. [names.lifetime] Lifetimes and loop labels use a dedicated syntax using a leading quote. [names.namespace] Names
  • Panic » Unwinding across FFI boundariesusing an appropriate ABI declaration . While useful in certain cases, this creates unique opportunities for undefined behavior, especially when multiple language runtimes are involved. [panic.unwind.ffi.undefined] Unwinding with the wrong ABI

Introduction

This book is the primary reference for the Rust programming language. It provides three kinds of material:

  • Chapters that informally describe each language construct and their use.
  • Chapters that informally describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities.
  • Appendix chapters providing rationale and references to languages that influenced the design.

Warning

This book is incomplete. Documenting everything takes a while. See the GitHub issues for what is not documented in this book.

Rust releases

Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (rustc, cargo, etc.) and documentation (Standard library, this book, etc.) are released with the language release.

The latest release of this book, matching the latest Rust version, can always be found at https://doc.rust-lang.org/reference/. Prior versions can be found by adding the Rust version before the “reference” directory. For example, the Reference for Rust 1.49.0 is located at https://doc.rust-lang.org/1.49.0/reference/.

What The Reference is not

This book does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate book is available to help acquire such background familiarity.

This book also does not serve as a reference to the standard library included in the language distribution. Those libraries are documented separately by extracting documentation attributes from their source code. Many of the features that one might expect to be language features are library features in Rust, so what you’re looking for may be there, not here.

Similarly, this book does not usually document the specifics of rustc as a tool or of Cargo. rustc has its own book. Cargo has a book that contains a reference. There are a few pages such as linkage that still describe how rustc works.

This book also only serves as a reference to what is available in stable Rust. For unstable features being worked on, see the Unstable Book.

Rust compilers, including rustc, will perform optimizations. The reference does not specify what optimizations are allowed or disallowed. Instead, think of the compiled program as a black box. You can only probe by running it, feeding it input and observing its output. Everything that happens that way must conform to what the reference says.

Finally, this book is not normative. It may include details that are specific to rustc itself, and should not be taken as a specification for the Rust language. We intend to produce such a book someday, and until then, the reference is the closest thing we have to one.

How to use this book

This book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss.

There are two main ways to read this document.

The first is to answer a specific question. If you know which chapter answers that question, you can jump to that chapter in the table of contents. Otherwise, you can press s or click the magnifying glass on the top bar to search for keywords related to your question. For example, say you wanted to know when a temporary value created in a let statement is dropped. If you didn’t already know that the lifetime of temporaries is defined in the expressions chapter, you could search “temporary let” and the first search result will take you to that section.

The second is to generally improve your knowledge of a facet of the language. In that case, just browse the table of contents until you see something you want to know more about, and just start reading. If a link looks interesting, click it, and read about that section.

That said, there is no wrong way to read this book. Read it however you feel helps you best.

Conventions

Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here.

  • Statements that define a term contain that term in italics. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition.

    An example term is an example of a term being defined.

  • Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words “Edition differences:” in bold.

    Edition differences: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition.

  • Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks.

    Note

    This is an example note.

  • Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box.

    Warning

    This is an example warning.

  • Code snippets inline in the text are inside <code> tags.

    Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner.

    // This is a hidden line.
fn main() {
    println!("This is a code example");
}

    All examples are written for the latest edition unless otherwise stated.

  • The grammar and lexical structure is in blockquotes with either “Lexer” or “Syntax” in bold superscript as the first line.

    Syntax
    ExampleGrammar:
          ~ Expression
       | box Expression

    See Notation for more detail.

  • Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to a specific rule in the language. The rule identifier uses periods to separate sections from most general to most specific (destructors.scope.nesting.function-body for example). On narrow screens, the rule name will collapse to display [*].

    The rule name can be clicked to link to that rule.

    Warning

    The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases.

  • Rules that have associated tests will include a Tests link below them (no narrow screens, the link is [T]). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see input.encoding.utf8.

    Linking rules to tests is an ongoing effort. See the Test summary chapter for an overview.

Contributing

We welcome contributions of all kinds.

You can contribute to this book by opening an issue or sending a pull request to the Rust Reference repository. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to file an issue or ask about it in the t-lang/doc stream on Zulip. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. We also want the reference to be as normative as possible, so if you see anything that is wrong or is non-normative but not specifically called out, please also file an issue.