# The Unstable Book

Welcome to the Unstable Book! This book consists of a number of chapters, each one organized by a "feature flag." That is, when using an unstable feature of Rust, you must use a flag, like this:

    #![feature(box_syntax)]

    fn main() {
        let five = box 5;
    }

The `box_syntax` feature has a chapter describing how to use it.

Because this documentation relates to unstable features, we make no guarantees that what is contained here is accurate or up to date. It's developed on a best-effort basis. Each page will have a link to its tracking issue with the latest developments; you might want to check those as well.

# Compiler flags

# `emit-stack-sizes`

The tracking issue for this feature is: #54192

The rustc flag `-Z emit-stack-sizes` makes LLVM emit stack size metadata.

> NOTE: This LLVM feature only supports the ELF object format as of LLVM 8.0. Using this flag with targets that use other object formats (e.g. macOS and Windows) will result in it being ignored.

Consider this crate:

    #![crate_type = "lib"]

    use std::ptr;

    pub fn foo() {
        // this function doesn't use the stack
    }

    pub fn bar() {
        let xs = [0u32; 2];

        // force LLVM to allocate `xs` on the stack
        unsafe { ptr::read_volatile(&xs.as_ptr()); }
    }

Using the `-Z emit-stack-sizes` flag produces extra linker sections in the output object file.

    $ rustc -C opt-level=3 --emit=obj foo.rs

    $ size -A foo.o
    foo.o  :
    section                                 size   addr
    .text                                      0      0
    .text._ZN3foo3foo17he211d7b4a3a0c16eE      1      0
    .text._ZN3foo3bar17h1acb594305f70c2eE     22      0
    .note.GNU-stack                            0      0
    .eh_frame                                 72      0
    Total                                     95

    $ rustc -C opt-level=3 --emit=obj -Z emit-stack-sizes foo.rs

    $ size -A foo.o
    foo.o  :
    section                                 size   addr
    .text                                      0      0
    .text._ZN3foo3foo17he211d7b4a3a0c16eE      1      0
    .stack_sizes                               9      0
    .text._ZN3foo3bar17h1acb594305f70c2eE     22      0
    .stack_sizes                               9      0
    .note.GNU-stack                            0      0
    .eh_frame                                 72      0
    Total                                    113

As of LLVM 7.0 the data will be written into a section named `.stack_sizes` and the format is "an array of pairs of function symbol values (pointer size) and stack sizes (unsigned LEB128)".

    $ objdump -d foo.o

    foo.o:     file format elf64-x86-64

    Disassembly of section .text._ZN3foo3foo17he211d7b4a3a0c16eE:

    0000000000000000 <_ZN3foo3foo17he211d7b4a3a0c16eE>:
       0:   c3                      retq

    Disassembly of section .text._ZN3foo3bar17h1acb594305f70c2eE:

    0000000000000000 <_ZN3foo3bar17h1acb594305f70c2eE>:
       0:   48 83 ec 10             sub    $0x10,%rsp
       4:   48 8d 44 24 08          lea    0x8(%rsp),%rax
       9:   48 89 04 24             mov    %rax,(%rsp)
       d:   48 8b 04 24             mov    (%rsp),%rax
      11:   48 83 c4 10             add    $0x10,%rsp
      15:   c3                      retq

    $ objdump -s -j .stack_sizes foo.o

    foo.o:     file format elf64-x86-64

    Contents of section .stack_sizes:
     0000 00000000 00000000 00                 .........
    Contents of section .stack_sizes:
     0000 00000000 00000000 10                 .........

It's important to note that linkers will discard this linker section by default. To preserve the section you can use a linker script like the one shown below.

    /* file: keep-stack-sizes.x */
    SECTIONS
    {
      /* `INFO` makes the section not allocatable so it won't be loaded into memory */
      .stack_sizes (INFO) :
      {
        KEEP(*(.stack_sizes));
      }
    }

The linker script must be passed to the linker using a rustc flag like `-C link-arg`.

    // file: src/main.rs
    use std::ptr;

    #[inline(never)]
    fn main() {
        let xs = [0u32; 2];

        // force LLVM to allocate `xs` on the stack
        unsafe { ptr::read_volatile(&xs.as_ptr()); }
    }

    $ RUSTFLAGS="-Z emit-stack-sizes" cargo build --release

    $ size -A target/release/hello | grep stack_sizes || echo section was not found
    section was not found

    $ RUSTFLAGS="-Z emit-stack-sizes" cargo rustc --release -- \
        -C link-arg=-Wl,-Tkeep-stack-sizes.x \
        -C link-arg=-N

    $ size -A target/release/hello | grep stack_sizes
    .stack_sizes                               90   176272

    $ # non-allocatable section (flags don't contain the "A" (alloc) flag)
    $ readelf -S target/release/hello
    Section Headers:
      [Nr]   Name              Type             Address           Offset
           Size              EntSize            Flags  Link  Info  Align
    (..)
      [1031] .stack_sizes      PROGBITS         000000000002b090  0002b0f0
           000000000000005a  0000000000000000   L       5     0     1

    $ objdump -s -j .stack_sizes target/release/hello

    target/release/hello:     file format elf64-x86-64

    Contents of section .stack_sizes:
     2b090 c0040000 00000000 08f00400 00000000  ................
     2b0a0 00080005 00000000 00000810 05000000  ................
     2b0b0 00000000 20050000 00000000 10400500  .... ........@..
     2b0c0 00000000 00087005 00000000 00000080  ......p.........
     2b0d0 05000000 00000000 90050000 00000000  ................
     2b0e0 00a00500 00000000 0000               ..........

> Author note: I'm not entirely sure why, in this case, `-N` is required in addition to `-Tkeep-stack-sizes.x`. For example, it's not required when producing statically linked files for the ARM Cortex-M architecture.

# `profile`

The tracking issue for this feature is: #42524.

This feature allows the generation of code coverage reports.

Set the `-Zprofile` compiler flag in order to enable gcov profiling.

For example:

    cargo new testgcov --bin
    cd testgcov
    export RUSTFLAGS="-Zprofile"
    cargo build
    cargo run

Once you've built and run your program, files with the `gcno` (after build) and `gcda` (after execution) extensions will be created. You can parse them with llvm-cov gcov or grcov.

# Language features

# `aarch64_target_feature`

The tracking issue for this feature is: #44839

# `abi_amdgpu_kernel`

The tracking issue for this feature is: #51575

# `abi_msp430_interrupt`

The tracking issue for this feature is: #38487

In the MSP430 architecture, interrupt handlers have a special calling convention. You can use the `"msp430-interrupt"` ABI to make the compiler apply the right calling convention to the interrupt handlers you define.

    #![feature(abi_msp430_interrupt)]
    #![no_std]

    // Place the interrupt handler at the appropriate memory address
    // (Alternatively, you can use `#[used]` and remove `pub` and `#[no_mangle]`)
    #[link_section = "__interrupt_vector_10"]
    #[no_mangle]
    pub static TIM0_VECTOR: extern "msp430-interrupt" fn() = tim0;

    // The interrupt handler
    extern "msp430-interrupt" fn tim0() {
        // ..
    }

    $ msp430-elf-objdump -CD ./target/msp430/release/app
    Disassembly of section __interrupt_vector_10:

    0000fff2 <TIM0_VECTOR>:
        fff2:       00 c0           interrupt service routine at 0xc000

    Disassembly of section .text:

    0000c000 <int::tim0>:
        c000:       00 13           reti

# `abi_ptx`

The tracking issue for this feature is: #38788

When emitting PTX code, all vanilla Rust functions (`fn`) get translated to "device" functions. These functions are not callable from the host via the CUDA API so a crate with only device functions is not too useful!

OTOH, "global" functions can be called by the host; you can think of them as the real public API of your crate. To produce a global function use the `"ptx-kernel"` ABI.

    #![feature(abi_ptx)]
    #![no_std]

    pub unsafe extern "ptx-kernel" fn global_function() {
        device_function();
    }

    pub fn device_function() {
        // ..
    }

    $ xargo rustc --target nvptx64-nvidia-cuda --release -- --emit=asm

    $ cat $(find -name '*.s')
    //
    // Generated by LLVM NVPTX Back-End
    //

    .version 3.2
    .target sm_20
    .address_size 64

            // .globl       _ZN6kernel15global_function17h46111ebe6516b382E

    .visible .entry _ZN6kernel15global_function17h46111ebe6516b382E()
    {

            ret;
    }

            // .globl       _ZN6kernel15device_function17hd6a0e4993bbf3f78E
    .visible .func _ZN6kernel15device_function17hd6a0e4993bbf3f78E()
    {

            ret;
    }

# `abi_thiscall`

The tracking issue for this feature is: #42202

The MSVC ABI on x86 Windows uses the `thiscall` calling convention for C++ instance methods by default; it is identical to the usual (C) calling convention on x86 Windows except that the first parameter of the method, the `this` pointer, is passed in the ECX register.

# `abi_unadjusted`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `abi_vectorcall`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `abi_x86_interrupt`

The tracking issue for this feature is: #40180

# `adx_target_feature`

The tracking issue for this feature is: #44839

# `alloc_error_handler`

The tracking issue for this feature is: #51540

# `allocator_internals`

This feature does not have a tracking issue, it is an unstable implementation detail of the `global_allocator` feature not intended for use outside the compiler.

# `allow_fail`

The tracking issue for this feature is: #46488

# `allow_internal_unsafe`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `allow_internal_unstable`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `arbitrary_self_types`

The tracking issue for this feature is: #44874

# `arm_target_feature`

The tracking issue for this feature is: #44839

# `asm`

The tracking issue for this feature is: #29722

For extremely low-level manipulations and performance reasons, one might wish to control the CPU directly. Rust supports using inline assembly to do this via the `asm!` macro.

    asm!(assembly template
       : output operands
       : input operands
       : clobbers
       : options
       );

Any use of `asm` is feature gated (requires `#![feature(asm)]` on the crate to allow) and of course requires an `unsafe` block.

> Note: the examples here are given in x86/x86-64 assembly, but all platforms are supported.

## Assembly template

The `assembly template` is the only required parameter and must be a literal string (i.e. `""`)

    #![feature(asm)]

    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    fn foo() {
        unsafe {
            asm!("NOP");
        }
    }

    // Other platforms:
    #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    fn foo() { /* ... */ }

    fn main() {
        // ...
        foo();
        // ...
    }

(The `feature(asm)` and `#[cfg]`s are omitted from now on.)

Output operands, input operands, clobbers and options are all optional but you must add the right number of `:` if you skip them:

    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    # fn main() { unsafe {
    asm!("xor %eax, %eax"
        :
        :
        : "eax"
       );
    # } }
    # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    # fn main() {}

Whitespace also doesn't matter:

    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    # fn main() { unsafe {
    asm!("xor %eax, %eax" ::: "eax");
    # } }
    # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    # fn main() {}

## Operands

Input and output operands follow the same format: `: "constraints1"(expr1), "constraints2"(expr2), ..."`. Output operand expressions must be mutable lvalues, or not yet assigned:

    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    fn add(a: i32, b: i32) -> i32 {
        let c: i32;
        unsafe {
            asm!("add $2, $0"
                 : "=r"(c)
                 : "0"(a), "r"(b)
                 );
        }
        c
    }
    # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    # fn add(a: i32, b: i32) -> i32 { a + b }

    fn main() {
        assert_eq!(add(3, 14159), 14162)
    }

If you would like to use real operands in this position, however, you are required to put curly braces `{}` around the register that you want, and you are required to put the specific size of the operand. This is useful for very low level programming, where which register you use is important:

    # #![allow(unused_variables)]
    #fn main() {
    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    # unsafe fn read_byte_in(port: u16) -> u8 {
    let result: u8;
    asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port));
    result
    # }
    #}

## Clobbers

Some instructions modify registers which might otherwise have held different values so we use the clobbers list to indicate to the compiler not to assume any values loaded into those registers will stay valid.

    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    # fn main() { unsafe {
    // Put the value 0x200 in eax:
    asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax");
    # } }
    # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    # fn main() {}

Input and output registers need not be listed since that information is already communicated by the given constraints. Otherwise, any other registers used either implicitly or explicitly should be listed.

If the assembly changes the condition code register `cc` should be specified as one of the clobbers. Similarly, if the assembly modifies memory, `memory` should also be specified.

## Options

The last section, `options` is specific to Rust. The format is comma separated literal strings (i.e. `:"foo", "bar", "baz"`). It's used to specify some extra info about the inline assembly:

Current valid options are:

1. volatile - specifying this is analogous to `__asm__ __volatile__ (...)` in gcc/clang.
2. alignstack - certain instructions expect the stack to be aligned a certain way (i.e. SSE) and specifying this indicates to the compiler to insert its usual stack alignment code
3. intel - use intel syntax instead of the default AT&T.

    # #![feature(asm)]
    # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    # fn main() {
    let result: i32;
    unsafe {
       asm!("mov eax, 2" : "={eax}"(result) : : : "intel")
    }
    println!("eax is currently {}", result);
    # }
    # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
    # fn main() {}

## More Information

The current implementation of the `asm!` macro is a direct binding to LLVM's inline assembler expressions, so be sure to check out their documentation as well for more information about clobbers, constraints, etc.

If you need more power and don't mind losing some of the niceties of `asm!`, check out global_asm.

# `associated_type_defaults`

The tracking issue for this feature is: #29661

# `async_await`

The tracking issue for this feature is: #50547

# `avx512_target_feature`

The tracking issue for this feature is: #44839

# `bind_by_move_pattern_guards`

The tracking issue for this feature is: #15287

# `box_patterns`

The tracking issue for this feature is: #29641

See also `box_syntax`

Box patterns let you match on `Box<T>`s:

    #![feature(box_patterns)]

    fn main() {
        let b = Some(Box::new(5));
        match b {
            Some(box n) if n < 0 => {
                println!("Box contains negative number {}", n);
            },
            Some(box n) if n >= 0 => {
                println!("Box contains non-negative number {}", n);
            },
            None => {
                println!("No box");
            },
            _ => unreachable!()
        }
    }

# `box_syntax`

The tracking issue for this feature is: #49733

See also `box_patterns`

Currently the only stable way to create a `Box` is via the `Box::new` method. Also it is not possible in stable Rust to destructure a `Box` in a match pattern. The unstable `box` keyword can be used to create a `Box`. An example usage would be:

    #![feature(box_syntax)]

    fn main() {
        let b = box 5;
    }

# `cfg_target_has_atomic`

The tracking issue for this feature is: #32976

# `cfg_target_thread_local`

The tracking issue for this feature is: #29594

# `cmpxchg16b_target_feature`

The tracking issue for this feature is: #44839

# `compiler_builtins`

This feature is internal to the Rust compiler and is not intended for general use.

# `concat_idents`

The tracking issue for this feature is: #29599

The `concat_idents` feature adds a macro for concatenating multiple identifiers into one identifier.

## Examples

    #![feature(concat_idents)]

    fn main() {
        fn foobar() -> u32 { 23 }
        let f = concat_idents!(foo, bar);
        assert_eq!(f(), 23);
    }

# `const_compare_raw_pointers`

The tracking issue for this feature is: #53020

# `const_fn`

The tracking issue for this feature is: #57563

The `const_fn` feature allows marking free functions and inherent methods as `const`, enabling them to be called in constants contexts, with constant arguments.

## Examples

    #![feature(const_fn)]

    const fn double(x: i32) -> i32 {
        x * 2
    }

    const FIVE: i32 = 5;
    const TEN: i32 = double(FIVE);

    fn main() {
        assert_eq!(5, FIVE);
        assert_eq!(10, TEN);
    }

# `const_fn_union`

The tracking issue for this feature is: #51909

# `const_panic`

The tracking issue for this feature is: #51999

# `const_raw_ptr_deref`

The tracking issue for this feature is: #51911

# `const_raw_ptr_to_usize_cast`

The tracking issue for this feature is: #51910

# `const_transmute`

The tracking issue for this feature is: #53605

# `crate_visibility_modifier`

The tracking issue for this feature is: #45388

The `crate_visibility_modifier` feature allows the `crate` keyword to be used as a visibility modifier synonymous to `pub(crate)`, indicating that a type (function, &c.) is to be visible to the entire enclosing crate, but not to other crates.

    # #![allow(unused_variables)]
    #![feature(crate_visibility_modifier)]

    #fn main() {
    crate struct Foo {
        bar: usize,
    }
    #}

# `custom_attribute`

The tracking issue for this feature is: #29642

# `custom_inner_attributes`

The tracking issue for this feature is: #54726

# `custom_test_frameworks`

The tracking issue for this feature is: #50297

The `custom_test_frameworks` feature allows the use of `#[test_case]` and `#![test_runner]`. Any function, const, or static can be annotated with `#[test_case]` causing it to be aggregated (like `#[test]`) and be passed to the test runner determined by the `#![test_runner]` crate attribute.

    # #![allow(unused_variables)]
    #![feature(custom_test_frameworks)]
    #![test_runner(my_runner)]

    #fn main() {
    fn my_runner(tests: &[&i32]) {
        for t in tests {
            if **t == 0 {
                println!("PASSED");
            } else {
                println!("FAILED");
            }
        }
    }

    #[test_case]
    const WILL_PASS: i32 = 0;

    #[test_case]
    const WILL_FAIL: i32 = 4;
    #}

# `decl_macro`

The tracking issue for this feature is: #39412

# `default_type_parameter_fallback`

The tracking issue for this feature is: #27336

# `doc_alias`

The tracking issue for this feature is: #50146

You can add alias(es) to an item when using the `rustdoc` search through the `doc(alias)` attribute. Example:

    # #![allow(unused_variables)]
    #![feature(doc_alias)]

    #fn main() {
    #[doc(alias = "x")]
    #[doc(alias = "big")]
    pub struct BigX;
    #}

Then, when looking for it through the `rustdoc` search, if you enter "x" or "big", search will show the `BigX` struct first.

Note that this feature is currently hidden behind the `feature(doc_alias)` gate.

# `doc_cfg`

The tracking issue for this feature is: #43781

The `doc_cfg` feature allows an API be documented as only available in some specific platforms. This attribute has two effects:

1. In the annotated item's documentation, there will be a message saying "This is supported on (platform) only".

2. The item's doc-tests will only run on the specific platform.

In addition to allowing the use of the `#[doc(cfg)]` attribute, this feature enables the use of a special conditional compilation flag, `#[cfg(rustdoc)]`, set whenever building documentation on your crate.

This feature was introduced as part of PR #43348 to allow the platform-specific parts of the standard library be documented.

    # #![allow(unused_variables)]
    #![feature(doc_cfg)]

    #fn main() {
    #[cfg(any(windows, rustdoc))]
    #[doc(cfg(windows))]
    /// The application's icon in the notification area (a.k.a. system tray).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// extern crate my_awesome_ui_library;
    /// use my_awesome_ui_library::current_app;
    /// use my_awesome_ui_library::windows::notification;
    ///
    /// let icon = current_app().get::<notification::Icon>();
    /// icon.show();
    /// icon.show_message("Hello");
    /// ```
    pub struct Icon {
        // ...
    }
    #}

# `doc_keyword`

The tracking issue for this feature is: #51315

# `doc_masked`

The tracking issue for this feature is: #44027

The `doc_masked` feature allows a crate to exclude types from a given crate from appearing in lists of trait implementations. The specifics of the feature are as follows:

1. When rustdoc encounters an `extern crate` statement annotated with a `#[doc(masked)]` attribute, it marks the crate as being masked.

2. When listing traits a given type implements, rustdoc ensures that traits from masked crates are not emitted into the documentation.

3. When listing types that implement a given trait, rustdoc ensures that types from masked crates are not emitted into the documentation.

This feature was introduced in PR #44026 to ensure that compiler-internal and implementation-specific types and traits were not included in the standard library's documentation. Such types would introduce broken links into the documentation.

# `doc_spotlight`

The tracking issue for this feature is: #45040

The `doc_spotlight` feature allows the use of the `spotlight` parameter to the `#[doc]` attribute, to "spotlight" a specific trait on the return values of functions. Adding a `#[doc(spotlight)]` attribute to a trait definition will make rustdoc print extra information for functions which return a type that implements that trait. This attribute is applied to the `Iterator`, `io::Read`, and `io::Write` traits in the standard library.

You can do this on your own traits, like this:

    #![feature(doc_spotlight)]

    #[doc(spotlight)]
    pub trait MyTrait {}

    pub struct MyStruct;
    impl MyTrait for MyStruct {}

    /// The docs for this function will have an extra line about `MyStruct` implementing `MyTrait`,
    /// without having to write that yourself!
    pub fn my_fn() -> MyStruct { MyStruct }

This feature was originally implemented in PR #45039.

# `dropck_eyepatch`

The tracking issue for this feature is: #34761

# `dropck_parametricity`

The tracking issue for this feature is: #28498

# `exclusive_range_pattern`

The tracking issue for this feature is: #37854

# `exhaustive_patterns`

The tracking issue for this feature is: #51085

# `existential_type`

The tracking issue for this feature is: #34511

# `extern_crate_self`

The tracking issue for this feature is: #56409

# `extern_types`

The tracking issue for this feature is: #43467

# `external_doc`

The tracking issue for this feature is: #44732

The `external_doc` feature allows the use of the `include` parameter to the `#[doc]` attribute, to include external files in documentation. Use the attribute in place of, or in addition to, regular doc comments and `#[doc]` attributes, and `rustdoc` will load the given file when it renders documentation for your crate.

With the following files in the same directory:

`external-doc.md`:

    # My Awesome Type

    This is the documentation for this spectacular type.

`lib.rs`:

    #![feature(external_doc)]

    #[doc(include = "external-doc.md")]
    pub struct MyAwesomeType;

`rustdoc` will load the file `external-doc.md` and use it as the documentation for the `MyAwesomeType` struct.

When locating files, `rustdoc` will base paths in the `src/` directory, as if they were alongside the `lib.rs` for your crate. So if you want a `docs/` folder to live alongside the `src/` directory, start your paths with `../docs/` for `rustdoc` to properly find the file.

This feature was proposed in RFC #1990 and initially implemented in PR #44781.

# `format_args_nl`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `fundamental`

The tracking issue for this feature is: #29635

# `generators`

The tracking issue for this feature is: #43122

The `generators` feature gate in Rust allows you to define generator or coroutine literals. A generator is a "resumable function" that syntactically resembles a closure but compiles to much different semantics in the compiler itself. The primary feature of a generator is that it can be suspended during execution to be resumed at a later date. Generators use the `yield` keyword to "return", and then the caller can `resume` a generator to resume execution just after the `yield` keyword.

Generators are an extra-unstable feature in the compiler right now. Added in RFC 2033 they're mostly intended right now as a information/constraint gathering phase. The intent is that experimentation can happen on the nightly compiler before actual stabilization. A further RFC will be required to stabilize generators/coroutines and will likely contain at least a few small tweaks to the overall design.

A syntactical example of a generator is:

    #![feature(generators, generator_trait)]

    use std::ops::{Generator, GeneratorState};

    fn main() {
        let mut generator = || {
            yield 1;
            return "foo"
        };

        match unsafe { generator.resume() } {
            GeneratorState::Yielded(1) => {}
            _ => panic!("unexpected value from resume"),
        }
        match unsafe { generator.resume() } {
            GeneratorState::Complete("foo") => {}
            _ => panic!("unexpected value from resume"),
        }
    }

Generators are closure-like literals which can contain a `yield` statement. The `yield` statement takes an optional expression of a value to yield out of the generator. All generator literals implement the `Generator` trait in the `std::ops` module. The `Generator` trait has one main method, `resume`, which resumes execution of the generator at the previous suspension point.

An example of the control flow of generators is that the following example prints all numbers in order:

    #![feature(generators, generator_trait)]

    use std::ops::Generator;

    fn main() {
        let mut generator = || {
            println!("2");
            yield;
            println!("4");
        };

        println!("1");
        unsafe { generator.resume() };
        println!("3");
        unsafe { generator.resume() };
        println!("5");
    }

At this time the main intended use case of generators is an implementation primitive for async/await syntax, but generators will likely be extended to ergonomic implementations of iterators and other primitives in the future. Feedback on the design and usage is always appreciated!

### The `Generator` trait

The `Generator` trait in `std::ops` currently looks like:

    # #![feature(generator_trait)]
    # use std::ops::GeneratorState;

    pub trait Generator {
        type Yield;
        type Return;
        unsafe fn resume(&mut self) -> GeneratorState<Self::Yield, Self::Return>;
    }

The `Generator::Yield` type is the type of values that can be yielded with the `yield` statement. The `Generator::Return` type is the returned type of the generator. This is typically the last expression in a generator's definition or any value passed to `return` in a generator. The `resume` function is the entry point for executing the `Generator` itself.

The return value of `resume`, `GeneratorState`, looks like:

    pub enum GeneratorState<Y, R> {
        Yielded(Y),
        Complete(R),
    }

The `Yielded` variant indicates that the generator can later be resumed. This corresponds to a `yield` point in a generator. The `Complete` variant indicates that the generator is complete and cannot be resumed again. Calling `resume` after a generator has returned `Complete` will likely result in a panic of the program.

### Closure-like semantics

The closure-like syntax for generators alludes to the fact that they also have closure-like semantics. Namely:

- When created, a generator executes no code. A closure literal does not actually execute any of the closure's code on construction, and similarly a generator literal does not execute any code inside the generator when constructed.

- Generators can capture outer variables by reference or by move, and this can be tweaked with the `move` keyword at the beginning of the closure. Like closures all generators will have an implicit environment which is inferred by the compiler. Outer variables can be moved into a generator for use as the generator progresses.

- Generator literals produce a value with a unique type which implements the `std::ops::Generator` trait. This allows actual execution of the generator through the `Generator::resume` method as well as also naming it in return types and such.

- Traits like `Send` and `Sync` are automatically implemented for a `Generator` depending on the captured variables of the environment. Unlike closures, generators also depend on variables live across suspension points. This means that although the ambient environment may be `Send` or `Sync`, the generator itself may not be due to internal variables live across `yield` points being not-`Send` or not-`Sync`. Note that generators, like closures, do not implement traits like `Copy` or `Clone` automatically.

- Whenever a generator is dropped it will drop all captured environment variables.

Note that unlike closures, generators at this time cannot take any arguments. That is, generators must always look like `|| { ... }`. This restriction may be lifted at a future date, the design is ongoing!

### Generators as state machines

In the compiler, generators are currently compiled as state machines. Each `yield` expression will correspond to a different state that stores all live variables over that suspension point. Resumption of a generator will dispatch on the current state and then execute internally until a `yield` is reached, at which point all state is saved off in the generator and a value is returned.

Let's take a look at an example to see what's going on here:

    #![feature(generators, generator_trait)]

    use std::ops::Generator;

    fn main() {
        let ret = "foo";
        let mut generator = move || {
            yield 1;
            return ret
        };

        unsafe { generator.resume() };
        unsafe { generator.resume() };
    }

This generator literal will compile down to something similar to:

    #![feature(generators, generator_trait)]

    use std::ops::{Generator, GeneratorState};

    fn main() {
        let ret = "foo";
        let mut generator = {
            enum __Generator {
                Start(&'static str),
                Yield1(&'static str),
                Done,
            }

            impl Generator for __Generator {
                type Yield = i32;
                type Return = &'static str;

                unsafe fn resume(&mut self) -> GeneratorState<i32, &'static str> {
                    use std::mem;
                    match mem::replace(self, __Generator::Done) {
                        __Generator::Start(s) => {
                            *self = __Generator::Yield1(s);
                            GeneratorState::Yielded(1)
                        }

                        __Generator::Yield1(s) => {
                            *self = __Generator::Done;
                            GeneratorState::Complete(s)
                        }

                        __Generator::Done => {
                            panic!("generator resumed after completion")
                        }
                    }
                }
            }

            __Generator::Start(ret)
        };

        unsafe { generator.resume() };
        unsafe { generator.resume() };
    }

Notably here we can see that the compiler is generating a fresh type, `__Generator` in this case. This type has a number of states (represented here as an `enum`) corresponding to each of the conceptual states of the generator. At the beginning we're closing over our outer variable `foo` and then that variable is also live over the `yield` point, so it's stored in both states.

When the generator starts it'll immediately yield 1, but it saves off its state just before it does so indicating that it has reached the yield point. Upon resuming again we'll execute the `return ret` which returns the `Complete` state.

Here we can also note that the `Done` state, if resumed, panics immediately as it's invalid to resume a completed generator. It's also worth noting that this is just a rough desugaring, not a normative specification for what the compiler does.

# `generic_associated_types`

The tracking issue for this feature is: #44265

# `global_asm`

The tracking issue for this feature is: #35119

The `global_asm!` macro allows the programmer to write arbitrary assembly outside the scope of a function body, passing it through `rustc` and `llvm` to the assembler. The macro is a no-frills interface to LLVM's concept of module-level inline assembly. That is, all caveats applicable to LLVM's module-level inline assembly apply to `global_asm!`.

`global_asm!` fills a role not currently satisfied by either `asm!` or `#[naked]` functions. The programmer has all features of the assembler at their disposal. The linker will expect to resolve any symbols defined in the inline assembly, modulo any symbols marked as external. It also means syntax for directives and assembly follow the conventions of the assembler in your toolchain.

A simple usage looks like this:

    # #![feature(global_asm)]
    # you also need relevant target_arch cfgs
    global_asm!(include_str!("something_neato.s"));

And a more complicated usage looks like this:

    # #![feature(global_asm)]
    # #![cfg(any(target_arch = "x86", target_arch = "x86_64"))]

    pub mod sally {
        global_asm!(r#"
            .global foo
          foo:
            jmp baz
        "#);

        #[no_mangle]
        pub unsafe extern "C" fn baz() {}
    }

    // the symbols `foo` and `bar` are global, no matter where
    // `global_asm!` was used.
    extern "C" {
        fn foo();
        fn bar();
    }

    pub mod harry {
        global_asm!(r#"
            .global bar
          bar:
            jmp quux
        "#);

        #[no_mangle]
        pub unsafe extern "C" fn quux() {}
    }

You may use `global_asm!` multiple times, anywhere in your crate, in whatever way suits you. The effect is as if you concatenated all usages and placed the larger, single usage in the crate root.

If you don't need quite as much power and flexibility as `global_asm!` provides, and you don't mind restricting your inline assembly to `fn` bodies only, you might try the asm feature instead.

# `hexagon_target_feature`

The tracking issue for this feature is: #44839

# `impl_trait_in_bindings`

The tracking issue for this feature is: #34511

The `impl_trait_in_bindings` feature gate lets you use `impl Trait` syntax in `let`, `static`, and `const` bindings.

A simple example is:

    #![feature(impl_trait_in_bindings)]

    use std::fmt::Debug;

    fn main() {
        let a: impl Debug + Clone = 42;
        let b = a.clone();
        println!("{:?}", b); // prints `42`
    }

Note however that because the types of `a` and `b` are opaque in the above example, calling inherent methods or methods outside of the specified traits (e.g., `a.abs()` or `b.abs()`) is not allowed, and yields an error.

# `in_band_lifetimes`

The tracking issue for this feature is: #44524

# `infer_static_outlives_requirements`

The tracking issue for this feature is: #44493

The `infer_static_outlives_requirements` feature indicates that certain `'static` outlives requirements can be inferred by the compiler rather than stating them explicitly.

Note: It is an accompanying feature to `infer_outlives_requirements`, which must be enabled to infer outlives requirements.

For example, currently generic struct definitions that contain references, require where-clauses of the form T: 'static. By using this feature the outlives predicates will be inferred, although they may still be written explicitly.

    struct Foo<U> where U: 'static { // <-- currently required
        bar: Bar<U>
    }
    struct Bar<T: 'static> {
        x: T,
    }

## Examples:

    #![feature(infer_outlives_requirements)]
    #![feature(infer_static_outlives_requirements)]

    #[rustc_outlives]
    // Implicitly infer U: 'static
    struct Foo<U> {
        bar: Bar<U>
    }
    struct Bar<T: 'static> {
        x: T,
    }

# `intrinsics`

The tracking issue for this feature is: None.

Intrinsics are never intended to be stable directly, but intrinsics are often exported in some sort of stable manner. Prefer using the stable interfaces to the intrinsic directly when you can.

These are imported as if they were FFI functions, with the special `rust-intrinsic` ABI. For example, if one was in a freestanding context, but wished to be able to `transmute` between types, and perform efficient pointer arithmetic, one would import those functions via a declaration like

    #![feature(intrinsics)]
    # fn main() {}

    extern "rust-intrinsic" {
        fn transmute<T, U>(x: T) -> U;

        fn offset<T>(dst: *const T, offset: isize) -> *const T;
    }

As with any other FFI functions, these are always `unsafe` to call.

# `label_break_value`

The tracking issue for this feature is: #48594

# `lang_items`

The tracking issue for this feature is: None.

The `rustc` compiler has certain pluggable operations, that is, functionality that isn't hard-coded into the language, but is implemented in libraries, with a special marker to tell the compiler it exists. The marker is the attribute `#[lang = "..."]` and there are various different values of `...`, i.e. various different 'lang items'.

For example, `Box` pointers require two lang items, one for allocation and one for deallocation. A freestanding program that uses the `Box` sugar for dynamic allocations via `malloc` and `free`:

    #![feature(lang_items, box_syntax, start, libc, core_intrinsics)]
    #![no_std]
    use core::intrinsics;
    use core::panic::PanicInfo;

    extern crate libc;

    #[lang = "owned_box"]
    pub struct Box<T>(*mut T);

    #[lang = "exchange_malloc"]
    unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
        let p = libc::malloc(size as libc::size_t) as *mut u8;

        // Check if `malloc` failed:
        if p as usize == 0 {
            intrinsics::abort();
        }

        p
    }

    #[lang = "box_free"]
    unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
        libc::free(ptr as *mut libc::c_void)
    }

    #[start]
    fn main(_argc: isize, _argv: *const *const u8) -> isize {
        let _x = box 1;

        0
    }

    #[lang = "eh_personality"] extern fn rust_eh_personality() {}
    #[lang = "panic_impl"] extern fn rust_begin_panic(info: &PanicInfo) -> ! { unsafe { intrinsics::abort() } }
    #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
    #[no_mangle] pub extern fn rust_eh_register_frames () {}
    #[no_mangle] pub extern fn rust_eh_unregister_frames () {}

Note the use of `abort`: the `exchange_malloc` lang item is assumed to return a valid pointer, and so needs to do the check internally.

Other features provided by lang items include:

- overloadable operators via traits: the traits corresponding to the `==`, `<`, dereferencing (`*`) and `+` (etc.) operators are all marked with lang items; those specific four are `eq`, `ord`, `deref`, and `add` respectively.
- stack unwinding and general failure; the `eh_personality`, `eh_unwind_resume`, `fail` and `fail_bounds_checks` lang items.
- the traits in `std::marker` used to indicate types of various kinds; lang items `send`, `sync` and `copy`.
- the marker types and variance indicators found in `std::marker`; lang items `covariant_type`, `contravariant_lifetime`, etc.

Lang items are loaded lazily by the compiler; e.g. if one never uses `Box` then there is no need to define functions for `exchange_malloc` and `box_free`. `rustc` will emit an error when an item is needed but not found in the current crate or any that it depends on.

Most lang items are defined by `libcore`, but if you're trying to build an executable without the standard library, you'll run into the need for lang items. The rest of this page focuses on this use-case, even though lang items are a bit broader than that.

### Using libc

In order to build a `#[no_std]` executable we will need libc as a dependency. We can specify this using our `Cargo.toml` file:

    [dependencies]
    libc = { version = "0.2.14", default-features = false }

Note that the default features have been disabled. This is a critical step - the default features of libc include the standard library and so must be disabled.

### Writing an executable without stdlib

Controlling the entry point is possible in two ways: the `#[start]` attribute, or overriding the default shim for the C `main` function with your own.

The function marked `#[start]` is passed the command line parameters in the same format as C:

    #![feature(lang_items, core_intrinsics)]
    #![feature(start)]
    #![no_std]
    use core::intrinsics;
    use core::panic::PanicInfo;

    // Pull in the system libc library for what crt0.o likely requires.
    extern crate libc;

    // Entry point for this program.
    #[start]
    fn start(_argc: isize, _argv: *const *const u8) -> isize {
        0
    }

    // These functions are used by the compiler, but not
    // for a bare-bones hello world. These are normally
    // provided by libstd.
    #[lang = "eh_personality"]
    #[no_mangle]
    pub extern fn rust_eh_personality() {
    }

    // This function may be needed based on the compilation target.
    #[lang = "eh_unwind_resume"]
    #[no_mangle]
    pub extern fn rust_eh_unwind_resume() {
    }

    #[lang = "panic_impl"]
    #[no_mangle]
    pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
        unsafe { intrinsics::abort() }
    }

To override the compiler-inserted `main` shim, one has to disable it with `#![no_main]` and then create the appropriate symbol with the correct ABI and the correct name, which requires overriding the compiler's name mangling too:

    #![feature(lang_items, core_intrinsics)]
    #![feature(start)]
    #![no_std]
    #![no_main]
    use core::intrinsics;
    use core::panic::PanicInfo;

    // Pull in the system libc library for what crt0.o likely requires.
    extern crate libc;

    // Entry point for this program.
    #[no_mangle] // ensure that this symbol is called `main` in the output
    pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
        0
    }

    // These functions are used by the compiler, but not
    // for a bare-bones hello world. These are normally
    // provided by libstd.
    #[lang = "eh_personality"]
    #[no_mangle]
    pub extern fn rust_eh_personality() {
    }

    // This function may be needed based on the compilation target.
    #[lang = "eh_unwind_resume"]
    #[no_mangle]
    pub extern fn rust_eh_unwind_resume() {
    }

    #[lang = "panic_impl"]
    #[no_mangle]
    pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
        unsafe { intrinsics::abort() }
    }

In many cases, you may need to manually link to the `compiler_builtins` crate when building a `no_std` binary. You may observe this via linker error messages such as "`undefined reference to `__rust_probestack'`". Using this crate also requires enabling the library feature `compiler_builtins_lib`. You can read more about this here.

## More about the language items

The compiler currently makes a few assumptions about symbols which are available in the executable to call. Normally these functions are provided by the standard library, but without it you must define your own. These symbols are called "language items", and they each have an internal name, and then a signature that an implementation must conform to.

The first of these functions, `rust_eh_personality`, is used by the failure mechanisms of the compiler. This is often mapped to GCC's personality function (see the libstd implementation for more information), but crates which do not trigger a panic can be assured that this function is never called. The language item's name is `eh_personality`.

The second function, `rust_begin_panic`, is also used by the failure mechanisms of the compiler. When a panic happens, this controls the message that's displayed on the screen. While the language item's name is `panic_impl`, the symbol name is `rust_begin_panic`.

A third function, `rust_eh_unwind_resume`, is also needed if the `custom_unwind_resume` flag is set in the options of the compilation target. It allows customizing the process of resuming unwind at the end of the landing pads. The language item's name is `eh_unwind_resume`.

## List of all language items

This is a list of all language items in Rust along with where they are located in the source code.

- Primitives
  - `i8`: `libcore/num/mod.rs`
  - `i16`: `libcore/num/mod.rs`
  - `i32`: `libcore/num/mod.rs`
  - `i64`: `libcore/num/mod.rs`
  - `i128`: `libcore/num/mod.rs`
  - `isize`: `libcore/num/mod.rs`
  - `u8`: `libcore/num/mod.rs`
  - `u16`: `libcore/num/mod.rs`
  - `u32`: `libcore/num/mod.rs`
  - `u64`: `libcore/num/mod.rs`
  - `u128`: `libcore/num/mod.rs`
  - `usize`: `libcore/num/mod.rs`
  - `f32`: `libstd/f32.rs`
  - `f64`: `libstd/f64.rs`
  - `char`: `libcore/char.rs`
  - `slice`: `liballoc/slice.rs`
  - `str`: `liballoc/str.rs`
  - `const_ptr`: `libcore/ptr.rs`
  - `mut_ptr`: `libcore/ptr.rs`
  - `unsafe_cell`: `libcore/cell.rs`
- Runtime
  - `start`: `libstd/rt.rs`
  - `eh_personality`: `libpanic_unwind/emcc.rs` (EMCC)
  - `eh_personality`: `libpanic_unwind/seh64_gnu.rs` (SEH64 GNU)
  - `eh_personality`: `libpanic_unwind/seh.rs` (SEH)
  - `eh_unwind_resume`: `libpanic_unwind/seh64_gnu.rs` (SEH64 GNU)
  - `eh_unwind_resume`: `libpanic_unwind/gcc.rs` (GCC)
  - `msvc_try_filter`: `libpanic_unwind/seh.rs` (SEH)
  - `panic`: `libcore/panicking.rs`
  - `panic_bounds_check`: `libcore/panicking.rs`
  - `panic_impl`: `libcore/panicking.rs`
  - `panic_impl`: `libstd/panicking.rs`
- Allocations
  - `owned_box`: `liballoc/boxed.rs`
  - `exchange_malloc`: `liballoc/heap.rs`
  - `box_free`: `liballoc/heap.rs`
- Operands
  - `not`: `libcore/ops/bit.rs`
  - `bitand`: `libcore/ops/bit.rs`
  - `bitor`: `libcore/ops/bit.rs`
  - `bitxor`: `libcore/ops/bit.rs`
  - `shl`: `libcore/ops/bit.rs`
  - `shr`: `libcore/ops/bit.rs`
  - `bitand_assign`: `libcore/ops/bit.rs`
  - `bitor_assign`: `libcore/ops/bit.rs`
  - `bitxor_assign`: `libcore/ops/bit.rs`
  - `shl_assign`: `libcore/ops/bit.rs`
  - `shr_assign`: `libcore/ops/bit.rs`
  - `deref`: `libcore/ops/deref.rs`
  - `deref_mut`: `libcore/ops/deref.rs`
  - `index`: `libcore/ops/index.rs`
  - `index_mut`: `libcore/ops/index.rs`
  - `add`: `libcore/ops/arith.rs`
  - `sub`: `libcore/ops/arith.rs`
  - `mul`: `libcore/ops/arith.rs`
  - `div`: `libcore/ops/arith.rs`
  - `rem`: `libcore/ops/arith.rs`
  - `neg`: `libcore/ops/arith.rs`
  - `add_assign`: `libcore/ops/arith.rs`
  - `sub_assign`: `libcore/ops/arith.rs`
  - `mul_assign`: `libcore/ops/arith.rs`
  - `div_assign`: `libcore/ops/arith.rs`
  - `rem_assign`: `libcore/ops/arith.rs`
  - `eq`: `libcore/cmp.rs`
  - `ord`: `libcore/cmp.rs`
- Functions
  - `fn`: `libcore/ops/function.rs`
  - `fn_mut`: `libcore/ops/function.rs`
  - `fn_once`: `libcore/ops/function.rs`
  - `generator_state`: `libcore/ops/generator.rs`
  - `generator`: `libcore/ops/generator.rs`
- Other
  - `coerce_unsized`: `libcore/ops/unsize.rs`
  - `drop`: `libcore/ops/drop.rs`
  - `drop_in_place`: `libcore/ptr.rs`
  - `clone`: `libcore/clone.rs`
  - `copy`: `libcore/marker.rs`
  - `send`: `libcore/marker.rs`
  - `sized`: `libcore/marker.rs`
  - `unsize`: `libcore/marker.rs`
  - `sync`: `libcore/marker.rs`
  - `phantom_data`: `libcore/marker.rs`
  - `freeze`: `libcore/marker.rs`
  - `debug_trait`: `libcore/fmt/mod.rs`
  - `non_zero`: `libcore/nonzero.rs`
  - `arc`: `liballoc/sync.rs`
  - `rc`: `liballoc/rc.rs`

# `link_args`

The tracking issue for this feature is: #29596

You can tell `rustc` how to customize linking, and that is via the `link_args` attribute. This attribute is applied to `extern` blocks and specifies raw flags which need to get passed to the linker when producing an artifact. An example usage would be:

    #![feature(link_args)]

    #[link_args = "-foo -bar -baz"]
    extern {}
    # fn main() {}

Note that this feature is currently hidden behind the `feature(link_args)` gate because this is not a sanctioned way of performing linking. Right now `rustc` shells out to the system linker (`gcc` on most systems, `link.exe` on MSVC), so it makes sense to provide extra command line arguments, but this will not always be the case. In the future `rustc` may use LLVM directly to link native libraries, in which case `link_args` will have no meaning. You can achieve the same effect as the `link_args` attribute with the `-C link-args` argument to `rustc`.

It is highly recommended to not use this attribute, and rather use the more formal `#[link(...)]` attribute on `extern` blocks instead.

# `link_cfg`

The tracking issue for this feature is: #37406

# `link_llvm_intrinsics`

The tracking issue for this feature is: #29602

# `linkage`

The tracking issue for this feature is: #29603

# `lint_reasons`

The tracking issue for this feature is: #54503

# `log_syntax`

The tracking issue for this feature is: #29598

# `macros_in_extern`

The tracking issue for this feature is: #49476

# `main`

The tracking issue for this feature is: #29634

# `marker_trait_attr`

The tracking issue for this feature is: #29864

Normally, Rust keeps you from adding trait implementations that could overlap with each other, as it would be ambiguous which to use. This feature, however, carves out an exception to that rule: a trait can opt-in to having overlapping implementations, at the cost that those implementations are not allowed to override anything (and thus the trait itself cannot have any associated items, as they're pointless when they'd need to do the same thing for every type anyway).

    # #![allow(unused_variables)]
    #![feature(marker_trait_attr)]

    #fn main() {
    #[marker] trait CheapToClone: Clone {}

    impl<T: Copy> CheapToClone for T {}

    // These could potentally overlap with the blanket implementation above,
    // so are only allowed because CheapToClone is a marker trait.
    impl<T: CheapToClone, U: CheapToClone> CheapToClone for (T, U) {}
    impl<T: CheapToClone> CheapToClone for std::ops::Range<T> {}

    fn cheap_clone<T: CheapToClone>(t: T) -> T {
        t.clone()
    }
    #}

This is expected to replace the unstable `overlapping_marker_traits` feature, which applied to all empty traits (without needing an opt-in).

# `mips_target_feature`

The tracking issue for this feature is: #44839

# `mmx_target_feature`

The tracking issue for this feature is: #44839

# `naked_functions`

The tracking issue for this feature is: #32408

# `needs_allocator`

The tracking issue for this feature is: #27389

# `needs_panic_runtime`

The tracking issue for this feature is: #32837

# `never_type`

The tracking issue for this feature is: #35121

# `nll`

The tracking issue for this feature is: #43234

# `no_core`

The tracking issue for this feature is: #29639

# `no_debug`

The tracking issue for this feature is: #29721

# `non_ascii_idents`

The tracking issue for this feature is: #55467

The `non_ascii_idents` feature adds support for non-ASCII identifiers.

## Examples

    # #![allow(unused_variables)]
    #![feature(non_ascii_idents)]

    #fn main() {
    const ε: f64 = 0.00001f64;
    const Π: f64 = 3.14f64;
    #}

## Changes to the language reference

> Lexer:
> IDENTIFIER :
> XID_start XID_continue*
> | `_` XID_continue+

An identifier is any nonempty Unicode string of the following form:

Either

- The first character has property `XID_start`
- The remaining characters have property `XID_continue`

Or

- The first character is `_`
- The identifier is more than one character, `_` alone is not an identifier
- The remaining characters have property `XID_continue`

that does not occur in the set of strict keywords.

> Note: `XID_start` and `XID_continue` as character properties cover the character ranges used to form the more familiar C and Java language-family identifiers.

# `non_exhaustive`

The tracking issue for this feature is: #44109

The `non_exhaustive` gate allows you to use the `#[non_exhaustive]` attribute on structs and enums. When applied within a crate, users of the crate will need to use the `_` pattern when matching enums and use the `..` pattern when matching structs. Structs marked as `non_exhaustive` will not be able to be created normally outside of the defining crate. This is demonstrated below:

    use std::error::Error as StdError;

    #[non_exhaustive]
    pub enum Error {
        Message(String),
        Other,
    }
    impl StdError for Error {
        fn description(&self) -> &str {
            // This will not error, despite being marked as non_exhaustive, as this
            // enum is defined within the current crate, it can be matched
            // exhaustively.
            match *self {
                Message(ref s) => s,
                Other => "other or unknown error",
            }
        }
    }

    use mycrate::Error;

    // This will not error as the non_exhaustive Error enum has been matched with
    // a wildcard.
    match error {
        Message(ref s) => ...,
        Other => ...,
        _ => ...,
    }

    #[non_exhaustive]
    pub struct Config {
        pub window_width: u16,
        pub window_height: u16,
    }

    // We can create structs as normal within the defining crate when marked as
    // non_exhaustive.
    let config = Config { window_width: 640, window_height: 480 };

    // We can match structs exhaustively when within the defining crate.
    if let Ok(Config { window_width, window_height }) = load_config() {
        // ...
    }

    use mycrate::Config;

    // We cannot create a struct like normal if it has been marked as
    // non_exhaustive.
    let config = Config { window_width: 640, window_height: 480 };
    // By adding the `..` we can match the config as below outside of the crate
    // when marked non_exhaustive.
    let &Config { window_width, window_height, .. } = config;

# `omit_gdb_pretty_printer_section`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `on_unimplemented`

The tracking issue for this feature is: #29628

The `on_unimplemented` feature provides the `#[rustc_on_unimplemented]` attribute, which allows trait definitions to add specialized notes to error messages when an implementation was expected but not found. You can refer to the trait's generic arguments by name and to the resolved type using `Self`.

For example:

    #![feature(on_unimplemented)]

    #[rustc_on_unimplemented="an iterator over elements of type `{A}` \
        cannot be built from a collection of type `{Self}`"]
    trait MyIterator<A> {
        fn next(&mut self) -> A;
    }

    fn iterate_chars<I: MyIterator<char>>(i: I) {
        // ...
    }

    fn main() {
        iterate_chars(&[1, 2, 3][..]);
    }

When the user compiles this, they will see the following;

    error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
      --> <anon>:14:5
       |
    14 |     iterate_chars(&[1, 2, 3][..]);
       |     ^^^^^^^^^^^^^ an iterator over elements of type `char` cannot be built from a collection of type `&[{integer}]`
       |
       = help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
       = note: required by `iterate_chars`

`on_unimplemented` also supports advanced filtering for better targeting of messages, as well as modifying specific parts of the error message. You target the text of:

- the main error message (`message`)
- the label (`label`)
- an extra note (`note`)

For example, the following attribute

    # #![allow(unused_variables)]
    #fn main() {
    #[rustc_on_unimplemented(
        message="message",
        label="label",
        note="note"
    )]
    trait MyIterator<A> {
        fn next(&mut self) -> A;
    }
    #}

Would generate the following output:

    error[E0277]: message
      --> <anon>:14:5
       |
    14 |     iterate_chars(&[1, 2, 3][..]);
       |     ^^^^^^^^^^^^^ label
       |
       = note: note
       = help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
       = note: required by `iterate_chars`

To allow more targeted error messages, it is possible to filter the application of these fields based on a variety of attributes when using `on`:

- `crate_local`: whether the code causing the trait bound to not be fulfilled is part of the user's crate. This is used to avoid suggesting code changes that would require modifying a dependency.
- Any of the generic arguments that can be substituted in the text can be referred by name as well for filtering, like `Rhs="i32"`, except for `Self`.
- `_Self`: to filter only on a particular calculated trait resolution, like `Self="std::iter::Iterator<char>"`. This is needed because `Self` is a keyword which cannot appear in attributes.
- `direct`: user-specified rather than derived obligation.
- `from_method`: usable both as boolean (whether the flag is present, like `crate_local`) or matching against a particular method. Currently used for `try`.
- `from_desugaring`: usable both as boolean (whether the flag is present) or matching against a particular desugaring.

For example, the `Iterator` trait can be annotated in the following way:

    # #![allow(unused_variables)]
    #fn main() {
    #[rustc_on_unimplemented(
        on(
            _Self="&str",
            note="call `.chars()` or `.as_bytes()` on `{Self}"
        ),
        message="`{Self}` is not an iterator",
        label="`{Self}` is not an iterator",
        note="maybe try calling `.iter()` or a similar method"
    )]
    pub trait Iterator {}
    #}

Which would produce the following outputs:

    error[E0277]: `Foo` is not an iterator
     --> src/main.rs:4:16
      |
    4 |     for foo in Foo {}
      |                ^^^ `Foo` is not an iterator
      |
      = note: maybe try calling `.iter()` or a similar method
      = help: the trait `std::iter::Iterator` is not implemented for `Foo`
      = note: required by `std::iter::IntoIterator::into_iter`

    error[E0277]: `&str` is not an iterator
     --> src/main.rs:5:16
      |
    5 |     for foo in "" {}
      |                ^^ `&str` is not an iterator
      |
      = note: call `.chars()` or `.bytes() on `&str`
      = help: the trait `std::iter::Iterator` is not implemented for `&str`
      = note: required by `std::iter::IntoIterator::into_iter`

# `optin_builtin_traits`

The tracking issue for this feature is #13231

The `optin_builtin_traits` feature gate allows you to define auto traits.

Auto traits, like `Send` or `Sync` in the standard library, are marker traits that are automatically implemented for every type, unless the type, or a type it contains, has explicitly opted out via a negative impl.

    impl !Type for Trait

Example:

    #![feature(optin_builtin_traits)]

    auto trait Valid {}

    struct True;
    struct False;

    impl !Valid for False {}

    struct MaybeValid<T>(T);

    fn must_be_valid<T: Valid>(_t: T) { }

    fn main() {
        // works
        must_be_valid( MaybeValid(True) );

        // compiler error - trait bound not satisfied
        // must_be_valid( MaybeValid(False) );
    }

# `overlapping_marker_traits`

The tracking issue for this feature is: #29864

# `panic_runtime`

The tracking issue for this feature is: #32837

# `platform_intrinsics`

The tracking issue for this feature is: #27731

# `plugin`

The tracking issue for this feature is: #29597

This feature is part of "compiler plugins." It will often be used with the `plugin_registrar` and `rustc_private` features.

`rustc` can load compiler plugins, which are user-provided libraries that extend the compiler's behavior with new syntax extensions, lint checks, etc.

A plugin is a dynamic library crate with a designated registrar function that registers extensions with `rustc`. Other crates can load these extensions using the crate attribute `#![plugin(...)]`. See the `rustc_plugin` documentation for more about the mechanics of defining and loading a plugin.

If present, arguments passed as `#![plugin(foo(... args ...))]` are not interpreted by rustc itself. They are provided to the plugin through the `Registry`'s `args` method.

In the vast majority of cases, a plugin should only be used through `#![plugin]` and not through an `extern crate` item. Linking a plugin would pull in all of libsyntax and librustc as dependencies of your crate. This is generally unwanted unless you are building another plugin. The `plugin_as_library` lint checks these guidelines.

The usual practice is to put compiler plugins in their own crate, separate from any `macro_rules!` macros or ordinary Rust code meant to be used by consumers of a library.

# Syntax extensions

Plugins can extend Rust's syntax in various ways. One kind of syntax extension is the procedural macro. These are invoked the same way as ordinary macros, but the expansion is performed by arbitrary Rust code that manipulates syntax trees at compile time.

Let's write a plugin `roman_numerals.rs` that implements Roman numeral integer literals.

    #![crate_type="dylib"]
    #![feature(plugin_registrar, rustc_private)]

    extern crate syntax;
    extern crate rustc;
    extern crate rustc_plugin;

    use syntax::parse::token;
    use syntax::tokenstream::TokenTree;
    use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
    use syntax::ext::build::AstBuilder;  // A trait for expr_usize.
    use syntax::ext::quote::rt::Span;
    use rustc_plugin::Registry;

    fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
            -> Box<MacResult + 'static> {

        static NUMERALS: &'static [(&'static str, usize)] = &[
            ("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
            ("C",  100), ("XC",  90), ("L",  50), ("XL",  40),
            ("X",   10), ("IX",   9), ("V",   5), ("IV",   4),
            ("I",    1)];

        if args.len() != 1 {
            cx.span_err(
                sp,
                &format!("argument should be a single identifier, but got {} arguments", args.len()));
            return DummyResult::any(sp);
        }

        let text = match args[0] {
            TokenTree::Token(_, token::Ident(s)) => s.to_string(),
            _ => {
                cx.span_err(sp, "argument should be a single identifier");
                return DummyResult::any(sp);
            }
        };

        let mut text = &*text;
        let mut total = 0;
        while !text.is_empty() {
            match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
                Some(&(rn, val)) => {
                    total += val;
                    text = &text[rn.len()..];
                }
                None => {
                    cx.span_err(sp, "invalid Roman numeral");
                    return DummyResult::any(sp);
                }
            }
        }

        MacEager::expr(cx.expr_usize(sp, total))
    }

    #[plugin_registrar]
    pub fn plugin_registrar(reg: &mut Registry) {
        reg.register_macro("rn", expand_rn);
    }

Then we can use `rn!()` like any other macro:

    #![feature(plugin)]
    #![plugin(roman_numerals)]

    fn main() {
        assert_eq!(rn!(MMXV), 2015);
    }

The advantages over a simple `fn(&str) -> u32` are:

- The (arbitrarily complex) conversion is done at compile time.
- Input validation is also performed at compile time.
- It can be extended to allow use in patterns, which effectively gives a way to define new literal syntax for any data type.

In addition to procedural macros, you can define new `derive`-like attributes and other kinds of extensions. See `Registry::register_syntax_extension` and the `SyntaxExtension` enum. For a more involved macro example, see `regex_macros`.

## Tips and tricks

You can use `syntax::parse` to turn token trees into higher-level syntax elements like expressions:

    fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
            -> Box<MacResult+'static> {

        let mut parser = cx.new_parser_from_tts(args);

        let expr: P<Expr> = parser.parse_expr();

Looking through `libsyntax` parser code will give you a feel for how the parsing infrastructure works.

Keep the `Span`s of everything you parse, for better error reporting. You can wrap `Spanned` around your custom data structures.

Calling `ExtCtxt::span_fatal` will immediately abort compilation. It's better to instead call `ExtCtxt::span_err` and return `DummyResult` so that the compiler can continue and find further errors.

To print syntax fragments for debugging, you can use `span_note` together with `syntax::print::pprust::*_to_string`.

The example above produced an integer literal using `AstBuilder::expr_usize`. As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of quasiquote macros. They are undocumented and very rough around the edges. However, the implementation may be a good starting point for an improved quasiquote as an ordinary plugin library.

# Lint plugins

Plugins can extend Rust's lint infrastructure with additional checks for code style, safety, etc. Now let's write a plugin `lint_plugin_test.rs` that warns about any item named `lintme`.

    #![feature(plugin_registrar)]
    #![feature(box_syntax, rustc_private)]

    extern crate syntax;

    // Load rustc as a plugin to get macros
    #[macro_use]
    extern crate rustc;
    extern crate rustc_plugin;

    use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
                      EarlyLintPassObject, LintArray};
    use rustc_plugin::Registry;
    use syntax::ast;

    declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");

    struct Pass;

    impl LintPass for Pass {
        fn get_lints(&self) -> LintArray {
            lint_array!(TEST_LINT)
        }
    }

    impl EarlyLintPass for Pass {
        fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
            if it.ident.as_str() == "lintme" {
                cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
            }
        }
    }

    #[plugin_registrar]
    pub fn plugin_registrar(reg: &mut Registry) {
        reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
    }

Then code like

    #![plugin(lint_plugin_test)]

    fn lintme() { }

will produce a compiler warning:

    foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
    foo.rs:4 fn lintme() { }
             ^~~~~~~~~~~~~~~

The components of a lint plugin are:

- one or more `declare_lint!` invocations, which define static `Lint` structs;

- a struct holding any state needed by the lint pass (here, none);

- a `LintPass` implementation defining how to check each syntax element. A single `LintPass` may call `span_lint` for several different `Lint`s, but should register them all through the `get_lints` method.

Lint passes are syntax traversals, but they run at a late stage of compilation where type information is available. `rustc`'s built-in lints mostly use the same infrastructure as lint plugins, and provide examples of how to access type information.

Lints defined by plugins are controlled by the usual attributes and compiler flags, e.g. `#[allow(test_lint)]` or `-A test-lint`. These identifiers are derived from the first argument to `declare_lint!`, with appropriate case and punctuation conversion.

You can run `rustc -W help foo.rs` to see a list of lints known to `rustc`, including those provided by plugins loaded by `foo.rs`.

# `plugin_registrar`

The tracking issue for this feature is: #29597

This feature is part of "compiler plugins." It will often be used with the `plugin` and `rustc_private` features as well. For more details, see their docs.

# `powerpc_target_feature`

The tracking issue for this feature is: #44839

# `precise_pointer_size_matching`

The tracking issue for this feature is: #56354

# `prelude_import`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `proc_macro_hygiene`

The tracking issue for this feature is: #54727

# `profiler_runtime`

The tracking issue for this feature is: #42524.

# `quote`

The tracking issue for this feature is: #29601

# `re_rebalance_coherence`

The tracking issue for this feature is: #55437

The `re_rebalance_coherence` feature tweaks the rules regarding which trait impls are allowed in crates. The following rule is used:

Given `impl<P1..=Pn> Trait<T1..=Tn> for T0`, an impl is valid only if at least one of the following is true:

- `Trait` is a local trait
- All of
  - At least one of the types `T0..=Tn` must be a local type. Let `Ti` be the first such type.
  - No uncovered type parameters `P1..=Pn` may appear in `T0..Ti` (excluding `Ti`)

See the RFC for details.

# `repr_simd`

The tracking issue for this feature is: #27731

# `repr128`

The tracking issue for this feature is: #35118

The `repr128` feature adds support for `#[repr(u128)]` on `enum`s.

    # #![allow(unused_variables)]
    #![feature(repr128)]

    #fn main() {
    #[repr(u128)]
    enum Foo {
        Bar(u64),
    }
    #}

# `rustc_attrs`

The tracking issue for this feature is: #29642

# `rustc_const_unstable`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `rustc_diagnostic_macros`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `sanitizer_runtime`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `simd_ffi`

The tracking issue for this feature is: #27731

# `slice_patterns`

The tracking issue for this feature is: #23121

The `slice_patterns` feature gate lets you use `..` to indicate any number of elements inside a pattern matching a slice. This wildcard can only be used once for a given array. If there's an pattern before the `..`, the subslice will be matched against that pattern. For example:

    #![feature(slice_patterns)]

    fn is_symmetric(list: &[u32]) -> bool {
        match list {
            &[] | &[_] => true,
            &[x, ref inside.., y] if x == y => is_symmetric(inside),
            &[..] => false,
        }
    }

    fn main() {
        let sym = &[0, 1, 4, 2, 4, 1, 0];
        assert!(is_symmetric(sym));

        let not_sym = &[0, 1, 7, 2, 4, 1, 0];
        assert!(!is_symmetric(not_sym));
    }

# `specialization`

The tracking issue for this feature is: #31844

# `sse4a_target_feature`

The tracking issue for this feature is: #44839

# `staged_api`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `start`

The tracking issue for this feature is: #29633

# `static_nobundle`

The tracking issue for this feature is: #37403

# `stmt_expr_attributes`

The tracking issue for this feature is: #15701

# `structural_match`

The tracking issue for this feature is: #31434

# `tbm_target_feature`

The tracking issue for this feature is: #44839

# `test_2018_feature`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `thread_local`

The tracking issue for this feature is: #29594

# `trace_macros`

The tracking issue for this feature is #29598.

With `trace_macros` you can trace the expansion of macros in your code.

## Examples

    #![feature(trace_macros)]

    fn main() {
        trace_macros!(true);
        println!("Hello, Rust!");
        trace_macros!(false);
    }

The `cargo build` output:

    note: trace_macro
     --> src/main.rs:5:5
      |
    5 |     println!("Hello, Rust!");
      |     ^^^^^^^^^^^^^^^^^^^^^^^^^
      |
      = note: expanding `println! { "Hello, Rust!" }`
      = note: to `print ! ( concat ! ( "Hello, Rust!" , "\n" ) )`
      = note: expanding `print! { concat ! ( "Hello, Rust!" , "\n" ) }`
      = note: to `$crate :: io :: _print ( format_args ! ( concat ! ( "Hello, Rust!" , "\n" ) )
              )`

        Finished dev [unoptimized + debuginfo] target(s) in 0.60 secs

# `trait_alias`

The tracking issue for this feature is: [#41517]

The `trait_alias` feature adds support for trait aliases. These allow aliases to be created for one or more traits (currently just a single regular trait plus any number of auto-traits), and used wherever traits would normally be used as either bounds or trait objects.

    #![feature(trait_alias)]

    trait Foo = std::fmt::Debug + Send;
    trait Bar = Foo + Sync;

    // Use trait alias as bound on type parameter.
    fn foo<T: Foo>(v: &T) {
        println!("{:?}", v);
    }

    pub fn main() {
        foo(&1);

        // Use trait alias for trait objects.
        let a: &Bar = &123;
        println!("{:?}", a);
        let b = Box::new(456) as Box<dyn Foo>;
        println!("{:?}", b);
    }

# `trivial_bounds`

The tracking issue for this feature is: #48214

# `try_blocks`

The tracking issue for this feature is: #31436

The `try_blocks` feature adds support for `try` blocks. A `try` block creates a new scope one can use the `?` operator in.

    # #![allow(unused_variables)]
    #![feature(try_blocks)]

    #fn main() {
    use std::num::ParseIntError;

    let result: Result<i32, ParseIntError> = try {
        "1".parse::<i32>()?
            + "2".parse::<i32>()?
            + "3".parse::<i32>()?
    };
    assert_eq!(result, Ok(6));

    let result: Result<i32, ParseIntError> = try {
        "1".parse::<i32>()?
            + "foo".parse::<i32>()?
            + "3".parse::<i32>()?
    };
    assert!(result.is_err());
    #}

# `type_alias_enum_variants`

The tracking issue for this feature is: #49683

The `type_alias_enum_variants` feature enables the use of variants on type aliases that refer to enums, as both a constructor and a pattern. That is, it allows for the syntax `EnumAlias::Variant`, which behaves exactly the same as `Enum::Variant` (assuming that `EnumAlias` is an alias for some enum type `Enum`).

Note that since `Self` exists as a type alias, this feature also enables the use of the syntax `Self::Variant` within an impl block for an enum type.

    #![feature(type_alias_enum_variants)]

    enum Foo {
        Bar(i32),
        Baz { i: i32 },
    }

    type Alias = Foo;

    fn main() {
        let t = Alias::Bar(0);
        let t = Alias::Baz { i: 0 };
        match t {
            Alias::Bar(_i) => {}
            Alias::Baz { i: _i } => {}
        }
    }

# `type_ascription`

The tracking issue for this feature is: #23416

# `unboxed_closures`

The tracking issue for this feature is #29625

See Also: `fn_traits`

The `unboxed_closures` feature allows you to write functions using the `"rust-call"` ABI, required for implementing the `Fn*` family of traits. `"rust-call"` functions must have exactly one (non self) argument, a tuple representing the argument list.

    #![feature(unboxed_closures)]

    extern "rust-call" fn add_args(args: (u32, u32)) -> u32 {
        args.0 + args.1
    }

    fn main() {}

# `underscore_const_names`

The tracking issue for this feature is: #54912

# `unrestricted_attribute_tokens`

The tracking issue for this feature is: #55208

# `unsized_locals`

The tracking issue for this feature is: #48055

This implements RFC1909. When turned on, you can have unsized arguments and locals:

    #![feature(unsized_locals)]

    use std::any::Any;

    fn main() {
        let x: Box<dyn Any> = Box::new(42);
        let x: dyn Any = *x;
        //  ^ unsized local variable
        //               ^^ unsized temporary
        foo(x);
    }

    fn foo(_: dyn Any) {}
    //     ^^^^^^ unsized argument

The RFC still forbids the following unsized expressions:

    #![feature(unsized_locals)]

    use std::any::Any;

    struct MyStruct<T: ?Sized> {
        content: T,
    }

    struct MyTupleStruct<T: ?Sized>(T);

    fn answer() -> Box<dyn Any> {
        Box::new(42)
    }

    fn main() {
        // You CANNOT have unsized statics.
        static X: dyn Any = *answer();  // ERROR
        const Y: dyn Any = *answer();  // ERROR

        // You CANNOT have struct initialized unsized.
        MyStruct { content: *answer() };  // ERROR
        MyTupleStruct(*answer());  // ERROR
        (42, *answer());  // ERROR

        // You CANNOT have unsized return types.
        fn my_function() -> dyn Any { *answer() }  // ERROR

        // You CAN have unsized local variables...
        let mut x: dyn Any = *answer();  // OK
        // ...but you CANNOT reassign to them.
        x = *answer();  // ERROR

        // You CANNOT even initialize them separately.
        let y: dyn Any;  // OK
        y = *answer();  // ERROR

        // Not mentioned in the RFC, but by-move captured variables are also Sized.
        let x: dyn Any = *answer();
        (move || {  // ERROR
            let y = x;
        })();

        // You CAN create a closure with unsized arguments,
        // but you CANNOT call it.
        // This is an implementation detail and may be changed in the future.
        let f = |x: dyn Any| {};
        f(*answer());  // ERROR
    }

## By-value trait objects

With this feature, you can have by-value `self` arguments without `Self: Sized` bounds.

    #![feature(unsized_locals)]

    trait Foo {
        fn foo(self) {}
    }

    impl<T: ?Sized> Foo for T {}

    fn main() {
        let slice: Box<[i32]> = Box::new([1, 2, 3]);
        <[i32] as Foo>::foo(*slice);
    }

And `Foo` will also be object-safe.

    #![feature(unsized_locals)]

    trait Foo {
        fn foo(self) {}
    }

    impl<T: ?Sized> Foo for T {}

    fn main () {
        let slice: Box<dyn Foo> = Box::new([1, 2, 3]);
        // doesn't compile yet
        <dyn Foo as Foo>::foo(*slice);
    }

One of the objectives of this feature is to allow `Box<dyn FnOnce>`, instead of `Box<dyn FnBox>` in the future. See #28796 for details.

## Variable length arrays

The RFC also describes an extension to the array literal syntax: `[e; dyn n]`. In the syntax, `n` isn't necessarily a constant expression. The array is dynamically allocated on the stack and has the type of `[T]`, instead of `[T; n]`.

    #![feature(unsized_locals)]

    fn mergesort<T: Ord>(a: &mut [T]) {
        let mut tmp = [T; dyn a.len()];
        // ...
    }

    fn main() {
        let mut a = [3, 1, 5, 6];
        mergesort(&mut a);
        assert_eq!(a, [1, 3, 5, 6]);
    }

VLAs are not implemented yet. The syntax isn't final, either. We may need an alternative syntax for Rust 2015 because, in Rust 2015, expressions like `[e; dyn(1)]` would be ambiguous. One possible alternative proposed in the RFC is `[e; n]`: if `n` captures one or more local variables, then it is considered as `[e; dyn n]`.

## Advisory on stack usage

It's advised not to casually use the `#![feature(unsized_locals)]` feature. Typical use-cases are:

- When you need a by-value trait objects.
- When you really need a fast allocation of small temporary arrays.

Another pitfall is repetitive allocation and temporaries. Currently the compiler simply extends the stack frame every time it encounters an unsized assignment. So for example, the code

    #![feature(unsized_locals)]

    fn main() {
        let x: Box<[i32]> = Box::new([1, 2, 3, 4, 5]);
        let _x = {{{{{{{{{{*x}}}}}}}}}};
    }

and the code

    #![feature(unsized_locals)]

    fn main() {
        for _ in 0..10 {
            let x: Box<[i32]> = Box::new([1, 2, 3, 4, 5]);
            let _x = *x;
        }
    }

will unnecessarily extend the stack frame.

# `unsized_tuple_coercion`

The tracking issue for this feature is: #42877

This is a part of RFC0401. According to the RFC, there should be an implementation like this:

    impl<..., T, U: ?Sized> Unsized<(..., U)> for (..., T) where T: Unsized<U> {}

This implementation is currently gated behind `#[feature(unsized_tuple_coercion)]` to avoid insta-stability. Therefore you can use it like this:

    #![feature(unsized_tuple_coercion)]

    fn main() {
        let x : ([i32; 3], [i32; 3]) = ([1, 2, 3], [4, 5, 6]);
        let y : &([i32; 3], [i32]) = &x;
        assert_eq!(y.1[0], 4);
    }

# `untagged_unions`

The tracking issue for this feature is: #32836

# `unwind_attributes`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `wasm_target_feature`

The tracking issue for this feature is: #44839

# Library Features

# `align_offset`

The tracking issue for this feature is: #44488

# `alloc`

The tracking issue for this feature is: #27783

# `alloc_error_hook`

The tracking issue for this feature is: #51245

# `alloc_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `alloc_layout_extra`

The tracking issue for this feature is: #55724

# `allocator_api`

The tracking issue for this feature is #32838

Sometimes you want the memory for one collection to use a different allocator than the memory for another collection. In this case, replacing the global allocator is not a workable option. Instead, you need to pass in an instance of an `Alloc` to each collection for which you want a custom allocator.

TBD

# `array_error_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `as_cell`

The tracking issue for this feature is: #43038

# `atomic_min_max`

The tracking issue for this feature is: #48655

# `await_macro`

The tracking issue for this feature is: #50547

# `box_into_pin`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `box_into_raw_non_null`

The tracking issue for this feature is: #47336

# `bufreader_buffer`

The tracking issue for this feature is: #45323

# `bufreader_seek_relative`

The tracking issue for this feature is: #31100

# `c_variadic`

The tracking issue for this feature is: #27745

# `c_void_variant`

This feature is internal to the Rust compiler and is not intended for general use.

# `cell_update`

The tracking issue for this feature is: #50186

# `char_error_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `coerce_unsized`

The tracking issue for this feature is: #27732

# `compiler_builtins_lib`

The tracking issue for this feature is: None.

This feature is required to link to the `compiler_builtins` crate which contains "compiler intrinsics". Compiler intrinsics are software implementations of basic operations like multiplication of `u64`s. These intrinsics are only required on platforms where these operations don't directly map to a hardware instruction.

You should never need to explicitly link to the `compiler_builtins` crate when building "std" programs as `compiler_builtins` is already in the dependency graph of `std`. But you may need it when building `no_std` binary crates. If you get a linker error like:

    $PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
    $PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'

That means that you need to link to this crate.

When you link to this crate, make sure it only appears once in your crate dependency graph. Also, it doesn't matter where in the dependency graph you place the `compiler_builtins` crate.

    #![feature(compiler_builtins_lib)]
    #![no_std]

    extern crate compiler_builtins;

# `concat_idents_macro`

The tracking issue for this feature is: #29599

# `const_cstr_unchecked`

The tracking issue for this feature is: #57563

# `const_int_conversion`

The tracking issue for this feature is: #57563

# `const_int_ops`

The tracking issue for this feature is: #57563

# `const_int_overflowing`

The tracking issue for this feature is: #57563

# `const_int_rotate`

The tracking issue for this feature is: #57563

# `const_int_wrapping`

The tracking issue for this feature is: #57563

# `const_ip`

The tracking issue for this feature is: #57563

# `const_needs_drop`

The tracking issue for this feature is: #57563

# `const_slice_len`

The tracking issue for this feature is: #57563

# `const_str_as_bytes`

The tracking issue for this feature is: #57563

# `const_str_len`

The tracking issue for this feature is: #57563

# `const_string_new`

The tracking issue for this feature is: #57563

# `const_type_id`

The tracking issue for this feature is: #57563

# `const_vec_new`

The tracking issue for this feature is: #57563

# `copied`

The tracking issue for this feature is: #57126

# `copy_within`

The tracking issue for this feature is: #54236

# `copysign`

The tracking issue for this feature is: #55169

# `core_intrinsics`

This feature is internal to the Rust compiler and is not intended for general use.

# `core_panic`

This feature is internal to the Rust compiler and is not intended for general use.

# `core_panic_info`

The tracking issue for this feature is: #44489

# `core_private_bignum`

This feature is internal to the Rust compiler and is not intended for general use.

# `core_private_diy_float`

This feature is internal to the Rust compiler and is not intended for general use.

# `deadline_api`

The tracking issue for this feature is: #46316

# `dec2flt`

This feature is internal to the Rust compiler and is not intended for general use.

# `derive_clone_copy`

This feature is internal to the Rust compiler and is not intended for general use.

# `derive_eq`

This feature is internal to the Rust compiler and is not intended for general use.

# `dispatch_from_dyn`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `drain_filter`

The tracking issue for this feature is: #43244

# `duration_constants`

The tracking issue for this feature is: #57391

# `duration_float`

The tracking issue for this feature is: #54361

# `error_type_id`

The tracking issue for this feature is: #27745

# `euclidean_division`

The tracking issue for this feature is: #49048

# `exact_size_is_empty`

The tracking issue for this feature is: #35428

# `extra_log_consts`

The tracking issue for this feature is: #50540

# `fd`

This feature is internal to the Rust compiler and is not intended for general use.

# `fd_read`

This feature is internal to the Rust compiler and is not intended for general use.

# `fixed_size_array`

The tracking issue for this feature is: #27778

# `flt2dec`

This feature is internal to the Rust compiler and is not intended for general use.

# `fmt_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `fn_traits`

The tracking issue for this feature is #29625

See Also: `unboxed_closures`

The `fn_traits` feature allows for implementation of the `Fn*` traits for creating custom closure-like types.

    #![feature(unboxed_closures)]
    #![feature(fn_traits)]

    struct Adder {
        a: u32
    }

    impl FnOnce<(u32, )> for Adder {
        type Output = u32;
        extern "rust-call" fn call_once(self, b: (u32, )) -> Self::Output {
            self.a + b.0
        }
    }

    fn main() {
        let adder = Adder { a: 3 };
        assert_eq!(adder(2), 5);
    }

# `fnbox`

The tracking issue for this feature is: #28796

# `forget_unsized`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `futures_api`

The tracking issue for this feature is: #50547

# `gen_future`

The tracking issue for this feature is: #50547

# `generator_trait`

The tracking issue for this feature is: #43122

# `get_type_id`

The tracking issue for this feature is: #27745

# `hash_raw_entry`

The tracking issue for this feature is: #56167

# `hashmap_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `inner_deref`

The tracking issue for this feature is: #50264

# `int_error_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `int_error_matching`

The tracking issue for this feature is: #22639

# `integer_atomics`

The tracking issue for this feature is: #32976

# `ip`

The tracking issue for this feature is: #27709

# `iter_copied`

The tracking issue for this feature is: #57127

# `iter_nth_back`

The tracking issue for this feature is: #56995

# `iter_once_with`

The tracking issue for this feature is: #57581

# `iter_unfold`

The tracking issue for this feature is: #55977

# `libstd_io_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `libstd_sys_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `libstd_thread_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `linked_list_extras`

The tracking issue for this feature is: #27794

# `manually_drop_take`

The tracking issue for this feature is: #55422

# `map_entry_replace`

The tracking issue for this feature is: #44286

# `map_get_key_value`

The tracking issue for this feature is: #49347

# `maybe_uninit`

The tracking issue for this feature is: #53491

# `mpsc_select`

The tracking issue for this feature is: #27800

# `n16`

This feature is internal to the Rust compiler and is not intended for general use.

# `no_more_cas`

The tracking issue for this feature is: #48655

# `no_panic_pow`

The tracking issue for this feature is: #48320

# `once_is_completed`

The tracking issue for this feature is: #54890

# `once_poison`

The tracking issue for this feature is: #33577

# `option_xor`

The tracking issue for this feature is: #50512

# `panic_abort`

The tracking issue for this feature is: #32837

# `panic_info_message`

The tracking issue for this feature is: #44489

# `panic_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `panic_unwind`

The tracking issue for this feature is: #32837

# `pattern`

The tracking issue for this feature is: #27721

# `print_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `proc_macro_def_site`

The tracking issue for this feature is: #54724

# `proc_macro_diagnostic`

The tracking issue for this feature is: #54140

# `proc_macro_internals`

The tracking issue for this feature is: #27812

# `proc_macro_quote`

The tracking issue for this feature is: #54722

# `proc_macro_raw_ident`

The tracking issue for this feature is: #54723

# `proc_macro_span`

The tracking issue for this feature is: #54725

# `process_exitcode_placeholder`

The tracking issue for this feature is: #48711

# `process_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `profiler_runtime_lib`

This feature is internal to the Rust compiler and is not intended for general use.

# `ptr_hash`

The tracking issue for this feature is: #56286

# `ptr_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `ptr_offset_from`

The tracking issue for this feature is: #41079

# `ptr_wrapping_offset_from`

The tracking issue for this feature is: #41079

# `range_contains`

The tracking issue for this feature is: #32311

# `range_is_empty`

The tracking issue for this feature is: #48111

# `raw`

The tracking issue for this feature is: #27751

# `raw_vec_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `read_initializer`

The tracking issue for this feature is: [#42788]

# `receiver_trait`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `refcell_map_split`

The tracking issue for this feature is: #51476

# `refcell_replace_swap`

The tracking issue for this feature is: #43570

# `repeat_generic_slice`

The tracking issue for this feature is: #48784

# `result_map_or_else`

The tracking issue for this feature is: #53268

# `reverse_bits`

The tracking issue for this feature is: #48763

# `rt`

This feature is internal to the Rust compiler and is not intended for general use.

# `rustc_private`

The tracking issue for this feature is: #27812

# `sanitizer_runtime_lib`

This feature is internal to the Rust compiler and is not intended for general use.

# `set_stdio`

This feature is internal to the Rust compiler and is not intended for general use.

# `sgx_platform`

The tracking issue for this feature is: #56975

# `shrink_to`

The tracking issue for this feature is: #56431

# `slice_concat_ext`

The tracking issue for this feature is: #27747

# `slice_index_methods`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `slice_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `slice_partition_dedup`

The tracking issue for this feature is: #54279

# `slice_sort_by_cached_key`

The tracking issue for this feature is: #34447

# `sort_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `split_ascii_whitespace`

The tracking issue for this feature is: #48656

# `std_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `stdsimd`

The tracking issue for this feature is: #48556

# `step_trait`

The tracking issue for this feature is: #42168

# `str_escape`

The tracking issue for this feature is: #27791

# `str_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `termination_trait_lib`

The tracking issue for this feature is: #43301

# `test`

The tracking issue for this feature is: None.

The internals of the `test` crate are unstable, behind the `test` flag. The most widely used part of the `test` crate are benchmark tests, which can test the performance of your code. Let's make our `src/lib.rs` look like this (comments elided):

    #![feature(test)]

    extern crate test;

    pub fn add_two(a: i32) -> i32 {
        a + 2
    }

    #[cfg(test)]
    mod tests {
        use super::*;
        use test::Bencher;

        #[test]
        fn it_works() {
            assert_eq!(4, add_two(2));
        }

        #[bench]
        fn bench_add_two(b: &mut Bencher) {
            b.iter(|| add_two(2));
        }
    }

Note the `test` feature gate, which enables this unstable feature.

We've imported the `test` crate, which contains our benchmarking support. We have a new function as well, with the `bench` attribute. Unlike regular tests, which take no arguments, benchmark tests take a `&mut Bencher`. This `Bencher` provides an `iter` method, which takes a closure. This closure contains the code we'd like to benchmark.

We can run benchmark tests with `cargo bench`:

    $ cargo bench
       Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
         Running target/release/adder-91b3e234d4ed382a

    running 2 tests
    test tests::it_works ... ignored
    test tests::bench_add_two ... bench:         1 ns/iter (+/- 0)

    test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured

Our non-benchmark test was ignored. You may have noticed that `cargo bench` takes a bit longer than `cargo test`. This is because Rust runs our benchmark a number of times, and then takes the average. Because we're doing so little work in this example, we have a `1 ns/iter (+/- 0)`, but this would show the variance if there was one.

Advice on writing benchmarks:

- Move setup code outside the `iter` loop; only put the part you want to measure inside
- Make the code do "the same thing" on each iteration; do not accumulate or change state
- Make the outer function idempotent too; the benchmark runner is likely to run it many times
- Make the inner `iter` loop short and fast so benchmark runs are fast and the calibrator can adjust the run-length at fine resolution
- Make the code in the `iter` loop do something simple, to assist in pinpointing performance improvements (or regressions)

## Gotcha: optimizations

There's another tricky part to writing benchmarks: benchmarks compiled with optimizations activated can be dramatically changed by the optimizer so that the benchmark is no longer benchmarking what one expects. For example, the compiler might recognize that some calculation has no external effects and remove it entirely.

    #![feature(test)]

    extern crate test;
    use test::Bencher;

    #[bench]
    fn bench_xor_1000_ints(b: &mut Bencher) {
        b.iter(|| {
            (0..1000).fold(0, |old, new| old ^ new);
        });
    }

gives the following results

    running 1 test
    test bench_xor_1000_ints ... bench:         0 ns/iter (+/- 0)

    test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured

The benchmarking runner offers two ways to avoid this. Either, the closure that the `iter` method receives can return an arbitrary value which forces the optimizer to consider the result used and ensures it cannot remove the computation entirely. This could be done for the example above by adjusting the `b.iter` call to

    # #![allow(unused_variables)]
    #fn main() {
    # struct X;
    # impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
    b.iter(|| {
        // Note lack of `;` (could also use an explicit `return`).
        (0..1000).fold(0, |old, new| old ^ new)
    });
    #}

Or, the other option is to call the generic `test::black_box` function, which is an opaque "black box" to the optimizer and so forces it to consider any argument as used.

    #![feature(test)]

    extern crate test;

    # fn main() {
    # struct X;
    # impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
    b.iter(|| {
        let n = test::black_box(1000);

        (0..n).fold(0, |a, b| a ^ b)
    })
    # }

Neither of these read or modify the value, and are very cheap for small values. Larger values can be passed indirectly to reduce overhead (e.g. `black_box(&huge_struct)`).

Performing either of the above changes gives the following benchmarking results

    running 1 test
    test bench_xor_1000_ints ... bench:       131 ns/iter (+/- 3)

    test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured

However, the optimizer can still modify a testcase in an undesirable manner even when using either of the above.

# `thread_local_internals`

This feature is internal to the Rust compiler and is not intended for general use.

# `thread_spawn_unchecked`

The tracking issue for this feature is: #55132

# `time_checked_add`

The tracking issue for this feature is: #55940

# `toowned_clone_into`

The tracking issue for this feature is: #41263

# `trusted_len`

The tracking issue for this feature is: #37572

# `try_from`

The tracking issue for this feature is: #33417

# `try_reserve`

The tracking issue for this feature is: #48043

# `try_trait`

The tracking issue for this feature is: #42327

This introduces a new trait `Try` for extending the `?` operator to types other than `Result` (a part of RFC 1859). The trait provides the canonical way to view a type in terms of a success/failure dichotomy. This will allow `?` to supplant the `try_opt!` macro on `Option` and the `try_ready!` macro on `Poll`, among other things.

Here's an example implementation of the trait:

    /// A distinct type to represent the `None` value of an `Option`.
    ///
    /// This enables using the `?` operator on `Option`; it's rarely useful alone.
    #[derive(Debug)]
    #[unstable(feature = "try_trait", issue = "42327")]
    pub struct None { _priv: () }

    #[unstable(feature = "try_trait", issue = "42327")]
    impl<T> ops::Try for Option<T>  {
        type Ok = T;
        type Error = None;

        fn into_result(self) -> Result<T, None> {
            self.ok_or(None { _priv: () })
        }

        fn from_ok(v: T) -> Self {
            Some(v)
        }

        fn from_error(_: None) -> Self {
            None
        }
    }

Note the `Error` associated type here is a new marker. The `?` operator allows interconversion between different `Try` implementers only when the error type can be converted `Into` the error type of the enclosing function (or catch block). Having a distinct error type (as opposed to just `()`, or similar) restricts this to where it's semantically meaningful.

# `unicode_internals`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `unicode_version`

The tracking issue for this feature is: #49726

# `unsize`

The tracking issue for this feature is: #27732

# `update_panic_count`

This feature is internal to the Rust compiler and is not intended for general use.

# `vec_remove_item`

The tracking issue for this feature is: #40062

# `vec_resize_default`

The tracking issue for this feature is: #41758

# `vecdeque_rotate`

The tracking issue for this feature is: #56686

# `wait_timeout_until`

The tracking issue for this feature is: #47960

# `wait_until`

The tracking issue for this feature is: #47960

# `weak_ptr_eq`

The tracking issue for this feature is: #55981

# `windows_c`

This feature is internal to the Rust compiler and is not intended for general use.

# `windows_file_type_ext`

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.

# `windows_handle`

This feature is internal to the Rust compiler and is not intended for general use.

# `windows_net`

This feature is internal to the Rust compiler and is not intended for general use.

# `windows_stdio`

This feature is internal to the Rust compiler and is not intended for general use.

# `wrapping_int_impl`

The tracking issue for this feature is: #32463

# `wrapping_next_power_of_two`

The tracking issue for this feature is: #32463